@aotter/mantle 0.1.5-alpha.1 → 0.2.0-alpha.1

package/docs/handbook/reference/manifest.md

@@ -1,134 +1,74 @@
 ---
-description: Envelope fields, unknown-key policy, multi-document YAML, LocalizedText, naming rules and reserved names shared by every Manifest kind.
+description: The manifest envelope of Mantle 0.2.0 — apiVersion, kind, metadata, files and documents, names, localized text, and the SQL naming conventions every atom shares.
 ---
 # Manifest envelope and conventions
 
-This page covers the rules that apply to every Manifest document before kind-specific validation runs. Read it once; the four atom pages ([Schema](./schema.md), [View](./view.md), [Procedure](./procedure.md), [Trigger](./trigger.md)) assume it. Diagnostic codes named here are catalogued in [Diagnostics](./diagnostics.md).
+```yaml
+apiVersion: cms.mantle.aotter.net/v2
+kind: Schema            # Schema | View | Procedure | Trigger
+metadata:
+  name: orders          # required, unique per kind
+spec: { … }             # kind-specific
+```
+
+- `apiVersion` is exactly `cms.mantle.aotter.net/v2`. A `v1` document fails
+  and names the upgrade guide.
+- `metadata` has `name` only.
+- Unknown keys anywhere in `spec` are refused, not ignored.
+
+## Files
+
+`mantle generate` reads every `.yaml` and `.yml` file directly in the manifest
+directory (`./manifests`, or `--manifests <dir>`), not subdirectories. A file
+may hold several documents separated by `---`. File names and order do not
+matter to the plan; they enter only `sourceHash`.
 
-For a task-to-field table covering all four atoms, see the [Manifest feature reference](./features.md). For the resulting console, see [Customize Admin](../guides/admin-ui.md).
+## Names
 
-## Envelope
+- Names are unique per kind (`DUPLICATE_NAME`). Two Schemas, or two fields of
+  one Schema, may not differ only in case: SQL resolves identifiers
+  case-insensitively.
+- A Schema name that is not a plain identifier (`support-tickets`) is written
+  quoted in SQL: `"support-tickets"`.
+- `input` and `auth` are reserved and cannot name a Schema or an alias. On
+  the `sqlite` dialect, SQL may not name a Schema, field or alias that is one
+  of the 14 words SQLite refuses unquoted (`SQL_UNSUPPORTED`):
+  `add alter autoincrement commit delete drop escape index insert nothing raise set transaction update`.
+- MCP tool names are the View or Procedure name in snake case.
 
-Every document is a YAML mapping with exactly four top-level keys.
+## Localized text
+
+`title` and `description` on every atom, and `title` and `description` on
+JSON Schema properties, take a string or a locale map:
 
 ```yaml
-apiVersion: cms.mantle.aotter.net/v1
-kind: Schema | View | Procedure | Trigger
-metadata:
-  name: posts
-spec:
-  # kind-specific
+title: { en: Products, zh-TW: 商品 }
 ```
 
-| Field | Type | Required | Rules |
-|---|---|---|---|
-| `apiVersion` | literal | yes | Exactly `cms.mantle.aotter.net/v1`. Anything else is `INVALID_MANIFEST_ENVELOPE` at `/apiVersion`. |
-| `kind` | enum | yes | `Schema`, `View`, `Procedure` or `Trigger`. |
-| `metadata` | mapping | yes | Only the key `name` is accepted. There is no `namespace`. |
-| `metadata.name` | string | yes | Non-empty. Unique within its kind (`DUPLICATE_NAME`, one diagnostic per occurrence). A Schema and a View may share a name. |
-| `spec` | mapping | yes | Kind-specific; see the atom pages. |
+Admin chooses the viewer's locale and MCP the surface's `locale` option (default `en`), then `en`, then the first entry.
 
-A document that is not a mapping is rejected with `manifest must be a YAML mapping`.
+## SQL conventions
 
-## Unknown-key policy
+| | |
+|---|---|
+| Syntax | PostgreSQL, parsed by PostgreSQL 18's parser; a dialect decides what runs |
+| Native columns | snake_case in SQL: `id`, `status`, `version`, `created_at`, `updated_at`, `author_id`. In `ctx.store` JSON, in `indexes` and in Schema `uiSchema`: `createdAt`, `updatedAt`, `authorId` |
+| References | `input.<name>`, `auth.uid()`, `auth.role()`, `now()` |
+| Mantle functions | `mantle.search`, `mantle.search_rank`, `mantle.near`, `mantle.distance` |
+| Literals | SQL literals; strings in single quotes |
+| Multi-line SQL | a YAML block scalar (`sql: \|`) |
 
-The parser rejects keys outside the shipped grammar at every level it knows. The diagnostic is `INVALID_MANIFEST_ENVELOPE` with the message `<dotted.path> is not supported` and a JSON Pointer to the offending key (for example `spec.foo is not supported` at `/spec/foo`). Enum values outside the grammar are rejected the same way.
+## Wire values
 
-| Pointer | Allowed keys |
+| JSON Schema | On the wire |
 |---|---|
