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

package/docs/handbook/reference/features.md

@@ -1,53 +1,45 @@
----
-description: A task-to-feature table for Mantle 0.2.0 manifests — what to declare for each common need, with links to the field reference and an example.
----
-# Manifest feature reference
-
-| You need | Declare | Reference | Example |
-|---|---|---|---|
-| A table | a Schema with a JSON Schema | [Schema](./schema.md) | every example |
-| Authored content with drafts and publishing | `lifecycle: publishing` (the default) | [Lifecycle](../concepts/lifecycle-and-locales.md) | [Publication](../../examples/publication.md) |
-| Records written by the system | `lifecycle: operational` | [Lifecycle](../concepts/lifecycle-and-locales.md) | [Intake form](../../examples/intake.md) |
-| Rows only their owner may ever see | `scope: { owner: auth.uid() }` | [Authorization](../concepts/authorization.md) | reference service `orders` |
-| A member sees their own rows, staff see all | store `auth.uid()` in the SQL, filter `WHERE x = auth.uid()` | [Authorization](../concepts/authorization.md) | [Procurement](../../examples/procurement.md) |
-| A rule every write obeys | `checks: ["stock >= 0"]` | [Schema](./schema.md#checks) | [Commerce inventory](../../examples/commerce-inventory.md) |
-| Uniqueness | `uniqueIndexes` | [Schema](./schema.md#indexes) | [Commerce](../../examples/commerce.md) |
-| Full-text search | `searchableFields` and `mantle.search` | [View](./view.md) | [Publication](../../examples/publication.md) |
-| Places | `format: geo` and `mantle.near` / `mantle.distance` | [View](./view.md) | |
-| Rows that expire | `ttl`, then `sweepExpired` | [Lifecycle](../concepts/lifecycle-and-locales.md#ttl) | |
-| Translations | `localized`, `translates` | [Schema](./schema.md#localized-and-translates) | [Publication](../../examples/publication.md) |
-| A public read | a View, `surface: public` | [View](./view.md) | every example |
-| A staff report with CSV | a View, `surface: staff`, `uiSchema.list` | [Admin](../guides/admin-ui.md) | [Reservation](../../examples/reservation.md) |
-| A read only code uses | a View, `surface: internal` | [Query from TypeScript](../guides/typed-queries.md) | [Commerce inventory](../../examples/commerce-inventory.md) |
-| Joins, aggregates, windows | the View's SQL | [View](./view.md#what-the-d1-dialect-accepts) | reference service `sales-by-item` |
-| A write | a Procedure with `handler: { sql }` | [Procedure](./procedure.md) | every example |
-| Several writes, all or nothing | several statements in one `sql` | [Procedure](./procedure.md#handlersql) | reference service `place-order` |
-| An upsert | `INSERT … ON CONFLICT (…) DO UPDATE` | [Procedure](./procedure.md) | reference service `restock` |
-| No lost updates | `WHERE id = input.id AND version = input.expectedVersion` | [Procedure](./procedure.md#row-ops-and-set-ops) | [Commerce](../../examples/commerce.md) |
-| Code: call a service, read then write, set `status` | `handler: { ref }` | [Procedure](./procedure.md#handlerref) | [Commerce inventory](../../examples/commerce-inventory.md) |
-| An HTTP route | a Trigger `kind: http` | [Trigger](./trigger.md#http) | every example |
-| An agent tool | a Trigger `kind: mcp`, or a View | [MCP and agents](../concepts/mcp-and-agents.md) | every example |
-| An Admin operation | a Trigger `kind: mcp, surface: staff` | [Admin](../guides/admin-ui.md) | [Procurement](../../examples/procurement.md) |
-| Signed-in callers only | `requires: { auth: { all: [ctx.user] } }` | [Authorization requirements](./authorization.md) | [Procurement](../../examples/procurement.md) |
-| Staff roles | `{ ctx.staff: [owner, editor] }` | [Authorization requirements](./authorization.md) | [Commerce](../../examples/commerce.md) |
-| API keys and scopes | a custom `CallerResolver`, `{ ctx.auth.scope: … }` | [Authorization](../concepts/authorization.md) | [Guarded API access](../../examples/guarded-api.md) |
-| A live check before one action | `requires.guard` | [Authorization requirements](./authorization.md#guard) | [Intake with bot check](../../examples/intake-hooks.md) |
-| A rule before every write of a Schema | a `before_*` lifecycle Trigger | [Trigger](./trigger.md#lifecycle) | |
-| Side effects after a write | an `after_*` lifecycle Trigger | [Trigger](./trigger.md#lifecycle) | [Intake with bot check](../../examples/intake-hooks.md) |
-| A recurring job | a Trigger `kind: schedule` (POSIX cron) | [Trigger](./trigger.md#schedule) | [Commerce inventory](../../examples/commerce-inventory.md) |
-| A signed webhook | a route in the service's `fetch`, then `runtime.invokeProcedure` | [Writes](../concepts/procedures-and-triggers.md#webhooks) | [Commerce inventory](../../examples/commerce-inventory.md) |
-| Media uploads | `d1Storage(db, { site })` and `r2MediaStorage` | [Media uploads with R2](../cloudflare/media-r2.md) | |
-
-## Not in 0.2.0
-
-| 0.1.x feature | In 0.2.0 |
-|---|---|
-| builtin handlers (`create`, `update`, `upsert`, `delete`, `archive`) | SQL statements; `archive` is a `ref` handler setting `status` |
-| the Filter AST, `params`, `$param`, `$ctx.user` | the View's SQL, `input`, `input.<name>`, `auth.uid()` |
-| `page` / `show` | `limit` / `cursor` |
-| `x-mantle-bind` | `scope`, or `auth.uid()` / `now()` in the SQL |
-| generated record tools on Staff MCP | declared Procedures with `mcp` Triggers |
-| `errorPolicy` on lifecycle hooks | before hooks fail closed; after hooks are best effort |
-| deferred hooks on a Queue | after hooks run after the commit; a queue is the service's own |
-| Mantle-rendered public pages, templates, sitemap | not ported; render from your own `fetch` |
-| `mantle validate`, `emit-openapi`, `mantle skills` | `mantle generate` and `mantle generate --check` |
+# Supported declarations
+
+The native 0.2.0 SDK compiles the closed v2 grammar for four targets. Generation diagnostics, rather than historical APIs or release plans, define the checked-out implementation. Existing integrations require explicit app wiring and data migration; initial schema.sql is for an empty database.
+
+## Supported
+
+| Feature | Availability / agent action |
+| --- | --- |
+| Closed v2 Schema/View/Procedure grammar, PostgreSQL SQL authoring | Generated for Bun SQLite, Bun PostgreSQL, Cloudflare D1 and Cloudflare PostgreSQL; dialect behavior stays native. |
+| Operational Schemas, scope, TTL read visibility, indexes, checks, native SQL facilities | Generated initial DDL and compiled SQL policy; run migrations and TTL maintenance in application code. |
+| System-only TTL maintenance | Generated `<schema>.sweepExpired`, bounded cursor scans and optional dry-run; app owns `scheduled()` wiring and cron configuration. See [TTL maintenance](../guides/native-execution.md#ttl-maintenance). |
+| Typed SQL Views and Procedures, auth predicates, OCC, atomic writes | Generated bare queries accept validated inputs and a verified Caller; date/date-time outputs are ISO strings, native errors stay internal. |
+| Typed Store collections and internal Views/Procedures | Shared Store, AND-only filters, indexed non-null keyset ordering, atomic batches; interactive transactions on SQLite/PostgreSQL. |
+| Searchable fields, Store search and SQL search/rank | Generated SQLite/D1 FTS5 trigram table and maintenance triggers; PostgreSQL ILIKE. Store find/first trim non-empty search and match exact id OR declared fields, within the caller's row rules. |
+| Better Auth integration and Workers builds | App owns `auth.ts` and `resolveCaller`; optional [OAuth helpers](../guides/oauth.md) provide consent/connected apps, live grant/session checks and DPoP. `mantle generate` emits native Wrangler build configuration. Keep heavy auth imports lazy. |
+| Transactional email port, English templates and dev console sender | Optional `@aotter/mantle/email`; app supplies the sender and passes locale through. See [email wiring](../guides/email.md). |
+| View keyset pages, generated boundary validation and HTTP error mapping | Generated `paged/views/*` for proved exposed/internal Views: indexed non-null tuples, complete groups and singleton joins/lookups; `validation/*` and `wire`; see [surface contracts](surface.md). |
+| REST and `http` Trigger exposure | Supported generated `rest.ts`; app mounts with `{ db, caller }` and required `handlers` for ref contracts. Public Views page at `/api/views/<name>`; HTTP Triggers keep method/path. |
+| Generated MCP and `mcp` Trigger exposure | Public/admin tools, shared generated checks, publishing transitions on admin only; SDK loads on matching requests. Install the official MCP peer for manifests selecting this surface. |
+| Dynamic `web.ts` (`llms.txt`, sitemap, `.md` alternates, head tags) | Generated; mount `web({ ... })`; see [surface contracts](surface.md#optional-web-output). |
+| Native Admin bindings, server and console | Supported; select `--admin` / `admin: true` and mount `entries(bindings.schemas, bindings.adapter)`. Shared authorized read templates, native Procedure writes and the console; see [Native Admin](../guides/native-admin.md).  |
+| Localized Schemas and translations | Plain-string locale values, atomic published-parent guard, SQL parent visibility and generated page locale helper; see [Translations](../concepts/lifecycle-and-locales.md#translations). |
+| Opt-in `lifecycle: publishing` | Generated status, `published_at`, admin-only transitions and published-only public reads; see [Publishing](../concepts/lifecycle-and-locales.md). |
+| `ref` Procedures and typed `Handlers` | Generated `Handlers` type; pass implementations at `store(db, caller, { handlers })`; `mantle generate` lists them. See [ref Procedures](../guides/native-execution.md#ref-procedures). |
+| Optional site settings and media | Select `site` defaults at generation to emit the generated `site` module and deployment tables; native media upload lifecycle, app-owned R2/signing. See [media](../cloudflare/media-r2.md). |
+
+## Refused
+
+Each unsupported declaration produces `GENERATE_UNSUPPORTED`, its manifest path,
+and the following hint. Invalid grammar/SQL retains the compiler's own diagnostic
+codes and paths. Multiple declarations produce multiple diagnostics.
+
+| Declaration | Do instead |
+| --- | --- |
+| `schedule` Triggers, including disabled ones | Wire `scheduled()` yourself. |
+| `lifecycle` Triggers: before/after hooks, including targets using `ref` | Write a custom handler. |
+| `requires.guard` on a View or Procedure | Write a custom handler that checks authorization before executing queries. |
+| A View projecting a native `geo` value | Select the latitude and longitude columns explicitly. |
+| Dynamic or repeated View output names | Give each SELECT output a unique explicit alias. |
+| Declared date/date-time outputs without one SELECT item per output | Expand the SELECT list explicitly. |
+| Input properties differing only in case | Rename input properties to be unique without regard to case. |
+| PostgreSQL JSON/date/date-time parameters used without the declared cast | Wrap each occurrence in the concrete `CAST(... AS <type>)` shown by the diagnostic. |
+
+
+Store handles simple AND reads and writes; use internal Views for OR, joins, aggregates and reuse. Ref Procedures are supported with a typed caller/transaction-bound Store. See [typed queries](../guides/typed-queries.md), [lifecycle/locales](../concepts/lifecycle-and-locales.md) and [database ownership](../concepts/runtime-and-adapters.md).

package/docs/handbook/reference/manifest.md

@@ -1,74 +1,11 @@
----
-description: The manifest envelope of Mantle 0.2.0 — apiVersion, kind, metadata, files and documents, names, localized text, and the SQL naming conventions every atom shares.
----
-# Manifest envelope and conventions
+# Manifest envelope
 
-```yaml
-apiVersion: cms.mantle.aotter.net/v2
-kind: Schema            # Schema | View | Procedure | Trigger
-metadata:
-  name: orders          # required, unique per kind
-spec: { … }             # kind-specific
-```
+Every YAML document has `apiVersion: cms.mantle.aotter.net/v2`, `kind`, `metadata.name` and `spec`. Kinds are Schema, View, Procedure and Trigger. Pass explicit file paths to `mantle generate`; a file may contain several documents separated by `---`.
 
-- `apiVersion` is exactly `cms.mantle.aotter.net/v2`. A `v1` document fails
-  and names the upgrade guide.
-- `metadata` has `name` only.
-- Unknown keys anywhere in `spec` are refused, not ignored.
+The grammar is closed. Unknown keys and invalid declarations fail generation. Names are unique per kind; Schema and field names cannot differ only by case. Quote non-identifier Schema names in SQL. `input` and `auth` are reserved.
 
-## Files
+Titles and descriptions accept a string or locale map, such as `{ en: Products, zh-TW: 商品 }`. Selected UI/MCP chooses the configured locale with fallback.
 
-`mantle generate` reads every `.yaml` and `.yml` file directly in the manifest
-directory (`./manifests`, or `--manifests <dir>`), not subdirectories. A file
-may hold several documents separated by `---`. File names and order do not
-matter to the plan; they enter only `sourceHash`.
+Author SQL in PostgreSQL syntax. Generation renders it for postgres or sqlite, including bound inputs and compiled row policy. SQL native columns use `id`, `version`, `created_at`, `updated_at`, `author_id`, plus `status` / `published_at` for publishing. Store uses storage names too. Manifest index declarations use authored field/native names (`createdAt`), which compile to storage names.
 
-## Names
-
-- Names are unique per kind (`DUPLICATE_NAME`). Two Schemas, or two fields of
-  one Schema, may not differ only in case: SQL resolves identifiers
-  case-insensitively.
-- A Schema name that is not a plain identifier (`support-tickets`) is written
-  quoted in SQL: `"support-tickets"`.
-- `input` and `auth` are reserved and cannot name a Schema or an alias. On
-  the `sqlite` dialect, SQL may not name a Schema, field or alias that is one
-  of the 14 words SQLite refuses unquoted (`SQL_UNSUPPORTED`):
-  `add alter autoincrement commit delete drop escape index insert nothing raise set transaction update`.
-- MCP tool names are the View or Procedure name in snake case.
-
-## Localized text
-
-`title` and `description` on every atom, and `title` and `description` on
-JSON Schema properties, take a string or a locale map:
-
-```yaml
-title: { en: Products, zh-TW: 商品 }
-```
-
-Admin chooses the viewer's locale and MCP the surface's `locale` option (default `en`), then `en`, then the first entry.
-
-## SQL conventions
-
-| | |
-|---|---|
-| Syntax | PostgreSQL, parsed by PostgreSQL 18's parser; a dialect decides what runs |
-| Native columns | snake_case in SQL: `id`, `status`, `version`, `created_at`, `updated_at`, `author_id`. In `ctx.store` JSON, in `indexes` and in Schema `uiSchema`: `createdAt`, `updatedAt`, `authorId` |
-| References | `input.<name>`, `auth.uid()`, `auth.role()`, `now()` |
-| Mantle functions | `mantle.search`, `mantle.search_rank`, `mantle.near`, `mantle.distance` |
-| Literals | SQL literals; strings in single quotes |
-| Multi-line SQL | a YAML block scalar (`sql: \|`) |
-
-## Wire values
-
-| JSON Schema | On the wire |
-|---|---|
-| `format: date-time`, and the native `createdAt` / `updatedAt` | an ISO 8601 string |
-| `format: date` | `YYYY-MM-DD` |
-| `boolean` | `true` / `false` |
-| `object`, `array` | JSON |
-
-## Generated output
-
-`plan.json` and `mantle.ts` under `.mantle/generated/` are rewritten by every
-`mantle generate` and compared by `--check`. Commit them; never edit them. See
-[Project layout and CLI](../start/project-and-cli.md).
+Use `input.<name>`, `auth.uid()`, `now()` and supported `mantle.*` functions. Only declared relations and allowed SQL constructs may be referenced. See [Schema](schema.md), [View](view.md), [Procedure](procedure.md), [Trigger](trigger.md) and [CLI](../start/project-and-cli.md).

package/docs/handbook/reference/procedure.md

@@ -1,127 +1,23 @@
----
-description: Procedure field reference for Mantle 0.2.0 — input and output, SQL and ref handlers, write rules, row ops and locks, target, mcp annotations, uiSchema and diagnostics.
----
 # Procedure
 
-```yaml
-apiVersion: cms.mantle.aotter.net/v2
-kind: Procedure
-metadata: { name: review-order }
-spec:
-  title: Review order                 # optional, a string or a locale map
-  description: …                      # optional; the MCP tool's and Admin operation's description
-  requires: { … }                     # optional, see Authorization requirements
-  input: { type: object, … }          # required JSON Schema
-  output: { type: object }            # required JSON Schema
-  handler: { sql: "…" }               # or { ref: <name> }
-  target: { schema, id, version? }    # optional; inferred for one locked row op
-  mcp: { destructiveHint: true }      # optional tool annotations
-  uiSchema: { … }                     # optional, Admin only
-```
+A Procedure requires `input`, `output` JSON Schemas and a `handler` containing SQL or a ref name. Optional fields include title, description, requires, target, MCP annotations and Admin uiSchema. See [manifest envelope](manifest.md).
 
-`input` is validated before the handler runs (`INPUT_VALIDATION_FAILED`),
-and the result against `output` (`OUTPUT_VALIDATION_FAILED`, a 500: the bug
-is the handler's). `expectedVersion` is the conventional input name for the
-version a caller read.
+SQL uses declared Schemas, `input.<name>`, `auth.uid()` and the expressions [the SQL reference](sql.md) lists for the selected dialect; [SQL patterns](../guides/sql-patterns.md) shows conditional status, approval, partial updates, upserts and guards. Compiler policy supplies scope and system fields. Do not assign scope, version, status, published_at, timestamps or author columns yourself. A SQL Procedure cannot write a `publishing` Schema: create and edit its rows from a ref handler through the Store, and change status with the generated publish/unpublish/archive transitions. `restrict` narrows the rows the statements read and write, as on a [View](view.md#restrict); it is refused on ref handlers.
 
-## `handler.sql`
+A row-classified INSERT/UPDATE/DELETE (one that targets a single row, e.g. `WHERE id = input.id`) must affect one row. Use `WHERE id = input.id AND version = input.expectedVersion` for explicit OCC. Set operations, including UPDATE with a subquery and `INSERT ... SELECT`, may affect zero rows without an error: check the returned rows when zero means failure. A unique clash, a failed Schema `checks` constraint or a failed row assertion is `CONFLICT` (409) with `kind` `"unique"`, `"check"` or `"row"` ([diagnostics](diagnostics.md)); statements run atomically. A check failure keeps that code, and its message is `A check of the Schema failed: <schema>: <check>` on every target, with the driver's own error only in `cause`; `ContractError.fields` is `{ kind: "check", schema, check }`. `check` is the expression on SQLite/D1 and the generated constraint name on PostgreSQL. Results are raw `{ results }`: one array of RETURNING rows per statement, in order (`results[0][0].id` is the first statement's first row), not runtime-validated authored outputs, with driver-native values: a SQLite/D1 boolean is `1`/`0` here, while a View returns a declared boolean column as `true`/`false`; read a row back through a View when a client needs the typed form. An array input is a row source: `json_each(input.items)` on SQLite/D1 and `jsonb_array_elements(input.items) AS j(value)` on PostgreSQL write any number of rows in the same atomic program. Callers pass the array itself (from a handler, `ctx.store.procedures["place-order"]({ orderRef, items })`); the generated input type is the authored one and the generated query serializes a JSON input for the driver, so no `JSON.stringify` is needed (a string is bound as it is). See [several rows that commit together](../guides/typed-queries.md#several-rows-that-commit-together). RETURNING uses SQL output names; quote an explicit alias to preserve declared case (`RETURNING reqStatus AS "reqStatus"`). Generation warns about unaliased direct fields whose declared name differs from storage.
 
-One or more `INSERT`, `UPDATE` and `DELETE` statements separated by `;`,
-applied as one batch: all or nothing, in order. The output is
-`{ "results": [[…], …] }`, the `RETURNING` rows of each statement in order; so
-an `output` of `{ type: object }` accepts it.
+A row-classified UPDATE/DELETE on an excluded or missing id affects zero rows and returns HTTP 409 (`CONFLICT`), just like a stale version; reads return not found. Native Admin's visible-row pre-read returns 404 for excluded/missing ids.
 
-| Statement | Supported |
-|---|---|
-| `INSERT` | `INSERT INTO t (cols) VALUES (…)` (one row), `INSERT INTO t (cols) SELECT …`, `ON CONFLICT (cols) DO NOTHING \| DO UPDATE SET c = EXCLUDED.c …`, `RETURNING` |
-| `UPDATE` | `UPDATE t SET c = <expr> … WHERE …`, `RETURNING` |
-| `DELETE` | `DELETE FROM t WHERE …`, `RETURNING` |
+A ref handler is application code called as `(ctx, input)`. Generation lists the `Handlers` keys the app must provide (every run, whether or not they exist yet); `tsc --noEmit` checks the implementation against the generated `Handlers` type. Wire them at `store(db, caller, { handlers })` and selected surfaces. The context has the Caller, the native db and a Store for that caller. A handler is not one transaction by itself: when it runs inside a caller's `store.transaction`, its db and Store are that transaction's; otherwise each write commits on its own. On PostgreSQL and bun:sqlite, `ctx.transaction(async ({ store, db }) => …)` makes writes that must commit together atomic; it joins the transaction the handler already runs in. A joined transaction has no savepoint, so let an error inside `ctx.transaction` propagate: a handler that catches it and carries on keeps the writes made before the error. Keep external calls (payments, supplier APIs) outside it, so a callback never waits for an uncommitted row. D1 has no interactive transactions, so its `HandlerContext` has no `transaction`: put writes that must commit together in one SQL Procedure, whose statements commit together, and call it through `ctx.store.procedures`. It is not a sandbox; the app owns external side effects and input/output handling. The context has no `env`: on Workers read bindings and secrets with `import { env } from "cloudflare:workers"`. The Caller carries no name or email; `userOf(caller)` from `@aotter/mantle/auth` returns the Better Auth user record it was resolved from, for session, OAuth and service credentials alike (undefined for system callers).
 
-Expressions are those of [View SQL](./view.md#what-the-d1-dialect-accepts).
-References: `input.<name>`, `auth.uid()`, `auth.role()`, `now()`.
+`target: { schema, id, version? }` binds an Admin operation to a row. SQL targets can be inferred for a single locked row operation; declare a target for a ref operation when needed. Input fields must have the required shapes.
 
-**A write may not name** the scope field, `version`, `status`, `created_at`,
-`updated_at`, `author_id`, or `id` in an `UPDATE`, in a column list, `SET` or
-`DO UPDATE SET`; on a scoped Schema an `INSERT` names no `id`. Store fills
-them (`SQL_WRITE`). Multi-row `VALUES` is refused: insert from
-`json_each(input.items)` instead. `UPDATE … FROM`, `DELETE … USING`,
-`INSERT OR …` and `last_insert_rowid()` are refused.
+## MCP tool hints
 
-**RETURNING names** fold to lower case unless quoted:
-`RETURNING id, orderNumber AS "orderNumber"`.
+Every generated AI-facing tool (MCP, WebMCP, publishing and media tools) carries a `title`, `readOnlyHint` and `destructiveHint`; clients such as Claude use them to decide between auto-approval and confirmation. The title is the declared `title`, else the name made readable (`add-item` reads `Add item`). A View is `readOnlyHint: true, destructiveHint: false`. A Procedure is `readOnlyHint: false`, and `destructiveHint` is `false` only when its SQL inserts without overwriting: any DELETE or UPDATE, an `ON CONFLICT DO UPDATE` or a ref handler makes it `true`. Of the generated publishing transitions only `archive` is destructive. The media tools always carry `openWorldHint: true`; the upload policy, list and get tools are read-only and only `delete_media_asset` is destructive. Admin's WebMCP navigation tools (`admin_get_context`, `admin_navigate`) are read-only. `spec.mcp` accepts `readOnlyHint`, `destructiveHint` and `openWorldHint`, and a declaration always wins; a declared `readOnlyHint: true` defaults `destructiveHint` to `false`. Outside the media tools `openWorldHint` appears only when declared. `idempotentHint` is never generated, and `spec.mcp` refuses it. Hints never change authorization.
 
-### Row ops and set ops
+Generated requires checks gate calls. Boundary input validators are generated separately; direct queries accept driver-ready, app-validated input. Dynamic guards and lifecycle hooks are rejected. See [native execution](../guides/native-execution.md) and [surface contracts](surface.md).
 
-- **Row op**: an `UPDATE` or `DELETE` whose top-level `WHERE` has
-  `id = <value>`, or a one-row `INSERT … VALUES` without `ON CONFLICT`. If it
-  writes no row the batch fails with `CONFLICT` and nothing applies.
-- **Set op**: everything else. Writing no row is a normal result. Refused on a
-  `publishing` Schema, and on a Schema with a `before_*` hook for that
-  operation.
-- **Lock**: `AND version = input.<name>` in a row op's `WHERE`. A stale version
-  matches nothing, so it is `CONFLICT` (HTTP 409).
+SQL `INSERT … VALUES`/upsert into a user-field scoped Schema follows the Store's insert rule ([field scope](schema.md#field-scope)); `INSERT … SELECT` into it is system-only, so a ref handler inserts those rows through `ctx.store`. `ctx.store` speaks storage names, not the manifest's: the handler's `input` uses authored names (`input.parentId`), while Store writes, filters and rows use the folded column (`insert({ parentid: input.parentId })`, `where: { parentid }`, `row.parentid`); generated Store types show the exact names ([typed queries](../guides/typed-queries.md)). SET cannot change a field-scope column, including ON CONFLICT DO UPDATE. Scoped unique conflict targets gain the owner/field prefix automatically.
 
-### `target`
-
-`{ schema, id, version? }`: the Schema the Procedure mutates, the required
-string input holding the row id, and the integer input holding the version it
-locks. Admin binds an operation to a row by it. A Procedure whose SQL is
-exactly one row op pinning `id` (and `version`) to inputs gets it inferred;
-declare it for a `ref` handler. `PROCEDURE_TARGET_INVALID` when the inputs do
-not have those shapes.
-
-## `handler.ref`
-
-```yaml
-handler: { ref: cancelOrder }
-```
-
-The name of a function in the service's `handlers` map. The generated
-`MantleHandlers` type lists exactly the plan's refs, with typed input and
-output; boot refuses a missing one (`HANDLER_NOT_REGISTERED`) and an extra
-one (`HANDLER_NOT_DECLARED`).
-
-```ts
-(input, ctx) => output | Promise<output>
-// ctx: { caller, cause, store, invoke, env, waitUntil }
-```
-
-A handler reaches Mantle-owned rows only through `ctx.store`
-([Query from TypeScript](../guides/typed-queries.md)). It throws
-`DiagnosticError` (from `@aotter/mantle`) to answer with a code; any
-other throw is logged and answered as `INTERNAL_ERROR`. Guards, before hooks
-and lifecycle targets must be `ref` handlers.
-
-## `requires`
-
-`requires.auth.all` (predicates) and `requires.guard.procedure` (a `ref`
-Procedure run before this one). See
-[Authorization requirements](./authorization.md).
-
-## `mcp`
-
-`readOnlyHint`, `destructiveHint`, `openWorldHint` (booleans), copied onto the
-MCP tool. `readOnlyHint` and `destructiveHint` may not both be true, and a SQL
-handler, which always writes, may not claim `readOnlyHint: true`.
-
-## `uiSchema`
-
-| Key | Effect in Admin |
-|---|---|
-| `fields.<name>.widget: textarea` | a multiline input |
-| `collectionAction: <schema>` | offer the operation on that collection's list |
-
-Admin lists a Procedure as an operation only when a Trigger binds it to the
-staff MCP surface.
-
-## Diagnostics
-
-Validate: `SQL_SYNTAX`, `SQL_UNSUPPORTED`, `SQL_FUNCTION`, `SQL_RELATION`,
-`SQL_COLUMN`, `SQL_WRITE`, `SQL_SHAPE`, `SQL_TYPE`, `PROCEDURE_TARGET_INVALID`,
-`GUARD_PROCEDURE_UNKNOWN`, `GUARD_SELF_REFERENCE`, `GUARD_PROCEDURE_NOT_REF`,
-`GUARD_CHAIN_NOT_ALLOWED`, `MCP_TOOL_DESCRIPTION_MISSING` (a warning),
-`MCP_TOOL_INPUT_UNION_AMBIGUOUS`, `MCP_TOOL_INPUT_UNBOUNDED`. Boot:
-`HANDLER_NOT_REGISTERED`, `HANDLER_NOT_DECLARED`. Run time:
-`INPUT_VALIDATION_FAILED`, `UNAUTHENTICATED`, `AUTH_DENIED`,
-`ENTITLEMENT_REQUIRED`, `CONFLICT`, `OUTPUT_VALIDATION_FAILED`,
-`INVOCATION_DEPTH_EXCEEDED`, `INTERNAL_ERROR`. See [Diagnostics](./diagnostics.md).
+Triggers are the only way request data reaches a Procedure: REST and MCP validate the input against the Procedure's schema, then call it. App code may also call a generated Procedure directly (`import run from "../generated/procedures/<name>.js"`, `await run(db, caller, input)`) or through the Store (`ctx.store.procedures[name](input)` in a handler); `requires`, row policy and checks still apply, but input validation does not, so pass only data the app produced or has verified (a cron job, a callback after its signature check). A page that takes user input submits it to the Procedure's REST Trigger; see `node_modules/@aotter/mantle/docs/examples/purchasing/src/requests-page.ts`.