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

package/docs/handbook/guides/size-and-startup.md

@@ -7,3 +7,143 @@ Workers use `mantle bundle` to emit split ESM. Keep Better Auth behind `authLoad
 Contributor checks use tracked fixtures to compare runtime/startup graphs against `size-budgets.json` and inspect the published allowlist in `check:package`. Package packed/unpacked bytes are reported separately from request startup and query costs. Do not infer latency from bundle bytes.
 
 Cloudflare startup_time_ms needs an actual upload/deployment; offline dry runs do not measure it. Measure on the selected host and report first use and warm work separately. Applications own deployment authorization and resources.
+
+## Size metrics
+
+Three metrics, one definition each. The [performance skill](../../skills/performance/SKILL.md)
+and the SDK's own checks use these names. Measure the production build that
+`mantle bundle` writes, never a dev server.
+
+"gzip per file" means: compress each file, or each inline script, on its own with
+Node's `zlib.gzipSync` at its default level, then add the results. A host may
+serve Brotli or another level; that is a different number, so name it when you
+report it.
+
+| Metric | What counts | Unit |
+|---|---|---|
+| First-load JavaScript | Every script a page's HTML loads: `<script src>` files and inline `<script>` text, classic or `type="module"`, plus every file they import statically, recursively. A dynamic `import()` is not followed. CSS, fonts, images and scripts from another origin do not count. | gzip per file |
+| MCP App HTML document | The whole built App document as served: its inline JavaScript, CSS and markup in one file. | raw bytes and gzip of the file |
+| Worker entry static graph | The Worker entry (Wrangler's `main`, such as `dist/worker/worker.js`) plus every chunk it imports statically, recursively. A dynamic `import()` is not followed. | gzip per file; raw bytes beside it |
+
+The 100 KB budget in the performance skill is first-load JavaScript. It applies to
+an MCP App too: `mantle bundle` builds the App as one HTML file with its
+JavaScript inline, so its first-load JavaScript is its inline script text. The
+MCP App HTML document also holds CSS and markup, so do not compare the document
+with that budget.
+
+### Measure
+
+This script measures first-load JavaScript and the Worker entry static graph. It
+follows static imports in the minified ESM that Vite and `mantle bundle` emit,
+and reproduces the SDK checks' graphs below. Save it outside `src/`:
+
+```js
+// first-load.mjs — node first-load.mjs <page.html | entry.js> [assets-directory]
+import { readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { gzipSync } from "node:zlib";
+
+const [target, root = dirname(target)] = process.argv.slice(2);
+const seen = new Set();
+let scripts = 0, raw = 0, gzip = 0;
+// `import … from "./x.js"`, `import "./x.js"`, `export … from "./x.js"`; a dynamic `import("./x.js")` is not followed.
+const imports = /(?:^|[;}\s])(?:import|export)\s*(?:[\w$*{},\s]*?from\s*)?["'](\.{1,2}\/[^"']+)["']/g;
+function count(code, directory) {
+  scripts += 1;
+  raw += code.length;
+  gzip += gzipSync(code).length;
+  for (const [, path] of code.toString().matchAll(imports)) visit(resolve(directory, path));
+}
+function visit(file) {
+  if (seen.has(file)) return;
+  seen.add(file);
+  count(readFileSync(file), dirname(file));
+}
+if (target.endsWith(".html")) {
+  // Every script the page loads: `<script src>` files and inline `<script>` text, classic or module.
+  const html = readFileSync(target, "utf8");
+  for (const [, attributes, body] of html.matchAll(/<script\b([^>]*)>([\s\S]*?)<\/script>/gi)) {
+    const type = /\btype="([^"]*)"/i.exec(attributes)?.[1] ?? "";
+    if (!["", "module", "text/javascript"].includes(type)) continue; // JSON data and import maps are not JavaScript
+    const src = /\bsrc="([^"]+)"/i.exec(attributes)?.[1];
+    if (!src) count(Buffer.from(body), dirname(resolve(target)));
+    else if (!/^(?:[a-z]+:)?\/\//i.test(src)) visit(src.startsWith("/") ? join(resolve(root), src) : resolve(dirname(target), src));
+  }
+} else visit(resolve(target));
+console.log(JSON.stringify({ scripts, raw, gzip }));
+```
+
+First-load JavaScript of a page: pass its HTML, and the assets directory when the
+page loads scripts by absolute path. Built-in Admin loads the blocking `theme.js`
+and the module entry:
+
+```sh
+pnpm exec mantle bundle src/worker.ts dist
+node first-load.mjs dist/client/admin/index.html dist/client
+```
+
+First-load JavaScript of an MCP App: pass its HTML document.
+
+```sh
+node first-load.mjs dist/client/admin/mcp-app.html
+```
+
+Worker entry static graph: pass Wrangler's `main`.
+
+```sh
+node first-load.mjs dist/worker/worker.js
+```
+
+MCP App HTML document:
+
+```sh
+node -e 'const b=require("fs").readFileSync(process.argv[1]);console.log(JSON.stringify({raw:b.length,gzip:require("zlib").gzipSync(b).length}))' dist/client/admin/mcp-app.html
+```
+
+## What the SDK's checks measure
+
+The SDK's own checks run on fixtures and the built-in Admin entry, not on your
+application. Where they differ from the definitions above:
+
+| Check | Reports | Difference |
+|---|---|---|
+| `check:ui-size`, `admin:entry-gzip` | Admin's module entry and its static graph, gzip per file | Leaves out the blocking classic `theme.js` (about 0.8 KB gzip). Reported, not gating. |
+| `check:ui-size`, `admin:mcp-html` | Raw bytes of `mcp-app.html` | No gzip figure and no inline JavaScript figure. Reported, not gating. |
+| `check:startup` and `check-size.ts`, `startup:<surface>` | The static graph of a fixture Worker mounting each surface, from esbuild's metafile | Raw minified bytes, not gzip. Gates against `size-budgets.json`. |
+| `check-size.ts`, `direct-op` | The static graph of one direct operation import | Raw minified bytes. Gates below 4 KiB. |
+| `check-size.ts`, `startupBytes` of `cloudflare-d1` and `cloudflare-postgres` | The fixture Worker entry's static graph | Raw minified bytes. Reported, not gating. |
+| `check-size.ts`, `totalBytes` and `gzipBytes` | Every `.js` file of a fixture Worker bundle; `gzipBytes` is gzip per file | Includes lazy chunks, so it is the whole bundle, not the static graph. Only `totalBytes` warns above its reference; neither gates. |
+
+`check:ui-size` also gates that lazy features and locales stay out of Admin's
+startup graph, and `check:startup` runs it with `--startup-only`. Package bytes
+(`packed`, `unpacked`) are a separate measure of what installs.
+
+## Native Admin baselines
+
+Built-in Admin is SDK-existing cost: both its page and its MCP App. The 0.2.0
+size pass, [#1554](https://github.com/aotter/mantle/issues/1554), shrank them and
+is closed; the misses below are what remains. Measured with the commands above on
+the built-in entry. The figures move with any change to Admin or its
+dependencies, so they hold only for the version and commit named.
+
+| SDK | Source | Admin page first-load JavaScript | MCP App first-load JavaScript | MCP App HTML document |
+|---|---|---|---|---|
+| 0.2.1 | `develop` at `6dafb812`, before the release | 212,102 B gzip in 5 files (211,338 B without `theme.js`) | 193,535 B gzip, inline | 694,170 B raw / 200,457 B gzip |
+
+Neither the built-in Admin page nor its MCP App meets the 100 KB first-load
+budget. Both misses are SDK cost, not your application's: report them as
+SDK-existing, link #1554, and keep them out of app-added cost.
+
+## Report size
+
+- Report app-added cost and SDK-existing cost separately. App-added cost is your
+  measurement minus the baseline for the installed SDK version. When your figures
+  for an unchanged built-in Admin differ from the table, measure the baseline
+  again on your install and subtract that.
+- When the installed SDK and Admin versions are unchanged and Admin uses the
+  built-in entry, the baseline still holds: do not repeat that experiment each
+  round. An `admin.tsx` entry or a custom MCP App changes what you measure.
+- A target still missed is PARTIAL, even when the SDK's cost causes it. Never
+  relabel PARTIAL as PASS and never raise a threshold to pass.
+- Do not patch vendor or SDK code, remove native Admin features or build a
+  general benchmark framework to pass. Report the miss and its owner.

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

@@ -0,0 +1,312 @@
+---
+description: Eight 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
+```
+
+## Create only if the parent exists: onNoRows
+
+`place-order` above writes no order for an unknown or discontinued product and still succeeds: its result is
+`results[0] = []`, and the caller must look. That is right when "nothing to do" is a normal outcome. When writing no
+row means the request failed, say so: write the handler as `steps`, one statement each, and give the statement that
+must write `onNoRows: conflict`. A step marked so that writes no row fails the call with `CONFLICT` (409) kind
+`"row"`, as a row-classified statement does, and the whole program rolls back, including steps that ran before it.
+
+```yaml
+apiVersion: cms.mantle.aotter.net/v2
+kind: Procedure
+metadata: { name: request-order }
+spec:
+  description: Ask for an order of a product that is still sold; it waits for approval. Refused (409) for an unknown or discontinued product.
+  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:
+    steps:
+      - sql: |
+          INSERT INTO orders (productId, qty, total, orderStatus)
+            SELECT p.id, input.qty, input.qty * p.price, 'pending_approval'
+            FROM products p WHERE p.id = input.productId AND p.active
+            RETURNING id
+        onNoRows: conflict
+```
+
+`steps` is the same program as `sql`, one statement per step, run in order in the same batch with the same checks:
+`handler: { sql }` and `handler: { steps }` are alternatives, and a step without `onNoRows` behaves exactly as that
+statement does in `sql`. A further step, such as `place-order`'s conditional reservation, is another list item
+(`- sql: UPDATE products SET reserved = …`) without `onNoRows` when writing nothing is fine.
+
+`WHERE EXISTS (SELECT 1 FROM products WHERE id = input.productId)` after a `SELECT` of input values works the same
+way when the new row needs nothing from the parent. Use `onNoRows` on a set op only: an `INSERT … SELECT`, an
+`INSERT … ON CONFLICT`, or an UPDATE or DELETE that does not pin `id`. A one-row `INSERT … VALUES` or a
+`WHERE id = input.id` statement already must change exactly one row, and generation refuses `onNoRows` on it. The
+check is "at least one", so a statement that writes several rows (`json_each(input.items)`, an UPDATE over a set)
+passes; give an array input `minItems: 1` when an empty one is a mistake. A ref handler throws its own
+`ContractError` instead.
+
+## 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

