@aotter/mantle 0.2.0-alpha.9 → 0.2.1-alpha.1

package/docs/handbook/reference/authorization.md

@@ -38,7 +38,7 @@ Values come from the verified Better Auth user record. Declare stored fields wit
 
 SQL cannot reference caller values: `auth.user()` fails with `USER_REF_SCOPE_ONLY`, and `auth.hasRole()` / `auth.role()` with `AUTH_ROLE_REMOVED`. Names are literals; Better Auth core fields and names beginning `mantle` are reserved.
 
-Values come from the original frozen Caller, which holds identity in a private WeakMap. Anonymous and copied/unbranded callers have no roles or user fields. Values are validated and frozen: finite numbers; strings of 1–256 UTF-8 bytes without NUL or lone surrogates; arrays of at most 64 items with duplicates removed, only for multi-valued fields. `{ all: true }` is the typed "every value" state of one field; storing it requires a Better Auth additional field of type `json`. Unknown user fields are discarded. A missing or empty value is refused before SQL runs (`UNAUTHENTICATED` for anonymous callers, otherwise `AUTH_DENIED`); it never matches every row. Never mint verified users from request data. Resolve credentials before constructing an identity, and pass the original Caller to generated operations.
+Values come from the original frozen Caller, which holds identity in a private WeakMap. Anonymous and copied/unbranded callers have no roles or user fields. Values are validated and frozen: finite numbers, integers when the field scopes an `integer` column; strings of 1–256 UTF-8 bytes without NUL or lone surrogates; arrays of at most 64 items with duplicates removed, only for multi-valued fields. `{ all: true }` is the typed "every value" state of one field; storing it requires a Better Auth additional field of type `json`. Unknown user fields are discarded. A missing or empty value is refused before SQL runs (`UNAUTHENTICATED` for anonymous callers, otherwise `AUTH_DENIED`); it never matches every row. Never mint verified users from request data. Resolve credentials before constructing an identity, and pass the original Caller to generated operations.
 
 ## Gateway mode
 
@@ -52,6 +52,8 @@ Snapshots may read only: SQL writes, Store/Admin mutations, publishing transitio
 
 Pins use [describe](describe.md)'s `_meta.id`: `rest:<METHOD> <path>`, `admin:<METHOD> <path template>`, or the View/Procedure target for MCP and web. The route checks `target` and the generated target hash before execution: mismatches return 412 `TARGET_MISMATCH` or `TARGET_HASH_MISMATCH`. The generated `access-targets.ts` map loads only for gateway requests. Manually composed boundaries can supply an `accessTargets` loader returning the same metadata.
 
