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

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

@@ -1,26 +1,20 @@
 ---
-description: Read and write through the typed Store from handlers and service code, call named Views, and choose between ctx.store, runtime.store and runtime.store.as(caller).
+description: Choose Store for writes and simple lookups; declare internal Views for richer reads.
 ---
 # Query from TypeScript
 
-Handler and service code reach Mantle-owned rows only through Store. The
-generated `.mantle/generated/mantle.ts` types it over your Schemas and Views:
-`ctx.store` in a `MantleHandlers` handler is its `CallerStore`, while
-`runtime.store` is the untyped `MantleStore` until you cast it to the
-generated `Store`.
+| Work | Data path |
+| --- | --- |
+| Writes | Store `insert` / `update` / `delete`, atomic `batch`, supported `transaction`, or declared Procedures |
+| Id lookup or simple AND filter | Store `findById` / `find` / `first`, inside handlers or an existing application |
+| Joins, aggregates, OR, reusable reads | Internal View: manifest SQL that is reviewable and typed |
 
-| Store | Where | Scope |
-|---|---|---|
-| `ctx.store` | inside a `ref` handler | bound to the invocation's caller. A guard or a before hook gets a read-only one |
-| `runtime.store.as(caller)` | service code that has resolved a caller | that caller |
-| `runtime.store` | trusted host code (imports, maintenance) | none: no caller scope. TTL still applies |
-
-Each one applies TTL visibility, and published-only on public Views. Only
-`runtime.store` skips caller scope, so never hand it a request's input
-unchecked.
+Never write raw SQL to Mantle collections: it bypasses scope, TTL, publishing and system-column rules. The Store applies row rules but does not check a View's or Procedure's `requires`; authorize your handler before using it.
 
 ## Declare an internal View
 
+Save this as `manifests/tickets.yaml`:
+
 ```yaml
 apiVersion: cms.mantle.aotter.net/v2
 kind: Schema
@@ -49,107 +43,223 @@ spec:
     properties:
       ticketState: { type: string, enum: [open, closed] }
   sql: |
-    SELECT id, subject, ticketState FROM tickets
+    SELECT id, subject, ticketState AS "ticketState" FROM tickets
     WHERE ticketState = input.ticketState
-    ORDER BY created_at DESC LIMIT 50
+    ORDER BY id ASC
 ```
 
-`internal` keeps the View off REST, MCP and Admin. It is still in the plan and
-the typed Store. It is not a security bypass: a `requires` on it is checked
-for the caller the Store is bound to.
-
-## Call it
+Generate with `mantle generate cloudflare-d1 generated manifests/tickets.yaml`.
+An internal View has no public REST route or MCP tool. Its generated function still applies declared authorization and compiled row policy.
 
 ```ts
-import type { MantleHandlers } from "../.mantle/generated/mantle.js";
-
-export const handlers: MantleHandlers = {
-  closeStale: async (_input, ctx) => {
-    const { rows, nextCursor } = await ctx.store.view("tickets-by-state", { input: { ticketState: "open" }, limit: 20 });
-    // rows: { id: unknown; subject: string | null; ticketState: "open" | "closed" | null }[]
-    return { open: rows.length, more: nextCursor !== undefined };
-  },
-};
+import { store } from './generated/generated.js';
+import ticketsByState from './generated/views/tickets-by-state.js';
+import type { Caller } from '@aotter/mantle/contracts';
+
+export async function readTickets(db: Parameters<typeof store>[0], caller: Caller) {
+  const tickets = store(db, caller).collection('tickets');
+  const first = await tickets.first({ where: { ticketstate: 'open' } });
+  const rows = await ticketsByState(db, caller, { ticketState: 'open' });
+  return { first, rows };
+}
 ```
 
-The View name, its `input` and its row type are checked by `tsc`. A staff View
-with `uiSchema.list.searchFields` or `filterFields` also takes `search` and
-`filters` (`ctx.store.view(name, { search: "refund", filters: { ticketState: "open" } })`);
-Store refuses a filter the View does not declare. An output that reads a
-Schema field unchanged has that field's type, `created_at` and `updated_at`
-are `string | null`, and an expression, or another native column such as `id`,
-is `unknown`. Page with `limit` (default 50, at most 500) and the opaque
-`cursor` from `nextCursor`.
+The app supplies a verified Caller and its existing native handle. External input needs boundary validation. Store rows, filters and writes use storage names (`ticketstate`, `created_at`); View aliases use the SQL output names.
 
-## `select` and `write`
+## Store reads and writes
 
-For a query that needs no declared View, `select` takes a JSON query over one
-Schema:
+`find` returns `{ rows, cursor }` (null cursor on the last page), with limits 1–500 and opaque keyset cursors. `where` combines fields with AND; `orderBy` selects a generated indexed column with `id` ties. Most order columns must be NOT NULL; publishing `published_at` supports nulls. For a proved pageable internal View, import `paged/views/<encoded-name>.ts` and call `(db, caller, input, { limit?, cursor? })`. Other internal Views retain their bare row-array function.
 
