@aotter/mantle 0.2.0-alpha.9 → 0.2.0

package/docs/handbook/guides/public-pages.md

@@ -11,6 +11,12 @@ here instead of repeating it.
 - **App-owned pages** in `src/routes.ts`, when the page needs its own layout, JSON-LD or languages. The reference
   implementation is `node_modules/@aotter/mantle/docs/examples/recipes` (`src/pages.ts`, `src/routes.ts`; `smoke.mjs` checks every item below).
 
+## URLs
+
+Mantle owns `/admin`, `/mcp`, `/api/auth/`, `/oauth/consent` and `/.well-known/oauth-*`, and the app's HTTP Triggers own
+their declared paths. Give visitor pages their own prefix (`/{locale}/…`, `/teas/{slug}`), or make a root page (`/{slug}`)
+return nothing for those paths; the app shell already keeps `/admin` and `/mcp` away from `src/routes.ts`.
+
 ## Every public page
 
 - Server-rendered HTML per URL with the content in the body. A client-only SPA shell or metadata set by script is not
@@ -26,7 +32,9 @@ here instead of repeating it.
 
 - JSON-LD of the matching schema.org type (`Recipe`, `Article`, `Event`, `Product`, ...), built from the same row as
   the visible content: `name`, `description`, `url`, `inLanguage`, `datePublished`, `dateModified`, and `image` when
-  there is one (some rich results require it). Escape `<` in the serialized JSON so stored text cannot close the
+  there is one (some rich results require it). A type that has no date or language properties (`Product`) gets them on
+  a page node instead: an `@graph` with an `ItemPage` (`inLanguage`, dates, `mainEntity`) pointing to the `Product`
+  (`offers` with `price` and `priceCurrency`). Escape `<` in the serialized JSON so stored text cannot close the
   script element. Do not add facts the page does not show.
 - A short answer block for answer engines: one question heading and a one-sentence answer from the row's data.
 - A Markdown alternate at `<url>.md`, linked with `<link rel="alternate" type="text/markdown">`.