+A gateway computes the pin from the request with [`matchTarget(describe, request)`](describe.md#matching-a-request-to-its-target), which applies the routers' own path normalisation, `HEAD` handling, Admin mount and precedence to the saved `mantle describe` JSON. It returns the target's `_meta`, including `targetHash` and the `readOnly` flag that the freshness rule reads, or `null` when the application serves no such route or tool.
+
 MCP host callers may use `initialize` and `tools/call` of their pinned tool; batches stay refused and `tools/list` returns 403 because the host provides its catalogue.
 
 `dryRun: true` runs target/hash checks, input validation, generated caller checks, `authorize` and freshness, without SQL or side effects. It returns 200 `{ dryRun: true, event }`; MCP carries this result in the SDK tool response. Ref handlers, custom guards, uploads and opaque work return 412 `DRY_RUN_UNSUPPORTED`. Dry runs validate authority and input; they do not verify database state, row existence or OCC conflicts.

package/docs/handbook/reference/describe.md

@@ -46,6 +46,48 @@ Each target’s `_meta` contains:
 Descriptions contain no SQL or rows. They describe declarations; application
 router additions and optional module mounting remain application-owned.
 
+## Matching a request to its target
+
+`matchTarget(describe, request)` from `@aotter/mantle/describe` returns the
+`_meta` of the target that the generated routers select for a request, or
+`null` when they serve none. It reads only the JSON this command prints: it
+imports no application, opens no database and makes no network call, so a
+gateway can compute `props.mantle.target` and `targetHash` before forwarding.
+
+```ts
+import { matchTarget } from "@aotter/mantle/describe";
+const url = new URL(request.url);
+matchTarget(describe, { surface: "rest", method: request.method, path: url.pathname });   // rest:GET /api/views/orders
+matchTarget(describe, { surface: "admin", method: request.method, path: url.pathname });  // admin:GET /entries/:id
+matchTarget(describe, { surface: "mcp", tool: params.name, path: url.pathname });         // view:orders, admin:tool:<name>
+```
+
+The matcher compiles describe ids with the routers' own pattern grammar and
+precedence, and a conformance test checks it against the generated REST, MCP
+and Admin routers for every route of the example apps:
+
+- Paths are the URL pathname. Each segment is percent-decoded and re-encoded,
+  so `/api/views/%6Frders` matches `/api/views/orders`; a malformed escape
+  matches nothing. One trailing slash is optional. Repeated slashes and a
+  different letter case do not match.
+- Methods are compared as `Request.method` reports them. `HEAD` selects a
+  public View's `GET` route; Admin and Procedure routes do not serve `HEAD`.
+- REST precedence is the generated router's order (see
+  [http Triggers](trigger.md#route-precedence)). Admin precedence is Admin's
+  declared route order, so `/entries/export` wins over `/entries/:id`.
+- Admin paths start with `/admin/api`, where Admin mounts its API. Admin ids
+  are relative to it.
+- MCP matches the `tools/call` name. Pass the `/mcp` or `/mcp/admin` path to
+  limit the match to that endpoint's tools. Without a path, a name that the two
+  endpoints map to different targets matches nothing.
+
+Media tools (`admin:tool:<name>`) and the optional Admin developer and
+statistics routes match even when the application does not mount them; the
+application then answers `NOT_FOUND`. Routes and tools the application adds
+itself, including Admin `routes` it passes to `admin()`, are not in describe and
+return `null`. Web and site pages (pinned by `view:<name>`) and auth routes are
+outside `matchTarget`.
+
 Diff records contain `id`, `field`, `direction` and optional `before`/`after`.
 Removing a scope or restrict term widens access; adding one narrows it.
 Reading another Schema, dropping requirements, adding surfaces or Triggers,

package/docs/handbook/reference/diagnostics.md

@@ -8,14 +8,28 @@ Bare queries preserve native errors except required conflict/uncertain-write cla
 | --- | --- | --- |
 | INPUT_VALIDATION_FAILED | 400 | Invalid external input, paging or Store operation |
 | UNAUTHENTICATED | 401 | Caller lacks required authenticated authority |
-| AUTH_DENIED | 403 | Predicate, role or session-origin refusal |
+| AUTH_DENIED | 403 | Predicate, role or session-origin refusal; a generic Admin write to a read-only Schema |
 | NOT_FOUND | 404 | Missing or excluded resource |
 | METHOD_NOT_ALLOWED | 405 | Path exists for another method |
-| CONFLICT | 409 | Unique clash, stale lock or failed row/state guard |
+| CONFLICT | 409 | Unique clash, stale lock, failed row/state guard or a PostgreSQL transaction race |
 | OUTCOME_UNKNOWN | 503 | Write may have committed; reconcile without automatic retry |
 
+A `CONFLICT` carries `kind`: `"row"` when a row statement, or a Procedure step marked `onNoRows: conflict`, changed no row (missing or not visible, a stale version, or a
+state its WHERE no longer allows; one message covers all three, so it never reveals whether the row exists), `"unique"`
+for a unique-index clash, `"serialization"` for a definitive PostgreSQL serialization failure (`40001`) or deadlock (`40P01`), `"check"` for a Schema check (with `schema` and `check`) and `"lock"` when a [Schema lock](schema.md#locks)
+holds the row (with `schema`, `verb`, `lock` and `message`, the lock's static text; the row is visible to the caller, so
+naming the lock reveals nothing new). Match `kind`, not the message. A `"lock"` refusal never succeeds on retry: change the
+state that locks the row first (for a live revision, switch the post to another revision).
+To recover from `"row"`, read the record again and decide from its current state: retry with its current version only when the change still applies, and never retry blindly. A Procedure can name a precise reason itself (a ref handler that reads the row first, or a RETURNING the caller checks).
+
+A `"serialization"` conflict means PostgreSQL refused and rolled back the write, whether the refusal happened during a statement or COMMIT. The native error remains attached as the in-process `cause`, never exposed on the wire. Re-read the relevant state before deciding whether to retry; Mantle never retries automatically. A lost COMMIT response or missing server evidence stays `OUTCOME_UNKNOWN`, not `CONFLICT`.
+
 Unknown errors map to redacted `INTERNAL_ERROR` (500). A custom `ContractError` outside the core set must carry an explicit status. Media uses its selected `mediaError` contract. Never expose SQL errors, tokens or credentials.
 
 The runtime runs no DDL or schema checks. Schema installation and failures belong to [the native migration tool](../concepts/runtime-and-adapters.md#schema-installation-and-migrations), not a boot diagnostic.
 
+`Schema.spec.publishing` that is malformed or on a Schema that is not `lifecycle: publishing` is `SCHEMA_PUBLISHING_INVALID`. A Store update that sets a field `publish` requires to null on a published row is `INPUT_VALIDATION_FAILED`, naming the field, for every caller. A malformed `Schema.spec.lock` entry is `SCHEMA_LOCK_INVALID`; a lock `when` outside the [lock subset](schema.md#locks) is `SQL_SHAPE` (or the SQL compiler's own code), and an `EXISTS` no declared index serves is `LOCK_INDEX_MISSING`, whose message names the index to declare.
+
+A Procedure `handler` with other than exactly one of `sql`, `steps` and `ref`, an empty `steps` list, a step key other than `sql` and `onNoRows`, an empty step `sql` or an `onNoRows` other than `conflict` is `INVALID_MANIFEST_ENVELOPE` at that pointer. A step that holds several statements or none, and `onNoRows` on a row-classified statement, are `SQL_SHAPE` at `/spec/handler/steps/<i>/sql` and `/spec/handler/steps/<i>/onNoRows`; any other SQL refusal in a step points at that step, its line counted from the step's first line.
+
 User-field generation diagnostics are `AUTH_ROLE_REMOVED` (`auth.role` / `auth.hasRole`), `USER_REF_SCOPE_ONLY` (`auth.user` outside `scope` / `restrict`), `USER_FIELD_INVALID` (literal name/value or template grammar), `USER_FIELD_POSITION` (SET of a partition) and `USER_FIELD_CONFLICT` (column type/enum disagreement, or a reference to a field-scoped Schema without its scope terms). Warnings are `USER_FIELD_VALUES_UNENUMERATED` (no enum list), `USER_SCOPE_PUBLIC_ANON_EMPTY` (anonymous public reads are refused), `USER_SCOPE_ADMIN_VALUES` (an admin target reads field-scoped rows) and `USER_SCOPE_JOIN_DROPS` (a join of Schemas scoped by different fields). A generated app supplies the literal USER_REFS_V1 bind capability version; a mismatch throws `USER_REFS_VERSION` before native SQL.

package/docs/handbook/reference/procedure.md

@@ -1,14 +1,14 @@
 # Procedure
 
-A Procedure requires `input`, `output` JSON Schemas and a `handler` containing SQL or a ref name. Optional fields include title, description, requires, target, MCP annotations and Admin uiSchema. See [manifest envelope](manifest.md).
+A Procedure requires `input`, `output` JSON Schemas and a `handler` with exactly one of `sql` (the program), `steps` (the same program, one statement per step: `[{ sql, onNoRows? }]`) or `ref`. Optional fields include title, description, requires, target, MCP annotations and Admin uiSchema. See [manifest envelope](manifest.md).
 
-SQL uses declared Schemas, `input.<name>`, `auth.uid()` and native expressions accepted by the selected compiler dialect. Compiler policy supplies scope and system fields. Do not assign scope, version, status, published_at, timestamps or author columns yourself. Publishing writes use generated transitions. `restrict` narrows the rows the statements read and write, as on a [View](view.md#restrict); it is refused on ref handlers.
+SQL uses declared Schemas, `input.<name>`, `auth.uid()` and the expressions [the SQL reference](sql.md) lists for the selected dialect; [SQL patterns](../guides/sql-patterns.md) shows conditional status, approval, partial updates, upserts, guards and creating a row only when its parent exists. Compiler policy supplies scope and system fields. Do not assign scope, version, status, published_at, timestamps or author columns yourself. A SQL Procedure cannot write a `publishing` Schema: create and edit its rows from a ref handler through the Store, and change status with the generated publish/unpublish/archive transitions. `restrict` narrows the rows the statements read and write, as on a [View](view.md#restrict); it is refused on ref handlers.
 
-A row-classified INSERT/UPDATE/DELETE (one that targets a single row, e.g. `WHERE id = input.id`) must affect one row. Use `WHERE id = input.id AND version = input.expectedVersion` for explicit OCC. Set operations, including UPDATE with a subquery and `INSERT ... SELECT`, may affect zero rows without an error: check the returned rows when zero means failure. A unique clash, a failed Schema `checks` constraint or a failed row assertion is `CONFLICT` (409); statements run atomically. A check failure keeps that code and its existing `A check of the Schema failed` message, and sets `ContractError.fields` to `{ kind: "check", schema, check }`; `check` is the expression on SQLite/D1 and the generated constraint name on PostgreSQL. Results are raw `{ results }`, not runtime-validated authored outputs. RETURNING uses SQL output names; quote an explicit alias to preserve declared case (`RETURNING reqStatus AS "reqStatus"`). Generation warns about unaliased direct fields whose declared name differs from storage.
+A row-classified INSERT/UPDATE/DELETE (one that targets a single row, e.g. `WHERE id = input.id`) must affect one row. Use `WHERE id = input.id AND version = input.expectedVersion` for explicit OCC. Set operations, including UPDATE with a subquery and `INSERT ... SELECT`, may affect zero rows without an error. When zero means failure, write the handler as `steps` and give that statement `onNoRows: conflict` (`steps: [{ sql: "INSERT … SELECT …", onNoRows: conflict }]`): it must write at least one row, or the call is `CONFLICT` kind `"row"` and the whole program rolls back ([create only if the parent exists](../guides/sql-patterns.md#create-only-if-the-parent-exists-onnorows)). `steps` compile exactly as the same statements in `sql`, in order and in one batch; each step must be exactly one statement. Generation refuses a step with several statements or none, `onNoRows` on a row-classified statement (it already must change exactly one row) and any `onNoRows` value but `conflict`; a ref handler has no steps. A unique clash, a failed Schema `checks` constraint or a failed row assertion is `CONFLICT` (409) with `kind` `"unique"`, `"check"` or `"row"` ([diagnostics](diagnostics.md)); statements run atomically. A check failure keeps that code, and its message is `A check of the Schema failed: <schema>: <check>` on every target, with the driver's own error only in `cause`; `ContractError.fields` is `{ kind: "check", schema, check }`. `check` is the expression on SQLite/D1 and the generated constraint name on PostgreSQL. Results are raw `{ results }`: one array of RETURNING rows per statement, in order (`results[0][0].id` is the first statement's first row), not runtime-validated authored outputs, with driver-native values: a SQLite/D1 boolean is `1`/`0` here, while a View returns a declared boolean column as `true`/`false`; read a row back through a View when a client needs the typed form. Likewise `RETURNING version` is a number on SQLite/D1 and int8 text (`"2"`) on PostgreSQL; the Store converts `version` to a number, a Procedure result does not, so use `Number(version)` or read the row back through the Store. An array input is a row source: `json_each(input.items)` on SQLite/D1 and `jsonb_array_elements(input.items) AS j(value)` on PostgreSQL write any number of rows in the same atomic program. Callers pass the array itself (from a handler, `ctx.store.procedures["place-order"]({ orderRef, items })`); the generated input type is the authored one and the generated query serializes a JSON input for the driver, so no `JSON.stringify` is needed (a string is bound as it is). See [several rows that commit together](../guides/typed-queries.md#several-rows-that-commit-together). RETURNING uses SQL output names; quote an explicit alias to preserve declared case (`RETURNING reqStatus AS "reqStatus"`). Generation warns about unaliased direct fields whose declared name differs from storage.
 
 A row-classified UPDATE/DELETE on an excluded or missing id affects zero rows and returns HTTP 409 (`CONFLICT`), just like a stale version; reads return not found. Native Admin's visible-row pre-read returns 404 for excluded/missing ids.
 
-A ref handler is application code called as `(ctx, input)`. Generation prints required `Handlers` keys; typecheck and implement them. Wire them at `store(db, caller, { handlers })` and selected surfaces. The context has the Caller, the native db and a Store for that caller. A handler is not one transaction by itself: when it runs inside a caller's `store.transaction`, its db and Store are that transaction's; otherwise each write commits on its own. On PostgreSQL and bun:sqlite, `ctx.transaction(async ({ store, db }) => …)` makes writes that must commit together atomic; it joins the transaction the handler already runs in. A joined transaction has no savepoint, so let an error inside `ctx.transaction` propagate: a handler that catches it and carries on keeps the writes made before the error. Keep external calls (payments, supplier APIs) outside it, so a callback never waits for an uncommitted row. D1 has no interactive transactions, so its `HandlerContext` has no `transaction`: put writes that must commit together in one SQL Procedure, whose statements commit together, and call it through `ctx.store.procedures`. It is not a sandbox; the app owns external side effects and input/output handling. The context has no `env`: on Workers read bindings and secrets with `import { env } from "cloudflare:workers"`. The Caller carries no name or email; `userOf(caller)` from `@aotter/mantle/auth` returns the Better Auth user record it was resolved from, for session, OAuth and service credentials alike (undefined for system callers).
+A ref handler is application code called as `(ctx, input)`. Generation lists the `Handlers` keys the app must provide (every run, whether or not they exist yet); `tsc --noEmit` checks the implementation against the generated `Handlers` type. Wire them at `store(db, caller, { handlers })` and selected surfaces. The context has the Caller, the native db and a Store for that caller. A handler is not one transaction by itself: when it runs inside a caller's `store.transaction`, its db and Store are that transaction's; otherwise each awaited write commits on its own. For known multi-writes, `ctx.store.batch([...])` is available on every target, including D1: it commits atomically standalone and joins the same outer transaction when one exists. A batch step cannot consume a previous step's result. A rejected batch marks that outer transaction rollback-only, even if the handler catches the error: the transaction rejects with the first batch failure and rolls back all writes. No nested BEGIN or savepoint is added. On PostgreSQL and bun:sqlite, `ctx.transaction(async ({ store, db }) => …)` supports dependent writes and joins the transaction the handler already runs in. A joined transaction has no savepoint; application errors outside a batch must propagate to roll back its writes. Keep external calls (payments, supplier APIs) outside it, so a callback never waits for an uncommitted row. D1 has no interactive transactions, so its `HandlerContext` has no `transaction`; use `ctx.store.batch` or a multi-statement SQL Procedure through `ctx.store.procedures` for atomic writes. It is not a sandbox; the app owns external side effects and input/output handling. The context has no `env`: on Workers read bindings and secrets with `import { env } from "cloudflare:workers"`. The Caller carries no name or email; `userOf(caller)` from `@aotter/mantle/auth` returns the Better Auth user record it was resolved from, for session, OAuth and service credentials alike (undefined for system callers).
 
 `target: { schema, id, version? }` binds an Admin operation to a row. SQL targets can be inferred for a single locked row operation; declare a target for a ref operation when needed. Input fields must have the required shapes.
 
@@ -18,6 +18,6 @@ Every generated AI-facing tool (MCP, WebMCP, publishing and media tools) carries
 
 Generated requires checks gate calls. Boundary input validators are generated separately; direct queries accept driver-ready, app-validated input. Dynamic guards and lifecycle hooks are rejected. See [native execution](../guides/native-execution.md) and [surface contracts](surface.md).
 
-SQL INSERT/upsert into a user-field scoped Schema is system-only. For a verified user, insert through `ctx.store` so membership and single-partition autofill run before the native write. `ctx.store` speaks storage names, not the manifest's: the handler's `input` uses authored names (`input.parentId`), while Store writes, filters and rows use the folded column (`insert({ parentid: input.parentId })`, `where: { parentid }`, `row.parentid`); generated Store types show the exact names ([typed queries](../guides/typed-queries.md)). SET cannot change a field-scope column, including ON CONFLICT DO UPDATE. Scoped unique conflict targets gain the owner/field prefix automatically.
+SQL `INSERT … VALUES`/upsert into a user-field scoped Schema follows the Store's insert rule ([field scope](schema.md#field-scope)); `INSERT … SELECT` into it is system-only, so a ref handler inserts those rows through `ctx.store`. `ctx.store` speaks storage names, not the manifest's: the handler's `input` uses authored names (`input.parentId`), while Store writes, filters and rows use the folded column (`insert({ parentid: input.parentId })`, `where: { parentid }`, `row.parentid`); generated Store types show the exact names ([typed queries](../guides/typed-queries.md)). SET cannot change a field-scope column, including ON CONFLICT DO UPDATE. Scoped unique conflict targets gain the owner/field prefix automatically.
 
-Triggers are the only way request data reaches a Procedure: REST and MCP validate the input against the Procedure's schema, then call it. App code may also call a generated Procedure directly (`import run from "../generated/procedures/<name>.js"`, `await run(db, caller, input)`); `requires`, row policy and checks still apply, but input validation does not, so pass only data the app produced or has verified (a cron job, a callback after its signature check). A page that takes user input submits it to the Procedure's REST Trigger; see `node_modules/@aotter/mantle/docs/examples/purchasing/src/requests-page.ts`.
+Triggers are the only way request data reaches a Procedure: REST and MCP validate the input against the Procedure's schema, then call it. App code may also call a generated Procedure directly (`import run from "../generated/procedures/<name>.js"`, `await run(db, caller, input)`) or through the Store (`ctx.store.procedures[name](input)` in a handler); `requires`, row policy and checks still apply, but input validation does not, so pass only data the app produced or has verified (a cron job, a callback after its signature check). A page that takes user input submits it to the Procedure's REST Trigger; see `node_modules/@aotter/mantle/docs/examples/purchasing/src/requests-page.ts`.

package/docs/handbook/reference/schema.md

@@ -1,6 +1,6 @@
 # Schema
 
-A Schema declares one table and its typed Store collection. Required keys are title and an object JSON Schema. Optional keys include lifecycle, scope, TTL, indexes, uniqueIndexes, checks, searchableFields, localized, translates and uiSchema. Unknown keys fail validation.
+A Schema declares one table and its typed Store collection. Required keys are title and an object JSON Schema. Optional keys include lifecycle, scope, lock, TTL, indexes, uniqueIndexes, checks, searchableFields, localized, translates and uiSchema. Unknown keys fail validation.
 
 ```yaml
 apiVersion: cms.mantle.aotter.net/v2
@@ -38,7 +38,7 @@ A string `pattern` needs a `maxLength`: generation bounds each regex's backtrack
 | object/array | JSON text | jsonb |
 | geo | lat/lng columns, R*Tree | lat/lng columns |
 
-System columns include id, version, created_at, updated_at and author_id; publishing adds status/published_at. Do not declare reserved fields. Manifest native column names in indexes use camelCase (`createdAt`); generated Store/SQL use storage names (`created_at`). Scope is omitted from returned rows.
+System columns include id, version, created_at, updated_at and author_id; publishing adds status/published_at. Initial DDL declares a field NOT NULL when an `operational` Schema lists it in `required` and it does not allow null; `default` never does, and no column gets a DDL `DEFAULT` ([server-maintained fields](#admin-uischema)). Do not declare reserved fields. Manifest native column names in indexes use camelCase (`createdAt`); generated Store/SQL use storage names (`created_at`). Scope is omitted from returned rows.
 
 Declared date/date-time outputs are SQL-formatted strings (`YYYY-MM-DD`, UTC ISO with six fractional digits). Computed timestamps remain native. Inputs and other output scalars follow [the native contract](../guides/native-execution.md). Date conversion through JS Date loses microseconds.
 
@@ -46,10 +46,57 @@ Generated types constrain Store fields and writes; Store does not interpret a JS
 
 ## Row rules
 
-Schemas default to operational. Publishing opts into draft/published/archived and generated admin/system transitions. Store cannot assign system columns or scope; generated policy fills them. See [lifecycle and locales](../concepts/lifecycle-and-locales.md).
+Schemas default to operational. Publishing opts into draft/published/archived and generated admin/system transitions. Store cannot assign system columns or scope; generated policy fills them. `publishing: { liveEdits: true }` (only with `lifecycle: publishing`) lets Admin's generic patch edit a published entry in place; without it, generic patches edit drafts only, an implicit lock named `publishing` that never binds the transitions. No update clears a field `publish` requires from a published row (`INPUT_VALIDATION_FAILED`): a Store update that sets one to null is refused, while Admin's live edit validates the whole merged entry as `publish` does. See [lifecycle and locales](../concepts/lifecycle-and-locales.md).
 
 Owner and field columns prefix every unique index in that order. User reads/writes see their own rows; anonymous reads see none. System callers bypass scope. TTL uses `{ field, expireAfterSeconds }` over a date-time field; expired rows become invisible but remain stored until a system sweep. TTL is not allowed on translations.
 
+### Locks
+
+`lock` freezes a row while a condition on it holds. It is a data-state invariant, not an authorization rule: it binds every caller, admins included.
+
+```yaml
+apiVersion: cms.mantle.aotter.net/v2
+kind: Schema
+metadata: { name: posts }
+spec:
+  title: Posts
+  lifecycle: publishing
+  indexes: [[current_revision]]
+  schema:
+    type: object
+    properties:
+      slug: { type: string }
+      current_revision: { type: string, x-mantle-ref: post_revisions }
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Schema
+metadata: { name: post_revisions }
+spec:
+  title: Post revisions
+  lifecycle: operational
+  lock:
+    - name: live_revision
+      on: [update, delete]
+      when: EXISTS (SELECT 1 FROM posts p WHERE p.current_revision = post_revisions.id)
+      message: "This revision is live. Create a new revision and switch to it."
+  schema:
+    type: object
+    required: [post, body]
+    properties:
+      post: { type: string, x-mantle-ref: posts }
+      body: { type: string }
+```
+
+- `when` true means locked. It reads the existing row only (like RLS `USING`); new rows stay with `checks`. `on` lists `update` and/or `delete`; names are unique per Schema.
+- A caller's update or delete of the Schema gets `AND NOT (<when>)` in its WHERE, beside scope and the version check, so the write stays one atomic statement. Several locks are ANDed. A NULL `when` refuses the write: a lock fails closed. So `when: body = 'keep'` also locks a row whose `body` is NULL; write `body IS NOT NULL AND body = 'keep'` to lock only the rows that hold the value. An `ON CONFLICT DO UPDATE` carries the `update` locks too, as a set op: an upsert whose conflicting row is locked leaves it unchanged and returns no row for it, like `DO NOTHING`; use a row-classified `UPDATE` to get `CONFLICT` `kind: "lock"`.
+- It applies to every caller-facing write: Admin's generic patch and delete (which the Admin MCP App and WebMCP reach through the same routes), caller-mode SQL Procedures' `UPDATE`/`DELETE` of the locked Schema (over REST, MCP or a direct call), the generated publishing transitions (`<schema>.publish` / `.unpublish` / `.archive`, which carry the `update` locks) and Stores bound to a caller (`store(db, caller)`, a ref handler's `ctx.store`). Only a trusted write (the system caller, a system Store, the TTL sweep) bypasses it: the maintenance escape hatch, visible in code review.
+- A refused write is `CONFLICT` with `kind: "lock"` and `{ schema, verb, lock, message }` ([diagnostics](diagnostics.md)). When the write changed no row, one read of the row as the caller sees it classifies the failure: a missing or invisible row stays `kind: "row"`.
+- `when` allows the Schema's own columns, constants, comparisons (`=`, `<>`, `<`, `>`, `<=`, `>=`, `IN (…)`), `AND`/`OR`/`NOT`, `IS [NOT] NULL` and `[NOT] EXISTS (SELECT … FROM <declared Schema> [alias] WHERE …)`. It calls no function (`now()`, `auth.*`, aggregates, windows) and reads no `input.*`, so it holds the same for every caller and request. Inside a subquery every column is qualified: `p.current_revision` for the subquery's Schema, `post_revisions.id` for the locked row (an unqualified `id` would silently read `posts.id`). A subquery reads one Schema, without join, `WITH`, `GROUP BY`, `ORDER BY`, `LIMIT` or `DISTINCT`, and its alias may not hide the locked Schema's name. `when` is one expression: a trailing `ORDER BY`, `GROUP BY` or `LIMIT` is refused. The compiler gives each subquery relation a reserved `_mantle_lock_<n>` alias, so the alias of a write the lock guards can never capture its references (relation aliases starting with `_mantle` are refused in authored SQL).
+- Subqueries read the stored rows, without the reader's scope, publishing filter or TTL: a referencing row the caller cannot see still locks.
+- **Concurrency.** The lock is a predicate on the write's database snapshot, not a lock on every row its subquery reads. On PostgreSQL READ COMMITTED, a concurrent change in another Schema can make a cross-row `EXISTS` condition true after an UPDATE has already passed that check. For a publication guarantee across editors, the [revisions recipe](../guides/revisions.md) first CAS-seals the revision's own row and locks on that stored seal; its parent pointer changes only after sealing succeeds. A transaction around the pointer change alone does not serialize unrelated autocommit edits.
+- Admin knows before the edit: its editor and list reads evaluate each lock per row, and each entry carries `locks: { update, delete }` (per verb, the holding lock's `{ lock, message }` or `false`), so Save, Delete and transitions are disabled with the message ([native Admin](../guides/native-admin.md)). On a publishing Schema the draft-only rule shows there too, as the implicit lock `publishing`, after any declared lock on the same verb. The write's WHERE remains the authority.
+- **Index rule.** Locks are index-proven reads, like [paged Views](#index-prefixes-for-paged-views): every guarded write runs them. Each `EXISTS` needs an equality (`=` to the locked row's column, an outer subquery's column or a literal, or `IN (<literals>)`) among its top-level `AND` terms on the first column of a declared index, unique index or `id` of its Schema. The example needs `indexes: [[current_revision]]` on `posts`; otherwise generation fails with `LOCK_INDEX_MISSING`, naming the index to declare. A condition on the locked row's own columns needs no index. An `OR` of correlations is not index-proven: split it into separate locks.
+
 `localized` and `translates: { parent, on }` declare a translation child. Parent visibility and publication are retained, with matching scope where needed. Locale values stay plain strings.
 
 ## Indexes, checks and search
@@ -70,15 +117,17 @@ Declaring both indexes does not make one View bounded for every caller. System (
 
 Publishing fields may be NULL in drafts even when required, so they cannot be View paging keys. Store accepts `published_at` ordering, but View paging rejects it. Use `ORDER BY id`, or keep the business date in an operational Schema as an indexed, required non-null field. See [View paging](view.md#results-and-paging).
 
-`checks` are restricted SQL expressions over the table's columns, emitted in initial DDL. Native databases enforce them; bare database errors are not automatically mapped to input-validation failures. Searchable fields must be plain string fields. SQLite/D1 emit FTS5 trigram tables and maintenance triggers; PostgreSQL uses ILIKE. Short SQLite terms use LIKE. Store search additionally matches exact id and combines with row policy.
+`checks` are restricted SQL expressions over the table's columns, emitted in initial DDL. Native databases enforce them; bare database errors are not automatically mapped to input-validation failures. `searchableFields` defaults to none: Store and Admin list search then match the exact id only, and Admin's search box says so. Name the fields people search by, such as the list `primaryField` or a `title`; with Admin selected, `mantle generate` warns when a Schema has no `searchableFields` but has such a field that could be one (a plain string, not a date, date-time or reference). Searchable fields must be plain string fields. SQLite/D1 emit FTS5 trigram tables and maintenance triggers; PostgreSQL uses ILIKE. Short SQLite terms use LIKE. Store search additionally matches exact id and combines with row policy.
 
 The runtime never creates, alters or checks tables. Initial DDL is for an empty database. Changed fields, checks, indexes and search DDL require [agent-owned native migrations](../concepts/runtime-and-adapters.md#schema-installation-and-migrations), including explicit data migration for destructive/type changes. Mantle drops nothing.
 
 ## Admin uiSchema
 
-A property marked `readOnly: true` in the JSON Schema is server-maintained (a counter, a total): Admin's generic create stores its `default` whatever the input says, Admin edits ignore it, and only Procedures (or server code through the Store) change it afterwards. JSON Schema defaults are applied by Admin and the Store, not by the database: a SQL Procedure that inserts the row sets the field itself. A root `readOnly: true` makes the whole Schema read-only in Admin.
+A property marked `readOnly: true` in the JSON Schema is server-maintained (a counter, a total): Admin's generic create stores its `default` whatever the input says, Admin edits ignore it, and only Procedures (or server code through the Store) change it afterwards. JSON Schema defaults are applied by Admin's generic create only, not by the Store or the database: initial DDL emits no `DEFAULT` for a field, so server code through the Store and a SQL Procedure that inserts the row set the field themselves. A root `readOnly: true` makes the whole Schema read-only in Admin: a generic Admin write is refused with 403 `AUTH_DENIED` (not a 409 version conflict).
+
+`default` does not make a column NOT NULL; `required` does (in an `operational` Schema). For a server-maintained value that is never NULL, list it in both, `required: [name, total]` with `total: {type: integer, readOnly: true, default: 0}`: initial DDL declares `total` NOT NULL, Store and View row types read it as `number` rather than `number | null`, Admin's create still fills the default when the client omits it, and the Store's insert type requires server code to pass it. Without `required` the column stays nullable, and an INSERT that omits it stores NULL. Adding `required` to an existing table is a [migration](../concepts/runtime-and-adapters.md#schema-installation-and-migrations): backfill NULLs, then add NOT NULL.
 
-`fields.<name>.widget` selects a built-in control (`textarea`); `list.primaryField`, `list.columns` and enum `filterField` select list presentation; `nav.parentField` chooses the parent a child folds under (required when two or more required `id` references exist) and `nav.standalone` lists the child in the sidebar; `nav.group/order/hidden` place it in the sidebar ([sidebar](../guides/native-admin.md#sidebar)). `list.columns` must not repeat `list.primaryField` or itself (`SCHEMA_UI_INVALID`). Generation validates these against declared fields/indexes. Components that render a field, cell or record aside are not manifest references: they live in `defineAdmin` ([customising Admin](../guides/native-admin.md#customising-admin)), and a manifest that still names one (`widget: <extension>/<contribution>`, `widget` `options`, `list.cells`, `panels`) is refused. JSON Schema root `schema.readOnly: true` disables generic Admin writes, not declared Procedures; `uiSchema.readOnly` is rejected with `SCHEMA_UI_INVALID`. `x-mantle-ref` relates a field to another Schema id or single-field unique field.
+`fields.<name>.widget` selects a built-in control (`textarea`); `list.primaryField`, `list.columns` and enum `filterField` select list presentation (operational Schemas only; a publishing Schema's list shows its title field and status); `nav.parentField` chooses the parent a child folds under (required when two or more required `id` references exist) and `nav.standalone` lists the child in the sidebar; `nav.group/order/hidden` place it in the sidebar ([sidebar](../guides/native-admin.md#sidebar)). `list.columns` must not repeat `list.primaryField` or itself (`SCHEMA_UI_INVALID`). Generation validates these against declared fields/indexes. Components that render a field, cell or record aside are not manifest references: they live in `defineAdmin` ([customising Admin](../guides/native-admin.md#customising-admin)), and a manifest that still names one (`widget: <extension>/<contribution>`, `widget` `options`, `list.cells`, `panels`) is refused. JSON Schema root `schema.readOnly: true` disables generic Admin writes, not declared Procedures; `uiSchema.readOnly` is rejected with `SCHEMA_UI_INVALID`. `x-mantle-ref` relates a field to another Schema id or single-field unique field. It is not a foreign key: the database does not check that the referenced row exists, and deleting that row leaves the reference dangling. Check existence in the write (a JOIN or `EXISTS` in the Procedure, with `onNoRows: conflict` on its step when a missing parent must be a 409) and guard deletes with `NOT EXISTS` ([SQL patterns](../guides/sql-patterns.md)).
 
 See [Admin](../guides/admin-ui.md) and [diagnostics](diagnostics.md).
 
@@ -88,7 +137,11 @@ See [Admin](../guides/admin-ui.md) and [diagnostics](diagnostics.md).
 
 A caller whose value for a field is `{ all: true }` drops that field's term only; the other terms still apply. Generated SQL holds one statement per target and selects the form for each caller at run time; values are always bound parameters. Neither roles nor the admin layer widen a field scope or a translation parent's visibility. A Schema whose `x-mantle-ref` points to a field-scoped Schema must carry the same scope terms.
 
-For inserts, one allowed partition autofills a missing value; multiple values require an explicit allowed partition, and missing/empty values fail with `AUTH_DENIED`. Callers holding `{ all: true }` and system callers always provide an explicit partition. Procedure INSERT/upsert is trusted-only; use the scoped Store for user writes. The partition is never writable through SET, including upsert and native Admin patch. An excluded id behaves like a missing row: reads return not found; Store update/delete and row-classified Procedure UPDATE/DELETE affecting zero rows return HTTP 409 (`CONFLICT`). Native Admin's visible-row pre-read returns 404 for either id. SQLite binds a JSON array; PostgreSQL binds a quoted, escaped array. Public Views over field scope warn that anonymous callers are refused.
+For inserts, one allowed partition autofills a missing value; multiple values require an explicit allowed partition, and missing/empty values fail with `AUTH_DENIED`. Callers holding `{ all: true }` and system callers always provide an explicit partition. A Procedure `INSERT … VALUES` follows the same rule for user callers, checked before any SQL runs: leave the partition column out to autofill a caller's single value, or take it from an input declared with the column's own type (`VALUES (input.region, …)`) or a matching literal, which must be inside the caller's set; any other expression there is refused. A Procedure that callers holding several values or `{ all: true }` use, such as an Admin create action, takes the partition as an optional input. `INSERT … SELECT` into a field-scoped Schema, and an insert into a Schema the target `restrict`s, run only for system callers, which this check does not cover: they name the partition themselves; use the scoped Store for user writes there. The partition is never writable through SET, including upsert and native Admin patch. An excluded id behaves like a missing row: reads return not found; Store update/delete and row-classified Procedure UPDATE/DELETE affecting zero rows return HTTP 409 (`CONFLICT`). Native Admin's visible-row pre-read returns 404 for either id. SQLite binds a JSON array; PostgreSQL binds a quoted, escaped array. Public Views over field scope warn that anonymous callers are refused.
+
+#### References to a scoped Schema
+
+A non-null `x-mantle-ref` value that points to a scoped Schema (field or owner scope) must name a row of that Schema the caller can read, matched on `id` or on the object form's `field`, and that row must have the same value as the child for every scope field the two share (`ADR-0034`: a reference between scoped Schemas stays inside one owner or partition). A Store insert or update, a Procedure `INSERT … VALUES`, `UPDATE … SET` or `DO UPDATE SET`, and native Admin's generic create and patch check it in the same statement; a missing, unreadable or other-partition parent behaves like a missing row: a single-row statement returns HTTP 409 (`CONFLICT`), and an `ON CONFLICT` insert or a set update writes nothing for that row. A caller holding several values or `{ all: true }` can still not point a child in one partition at a parent in another. `INSERT … SELECT` that writes such a reference runs only for system callers. A caller's `UPDATE … SET` or `DO UPDATE SET` of such a reference takes no subquery, which could read the parent's columns as its own. Trusted writes (`store(db, caller)` or a ref handler's `ctx.store` with a system caller, `{ kind: "system", reason }`) are not checked, like the other row rules. NULL is always allowed; deleting a parent does not touch its children.
 
 ## Reserved entry columns
 
@@ -100,5 +153,22 @@ the publishing lifecycle; `version` backs `expectedVersion`; `author_id` is the
 `restrict: { <schema>: "author_id = auth.uid()" }`.
 
 A seed or other SQL that inserts rows outside Mantle (`wrangler d1 execute --file seed.sql`) sets the native columns
-itself: `id` (text, unique) and `created_at` (integer microseconds since the Unix epoch, e.g. `1767225600000000`);
-`updated_at` and `version` have defaults. Procedures and the Store fill them for you.
+itself. Procedures and the Store fill every one of them for you; prefer them for fixtures. The Store accepts no
+value for these columns or the scope column, for any caller: it sets them itself, so SQL is also the only way to keep
+their existing values.
+
+| Column | SQLite and D1 | PostgreSQL | If the SQL omits it |
+|---|---|---|---|
+| `id` | text, unique | text, unique | the insert fails |
+| `version` | integer, `1` for a new row | `int8` | `1` |
+| `created_at` | integer microseconds since the Unix epoch (`1767225600000000` is 2026-01-01T00:00:00Z) | `timestamptz` | the insert fails |
+| `updated_at` | integer microseconds, like `created_at` | `timestamptz` | SQLite and D1 store `0`, which Admin shows as 1970-01-01; PostgreSQL stores `now()` |
+| `author_id` | the creator's Better Auth user id, or `NULL` | the same | `NULL`: `restrict: { <schema>: "author_id = auth.uid()" }` shows the row to no member |
+| `status` (publishing) | `'draft'`, `'published'` or `'archived'` | the same | `'draft'` |
+| `published_at` (publishing) | integer microseconds when `status` is `'published'`, otherwise `NULL` | `timestamptz` or `NULL` | `NULL` |
+| scope column (owner or field scope) | the field the `scope` names (`owner` in `owner = auth.uid()`), text, not null | the same | the insert fails |
+
+Units differ by table: entry timestamps (`created_at`, `updated_at`, `published_at` and declared `date-time` fields)
+are microseconds on SQLite and D1, while the optional media library's `media_assets.created_at` is epoch
+**milliseconds** on every dialect ([media](../cloudflare/media-r2.md)). A declared `date` field is integer days since
+1970-01-01 on SQLite and D1. [Seed data](../guides/local-testing.md#seed-data) shows a complete seed for each dialect.

package/docs/handbook/reference/sql.md

@@ -0,0 +1,65 @@
+---
+description: The SQL that Views and Procedures accept on SQLite/D1 and on PostgreSQL, and what each refuses with which diagnostic.
+---
+# SQL accepted by each dialect
+
+Views and Procedures share one allowlist with two profiles. SQLite and D1 run the base profile; PostgreSQL runs the
+base profile plus the additions below. Anything not listed is refused at generation with a code (`SQL_UNSUPPORTED`,
+`SQL_FUNCTION`, `SQL_SHAPE`, `SQL_TYPE`) and a source position, so generation is the authority for each target. For
+worked examples see [SQL patterns](../guides/sql-patterns.md).
+
+## Both dialects
+
+| Area | Accepted |
+| --- | --- |
+| Statements | `SELECT`, `INSERT … VALUES` / `INSERT … SELECT`, `UPDATE … SET … WHERE`, `DELETE … WHERE`, each with `RETURNING`; `WITH` (non-recursive) on a `SELECT` |
+| Upsert | `ON CONFLICT (<unique index columns>) DO NOTHING` / `DO UPDATE SET …`, with `excluded.<column>` |
+| Joins | `INNER JOIN`, `LEFT JOIN`; a comma join only for a row source (`json_each`, or PostgreSQL's below) |
+| Clauses | `WHERE`, `GROUP BY`, `HAVING`, `ORDER BY`, `LIMIT` |
+| Predicates | `=`, `<>`, `!=`, `<`, `>`, `<=`, `>=`, `AND`, `OR`, `NOT`, `IS [NOT] NULL`, `IS [NOT] DISTINCT FROM`, `[NOT] BETWEEN`, `IN (list)`, `IN (subquery)`, `LIKE`, `[NOT] EXISTS (subquery)` |
+| Expressions | `+ - * / %`, `\|\|`, `->>` (JSON field), `CASE`, `COALESCE`, `NULLIF`, scalar subqueries, `CAST(… AS text \| int4 \| int8 \| float8 \| bool \| timestamptz \| date \| numeric \| interval)` |
+| Aggregates | `count`, `sum`, `min`, `max`, `avg` |
+| Windows | `row_number()`, `rank()`, `sum()`, `count()` with `OVER (PARTITION BY … ORDER BY …)` and the default frame |
+| Scalar functions | `lower`, `upper`, `length`, `abs`, `round`, `substr`, `replace`, `trim`, `ltrim`, `rtrim`, `instr` |
+| Time | `now()`, `date_trunc('hour' \| 'day' \| 'week' \| 'month' \| 'year', …)`, `extract(year \| month \| day \| dow \| hour FROM …)` |
+| Mantle | `auth.uid()`, `input.<name>`, `mantle.search`, `mantle.search_rank`, `mantle.near`, `mantle.distance` ([features](features.md)) |
+
+## SQLite and D1 only
+
+| Accepted | PostgreSQL instead |
+| --- | --- |
+| `json_each(<array>)` as a row source (`FROM json_each(input.items) j`, `j.value ->> 'field'`) | `jsonb_array_elements(…) AS j(value)` |
+| `json_group_array`, `json_group_object` | `jsonb_agg`, `jsonb_object_agg` |
+| `json_extract`, `json_set`, `json_insert`, `json_remove`, `json_array_length`; build an object with `json_set('{}', '$.k', v, …)` (`json_object` is refused) | `jsonb_build_object`, `jsonb_build_array` and the jsonb operators |
+| `typeof`, `hex` | refused (`typeof` is SQLite's; PostgreSQL has `pg_typeof`) |
+
+An integer `CAST` of anything but a literal is refused (`SQL_TYPE`): SQLite truncates where PostgreSQL rounds. Write
+`round(x)`; `->>` already returns a JSON number as a number.
+
+## PostgreSQL additions
+
+| Area | Accepted |
+| --- | --- |
+| Set operations | `UNION [ALL]`, `INTERSECT`, `EXCEPT`, inside a `WITH` or a subquery (the View's own SELECT is the one that pages) |
+| Relations | `LATERAL` subqueries, `WITH RECURSIVE`, `MATERIALIZED` / `NOT MATERIALIZED` CTEs |
+| Row sources | `jsonb_array_elements`, `jsonb_array_elements_text`, `jsonb_each`, `jsonb_each_text`, with `WITH ORDINALITY` |
+| Operators | `ILIKE`, `~`, `~*`, `!~`, `!~*`, jsonb `->`, `#>`, `#>>`, `@>`, `<@`, `?`, `?\|`, `?&` |
+| Aggregates | `string_agg`, `jsonb_agg`, `jsonb_object_agg`, with `FILTER (WHERE …)` and `ORDER BY` inside the call |
+| Windows | also `avg`, `min`, `max`, `lag`, `lead`, `first_value`, `last_value`, `dense_rank`; frames except `GROUPS` and `EXCLUDE` |
+| Functions | `GREATEST`, `LEAST`, `floor`, `ceil`, `sqrt`, `power`, `split_part`, `timezone`, `jsonb_build_object`, `jsonb_build_array`, `jsonb_strip_nulls`, `to_jsonb`, `jsonb_typeof`, `CAST(… AS jsonb)` |
+| Time | `date_trunc` also `'minute'`, `'quarter'`; `extract` also `minute`, `quarter`, `week`, `isoyear`, `isodow`, `doy`, `epoch` |
+
+`jsonb_agg` of no rows is `NULL`: write `COALESCE(jsonb_agg(…), CAST('[]' AS jsonb))` for an empty array.
+
+## Refused on every target
+
+- `OFFSET`: page with the generated cursor (`limit`, `cursor`) instead.
+- `RIGHT` and `FULL` joins, `UPDATE … FROM`, `DELETE … USING`, DDL and any function not listed.
+- `DISTINCT` with `ORDER BY`: the paging key Mantle appends would change what is distinct; use `GROUP BY`.
+- A program of more than 2000 syntax nodes.
+
+Two write rules come from Mantle, not the dialect ([Procedure](procedure.md)). A row-classified `UPDATE`/`DELETE`
+(`WHERE id = input.id …`) must change exactly one row, otherwise `CONFLICT`. A set form (`WHERE id IN (SELECT …)`,
+`INSERT … SELECT`) may change none, so write a conditional write that may do nothing in that form; a Procedure step with
+`onNoRows: conflict` turns "none" into `CONFLICT`. Scope, version,
+timestamps and author columns are assigned by Mantle, never by your SQL.

package/docs/handbook/reference/surface.md

@@ -233,7 +233,7 @@ surface its generated `publish_<schema>`, `unpublish_<schema>` and
 `archive_<schema>` tools use the same snake-case naming rule, are admin-only
 and take `{ id, expectedVersion }` through the shared generated validation.
 
-`/mcp/admin` admits only admins: `isAdmin(caller)` must hold. Better Auth’s admin plugin `adminRoles` defines this layer (default `["admin"]`); the application supplies its verified Caller. MCP bodies are limited
+`/mcp/admin` admits only admins: `isAdmin(caller)` must hold. It lists only admin-surface tools; public Views and Procedures stay on `/mcp`, and generation never copies them across. An admin's AI that changes records also needs admin Views to find them and read back the committed row and its version (search, detail), declared by the app; the [acceptance design audit](../guides/agent-workflow-acceptance.md#audit-mcp-tool-design-before-implementation) checks this. Better Auth’s admin plugin `adminRoles` defines this layer (default `["admin"]`); the application supplies its verified Caller. MCP bodies are limited
 to 1 MiB (1,048,576 bytes). Resource metadata challenges use the origin of
 `request.url`; behind a proxy, the app must pass a Request with its public
 origin so the audience and metadata URL point to the client-visible service.
@@ -352,13 +352,17 @@ REST and MCP View pages expose declared JSON columns as JSON values and declared
 boolean columns as booleans, including explicitly authored SQL aliases. SQLite
 and D1 conversions are compiled into only the selected boundary pages;
 PostgreSQL already-native JSON/boolean values pass through. SQL NULL stays null and absent
-fields stay absent. Expressions without declared column lineage stay native.
+fields stay absent. A computed output that is a JSON document by construction
+(`json_group_array`, `json_set`, `jsonb_agg`, `jsonb_build_object` and the like, a scalar
+subquery of one, or a `COALESCE` of those) is converted like a declared JSON column, so it
+is a JSON value on every target. Other expressions without declared column lineage stay native.
 Malformed persisted JSON becomes a redacted internal failure. The conversion
 adds no database operations and does not mutate native query rows.
 
 Bare Views, Store rows, native SQL Procedure `{ results }` and application-owned
-ref outputs retain their native contracts. Use the generated `rest()` / `mcp()`
-module for this client wire contract; do not duplicate JSON/boolean decoding in
+ref outputs retain their native contracts, except that a Store row's `version` is a
+number on every target, so a ref handler returning it outputs the same type
+everywhere. Use the generated `rest()` / `mcp()` module for this client wire contract; do not duplicate JSON/boolean decoding in
 application route handlers or decode PostgreSQL JSON strings a second time.
 
 Declared integer columns (including a selected system `version`) on every target

package/docs/handbook/reference/trigger.md

@@ -35,6 +35,18 @@ spec:
 
 The target names a declared Procedure. `http` sources use POST/PUT/PATCH/DELETE and an `/api/` path. Path parameters bind to corresponding declared input fields and override JSON-body values. The generated REST module retains the Procedure's authorization and validates boundary input.
 
+A path parameter is a whole `{name}` segment. Other segments are literal and may not start with `:` or contain braces, since [describe](describe.md) writes `{name}` as `:name` (`TRIGGER_PATH_INVALID`). Two Triggers with the same method and the same path apart from parameter names are refused (`TRIGGER_PATH_COLLISION`).
+
+### Route precedence
+
+When several http Triggers with the same method match a request, the generated router picks the most specific one, independent of manifest order:
+
+1. fewer `{name}` parameters first;
+2. then, comparing segments from the left, a literal segment before a parameter;
+3. then the path text.
+
+So `POST /api/items/export` wins over `POST /api/items/{id}`, and for `/api/items/latest` the route `POST /api/items/{id}` wins over `POST /api/{kind}/latest`. A public View's `GET /api/views/<name>` route comes before every Trigger. Gateways resolve the same order from [`matchTarget`](describe.md#matching-a-request-to-its-target).
+
 An MCP source is `{ kind: mcp, surface: public }` or admin. The selected MCP module exposes the Procedure as a snake-case tool with its description, [tool hints](procedure.md#mcp-tool-hints) and requires checks.
 
 By default, pair every HTTP Trigger with an MCP Trigger so the same operation is reachable by the user's AI. `mantle generate` warns when a Procedure has HTTP exposure but no MCP exposure, suggesting `surface: admin` for an admin-only Procedure and `public` otherwise. Triggers still decide every Procedure surface: intentional asymmetric exposure is allowed and generation succeeds.

package/docs/handbook/reference/view.md

@@ -1,12 +1,14 @@
 # View
 
-A View requires `surface: public | admin | internal` and one `sql` SELECT. Optional keys include title, description, input, requires, restrict, uiSchema (admin only), and cache. The app imports its generated typed function and supplies a native handle, verified Caller and driver-ready input.
+A View requires `surface: public | admin | internal` and one `sql` SELECT. Optional keys include title, description, input, requires, restrict, uiSchema (admin only), and cache. The app imports its generated typed function and supplies a native handle, verified Caller and driver-ready input; a JSON input (an array read by `json_each(input.ids)`) takes its authored array or object, which the generated query serializes.
 
 ## SQL
 
 PostgreSQL syntax is parsed and checked at generation. Reads may reference declared Schemas, CTEs and reusable internal Views; no auth/system tables or arbitrary external relations. The compiler adds scope, TTL, publication and translation-parent visibility at every relation. SQL policy is not injected at request time.
 
-SQLite supports the compiler's subset: scalar expressions, comparisons, AND/OR/NOT, CASE, COALESCE, supported casts, INNER/LEFT JOIN, subqueries, grouping/aggregates, supported windows, ordered LIMIT, date operations and declared Mantle search/geo functions. PostgreSQL additionally supports recursive CTEs, lateral relations, more window/aggregate forms, ILIKE and jsonb operators where the allowlist permits them. Unsupported SQL fails with a source position; generation is the authority for each target.
+The SQL each dialect accepts, for Views and Procedures alike, is listed in [the SQL reference](sql.md); [SQL patterns](../guides/sql-patterns.md) shows the common ones. Unsupported SQL fails with a source position; generation is the authority for each target.
+
+`*` and `t.*` expand to the Schema's declared fields only. Select `id`, `version`, `created_at` and `updated_at` by name when a client needs them (a write's `expectedVersion`, a detail link, keyset paging).
 
 OFFSET, arbitrary functions/relations, DDL and transaction control are not a read escape hatch. Use keyset paging. Select latitude/longitude explicitly instead of native geo projections.
 
@@ -16,6 +18,12 @@ OFFSET, arbitrary functions/relations, DDL and transaction control are not a rea
 
 ## Search and totals
 
+`mantle.search(<alias>, <text>)` matches the Schema's declared `searchableFields`, and `mantle.search_rank(<alias>)`
+orders by relevance; qualify both with `mantle.`. An optional search reads
+`WHERE p.active AND (input.q IS NULL OR mantle.search(p, input.q))`, and a ranked one
+`WHERE mantle.search(p, input.q) ORDER BY mantle.search_rank(p), p.id` (see `examples/reference-service` `catalog.yaml`
+for cursor paging over the rank).
+
 Views using `mantle.search`, Store search and Admin list search share the dialect search: SQLite/D1 use FTS for queries of 3 or more characters (shorter queries use LIKE); PostgreSQL uses ILIKE over the declared fields and scans by default. A View does not make PostgreSQL search faster. For large PostgreSQL tables, the application's agent adds trigram indexes in a migration, which ILIKE then uses with no code change:
 
 ```sql
@@ -27,7 +35,7 @@ Store keeps `find`/`first` search and `count`. `count` scans every matching row;
 
 ## Results and paging
 
-Each SELECT output needs a unique static name. Unquoted SQL identifiers fold to lower case; use an explicit quoted alias to preserve case (`r.reqStatus AS "reqStatus"`). Generation warns when an unaliased direct declared field would use its lower-case storage name. Declared-column lineage supplies generated types; computed outputs remain native/unknown. SQL formats declared date-time/date outputs, while computed timestamps retain driver values. See [native execution](../guides/native-execution.md).
+Each SELECT output needs a unique static name. Unquoted SQL identifiers fold to lower case; use an explicit quoted alias to preserve case (`r.reqStatus AS "reqStatus"`). Generation warns when an unaliased direct declared field would use its lower-case storage name. Declared-column lineage supplies generated types; computed outputs remain native/unknown, except a top-level output that is a JSON document by construction (a JSON aggregate or builder, a scalar subquery of one, or a `COALESCE` of those; see [SQL patterns](../guides/sql-patterns.md#a-row-with-its-children-in-one-read)), which is typed JSON. An output is non-null (`string`, not `string | null`) only when it reads unchanged a column its table declares NOT NULL (`id`, `version`, `created_at`, `updated_at`, a publishing `status`, or a [required](schema.md#fields-and-storage) field of an operational Schema) directly or through FROM subqueries; the right side of a LEFT JOIN, an aggregate, a column beside an aggregate without GROUP BY, a CTE and an expression stay nullable. SQL formats declared date-time/date outputs, while computed timestamps retain driver values. See [native execution](../guides/native-execution.md).
 
 Bare `views/<encoded-name>.ts` returns row arrays. Proved pageable exposed/internal Views also receive native `paged/views/*`, returning `{ rows, nextCursor? }`. Selected REST/MCP boundaries use separate `paged/wire/views/*` SQL when declared integers require exact transport projections; bare modules also export `WireRow`. Indexed ordering after fixed equality prefixes ([index prefixes](schema.md#index-prefixes-for-paged-views)), non-null typed keys, complete groups and singleton joins/lookups are checked at generation. Unsupported internal paging retains its bare View; exposure requires a supported page contract. Aggregates still scan/group their sources: inspect EXPLAIN.
 

package/docs/handbook/releases/index.md

@@ -1,5 +1,5 @@
 ---
-description: Every Mantle release line — what 0.2.0 changes, and what each stable 0.1.x release contained.
+description: Every Mantle release line — what 0.2.x changes, and what each stable 0.1.x release contained.
 ---
 # Releases
 
@@ -15,15 +15,79 @@ From 0.2.0-alpha.7, Mantle publishes three packages together at one version:
 and `@aotter/mantle-admin` (optional Admin server, SPA and MCP App).
 Pin every package you use to the same exact version and upgrade them together.
 
-## 0.2.0 — in preparation
-
-### Upgrading to 0.2.0-alpha.9
+## 0.2.1 — in preparation
+
+0.2.1 adds Schema locks: a manifest rule that refuses a row's update or delete
+for every caller path (REST, MCP, Admin and Procedures), with Admin showing the
+lock before an edit. `spec.publishing.liveEdits` lets an application edit a
+published row in place, and the [revisions guide](../guides/revisions.md) now
+freezes the live revision with a lock and switches it atomically. It also brings
+Admin form and refresh fixes, the media picker for custom inputs and pages
+(`@aotter/mantle-admin/media`), `matchTarget` in `@aotter/mantle/describe`, and
+dependency updates for current advisories.
+
+Procedures gain `handler.steps`: a program written one statement per step, where
+`onNoRows: conflict` makes a set-op write that writes nothing a `CONFLICT` and
+rolls the whole program back ("create only if the parent exists"). Ref handlers
+and interactive transactions can use `store.batch` for atomic multi-writes, and
+`mantle bundle` under `wrangler dev` reports stale generated output in one line
+instead of a failed build.
+
+### Upgrading to 0.2.1-alpha.1
+
+Pin `@aotter/mantle`, and any selected `@aotter/mantle-ui` and
+`@aotter/mantle-admin`, to `0.2.1-alpha.1`, refresh the lockfile, regenerate and
+review owned output. No DDL changes are required. Breaking changes:
+
+- **PostgreSQL `version`:** Store results return `version` as a number, as on
+  SQLite and D1. Procedure results stay driver-native.
+- **Admin record form:** clearing an optional field sends `null`; generated
+  form types for optional fields are `T | null`.
+- **REST route precedence** is fixed and most-specific-first. Only overlapping
+  same-method http Triggers with the same parameter count can change winner.
+  `TRIGGER_PATH_INVALID` and `TRIGGER_PATH_COLLISION` refuse ambiguous paths
+  at generation; see [route precedence](../reference/trigger.md#route-precedence).
+- **Tooling:** the templates move to Wrangler 4.153.0 and
+  `@cloudflare/workers-types` 5.20261027.1.
+- **PostgreSQL serialization failures:** SQLSTATE `40001` and `40P01` from a
+  definitive server refusal are now `CONFLICT` with `kind: "serialization"`
+  (409), instead of an unclassified driver error. Nothing is retried
+  automatically; read again before deciding to retry.
+- **Revisions recipe:** an application that copied the guide's
+  `switch-revision` handler should adopt the new version. It requires
+  `expectedRevisionVersion` from the preview and seals and switches in one
+  `ctx.store.batch`.
+
+## 0.2.0 (2026-10-19)
+
+The first stable native 0.2 release compiles closed v2 manifests to SQL and
+TypeScript for Bun SQLite/PostgreSQL and Cloudflare D1/PostgreSQL. It ships
+three matching packages: Core, the pure UI kit and the optional application-built
+Admin. Applications own routing, verified identity, database handles, migrations
+and deployment; selected REST, MCP, public pages, publishing, translations and
+media compose around the generated operations.
+
+This is a breaking upgrade from 0.1.x: follow the [0.1-to-0.2 migration
+guide](../../upgrade-0.1-to-0.2.md), use a new 0.2 database and explicitly move
+data. From alpha.11, pin the three selected packages to 0.2.0, regenerate and
+review owned output; the stable version commit changes release metadata and
+documentation rather than adding another runtime API.
+
+[GitHub release](https://github.com/aotter/mantle/releases/tag/v0.2.0) is the
+complete change history. Known follow-ups remain tracked: [Admin/authoring
+refinements](https://github.com/aotter/mantle/issues/1752), [production social
+and magic-link recipe verification](https://github.com/aotter/mantle/issues/1273)
+and [real Sites guide verification](https://github.com/aotter/mantle/issues/1272).
+Those provider-specific paths are not claimed as verified by local OTP or
+native-host tests.
+
+### Upgrading to 0.2.0
 
 Pin every selected `@aotter/mantle`, `@aotter/mantle-ui` and
-`@aotter/mantle-admin` dependency to `0.2.0-alpha.9`, refresh the lockfile,
+`@aotter/mantle-admin` dependency to `0.2.0`, refresh the lockfile,
 then regenerate and check the application's owned artifacts. Keep existing
 production migrations application-owned; generated initial DDL is for an empty
-database. This alpha includes breaking Admin authoring and paging changes.
+database. This release includes breaking Admin authoring and paging changes.
 
 1. **Build output and host configuration.** `mantle bundle` writes server
    modules to `dist/worker` and static files to `dist/client`, including
@@ -112,7 +176,7 @@ Existing alpha.6 applications require a source migration:
   application code. Review [authorization and Caller wiring](../concepts/runtime-and-adapters.md)
   and regenerate all owned artifacts before running `generate --check`.
 
-The [reference Worker](https://github.com/aotter/mantle/tree/v0.2.0-alpha.9/docs/examples/reference-service) and
+The [reference Worker](https://github.com/aotter/mantle/tree/v0.2.0/docs/examples/reference-service) and
 [app shell](../../examples/app-shell/) demonstrate the current composition.
 The following earlier-alpha notes are historical; the current handbook and
 the native migration above supersede their runtime and CLI instructions.