@aotter/mantle 0.1.5-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,28 @@
 ---
-description: Generate and call typed Views, including internal-only queries, and choose indexed entry readers without confusing them with authorized public reads.
+description: Choose Store for writes and simple lookups; declare internal Views for richer reads.
 ---
 # Query from TypeScript
 
-Use a **View** when a read needs declared params, projection, pagination or
-`requires` authorization. Use an **entry reader** for trusted host code that
-needs stored entries by a data field. Both are exposed by generated bindings;
-only the View executes the declared View authorization contract.
+| 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 |
 
-## Declare an internal query
+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.
 
-Save this complete source as `manifests/tickets.yaml`. The operational Schema
-uses a business status field distinct from Mantle's native `status`.
+## Declare an internal View
+
+Save this as `manifests/tickets.yaml`:
 
 ```yaml
-apiVersion: cms.mantle.aotter.net/v1
+apiVersion: cms.mantle.aotter.net/v2
 kind: Schema
-metadata:
-  name: tickets
+metadata: { name: tickets }
 spec:
   title: Tickets
   lifecycle: operational
+  indexes: [[ticketState]]
   schema:
     type: object
     additionalProperties: false
@@ -28,134 +30,236 @@ spec:
     properties:
       subject: { type: string }
       ticketState: { type: string, enum: [open, closed] }
-  indexes: [[ticketState]]
 ---
-apiVersion: cms.mantle.aotter.net/v1
+apiVersion: cms.mantle.aotter.net/v2
 kind: View
-metadata:
-  name: tickets-by-state
+metadata: { name: tickets-by-state }
 spec:
   surface: internal
-  from: tickets
-  fields: [id, subject, ticketState]
-  filter:
-    eq: { field: ticketState, value: { $param: ticketState } }
-  params:
+  input:
     type: object
     additionalProperties: false
     required: [ticketState]
     properties:
       ticketState: { type: string, enum: [open, closed] }
-  limit: 50
+  sql: |
+    SELECT id, subject, ticketState AS "ticketState" FROM tickets
+    WHERE ticketState = input.ticketState
+    ORDER BY id ASC
 ```
 
-```sh
-pnpm exec mantle validate --no-source
-pnpm exec mantle generate
-pnpm exec mantle generate --check
+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 { 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 };
+}
 ```
 
-`internal` keeps this query out of REST routes, OpenAPI, MCP/WebMCP catalogs and
-Admin reports. It remains in the plan and generated binding. It is not a
-security bypass: adding `requires` evaluates the same authorization and guards
-against the host-supplied `ctx` on every call. No `uiSchema` or shared HTTP
-cache is allowed for an internal View.
+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.
 
-## Bind and call
+## Store reads and writes
 
-When the host already owns a prepared Runtime, bind it once where you need the
-typed API. This function can live in `src/queries.ts`:
+`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
-import type { MantleRuntime } from "@aotter/mantle/runtime";
-import { bindMantle } from "../.mantle/generated/mantle.js";
-
-export async function openTickets(runtime: MantleRuntime) {
-  const mantle = bindMantle(runtime);
-  const result = await mantle.views.ticketsByState({
-    params: { ticketState: "open" },
-    page: 1,
-    show: 20,
-  });
-  if (!result.ok) throw new Error(result.diagnostic.message);
-  return result.result.rows;
-}
-```
+Store keeps `find({ search: 'text' })`, `first({ search: 'text' })` and `count(where?)`. Search matches exact id or declared searchable fields under the same row policy.
 
