rip-lang 3.16.0 → 3.16.2

package/docs/RIP-SCHEMA.md

@@ -4,33 +4,44 @@
 
 # Rip Schema
 
-> **One keyword. A validator, a class, an ORM, a migration tool, and a TypeScript type — from a single declaration.**
+> **One keyword. A validator, a class, an ORM, migrations, and a live API contract — from a single declaration.**
 
-In a typical TypeScript application the shape of a `User` is described four
+In a typical TypeScript application the shape of a `User` is described five
 times. Once as a Zod schema for input validation. Once as a Prisma model for
 the database. Once as a generated TypeScript type for the editor. Once as a
-DTO class for API projections. Every change has to be propagated across all
-four. Every divergence becomes a bug.
+DTO class for API projections. Once more as an OpenAPI document for clients.
+Every change has to be propagated across all five. Every divergence becomes
+a bug.
 
-Rip Schema collapses all four into one declaration:
+Rip Schema collapses all of them into one declaration:
 
 ```coffee
 User = schema :model
   name!   string, 1..100
-  email!# email
+  email! email @unique
+  phone?  ~:phone
   @timestamps
   @has_many Order
   identifier:       ~> "#{@name} <#{@email}>"
   beforeValidation: -> @email = @email.toLowerCase()
 ```
 
-From that single line of source, the language gives you:
+From that single declaration, the language gives you:
 
-- a **runtime validator** — `User.parse(data)` / `.safe()` / `.ok()`
+- a **runtime validator** — `User.parse(data)` / `.safe()` / `.ok()` (plus
+  async variants), with strict wire coercion (`~integer`, `~:phone`),
+  cross-field refinements, and discriminated unions
 - a **generated class** with your methods and `~>` computed getters bound as prototype getters
-- a **TypeScript type** — `ModelSchema<UserInstance, UserData>`, automatic, no codegen step
+- a **TypeScript type** — `ModelSchema<User, UserData>`, automatic, no codegen step
 - an **async ORM** — `User.find! 1`, `User.where(active: true).all!`, `user.save!`
-- **migration-grade DDL** — `User.toSQL()` emits `CREATE TABLE`, indexes, foreign keys
+- **transactions** — `schema.transaction! ->` with ambient propagation,
+  rollback, and `afterCommit` hooks
+- **query economics** — `User.includes(:orders)` eager loading, composable
+  `@scope`s, batch writes; no N+1 by default
+- **migrations** — `rip schema make/migrate` diffs the declared models
+  against the live database and writes plain-SQL migration files
+- **a wire contract** — `User.toJSONSchema()`, and rip-server routes that
+  validate with a schema contribute to a generated `GET /openapi.json`
 - **schema algebra** — `User.omit("password")` produces a correctly-typed derived shape
 
 Schemas are runtime values. You pass them around, export them, derive from