-| `/` | `apiVersion`, `kind`, `metadata`, `spec` |
-| `/metadata` | `name` |
-| `/spec` (Schema) | `title`, `description`, `schema`, `uiSchema`, `uniqueIndexes`, `indexes`, `searchableFields`, `localized`, `translates`, `lifecycle` |
-| `/spec` (View) | `title`, `uiSchema`, `from`, `sql`, `surface`, `cache`, `requires`, `filter`, `fields`, `orderBy`, `limit`, `params` |
-| `/spec` (Procedure) | `title`, `description`, `requires`, `input`, `uiSchema`, `output`, `handler`, `mcp` |
-| `/spec` (Trigger) | `source`, `target` |
-| `/spec/translates` | `parent`, `on` |
-| `/spec/requires` | `auth`, `guard` |
-| `/spec/requires/auth` | `all` |
-| `/spec/requires/guard` | `procedure` |
-| `/spec/requires/auth/all/<i>` (object form) | exactly one of `ctx.staff`, `ctx.auth.scope` |
-| `/spec/handler` (`kind: ref`) | `kind`, `ref` |
-| `/spec/handler` (`kind: builtin`) | `kind`, `op`, `schema`, `match` |
-| `/spec/filter/<op>` | `field`, `value` |
-| `/spec/orderBy/<i>` | `field`, `direction` |
-| `/spec/cache` (View) | `sharedMaxAge` |
-| `/spec/source` (`kind: http`) | `kind`, `method`, `path` |
-| `/spec/source` (`kind: lifecycle`) | `kind`, `schema`, `on`, `errorPolicy` |
-| `/spec/source` (`kind: mcp`) | `kind`, `surface` |
-| `/spec/target` | `procedure` |
-| `/spec/uiSchema` (View) | `list` (only on `surface: staff`; violations are `VIEW_UI_INVALID`) |
-| `/spec/uiSchema/list` (View) | `columns`, `searchFields`, `filterFields` |
-| `/spec/uiSchema` (Schema) | `fields`, `list`, `nav` |
-| `/spec/uiSchema/list` (Schema) | `filterField`, `primaryField`, `columns` |
-| `/spec/uiSchema/nav` (Schema) | `standalone`, `parentField` |
-| `/spec/uiSchema` (Procedure) | `collectionAction`, `fields` |
-
-`uiSchema` roots are closed. Schema accepts `fields`, `list`, and `nav`; Procedure accepts `collectionAction` and `fields`; View accepts `list` on `surface: staff`. Nested keys are closed. A Schema that declares `uiSchema.collectionAction` is rejected with `SCHEMA_UI_INVALID`. JSON Schema documents inside `spec.schema`, `spec.input`, `spec.output` and `spec.params` follow the [JSON Schema subset](./schema.md#json-schema-subset) instead of an allowlist.
-
-## Multi-document YAML and sources
-
-The parser consumes a set of sources, each `{ sourceId, text }`. The CLI builds this set from the immediate `.yaml` and `.yml` files of the manifests directory, sorted lexicographically, with the file path as `sourceId`; an unreadable or empty directory is `MANIFEST_ROOT_NOT_FOUND`. Nested directories are not read.
-
-Within one source:
-
-- `---` separates documents. A feature commonly bundles a Procedure and its Triggers in one file.
-- YAML merge keys (`<<`) are disabled.
-- Alias expansion is capped at 100 aliases per document. Exceeding the cap is `INVALID_MANIFEST_ENVELOPE` with the message `YAML alias-expansion limit exceeded`.
-- Empty or `null` documents are skipped.
-- A YAML syntax error is `INVALID_MANIFEST_ENVELOPE` at `/`, prefixed `[doc <index>]`.
-
-Parsing is all-or-nothing. Any error-severity diagnostic in any document withholds the whole parsed set; later stages never see a partial graph. Every diagnostic carries `source: { sourceId, documentIndex, path }` plus a line and column span when the YAML node is known.
-
-## LocalizedText
-
-`Schema.spec.title` (required), `Schema.spec.description`, `View.spec.title`, `Procedure.spec.title` and `Procedure.spec.description` accept either a plain string or a locale map.
+| `format: date-time`, and the native `createdAt` / `updatedAt` | an ISO 8601 string |
+| `format: date` | `YYYY-MM-DD` |
+| `boolean` | `true` / `false` |
+| `object`, `array` | JSON |
 
-```yaml
-title: Products
-# or
-title: { en: Products, "zh-TW": 商品 }
-```
+## Generated output
 
-The parser rejects an empty string, an empty map `{}`, an array, an empty locale key and any non-string or empty value. JSON Schema property `title` and `description` keywords accept the same shape for Admin labels and help text; MCP tool schemas collapse them to the `en` value.
-
-Resolution order (`resolveLocalizedText`): the viewer's preferred locale, then the site's canonical locale, then the first key in insertion order. A value that was never set resolves to `null`.
-
-## Naming rules for `metadata.name`
-
-| Rule | Applies to | Diagnostic |
-|---|---|---|
-| Non-empty string, unique within the kind. | all kinds | `DUPLICATE_NAME` |
-| Must match `/^[A-Za-z][A-Za-z0-9_.-]*$/` when the Schema declares any `indexes` or `uniqueIndexes`. | Schema | `SCHEMA_INDEX_INVALID` at `/metadata/name` |
-| Unique after MCP mangling (`mcpToolNameSegment`: lower-case, `-` becomes `_`). Two Schemas, or two Views, that mangle to the same segment collide. | Schema, View | `MCP_TOOL_NAME_COLLISION` |
-| A Procedure's mangled name must not equal a reserved generic tool name, start with a reserved tool prefix, equal a Schema's mangled segment, or equal another Procedure's mangled name. | Procedure | `MCP_TOOL_NAME_COLLISION` |
-| One MCP Trigger per `(surface, tool name)`. | Trigger | `MCP_TOOL_NAME_COLLISION` |
-| Unique lower-camel identifier within each group (`entries`, `views`, `procedures`, `triggers`) when running `mantle generate`. The identifier joins the `[A-Za-z0-9]+` runs of the name, lower-casing the first and capitalising the rest; `my-orders` and `My Orders` both become `myOrders`. | all kinds | `CODEGEN_IDENTIFIER_COLLISION` |
-
-Names containing `-` must be double-quoted when used as tables in a `sql` View (`"post-translations"`).
-
-## Reserved names
-
-| Namespace | Reserved | Effect |
-|---|---|---|
-| Entry columns | `id`, `status`, `version`, `createdAt`, `updatedAt`, `authorId` | Native on every Schema; a data property may not reuse the name (`INVALID_MANIFEST_ENVELOPE`). Where they may appear in Views and indexes: [Schema reference](./schema.md#reserved-entry-columns) (ADR-0025). |
-| Data field | `locale` | A non-localized Schema that declares `properties.locale` is rejected; use a domain name such as `orderLocale`. On a localized Schema the runtime requires `data.locale` on writes. |
-| Data field | `expectedVersion` | Reserved Procedure OCC wire name. A Schema that declares `spec.schema.properties.expectedVersion` is `INVALID_MANIFEST_ENVELOPE` (ADR-0022). New reserved names need an ADR. |
-| View params | `page`, `show`, `cursor` | Owned by the runtime for pagination. Declaring them under `params.properties` is `VIEW_PARAMS_RESERVED_NAME`. |
-| Builtin input | `id`, `expectedVersion` | Contract fields for builtin `update`, `delete`, `archive`, and version-checked `upsert`. `expectedVersion` is the observed native `entry.version` at read time (not `version+1`). Matched upsert must declare it as a strict number and must not declare `id`. New reserved wire names need an ADR. |
-| MCP tool names | `request_publish`, `unpublish_entry`, `archive_entry`, `delete_entry`, `create_media_upload`, `commit_media_upload` | A Procedure that mangles to one of these is `MCP_TOOL_NAME_COLLISION`. |
-| MCP tool prefixes | `create_draft_`, `update_draft_`, `create_record_`, `update_record_`, `query_view_` | Same as above. |
-| HTTP paths | Every `http` Trigger path must start with `/api/` (`TRIGGER_PATH_INVALID` at validate time). The Cloudflare Worker additionally reserves `/admin`, `/_mantle`, `/api/auth`, `/api/views`, `/oauth`, `/mcp`, any path starting `/.well-known/oauth`, and the exact registrations `*` and `/*`; a Trigger under one of these fails at boot with `TRIGGER_PATH_INVALID`. | See [Trigger](./trigger.md#http-source). |
-
-## Source
-
-- [`packages/mantle-spec/src/domain/model/ManifestGrammar.ts`](../../../packages/mantle-spec/src/domain/model/ManifestGrammar.ts)
-- [`packages/mantle-spec/src/domain/service/ManifestParser.ts`](../../../packages/mantle-spec/src/domain/service/ManifestParser.ts)
-- [`packages/mantle-spec/src/domain/service/ManifestGraphValidator.ts`](../../../packages/mantle-spec/src/domain/service/ManifestGraphValidator.ts)
-- [`packages/mantle-spec/src/domain/service/SchemaIndexChecker.ts`](../../../packages/mantle-spec/src/domain/service/SchemaIndexChecker.ts)
-- [`packages/mantle-spec/src/domain/service/SchemaAdminUiChecker.ts`](../../../packages/mantle-spec/src/domain/service/SchemaAdminUiChecker.ts)
-- [`packages/mantle-spec/src/domain/service/McpToolNaming.ts`](../../../packages/mantle-spec/src/domain/service/McpToolNaming.ts)
-- [`packages/mantle-spec/src/infrastructure/cli/loadManifests.ts`](../../../packages/mantle-spec/src/infrastructure/cli/loadManifests.ts)
-- [`packages/mantle-spec/src/kernel/diagnostic.ts`](../../../packages/mantle-spec/src/kernel/diagnostic.ts)
-- [`packages/mantle/src/codegen/emitMantleModule.ts`](../../../packages/mantle/src/codegen/emitMantleModule.ts)
-- [`packages/mantle-runtime/src/usecase/boot/ValidateBootUseCase.ts`](../../../packages/mantle-runtime/src/usecase/boot/ValidateBootUseCase.ts)
-- [`packages/adapters/cloudflare/src/worker/createMantleWorker.ts`](../../../packages/adapters/cloudflare/src/worker/createMantleWorker.ts)
+`plan.json` and `mantle.ts` under `.mantle/generated/` are rewritten by every
+`mantle generate` and compared by `--check`. Commit them; never edit them. See
+[Project layout and CLI](../start/project-and-cli.md).

package/docs/handbook/reference/procedure.md

@@ -1,315 +1,127 @@
 ---
-description: Procedure field reference — runtime order of operations, ref and builtin handlers, the builtin op contract, EntryRow responses and Admin operations.
+description: Procedure field reference for Mantle 0.2.0 — input and output, SQL and ref handlers, write rules, row ops and locks, target, mcp annotations, uiSchema and diagnostics.
 ---
 # Procedure
 
-A Procedure is a typed callable: input schema, output schema, authorization requirement, and one handler binding. It is the only atom with a code seam, and it is never exposed on its own — a [Trigger](./trigger.md) is what makes it reachable. This page is the field-level contract; the concepts are in [Procedures and Triggers](../concepts/procedures-and-triggers.md). Envelope rules are in [Manifest envelope and conventions](./manifest.md), and diagnostic codes are catalogued in [Diagnostics](./diagnostics.md).
-
-## Fields
-
-| Field | Type | Required | Rules |
-|---|---|---|---|
-| `title` | LocalizedText | no | Admin label for the staff-operations surface. Absent falls back to a Title-Cased `metadata.name`. |
-| `description` | LocalizedText | no | The MCP tool description and the `description` field of `GET /admin/api/operations`. |
-| `requires` | AuthorizationRequirements | no | `auth.all` predicates plus one optional `guard.procedure`. See [Authorization](./authorization.md). |
-| `input` | JSON Schema | yes | Must be an object. Becomes the MCP tool `inputSchema` and the OpenAPI request body. |
-| `uiSchema` | object | no | Admin-only. Accepts `collectionAction` and `fields`. Violations are `SCHEMA_UI_INVALID`. |
-| `output` | JSON Schema | yes | Checked after the handler returns. Failure is `OUTPUT_VALIDATION_FAILED` (500). |
-| `handler` | `ref` \| `builtin` | yes | Exactly one binding shape; see below. |
-| `mcp` | object | no | MCP tool annotations the author asserts: `readOnlyHint`, `destructiveHint`, `openWorldHint` (booleans). Core infers what it can prove — every builtin handler writes, `op: delete` destroys, an `x-mcp-hint: idempotency-key` input makes the tool idempotent — and emits nothing else, so absent hints keep the MCP spec's conservative defaults. `readOnlyHint: true` on a builtin handler is `BUILTIN_HANDLER_CONTRACT_INVALID`. |
-
-Both `input` and `output` are walked by the [JSON Schema subset](./schema.md#json-schema-subset) validator, so the same recognized and rejected keywords apply.
-
-## Order of operations
-
-Every invocation — HTTP Trigger, MCP tool call, lifecycle hook, Admin operation — runs the same pipeline.
-
-| Step | Behavior | Failure |
-|---|---|---|
-| 1. Authorize | Evaluate every `requires.auth.all` predicate against the caller context. | `UNAUTHENTICATED` (401) when the caller carried no credential, `AUTH_DENIED` (403) when an authenticated caller falls short. |
-| 2. Validate input | Compile `input` to zod and parse the request. | `INPUT_VALIDATION_FAILED` (400), pointing at the first failing property. |
-| 3. Guard | Invoke `requires.guard.procedure` with the validated input and the same context. | Any guard failure denies the target. Guards fail closed. |
-| 4. Dispatch | `ref`: look up the registration key and call the function. `builtin`: run the op. | See the two handler sections. |
-| 5. Validate output | Parse the handler result against `output`. | `OUTPUT_VALIDATION_FAILED` (500) — this is a handler bug, not a caller error. |
-
-The value returned to the caller is the handler's own result. Output validation checks it; it does not strip unexpected fields.
-
-## `handler.kind: ref`
-
-```yaml
-handler:
-  kind: ref
-  ref: approve-purchase-order
-```
-
-`ref` is an **opaque registration key, not a path**. It never names a file, module or export. The consumer passes a matching key in the `handlers` map given to the runtime or Worker, and the key is the whole contract between manifest and code.
-
-| Rule | Effect |
-|---|---|
-| `ref` is a non-empty string; only `kind` and `ref` are accepted under `handler`. | `INVALID_MANIFEST_ENVELOPE` |
-| Every declared `ref` resolves to a registered handler. | `HANDLER_NOT_REGISTERED` at boot, listing the registered keys as candidates. |
-| An unregistered key reached at request time. | The same `HANDLER_NOT_REGISTERED` code, mapped to 500 — defense in depth for embeddings that skipped boot validation. |
-| A handler throws. | Anything other than a structured error becomes `INTERNAL_ERROR` (500) with a safe generic message; exception details remain in internal logs. |
-
-To return a structured error instead, throw `InvokeFailure` carrying a diagnostic; the runtime unwraps it and returns that diagnostic with its own status. This is how a handler reports `CONFLICT`, `ENTITLEMENT_REQUIRED` or a domain-specific `INPUT_VALIDATION_FAILED` rather than a generic 500.
-
-### `ref` example
-
 ```yaml
-apiVersion: cms.mantle.aotter.net/v1
+apiVersion: cms.mantle.aotter.net/v2
 kind: Procedure
-metadata:
-  name: approve-purchase-order
+metadata: { name: review-order }
 spec:
-  title: { en: Approve purchase order, "zh-TW": 核准採購單 }
-  description: Approve a submitted order and record the approver.
-  requires:
-    auth:
-      all:
-        - { "ctx.staff": [owner, editor] }
-  input:
-    type: object
-    additionalProperties: false
-    required: [orderId, decision]
-    properties:
-      orderId: { type: string, x-mantle-ref: purchase-orders }
-      decision: { type: string, enum: [approve, reject] }
-      note: { type: string, maxLength: 2000 }
-      requestId: { type: string, x-mcp-hint: idempotency-key }
-  uiSchema:
-    fields:
-      note: { widget: textarea }
-  output:
-    type: object
-    required: [orderId, status]
-    properties:
-      orderId: { type: string }
-      status: { type: string, enum: [approved, rejected] }
-  handler:
-    kind: ref
-    ref: approve-purchase-order
+  title: Review order                 # optional, a string or a locale map
+  description: …                      # optional; the MCP tool's and Admin operation's description
+  requires: { … }                     # optional, see Authorization requirements
+  input: { type: object, … }          # required JSON Schema
+  output: { type: object }            # required JSON Schema
+  handler: { sql: "…" }               # or { ref: <name> }
+  target: { schema, id, version? }    # optional; inferred for one locked row op
+  mcp: { destructiveHint: true }      # optional tool annotations
+  uiSchema: { … }                     # optional, Admin only
 ```
 
-```ts
-// src/mantle/config.ts
-import { approvePurchaseOrder } from "./handlers/approve-purchase-order";
-
-export const handlers = {
-  "approve-purchase-order": approvePurchaseOrder,
-};
-```
+`input` is validated before the handler runs (`INPUT_VALIDATION_FAILED`),
+and the result against `output` (`OUTPUT_VALIDATION_FAILED`, a 500: the bug
+is the handler's). `expectedVersion` is the conventional input name for the
+version a caller read.
 
-## `handler.kind: builtin`
+## `handler.sql`
 
-A shortcut over the entry-writer chokepoint for Procedures whose body is "write a row". Reach for `ref` as soon as there is real business logic.
+One or more `INSERT`, `UPDATE` and `DELETE` statements separated by `;`,
+applied as one batch: all or nothing, in order. The output is
+`{ "results": [[…], …] }`, the `RETURNING` rows of each statement in order; so
+an `output` of `{ type: object }` accepts it.
 
-```yaml
-handler:
-  kind: builtin
-  op: create | update | upsert | delete | archive
-  schema: <Schema metadata.name>
-  match: [<field>, ...]   # only with op: upsert
-```
-
-| Rule | Diagnostic |
+| Statement | Supported |
 |---|---|
-| Only `kind`, `op`, `schema` and `match` are accepted; `ref` alongside `builtin` is rejected. | `INVALID_MANIFEST_ENVELOPE` |
-| `op` is one of the five; `schema` is a non-empty string. | `INVALID_MANIFEST_ENVELOPE` |
-| `match` appears only with `op: upsert`, and is a non-empty array of unique non-empty strings. | `INVALID_MANIFEST_ENVELOPE` |
-| `schema` names a declared Schema. | `BUILTIN_HANDLER_SCHEMA_UNKNOWN` |
-| `input` is an object schema. | `BUILTIN_HANDLER_CONTRACT_INVALID` |
-| The runtime was built without the builtin dispatcher. | `HANDLER_BUILTIN_NOT_IN_V010` at request time. |
+| `INSERT` | `INSERT INTO t (cols) VALUES (…)` (one row), `INSERT INTO t (cols) SELECT …`, `ON CONFLICT (cols) DO NOTHING \| DO UPDATE SET c = EXCLUDED.c …`, `RETURNING` |
+| `UPDATE` | `UPDATE t SET c = <expr> … WHERE …`, `RETURNING` |
+| `DELETE` | `DELETE FROM t WHERE …`, `RETURNING` |
 
-`request_publish` and `publish` are deliberately absent: they are lifecycle operations, not CRUD primitives.
+Expressions are those of [View SQL](./view.md#what-the-d1-dialect-accepts).
+References: `input.<name>`, `auth.uid()`, `auth.role()`, `now()`.
 
-### Ops
+**A write may not name** the scope field, `version`, `status`, `created_at`,
+`updated_at`, `author_id`, or `id` in an `UPDATE`, in a column list, `SET` or
+`DO UPDATE SET`; on a scoped Schema an `INSERT` names no `id`. Store fills
+them (`SQL_WRITE`). Multi-row `VALUES` is refused: insert from
+`json_each(input.items)` instead. `UPDATE … FROM`, `DELETE … USING`,
+`INSERT OR …` and `last_insert_rowid()` are refused.
 
-| `op` | Runtime behavior | Input contract |
-|---|---|---|
-| `create` | Projects `input ∩ Schema.properties` into `data`, stamps every `x-mantle-bind` property, generates an id and writes. `status` is `draft`, or `published` on a `lifecycle: operational` Schema. `authorId` is `ctx.user?.id ?? null`. Returns the created row. | `input` is an object schema. No other required properties. |
-| `update` | Loads the row (`NOT_FOUND` if absent), merges the patch over the stored `data` so omitted fields and existing stamps survive, writes under optimistic concurrency against the caller's `expectedVersion` (observed native `entry.version` at read time, not `version+1`), bumps `version`. | `id` (strict `type: string`) and `expectedVersion` (strict `type: number`) declared under `properties` **and** listed in `required`. |
-| `upsert` with `match` | Reads the matched fields off the validated input and looks the row up by those data values. Found: the update path, using the **caller's** `expectedVersion` (never the preloaded row's version). Not found: the create path only when `expectedVersion` is omitted; a versioned write for a missing row is `NOT_FOUND` and does not recreate. | `match` equals one declared `uniqueIndexes` tuple exactly, in order. Every matched field is a Schema property, is declared in `input.properties`, and appears in `input.required`. `input` must **not** declare `id`. `expectedVersion` **must** be declared as strict `number`; it is not globally required so create can omit it. |
-| `upsert` without `match` | Id-based upsert. Create when the caller omits `expectedVersion` (and either omits `id` or the id is unknown). Update when a resolved `id` is present — the caller token is required and is the OCC check. A versioned write for a missing id is `NOT_FOUND`. | `expectedVersion` must be declared as strict `number`. If `id` is declared it must be strict `string`. Neither is in `required`. |
-| `delete` | Loads the row (`NOT_FOUND` if absent), runs the delete guard, then hard-deletes pinned to the row's status and version. Returns `{ removed }`. | `id` (strict `type: string`) declared and in `required`. |
-| `archive` | Loads the row, checks the lifecycle state machine (`CONFLICT` on an illegal transition), then transitions to `archived` pinned to the version just read. | `id` (strict `type: string`) declared and in `required`. The target Schema must be `lifecycle: publishing`; an operational target is rejected. |
+**RETURNING names** fold to lower case unless quoted:
+`RETURNING id, orderNumber AS "orderNumber"`.
 
-Every contract violation in the right-hand column is `BUILTIN_HANDLER_CONTRACT_INVALID`, reported at the offending pointer. *Strict* means a single scalar type — an array-valued `type` or `nullable: true` does not satisfy it.
+### Row ops and set ops
 
-All five ops write through the same chokepoint, which validates the projected `data` against the Schema, runs the [write-time locale gate](./schema.md#write-time-locale-gate) and performs a unique-index preflight before the write.
+- **Row op**: an `UPDATE` or `DELETE` whose top-level `WHERE` has
+  `id = <value>`, or a one-row `INSERT … VALUES` without `ON CONFLICT`. If it
+  writes no row the batch fails with `CONFLICT` and nothing applies.
+- **Set op**: everything else. Writing no row is a normal result. Refused on a
+  `publishing` Schema, and on a Schema with a `before_*` hook for that
+  operation.
+- **Lock**: `AND version = input.<name>` in a row op's `WHERE`. A stale version
+  matches nothing, so it is `CONFLICT` (HTTP 409).
 
-### Side-channel input fields
+### `target`
 
-`input` is the contract with the *caller*, not with the Schema. It may declare fields the collection has no column for — a CAPTCHA token, an idempotency key, a routing hint. JSON Schema's default `additionalProperties: true` lets them validate, and the builtin op projects `input ∩ Schema.properties`, so they never reach `data`.
+`{ schema, id, version? }`: the Schema the Procedure mutates, the required
+string input holding the row id, and the integer input holding the version it
+locks. Admin binds an operation to a row by it. A Procedure whose SQL is
+exactly one row op pinning `id` (and `version`) to inputs gets it inferred;
+declare it for a `ref` handler. `PROCEDURE_TARGET_INVALID` when the inputs do
+not have those shapes.
 
-They are not lost. The pre-projection input travels to the chokepoint as `originalInput`, and synchronous `before_*` lifecycle hooks receive it as their handler input. A `before_create` hook can therefore verify a token the row never stores. See [Trigger](./trigger.md#lifecycle-source).
-
-### Builtin `upsert` example
+## `handler.ref`
 
 ```yaml
-apiVersion: cms.mantle.aotter.net/v1
-kind: Procedure
-metadata:
-  name: sync-inventory-level
-spec:
-  title: Sync inventory level
-  description: Insert or update the stock level for one SKU in one warehouse.
-  requires:
-    auth:
-      all:
-        - ctx.auth
-        - { "ctx.auth.scope": "inventory:write" }
-  input:
-    type: object
-    required: [sku, warehouse, onHand]
-    properties:
-      sku: { type: string, minLength: 1 }
-      warehouse: { type: string, minLength: 1 }
-      onHand: { type: integer, minimum: 0 }
-      countedAt: { type: integer, x-mcp-hint: timestamp-ms }
-      requestId: { type: string, x-mcp-hint: idempotency-key }
-      expectedVersion: { type: number }
-  output:
-    type: object
-    required: [id, version]
-    properties:
-      id: { type: string }
-      version: { type: number }
-  handler:
-    kind: builtin
-    op: upsert
-    schema: inventory-levels
-    match: [sku, warehouse]
+handler: { ref: cancelOrder }
 ```
 
-This requires `inventory-levels` to declare `uniqueIndexes: [[sku, warehouse]]` — the same fields, in the same order. `requestId` is a side-channel field: it validates, reaches `before_*` hooks, and is never written to `data`. `expectedVersion` is the observed native `entry.version` at read time (not `version+1`). Omit it to create; send it to update. First-party Admin binds and hides it; HTTP and MCP callers supply it themselves.
-
-## The response shape
-
-Every builtin op except `delete` returns the persisted `EntryRow`.
-
-| Field | Type | Notes |
-|---|---|---|
-| `id` | string | Generated on create. |
-| `collection` | string | The Schema's `metadata.name`. |
-| `status` | `draft` \| `published` \| `archived` | |
-| `version` | number | Optimistic-concurrency counter; bumps on every persisted update. |
-| `data` | object | The projected, stamped Schema fields. |
-| `authorId` | string \| null | |
-| `createdAt`, `updatedAt` | number | Unix epoch milliseconds. |
-| `locale` | string | Present only when the row carries `data.locale`. |
-
-An HTTP Trigger wraps a success as `{ "ok": true, "data": <EntryRow> }` with status 200.
-
-> **Warning**
-> Declare `output` against the **row**, not the envelope. `output: { type: object, required: [id], properties: { id: { type: string } } }` checks that an id came back. Output validation does not strip the other fields, so a caller still receives the whole row; use a `ref` handler with an explicit projection when the response must be smaller.
-
-`delete` returns `{ removed: boolean }` instead.
-
-## Conflicts and idempotency
-
-A unique-index preflight runs before individual writes, and the database's own constraints catch the races the preflight misses. Atomic groups rely on the transaction's database constraints so an earlier operation may free a unique value for a later one. Both paths surface collisions as `CONFLICT` (409), as do a stale `expectedVersion` and an illegal lifecycle transition. **There is no automatic retry** — the caller decides whether to re-read and try again.
-
-Idempotency has no grammar key. The convention is an `input` property marked `x-mcp-hint: idempotency-key`: Admin generates and hides one UUID per form submission, and other callers generate one and reuse it across retries of the same logical request. The handler is responsible for acting on it.
-
-Optimistic concurrency uses the reserved input name `expectedVersion` — the version the caller **read**, not the next version. First-party Admin and SDK bind-and-hide that property from the OCC target row; other callers send it themselves. There is no `x-mcp-hint` for OCC. On `CONFLICT` (409) Admin keeps the operator's business fields and requires an explicit re-read; it does not retry with the latest version. New reserved Procedure input names need an ADR.
-
-Deferred lifecycle hooks have a stronger guarantee to work with: delivery is at-least-once, and handlers key on `${ctx.event.id}:${ctx.event.trigger}` — stable across enqueue fallback, queue retries and replay. See [Deferred hooks on Queues](../cloudflare/deferred-hooks-queues.md).
-
-## Atomic entry writes in a ref handler
-
-When one request must change several Schemas together, a `ref` handler can call
-`ctx.writeAtomically(operations)`. Cloudflare D1 and Bun SQLite support it; an
-adapter without the optional `atomicEntries` capability returns
-`RESOURCE_UNAVAILABLE` (503)
-instead of committing part of the group. Operations use the `createDraft`,
-`updateDraft`, or `deleteEntry` request shape; atomic deletes additionally
-require `expectedVersion`. Operational Schemas become live on create;
-publishing Schemas create drafts. Updates and deletes require the version the
-caller read.
+The name of a function in the service's `handlers` map. The generated
+`MantleHandlers` type lists exactly the plan's refs, with typed input and
+output; boot refuses a missing one (`HANDLER_NOT_REGISTERED`) and an extra
+one (`HANDLER_NOT_DECLARED`).
 
 ```ts
-const sessionId = crypto.randomUUID();
-const rows = await ctx.writeAtomically!([
-  { kind: "create", id: sessionId, request: {
-    collection: "sessions", data: { name: input.name }, authorId: ctx.user?.id ?? null, ctx,
-  } },
-  { kind: "create", request: {
-    collection: "exercise-blocks", data: { sessionId, exercise: input.exercise },
-    authorId: ctx.user?.id ?? null, ctx,
-  } },
-  { kind: "create", request: {
-    collection: "receipts", data: { token: input.requestId }, authorId: ctx.user?.id ?? null, ctx,
-  } },
-]);
-return { sessionId: rows[0]!.id };
+(input, ctx) => output | Promise<output>
+// ctx: { caller, cause, store, invoke, env, waitUntil }
 ```
 
-Declare `receipts.token` as a Schema `uniqueIndexes: [[token]]`. A duplicate
-receipt rejects the whole group, including the session and block. The handler
-can then read the existing receipt **after** the failed transaction to answer
-an idempotent retry. A stale update or delete rejects the whole group even
-when it is the final operation. The group may touch each entry only once;
-read and authorization decisions happen before the batch, and the expected
-version/status is checked again by the conditional database write.
+A handler reaches Mantle-owned rows only through `ctx.store`
+([Query from TypeScript](../guides/typed-queries.md)). It throws
+`DiagnosticError` (from `@aotter/mantle`) to answer with a code; any
+other throw is logged and answered as `INTERNAL_ERROR`. Guards, before hooks
+and lifecycle targets must be `ref` handlers.
 
-All Schema projection, stamping, validation, uniqueness, and lifecycle rules
-still apply. `before_*` hooks run in operation order before the batch and can
-veto it; their external effects cannot be rolled back. `after_*` hooks run
-only after commit, in operation order. Publishing-content invalidation runs
-once for the group. Deferred Queue delivery is separate from the database
-transaction. Application-owned tables can use their host's transaction
-facility inside a ref handler, but that does not give those tables Mantle
-entry semantics. Direct SQL writes to Mantle Schema tables are unsupported.
-Authorization guard Procedures do not receive `ctx.writeAtomically`.
+## `requires`
 
-## TTL sweep in a ref handler
+`requires.auth.all` (predicates) and `requires.guard.procedure` (a `ref`
+Procedure run before this one). See
+[Authorization requirements](./authorization.md).
 
-`ctx.sweepExpired({ collection, limit })` previews a bounded page of expired rows; `delete: true` explicitly removes it. The result contains `scanned`, `removed` and an optional `nextCursor`. Continue with that cursor until absent. D1 and Bun SQLite implement this semantic capability; unsupported storage returns `RESOURCE_UNAVAILABLE`. Authorization guard Procedures do not receive the sweep function. For a scheduled cleanup, declare a [schedule Trigger](./trigger.md#schedule-source) targeting a no-input ref Procedure. No sweep is scheduled automatically. See [Schema TTL](./schema.md#ttl).
+## `mcp`
 
-## `uiSchema`
-
-Admin presentation only. It never affects input validation, the MCP tool schema or the OpenAPI document. Roots are closed: `collectionAction` and `fields`.
-
-| Key | Rule |
-|---|---|
-| `collectionAction` | A declared Schema name. Admin offers the Procedure as an action on that collection's list page. A non-empty string that names no Schema is `SCHEMA_UI_INVALID`; a Schema that declares `collectionAction` is rejected outright. |
-| `fields.<field>.widget` | Only `textarea`. `<field>` must be a top-level property of `input` with a string type. Anything else is `SCHEMA_UI_INVALID`. |
+`readOnlyHint`, `destructiveHint`, `openWorldHint` (booleans), copied onto the
+MCP tool. `readOnlyHint` and `destructiveHint` may not both be true, and a SQL
+handler, which always writes, may not claim `readOnlyHint: true`.
 
-## Staff operations in Admin
-
-Admin derives its operations surface from the manifest graph — there is no extra grammar. A Procedure is staff-operable when **either** condition holds:
-
-1. Some Trigger targets it with `source.kind: mcp` and `source.surface: staff` — the same predicate that builds the `/mcp/staff` tool catalog.
-2. Some Trigger targets it with `source.kind: http` **and** the Procedure's `requires.auth.all` includes a `ctx.staff` predicate.
+## `uiSchema`
 
-| Endpoint | Behavior |
+| Key | Effect in Admin |
 |---|---|
-| `GET /admin/api/operations` | Lists the staff-operable Procedures the calling staff member may actually run. |
-| `POST /admin/api/operations/:name` | Invokes one, through the same pipeline as any other caller. |
-
-Each listed operation carries `name`, `title`, `description`, `input`, `uiSchema`, `triggers` (the distinct kinds that qualified it, so a Procedure can be both), `rowBindings`, and `targetCollection` (the builtin handler schema, or `null`).
-
-`rowBindings` come from `x-mantle-ref` on the Procedure's input properties. An input property referencing a declared, non-`translates` Schema produces `{ collection, inputField, rowField }`, and Admin offers the operation from that collection's row menu with the field pre-filled and read-only. `rowField` is the target Schema's same-named property when it has one, otherwise the lone field of a single single-field unique index, otherwise the reserved `id` column. Refs to unknown collections or to translation children produce no binding and no error.
-
-When `input` declares `expectedVersion`, Admin treats that reserved name as magic: it captures the OCC target's current `version` at read time, submits it, and does not render an editable version field. Changing the selected target rebinds version (an organization row must not supply a membership mutation's version). A resolvable OCC target or a row-bound dialog must have that captured version before Run is enabled, including matched upsert where the field is declared but not globally required. If `expectedVersion` is in `input.required` and no target can be resolved, submit stays disabled. Collection create / no-row dialogs may omit it when it is not required. Builtin operations also expose `targetCollection` (the handler schema) so Admin can pick the mutated collection over a contextual parent.
-
-Worked end-to-end examples live in [Commerce inventory](../../examples/cf-primitives-commerce-inventory.md), [Commerce catalog](../../examples/builtin-commerce.md), and [Procurement approvals](../../examples/builtin-procurement.md).
-
-## Source
-
-- [`packages/mantle-spec/src/domain/model/ManifestGrammar.ts`](../../../packages/mantle-spec/src/domain/model/ManifestGrammar.ts)
-- [`packages/mantle-spec/src/domain/service/ManifestParser.ts`](../../../packages/mantle-spec/src/domain/service/ManifestParser.ts)
-- [`packages/mantle-spec/src/domain/service/ManifestGraphValidator.ts`](../../../packages/mantle-spec/src/domain/service/ManifestGraphValidator.ts)
-- [`packages/mantle-spec/src/domain/service/SchemaAdminUiChecker.ts`](../../../packages/mantle-spec/src/domain/service/SchemaAdminUiChecker.ts)
-- [`packages/mantle-runtime/src/usecase/procedure/InvokeProcedureUseCase.ts`](../../../packages/mantle-runtime/src/usecase/procedure/InvokeProcedureUseCase.ts)
-- [`packages/mantle-runtime/src/usecase/procedure/InvokeBuiltinUseCase.ts`](../../../packages/mantle-runtime/src/usecase/procedure/InvokeBuiltinUseCase.ts)
-- [`docs/adr/0020-builtin-handler-contracts-and-matched-upsert.md`](../../adr/0020-builtin-handler-contracts-and-matched-upsert.md)
-- [`docs/adr/0022-caller-observed-version-occ.md`](../../adr/0022-caller-observed-version-occ.md)
-- [`packages/mantle-runtime/src/domain/service/BuiltinProjector.ts`](../../../packages/mantle-runtime/src/domain/service/BuiltinProjector.ts)
-- [`packages/mantle-runtime/src/domain/model/EntryRow.ts`](../../../packages/mantle-runtime/src/domain/model/EntryRow.ts)
-- [`packages/mantle-runtime/src/domain/service/io/EntryWriteGuard.ts`](../../../packages/mantle-runtime/src/domain/service/io/EntryWriteGuard.ts)
-- [`packages/mantle-runtime/src/domain/service/io/EntryDeleteGuard.ts`](../../../packages/mantle-runtime/src/domain/service/io/EntryDeleteGuard.ts)
-- [`packages/mantle-runtime/src/domain/service/CallableCapabilityProjector.ts`](../../../packages/mantle-runtime/src/domain/service/CallableCapabilityProjector.ts)
-- [`packages/mantle-runtime/src/usecase/boot/ValidateBootUseCase.ts`](../../../packages/mantle-runtime/src/usecase/boot/ValidateBootUseCase.ts)
-- [`packages/mantle-runtime/src/infrastructure/http/createMantleRequestHandler.ts`](../../../packages/mantle-runtime/src/infrastructure/http/createMantleRequestHandler.ts)
-- [`packages/mantle-admin/src/mountMantleAdmin.ts`](../../../packages/mantle-admin/src/mountMantleAdmin.ts)
+| `fields.<name>.widget: textarea` | a multiline input |
+| `collectionAction: <schema>` | offer the operation on that collection's list |
+
+Admin lists a Procedure as an operation only when a Trigger binds it to the
+staff MCP surface.
+
+## Diagnostics
+
+Validate: `SQL_SYNTAX`, `SQL_UNSUPPORTED`, `SQL_FUNCTION`, `SQL_RELATION`,
+`SQL_COLUMN`, `SQL_WRITE`, `SQL_SHAPE`, `SQL_TYPE`, `PROCEDURE_TARGET_INVALID`,
+`GUARD_PROCEDURE_UNKNOWN`, `GUARD_SELF_REFERENCE`, `GUARD_PROCEDURE_NOT_REF`,
+`GUARD_CHAIN_NOT_ALLOWED`, `MCP_TOOL_DESCRIPTION_MISSING` (a warning),
+`MCP_TOOL_INPUT_UNION_AMBIGUOUS`, `MCP_TOOL_INPUT_UNBOUNDED`. Boot:
+`HANDLER_NOT_REGISTERED`, `HANDLER_NOT_DECLARED`. Run time:
+`INPUT_VALIDATION_FAILED`, `UNAUTHENTICATED`, `AUTH_DENIED`,
+`ENTITLEMENT_REQUIRED`, `CONFLICT`, `OUTPUT_VALIDATION_FAILED`,
+`INVOCATION_DEPTH_EXCEEDED`, `INTERNAL_ERROR`. See [Diagnostics](./diagnostics.md).