-The runtime response uses `result` on success (`result.result.rows` above);
-REST wraps those rows under `data` instead.
+`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.
 
-The wire name `tickets-by-state` becomes `ticketsByState`. Required params
-make the request and `params` mandatory; invalid enum values are TypeScript
-errors, and Runtime also validates actual inputs. `show` remains capped by
-`limit`. For an authorized View, pass the verified caller context as `ctx`;
-do not fabricate staff/user identities from request input.
+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:
 
-A host without a Runtime can use generated `createMantle({ storage, handlers,
-ports })`, which delegates one eager boot attempt and returns the typed
-binding. Host code still owns connection lifetime and retries. See
-[Runtime and adapters](../concepts/runtime-and-adapters.md).
+```sql
+CREATE EXTENSION IF NOT EXISTS pg_trgm;
+CREATE INDEX articles_title_trgm ON articles USING gin (title gin_trgm_ops);
+```
 
-## What is typed
+Index each searched field as needed and inspect EXPLAIN for the workload. Case folding follows the engine.
 
-| Query form | Generated shape | Limit |
-|---|---|---|
-| Declarative View | `Mantle.ViewParams_<name>` and `Mantle.ViewRow_<name>` | Projection follows `fields`; native columns have their native types. Data properties remain optional in the row type. |
-| SQL View | Typed params; row type `unknown` | The generator does not infer SQL expressions or aliases. Narrow/validate rows in host code. |
-| Entry field reader | `MantleEntry<Mantle.Entry_<schema>>` | The field must be a declared data property and the value a compatible string, number or boolean. Types do not prove an index exists. |
-| Dynamic Runtime call | `runtime.executeView({ view, ctx, options })` | Useful without codegen; supplying a generic row type is the caller's assertion, not SQL validation. |
+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.
 
-Without `fields`, a declarative View includes native entry columns and Schema
-properties. Use explicit projections on exposed reads. Public declarative
-Views over publishing Schemas inject `status = published`; internal/staff
-Views and SQL statements do not. See [View reference](../reference/view.md).
+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.
 
-## Indexed entry reads
+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.
 
-For the Schema above:
+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.
 
-```ts
-const rows = await mantle.entries.tickets.findManyByDataField({
-  field: "ticketState",
-  value: "open",
-  limit: 20,
-});
-// rows[n].data is the generated tickets data shape.
-```
+## Prefer Store-backed ref Procedures for simple writes
 
-| Method | Returns | Options worth knowing |
-|---|---|---|
-| `readBySlug({ slug, locale?, status? })` | One entry or `null` | Use on a Schema with a slug field and an appropriate index. |
-| `readByDataField({ field, value, locale?, status? })` | One entry or `null` | Equality on one data property. |
-| `readByDataFieldIn({ field, values, latestPerValue?, locale?, status? })` | Entry array | Batch equality lookups; `latestPerValue` selects the newest match per value. |
-| `findManyByDataField({ field, value, limit })` | Entry array | Bounded equality lookup across statuses; no `ctx`, `status` or `locale` option. |
+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.
 
-These readers do not evaluate View `requires`, inject public visibility or
-fire mutation hooks. In particular, `findManyByDataField` can return drafts.
-Use a public View for untrusted callers; do not expose a raw reader as a public
-route and assume the generated type authorizes it. Declare a measured index
-whose leftmost field matches the lookup; do not scan an entire collection in
-TypeScript to replace a field query.
+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.
 
-## Generate from an existing plan
+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.
 
-A build tool that already compiled a sealed plan can use the pure emitter:
+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.
 
-```ts
-import { emitMantleModule } from "@aotter/mantle/codegen";
+## 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.
 
-const emitted = emitMantleModule({ plan });
-if (!emitted.ok) throw new Error(emitted.diagnostics.map(d => d.message).join("\n"));
-// Write emitted.source to your generated module in the build step.
+```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";
 ```
 
-Pass either `{ plan }` or `{ linked }`, never both. The plan form avoids
-reparsing YAML and preserves the same generated types and entry/View/Procedure
-bindings. The emitter does no I/O, asset copying, storage preparation or caching.
+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.
 
-## Source
+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.
 
-- [Binding generator](../../../packages/mantle/src/codegen/emitMantleModule.ts)
-- [Type generator](../../../packages/mantle-spec/src/usecase/EmitTypesUseCase.ts)
-- [Entry reader contract](../../../packages/mantle-runtime/src/domain/port/EntryReader.ts)
-- [View execution](../../../packages/mantle-runtime/src/usecase/view/ExecuteViewUseCase.ts)
+[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 });
+}
+```