@@ -83,11 +83,16 @@ CREATE INDEX articles_title_trgm ON articles USING gin (title gin_trgm_ops);
 
 Index each searched field as needed and inspect EXPLAIN for the workload. Case folding follows the engine.
 
-Writes are lazy and execute once when awaited. Insert/update return native rows; delete returns void. `update(id, set, { lock })` and `delete(id, { lock })` require the version the caller reviewed. A stale lock, excluded row or unique clash is `CONFLICT`. `batch` atomically executes unused Writes from one Store in input order; a step cannot use a prior result.
+Writes are lazy and execute once when awaited. Insert/update return native rows; delete returns void. Store rows carry `version` as a number on every target: PostgreSQL's int8 text is converted, and a value beyond `Number.MAX_SAFE_INTEGER` is `SQL_TYPE` rather than rounded. `update(id, set, { lock })` and `delete(id, { lock })` require the version the caller reviewed, as a number or an exact integer string. A stale lock, excluded row or unique clash is `CONFLICT`. A definitive PostgreSQL serialization failure (`40001`) or deadlock (`40P01`) is also `CONFLICT`, with `kind: "serialization"` and the native error as `cause`; the write was rolled back. This includes a server refusal at COMMIT. A missing/uncertain response remains `OUTCOME_UNKNOWN`. Re-read before deciding whether to retry; there is no automatic retry. `batch` atomically executes unused Writes from one Store in input order; a step cannot use a prior result.
 
