@aotter/mantle 0.2.0-alpha.5 → 0.2.0-alpha.7

package/docs/handbook/reference/view.md

@@ -1,162 +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. `*` 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. 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, 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,43 @@ 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
 
+### 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.
+  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.7/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 +56,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 +67,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,14 +85,94 @@ 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,
+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
 
 0.1.4 repairs the published consumer path without changing the Manifest

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, SPA, extensions, 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.