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

package/docs/handbook/reference/trigger.md

@@ -1,104 +1,77 @@
----
-description: Trigger field reference for Mantle 0.2.0 — http, mcp, lifecycle and schedule sources, POSIX cron and its Cloudflare translation, and the diagnostics each raises.
----
 # Trigger
 
 ```yaml
 apiVersion: cms.mantle.aotter.net/v2
+kind: Schema
+metadata: { name: tickets }
+spec:
+  title: Tickets
+  lifecycle: operational
+  schema: { type: object, required: [closed], properties: { closed: { type: boolean } } }
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Procedure
+metadata: { name: close-ticket }
+spec:
+  requires: { auth: { all: [ctx.admin] } }
+  input: { type: object, required: [id, version], properties: { id: { type: string }, version: { type: integer } }, additionalProperties: false }
+  output: { type: object }
+  handler: { sql: 'UPDATE tickets SET closed=true WHERE id=input.id AND version=input.version RETURNING id,closed' }
+---
+apiVersion: cms.mantle.aotter.net/v2
 kind: Trigger
-metadata: { name: place-order-http }
+metadata: { name: close-ticket-http }
 spec:
-  source: { kind: http, method: POST, path: /api/orders }
-  target: { procedure: place-order }
+  source: { kind: http, method: POST, path: '/api/tickets/{id}/close' }
+  target: { procedure: close-ticket }
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Trigger
+metadata: { name: close-ticket-mcp }
+spec:
+  source: { kind: mcp, surface: admin }
+  target: { procedure: close-ticket }
 ```
 
-`target.procedure` names a declared Procedure
-(`TRIGGER_TARGET_PROCEDURE_UNKNOWN`). Several Triggers may target one
-Procedure; each source runs it as an `Invocation` with the same `requires`,
-guard and validation.
-
-## `http`
-
-| Field | Values |
-|---|---|
-| `method` | `POST`, `PUT`, `PATCH`, `DELETE` (reads are Views) |
-| `path` | starts with `/api/` (`TRIGGER_PATH_INVALID`); `{param}` segments bind to inputs of the same name, coerced to their declared types |
-
-The REST surface answers it. The JSON body and the path parameters merge into
-the input (a path parameter wins). A `(method, path)` pair is unique
-(`TRIGGER_PATH_COLLISION`); a route with fewer parameters is tried first, so
-`/api/items/search` is not shadowed by `/api/items/{id}`. The answer is the
-Procedure's output, or `{ "error": … }`. `ctx.cause.kind` is `http`.
-
-The body is parsed JSON. For a signed webhook, verify the raw body in the
-service's own `fetch` and call `runtime.invokeProcedure`.
-
-## `mcp`
+The target names a declared Procedure. `http` sources use POST/PUT/PATCH/DELETE and an `/api/` path. Path parameters bind to corresponding declared input fields and override JSON-body values. The generated REST module retains the Procedure's authorization and validates boundary input.
 