@@ -49,32 +60,37 @@ architecture for contributors.
 1. [What Rip Schema is](#1-what-rip-schema-is)
 2. [A quick tour](#2-a-quick-tour)
 3. [Schemas vs types](#3-schemas-vs-types)
-4. [The five kinds](#4-the-five-kinds)
+4. [The six kinds](#4-the-six-kinds)
 5. [Body syntax](#5-body-syntax)
 6. [The runtime API](#6-the-runtime-api)
 7. [What `.parse()` returns by kind](#7-what-parse-returns-by-kind)
-8. [`:model` — ORM, DDL, hooks, relations](#8-model--orm-ddl-hooks-relations)
-9. [Mixins](#9-mixins)
-10. [Schema algebra](#10-schema-algebra)
-11. [Shadow TypeScript](#11-shadow-typescript)
-12. [SchemaError and diagnostics](#12-schemaerror-and-diagnostics)
-13. [Common mistakes](#13-common-mistakes)
-14. [Recipes](#14-recipes)
-15. [What's not here yet](#15-whats-not-here-yet)
+8. [`:model` — the ORM](#8-model--the-orm)
+9. [Transactions & data integrity](#9-transactions--data-integrity)
+10. [Query economics](#10-query-economics)
+11. [Adapters](#11-adapters)
+12. [DDL & schema evolution](#12-ddl--schema-evolution)
+13. [Wire contracts — JSON Schema & OpenAPI](#13-wire-contracts--json-schema--openapi)
+14. [Mixins](#14-mixins)
+15. [Schema algebra](#15-schema-algebra)
+16. [Shadow TypeScript](#16-shadow-typescript)
+17. [SchemaError and diagnostics](#17-schemaerror-and-diagnostics)
+18. [Common mistakes](#18-common-mistakes)
+19. [Recipes](#19-recipes)
+20. [What's not here yet](#20-whats-not-here-yet)
 
 ## Part II — Reference
-16. [Capability matrix](#16-capability-matrix)
-17. [Field types](#17-field-types)
-18. [Directives](#18-directives)
-19. [Hook reference](#19-hook-reference)
-20. [Constraints](#20-constraints)
-21. [Relations](#21-relations)
-22. [Design invariants](#22-design-invariants)
+21. [Capability matrix](#21-capability-matrix)
+22. [Field types](#22-field-types)
+23. [Directives](#23-directives)
+24. [Hook reference](#24-hook-reference)
+25. [Constraints](#25-constraints)
+26. [Relations](#26-relations)
+27. [Design invariants](#27-design-invariants)
 
 ## Part III — Architecture
-23. [Runtime architecture](#23-runtime-architecture)
-24. [Compiler integration](#24-compiler-integration)
-25. [FAQ](#25-faq)
+28. [Runtime architecture](#28-runtime-architecture)
+29. [Compiler integration](#29-compiler-integration)
+30. [FAQ](#30-faq)
 
 ---
 
@@ -86,9 +102,9 @@ A *schema* in Rip is a runtime value that describes data. You create one with
 the `schema` keyword and an optional `:kind` symbol:
 
 ```coffee
-SignupInput = schema             # default :input
-Role        = schema :enum
-User        = schema :model
+SignupInput = schema; email!     # default :input
+Role        = schema :enum; :admin; :user
+User        = schema :model; name!
 ```
 
 Every schema is a real JavaScript object at runtime. It has methods
@@ -122,7 +138,7 @@ schema dialect, its own types, its own runtime, its own failure modes:
 | Input validation            | Zod, Yup, Joi, io-ts, Valibot       | `schema :input` + `.parse/.safe`     |
 | Domain objects with logic   | hand-written classes + `zod.infer`  | `schema :shape`                      |
 | Database models             | Prisma, Drizzle, TypeORM, Sequelize | `schema :model`                      |
-| Migrations / DDL            | Prisma migrate, Drizzle Kit, knex   | `Model.toSQL()`                      |
+| Migrations / DDL            | Prisma migrate, Drizzle Kit, knex   | `Model.toSQL()` + `rip schema make/migrate` |
 | API projections / DTOs      | `.pick` / `.omit` on Zod + class    | `Model.pick/.omit/.partial/.extend`  |
 | Static types for the editor | Inferred from every library above   | Automatic shadow TS — no codegen     |
 | Fixed value sets            | TS `enum` or string unions          | `schema :enum` (runtime + static)    |
@@ -190,6 +206,27 @@ result = SignupInput.safe rawJson
 valid = SignupInput.ok rawJson
 ```
 
+### Validating a list
+
+`.array` turns any schema into a *list-of-that* schema, exposing the same
+validation family — the common shape for an API response (one request, many
+records):
+
+```coffee
+Product = schema :shape
+  id!   integer
+  name! string
+
+items   = Product.array.parse rawJson      # → Product[]; throws on any bad item
+result  = Product.array.safe rawJson       # → {ok, value: Product[], errors}
+allGood = Product.array.ok rawJson         # → boolean
+```
+
+A non-array input fails fast with an error naming what it got — so an enveloped
+`{ items: [...] }` passed whole, or a renamed key, is obvious — and each item
+failure carries its `[index]` so a bad record is locatable. `parseAsync` /
+`safeAsync` / `okAsync` mirror the async variants.
+
 ### A shape with behavior
 
 ```coffee
@@ -231,7 +268,7 @@ Status.ok "unknown"      # false
 ```coffee
 User = schema :model
   name!    string, 1..100
-  email!#  email
+  email!   email @unique
   @timestamps
   @has_many Order
 
@@ -246,21 +283,51 @@ Order = schema :model
 # DDL for migration (works with or without the ORM adapter configured)
 sql = User.toSQL()
 
-# ORM operations (async, use `!` or `await`)
+# ORM operations (async — `!` is the dammit operator, Rip's await)
 user   = User.create! name: "Alice", email: "ALICE@EXAMPLE.COM"
 found  = User.find! user.id
 orders = user.orders!                       # has_many relation → Order[]
 owner  = orders[0]?.user!                   # belongs_to relation → User
 ```
 
+### The production layer
+
+The same declaration carries the whole data layer — atomic writes,
+constant-query-count reads, schema evolution, and a live API contract:
+
+```coffee
+# Transactions — ambient propagation; model code inside is unchanged
+order = schema.transaction! ->
+  o = Order.create! userId: user.id, total: 100
+  user.name = "Alice Q."
+  user.save!
+  o                                          # block value = transaction value
+
+# Eager loading + scopes — a list view in three queries, any row count
+users = User.includes(orders: :user).where(active: true).all!
+
+# Migrations — diff the declared models against the live database
+#   rip schema status      applied / pending / drift + the classified plan
+#   rip schema make NAME   write migrations/NNNN_NAME.sql from the diff
+#   rip schema migrate     apply pending files, checksummed history
+
+# Wire contract — schema-validated routes feed a generated OpenAPI doc
+post '/signup', input: SignupInput, ->
+  { welcome: @input.email }                  # 400 + issues automatic
+```
+
+Each of these has its own section: [§9](#9-transactions--data-integrity),
+[§10](#10-query-economics), [§12](#12-ddl--schema-evolution),
+[§13](#13-wire-contracts--json-schema--openapi).
+
 ### Schema algebra — derive new shapes
 
 ```coffee
 UserPublic = User.omit "email"              # →  Schema<Omit<UserData, 'email'>>
 UserCreate = User.pick "name", "email"      # →  Schema<Pick<UserData, 'name' | 'email'>>
 UserUpdate = User.partial()                 # →  Schema<Partial<UserData>>
-AdminUser  = User.extend schema :shape
-  permissions! string[]
+AdminUser  = User.extend (schema :shape
+  permissions! string[])
 ```
 
 Derived schemas are always `:shape`. **Field semantics survive** —
@@ -285,9 +352,9 @@ User = schema
 schema.defaultMaxString = 500
 
 Profile = schema :model
-  name!                         # → {min: 1, max: 500}
-  email!#     email             # → {max: 500}
-  bio?        text              # → uncapped (text opts out)
+  name!                  # → {min: 1, max: 500}
+  email! email @unique   # → {max: 500}
+  bio?   text            # → uncapped (text opts out)
 
 # One-line small shapes, plus a registered schema used as a field type.
 Address = schema :shape; street? ..200; city? ..100; zip? ..10
@@ -296,8 +363,8 @@ Order = schema :shape
   address!    Address           # validation recurses; errors like "address.street"
 ```
 
-See §5 for body-syntax details, §17 for nested type references, and
-§20 for constraint and pragma rules.
+See §5 for body-syntax details, §22 for nested type references, and
+§25 for constraint and pragma rules.
 
 ---
 
@@ -342,17 +409,19 @@ plus the runtime dimension.
 
 ---
 
-## 4. The five kinds
+## 4. The six kinds
 
-Every schema has one of five kinds, selected by a `:symbol` after the
+Every schema has one of six kinds, selected by a `:symbol` after the
 `schema` keyword:
 
+<!-- doctest: skip -->
 ```coffee
 input  = schema                # default — :input
 shape  = schema :shape
 enum   = schema :enum
 mixin  = schema :mixin
 model  = schema :model
+union  = schema :union
 ```
 
 The kind determines which body forms are legal, what `.parse()` returns,
@@ -430,6 +499,48 @@ User = schema :model
 Mixins are fields-only. Methods, computed, hooks, and non-`@mixin`
 directives inside a mixin body are compile errors.
 
+### `:union`
+
+A discriminated union over registered schemas. The body names the
+discriminator field (`@on :field`, required — untagged unions are a
+non-goal: they make dispatch O(n) and error messages incoherent) and
+two or more constituent schemas, one per line:
+
+```coffee
+ClickEvent = schema :shape
+  kind! "click"               # single-literal constant — the tag
+  x!    integer
+  y!    integer
+
+ScrollEvent = schema :shape
+  kind!  "scroll"
+  delta! integer
+
+Event = schema :union
+  @on :kind
+  ClickEvent
+  ScrollEvent
+
+Event.parse(kind: "click", x: 1, y: 2)    # → ClickEvent instance
+Event.safe(kind: "hover")                 # → {field: "kind", error: "union",
+                                          #    message: "expected one of click | scroll"}
+```
+
+- Each constituent must declare the discriminator as a string-literal
+  type, all values distinct across the union — checked at first parse
+  (lazy, consistent with registry resolution), with the colliding
+  constituents named in the error.
+- `.parse(data)` reads the discriminator and dispatches O(1) to the
+  matching constituent's validator; the result is that constituent's
+  instance (shapes keep their behavior).
+- Usable as a field type like any registered schema: `events! Event[]`.
+- If any constituent is async-validating (`@ensure!`), the union is too
+  — use `parseAsync!` / `safeAsync!` / `okAsync!`.
+- Schema algebra on a union throws — distribute-vs-intersect has no
+  obviously-right answer, so v1 defers; derive from a constituent.
+- Shadow TS: `type Event = ClickEvent | ScrollEvent;` — narrowing via
+  the discriminator works natively.
+
 ### `:model`
 
 A DB-backed entity. Everything `:shape` offers (all field forms,
@@ -443,7 +554,7 @@ instances.
 ```coffee
 User = schema :model
   name!    string
-  email!#  email
+  email!   email @unique
   @timestamps
   @has_many Order
 
@@ -461,6 +572,7 @@ a schema-specific diagnostic.
 
 ### Field
 
+<!-- doctest: skip -->
 ```coffee
 name[!|?|#]*  [type]  [range]  [default]  [regex]  [attrs]  [, -> transform]
 ```
@@ -470,32 +582,111 @@ Modifiers:
 | Modifier | Meaning  |
 | -------- | -------- |
 | `!`      | required |
-| `#`      | unique (emits `UNIQUE` in DDL; also creates a unique index) |
 | `?`      | optional |
 
-Any combination works (`email!#` means required + unique). Order among
-modifiers doesn't matter. No modifier means "present but not required" —
+`!` and `?` are *shape* modifiers — they apply to every schema kind, and
+order doesn't matter. No modifier means "present but not required" —
 equivalent to `?` for validation purposes.
 
+Uniqueness is **not** a modifier — it's a *storage* constraint (only
+meaningful on `:model`), spelled `@unique`: inline as `email! email @unique`,
+or as a directive `@unique :email` (composite: `@unique [:partnerId, :mrn]`).
+
 **Type is optional** — when omitted, the field defaults to `string`. Type
 expressions accept:
 
 - a type identifier (`string`, `email`, `integer`, …)
 - an array suffix (`string[]`)
 - a string-literal union (`"M" | "F" | "U"`) — value must be one of the
-  listed members; 2+ members required, no mixing with base types
-
-```coffee
-name!                                   # required string (default type)
-tags!      string[]                     # required array of strings
-email!#    email                        # required, unique, email-format-validated
-bio?       text, 0..1000                # optional text, 0-1000 chars
-role?      string, ["user"]             # optional, default "user"
-status     string, [:draft]             # default :draft — same as ["draft"]
-zip!       string, /^\d{5}$/            # regex-validated
-sex?       "M" | "F" | "U"              # literal union
-priority   "low" | "med" | "high", [:med]  # literal union + default
-```
+  listed members; no mixing with base types. A single literal
+  (`kind! "click"`) is a constant field — the building block of
+  [discriminated unions](#union)
+- a `~`-prefixed coercible type (`~integer`, `~number`, `~boolean`,
+  `~date`) — "coerce, then validate" (see below)
+
+```coffee
+Example = schema
+  name!                                   # required string (default type)
+  tags!      string[]                     # required array of strings
+  email!    email @unique                        # required, unique, email-format-validated
+  bio?       text, 0..1000                # optional text, 0-1000 chars
+  role?      string, ["user"]             # optional, default "user"
+  status     string, [:draft]             # default :draft — same as ["draft"]
+  zip!       string, /^\d{5}$/            # regex-validated
+  sex?       "M" | "F" | "U"              # literal union
+  priority   "low" | "med" | "high", [:med]  # literal union + default
+```
+
+### Coercion types (`~type`)
+
+Wire data arrives as strings; a `~` prefix on a coercible built-in
+means the value converts through a strict table before validation:
+
+```coffee
+SearchParams = schema
+  page?     ~integer        # "42" → 42; "abc" → {error: 'coerce'}
+  minPrice? ~number         # "19.95" → 19.95
+  active?   ~boolean        # "true"/"1"/1 → true; "false"/"0"/0 → false
+  since?    ~date           # ISO-8601 string or epoch ms → Date
+```
+
+- Coercion tables are strict and documented: `~integer` accepts
+  integral strings and integral numbers, rejects `NaN` and `"12.5"`;
+  `~boolean` accepts exactly the six tokens above; `~date` accepts
+  ISO-8601 strings and finite epoch numbers. Failed coercion is
+  `{error: 'coerce'}` — distinct from `{error: 'type'}`, because "looked
+  like wire data but didn't convert" is a different mistake than "wrong
+  shape entirely".
+- Constraints apply **after** coercion — `age? ~integer, 18..120` range-
+  checks the coerced number.
+- Coercion is field semantics, so it **survives algebra** (`.pick`,
+  `.omit`, …) like transforms do, and is **skipped on DB hydrate**
+  (rows arrive canonical).
+- `~` doesn't combine with a `->` transform (the transform IS manual
+  control of the same step), doesn't apply to arrays, and only covers
+  the four wire-friendly built-ins — everything else wants a named
+  coercer or an explicit transform.
+
+### Named coercers (`~:name`)
+
+A `~:symbol` in the type slot coerces through the **named-coercer
+registry** — and `@rip-lang/validate` (the zero-dependency,
+browser-safe package behind `@rip-lang/server`'s `read()` vocabulary)
+registers every battle-tested wire normalizer (`id`, `money`, `ssn`,
+`phone`, `name`, `date`, `state`, `zipplus4`, `slug`, `ids`, …) there
+at load, so they all work in a schema field:
+
+```coffee
+Patient = schema :model
+  chart!  ~:id, 1..99999     # "42" → 42 (integer; constraint after coercion)
+  ssn?    ~:ssn              # "123-45-6789" → "123456789"
+  phone?  ~:phone            # "8016542000" → "(801) 654-2000"
+  state?  ~:state            # "ut" → "UT"
+  dob?    ~:date             # normalized "YYYY-MM-DD" string
+  amount? ~:money            # "$1,234.50" → 1234.5
+  kids?   ~:ids              # "3, 1, 2, 2" → [1, 2, 3]
+```
+
+- The normalizer behind `read 'dob', 'date'` is the *same function*
+  behind `dob? ~:date` — one vocabulary, two call sites.
+  `registerValidator` registers both; schema-only code can use
+  `schema.registerCoercer name, fn` directly.
+- The vocabulary is **isomorphic**: importing `@rip-lang/server` loads
+  it on the server, and a side-effect `import '@rip-lang/validate'` in
+  any component file loads it in the browser bundle — so a schema with
+  `~:ssn` parses identically on both sides of the wire.
+- A coercer returning `null`/`undefined`/`false` fails the field with
+  `{error: 'coerce', message: "<field> is not a valid <name>"}`. A
+  coercer that isn't registered at parse time is a **config error**
+  (fail loud), not a validation failure.
+- Output types: the shipped names carry static output types for shadow
+  TS and DDL (`~:id` → `number`/INTEGER, `~:money` → `number`,
+  `~:ids` → `number[]`, `~:ssn` → `string`, …). Custom-registered
+  names type as `any` — use an explicit transform when you need a
+  precise static type.
+- Note the namespaces differ: `~date` (built-in) coerces to a `Date`
+  instance; `~:date` (named) normalizes to a `"YYYY-MM-DD"` string —
+  exactly what `read 'x', 'date'` returns.
 
 ### Inline field transform
 
@@ -505,11 +696,12 @@ raw input. `it` inside the body refers to the **whole raw input object**
 differently-named key, compose across multiple inputs, or coerce types:
 
 ```coffee
-id!          -> it.Id                                    # remap PascalCase input
-displayName! -> it.DisplayName
-shippedAt?   date, -> new Date(it.shippedAt)             # wire string → Date
-slug!        -> "#{it.FirstName}-#{it.LastName}".toLowerCase()
-email!#      email, -> it.email.toLowerCase().trim()     # normalize + validate
+Imported = schema
+  id!          -> it.Id                                    # remap PascalCase input
+  displayName! -> it.DisplayName
+  shippedAt?   date, -> new Date(it.shippedAt)             # wire string → Date
+  slug!        -> "#{it.FirstName}-#{it.LastName}".toLowerCase()
+  email!       email @unique, -> it.email.toLowerCase().trim()     # normalize + validate
 ```
 
 Rules:
@@ -521,7 +713,7 @@ Rules:
   the line (type, range, regex, default, attrs). The comma is a
   structural boundary between the field declaration and the
   transform, not an argument separator — without it, lines like
-  `email!# email -> fn` misleadingly suggest `email` is an input to
+  `email! email -> fn` misleadingly suggest `email` is an input to
   the arrow. The bare form `name! -> fn` (nothing before the arrow
   except the name and modifiers) parses comma-less because there's
   nothing to elide. This is unlike Rip's general `get '/path' ->`
@@ -541,7 +733,7 @@ Rules:
 ```
 
 Directives attach behavior that isn't a field. The set depends on the
-kind (see [§18](#18-directives)). Examples:
+kind (see [§23](#23-directives)). Examples:
 
 ```coffee
 @timestamps                       # adds createdAt/updatedAt columns (:model only)
@@ -557,21 +749,33 @@ kind (see [§18](#18-directives)). Examples:
 
 ```coffee
 name: -> body
+name: (params) -> body
 ```
 
 Thin-arrow method bound on the generated class prototype. `this` is the
-instance. For `:model`, method names matching known [hook
-names](#19-hook-reference) bind to the lifecycle; on other kinds those
-names are just methods.
+instance. Parameters are optional and may carry Rip type annotations,
+which flow into shadow TS — a fully-annotated method gets its complete
+signature (typed params, `this`, and the inferred return) instead of
+`(...args: any[]) => unknown`:
 
 ```coffee
 greet: -> "Hello, #{@name}!"
 
+add: (other:: Money) ->
+  Money.parse amount: @amount + other.amount, currency: @currency
+  # shadow TS: add(this: Money, other: Money): Money
+
 beforeSave: ->
   @email = @email.toLowerCase()
   @slug  = @name.toLowerCase().replace(/\s+/g, '-')
 ```
 
+Parameters are method-only — lifecycle hooks, computed getters (`~>`),
+and eager-derived fields (`!>`) are accessor-shaped and reject them.
+For `:model`, method names matching known [hook
+names](#24-hook-reference) bind to the lifecycle; on other kinds those
+names are just methods.
+
 ### Computed getter (lazy)
 
 ```coffee
@@ -591,6 +795,7 @@ isAdmin:    ~> @role is 'admin'
 
 ### Eager-derived field
 
+<!-- doctest: skip -->
 ```coffee
 name: !> body
 ```
@@ -602,9 +807,11 @@ Excluded from DDL and persistence — re-computed on hydrate from the
 declared fields.
 
 ```coffee
-fullName:    !> "#{@firstName} #{@lastName}".trim()
-orderNumber: !> "ORD-#{String(@id).padStart(6, '0')}"
-slug:        !> @fullName.toLowerCase().replace(/\s+/g, '-')
+Person = schema :shape
+  firstName! string
+  lastName!  string
+  fullName:    !> "#{@firstName} #{@lastName}".trim()
+  slug:        !> @fullName.toLowerCase().replace(/\s+/g, '-')
 ```
 
 Declaration order matters — an `!>` can read earlier declared fields
@@ -652,6 +859,36 @@ Two forms, same semantics:
 ]
 ```
 
+An optional `:field` symbol between the message and the predicate
+**attributes the failure to a specific field**, so form libraries can
+attach the error to the right input (without it, the issue stays
+schema-wide with `field: ''`):
+
+```coffee
+@ensure "passwords must match", :password2, (u) -> u.password is u.password2
+# fails as {field: "password2", error: "ensure", message: "passwords must match"}
+```
+
+**Async refinements** use the dammit operator — `@ensure!` — for
+predicates that await a database or network check:
+
+```coffee
+Signup = schema
+  email! email
+  @ensure! "email already registered", :email, (u) ->
+    not await User.where(email: u.email).first()
+```
+
+A schema with ≥1 `@ensure!` is **async-validating**: sync `.parse` /
+`.safe` / `.ok` throw immediately ("use parseAsync!/safeAsync!/okAsync!")
+— no silent promise-leak, no sometimes-sync API. Sync refinements run
+first (cheap before expensive); async refinements then run
+**concurrently** (`Promise.all`) with all results collected in
+declaration order, preserving the no-short-circuit rule. A rejected
+async predicate counts as failed with the declared message. Async
+refinements are skipped on hydrate and dropped by algebra, same as
+sync ones.
+
 Both forms compile to the same internal representation; use whichever
 reads cleanest for the case at hand. The inline form is nicer for
 one-offs; the array form keeps related invariants visually grouped.
@@ -685,7 +922,7 @@ Rules:
   would be wasted work.
 - **Refinements drop on algebra.** Any derivation (`.pick`, `.omit`,
   `.partial`, `.required`, `.extend`) returns a `:shape` without any
-  refinements from the source. See [§10](#10-schema-algebra).
+  refinements from the source. See [§15](#15-schema-algebra).
 
 **Scope**: `:input`, `:shape`, and `:model` accept `@ensure`. `:enum`
 and `:mixin` reject it at compile time with a diagnostic pointing at
@@ -737,6 +974,7 @@ hook / transform), `~>` (computed getter), `!>` (eager-derived) — is
 rejected on the inline form with a message pointing to the indented
 form:
 
+<!-- doctest: fail -->
 ```coffee
 # compile error — point at the indented form:
 X = schema :shape; name!; greet: -> @name   # ✗ '->' not allowed inline
@@ -800,14 +1038,25 @@ Validates `data`. Returns a boolean. Allocates no error arrays — this is
 the fast path for filter-style checks.
 
 ```coffee
-if User.ok raw
-  # ...
+process raw if User.ok raw
 ```
 
-### Async variants (`parse!`, `safe!`, `ok!`)
+### `.parseAsync(data)` / `.safeAsync(data)` / `.okAsync(data)`
+
+Async validation entry points. They exist on **every** schema (sync-only
+schemas just resolve immediately) and are **required** when the schema
+has `@ensure!` async refinements — the sync trio throws on those schemas
+rather than sometimes-returning a promise. The dammit operator gives the
+idiomatic call:
+
+```coffee
+user = Signup.parseAsync! raw
+r    = Signup.safeAsync! raw
+ok   = Signup.okAsync! raw
+```
+
+### The dammit operator and the ORM
 
-Every method has a dammit-operator variant that awaits the result. For
-`:input`/`:shape`/`:enum` these are sync, so `!` is a no-op (harmless).
 For `:model`, the ORM methods are all genuinely async and `!` is the
 canonical form:
 
@@ -827,6 +1076,7 @@ users = User.where(active: true).all!
 | `:shape`   | Instance of a generated class — fields as enumerable own properties, methods and getters on the prototype | same |
 | `:enum`    | The member value (or the name string, for bare enums) | same |
 | `:model`   | **Unpersisted** instance — same structure as `:shape`, but the class also has `save()`, `destroy()`, relation methods, and `_persisted` state | same |
+| `:union`   | The matching constituent's `.parse()` result — dispatched O(1) on the discriminator | same |
 | `:mixin`   | **Not instantiable** — `.parse()` throws | N/A |
 
 For `:shape` and `:model`:
@@ -841,32 +1091,42 @@ For `:shape` and `:model`:
 
 ---
 
-## 8. `:model` — ORM, DDL, hooks, relations
+## 8. `:model` — the ORM
 
 `:model` is where everything comes together. A model declaration gives
 you:
 
 - field validation (from `:shape`)
 - class instances with methods and computed getters (from `:shape`)
-- lifecycle hooks bound by name
+- lifecycle hooks bound by name (12 of them, including transaction-aware
+  `afterCommit` / `afterRollback`)
 - an async ORM — `find`, `where`, `create`, `save`, `destroy`
-- `.toSQL()` for DDL (works without ever touching the ORM)
 - relation accessors driven by `@belongs_to` / `@has_many` / `@has_one`
 - automatic registration in a process-global registry for cross-module
   relation resolution
 
+This section covers the core read/write surface. The rest of the data
+layer has its own sections: transactions and constraint translation
+([§9](#9-transactions--data-integrity)), eager loading / scopes / batch
+writes / soft deletes ([§10](#10-query-economics)), adapters
+([§11](#11-adapters)), DDL and migrations
+([§12](#12-ddl--schema-evolution)).
+
 ### Static ORM methods
 
 ```coffee
-User.find! id                            # → UserInstance | null
-User.findMany! [1, 2, 3]                 # → UserInstance[]
-User.where(active: true).all!            # → UserInstance[]
-User.where(active: true).first!          # → UserInstance | null
+User.find! id                            # → User | null
+User.findMany! [1, 2, 3]                 # → User[] (one IN query)
+User.where(active: true).all!            # → User[]
+User.where(active: true).first!          # → User | null
 User.where(active: true).count!          # → number
-User.all!                                # → UserInstance[]
-User.first!                              # → UserInstance | null
+User.includes(:orders).all!              # → eager-loaded (see below)
+User.all!                                # → User[]
+User.first!                              # → User | null
 User.count!                              # → number
 User.create! name: "Alice", email: "a@b.c"
+User.upsert! {email: "a@b.c", name: "Al"}, on: :email   # INSERT … ON CONFLICT
+User.insertMany! rows                    # validate all, one multi-VALUES INSERT
 User.toSQL()                             # → DDL string (no DB call)
 ```
 
@@ -875,16 +1135,19 @@ User.toSQL()                             # → DDL string (no DB call)
 ```coffee
 User
   .where(active: true)                   # object → AND equalities
+  .where(id: [1, 2, 3])                  # array value → IN (…)
   .where("created_at > ?", since)        # raw SQL + params
+  .includes(:orders)                     # eager-load relations (see below)
   .order("last_name, first_name")        # or .orderBy — same thing
   .limit(10)
   .offset(20)
   .all!
 ```
 
-- `.where`, `.limit`, `.offset`, `.order` / `.orderBy` return the query
-  builder (sync).
-- `.all`, `.first`, `.count` terminate with a promise.
+- `.where`, `.includes`, `.limit`, `.offset`, `.order` / `.orderBy`,
+  `.withDeleted`, `.onlyDeleted` return the query builder (sync).
+- `.all`, `.first`, `.count`, `.updateAll`, `.deleteAll` terminate with
+  a promise.
 
 ### Instance methods
 
@@ -893,6 +1156,8 @@ Every `:model` instance carries:
 ```coffee
 user.save!              # validate, run hooks, INSERT or UPDATE
 user.destroy!           # run hooks, DELETE (or UPDATE deleted_at for @softDelete)
+user.destroy! hard: true  # force a real DELETE on a @softDelete model
+user.restore!           # @softDelete only — UPDATE deleted_at = NULL
 user.ok()               # boolean — current fields validate
 user.errors()           # SchemaIssue[] — current fields' errors
 user.toJSON()           # plain object of own enumerable properties
@@ -1022,8 +1287,8 @@ the same instance work fine.
 
 ### Lifecycle hooks
 
-Hooks are methods whose name matches one of the [ten recognized hook
-names](#19-hook-reference). On `:model` they bind into the lifecycle; on
+Hooks are methods whose name matches one of the [twelve recognized hook
+names](#24-hook-reference). On `:model` they bind into the lifecycle; on
 other kinds they're just regular methods.
 
 **Save flow:**
@@ -1061,6 +1326,12 @@ Validation happens **after** `beforeValidation` (so that hook is the
 right place to normalize input) and **before** `beforeSave` (so `beforeSave`
 only runs on already-valid data).
 
+`afterCommit` and `afterRollback` sit outside both flows: when a
+`schema.transaction!` is open they queue on it and fire after the
+outermost COMMIT / ROLLBACK; with no transaction open, `afterCommit`
+fires immediately after a successful save/destroy and `afterRollback`
+never fires. See the Transactions section above.
+
 ### Relations
 
 ```coffee
@@ -1079,11 +1350,11 @@ Relation accessors are **async methods** on the instance prototype:
 
 ```coffee
 user = User.find! 1
-orders  = user.orders!            # → OrderInstance[]
-profile = user.profile!           # → ProfileInstance | null
+orders  = user.orders!            # → Order[]
+profile = user.profile!           # → Profile | null
 
 order  = Order.find! 42
-owner  = order.user!              # → UserInstance | null
+owner  = order.user!              # → User | null
 ```
 
 Accessor names:
@@ -1096,81 +1367,9 @@ Targets resolve lazily through a process-global registry keyed by name.
 Circular and cross-module references work — import the file that defines
 the target, and relation calls succeed.
 
-See [§21 Relations](#21-relations) for the full table of directive →
+See [§26 Relations](#26-relations) for the full table of directive →
 accessor → return type.
 
-### DDL (`.toSQL()`)
-
-`.toSQL()` returns `CREATE SEQUENCE` + `CREATE TABLE` + index `CREATE`
-statements for a model. It does not touch the database — you run the
-output through whatever migration plumbing you prefer.
-
-```coffee
-User.toSQL()
-# CREATE SEQUENCE users_seq START 1;
-#
-# CREATE TABLE users (
-#   id INTEGER PRIMARY KEY DEFAULT nextval('users_seq'),
-#   name VARCHAR(100) NOT NULL,
-#   email VARCHAR NOT NULL UNIQUE,
-#   created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
-#   updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
-# );
-#
-# CREATE UNIQUE INDEX idx_users_email ON users ("email");
-```
-
-`.toSQL()` works independently of the ORM. A migration script that never
-calls `.find()` or `.create()` can still emit full DDL.
-
-#### Sequence start value
-
-The auto-id sequence seeds at `1` by default. Override per-model with the
-`@idStart N` directive, or per-call with the `idStart` option (the option
-wins):
-
-```coffee
-User = schema :model
-  name! string
-  @idStart 10001            # customer-facing IDs start at 10001
-
-User.toSQL()                # → CREATE SEQUENCE users_seq START 10001;
-User.toSQL(idStart: 50000)  # → CREATE SEQUENCE users_seq START 50000;
-```
-
-Required because DuckDB (as of 1.5.2) does not implement
-`ALTER SEQUENCE … RESTART WITH N` — so the seed has to be baked into the
-initial `CREATE SEQUENCE` rather than bumped in a follow-up migration.
-
-To emit a whole application's schema, call `.toSQL()` per model and join.
-Order by FK dependency (models referenced via `@belongs_to` come first):
-
-```coffee
-ddl = [
-  User.toSQL()
-  Category.toSQL()
-  Order.toSQL()       # references User
-  OrderItem.toSQL()   # references Order
-].join('\n\n')
-```
-
-### The adapter seam
-
-All ORM methods route through a single adapter interface: `adapter.query(sql, params)`.
-The default adapter uses `fetch` against a rip-db instance at `$DB_URL`.
-Install a custom adapter (for tests, or for a different backend) with
-`__schemaSetAdapter`:
-
-```coffee
-globalThis.__ripSchema.__schemaSetAdapter
-  query: (sql, params) ->
-    # return {columns: [{name, type}, ...], data: [[row values], ...], rows: N}
-    ...
-```
-
-The adapter contract is minimal — one method, one result shape. Any DB
-client that can execute parameterized SQL and return row data fits.
-
 ### Snake / camel dual access on instances
 
 Database columns are typically snake_case (`user_id`, `created_at`) while
@@ -1268,7 +1467,426 @@ always quoted, and raw SQL is always the user's responsibility.
 
 ---
 
-## 9. Mixins
+## 9. Transactions & data integrity
+
+Atomic multi-statement writes, transaction-aware lifecycle hooks, and
+DB constraint violations that fail the same structured way validation
+does.
+
+### Transactions (`schema.transaction!`)
+
+Atomic multi-statement writes. The block's value becomes the
+transaction's value; a throw rolls everything back and propagates:
+
+```coffee
+result = schema.transaction! ->
+  user = User.create! name: "Alice", email: "a@b.c"
+  Order.create! userId: user.id, total: 100
+  user                                   # block value = transaction!'s value
+```
+
+- **Propagation is ambient** (AsyncLocalStorage): every ORM call inside
+  the block — `create!`, `save!`, `destroy!`, relation accessors,
+  queries — automatically routes through the transaction's pinned
+  connection. Model code is unchanged inside the block.
+- Block throws → `ROLLBACK`, the exception propagates. Block returns →
+  `COMMIT`, the value is returned.
+- **Nested `transaction!` joins the outer transaction** (Active
+  Record's default). DuckDB has no `SAVEPOINT`, so independent nested
+  units aren't expressible on the primary backend; joining is the
+  honest semantics.
+- Don't parallelize ORM calls *inside* one transaction — they share one
+  pinned DB connection, exactly like one connection in any ORM.
+  Parallel `transaction!` blocks are fine; each gets its own connection
+  and its own ambient context.
+- Two transaction-aware hooks: `afterCommit` fires after the outermost
+  transaction commits (or immediately after save/destroy when no
+  transaction is open) — this is where emails, webhooks, and cache
+  invalidation belong. `afterRollback` fires after a rollback for each
+  instance saved/destroyed inside the rolled-back transaction. A row
+  saved twice in one transaction gets one callback. Exceptions in
+  `afterCommit` propagate but cannot roll back — the COMMIT already
+  happened.
+- Against rip-db / duckdb-harbor, the transaction rides harbor's
+  session protocol (`POST /sql/sessions/new` pins a connection; the
+  session is destroyed after COMMIT/ROLLBACK; harbor's idle TTL
+  auto-rolls-back abandoned transactions server-side). Note: harbor
+  gates session creation behind the `__HARBOR_ADMIN__:sessions:create`
+  authz policy — transactions need an authz rule allowing it (or
+  `harbor_allow_admin_without_authz = true` on trusted deployments),
+  and an authenticated principal (harbor's unauthenticated `token :=
+  NULL` mode cannot create owned sessions).
+- Adapters without `begin()` throw a clear "does not support
+  transactions" error — never a silent non-transactional fallback.
+
+### Constraint violations are SchemaErrors
+
+The ORM wraps every adapter call. DB errors recognized as constraint
+violations are translated into `SchemaError` so a `save!` that trips a
+UNIQUE index fails the same way a `save!` that trips a validator does:
+
+| DB condition | Issue emitted |
+| --- | --- |
+| UNIQUE violation | `{field: "email", error: "unique", message: "email already taken"}` |
+| NOT NULL violation | `{field, error: "required", …}` |
+| FK violation | `{field, error: "reference", …}` |
+| CHECK violation | `{field: "", error: "check", …}` |
+
+The original adapter error is preserved as `err.cause`. Unrecognized
+errors propagate untouched. Uniqueness pre-checks
+(`validates_uniqueness_of`-style) are deliberately **not** offered —
+they race; the DB constraint is the check, translation makes it
+ergonomic.
+
+## 10. Query economics
+
+The features that keep list views at a constant query count and bulk
+operations at one statement: eager loading, composable scopes, batch
+writes, and soft deletes.
+
+### Eager loading (`.includes`)
+
+Relations are lazy by default — `user.orders!` issues a query on demand,
+which makes N+1 the default behavior of every list view. `.includes`
+fixes the economics with **batched second queries** (`WHERE fk IN (…)`),
+never JOINs — no row duplication, uniform across `belongs_to` /
+`has_one` / `has_many`:
+
+```coffee
+users = User.includes(:orders).where(active: true).all!
+posts = Post.includes(:author, comments: :author).limit(20).all!
+```
+
+- Accepts `:symbols`, strings, and nested `{relation: nested}` maps to
+  any depth. One query per relation per nesting level, regardless of
+  row count.
+- Preloaded relations fill the accessor's **memo**: `user.orders!`
+  resolves from cache with no query. The accessor API is unchanged
+  (uniform async) — preloading is purely a performance fact, invisible
+  to call sites.
+- `.includes` never changes the root result set — same rows with or
+  without it.
+
+Relation accessors memoize independently of `.includes`: the second
+`user.orders!` call on the same instance is free. Pass
+`user.orders! reload: true` to bust the memo and re-query.
+
+### Query scopes (`@scope`, `@defaultScope`)
+
+Named, composable query fragments declared on the model:
+
+```coffee
+User = schema :model
+  name!    string
+  active?  boolean
+  role?    string
+  @scope :active, -> @where(active: true)
+  @scope :since,  (d) -> @where("created_at > ?", d)
+  @defaultScope -> @where(banned: false)
+
+User.active().since(monday).order("name").all!
+User.where(role: "admin").active().all!       # chains in any order
+User.unscoped().all!                          # skip the @defaultScope
+```
+
+- `this` inside a scope body is the query builder; scopes return the
+  builder, so they compose with each other and with `.where` /
+  `.order` / `.limit` in any order. Parameterized scopes declare their
+  args: `(d) -> @where("created_at > ?", d)`.
+- Scopes live in the **static** namespace (model + builder), so a field
+  `active` and a scope `:active` coexist. Scope names may not collide
+  with the query API (`where`, `find`, `order`, …) or with each other —
+  checked at first use with a `collision` SchemaError.
+- `@defaultScope` (at most one per model) applies to every read and
+  bulk write — `where`/`all`/`first`/`count`/`find`/`findMany`/
+  `updateAll`/`deleteAll` — unless `.unscoped()` appears anywhere in
+  the chain. It composes with `@softDelete`'s implicit filter; both
+  apply. (Use sparingly — Active Record's caveats about default
+  scopes apply verbatim.)
+- Scopes appear in shadow TS: typed statics on the model const plus a
+  per-model `UserQuery` alias so scope-first chains typecheck.
+
+### Batch writes
+
+```coffee
+User.upsert! {email: "a@b.c", name: "Alice"}, on: :email
+  # INSERT … ON CONFLICT (email) DO UPDATE SET …; validates;
+  # beforeSave/afterSave fire; beforeCreate/beforeUpdate do NOT
+  # (the runtime can't know which branch the DB took).
+  # DuckDB caveat: ON CONFLICT updates on rows referenced by another
+  # table's FK trip DuckDB's indexed-column restriction — see
+  # docs/RIP-DUCKDB.md.
+
+User.insertMany! rows
+  # validates every row first (ALL failures collected into one
+  # SchemaError with `[i].field` issue paths, before any SQL), then one
+  # multi-VALUES INSERT … RETURNING *. Per-instance hooks deliberately
+  # skipped — this is the bulk path; use create! in a loop for hooks.
+
+User.where(active: false).deleteAll!     # one statement (soft-delete aware)
+User.where(plan: "trial").updateAll! expired: true
+  # one UPDATE; bypasses validation and hooks — the name says "all",
+  # the docs say "raw". Bumps updated_at on @timestamps models.
+```
+
+### Soft deletes
+
+`@softDelete` adds a `deleted_at` column and turns `.destroy()` into an
+UPDATE. Every read (`find`, `where`, `all`, `first`, `count`) and bulk
+write implicitly filters `deleted_at IS NULL`. The escape hatches:
+
+```coffee
+User.withDeleted().all!          # no filter — live and deleted rows
+User.onlyDeleted().all!          # inverted filter — deleted rows only
+user.restore!                    # UPDATE … SET deleted_at = NULL
+user.destroy! hard: true         # real DELETE; hooks still fire
+```
+
+Relation accessors on other models respect the target's soft-delete
+filter — an `order.user!` of a soft-deleted user resolves `null`,
+consistent with `find`.
+
+## 11. Adapters
+
+### The adapter seam (Contract v2)
+
+All ORM methods route through a single adapter funnel.
+`query(sql, params)` is the only **required** method; v2 adds optional
+capabilities the runtime feature-detects:
+
+```coffee
+globalThis.__ripSchema.__schemaSetAdapter
+  # required — returns {columns: [{name, type}, …], data: [[…]], rowCount: N}
+  query: (sql, params) ->
+    db.run sql, params
+
+  # optional — transactions (schema.transaction!). Returns a TxHandle.
+  begin: (options) ->
+    conn = db.pin()
+    conn.run 'BEGIN'
+    {
+      query:    (sql, params) -> conn.run sql, params
+      commit:   -> conn.run 'COMMIT'   and conn.release()
+      rollback: -> conn.run 'ROLLBACK' and conn.release()
+    }
+
+  capabilities: { tx: true }    # truthful self-report
+```
+
+Calling a feature whose method is absent throws a clear error
+(`schema.transaction()` on an adapter without `begin()` says so by
+name) — never a silent fallback.
+
+The default adapter talks to a duckdb-harbor instance: `RIP_DB_URL`
+(default `http://127.0.0.1:9494`; legacy `DB_URL` honored) and
+`RIP_DB_TOKEN` for bearer auth. Its `begin()` rides harbor's session
+protocol — `POST /sql/sessions/new` pins a connection, statements carry
+the `sessionId`, and the session is destroyed after COMMIT/ROLLBACK.
+`@rip-lang/db`'s `connect(url)` installs the same contract (query +
+begin) with its richer error handling and timeouts.
+
+### Per-schema adapters (`on:`)
+
+Multi-database setups pin individual models to their own adapter:
+
+```coffee
+analytics = schema.connect url: env.ANALYTICS_URL, token: env.ANALYTICS_TOKEN
+
+Event = schema :model, on: analytics
+  name! string
+  @timestamps
+```
+
+- `schema.connect {url, token?}` builds a NEW harbor adapter value
+  without installing it globally; any Contract-v2 adapter object works
+  in the `on:` slot. The default remains the global adapter.
+- Every ORM call resolves the model's adapter; `schema.transaction!`
+  takes `on: analytics` to pin the ambient transaction to one adapter.
+  ORM calls against a *different* adapter inside that block run
+  **outside** the transaction — each adapter has its own ambient slot,
+  and cross-adapter atomicity is impossible, so the runtime never
+  pretends otherwise.
+- `@belongs_to` / `@has_many` across adapters: the accessor works (it's
+  just a second query), but FK DDL emission is suppressed with a note —
+  the constraint can't exist cross-database.
+
+## 12. DDL & schema evolution
+
+Greenfield CREATE comes from `toSQL()`; everything after the first
+deploy comes from the migration system — diffing the declared models
+against the live database.
+
+### DDL (`.toSQL()`)
+
+`.toSQL()` returns `CREATE SEQUENCE` + `CREATE TABLE` + index `CREATE`
+statements for a model. It does not touch the database — you run the
+output through whatever migration plumbing you prefer.
+
+```coffee
+User.toSQL()
+# CREATE SEQUENCE users_seq START 1;
+#
+# CREATE TABLE users (
+#   id INTEGER PRIMARY KEY DEFAULT nextval('users_seq'),
+#   name VARCHAR(100) NOT NULL,
+#   email VARCHAR NOT NULL,
+#   created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+#   updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+# );
+#
+# CREATE UNIQUE INDEX idx_users_email ON users ("email");
+#
+# CREATE UNIQUE INDEX idx_users_email ON users ("email");
+```
+
+`.toSQL()` works independently of the ORM. A migration script that never
+calls `.find()` or `.create()` can still emit full DDL.
+
+#### Sequence start value
+
+The auto-id sequence seeds at `1` by default. Override per-model with the
+`@idStart N` directive, or per-call with the `idStart` option (the option
+wins):
+
+```coffee
+User = schema :model
+  name! string
+  @idStart 10001            # customer-facing IDs start at 10001
+
+User.toSQL()                # → CREATE SEQUENCE users_seq START 10001;
+User.toSQL(idStart: 50000)  # → CREATE SEQUENCE users_seq START 50000;
+```
+
+Required because DuckDB (as of 1.5.2) does not implement
+`ALTER SEQUENCE … RESTART WITH N` — so the seed has to be baked into the
+initial `CREATE SEQUENCE` rather than bumped in a follow-up migration.
+
+To emit a whole application's schema, call `.toSQL()` per model and join.
+Order by FK dependency (models referenced via `@belongs_to` come first):
+
+```coffee
+ddl = [
+  User.toSQL()
+  Category.toSQL()
+  Order.toSQL()       # references User
+  OrderItem.toSQL()   # references Order
+].join('\n\n')
+```
+
+### Schema evolution (`rip schema status / make / migrate`)
+
+`.toSQL()` covers greenfield CREATE. Evolution — diffing the declared
+models against the deployed database and emitting ALTER migrations —
+is built in:
+
+```text
+rip schema status  [models.rip]        # applied / pending / drift + the current plan
+rip schema plan    [models.rip]        # just the classified diff
+rip schema make <name> [models.rip]    # write migrations/NNNN_<name>.sql from the diff
+rip schema migrate [models.rip]        # apply pending migration files in order
+```
+
+The same verbs are callable from code: `schema.plan!`, `schema.status!`,
+`schema.make! "name", opts`, `schema.migrate! opts`, and
+`schema.introspect!` (the deployed schema as canonical table specs).
+
+**How it works.** The DDL emitter's internal model is exposed as a
+canonical table spec (`Model._tableSpec()`); introspection builds the
+same structure from the live database (`information_schema` +
+`duckdb_*()` catalogs, or the adapter's own `introspect()` capability).
+The differ operates on two values of the same type and emits classified
+steps:
+
+| Class | Examples | Gate |
+| --- | --- | --- |
+| `safe` | ADD COLUMN (nullable / defaulted), CREATE TABLE, CREATE INDEX, RENAME | none |
+| `lossy` | type change, SET NOT NULL, new UNIQUE on existing data | `--allow-lossy` |
+| `destructive` | DROP COLUMN, DROP TABLE | `--allow-destructive` |
+| `blocked` | any ALTER DuckDB refuses on an FK-referenced table | no flag — manual rebuild |
+
+**Migration files are plain SQL** — numbered, hand-editable, checked
+into git (default `./migrations`). `make` writes them; humans may amend
+them; `migrate` applies pending files in order (each inside a
+transaction when the adapter supports one) and records
+`(version, name, checksum, applied_at)` in `_rip_migrations`. A
+checksum mismatch on an applied file aborts — someone edited history —
+unless `--repair` re-records.
+
+**Renames are resolved in the declaration**, since a diff cannot
+distinguish rename from drop + add:
+
+```coffee
+User = schema :model
+  givenName! ..50, {was: "first_name"}    # column rename
+  @tableWas legacy_users                   # table rename
+```
+
+The differ consumes the annotation and emits `RENAME` instead of
+`DROP + ADD`; once the migration lands, the annotation is dead weight
+and can be removed.
+
+**DuckDB caveats the differ understands:**
+
+- `ADD COLUMN` cannot carry `NOT NULL` / `UNIQUE` / `REFERENCES` —
+  required adds become add → (backfill TODO when no default) →
+  `SET NOT NULL`; unique adds get a separate `CREATE UNIQUE INDEX`;
+  FK constraints cannot be added to an existing table at all (a note is
+  emitted).
+- A table referenced by another table's FOREIGN KEY is frozen for
+  everything except `ADD COLUMN` and index DDL ("Dependency Error") —
+  such steps classify `blocked`. The plan orders ALTERs before
+  CREATEs so a new child table never freezes its parent mid-migration.
+- `VARCHAR(n)` length hints are not persisted by DuckDB, so they never
+  produce drift; sequence start values cannot be altered after
+  creation, so `@idStart` drift is reported as a note, not a step.
+
+## 13. Wire contracts — JSON Schema & OpenAPI
+
+### JSON Schema & OpenAPI (`toJSONSchema`)
+
+Every schema exports a JSON Schema (draft 2020-12):
+
+```coffee
+SignupInput.toJSONSchema()
+# { $schema: "…/2020-12/schema", title: "SignupInput", type: "object",
+#   properties: { email: {type: "string", format: "email"}, … },
+#   required: ["email", "password"] }
+```
+
+- Field types map per [§22](#22-field-types); ranges become
+  `minLength`/`maxLength`/`minimum`/`maximum`/`minItems`/`maxItems`,
+  regexes become `pattern`, defaults become `default`, literal unions
+  become `enum` (single literal → `const`).
+- Nested registry schemas become `$ref`s collected under `$defs`
+  (cycle-safe — recursive shapes work); `:enum` maps to `enum`,
+  `:union` to `oneOf` + a `discriminator`.
+- `:model` shapes include the DB-managed columns `toJSON()` carries
+  (`id`, FKs, `@timestamps`, `@softDelete`).
+- Transforms and refinements have no executable JSON Schema equivalent
+  — they export as `description` annotations rather than being
+  silently dropped or approximated.
+
+**The payoff is rip-server integration.** A route that validates with
+a schema contributes to a generated `GET /openapi.json` automatically:
+
+```coffee
+import { post, openapi } from '@rip-lang/server'
+
+post '/signup', input: SignupInput, ->
+  # @input is the parsed (defaulted, coerced) value;
+  # 400 with structured {field, error, message} issues is automatic
+  createUser @input
+
+openapi title: 'Trust Health API', version: '1.4.0'   # optional info block
+```
+
+The `input:` option validates through `safeAsync` (so `@ensure!`
+schemas work), never re-reads the body stream, and registers
+`/openapi.json` on first use — declaration → DB → server contract →
+client codegen (any OpenAPI generator), with zero additional
+authoring.
+
+## 14. Mixins
 
 `:mixin` schemas exist to share field groups across multiple models or
 shapes. They're non-instantiable — you declare them, then other schemas
@@ -1331,7 +1949,7 @@ orthogonal to the capability axis that distinguishes the kinds.
 
 ---
 
-## 10. Schema algebra
+## 15. Schema algebra
 
 Algebra operators derive new schemas from existing ones:
 
@@ -1370,8 +1988,8 @@ Algebra operators derive new schemas from existing ones:
 
 ```coffee
 User = schema :model
-  name!    string
-  email!#  email, -> it.email.toLowerCase()
+  name!     string
+  email!    email @unique, -> it.email.toLowerCase()
   password! string
   full: ~> "#{@name} <#{@email}>"
   tagline: !> "#{@name} (active)"
@@ -1392,8 +2010,8 @@ typeof u.tagline                    # 'undefined' — !> dropped
 fields from another schema. Collisions still throw.
 
 ```coffee
-AdminUser = User.extend schema :shape
-  permissions! string[]
+AdminUser = User.extend (schema :shape
+  permissions! string[])
 ```
 
 `.sourceModel` is preserved through chained algebra, so tooling can trace
@@ -1414,7 +2032,7 @@ generators, query projectors) can walk this back to the originating
 
 ---
 
-## 11. Shadow TypeScript
+## 16. Shadow TypeScript
 
 Every named schema emits virtual TypeScript declarations that the
 language service picks up. The VS Code extension and `rip check` both
@@ -1423,42 +2041,58 @@ the box.
 
 ### What gets emitted
 
-For `:input`:
+The schema's **bare name** is the type you reference everywhere — the parsed
+value (for `:input`/`:shape`) or the hydrated instance (for `:model`) — exactly
+the way a class names both its value and its instance type. A separate
+`<Name>Data` (fields-only) type is emitted only when it differs from the bare
+name: behavior-bearing `:shape`s and every `:model`.
+
+For `:input` (no behavior — the bare name is the whole shape):
 
 ```ts
-type SignupInputValue = { email: string; password: string };
-declare const SignupInput: Schema<SignupInputValue, SignupInputValue>;
+type SignupInput = { email: string; password: string };
+declare const SignupInput: Schema<SignupInput, SignupInput>;
 ```
 
-For `:shape` (with behavior):
+For `:shape` (with behavior — `<Name>Data` = fields, bare `<Name>` = instance):
 
 ```ts
 type AddressData = { street: string; city: string };
-type AddressInstance = AddressData & {
+type Address = AddressData & {
   readonly full: unknown;
   normalize: (...args: any[]) => unknown;
 };
-declare const Address: Schema<AddressInstance, AddressData>;
+declare const Address: Schema<Address, AddressData>;
 ```
 
 For `:model`:
 
 ```ts
 type UserData = { name: string; email: string };
-type UserInstance = UserData & {
+type UserCreate = { name: string; email: string };   // create()'s input — required-no-default fields
+type User = UserData & {
   readonly identifier: unknown;
   greet: (...args: any[]) => unknown;
-  save(): Promise<UserInstance>;
-  destroy(): Promise<UserInstance>;
+  save(): Promise<User>;
+  destroy(): Promise<User>;
   ok(): boolean;
   errors(): SchemaIssue[];
   toJSON(): UserData;
-  organization(): Promise<OrganizationInstance | null>;
-  orders(): Promise<OrderInstance[]>;
+  organization(): Promise<Organization | null>;
+  orders(): Promise<Order[]>;
 };
-declare const User: ModelSchema<UserInstance, UserData>;
+declare const User: ModelSchema<User, UserData, number, UserCreate>;
 ```
 
+> **Computed/derived inference.** The `unknown` on a `~>`/`!>` member above is
+> the *published* `.d.ts` form. In the editor and `rip check`, the type emitter
+> infers each computed/derived member from its body — `full` above resolves to
+> `string`, and a `status: ~> if @done then 'Completed' else 'Pending'` resolves
+> to `"Completed" | "Pending"` — so they're usable as their real types (e.g.
+> `order.name.toUpperCase()`). A plain `.d.ts` has no runtime body to infer
+> from, so it keeps `unknown`. Methods stay `(...args: any[]) => unknown` either
+> way (their params aren't typed).
+
 For `:enum`:
 
 ```ts
@@ -1490,6 +2124,17 @@ Schema<Omit<UserData, "email">, Omit<UserData, "email">>
 Schema<Partial<UserData>, Partial<UserData>>
 ```
 
+A **named** derived schema additionally gets a bare type of its own, so a
+projection can be annotated or re-exported under a clean name:
+
+```coffee
+UserPublic = User.pick("id", "name")   # also emits a bare `type UserPublic`
+```
+
+It's emitted as `type UserPublic = ReturnType<(typeof UserPublic)['parse']>`,
+which resolves to the exact projection (`Pick<UserData, "id" | "name">`) —
+covering every operator and chain for free.
+
 ### Same-file targets type relation accessors
 
 Relation accessors get precise return types when the target is declared
@@ -1499,7 +2144,7 @@ in the same file:
 User = schema :model
   name! string
 Order = schema :model
-  @belongs_to User                   # → order.user(): Promise<UserInstance | null>
+  @belongs_to User                   # → order.user(): Promise<User | null>
 ```
 
 Cross-file relation targets degrade to `unknown` rather than emit
@@ -1508,7 +2153,7 @@ requiring virtual-module imports.
 
 ### Intrinsic declarations
 
-Three base interfaces get injected into every schema-using file's type
+Five base interfaces get injected into every schema-using file's type
 view:
 
 ```ts
@@ -1518,8 +2163,8 @@ type SchemaSafeResult<T> =
   | { ok: false; value: null; errors: SchemaIssue[] };
 
 interface Schema<Out, In = unknown> {
-  parse(data: In): Out;
-  safe(data: In): SchemaSafeResult<Out>;
+  parse(data: unknown): Out;
+  safe(data: unknown): SchemaSafeResult<Out>;
   ok(data: unknown): boolean;
   pick<K extends keyof In>(...keys: K[]): Schema<Pick<In, K>, Pick<In, K>>;
   omit<K extends keyof In>(...keys: K[]): Schema<Omit<In, K>, Omit<In, K>>;
@@ -1531,16 +2176,36 @@ interface Schema<Out, In = unknown> {
   extend<U>(other: Schema<U>): Schema<In & U, In & U>;
 }
 
-interface ModelSchema<Instance, Data = unknown> extends Schema<Instance, Data> {
-  find(id: unknown): Promise<Instance | null>;
-  findMany(ids: unknown[]): Promise<Instance[]>;
+interface SchemaQuery<T> {
+  all(): Promise<T[]>;
+  first(): Promise<T | null>;
+  count(): Promise<number>;
+  limit(n: number): SchemaQuery<T>;
+  offset(n: number): SchemaQuery<T>;
+  order(spec: string): SchemaQuery<T>;
+}
+
+interface ModelSchema<Instance, Data = unknown, Id = number, Create = Partial<Data>> extends Schema<Instance, Data> {
+  find(id: Id): Promise<Instance | null>;
+  findMany(ids: Id[]): Promise<Instance[]>;
   where(cond: Record<string, unknown> | string, ...params: unknown[]): SchemaQuery<Instance>;
+  includes(...specs: unknown[]): SchemaQuery<Instance>;
+  withDeleted(): SchemaQuery<Instance>;
+  onlyDeleted(): SchemaQuery<Instance>;
+  unscoped(): SchemaQuery<Instance>;
   all(limit?: number): Promise<Instance[]>;
   first(): Promise<Instance | null>;
   count(cond?: Record<string, unknown>): Promise<number>;
-  create(data: Partial<Data>): Promise<Instance>;
-  toSQL(options?: { dropFirst?: boolean; header?: string }): string;
+  create(data: Create): Promise<Instance>;
+  upsert(data: Create, opts: { on: unknown }): Promise<Instance>;
+  insertMany(rows: Create[]): Promise<Instance[]>;
+  toSQL(options?: { dropFirst?: boolean; header?: string; idStart?: number }): string;
 }
+
+declare const schema: {
+  transaction<T>(fn: () => T | Promise<T>): Promise<T>;
+  transaction<T>(opts: Record<string, unknown>, fn: () => T | Promise<T>): Promise<T>;
+};
 ```
 
 You don't import these — they're injected automatically when the file
@@ -1548,7 +2213,7 @@ contains any schema declaration.
 
 ---
 
-## 12. SchemaError and diagnostics
+## 17. SchemaError and diagnostics
 
 ### `SchemaError`
 
@@ -1612,13 +2277,14 @@ range or drop the conflicting pragma.
 
 ---
 
-## 13. Common mistakes
+## 18. Common mistakes
 
 These forms look right but don't work — the parser catches all of them
 with specific diagnostics.
 
 ### `name: type` instead of `name type`
 
+<!-- doctest: fail -->
 ```coffee
 # wrong — fields use a space, not a colon, between name and type
 X = schema
@@ -1631,6 +2297,7 @@ X = schema
 
 ### Bare identifier enum members
 
+<!-- doctest: fail -->
 ```coffee
 # wrong — enum members are :symbol
 R = schema :enum
@@ -1645,6 +2312,7 @@ R = schema
 
 ### `name: value` as an enum member
 
+<!-- doctest: fail -->
 ```coffee
 # wrong — use :name value
 R = schema :enum
@@ -1657,6 +2325,7 @@ R = schema
 
 ### Methods in `:input` or `:mixin`
 
+<!-- doctest: fail -->
 ```coffee
 # wrong — :input is fields-only
 X = schema :input
@@ -1671,6 +2340,7 @@ X = schema :shape
 
 ### ORM directives on `:shape`
 
+<!-- doctest: fail -->
 ```coffee
 # wrong — @timestamps is :model-only
 A = schema :shape
@@ -1686,14 +2356,14 @@ A = schema :model
 ### Calling ORM methods on a derived shape
 
 ```coffee
-UserPublic = User.omit "password"
+UserPublic = User.pick "id", "name", "email"
 
 # wrong — algebra returns :shape; :shape has no .find()
 user = UserPublic.find! 1
 
 # right — query the source model and project
 user = User.find! 1
-publicView = UserPublic.parse user.toJSON()
+view = UserPublic.parse user.toJSON()
 ```
 
 ### Treating `.ok()` as a type predicate for shapes/models
@@ -1717,34 +2387,92 @@ predicate.
 
 ---
 
-## 14. Recipes
+## 19. Recipes
 
 ### Validating HTTP input
 
+The `input:` route option validates the JSON body before the handler
+runs — a 400 with structured issues goes out automatically, the parsed
+(defaulted, coerced) value is `@input`, and the route contributes to
+the generated `GET /openapi.json`:
+
 ```coffee
-import { post, read } from '@rip-lang/server'
+import { post } from '@rip-lang/server'
 
 SignupInput = schema
   email!    email
   password! string, 8..100
-  age?      integer, 18..120
+  age?      ~integer, 18..120         # "21" on the wire → 21
 
-post '/signup' ->
-  raw = @json()                       # whatever shape the client sent
-  result = SignupInput.safe raw
-  unless result.ok
-    return error! 400, errors: result.errors
-  # result.value is the cleaned, typed payload
-  db.users.insert result.value
+post '/signup', input: SignupInput, ->
+  db.users.insert @input
   { ok: true }
 ```
 
+Validating by hand works too — `SignupInput.safe raw` returns
+`{ok, value, errors}` for cases where you need custom failure handling.
+
+### An atomic checkout
+
+`schema.transaction!` makes the multi-write atomic; the UNIQUE
+constraint is the duplicate check (no racy pre-query — the DB error
+arrives as a structured SchemaError); `afterCommit` is where effects
+that must never observe uncommitted state belong:
+
+```coffee
+Order = schema :model
+  total!     integer
+  reference! # string
+  @belongs_to User
+  @timestamps
+  afterCommit: -> queueEmail 'receipt', @id     # fires after COMMIT only
+
+placeOrder = (user, items, reference) ->
+  try
+    schema.transaction! ->
+      order = Order.create! userId: user.id, total: totalOf(items), reference: reference
+      Invoice.create! orderId: order.id, amount: order.total
+      order
+  catch err
+    if err.issues?[0]?.error is 'unique'
+      error! 'That order reference already exists', 409
+    throw err
+```
+
+A throw anywhere in the block rolls everything back — the order and
+invoice land together or not at all.
+
+### A list view without N+1
+
+`.includes` batches relations (`WHERE fk IN (…)` — one query per
+relation per level), scopes name the filters, and `@defaultScope`
+keeps cancelled rows out of every query unless `.unscoped()` opts in:
+
+```coffee
+Patient = schema :model
+  name!    string
+  active?  boolean
+  @has_many Visit
+  @scope :active, -> @where(active: true)
+  @defaultScope -> @where(archived: false)
+
+Visit = schema :model
+  reason? string
+  @belongs_to Patient
+  @belongs_to Provider
+
+# 3 queries total, regardless of row count:
+patients = Patient.active().includes(visits: :provider).all!
+for patient in patients
+  visits = patient.visits!            # memo hit — no query
+```
+
 ### A DB-backed model with relations
 
 ```coffee
 User = schema :model
   name!    string, 1..100
-  email!#  email
+  email!   email @unique
   @timestamps
   @has_many Order
 
@@ -1803,53 +2531,83 @@ Post = schema :model
   @belongs_to User
 ```
 
-### Building a public DTO from a model
+### Projecting a model to a wire view
 
 ```coffee
 User = schema :model
   name!     string
-  email!#   email
+  email!    email @unique
   password! string
   role?     string, [:user]
   @timestamps
 
-# Public projection — no password, no ORM methods.
-UserPublic = User.omit "password"
-
-publicJson = (user) -> UserPublic.parse user.toJSON()
+# Wire projection — the shape clients receive, derived from the one model.
+# Use `pick` (an allowlist): a field added to the model later can't leak to
+# clients by default — `password` is simply never selected. Prefer this over
+# `omit` for anything crossing a trust boundary; `omit` fails open.
+UserPublic = User.pick "id", "name", "email", "role"
 
 get '/users/:id' ->
   id = read 'id', 'id!'
   user = User.find! id
   return error! 404 unless user
-  { user: publicJson user }
+  { user: UserPublic.parse user.toJSON() }
 ```
 
-### Writing a migration script
+### Evolving the schema (week 2 and beyond)
+
+Change the models, then let the differ write the migration. A rename is
+declared, not guessed:
 
 ```coffee
-# scripts/migrate.rip
-import { User, Order, OrderItem } from '../api/models.rip'
-import { sql, setup } from '../api/db.rip'
+# models.rip — week 2: rename a column, add a field, add a table
+User = schema :model
+  fullName! string, 1..100, {was: "name"}   # rename annotation
+  email!    email @unique
+  phone?    ~:phone                          # new column
+  @timestamps
 
-setup!                                   # start DB if needed
+AuditLog = schema :model                     # new table
+  action! string
+  @belongs_to User
+  @timestamps
+```
 
-# Emit DDL in dependency order
-ddl = [
-  User.toSQL()
-  Order.toSQL()       # references User
-  OrderItem.toSQL()   # references Order
-].join('\n\n')
+```text
+rip schema status models.rip          # review the classified plan
+rip schema make week2 models.rip      # writes migrations/0002_week2.sql
+rip schema migrate models.rip         # applies it, records the checksum
+```
+
+Lossy steps (type changes, SET NOT NULL) need `--allow-lossy`;
+DROPs need `--allow-destructive`; steps DuckDB refuses on
+FK-referenced tables are marked `blocked` and never auto-applied.
+Once the migration lands, delete the `{was: …}` annotation.
+
+For greenfield scripts, `.toSQL()` still works standalone — it never
+calls the adapter, so DDL can be emitted before the database exists.
+
+### The wire vocabulary (`~:name`)
 
-for stmt in ddl.split ';'
-  stmt = stmt.trim()
-  sql! stmt + ';' if stmt
+Every `read()` validator doubles as a schema coercer — one
+normalization vocabulary for route params and schema fields. It lives
+in `@rip-lang/validate` (browser-safe), loads with `@rip-lang/server`
+on the server, and a side-effect `import '@rip-lang/validate'` brings
+it to client-side parsing:
 
-p "[migrate] schema created"
+```coffee
+Patient = schema :model
+  chart!  ~:id, 1..99999     # "42" → 42, range-checked
+  ssn?    ~:ssn              # "123-45-6789" → "123456789"
+  phone?  ~:phone            # "8016542000" → "(801) 654-2000"
+  state?  ~:state            # "ut" → "UT"
+  dob?    ~:date             # normalized "YYYY-MM-DD"
+  amount? ~:money            # "$1,234.50" → 1234.5
 ```
 
-Because `.toSQL()` doesn't call the adapter, migration scripts work
-before the database exists or before the ORM is wired.
+Custom validators registered with `registerValidator` (from
+`@rip-lang/validate`) or `schema.registerCoercer` (anywhere) join the
+vocabulary automatically.
 
 ### Composing nested shapes
 
@@ -1884,11 +2642,11 @@ else
 ```
 
 Registered `:shape` / `:input` / `:model` names can all be referenced
-as field types — see §17 for resolution rules.
+as field types — see §22 for resolution rules.
 
 ---
 
-## 15. What's not here yet
+## 20. What's not here yet
 
 Rip Schema covers a large surface area with one keyword, but it deliberately
 does not yet cover every feature you might find across the union of Zod,
@@ -1898,55 +2656,32 @@ language.
 
 ### Validator features not yet in
 
-- **Full discriminated-union schemas** — `schema.union(A, B)` with a
-  `:discriminator` key that dispatches to the matching constituent.
-  String-literal unions in the type slot (`"a" | "b"`) are in;
-  schema-constituent unions over arbitrary shapes are not. Today you
-  express cross-shape alternation by running multiple `.safe()` calls.
-- **Issue paths** — `@ensure` issues today use `field: ''` (the whole
-  object). Per-field attribution (`field: 'email'`) on a refinement
-  isn't supported; write the field-specific rule as a constraint or
-  inline transform instead.
-- **Coercion built-in types** — `coerce.number`, `coerce.date`, etc.
-  as dedicated type names. Today a field transform handles the same
-  case (`shippedAt? date, -> new Date(it.shippedAt)`); coerce types
-  would just be a stdlib convenience over the transform mechanism.
-- **Async refinements** — `@ensure` predicates are sync. Async
-  refinements (that await a database or network check) would need
-  either a separate `@ensureAsync` directive or a full async variant
-  of the whole validate pipeline.
+- **Union algebra** — `.pick`/`.omit`/etc. on a `:union` throws; the
+  semantics (distribute? intersect?) have no obviously-right answer.
+  Derive from a constituent instead.
+- **Untagged unions** — deliberate non-goal: O(n) dispatch and
+  incoherent error messages. Use `@on :field`.
 
 ### ORM features not yet in
 
-- **Transactions** — `schema.transaction -> ...` with rollback semantics.
-  Today each ORM call is its own statement.
-- **Eager loading** — `User.where(...).includes(:orders)`. Today relations
-  are lazy (`user.orders!` on demand).
-- **Query scopes** — named, composable `Model.scope(name, ...)` reusable
-  across `.where` chains.
-- **Soft deletes** — a built-in `@soft_delete` directive with automatic
-  query-filter application. Today you add a `deleted_at` field yourself.
+- **FK-cluster rebuilds** — DuckDB freezes FK-referenced tables for most
+  ALTERs; the differ classifies those steps `blocked` and leaves the
+  rebuild (recreate referencing tables around the change) to the human.
+  Generating the rebuild automatically is the next migration item.
 - **Polymorphic associations** — `@belongs_to :commentable, polymorphic: true`.
 - **Non-SQL adapters** — Mongo, Redis, Elasticsearch. The adapter contract
   is `query(sql, params)`, which assumes SQL.
+- **Savepoint-backed nested transactions** — nested `transaction!`
+  joins the outer transaction. DuckDB has no `SAVEPOINT`, so
+  independent nested units aren't expressible on the primary backend.
 
 ### Type features not yet in
 
-- **Recursive schemas** — `Tree = schema :shape` that references itself
-  in a nested field. Compiler allows it; shadow TS currently emits
-  `unknown` for the recursive branch.
 - **Generic schemas** — `Paginated<T> = schema :shape ...` parameterized
   by another schema. Today you define a concrete `PaginatedUser` per type.
 - **Branded / nominal types** — `UserId = schema :input` whose parsed
   value is nominally distinct from `number`.
 
-### Deferred by design
-
-- **Per-schema adapters** — every schema currently uses the one global
-  adapter. Multi-database setups require swapping before the call.
-- **JSON Schema / OpenAPI export** — `User.toJSONSchema()`. The
-  four-layer runtime makes this feasible; no canonical emitter exists yet.
-
 None of these are architectural impossibilities. Each is a conscious pause
 while the core shape of the feature settles. If one of these is blocking
 you, file a proposal — the sidecar design makes most of them additive.
@@ -1955,35 +2690,43 @@ you, file a proposal — the sidecar design makes most of them additive.
 
 # Part II — Reference
 
-## 16. Capability matrix
+## 21. Capability matrix
 
 What each kind's body can contain:
 
 | Feature                                 | `:input` | `:shape` | `:enum`  | `:mixin` | `:model` |
 | --------------------------------------- | -------- | -------- | -------- | -------- | -------- |
 | Fields (`name` with optional type)      | ✓        | ✓        | —        | ✓        | ✓        |
-| Literal-union type (`"a" \| "b"`)       | ✓        | ✓        | —        | ✓        | ✓        |
+| Literal-union type (`"a" \| "b"`, single = constant) | ✓ | ✓   | —        | ✓        | ✓        |
+| Coercion (`~integer`, `~:ssn`)          | ✓        | ✓        | —        | ✓        | ✓        |
 | Range / regex / default / attrs         | ✓        | ✓        | —        | ✓        | ✓        |
 | Inline transforms (`name, -> fn(it)`)   | ✓        | ✓        | —        | —        | ✓        |
 | `@mixin` directive                      | ✓        | ✓        | —        | ✓        | ✓        |
-| `@ensure` refinement                    | ✓        | ✓        | —        | —        | ✓        |
-| Other directives                        | —        | —        | —        | —        | ✓        |
-| Methods (`name: -> body`)               | —        | ✓        | —        | —        | ✓        |
+| `@ensure` / `@ensure!` refinement       | ✓        | ✓        | —        | —        | ✓        |
+| Other directives (`@timestamps`, `@scope`, …) | — | —        | —        | —        | ✓        |
+| Methods (`name: (params) -> body`)      | —        | ✓        | —        | —        | ✓        |
 | Computed getter (`name: ~> body`)       | —        | ✓        | —        | —        | ✓        |
-| Eager-derived field (`name: !> body`)   | —        | ✓        | —        | —        | ✓        |
-| Hooks (by known name)                   | —        | methods  | —        | —        | ✓        |
+| Eager-derived field (`name: !> body`)   | ✓        | ✓        | —        | —        | ✓        |
+| Hooks (by known name, 12 total)         | —        | methods  | —        | —        | ✓        |
 | Enum members (`:symbol`)                | —        | —        | ✓        | —        | —        |
 | Algebra (`.pick` etc.)                  | ✓ → shape | ✓ → shape | —       | —        | ✓ → shape |
-| ORM (`.find`, `.create`)                | —        | —        | —        | —        | ✓        |
-| `.parse` / `.safe` / `.ok`              | ✓        | ✓        | ✓        | —        | ✓        |
-| `.toSQL()`                              | —        | —        | —        | —        | ✓        |
+| ORM (`.find`, `.create`, transactions, scopes) | — | —       | —        | —        | ✓        |
+| `.parse` / `.safe` / `.ok` (+ async trio) | ✓      | ✓        | ✓        | —        | ✓        |
+| `.toJSONSchema()`                       | ✓        | ✓        | ✓        | ✓        | ✓        |
+| `.toSQL()` / `rip schema make`          | —        | —        | —        | —        | ✓        |
 
 "methods" in the `:shape` / Hooks row means: hook-named functions are
 accepted, but they're just methods with no lifecycle binding.
 
+`:union` is body-incompatible with everything above — its body is
+exactly one `@on :field` plus 2+ bare constituent names. It exposes
+`.parse` / `.safe` / `.ok` (and the async trio) plus `.toJSONSchema()`
+(`oneOf` + discriminator) by delegating to the matched constituent;
+algebra and ORM surface throw.
+
 ---
 
-## 17. Field types
+## 22. Field types
 
 Built-in type names and their runtime / SQL / TypeScript mappings:
 
@@ -2043,25 +2786,36 @@ user-defined enums or shapes compose incrementally.
 
 ---
 
-## 18. Directives
+## 23. Directives
 
 ### For any fielded kind
 
 | Directive       | Effect                                                            |
 | --------------- | ----------------------------------------------------------------- |
 | `@mixin Name`   | Pull in the fields of mixin `Name` at Layer 2 normalization       |
-| `@ensure "msg", (x) -> pred` | Cross-field refinement — see [§5](#refinement-ensure). Allowed on `:input` / `:shape` / `:model`; rejected on `:enum` / `:mixin`. |
+| `@ensure "msg"[, :field], (x) -> pred` | Cross-field refinement, optionally attributed to a field — see [§5](#refinement-ensure). Allowed on `:input` / `:shape` / `:model`; rejected on `:enum` / `:mixin`. |
+| `@ensure! "msg"[, :field], (x) -> pred` | ASYNC refinement — the schema becomes async-validating (`parseAsync!` / `safeAsync!` / `okAsync!`) |
+
+### `:union`-only
+
+| Directive   | Effect                                                          |
+| ----------- | --------------------------------------------------------------- |
+| `@on :field` | Names the discriminator field (required, exactly once). Constituents follow as bare schema names, one per line |
 
 ### `:model`-only
 
 | Directive                     | Effect                                                              |
 | ----------------------------- | ------------------------------------------------------------------- |
 | `@timestamps`                 | Adds `created_at` + `updated_at` columns with `CURRENT_TIMESTAMP` defaults |
-| `@softDelete`                 | Adds `deleted_at` column; `.destroy()` sets `deleted_at = now()` instead of DELETE |
+| `@softDelete`                 | Adds `deleted_at` column; `.destroy()` sets `deleted_at = now()` instead of DELETE. Queries (`find`, `where`, `all`, `first`, `count`) implicitly filter `deleted_at IS NULL`; escape hatches: `.withDeleted()`, `.onlyDeleted()`, `inst.restore!`, `inst.destroy! hard: true` |
 | `@index [a, b, c]`            | Composite index on the listed columns                               |
 | `@index column`               | Single-column index (same as `@index [column]`)                     |
-| `@index [...] #`              | Unique index                                                        |
+| `@unique [a, b]`              | Composite unique constraint on the listed columns                   |
+| `@unique :column`             | Single-column unique (or inline on the field: `column! type @unique`) |
 | `@idStart N`                  | Seed value for the auto-id sequence in `.toSQL()` output (default `1`). Overridden per-call by `toSQL(idStart: N)`. |
+| `@scope :name, -> body`       | Named composable query scope — `this` is the builder; also `@scope :name, (args) -> body`. Installed on the model and the builder |
+| `@defaultScope -> body`       | Applied to every query unless `.unscoped()` is called. At most one per model |
+| `@tableWas old_name`          | Table-rename annotation for the schema differ — `rip schema make` emits `RENAME TO` instead of `DROP + CREATE`. Removable once the migration lands |
 | `@belongs_to Target`          | FK column `target_id` referencing `targets.id`, NOT NULL            |
 | `@belongs_to Target?`         | Same, nullable                                                      |
 | `@has_one Target`             | Accessor `target()` returning one                                   |
@@ -2069,10 +2823,10 @@ user-defined enums or shapes compose incrementally.
 
 ---
 
-## 19. Hook reference
+## 24. Hook reference
 
-Ten recognized hook names. On `:model` they bind into the lifecycle; on
-other kinds they're plain methods.
+Twelve recognized hook names. On `:model` they bind into the lifecycle;
+on other kinds they're plain methods.
 
 | Hook name          | When it runs                                             |
 | ------------------ | -------------------------------------------------------- |
@@ -2086,17 +2840,20 @@ other kinds they're plain methods.
 | `afterSave`        | After INSERT or UPDATE                                   |
 | `beforeDestroy`    | Before DELETE (or soft-delete UPDATE)                    |
 | `afterDestroy`     | After DELETE                                             |
+| `afterCommit`      | After the outermost transaction commits — or immediately after save/destroy when no transaction is open |
+| `afterRollback`    | After rollback, for each instance saved/destroyed inside the rolled-back transaction |
 
 Throwing from any hook aborts the operation and the exception propagates
 to the caller.
 
 ---
 
-## 20. Constraints
+## 25. Constraints
 
 Each constraint on a field line is self-identifying by its token
 shape. Multiple constraints combine on one field, separated by commas:
 
+<!-- doctest: skip -->
 ```coffee
 name[!|?|#]  [type]  [constraint]  [constraint]  …
 ```
@@ -2112,16 +2869,17 @@ a string-literal union; the **constraint** forms live after the type:
 | `min..max`           | constraint | Size (string/array length) or value range (numeric)    |
 | `[value]`            | constraint | Default value (single literal in brackets)             |
 | `/regex/`            | constraint | Pattern constraint (bare regex literal)                |
-| `{key: value}`       | constraint | Attrs (unique, index, etc.)                            |
+| `{key: value}`       | constraint | Attrs. Known keys: `{was: "old_name"}` — column-rename annotation for the schema differ |
 
 ```coffee
-password!  string, 8..100                     # length range
-age?       integer, 0..120                    # value range
-role?      string, ["guest"]                  # default
-zip!       string, /^\d{5}$/                  # regex pattern
-status?    string, 3..20, ["pending"]         # range AND default
-sex?       "M" | "F" | "U"                    # literal union
-status?    "draft" | "active" | "done", [:draft]  # union + default
+Example = schema
+  password!  string, 8..100                     # length range
+  age?       integer, 0..120                    # value range
+  role?      string, ["guest"]                  # default
+  zip!       string, /^\d{5}$/                  # regex pattern
+  status?    string, 3..20, ["pending"]         # range AND default
+  sex?       "M" | "F" | "U"                    # literal union
+  phase?     "draft" | "active" | "done", [:draft]  # union + default
 ```
 
 ### Range semantics by field type
@@ -2139,9 +2897,10 @@ status?    "draft" | "active" | "done", [:draft]  # union + default
 Use `n..n` for "exactly N":
 
 ```coffee
-sex?    1..1                     # single-character sex code
-npi!    10..10                   # NPI is exactly 10 digits
-code!   6..6                     # fixed-length code
+Fixed = schema
+  sex?    1..1                     # single-character sex code
+  npi!    10..10                   # NPI is exactly 10 digits
+  code!   6..6                     # fixed-length code
 ```
 
 Reads as "between N and N" which collapses to "exactly N."
@@ -2165,14 +2924,20 @@ redundant `1` that the `!` modifier already implies:
 
 ```coffee
 # These pairs mean the same thing:
-firstName!  1..50           firstName!  ..50
-name!       1..100          name!       ..100
-email!      1..320          email!      ..320
-
-# But explicit always wins:
-admin!      0..50           # explicit min=0 stays (rare: required but empty allowed)
-age!        0..120          # explicit min=0 stays (newborns are zero)
-score!      0..100          # explicit min=0 stays (test score can be zero)
+Explicit = schema
+  firstName!  1..50
+  name!       1..100
+  email!      1..320
+Sugar = schema
+  firstName!  ..50
+  name!       ..100
+  email!      ..320
+
+# But an explicit min always wins:
+Zeroes = schema
+  admin!      0..50            # explicit min=0 stays (rare: required but empty allowed)
+  age!        0..120           # explicit min=0 stays (newborns are zero)
+  score!      0..100           # explicit min=0 stays (test score can be zero)
 ```
 
 If the sugar would produce an impossible constraint (`! ..0` →
@@ -2205,9 +2970,10 @@ rejected at parse time with a clear error.
 Trailing comma + indent continues the line:
 
 ```coffee
-password! string,
-  8..100,
-  /[A-Z]/
+Account = schema
+  password! string,
+    8..100,
+    /[A-Z]/
 ```
 
 This is the same rule Rip applies to any trailing-comma continuation.
@@ -2236,7 +3002,7 @@ schema.defaultMaxString = 500
 
 User = schema :model
   name!                         # → {min: 1, max: 500}  (sugar + pragma)
-  email!#    email              # → {max: 500}
+  email!     email @unique      # → {max: 500}
   code?                         # → {max: 500}
   password!  8..200             # → {min: 8, max: 200}  (explicit wins)
   bio?       text               # → no constraint       (text opts out)
@@ -2275,16 +3041,16 @@ without changing the scanner shape.
 
 ---
 
-## 21. Relations
+## 26. Relations
 
 ### Directive → accessor → return type
 
 | Directive                   | Accessor name         | Returns                                  |
 | --------------------------- | --------------------- | ---------------------------------------- |
-| `@belongs_to User`          | `user()`              | `Promise<UserInstance \| null>`          |
-| `@belongs_to User?`         | `user()`              | `Promise<UserInstance \| null>` + nullable FK |
-| `@has_one Profile`          | `profile()`           | `Promise<ProfileInstance \| null>`       |
-| `@has_many Order`           | `orders()`            | `Promise<OrderInstance[]>`               |
+| `@belongs_to User`          | `user()`              | `Promise<User \| null>`          |
+| `@belongs_to User?`         | `user()`              | `Promise<User \| null>` + nullable FK |
+| `@has_one Profile`          | `profile()`           | `Promise<Profile \| null>`       |
+| `@has_many Order`           | `orders()`            | `Promise<Order[]>`               |
 
 Accessor names:
 
@@ -2306,11 +3072,18 @@ that declares the target (or the model file itself) are enough to make
 resolution succeed. Unresolved targets throw a runtime error with the
 name and the caller's schema name included.
 
+### Memoization
+
+Accessor results memoize per instance: the second `user.orders!` call
+resolves from cache with no query. Eager loading (`.includes`) fills
+the same memo, which is why preloaded relations are free. Pass
+`{reload: true}` to bust the memo and re-query.
+
 ---
 
-## 22. Design invariants
+## 27. Design invariants
 
-Twelve rules that define how Rip Schema behaves. Worth keeping in mind
+Sixteen rules that define how Rip Schema behaves. Worth keeping in mind
 when debugging or extending:
 
 1. **Default kind is `:input`.** `schema` with no marker and a
@@ -2333,10 +3106,15 @@ when debugging or extending:
    property of the field, not the instance.
 6. **`:mixin` is non-instantiable.** Mixins declare fields for reuse —
    they don't have a runtime identity of their own.
-7. **Schema names are global.** Relations and `@mixin` references
-   resolve by bare name through a process-global registry. Two models
-   with the same name in different modules produce the "last loaded
-   wins" behavior — avoid it.
+7. **Schema names are global, and collisions fail loudly.** Relations
+   and `@mixin` references resolve by bare name through a
+   process-global registry. Registering a name that already exists
+   with a *different* definition throws at registration time;
+   structurally identical re-registration (the same module arriving
+   twice) rebinds silently. `__SchemaRegistry.replace = true` restores
+   last-loaded-wins for dev/HMR reload; `__SchemaRegistry.scope(fn)`
+   runs `fn` against a fresh registry and restores the parent (test
+   isolation).
 8. **Default field type is `string`.** Omitting the type slot is
    legal; `name!` means "required string". Explicit types
    (`integer`, `email`, `"M" | "F"`, etc.) are needed only when
@@ -2356,20 +3134,46 @@ when debugging or extending:
     result as an own enumerable property. Mutating a dependency
     afterward does **not** update the derived value — it stays stale
     by design. Use `~>` for always-current derivations.
-12. **Refinements are schema-level, not field-level.** `@ensure`
-    predicates run after per-field validation succeeds, once per
-    parse, against the whole defaulted and typed object. They fail
-    with a declared message that ships verbatim to the caller;
-    thrown exceptions inside a predicate count as failure, not
-    error. Refinements are skipped on DB hydrate (trusted data)
-    and dropped by every algebra op (structural derivation never
-    carries non-structural invariants).
+12. **Refinements are schema-level, not field-level by default.**
+    `@ensure` predicates run after per-field validation succeeds, once
+    per parse, against the whole defaulted and typed object. An
+    optional `:field` symbol attributes the failure to one input;
+    without it the issue is schema-wide (`field: ''`). They fail with
+    a declared message that ships verbatim to the caller; thrown
+    exceptions inside a predicate count as failure, not error.
+    Refinements are skipped on DB hydrate (trusted data) and dropped
+    by every algebra op (structural derivation never carries
+    non-structural invariants).
+13. **Coercion is field semantics.** `~type` / `~:name` converts the
+    wire value in pipeline step 1, before defaults and validation —
+    constraints always see the coerced value. Like transforms,
+    coercion survives algebra and is skipped on hydrate. A failed
+    coercion is `{error: 'coerce'}`, distinct from `{error: 'type'}`;
+    an unregistered `~:name` is a loud config error, never a
+    validation failure.
+14. **Async-validating schemas refuse the sync API.** One `@ensure!`
+    makes the whole schema async-validating: `.parse`/`.safe`/`.ok`
+    throw immediately ("use parseAsync!/safeAsync!/okAsync!") rather
+    than sometimes-returning a promise. Sync refinements run first;
+    async ones run concurrently; issues collect in declaration order.
+15. **Unions dispatch, never merge.** `:union` resolves the
+    discriminator to exactly one constituent and delegates — the
+    result is that constituent's instance. Discriminator values must
+    be disjoint string literals (checked at first parse, lazily).
+    Algebra on a union throws; distribute-vs-intersect has no
+    obviously-right answer, so v1 declines to guess.
+16. **The default scope applies at terminal time.** `@defaultScope`
+    composes into the query when a terminal (`all`/`first`/`count`/
+    `updateAll`/`deleteAll`) runs — so `.unscoped()` works anywhere in
+    the chain and the default's clauses never double-apply. `find`
+    routes through the builder, so the default scope and the
+    `@softDelete` filter apply to it uniformly.
 
 ---
 
 # Part III — Architecture
 
-## 23. Runtime architecture
+## 28. Runtime architecture
 
 Each schema goes through four layers. Each layer is built lazily on first
 need, and the caches are independent.
@@ -2465,19 +3269,29 @@ this layer.
 Built on first `.find/.create/.save/.destroy/.where` call on a `:model`.
 Wires:
 
-- the query builder
-- save / destroy flows (including hook lifecycle)
-- relation accessors on the generated class
-- instance methods (`save`, `destroy`, `ok`, `errors`, `toJSON`)
+- the query builder (with scope methods, default-scope composition,
+  soft-delete filtering, and `.includes` eager-load resolution)
+- save / destroy / restore flows (including the 12-hook lifecycle and
+  constraint-violation translation)
+- relation accessors on the generated class (with per-instance
+  memoization)
+- instance methods (`save`, `destroy`, `restore`, `ok`, `errors`,
+  `toJSON`)
+- transaction routing — every statement checks the AsyncLocalStorage
+  slot for the schema's adapter and joins an ambient
+  `schema.transaction!` automatically
 
 Requires a configured adapter before first use.
 
 ### Layer 4b — DDL plan
 
-Built on first `.toSQL()` call. Emits the `CREATE SEQUENCE` /
-`CREATE TABLE` / indexes + foreign keys for one model. Independent of
-Layer 4a — a migration script that never touches the ORM builds this
-layer only.
+Built on first `.toSQL()` call. A canonical `_tableSpec` (columns,
+indexes, FKs, sequence) renders to `CREATE SEQUENCE` / `CREATE TABLE` /
+indexes + foreign keys for one model. The same spec is what the
+migration differ (`rip schema status/make/migrate`) compares against
+the introspected live database — DDL emission and diffing can't drift
+apart because they share one source. Independent of Layer 4a — a
+migration script that never touches the ORM builds this layer only.
 
 ### Lazy is the point
 
@@ -2491,20 +3305,26 @@ don't have to.
 
 `__SchemaRegistry` holds every named `:model` and `:mixin` by bare name.
 Registration happens in the `__SchemaDef` constructor — *importing a
-file that declares named schemas activates them*. Tests can call
-`__SchemaRegistry.reset()` between runs to avoid cross-test leakage.
+file that declares named schemas activates them*. Re-declaring a name
+with an identical structure is an idempotent no-op (double-import
+safe); a *different* structure throws unless `replace` mode is on (HMR
+and test runners opt in). Tests can also use `__SchemaRegistry.scope()`
+for isolated registries or `.reset()` between runs.
 
 ### The adapter
 
-One function: `adapter.query(sql, params) → {columns, data, rows}`. The
-default adapter talks to rip-db via `fetch`. Custom adapters (for
-tests, in-memory mocks, alternate SQL backends) install with
-`globalThis.__ripSchema.__schemaSetAdapter`. Every ORM method funnels
-through this interface.
+Contract v2: `query(sql, params) → {columns, data, rowCount}` is the
+one required method; `begin(options) → TxHandle` and a truthful
+`capabilities` object are optional and feature-detected (§11). The
+default adapter talks to a duckdb-harbor instance via `fetch`; named
+adapters from `schema.connect(...)` bind individual models elsewhere
+(`on:`). Custom adapters (for tests, in-memory mocks, alternate SQL
+backends) install with `globalThis.__ripSchema.__schemaSetAdapter`.
+Every ORM method funnels through this interface.
 
 ---
 
-## 24. Compiler integration
+## 29. Compiler integration
 
 The schema keyword is implemented as a compiler sidecar in
 `src/schema/schema.js`, alongside the existing type and component sidecars.
@@ -2570,21 +3390,41 @@ its footprint in the main compiler is small.
 
 ---
 
-## 25. FAQ
+## 30. FAQ
 
 **Why not just use Zod?**
-Zod gives you the validator. It doesn't give you the ORM, the DDL, the
-class, the computed getters, or the derived DTOs. Rip Schema is all of
-that from one declaration. If you only need the validator, `schema :input`
-is the equivalent surface — and the derived shadow TS is indistinguishable
-from `z.infer<>`.
+Zod gives you the validator. It doesn't give you the ORM, the
+transactions, the migrations, the class, the computed getters, the
+derived DTOs, or the OpenAPI document. Rip Schema is all of that from
+one declaration. The validator alone now covers Zod's daily surface
+too: strict coercion (`~integer`, `~:phone`), discriminated unions
+(`schema :union`), sync and async refinements (`@ensure` /
+`@ensure!`), and `safeParse`-style structured results — with shadow TS
+indistinguishable from `z.infer<>` and no codegen step.
 
 **Is this a full ORM replacement for Prisma / Drizzle?**
-For the common CRUD shape — yes. `find`, `where`, `create`, `save`,
-`destroy`, relations, migrations, hooks, lifecycle callbacks, and
-validations are all present and running in production apps. For
-transactions, eager loading, scopes, and soft deletes — not yet; see
-§15.
+For the production shape — yes. `find`, `where`, `create`, `save`,
+`destroy`, relations, hooks, validations, transactions
+(`schema.transaction!`), eager loading (`.includes`), query scopes
+(`@scope` / `@defaultScope`), soft deletes, upsert/batch writes,
+structured constraint-violation errors, DDL, **and migration diffing**
+(`rip schema status / make / migrate` — declared models vs the live
+database, with checksummed history and rename annotations). The
+remaining gaps are listed honestly in §20.
+
+**How do transactions propagate without passing a handle around?**
+AsyncLocalStorage. `schema.transaction! ->` pins a connection and binds
+it to the async context; every ORM call inside the block routes through
+it automatically — model code is unchanged. Nested calls join the outer
+transaction; parallel transactions get independent contexts; per-schema
+adapters get independent slots. See §9.
+
+**What's the difference between `"a" | "b"` and `schema :union`?**
+The literal union is a FIELD type — one value constrained to a set of
+strings. `:union` is a SCHEMA kind — whole objects dispatched to
+different constituent schemas by a discriminator field (`@on :kind`).
+A single literal (`kind! "click"`) is the constant field that tags a
+constituent.
 
 **Does the runtime belong to `schema.js` or is it loaded separately?**
 It's inlined. When a file uses `schema`, the compiler injects a small
@@ -2634,7 +3474,7 @@ Yes. They compose: `User.omit("password").pick("name", "email").partial()`
 produces a `:shape` with the intersection of the three operations.
 
 **How do I express cross-field rules — "passwords must match", "end after start"?**
-Use `@ensure`. See [§5](#refinement-ensure) and the summary in [§22](#22-design-invariants)
+Use `@ensure`. See [§5](#refinement-ensure) and the summary in [§27](#27-design-invariants)
 invariant 12. Messages are required, predicates are plain Rip fns,
 thrown exceptions count as failure, and all refinements run every time
 (no short-circuit between refinements).