-```ts
-const { rows } = await ctx.store.select({
-  from: "tickets",
-  columns: ["id", "subject"],
-  where: { ticketState: "open", subject: { like: "%refund%" } },
-  orderBy: { updatedAt: "desc" },
-  limit: 20,
-});
+Store keeps `find({ search: 'text' })`, `first({ search: 'text' })` and `count(where?)`. Search matches exact id or declared searchable fields under the same row policy.
+
+`count` scans every matching row. For large tables or frequently shown totals, use an internal View with indexed predicates or avoid exact totals; a View's aggregate still scans the matching rows.
+
+Store search, Admin list search and Views using `mantle.search` share the same dialect search. SQLite/D1 use FTS5 trigram for queries of 3 or more characters, and LIKE for shorter queries. PostgreSQL uses ILIKE over the declared fields, which scans by default. A View does not make PostgreSQL search faster. For large PostgreSQL tables, the application's agent adds trigram indexes in a migration; ILIKE then uses them with no code change:
+
+```sql
+CREATE EXTENSION IF NOT EXISTS pg_trgm;
+CREATE INDEX articles_title_trgm ON articles USING gin (title gin_trgm_ops);
 ```
 
-- `where`: `{ column: value }` is equality and sibling keys are AND; also
-  `{ column: { eq, ne, gt, gte, lt, lte, like, in, notIn, isNull } }`, and
-  `and`, `or`, `not`. `in` takes a list or `{ select, from, where }`.
-- `orderBy`: one column; `id` breaks ties. Default `{ updatedAt: "desc" }`.
-- `search`: text matched against `searchableFields` (and `id`).
-- Native columns are camelCase here (`createdAt`, `authorId`), while SQL spells
-  them snake_case (`created_at`).
+Index each searched field as needed and inspect EXPLAIN for the workload. Case folding follows the engine.
 
-`write` applies every operation or none, in order:
+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.
 
-```ts
-await ctx.store.write([
-  { update: "tickets", set: { ticketState: "closed" }, where: { id }, lock: expectedVersion },
-  { insert: "ticket-events", values: { ticketId: id, kind: "closed" } },
-]);
+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.
+
+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.
+
+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.
+
+## Prefer Store-backed ref Procedures for simple writes
+
+For a single-entity create or partial update, prefer a declared `ref` Procedure
+whose handler awaits its caller-bound `ctx.store.collection(...).insert(...)`
+or `.update(id, allowedPatch, { lock: expectedVersion })`. Keep the Procedure's
+`requires` and generated validation at its invocation boundary: Store enforces
+row policy, but does not substitute for operation authorization. Do not invoke
+a handler directly from a route and accidentally bypass those checks.
+
+Insert/update returns the actual written native row. Inside a transaction,
+that result is provisional until the outer transaction commits; later failure
+can still roll it back. Report committed success or emit external effects only
+after that transaction succeeds. Return an explicit
+allowlist of useful business fields, its backend `id` and returned `version`;
+do not spread the entire row, echo the submitted version, calculate a new
+version instead of reading the result, or add a generic receipt adapter. These
+ref results are app-owned: declare their output schema and make any required
+native-to-wire conversion explicit at the boundary.
+
+Patch only permitted fields. Omitted fields remain unchanged; define whether
+explicit null clears a nullable field or is invalid. Do not expand a partial
+request into a full replacement with defaults for unseen fields. A stale lock
+is a conflict; preserve intent and reconcile/review rather than silently
+refreshing the lock and retrying.
+
+Use SQL Procedures when conditions or related effects must commit together:
+for example, creating an order while decrementing stock under a CHECK, a state
+transition guarded by an atomic WHERE, or an additive restock upsert. A
+pre-read in TypeScript followed by an unguarded write is not equivalent.
+Store `batch` is atomic for known writes; a D1 batch step cannot consume a prior
+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";
 ```
 
-- `insert` with `values`, optional client `id` (`ctx.store.id()`) and
-  `onConflict: "ignore" | { columns, update }`. A scoped Schema refuses a
-  client `id`, because a chosen id could collide with another owner's row and
-  reveal it: give such rows a field of your own that is unique with the scope
-  field (`uniqueIndexes: [[owner, clientKey]]`) when other rows of the same
-  write must point at them, or when a retry must find them.
-- `update` with `set` and `where`; `delete` with `where`. A `where` that pins
-  `id` is a row op: it may carry `lock` (the version the caller saw), and
-  writing no row is `CONFLICT`.
-- A result is `{ id, version }` for a row op and `{ affected }` for a set op.
-- `set` and `values` never name the scope field or a native column (except
-  `status` on a `publishing` Schema, below); Store
-  fills them. A `null` leaves empty, or clears, a field the Schema does not
-  require (the generated `values` and `set` types accept it); for a required
-  field it is refused. On a `publishing` Schema, `set: { status }` is how a `ref`
-  handler publishes, unpublishes or archives.
-
-Failures throw `DiagnosticError` with `INPUT_VALIDATION_FAILED` (including a
-failed `check`), `CONFLICT` (`conflict.reason` is `lock`, `expect` or
-`unique`, and `conflict.opIndex` names the operation; for `unique` it is
-present when exactly one operation of the write targets the violated Schema,
-since the engine names the table and not the statement), `RESOURCE_UNAVAILABLE`
-or `OUTCOME_UNKNOWN`. Nothing is written on any failure. After
-`OUTCOME_UNKNOWN`, retry with the same client ids and locks: a replayed insert
-conflicts on its id, a replayed update on its lock.
-
-## From service code
-
-The service's `fetch` receives the runtime. Resolve the caller first, as the
-generated `withCaller` does, and bind Store to it:
+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
-const caller = await resolveCaller(request);
-if (!("caller" in caller)) return new Response("unauthorized", { status: 401 });
-const { rows } = await runtime.store.as(caller.caller).view("tickets-by-state", { input: { ticketState: "open" } });
-```
+import { store } from './generated/generated.js';
+import type { Caller } from '@aotter/mantle/contracts';
 
-To run a Procedure from service code, with its auth, guard and validation, call
-`runtime.invokeProcedure({ procedure, input, caller, cause: { kind: "internal", id } })`.
-Inside a handler, `ctx.invoke(name, input)` does the same and keeps the caller.
+// `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 });
+}
+```