-| Field | Values |
-|---|---|
-| `surface` | `public` (`/mcp`) or `staff` (the staff MCP surface; also an Admin operation) |
+An MCP source is `{ kind: mcp, surface: public }` or admin. The selected MCP module exposes the Procedure as a snake-case tool with its description, [tool hints](procedure.md#mcp-tool-hints) and requires checks.
 
-The tool is named after the Procedure, kebab to snake case
-(`MCP_TOOL_NAME_COLLISION` when two names meet). Give the Procedure a
-`description` (`MCP_TOOL_DESCRIPTION_MISSING` warns). `ctx.cause.kind` is
-`mcp`.
+By default, pair every HTTP Trigger with an MCP Trigger so the same operation is reachable by the user's AI. `mantle generate` warns when a Procedure has HTTP exposure but no MCP exposure, suggesting `surface: admin` for an admin-only Procedure and `public` otherwise. Triggers still decide every Procedure surface: intentional asymmetric exposure is allowed and generation succeeds.
 
-## `lifecycle`
+Lifecycle and schedule sources are rejected at generation with `GENERATE_UNSUPPORTED`, including disabled schedules. Use an app-owned handler or scheduler. For signed webhooks, verify the original raw Request in the app and call a generated Procedure with validated input; do not route it through a JSON boundary before signature verification.
 
-| Field | Values |
-|---|---|
-| `schema` | the Schema watched (`LIFECYCLE_SCHEMA_UNKNOWN`) |
-| `on` | non-empty: `before_create`, `after_create`, `before_update`, `after_update`, `before_delete`, `after_delete`, `before_publish`, `after_publish` |
+## Input rules
 
-The target is a `ref` Procedure (`LIFECYCLE_TARGET_NOT_REF`). `ctx.cause` is
-`{ kind: "lifecycle", trigger, hook, schema, rows, id }`.
+The admin MCP tool below lists `reason` and `closed` without the rules, and its
+description ends "'reason' is required when 'closed' is false."; a call with
+`closed: false` and no `reason` fails with `INPUT_VALIDATION_FAILED` at
+`procedures/set-ticket/input/reason` (the error path is
+`procedures/<name>/input/<field>`). See [surface contracts](surface.md) for the
+supported rules.
 
-- A **before** hook runs before the batch, receives the one row (for an insert,
-  the row about to be written), reads only, and rejects by throwing; nothing is
-  applied. The write then locks the version the hook saw. Before hooks on one
-  operation run in Trigger-name order.
-- An **after** hook runs after the commit, once per statement and Trigger, with
-  every written row in `rows` (each with `id` and `version`). A failure is
-  logged and never undoes the write. `id` is stable for a replay.
-
-A hook sees the originating caller. Any path that writes the Schema fires its
-hooks: SQL Procedures, `ctx.store`, Admin. A set op on a Schema with a before
-hook for that operation is refused.
-
-## `schedule`
-
-| Field | Values |
-|---|---|
-| `cron` | five-field POSIX cron in UTC; weekday 0 = Sunday |
-| `enabled` | optional, default `true` |
-
-The target runs as the system caller with input `{}`. It may not declare
-`requires.auth` predicates (`SCHEDULE_AUTH_INVALID`), and its input must
-accept an empty object (`SCHEDULE_INPUT_INVALID`). `ctx.cause` is
-`{ kind: "schedule", trigger, cron, scheduledTime, id: "<trigger>:<scheduledTime>" }`.
-
-The service passes `schedules: true` to `createMantle`; without it boot
-refuses an enabled schedule (`SCHEDULE_NOT_WIRED`). The Cloudflare preset
-passes it. The Bun preset has no scheduler, so `mantle generate --host bun`
-refuses an enabled schedule; use host `none` with your own scheduler calling
-`invokeSchedule(cron, scheduledTime, env)` on what `createMantle` returns.
-
-### Cloudflare
-
-Cloudflare numbers weekdays 1 (Sunday) to 7. `toCloudflareCron` from
-`@aotter/mantle/cloudflare` adds one to every explicit weekday number and
-leaves `*`, names and the other fields alone:
-
-| POSIX (manifest) | Cloudflare (`wrangler.jsonc`) |
-|---|---|
-| `0 3 * * 0` | `0 3 * * 1` |
-| `0 9 * * 1-5` | `0 9 * * 2-6` |
-| `*/5 * * * *` | `*/5 * * * *` |
+```yaml
+apiVersion: cms.mantle.aotter.net/v2
+kind: Procedure
+metadata: { name: set-ticket }
+spec:
+  description: Open or close a ticket.
+  input:
+    type: object
+    required: [id, closed]
+    properties: { id: { type: string }, closed: { type: boolean }, reason: { type: string, maxLength: 200 } }
+    additionalProperties: false
+    if: { properties: { closed: { const: false } }, required: [closed] }
+    then: { required: [reason] }
+  output: { type: object }
+  handler: { sql: 'UPDATE tickets SET closed=input.closed WHERE id=input.id RETURNING id,closed' }
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Trigger
+metadata: { name: set-ticket-mcp }
+spec:
+  source: { kind: mcp, surface: admin }
+  target: { procedure: set-ticket }
+```
 
-It refuses what it cannot translate faithfully: `?`, `L`, `W`, `#`, weekday
-`7`, numbers with a leading zero, a backwards range, a name with a step, and a
-day of month together with a weekday. `mantle generate` runs it on every
-enabled schedule and fails before writing on a refusal. The generated
-`src/index.ts` maps Cloudflare's cron back to every POSIX expression that
-shares it.
+See [surfaces](surface.md) for mounted paths, error mapping and origin checks.

package/docs/handbook/reference/view.md

@@ -1,162 +1,44 @@
----
-description: View field reference for Mantle 0.2.0 — the SQL SELECT and the dialect it accepts, input, surface, requires, uiSchema, cache, output names, paging and diagnostics.
----
 # View
 
-```yaml
-apiVersion: cms.mantle.aotter.net/v2
-kind: View
-metadata: { name: search-items }
-spec:
-  title: Search items          # optional, a string or a locale map
-  description: …               # optional; the MCP tool's description
-  surface: public              # public | staff | internal (required)
-  requires: { … }              # optional, see Authorization requirements
-  input:                       # optional JSON Schema object
-    type: object
-    required: [q]
-    properties: { q: { type: string, minLength: 1 } }
-  uiSchema: { list: { … } }    # optional, staff Views only
-  cache: { sharedMaxAge: 60 }  # optional
-  sql: |                       # required: one SELECT
-    SELECT i.id, i.name, i.stock FROM items i
-    WHERE mantle.search(i, input.q)
-    ORDER BY mantle.search_rank(i), i.name
+A View requires `surface: public | admin | internal` and one `sql` SELECT. Optional keys include title, description, input, requires, restrict, uiSchema (admin only), and cache. The app imports its generated typed function and supplies a native handle, verified Caller and driver-ready input; a JSON input (an array read by `json_each(input.ids)`) takes its authored array or object, which the generated query serializes.
+
+## SQL
+
+PostgreSQL syntax is parsed and checked at generation. Reads may reference declared Schemas, CTEs and reusable internal Views; no auth/system tables or arbitrary external relations. The compiler adds scope, TTL, publication and translation-parent visibility at every relation. SQL policy is not injected at request time.
+
+The SQL each dialect accepts, for Views and Procedures alike, is listed in [the SQL reference](sql.md); [SQL patterns](../guides/sql-patterns.md) shows the common ones. Unsupported SQL fails with a source position; generation is the authority for each target.
+
+`*` and `t.*` expand to the Schema's declared fields only. Select `id`, `version`, `created_at` and `updated_at` by name when a client needs them (a write's `expectedVersion`, a detail link, keyset paging).
+
+OFFSET, arbitrary functions/relations, DDL and transaction control are not a read escape hatch. Use keyset paging. Select latitude/longitude explicitly instead of native geo projections.
+
+## Restrict
+
+`restrict` narrows one target by Schema: `restrict: { orders: "region IN auth.user('region')" }`. Each key is a Schema the SQL reads; each value uses the [scope](schema.md#field-scope) grammar, and a `= auth.uid()` term only on `author_id` or that Schema's own owner column. The effective rule is the Schema's scope AND the restrict. `{ all: true }` never lifts a restrict term: such a caller is refused with `AUTH_DENIED`. A View or Procedure that reads a restricted View carries that View's restrict too, so composing never widens it. A View with `restrict` cannot use a shared cache.
+
+## Search and totals
+
+`mantle.search(<alias>, <text>)` matches the Schema's declared `searchableFields`, and `mantle.search_rank(<alias>)`
+orders by relevance; qualify both with `mantle.`. An optional search reads
+`WHERE p.active AND (input.q IS NULL OR mantle.search(p, input.q))`, and a ranked one
+`WHERE mantle.search(p, input.q) ORDER BY mantle.search_rank(p), p.id` (see `examples/reference-service` `catalog.yaml`
+for cursor paging over the rank).
+
+Views using `mantle.search`, Store search and Admin list search share the dialect search: SQLite/D1 use FTS for queries of 3 or more characters (shorter queries use LIKE); PostgreSQL uses ILIKE over the declared fields and 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, which ILIKE then uses 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);
 ```
 
-## `sql`
-
-One `SELECT` in PostgreSQL syntax over declared Schemas. It reads
-`input.<name>`, `auth.uid()`, `auth.role()` and `now()`. The runtime adds
-scope, TTL and (on a public View) published-only to every Schema it reads;
-never repeat them.
-
-### What the D1 dialect accepts
-
-The `sqlite` dialect (`@aotter/mantle/d1`) runs this subset on D1, on Bun's
-SQLite and on any `sqliteStorage` driver.
-
-| Area | Supported | Rule |
-|---|---|---|
-| Expressions | columns, aliases, literals, arithmetic, `\|\|`, `CASE`, `COALESCE`, `NULLIF`, `CAST` | `CAST(x AS int)` only for an integer literal: use `round(x)`. `CAST(x AS bool)` follows PostgreSQL. `*` expands to declared fields; a bare `*` over a subquery or `json_each` is refused: name the columns |
-| Conditions | comparisons, `AND`/`OR`/`NOT`, `BETWEEN`, `IS [NOT] NULL`, `IS DISTINCT FROM`, `IN (list \| subquery)`, `[NOT] EXISTS`, `LIKE … ESCAPE` | `LIKE` is case-insensitive (SQLite). An input array in `IN` binds once. A date-time, date or boolean column (and `created_at`, `updated_at`) is not compared with a bare string: write `CAST('…' AS timestamptz)`, `true`, or bind an input |
-| Relations | one Schema, `INNER`/`LEFT JOIN … ON` (self-joins too), a subquery in `FROM`, `json_each(<input or column>)` | the only comma join is `t, json_each(t.col)` |
-| Subqueries | scalar and correlated | |
-| Aggregation | `count`, `sum`, `min`, `max`, `avg`, `count(DISTINCT)`, `json_group_array([DISTINCT])`, `json_group_object`, `GROUP BY`, `HAVING` | a selected column is grouped or aggregated |
-| Windows | `row_number()`, `rank()`, `sum`/`count … OVER (PARTITION BY … ORDER BY …)` | no frame clause |
-| Order and paging | `ORDER BY … [NULLS FIRST \| LAST]`, `LIMIT`, `DISTINCT` | `id` is appended as the last sort key; `LIMIT` needs `ORDER BY` and bounds every page together; a sort key may be NULL (an unstated `NULLS` puts NULL first ascending and last descending, and the cursor follows the same rule); `ORDER BY 1` sorts by the first output; `DISTINCT` with `ORDER BY` is refused. A View without `ORDER BY` (a `DISTINCT`, an aggregate, a `GROUP BY`) is one page: it takes no cursor and is refused when it has more rows than the page |
-| JSON | `->>`, `json_extract`, `json_set`, `json_insert`, `json_remove`, `json_array_length` | `->` is refused |
-| Time | `now()`, `date_trunc('hour'\|'day'\|'week'\|'month'\|'year', ts)`, `extract(year\|month\|day\|dow\|hour FROM ts)`, `ts ± interval '<n> seconds\|minutes\|hours'`, `ts - ts` | site time zone; `ts - ts` is microseconds. Calendar intervals (`day`, `month`) are refused: bind the boundary as an input |
-| Search and places | `mantle.search(t, q)`, `mantle.search_rank(t)`, `mantle.near(t.f, lat, lng, meters)`, `mantle.distance(t.f, lat, lng)` | `near` takes a literal radius of at most 50 km; ordering by `distance` needs `LIMIT` ≤ 100 and has no cursor |
-
-Refused on D1: `WITH`, `LATERAL`, `UNION`/`INTERSECT`/`EXCEPT`, window frames,
-`FILTER`, `DISTINCT ON`, `ILIKE`, regular expressions and jsonb operators. The
-PostgreSQL dialect accepts each of them (next section), and D1 says so in its
-refusal: "needs the PostgreSQL dialect".
-
-Refused on every dialect: `OFFSET`, `RIGHT`/`FULL`/`CROSS JOIN`, `NATURAL`,
-`USING`, `FOR UPDATE`, a write inside `WITH`, positional `$1`, `rowid`,
-SQLite's clock (`'now'`, `CURRENT_TIMESTAMP`), `strftime`/`date`/`unixepoch`,
-`generate_series` and any function outside the allowlist, an unqualified
-`search()`, and any relation that is not a declared Schema, a CTE or an
-internal View (`_mantle_*` and auth tables included).
-
-### What the PostgreSQL dialect adds
-
-PostgreSQL is Mantle SQL's reference dialect (ADR-0037); D1 runs the subset above.
-On PostgreSQL a View may also use:
-
-| Construct | Notes |
-|---|---|
-| `WITH`, `WITH RECURSIVE` | every CTE body is a `SELECT`; a Schema read inside one is scoped like any other |
-| `UNION [ALL]`, `INTERSECT`, `EXCEPT`, `DISTINCT ON` | inside a `WITH` or a subquery, never the View's own `SELECT`, which Core pages and orders |
-| `JOIN LATERAL (…) x ON …`, `, LATERAL (…) x` | |
-| Window frames | `ROWS`/`RANGE BETWEEN … PRECEDING AND …` with literal offsets (an integer, or an interval for `RANGE` over time); `avg`, `min`, `max`, `lag`, `lead`, `first_value`, `last_value`, `dense_rank` over a window. `GROUPS` and `EXCLUDE` are refused |
-| Aggregates | `FILTER (WHERE …)`, `ORDER BY` inside an aggregate, `string_agg`, `jsonb_agg`, `jsonb_object_agg` |
-| jsonb | `->`, `#>`, `#>>`, `@>`, `<@`, `?`, `?\|`, `?&`; `jsonb_build_object`, `jsonb_build_array`, `jsonb_strip_nulls`, `to_jsonb`, `jsonb_typeof`; a json field is stored as `jsonb` |
-| Text and numbers | `ILIKE`, `~`, `~*`, `!~`, `!~*`, `split_part`, `greatest`, `least`, `floor`, `ceil`, `sqrt`, `power` |
-| Time | `ts AT TIME ZONE 'Asia/Taipei'`; `date_trunc` adds `minute` and `quarter`; `extract` adds `minute`, `quarter`, `week`, `isoyear`, `isodow`, `doy`, `epoch` |
-| Casts | any expression to `int4`, `int8`, `numeric(p, s)`, `date`, `timestamptz`, `jsonb`; a text literal compared with a date-time column is cast, as PostgreSQL does |
-
-Every statement on PostgreSQL has a 10-second `statement_timeout`
-(`postgresStorage({ statementTimeoutMs })`).
-
-### Reading another View
-
-A View's `FROM` may name an internal View (`surface: internal`, no `input`, no
-`requires`) by its name with `-` written `_`: `FROM free_window w`. The
-compiler inlines its `SELECT` as a subquery, so scope and every check apply
-inside it, on every dialect. A View that reads itself, directly or through
-others, is refused; a View named like a Schema is not readable this way (the name reads the Schema). Write a rule many
-Views share (a plan's visible window, a definition of "active") once this way.
-
-### Names
-
-- Unquoted identifiers fold to lower case; Schema and field names resolve
-  case-insensitively. A Schema whose name is not a plain identifier is quoted:
-  `FROM "support-tickets"`.
-- Native columns are `id`, `status`, `version`, `created_at`, `updated_at`,
-  `author_id`.
-- An output that reads a Schema field unchanged comes back under the field's
-  declared name and is decoded to its type, and so does `created_at` or
-  `updated_at` (an ISO date-time). A `sum`, `min` or `max` of one column keeps
-  that column's type and hints (a sum of a `money-minor` field is money); a
-  `count` or an `avg` is a plain number. Any other output keeps its alias as
-  SQL folded it: `AS orderCount` is `ordercount`, `AS "orderCount"` keeps the
-  case. A staff View's `uiSchema.list.columns` must name each output as the row
-  carries it; a name that differs only by case is `VIEW_UI_INVALID`, and the
-  message says to quote the alias.
-
-## `input`
-
-A JSON Schema object with declared `properties`; the SQL reads
-`input.<name>`. `limit` and `cursor` are reserved
-(`VIEW_INPUT_RESERVED_NAME`). An input the call leaves out binds `NULL`, after
-the schema's `default` if it declares one.
-
-## `surface`
-
-| Value | Served |
-|---|---|
-| `public` | `GET /api/views/<name>` and a tool on `/mcp` |
-| `staff` | `GET /admin/api/views/<name>`, `GET /admin/api/views/<name>/export` (CSV), and a tool on the staff MCP surface |
-| `internal` | nowhere: `ctx.store.view(name, …)` and `runtime.store` only |
-
-## Paging and the response
-
-Every surface takes `limit` (default 50, maximum 500) and `cursor`, and answers
-`{ "rows": [...], "nextCursor": "…" }`. `nextCursor` appears only when more
-rows exist; pass it back unchanged. A cursor is bound to its View and order.
-REST coerces each `input` query parameter to its declared type.
-
-## `uiSchema` (staff Views)
-
-| Key | Effect |
-|---|---|
-| `list.columns` | the outputs the console shows, in order; CSV export uses them |
-| `list.searchFields` | outputs the console's search box matches: one case-insensitive `LIKE '%text%'` per output, ORed, with `%`, `_` and `\` in the text matched literally |
-| `list.filterFields` | outputs the console offers as filters: one `=` each, the value coerced to the output's field type |
-
-Each name must be one of the View's outputs (`VIEW_UI_INVALID` otherwise).
-The conditions wrap the View's own query, after its `WHERE` and the injected
-policy and before paging, so they narrow what the caller may already see and
-the cursor stays valid. Over HTTP they are Admin's `search` and
-`filter.<output>` query parameters on `/admin/api/views/<name>` and its
-`/export`; in code, `store.view(name, { search, filters })`. A declared
-`input` remains the way to parameterize the query itself. Other keys are
-refused (`VIEW_UI_INVALID`).
-
-## `cache`
-
-`{ sharedMaxAge: 1–86400 }` is accepted only on an unguarded public View whose
-SQL reads neither `auth.*` nor `now()` (`VIEW_CACHE_INVALID`). The 0.2.0 REST
-surface does not send cache headers yet; cache in front of it if you need to.
-
-## Diagnostics
-
-`SQL_SYNTAX`, `SQL_UNSUPPORTED`, `SQL_FUNCTION`, `SQL_RELATION`, `SQL_COLUMN`,
-`SQL_SHAPE`, `SQL_TYPE` (each with a line and column in the SQL),
-`VIEW_INPUT_INVALID_SHAPE`, `VIEW_INPUT_RESERVED_NAME`, `VIEW_CACHE_INVALID`,
-`VIEW_UI_INVALID`, `AUTH_PREDICATE_NOT_IN_ENUM`, `GUARD_PROCEDURE_UNKNOWN`. At
-run time: `UNAUTHENTICATED`, `AUTH_DENIED`, `INPUT_VALIDATION_FAILED`,
-`NOT_FOUND`. See [Diagnostics](./diagnostics.md).
+Store keeps `find`/`first` search and `count`. `count` scans every matching row; for large tables or frequently shown totals, use an internal View with indexed predicates or avoid exact totals. Aggregates still scan matching rows. See [Store reads](../guides/typed-queries.md#store-reads-and-writes).
+
+## Results and paging
+
+Each SELECT output needs a unique static name. Unquoted SQL identifiers fold to lower case; use an explicit quoted alias to preserve case (`r.reqStatus AS "reqStatus"`). Generation warns when an unaliased direct declared field would use its lower-case storage name. Declared-column lineage supplies generated types; computed outputs remain native/unknown, except a top-level output that is a JSON document by construction (a JSON aggregate or builder, a scalar subquery of one, or a `COALESCE` of those; see [SQL patterns](../guides/sql-patterns.md#a-row-with-its-children-in-one-read)), which is typed JSON. An output is non-null (`string`, not `string | null`) only when it reads unchanged a column its table declares NOT NULL (`id`, `version`, `created_at`, `updated_at`, a publishing `status`, or a [required](schema.md#fields-and-storage) field of an operational Schema) directly or through FROM subqueries; the right side of a LEFT JOIN, an aggregate, a column beside an aggregate without GROUP BY, a CTE and an expression stay nullable. SQL formats declared date-time/date outputs, while computed timestamps retain driver values. See [native execution](../guides/native-execution.md).
+
+Bare `views/<encoded-name>.ts` returns row arrays. Proved pageable exposed/internal Views also receive native `paged/views/*`, returning `{ rows, nextCursor? }`. Selected REST/MCP boundaries use separate `paged/wire/views/*` SQL when declared integers require exact transport projections; bare modules also export `WireRow`. Indexed ordering after fixed equality prefixes ([index prefixes](schema.md#index-prefixes-for-paged-views)), non-null typed keys, complete groups and singleton joins/lookups are checked at generation. Unsupported internal paging retains its bare View; exposure requires a supported page contract. Aggregates still scan/group their sources: inspect EXPLAIN.
+
+Publishing Schema fields may be NULL in drafts even when required, so public View paging cannot order by them. `published_at` is accepted by Store ordering but rejected as a View paging key. Use `ORDER BY id`, or keep the business date in an operational Schema as an indexed, required non-null field.
+
+Internal Views have no public route/tool. Public and admin Views use selected REST/MCP/Admin bindings. `uiSchema.list` selects admin search/filter/display metadata; `uiSchema.nav.group/order/hidden` places an admin View in the sidebar ([sidebar](../guides/native-admin.md#sidebar)). See [surfaces](surface.md) for validation, paging and wire conversions and [typed queries](../guides/typed-queries.md) for a complete example.

package/docs/handbook/releases/index.md

@@ -10,15 +10,115 @@ open; installing one means choosing an exact version, not a channel.
 [GitHub Releases](https://github.com/aotter/mantle/releases) is the canonical
 change history; this page is the narrative one.
 
-From 0.2.0, Mantle is two packages, `@aotter/mantle` and `@aotter/mantle-ui`,
-published together at one version: the 0.1.x `-spec`, `-runtime`,
-`-cloudflare`, `-auth`, `-admin`, `-mcp`, `-web` and other packages fold into
-subpaths of `@aotter/mantle`, and `@aotter/mantle-admin-ui` into
-`@aotter/mantle-ui/admin`. Pin every one you use to the
-same exact version and upgrade them together.
+From 0.2.0-alpha.7, Mantle publishes three packages together at one version:
+`@aotter/mantle` (native SDK, compiler and CLI), `@aotter/mantle-ui` (pure UI),
+and `@aotter/mantle-admin` (optional Admin server, SPA and MCP App).
+Pin every package you use to the same exact version and upgrade them together.
 
 ## 0.2.0 — in preparation
 
+### Upgrading to 0.2.0-alpha.11
+
+Pin every selected `@aotter/mantle`, `@aotter/mantle-ui` and
+`@aotter/mantle-admin` dependency to `0.2.0-alpha.11`, refresh the lockfile,
+then regenerate and check the application's owned artifacts. Keep existing
+production migrations application-owned; generated initial DDL is for an empty
+database. This alpha includes breaking Admin authoring and paging changes.
+
+1. **Build output and host configuration.** `mantle bundle` writes server
+   modules to `dist/worker` and static files to `dist/client`, including
+   `dist/client/admin`. Rerun `mantle generate` with the application's `--entry`
+   and check the resulting Wrangler `main`, `base_dir`, asset directory and
+   build command. See [CLI and generated ownership](../start/project-and-cli.md).
+2. **Application-owned React.** Install React and React DOM in the application
+   at the same exact version (the examples use `19.3.0`). Admin takes them as
+   peers; a mismatched pair fails its build.
+3. **Replace extensions with application composition.** Move to
+   `defineAdmin(meta, { nav, pages, home, components, plugins, mcp })` in
+   `src/admin.tsx`. Remove `--admin-extensions`, `adminExtensions`,
+   `defineAdminExtension`, extension handlers and removed manifest widget,
+   `list.cells` and panel references. `navGroups` becomes `nav.groups`.
+   Use the [Admin migration table](../guides/native-admin.md#migrating-from-admin-extensions)
+   rather than carrying the former registration layer forward.
+4. **Build the MCP App with the application.** The prebuilt
+   `@aotter/mantle-admin/mcp-app` / `mantleAppHtml` export is gone. Use
+   `adminMcpApps({ catalogue: mcpAppCatalogues.admin })` with the generated
+   catalogue; it reads the built asset. Declare CSP once in `defineAdmin`.
+   The default resource URI hashes the built HTML, catalogue and metadata;
+   custom HTML functions need an explicit immutable URI. Load interactive
+   host HTML through authenticated `resources/read`, which embeds its
+   catalogue. See [MCP Apps](../guides/mcp-apps.md).
+5. **Run the generated compatibility check.** Run
+   `node --test generated/admin-mcp-app.check.mjs` after building. Install
+   the optional `playwright-core` peer and a browser, or set
+   `MANTLE_TEST_CHROMIUM`; a missing browser fails rather than skips. This
+   checks rendering with a synthetic catalogue, not application authorization
+   or completion of a Procedure action.
+6. **Keep the host graph safe.** The MCP build rejects `/admin/api` access,
+   cookies and undeclared remote loads. Its entry must be readable in Node.
+   An optional `src/admin.mcp.tsx` (or `buildAdmin({ mcpEntry })`) isolates
+   browser-only integrations; both roots can reuse one host-safe config,
+   components and CSS. Without it the whole shared entry graph is checked.
+7. **Distinguish total bounds from page sizes.** Authored SQL `LIMIT` now
+   bounds the complete ordered result set across cursor pages, including web
+   indexes. Use paging `options.limit` for page size; remove an authored limit
+   only if it was incorrectly being used as a page-size setting. MCP accepts
+   sizes of 1–500, but a response budget can return fewer rows: append pages
+   until `nextCursor` is absent, not until a short page. See
+   [View paging](../reference/surface.md).
+8. **Install build dependencies where the build runs.** Wrangler dev/deploy
+   runs its configured build command, so that environment needs
+   `node_modules`. The resulting built server/assets do not read
+   `node_modules` when served. See the
+   [application shell](../../examples/app-shell/README.md).
+
+Record/collection cells, inputs, record actions, asides and `RecordView` are
+now truthfully browser-only (`surface: "browser"`); remove unreachable MCP
+branches. View cells remain `both`, and pages opt in through `pages[].mcp`.
+A Procedure action's input is distinct from a collection record input: use a
+Procedure target and MCP Trigger with the View's unchanged `id` and observed
+`version` for native row actions. [Shared custom-page headers](../guides/mcp-apps.md#customising-admin-for-mcp-hosts)
+can compose localized title, description and actions on both surfaces; omit the
+option to keep prior behavior, or use `header: false` for an element-owned heading.
+
+OAuth issuer verification now follows Better Auth's normalized URL while
+preserving explicit issuer/JWKS settings. Cloudflare OAuth configurations need
+`global_fetch_strictly_public` for public JWKS fetches; generated settings and
+the official examples retain it. Native MCP Apps use the official ext-apps
+client. Browser Admin now displays a localized explicit reload action when a
+lazy page fails, rather than going blank; it does not reload automatically or
+replay writes.
+
+### Native SDK migration (alpha.7)
+
+Alpha.7 replaces the previous Core runtime and generated service contract.
+Existing alpha.6 applications require a source migration:
+
+- Replace `createMantle`, `Store.select` and the old host presets with
+  [native generated queries and Store](../guides/typed-queries.md).
+  Generate with an explicit target and output directory, for example
+  `mantle generate cloudflare-d1 generated manifests/*.yaml --auth src/auth.ts --admin`.
+  See [CLI and generated ownership](../start/project-and-cli.md).
+- The application owns routing, native database handles, verified Caller,
+  Auth configuration and migrations. Runtime no longer converges storage or
+  runs DDL at boot. Apply generated `schema.sql` only to an empty database;
+  migrate existing data explicitly. PostgreSQL uses Bun.SQL on Bun and
+  postgres.js on Workers. See [native execution](../guides/native-execution.md).
+- Install the separate `@aotter/mantle-admin` package when selecting Admin, with `react` and `react-dom` in the application pinned to one identical exact version (Admin no longer installs them).
+  Compose its [native bindings](../guides/native-admin.md) in the application.
+  Bare queries retain driver-native values; selected REST/MCP/Admin boundaries
+  own validation and declared-column wire conversion.
+- Move lifecycle/schedule handlers and dynamic authorization guards into
+  application code. Review [authorization and Caller wiring](../concepts/runtime-and-adapters.md)
+  and regenerate all owned artifacts before running `generate --check`.
+
+The [reference Worker](https://github.com/aotter/mantle/tree/v0.2.0-alpha.11/docs/examples/reference-service) and
+[app shell](../../examples/app-shell/) demonstrate the current composition.
+The following earlier-alpha notes are historical; the current handbook and
+the native migration above supersede their runtime and CLI instructions.
+
+### Earlier alpha design
+
 0.2.0 replaces 0.1.x's grammar and composition; no stable 0.1.5 was released
 (`0.1.5-alpha.1` was a prerelease). It breaks every consumer, and
 `docs/upgrade-0.1-to-0.2.md` in the package is the guide for moving a project
@@ -28,9 +128,10 @@ by hand.
   Procedures are SQL statements or a `ref`, in PostgreSQL syntax. The builtin
   handlers, the Filter AST, `params`, `$ctx` references and `x-mantle-bind` are
   gone; Schemas gain `checks`, and `searchableFields` becomes full-text search.
-- **SQL in PostgreSQL syntax.** PostgreSQL is the reference dialect
+- **SQL in the dialect's syntax.** PostgreSQL is the reference dialect
   (`@aotter/mantle/postgres`); D1 and SQLite run a subset
-  (`@aotter/mantle/d1`). A plan records its dialect.
+  (`@aotter/mantle/d1`). Each dialect is its own target (ADR-0039), and a
+  plan records its dialect.
 - **One Store.** Every read and write goes through Store, which adds caller
   scope, TTL and published-only to every statement, and an optimistic lock
   where the caller passes one; a write
@@ -38,8 +139,8 @@ by hand.
 - **The service is the application's.** `createMantle(service, …)` replaces
   `createMantleWorker`, and the first `mantle generate` writes the host's
   preset (`src/service.ts`, `src/index.ts`, ...) once. `--host` is
-  `cloudflare` (D1, or PostgreSQL through Hyperdrive), `bun` (Bun.SQL or
-  bun:sqlite, `@aotter/mantle/bun`) or `none` (plan and types only), and
+  `cloudflare` (D1, or PostgreSQL through Hyperdrive), `bun` (node-postgres
+  or bun:sqlite, `@aotter/mantle/bun`) or `none` (plan and types only), and
   `--dialect` is `sqlite` or `postgres`; both are chosen once.
 - **Mantle never owns your users.** A `CallerResolver` turns a request into a
   `Caller`; identity is `mantle` (Better Auth), `custom` or `none`. Core creates
@@ -56,8 +157,93 @@ by hand.
   `emit-openapi`, `skills` and `mantle-harness` are removed.
 - **The Admin console** moves to `@aotter/mantle-ui/admin`, served at `/admin`
   by the preset through the service's `ASSETS` binding.
-- **Not yet in 0.2.0:** Mantle-rendered public pages, the MCP interaction App
-  tools, and deploying to Mantle Cloud.
+- **Not yet in 0.2.0:** Mantle-rendered public pages and the MCP interaction
+  App tools.
+
+### Native driver and before-hook cleanup (#1426)
+
+This breaking source migration removes request-scoped PostgreSQL sessions,
+custom write pipelining/retries, SQLite lock polling and before-hook runtime
+policing. Copy the new native preset wiring; existing generated source is not
+overwritten. Authenticated Bun SQLite uses separate Store/Auth handles to the
+same WAL file. Operational before hooks no longer add an implicit version
+lock; explicit OCC, publishing checks and authorization guards remain.
+See [native execution migration](../guides/native-execution.md) and ADR-0041.
+The alpha.6 instructions below describe that release; ADR-0041 supersedes its
+requestScoped/pipeline/shared-SQLite-handle directions after this cleanup.
+
+### Upgrading an existing PostgreSQL service (0.2.0-alpha.6)
+
+PostgreSQL is native from this alpha (ADR-0039): each dialect is its own target,
+PostgreSQL's SQL and ordering are PostgreSQL's, and node-postgres (`pg`) is the
+PostgreSQL driver on every host. D1 and SQLite output is unchanged except where
+noted. Work through these in order before deploying.
+
+1. **Role settings (from #1383, now also checked on Bun).** Boot refuses with
+   `STORAGE_CHANGE_BLOCKED` (path `storage:settings`) unless the role Mantle
+   connects as has a statement limit and UTC:
+   `ALTER ROLE app SET statement_timeout = '10s'; ALTER ROLE app SET TimeZone = 'UTC';`
+   (10s or less). Bun's `Bun.SQL` entry used to pin its own limit and skip this
+   check. A Hyperdrive config must keep `--caching-disabled`: reads, role
+   re-reads and grant revocations run outside a transaction.
+2. **Rewrite SQLite spellings, then run `mantle generate`.** A PostgreSQL
+   manifest that uses `json_each`, `-> '$.a'`, `->> '$.a'`, `json_extract`,
+   `json_set`, `json_insert`, `json_remove` or `hex` fails validation with its
+   position and the PostgreSQL spelling. The
+   [dialect contract](../concepts/runtime-and-adapters.md#drivers-and-dialects)
+   covers the PostgreSQL target: `json_each(t.col) j` becomes
+   `jsonb_array_elements_text(t.col) WITH ORDINALITY AS j(value, n)` (a sorted
+   View over a row source needs the alias and `WITH ORDINALITY`, and `j.id`
+   becomes `j.n`), `CAST(n AS bool)` of an integer becomes `n <> 0`, and `||`
+   needs a text operand. The PostgreSQL dialect version is now 2, so a plan
+   compiled earlier fails at boot with `PLAN_FINGERPRINT_MISMATCH`: run
+   `mantle generate` and deploy the regenerated plan.
+3. **NULL order.** Unstated `NULLS` now follows PostgreSQL: NULL last ascending,
+   first descending, for every `ORDER BY` including windows and
+   `json_group_array`. Write `NULLS FIRST` or `NULLS LAST` to keep a specific
+   order. Rows tied on the last sort key are ordered by `id` in that key's
+   direction. A cursor live across the deploy may repeat or skip rows once.
+4. **Bun entry.** Install `pg` and `@types/pg`. Replace
+   `new SQL(url, { prepare: false, ... })` with
+   `new pg.Pool({ connectionString, pipeline: true })`; `Env.SQL` becomes
+   `Env.PG`. The simplest path is to delete `src/service.ts` and `src/index.ts`
+   and re-run `mantle generate --host bun`, or copy the new preset. Removed from
+   `@aotter/mantle/bun`: `bunPostgresStorage`, `bunPgConnect`,
+   `bunDatabaseDriver`, `bunAuthDatabase`, `BunSqlPool`, `BunAuthPool`. The role
+   no longer needs `TEMPORARY`. Custom transports lose `temporaryResultMetadata`,
+   `describeResult` and `readOnly` from `PgClient` / `PgStatement`.
+5. **Generated `src/service.ts` changed.** The `database(env).run` wrapper moved
+   to the exported `mantle`, and the Bun pooled wrapper ends each client once.
+   The preset is never rewritten: re-run `mantle generate` into a scratch
+   directory and copy the difference, or delete and regenerate if unedited.
+6. **First boot does one-time work.** It runs once under the advisory lock:
+   - one `_mantle_ix_<schema>_updated` index on `([scope,] updated_at, id)` per
+     Schema, built without `CONCURRENTLY` inside the convergence transaction, so
+     writes to a large table block while it builds. Pre-create it before
+     deploying, on the schema (`search_path`) Mantle uses, with both names quoted:
+     `CREATE INDEX CONCURRENTLY "_mantle_ix_<schema>_updated" ON "<schema>" (["<scope>",] updated_at, id)`.
+     A matching index is accepted. If a concurrent build fails, drop the invalid
+     index before deploying: boot accepts it by name and columns and never
+     rebuilds it. A Schema name longer than about 43 bytes gets a hashed index
+     name; read it from a fresh database's `pg_indexes` instead;
+   - each `_mantle_chk_*` check is rebuilt once (earlier releases left no
+     marker); later boots leave unchanged checks alone;
+   - the old `_mantle_jget`, `_mantle_bool` and `_mantle_json_each` functions
+     stay in place, unused: a previous release still running during a rolling
+     deploy calls them.
+7. **Boot under contention.** Concurrent boots converge once. A boot that cannot
+   get a lock within about five tries of one second fails with
+   `STORAGE_CHANGE_BLOCKED` naming the lock (another boot still converging, or a
+   long transaction on a table the plan changes), and is not retried for 10
+   seconds. A winner building a very large index can outlast its waiters, which
+   then report the blocked boot; boot again when it has finished (#1408).
+8. **Auth.** `get-session` no longer carries a `set-auth-jwt` response header
+   when the OAuth provider is configured; call the plugin's `/api/auth/token`
+   instead. `d1Driver`'s structural `D1PreparedStatement` now requires `first`
+   and `all`: a hand-rolled fake must add them.
+9. **D1.** A paged View with `json_each` in a `JOIN` arm, or with more than one
+   `json_each`, now pages by every element's `id`: its order among ties changes,
+   no row is skipped, and a cursor issued before the upgrade may need to restart.
 
 ## 0.1.4 — 2026-09-24