@@ -46,8 +54,40 @@ here instead of repeating it.
 - `/llms.txt` ([llmstxt.org](https://llmstxt.org)): a title, a one-line summary and a link to each item's Markdown
   alternate.
 
+## A complete site
+
+When the brief names a site, shop, catalogue or blog for visitors, these are part of the work without the user
+listing them:
+
+- Every item on this page, for every public page type the site has.
+- Accessible, responsive pages with the app's own styling; the examples are unstyled on purpose.
+- Content managed in Admin (draft, publish, edit, unpublish) shows on the site without a rebuild. Images go through
+  Admin's media library (`mantle help media-r2`); store committed asset IDs and never use an ID as an image URL.
+- Members' pages, if any, send anonymous visitors to `/sign-in` (`signInRedirect` in the app shell's `src/sign-in.ts`).
+- Who runs the site: an About/contact page and a footer with the business's name, location and contact, and on the
+  home page `Organization` (or `LocalBusiness`) JSON-LD with the same facts and the logo. Answer engines use these to
+  say whether the site is legitimate. Ask for the facts the brief lacks; never invent an address.
+- A favicon, and `og:image` on the home and list pages too.
+- A detail page leads to the action the brief sells (order, register, book), saying when it needs an account.
+- A cache policy: `Last-Modified` (from the row's `updated_at`) or an `ETag` on pages, `.md`, sitemap and `llms.txt`,
+  so crawlers can revalidate; `no-store` everywhere is safe but makes every crawl a full fetch.
+- Structured data and answer blocks state only what the page shows. Never promise ranking or AI citation.
+
 ## Check before you report done
 
-Request the HTML without running JavaScript and check the items above; publish, edit and unpublish an item and check
-that its page, Markdown, sitemap and `llms.txt` follow. The `mantle` skill's
-`references/local-testing.md` covers running this against `wrangler dev`.
+Request each page without running JavaScript (plain `fetch` in `smoke.mjs`; `mantle help local-testing`) and assert:
+
+1. HTML content type and the visible content; `<title>`, description, canonical on `PUBLIC_ORIGIN`, Open Graph; on
+   detail pages JSON-LD that parses with the visible name, and the answer block.
+2. Each `.md` alternate returns `text/markdown` with the current text.
+3. Walk the list View's complete cursor chain: its rows equal the `llms.txt` entries and the sitemap's detail URLs
+   (below the generated `web()` caps: 5,000 rows for `llms.txt`, 50,000 for the sitemap). `/robots.txt` names the
+   sitemap.
+4. An unknown URL, a malformed path, a draft and a row the visitor may not read are 404, also with an admin session.
+5. Publish, edit and unpublish an item through Admin's API (or the Procedure Admin uses); after each, its page,
+   `.md`, sitemap and `llms.txt` follow.
+6. Stored text with `<`, `&` and `</script>` renders escaped in HTML and inside JSON-LD.
+
+Report a check you could not run (for example a production origin you do not have) as UNVERIFIED with the reason.
+Then run [independent acceptance](agent-workflow-acceptance.md) with a visitor evaluator in a browser on the
+`pnpm accept` URL.

package/docs/handbook/guides/sql-patterns.md

@@ -0,0 +1,266 @@
+---
+description: Seven SQL patterns most apps need, each a complete manifest that compiles on every target, with the PostgreSQL spelling and what each refuses.
+---
+# SQL patterns
+
+Each section is a business need, the manifest that meets it, and what the database refuses. Every block here is
+generated by the docs check, and `packages/mantle/tests/sql-patterns.test.ts` runs the same manifest on bun:sqlite,
+local D1 and PostgreSQL through the generated REST boundary. The SQL is the SQLite and D1 spelling; where PostgreSQL
+differs, the section says so. What each dialect accepts is listed in [the SQL reference](../reference/sql.md).
+
+For an order with any number of lines, see [several rows that commit together](typed-queries.md#several-rows-that-commit-together).
+
+The sections share two Schemas:
+
+```yaml
+apiVersion: cms.mantle.aotter.net/v2
+kind: Schema
+metadata: { name: products }
+spec:
+  title: Products
+  lifecycle: operational
+  uniqueIndexes: [[sku]]
+  checks: ["reserved <= stock"]
+  schema:
+    type: object
+    required: [sku, name, price, stock, reserved, active]
+    properties:
+      sku: { type: string }
+      name: { type: string, minLength: 1 }
+      note: { type: string }
+      price: { type: integer, minimum: 0 }
+      stock: { type: integer, minimum: 0 }
+      reserved: { type: integer, minimum: 0 }
+      active: { type: boolean }
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Schema
+metadata: { name: orders }
+spec:
+  title: Orders
+  lifecycle: operational
+  indexes: [[productId, createdAt, id]]
+  schema:
+    type: object
+    required: [productId, qty, total, orderStatus]
+    properties:
+      productId: { type: string, x-mantle-ref: products }
+      qty: { type: integer, minimum: 1 }
+      total: { type: integer, minimum: 0 }
+      orderStatus: { type: string, enum: [reserved, pending_approval] }
+```
+
+## Choose a status while writing: CASE
+
+An order over 5000 waits for a manager; a smaller one reserves stock at once. `CASE` picks the status inside the
+INSERT, and the reservation runs only for a small order, in the same program, so the two never disagree. The total
+comes from the catalogue's `price`, never from the caller: a price in the input would let a caller choose the total,
+and with it whether the order needs approval.
+
+```yaml
+apiVersion: cms.mantle.aotter.net/v2
+kind: Procedure
+metadata: { name: place-order }
+spec:
+  description: Order a product. An order over 5000 waits for approval and reserves nothing yet.
+  requires: { auth: { all: [ctx.user] } }
+  input:
+    type: object
+    additionalProperties: false
+    required: [productId, qty]
+    properties:
+      productId: { type: string }
+      qty: { type: integer, minimum: 1 }
+  output: { type: object }
+  handler:
+    sql: |
+      INSERT INTO orders (productId, qty, total, orderStatus)
+        SELECT p.id, input.qty, input.qty * p.price,
+          CASE WHEN input.qty * p.price > 5000 THEN 'pending_approval' ELSE 'reserved' END
+        FROM products p WHERE p.id = input.productId AND p.active
+        RETURNING id, orderStatus AS "orderStatus";
+      UPDATE products SET reserved = reserved + input.qty
+        WHERE id IN (SELECT p.id FROM products p WHERE p.id = input.productId AND p.active AND input.qty * p.price <= 5000)
+```
+
+The second statement is written as `WHERE id IN (SELECT …)` on purpose. `WHERE id = input.productId AND …` is a
+row-classified UPDATE, which must change exactly one row: for an order that waits, it would change none and refuse the
+whole call with `CONFLICT`. A write that should do nothing when its condition is false needs the set form. The first
+statement's join on `products` with `p.active` means an unknown or discontinued product writes no order.
+
+## Approve before reserving
+
+Approval changes the status and reserves the stock in one program. The first statement is the guard: a stale
+`expectedVersion` or an order that is no longer `pending_approval` matches no row, which is `CONFLICT`. The second
+statement fails `reserved <= stock` when the stock is gone by now, and that rolls back the status change too, so the
+order stays pending. [Purchasing](../../examples/purchasing/README.md) does the same with a department budget
+(`approve-request-write`), and approves small requests at submission with `CASE` (`submit-request`).
+
+```yaml
+apiVersion: cms.mantle.aotter.net/v2
+kind: Procedure
+metadata: { name: approve-order }
+spec:
+  description: Approve a pending order at the version you reviewed; reserves its stock.
+  requires: { auth: { all: [ctx.admin] } }
+  input:
+    type: object
+    additionalProperties: false
+    required: [id, expectedVersion]
+    properties:
+      id: { type: string }
+      expectedVersion: { type: integer }
+  output: { type: object }
+  handler:
+    sql: |
+      UPDATE orders SET orderStatus = 'reserved'
+        WHERE id = input.id AND version = input.expectedVersion AND orderStatus = 'pending_approval'
+        RETURNING id, version;
+      UPDATE products SET reserved = reserved + (SELECT o.qty FROM orders o WHERE o.id = input.id)
+        WHERE id = (SELECT o.productId FROM orders o WHERE o.id = input.id)
+```
+
+## Change only the fields given: COALESCE
+
+A partial update keeps every field the caller left out: `COALESCE(input.name, name)` is the new name when one is given
+and the current one otherwise. `NULLIF(input.note, '')` also treats an empty string as left out. Because of that, this
+Procedure cannot clear a note; give clearing its own input (for example `clearNote: true` with
+`CASE WHEN input.clearNote THEN NULL ELSE … END`) if the app needs it. The version guard makes a stale edit a 409.
+
+```yaml
+apiVersion: cms.mantle.aotter.net/v2
+kind: Procedure
+metadata: { name: update-product }
+spec:
+  description: Change a product's name or note; a field you leave out keeps its value.
+  requires: { auth: { all: [ctx.admin] } }
+  input:
+    type: object
+    additionalProperties: false
+    required: [id, expectedVersion]
+    properties:
+      id: { type: string }
+      expectedVersion: { type: integer }
+      name: { type: string, minLength: 1 }
+      note: { type: string }
+  output: { type: object }
+  handler:
+    sql: |
+      UPDATE products SET name = COALESCE(input.name, name), note = COALESCE(NULLIF(input.note, ''), note)
+        WHERE id = input.id AND version = input.expectedVersion
+        RETURNING id, version, name, note
+```
+
+## Create or add: ON CONFLICT DO UPDATE
+
+Restocking a SKU creates the product the first time and adds to its stock afterwards, in one statement. The conflict
+target must be a declared unique index (`uniqueIndexes: [[sku]]`). `excluded` is the row the INSERT proposed;
+qualify the existing row with the table name (`products.stock`).
+
+```yaml
+apiVersion: cms.mantle.aotter.net/v2
+kind: Procedure
+metadata: { name: restock }
+spec:
+  description: Add stock by SKU, creating the product the first time.
+  requires: { auth: { all: [ctx.admin] } }
+  input:
+    type: object
+    additionalProperties: false
+    required: [sku, name, price, qty]
+    properties:
+      sku: { type: string }
+      name: { type: string, minLength: 1 }
+      price: { type: integer, minimum: 0 }
+      qty: { type: integer, minimum: 1 }
+  output: { type: object }
+  handler:
+    sql: |
+      INSERT INTO products (sku, name, price, stock, reserved, active) VALUES (input.sku, input.name, input.price, input.qty, 0, true)
+        ON CONFLICT (sku) DO UPDATE SET stock = products.stock + excluded.stock
+        RETURNING id, stock
+```
+
+## Refuse while something refers to it: NOT EXISTS
+
+A product cannot be discontinued while an order for it waits for approval, since approving that order would reserve
+stock of a product no longer sold. `NOT EXISTS (…)` is part of the guard, so while such an order exists the
+row-classified UPDATE changes nothing and the call is `CONFLICT`; the product stays on sale. Use `EXISTS` the same way
+for "only if a related row exists". [Purchasing](../../examples/purchasing/README.md) uses `NOT EXISTS` to write the
+ledger row only for the request its program just approved (`submit-request`).
+
+```yaml
+apiVersion: cms.mantle.aotter.net/v2
+kind: Procedure
+metadata: { name: discontinue-product }
+spec:
+  description: Stop selling a product; refused while an order for it waits for approval.
+  requires: { auth: { all: [ctx.admin] } }
+  input:
+    type: object
+    additionalProperties: false
+    required: [id]
+    properties:
+      id: { type: string }
+  output: { type: object }
+  handler:
+    sql: |
+      UPDATE products SET active = false
+        WHERE id = input.id
+          AND NOT EXISTS (SELECT 1 FROM orders o WHERE o.productId = products.id AND o.orderStatus = 'pending_approval')
+        RETURNING id
+```
+
+## A row with its children in one read
+
+An admin, or an AI client, reads each product with its orders in one call instead of one call per product. A
+correlated subquery builds the array, so a product without orders has `[]`; `LEFT JOIN … GROUP BY` would give it one
+empty object instead.
+
+```yaml
+apiVersion: cms.mantle.aotter.net/v2
+kind: View
+metadata: { name: products-with-orders }
+spec:
+  description: Each product with its orders as one JSON array.
+  surface: admin
+  requires: { auth: { all: [ctx.admin] } }
+  sql: |
+    SELECT p.id, p.name,
+      (SELECT json_group_array(json_set('{}', '$.id', o.id, '$.qty', o.qty)) FROM orders o WHERE o.productId = p.id) AS orders
+    FROM products p ORDER BY p.id
+```
+
+SQLite and D1 build each object with `json_set('{}', '$.id', o.id, …)` (`json_object` is not on the allowlist).
+PostgreSQL writes it as `COALESCE(jsonb_agg(jsonb_build_object('id', o.id, 'qty', o.qty)), CAST('[]' AS jsonb))`;
+`jsonb_agg` of no rows is `NULL`, hence the `COALESCE`. PostgreSQL can also order inside the aggregate
+(`jsonb_agg(… ORDER BY o.id)`); SQLite cannot, so sort the array.
+
+Generation types the column as JSON because its expression can only produce a JSON document: a `json_group_array`,
+`json_group_object`, `json_set`, `json_insert`, `json_remove`, `jsonb_agg`, `jsonb_object_agg`, `jsonb_build_object`,
+`jsonb_build_array`, `jsonb_strip_nulls`, `to_jsonb` or `CAST(… AS jsonb)` call, a scalar subquery of one, or a
+`COALESCE` of those with JSON literal fallbacks such as `'[]'`. REST, MCP (`structuredContent`) and Admin therefore
+return an array on every target, and `WireRow` types the column `unknown`. The bare View and the Store keep the
+driver's value: on SQLite and D1 that is JSON text, so code calling the bare View parses it. `json_extract`, `->>`
+and `CASE` can return a scalar, so their output stays native.
+
+## The latest row of each group: row_number()
+
+The most recent order of each product. `row_number() OVER (PARTITION BY … ORDER BY …)` numbers each product's orders
+newest first, and the outer query keeps number 1. End the window's ORDER BY with `id` so two rows created in the same
+instant still have one order. `rank()` instead gives tied rows the same number.
+
+```yaml
+apiVersion: cms.mantle.aotter.net/v2
+kind: View
+metadata: { name: latest-order-per-product }
+spec:
+  description: The most recent order of each product.
+  surface: admin
+  requires: { auth: { all: [ctx.admin] } }
+  sql: |
+    SELECT x.productId AS "productId", x.id, x.qty FROM (
+      SELECT o.productId, o.id, o.qty, row_number() OVER (PARTITION BY o.productId ORDER BY o.created_at DESC, o.id DESC) AS n
+      FROM orders o
+    ) x WHERE x.n = 1 ORDER BY x.productId
+```

package/docs/handbook/guides/typed-queries.md

@@ -125,3 +125,141 @@ step's returned ID. D1 has no interactive transaction callback, so retain the
 supported SQL program or another existing native atomic boundary for that case.
 The [MCP design audit](agent-workflow-acceptance.md) applies these choices before
 implementation and separates them from independent end-user acceptance.
+
+## Several rows that commit together
+
+An order with any number of lines, a cart checkout or a bulk import must commit
+every row or none. Pass the rows as one array input and write them in one SQL
+Procedure that reads the array as a row source: `json_each(input.items)` on
+SQLite and D1, `jsonb_array_elements(input.items) AS j(value)` on PostgreSQL.
+The Procedure's statements commit together on every target, so a Schema
+`checks` failure in any statement refuses the whole call with `CONFLICT` and
+leaves nothing behind. Bound the array with `maxItems`.
+
+A statement cannot read an earlier statement's `RETURNING`, so rows that must
+refer to each other share a key from the input: here the caller (or a `ref`
+handler that then calls this Procedure) supplies `orderRef`. A later statement
+does see the rows an earlier one wrote, so it can also store the parent's id
+(`(SELECT o.id FROM orders o WHERE o.orderRef = input.orderRef)`) in a field with
+`x-mantle-ref: orders`, which lets Admin fold the lines under their order.
+
+```yaml
+apiVersion: cms.mantle.aotter.net/v2
+kind: Schema
+metadata: { name: products }
+spec:
+  title: Products
+  lifecycle: operational
+  checks: ["reserved <= stock"]
+  schema:
+    type: object
+    required: [name, stock, reserved]
+    properties:
+      name: { type: string }
+      stock: { type: integer, minimum: 0 }
+      reserved: { type: integer, minimum: 0 }
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Schema
+metadata: { name: orders }
+spec:
+  title: Orders
+  lifecycle: operational
+  uniqueIndexes: [[orderRef]]
+  checks: ["matchedLines = lineCount"]
+  schema:
+    type: object
+    required: [orderRef, lineCount, matchedLines]
+    properties:
+      orderRef: { type: string }
+      lineCount: { type: integer, minimum: 1 }
+      matchedLines: { type: integer, minimum: 0 }
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Schema
+metadata: { name: order_lines }
+spec:
+  title: Order lines
+  lifecycle: operational
+  schema:
+    type: object
+    required: [orderRef, productId, qty]
+    properties:
+      orderRef: { type: string }
+      productId: { type: string, x-mantle-ref: products }
+      qty: { type: integer, minimum: 1 }
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Procedure
+metadata: { name: place-order }
+spec:
+  description: Place an order of one or more lines; an unknown product or a line that would oversell refuses the whole order.
+  requires: { auth: { all: [ctx.user] } }
+  input:
+    type: object
+    additionalProperties: false
+    required: [orderRef, items]
+    properties:
+      orderRef: { type: string }
+      items:
+        type: array
+        minItems: 1
+        maxItems: 50
+        items:
+          type: object
+          additionalProperties: false
+          required: [productId, qty]
+          properties:
+            productId: { type: string }
+            qty: { type: integer, minimum: 1 }
+  output: { type: object }
+  handler:
+    sql: |
+      INSERT INTO orders (orderRef, lineCount, matchedLines) VALUES (input.orderRef,
+        (SELECT COUNT(*) FROM json_each(input.items) j),
+        (SELECT COUNT(*) FROM json_each(input.items) j JOIN products p ON p.id = j.value ->> 'productId'));
+      UPDATE products SET reserved = reserved + (SELECT SUM(j.value ->> 'qty') FROM json_each(input.items) j WHERE j.value ->> 'productId' = products.id)
+        WHERE id IN (SELECT j.value ->> 'productId' FROM json_each(input.items) j);
+      INSERT INTO order_lines (orderRef, productId, qty)
+        SELECT input.orderRef, p.id, j.value ->> 'qty' FROM json_each(input.items) j JOIN products p ON p.id = j.value ->> 'productId'
+        RETURNING id, productId AS "productId";
+```
+
+Each refusal is a check or a unique index, so it rolls back all three statements:
+
+- A line that would oversell fails `reserved <= stock`. Repeated lines for one
+  product add up in the `SUM`, so they are checked against the same stock.
+- A line naming an unknown product does not match in the join, so
+  `matchedLines` falls short of `lineCount` and the `orders` check fails. Set
+  operations alone would skip that line and still succeed.
+- A repeated `orderRef` clashes with the unique index, so replaying a request
+  cannot reserve twice.
+
+On PostgreSQL `->>` returns text: write `CAST(j.value ->> 'qty' AS int8)`
+there. SQLite and D1 refuse that integer cast (`SQL_TYPE`, because SQLite
+truncates where PostgreSQL rounds), and their `->>` already returns the JSON
+number.
+
+[SQL patterns](sql-patterns.md) covers approving before reserving, choosing a status with `CASE`, partial updates,
+upserts, `EXISTS` guards and nested reads on the same `products`.
+
+Do not split this into a Store write, then a SQL Procedure, then a compensating
+delete: the rows are visible between the steps and a failure leaves cleanup to
+the handler. A `ref` handler that needs the rows written together calls this
+Procedure through `ctx.store.procedures`, passing the array itself: the
+generated input type is the authored one, and the generated query serializes
+the array for the driver (a string is bound as it is). Like a direct call, the
+Store does not validate input against the Procedure's schema (REST and MCP do),
+so `maxItems` and the line shape hold only for rows the handler has checked or
+built.
+
+```ts
+import { store } from './generated/generated.js';
+import type { Caller } from '@aotter/mantle/contracts';
+
+// `ctx.store` in a `ref` handler is this Store: `ctx.store.procedures['place-order']({ orderRef, items })`.
+export async function placeOrder(db: Parameters<typeof store>[0], caller: Caller, orderRef: string) {
+  const items = [{ productId: 'pen', qty: 2 }, { productId: 'stapler', qty: 1 }];
+  return store(db, caller).procedures['place-order']({ orderRef, items });
+}
+```

package/docs/handbook/navigation.json

@@ -4,6 +4,10 @@
     {
       "text": "Start here",
       "items": [
+        {
+          "text": "Build with an agent",
+          "link": "/start/agents"
+        },
         {
           "text": "Handbook overview",
           "link": "/start/overview"
@@ -33,6 +37,14 @@
           "text": "Public pages: SEO, AEO and languages",
           "link": "/guides/public-pages"
         },
+        {
+          "text": "Local HTTP checks",
+          "link": "/guides/local-testing"
+        },
+        {
+          "text": "SQL patterns",
+          "link": "/guides/sql-patterns"
+        },
         {
           "text": "Native Admin",
           "link": "/guides/native-admin"
@@ -131,6 +143,10 @@
           "text": "Trigger",
           "link": "/reference/trigger"
         },
+        {
+          "text": "SQL accepted by each dialect",
+          "link": "/reference/sql"
+        },
         {
           "text": "Authorization requirements",
           "link": "/reference/authorization"

package/docs/handbook/reference/admin-descriptors.md

@@ -37,7 +37,10 @@ execution plan or SQL AST, storage access or execution observer is included.
   admin tool names. A conflicting declared admin tool is refused.
 - `webmcp` carries static tool declarations and Admin page routes. `bootstrap`
   combines `collections`, `operations`, `views` and `webmcp`; the handler adds
-  request-owned `me`, `site` and any selected entries page.
+  request-owned `me`, `site` and any selected entries page. Its
+  `developerConsole` is a loader for the same snapshot, generated again in
+  `admin-developer-console.ts`, so Admin imports it on a developer-console
+  request instead of at Worker startup.
 
 Generation reuses the 0.2 projection and SQL-logic helpers. View columns come
 from the compiled plan (Core's `viewOutputs` provenance, including aliases,

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
 

package/docs/handbook/reference/diagnostics.md

@@ -8,12 +8,17 @@ 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 |
 | OUTCOME_UNKNOWN | 503 | Write may have committed; reconcile without automatic retry |
 
+A `CONFLICT` carries `kind`: `"row"` when a row statement 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 and `"check"` for a Schema check (with `schema` and `check`). Match `kind`, not the message.
+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).
+
 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.

package/docs/handbook/reference/procedure.md

@@ -2,13 +2,13 @@
 
 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).
 
-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 and guards. 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: check the returned rows when zero means failure. 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. 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 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).
 
 `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`.