@aotter/mantle 0.2.0-alpha.6 → 0.2.0-alpha.8

package/docs/handbook/reference/trigger.md

@@ -1,104 +1,68 @@
----
-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 }
 ```
 
-`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`
-
-| Field | Values |
-|---|---|
-| `surface` | `public` (`/mcp`) or `staff` (the staff MCP surface; also an Admin operation) |
-
-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`.
+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.
 
-## `lifecycle`
+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.
 
-| 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` |
+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.
 
-The target is a `ref` Procedure (`LIFECYCLE_TARGET_NOT_REF`). `ctx.cause` is
-`{ kind: "lifecycle", trigger, hook, schema, rows, id }`.
+## Input 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.
+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 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,164 +1,36 @@
----
-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.
+
+## 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.
+
+SQLite supports the compiler's subset: scalar expressions, comparisons, AND/OR/NOT, CASE, COALESCE, supported casts, INNER/LEFT JOIN, subqueries, grouping/aggregates, supported windows, ordered LIMIT, date operations and declared Mantle search/geo functions. PostgreSQL additionally supports recursive CTEs, lateral relations, more window/aggregate forms, ILIKE and jsonb operators where the allowlist permits them. Unsupported SQL fails with a source position; generation is the authority for each target.
+
+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
+
+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's text rules; an integer has no cast to boolean on PostgreSQL: write `x <> 0`. `*` 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>)` on D1; on PostgreSQL `jsonb_array_elements_text(<input or column>) WITH ORDINALITY AS j(value, n)` | the only comma join is `t, json_each(t.col)` on D1 (PostgreSQL: `t, jsonb_array_elements_text(t.col) WITH ORDINALITY AS j(value, n)`, [SQLite to PostgreSQL rewrites](../concepts/runtime-and-adapters.md#the-postgresql-dialect)) |
-| 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 (on PostgreSQL in the last key's direction); `LIMIT` needs `ORDER BY` and bounds every page together; a sort key may be NULL (an unstated `NULLS` follows the dialect: D1 puts NULL first ascending and last descending, PostgreSQL last ascending and first 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 `statement_timeout` of at most 10 seconds
-(`postgresStorage({ statementTimeoutMs })`); a View runs under the role's own,
-which boot requires to be set and no larger.
-
-### 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 |
-| `list.cells` | output -> `<extension>/<contribution>`: an Admin extension's `field.cell/v1` renderer for that column ([Extend Admin](../guides/admin-extensions.md)) |
-
-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. 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.8
+
+Pin every selected `@aotter/mantle`, `@aotter/mantle-ui` and
+`@aotter/mantle-admin` dependency to `0.2.0-alpha.8`, 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.8/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
@@ -57,14 +157,21 @@ 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.
-- **Mantle Cloud** uses its pinned Core contract and host protocol 4 through
-  the plugin's `mantle` Cloud workflow, requiring a verified source receipt
-  before save, with separate preview and publish
-  states. Its host contract decides the accepted version; offline readiness
-  is not a deployed service.
 - **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,
@@ -83,8 +190,8 @@ noted. Work through these in order before deploying.
    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
-   [rewrite table](../concepts/runtime-and-adapters.md#the-postgresql-dialect)
-   lists them: `json_each(t.col) j` becomes
+   [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 `||`

package/docs/handbook/start/overview.md

@@ -1,63 +1,16 @@
 ---
-description: What Mantle 0.2.0 is, how a service is put together, and where to read next.
+description: The native 0.2.0 handbook and its three package boundaries.
 ---
 # Mantle handbook
 
-Mantle is a manifest-driven service core. A service declares four atoms in
-YAML: a **Schema** stores rows, a **View** reads them, a **Procedure** writes
-them, and a **Trigger** binds a Procedure to HTTP, MCP, a lifecycle event or a
-schedule. Views and Procedures are SQL in PostgreSQL syntax.
+Mantle compiles a closed v2 manifest into native SQL and typed TypeScript. The app owns its database handle, verified Caller, routes, auth, migrations and deployment.
 
-`mantle generate` compiles the manifests into a sealed plan and a typed module.
-The runtime serves the plan through one **Store**, which adds each caller's
-scope, TTL visibility and publishing state to every statement, and an
-optimistic lock where the caller passes one. Your service owns its entry, its users and its frontend; Mantle
-adds tables, surfaces and typed access to them.
+| Package | Responsibility |
+| --- | --- |
+| `@aotter/mantle` | SDK, private compiler, generator and `mantle` CLI |
+| `@aotter/mantle-ui` | Pure UI kit and generic interaction controller; no SDK dependency |
+| `@aotter/mantle-admin` | Admin server, app-built SPA library, preview and MCP App; SDK peer |
 
-This handbook ships inside `@aotter/mantle` at
-`node_modules/@aotter/mantle/docs/handbook/`. The installed copy matches the
-installed package; prefer it over any online copy.
+Start with [a Worker](quickstart-worker.md) or [CLI and targets](project-and-cli.md). Existing TypeScript/Node apps can import selected generated operations using their own handle and verified Caller; no router or identity replacement is required. See the packaged [integrate skill](../../skills/integrate/SKILL.md).
 
-## How a service fits together
-
-```
-manifests/*.yaml ──mantle generate──▶ .mantle/generated/plan.json + mantle.ts
-                                          │
-src/service.ts   createMantle(service, { plan, storage, schedules })
-  ├─ handlers    the `ref` Procedures, typed by mantle.ts
-  └─ fetch       your routes, then Mantle's surfaces behind withCaller(resolver, …):
-                 auth routes · Admin at /admin · MCP at /mcp · REST at /api
-src/index.ts     the host entry: Cloudflare's fetch and scheduled, or Bun.serve
-```
-
-The first `mantle generate` writes `src/service.ts`, `src/index.ts`,
-`src/handlers.ts`, `tsconfig.json` and, on Cloudflare, `wrangler.jsonc` once.
-After that they are your files.
-
-## Read next
-
-| You want to | Read |
-|---|---|
-| Start a service | [Quickstart](./quickstart-worker.md), then [Project layout and CLI](./project-and-cli.md) |
-| Learn the model | [The four atoms](../concepts/four-atoms.md), [Reads](../concepts/views.md), [Writes](../concepts/procedures-and-triggers.md), [Authorization](../concepts/authorization.md) |
-| Look up a field | [Feature table](../reference/features.md), then the [Schema](../reference/schema.md), [View](../reference/view.md), [Procedure](../reference/procedure.md) and [Trigger](../reference/trigger.md) references |
-| Wire sign-in, media or deploy | [Authentication](../cloudflare/authentication.md), [Media uploads with R2](../cloudflare/media-r2.md), [Deploy and operate](../cloudflare/deploy-and-operate.md) |
-| Run on ChatGPT Sites | [Mantle on ChatGPT Sites](../cloudflare/chatgpt-sites.md) |
-| Save, preview and publish on Mantle Cloud | [Mantle Cloud](../cloudflare/deploy-and-operate.md#mantle-cloud), then the plugin's `mantle` Cloud workflow |
-| See whole services | [Examples](../examples/hub.md) and the runnable reference service |
-| Move a 0.1.x project | `docs/upgrade-0.1-to-0.2.md` in the installed package |
-
-The decisions behind 0.2.0 are ADR-0032 to ADR-0038 in `docs/adr/`. The ADRs
-record decisions and may describe work not built yet; the installed code is the
-authority. When an ADR and this handbook disagree, follow this handbook and
-check the code.
-
-## What 0.2.0 does not have yet
-
-- **Mantle-rendered public pages.** `createWebSurface` is not ported. Render
-  pages from your own `fetch` or frontend over the REST surface.
-- **A preset for any host but Cloudflare and Bun.** With `--host none`,
-  `mantle generate` writes the plan and its types only, and your code calls
-  `createMantle`. The Bun preset has no scheduler.
-- **Site settings and media on PostgreSQL.** Only the `sqlite` dialect's
-  storage takes `SiteDefaults`; see [Site defaults](../reference/site-config.md).
+Choose [Store or internal Views](../guides/typed-queries.md), review [database and migration ownership](../concepts/runtime-and-adapters.md), and mount only selected [surfaces](../reference/surface.md). Optional [Admin](../guides/native-admin.md) lives in its own package. Installed SDK docs are the authority for that exact version. [Release notes](../releases/index.md) describe historical releases.