-Interactive `transaction(async tx => …)` exists on bun:sqlite and PostgreSQL, with collections, Views and Procedures bound to the transaction. D1 supports batches only. PostgreSQL defaults to serializable, with an explicit isolation override; SQLite uses BEGIN IMMEDIATE. Use `tx` inside the callback, not the outer Store or handle. Nested transactions and `tx.batch` are refused; there is no automatic retry.
+Interactive `transaction(async tx => …)` exists on bun:sqlite and PostgreSQL, with collections, Views and Procedures bound to the transaction. D1 supports batches only. PostgreSQL defaults to serializable, with an explicit isolation override; SQLite uses BEGIN IMMEDIATE. Use `tx` inside the callback, not the outer Store or handle. Nested transactions are refused; there is no automatic retry. `tx.batch` joins the outer transaction, with no savepoint.
+A rejected batch marks the whole outer transaction rollback-only, including when its error is caught: the transaction
+rejects with the first batch failure and rolls back all its writes. This includes invalid/reused/foreign Writes and
+errors while building or executing the batch.
 
-Ref handlers receive `{ caller, db, store }` bound to the same Caller and transaction. Implement the generated `Handlers` interface and pass it to `store(db, caller, { handlers })`. Direct Procedure modules expose SQL Procedures; ref Procedures are reached through the bound Store or selected surfaces.
+Ref handlers receive `{ caller, db, store }` bound to the same Caller and transaction. `ctx.store.batch` is available
+on every target: a native atomic batch standalone, or part of the same outer transaction when one exists. Use it for
+known multi-writes rather than constructing another Store inside a handler. Implement the generated `Handlers` interface and pass it to `store(db, caller, { handlers })`. Direct Procedure modules expose SQL Procedures; ref Procedures are reached through the bound Store or selected surfaces.
 
 See [native execution](native-execution.md) for values and write outcomes and [migrations](../concepts/runtime-and-adapters.md#schema-installation-and-migrations) before changing a Schema.
 
@@ -125,3 +130,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,18 @@
           "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": "Edit published content without downtime",
+          "link": "/guides/revisions"
+        },
         {
           "text": "Native Admin",
           "link": "/guides/native-admin"
@@ -131,6 +147,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,