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

package/docs/handbook/concepts/runtime-and-adapters.md

@@ -1,239 +1,30 @@
 ---
-description: How createMantle boots the runtime from a storage adapter, how storage converges to the plan, the D1 and PostgreSQL dialects, and the fingerprint handshake.
+description: Native execution, database handles, two SQL dialects and application-owned migrations.
 ---
-# Runtime, Store and dialects
+# Runtime and databases
 
-```
-src/index.ts (host entry) ─▶ mantle = createMantle(service, { plan, storage, schedules })
-                                 │ first request: createMantleRuntime → storage.prepare(plan)
-                                 ▼
-service.fetch(request, env, { runtime, waitUntil })
-  └ surfaces / your routes ─▶ runtime.invokeProcedure · runtime.store
-                                 └ Store: policy rewrite → dialect check → StoreExecutor
-```
+`mantle generate` compiles manifest SQL and row policy into ordinary TypeScript and SQL. Generated Views and Procedures call the target's native driver. The app owns routing, authentication, handles, connection lifetime and deployment. Import only the operations and surfaces you use.
 
-## `createMantle`
+## Schema installation and migrations
 
-```ts
-createMantle(service, { plan, storage: (env) => MantleStorageAdapter, schedules?, expectedFingerprint? })
-// → { fetch(request, env, ctx?), invokeSchedule(cron, scheduledTime, env, ctx?), runDeferredHook(message, env, ctx?) }
-// runDeferredHook replays an after-hook Invocation from your own queue; nothing in Mantle emits one
-```
+The runtime never creates, alters or checks tables. Boot and requests run no DDL, introspection or schema checks.
 
-- `service` is `{ handlers, fetch(request, env, { runtime, waitUntil }) }`, a
-  WinterTC fetch the application owns. Mantle owns no route of its own: the
-  service decides what is mounted where.
-- The runtime boots lazily on the first call, once per isolate. A failed boot
-  is retried by the next request.
-- Each entry call binds its own `ctx.waitUntil` to the runtime facade handed
-  to the service. Handler calls, nested invocations and Store lifecycle hooks
-  retain work on that entry's context, including concurrent requests. Calls
-  without a context do not borrow another request's retainer.
-- `invokeSchedule` runs every enabled schedule Trigger whose cron is exactly
-  the given POSIX expression, as the system caller.
-- The host entry is a few lines the generator writes once
-  ([The service and its entry](../cloudflare/service-entry.md)); Core handles
-  no platform event types.
+For the first install, apply generated `schema.sql`, including selected auth/site DDL, to an empty database. Apply selected seed SQL explicitly.
 
-`createMantleRuntime(args)` is the same boot without the service, for tests
-and custom hosts. The runtime exposes `plan`, `store`, `invokeProcedure`,
-`bootReport()` (`{ fingerprint, coreVersion }`) and, with site defaults,
-`site`.
+For every later schema change, the application's coding agent diffs the regenerated `schema.sql`, writes a migration with the host's native tool (`wrangler d1 migrations` or the app's PostgreSQL migration tool), rehearses it on a copy, and applies it before deploying the new code. Cloud executes migrations at deploy time.
 
-## Boot checks
+Destructive changes and type changes need explicit data migration. Mantle drops nothing. Initial `schema.sql` is not an upgrade script.
 
-Boot refuses to serve when:
+## Drivers and dialects
 
-- a plan `ref` has no handler (`HANDLER_NOT_REGISTERED`), or a handler is not
-  in the plan (`HANDLER_NOT_DECLARED`);
-- the plan was compiled for another dialect, or does not match
-  `expectedFingerprint` (`PLAN_FINGERPRINT_MISMATCH`);
-- an enabled schedule exists without `schedules: true` (`SCHEDULE_NOT_WIRED`);
-- storage has a change it cannot make (`STORAGE_CHANGE_BLOCKED`), or a table
-  Mantle would create already exists without being Mantle's
-  (`STORAGE_TABLE_NOT_OWNED`).
+The driver layer is open: handles are structural contracts, not a registration API. PostgreSQL needs `unsafe(text, values)` and `begin(options, fn)` from `@aotter/mantle/contracts`; SQLite uses D1's prepare/bind/all/batch shape or bun:sqlite's query/transaction shape. Bun.SQL and postgres.js fit directly. See [adapting a driver](../guides/postgres-adapters.md).
 
-## Storage converges to the plan
+Users may supply anything that executes the emitted SQL, including WASM SQLite persisted to IndexedDB, at their own risk. Mantle promises behavior only on supported drivers: bun:sqlite, D1, Bun.SQL and postgres.js. A structural match alone does not prove transaction, result or error semantics.
 
-There are no migration files for Schema tables. When the plan's fingerprint
-differs from the one the database last booted, boot reads the database's
-actual tables and indexes, compares them with the plan, and:
+The dialect layer is closed in 0.2.0: exactly `postgres` and `sqlite`, selected by the generation target. SQL is rendered at generation time. A third engine requires forking the compiler and Store runtime; it is not a dialect plugin.
 
-| Difference | Boot |
-|---|---|
-| a missing table, field column, index, or unique index that builds | creates it (on SQLite, `STRICT` tables with their check and FTS triggers) |
-| a unique index that fails on existing rows, a column with another type, a changed index, a missing native column | refuses with `STORAGE_CHANGE_BLOCKED`, naming the change and a SQL hint |
-| a column or non-unique index the plan no longer declares | keeps it and warns; nothing is ever dropped |
+## Store and queries
 
-A renamed field is a new empty column beside the old one: copy the data
-yourself. A blocked change is the author's to make (SQL through the host's own
-tool, a data-copy Procedure, a dedupe), then boot checks again. With the same
-fingerprint boot reads nothing. `mantle generate --check --database <file>`
-prints the same diff against a local database without applying it.
+Use the [Store for writes and simple lookups, internal Views for richer reads](../guides/typed-queries.md). Store metadata initializes once on first `store()` use without SQL. Each call binds a fresh handle, verified Caller and handlers; never reuse a caller-bound Store across requests.
 
-Mantle's own tables (`_mantle_*`) and its product tables (`site_config`,
-`media_assets`, `pending_media_uploads`) keep versioned migrations of their
-own. Identity `mantle` migrates Better Auth's tables through Better Auth.
-
-## The D1 dialect
-
-The SQL language is PostgreSQL syntax, pinned to PostgreSQL 18's parser. A
-**dialect** decides which of it an engine runs and how. The built-in dialect,
-`@aotter/mantle/d1`, runs on SQLite as D1 does: its compile side refuses what
-D1 cannot compute exactly, and its runtime side prints SQLite, encodes types
-and converges storage.
-
-- `date-time` (and `created_at` / `updated_at`) is stored as microseconds,
-  `date` as days, `numeric(p, s)` as an integer of the smallest unit, so
-  arithmetic is exact on D1. On the wire a date-time is an ISO string.
-- `checks` are enforced by triggers. `x-mantle-ref` is checked by
-  `mantle generate` and used by Admin; storage does not enforce it in 0.2.0.
-  `searchableFields` uses
-  an FTS5 trigram index; `format: geo` uses an R*Tree.
-- `date_trunc` and `extract` compute in the site time zone
-  (`d1Storage(db, { timeZone })`, default UTC).
-
-`mantle.config.json` names the dialect (`sqlite`, `postgres`, or another dialect package, which must pass
-`runStorageConformance` from `@aotter/mantle/testing`). A plan records its
-dialect, and boot refuses a plan compiled for another one.
-
-## The PostgreSQL dialect
-
-`"dialect": "postgres"` in `mantle.config.json` compiles the plan for
-PostgreSQL (13 or later). On Cloudflare, `mantle generate --dialect postgres`
-writes the preset over Hyperdrive; on any other platform, add `"host": "none"`
-and compose `createMantle` with `postgresStorage` yourself (ADR-0036). PostgreSQL
-is Mantle SQL's reference dialect (ADR-0037), and its SQL is PostgreSQL's own
-(ADR-0039): Mantle lowers nothing to imitate SQLite. It accepts D1's subset except
-SQLite's own vocabulary (below), plus `WITH`, set operations, `LATERAL`, window
-frames, `FILTER`, jsonb operators and the rest of the
-[View reference](../reference/view.md)'s PostgreSQL table. A manifest targets one
-dialect: it need not compile for D1 or return the same values there. D1 to
-PostgreSQL is a migration (export, rewrite the SQL, import), not a switch.
-
-A SQLite spelling fails validation with its position and the PostgreSQL one:
-
-| SQLite (D1) | PostgreSQL |
-|---|---|
-| `FROM t, json_each(t.col) j`, `j.value` | `FROM t, jsonb_array_elements_text(t.col) WITH ORDINALITY AS j(value, n)` (`jsonb_array_elements` for jsonb values, `jsonb_each_text(t.col) WITH ORDINALITY AS j(key, value, n)` for an object) |
-| `ORDER BY …, j.id` of `json_each` | `WITH ORDINALITY AS j(value, n)`, then `ORDER BY …, j.n` (a sorted View over a row source needs `WITH ORDINALITY`; Mantle pages by it) |
-| `x ->> '$.a.b'`, `x ->> '$[0]'` | `x #>> '{a,b}'`, `x ->> 'a'`, `x ->> 0` (a `$…` string is refused: PostgreSQL would read it as a key) |
-| `json_extract(x, '$.a')` | `x ->> 'a'` (text) or `x -> 'a'` (jsonb) |
-| `json_remove(x, '$.a')` | `x - 'a'` |
-| `json_set`, `json_insert` | build the value with `jsonb_build_object` or `jsonb_build_array` |
-| `CAST(n AS bool)` of an integer | `n <> 0` (PostgreSQL has no bigint to boolean cast; `CAST('true' AS bool)` is unchanged) |
-| `2 * 3 \|\| 4` (text by any type) | `2 * 3 \|\| '4'`, or `CAST(n AS text) \|\| …`: `\|\|` needs a text operand |
-| `hex(x)`, `typeof(x)` | no equivalent on the allowlist; refused |
-| `NULL` first when ascending | `NULL` last when ascending (PostgreSQL's; say `NULLS FIRST` to override) |
-
-- Columns have native types: `timestamptz`, `date`, `numeric(p, s)`, `boolean`,
-  `jsonb`, `bigint` and `double precision`. Values are decoded by the type
-  PostgreSQL reports, so computed outputs (`now()`, `date_trunc`, a `CAST`) come
-  back as wire values too: ISO date-times, booleans, parsed JSON.
-- Every write batch is one `SERIALIZABLE` transaction, retried on a
-  serialization failure, so a guard such as `WHERE NOT EXISTS` holds under
-  concurrent writers as it does on SQLite's single writer.
-- `checks` are `CHECK` constraints added `NOT VALID`: they bind every later
-  write and leave older rows alone, like D1's triggers.
-- `->>`, `||`, `CAST` and the jsonb row sources mean what PostgreSQL says; the
-  only SQL function Mantle creates is `_mantle_expect`. A database booted by an
-  earlier release keeps its `_mantle_jget`, `_mantle_bool` and `_mantle_json_each`
-  unused. `json_group_array` and `json_group_object` order by value.
-- Text columns use `COLLATE "C"`, so they compare by code point. An `ORDER BY` key without `NULLS FIRST/LAST`
-  sorts NULL as PostgreSQL does: last ascending, first descending (D1 puts it
-  first ascending). The `id` tiebreak follows the last key's direction, so an
-  index on the sort keys (and the `updated_at` index Mantle creates) serves a
-  paged sort. This is PostgreSQL's default for every `ORDER BY`, window and
-  aggregate (`json_group_array`) ones included. Values never depend on
-  the server's `DateStyle`, `IntervalStyle` or `TimeZone`. Elsewhere the meaning
-  is PostgreSQL's, where D1 differs:
-  - `LIKE` is case-sensitive.
-  - Division by zero is an error.
-  - `->>` returns text.
-- `searchableFields` and `mantle.near()` scan without an index in 0.2.0, and
-  `mantle.search_rank()` counts occurrences rather than computing bm25.
-  Site settings and media are SQLite-only (D1, bun:sqlite).
-- `date_trunc` and `extract` compute in the site time zone
-  (`postgresStorage({ connect, timeZone })`, default UTC).
-- Every statement has a `statement_timeout` of at most 10 seconds
-  (`statementTimeoutMs`; 0 is none). A write batch sets it on its transaction.
-  A read is one statement outside a transaction, under the role's own
-  `statement_timeout`, so boot requires the role to have one no larger
-  (`ALTER ROLE app SET statement_timeout = '10s'`). Storage convergence has
-  none. A statement past it fails with `RESOURCE_UNAVAILABLE` and writes nothing.
-- Boot reads the role's settings once and refuses to start, naming the
-  `ALTER ROLE … SET` to run, unless `DateStyle` is ISO, `IntervalStyle` is
-  `postgres`, `extra_float_digits` is at least 1, `standard_conforming_strings`
-  is on and `TimeZone` is UTC (date and instant casts in your SQL use the
-  session's zone). These are PostgreSQL's defaults, except a server initialized
-  in another time zone. Mantle sets nothing per session, because
-  Hyperdrive resets every pooled session to the role's configuration.
-- Connect as a role that owns the service's tables but is not a superuser and
-  holds no file or server privilege (`pg_read_server_files`,
-  `pg_execute_server_program`). Mantle's allowlist refuses such functions; the
-  role is the second line.
-
-## Storage adapters
-
-| Adapter | From | Driver |
-|---|---|---|
-| `d1Storage(env.DB, { timeZone?, site? })` | `@aotter/mantle/cloudflare` | Cloudflare D1, the one the preset uses |
-| `sqliteStorage(driver, { timeZone?, maxBindings?, site?, restrict? })` | `@aotter/mantle/d1` | any `DatabaseDriver`: `{ batch(statements) }`, all or nothing |
-| `postgresStorage({ connect, timeZone?, statementTimeoutMs?, restrict? })` | `@aotter/mantle/postgres` | `connect` opens one node-postgres (`pg`) client: Hyperdrive on Workers, a `pg.Pool` on Bun (ADR-0039) |
-| `bunSqliteStorage(db, { timeZone?, site?, restrict? })` | `@aotter/mantle/bun` | a bun:sqlite `Database`; foreign keys are turned on |
-
-`restrict(plan, context)` returns refusals of its own, run after the dialect's
-on every program at runtime. It only narrows what runs, for an operator that
-runs other people's plans; a self-hosted service leaves it out (ADR-0037).
-
-On Workers, PostgreSQL goes through Hyperdrive, which pools the connections.
-`connect` opens one client, and `requestScoped` makes it one per request: every
-query of a request (Store, Better Auth, auth SQL) reuses it, and it is ended
-when the request ends, as a Worker's socket must be. Outside `run` (boot,
-schedules) each operation opens its own:
-
-```ts
-import pg from "pg";
-import { pgDatabaseDriver, pgPool, postgresStorage, requestScoped, type PgSession } from "@aotter/mantle/postgres";
-
-// one per isolate: every consumer must share it
-let session: PgSession | undefined;
-const database = (env: Env) => (session ??= requestScoped(async () => {
-  const client = new pg.Client({ connectionString: env.HYPERDRIVE.connectionString });
-  await client.connect();
-  return client;
-}));
-// storage: (env) => postgresStorage({ connect: database(env).connect })
-// identity: createMantleAuth({ database: pgPool(database(env).connect), driver: pgDatabaseDriver(database(env).connect), ... })
-// fetch: (request, env, ctx) => database(env).run(() => routes(request))
-```
-
-One operation holds the shared client from `connect()` to `end()`; another that
-arrives meanwhile opens its own, so nothing runs inside another's transaction.
-With `new pg.Client({ …, pipeline: true })` (pg 8.23 or later) a write batch is
-one round trip instead of N + 2; the generated Workers preset leaves it off
-until Hyperdrive is verified to forward a pipelined transaction.
-
-The Worker needs `compatibility_flags: ["nodejs_compat"]` for `pg`. Mantle's
-and Better Auth's reads run outside a transaction, which Hyperdrive would answer
-from its cache, so create the Hyperdrive config with caching disabled
-(`wrangler hyperdrive create … --caching-disabled`), or a read can miss the
-write before it and a revoked session can be accepted until the cache expires. The same holds for a role
-re-read and for a revoked grant: Auth's reads are single statements outside a transaction, so their freshness
-depends on `--caching-disabled` too. `timeZone` must be an
-IANA name: PostgreSQL reads an offset such as `+08:00` with the opposite sign.
-
-Bun has a generated preset for both engines (`mantle generate --host bun`,
-ADR-0038, ADR-0039): over PostgreSQL it is the Workers composition on a `pg.Pool`;
-over SQLite `bunSqliteDriver` gives Better Auth the same store. A `DatabaseDriver` is one method, so another engine
-(libSQL, for example) is a few lines of application code on `host: none`: the
-entry calls `createMantle` and its own server.
-
-`site` turns on the site capability (site settings and media); see
-[Site defaults and site_config](../reference/site-config.md).
-
-## Testing a service
-
-Run the service under `wrangler dev` against a fresh local D1 and drive it over
-HTTP, as the [reference service](../../examples/reference-service/README.md)'s
-`smoke.mjs` does.
+[Native execution](../guides/native-execution.md) defines input ownership, native result values, atomicity and uncertain write outcomes.

package/docs/handbook/concepts/views.md

@@ -1,116 +1,17 @@
----
-description: How a View's SQL SELECT is compiled, which policies the runtime injects, and how REST, MCP, Admin and Store serve it with limit and cursor paging.
----
 # Reads: Views, REST and MCP
 
-A View is one SQL `SELECT` in PostgreSQL syntax over declared Schemas.
+A View declares one PostgreSQL-syntax SELECT over declared Schemas or reusable internal Views. Generation parses, checks and lowers it for postgres or sqlite, adds row policy, and emits a typed function. Requests bind values and execute SQL; they do not parse or compile manifests.
 
-```yaml
-apiVersion: cms.mantle.aotter.net/v2
-kind: View
-metadata: { name: my-orders }
-spec:
-  surface: public
-  requires: { auth: { all: [ctx.user] } }
-  sql: |
-    SELECT o.id, o.qty, o.orderStatus, i.name AS item, o.version
-    FROM orders o JOIN items i ON i.id = o.itemId
-    ORDER BY o.created_at DESC
-```
+Use internal Views for joins, aggregates, OR and reusable reads. Simple handler id lookups and AND filters can use Store. See [query from TypeScript](../guides/typed-queries.md) for a complete example.
 
-## Compiled once, checked at every run
+| Surface | Exposure when mounted |
+| --- | --- |
+| public | REST `/api/views/<name>` and public MCP |
+| admin | Admin View API and admin MCP |
+| internal | Generated operation only; no public route/tool |
 
-`mantle generate` parses the SQL with PostgreSQL's own parser, refuses what the
-dialect does not support (with the position in the statement), and stores the
-parse tree as the View's IR in the plan. No running service parses SQL. At run time the
-runtime validates the IR against the same allowlist, injects policy, and the
-dialect prints its engine's SQL (SQLite for D1).
+Every generated invocation retains its `requires`. SQL row policy limits scope, TTL and publishing visibility at every relation. The app supplies a verified Caller.
 
-What the D1 dialect accepts, in short (the [View reference](../reference/view.md)
-has the full table):
+Bare Views return native row arrays. Declared date/date-time columns are formatted by SQL; other values retain driver behavior. Proved pageable Views also get `paged/views/<encoded-name>.ts`, returning `{ rows, nextCursor? }`. Internal paging creates no exposure. Keyset paging requires generate-time order/cardinality proofs; it does not avoid the source scan for an aggregate. Inspect native EXPLAIN and indexes.
 
-- columns, literals, arithmetic, `CASE`, `COALESCE`, `CAST` (to `int` only for
-  integer literals: use `round(x)`), JSON `->>`;
-- `WHERE` with comparisons, `BETWEEN`, `IN (list | subquery)`, `EXISTS`,
-  `LIKE` (case-insensitive, as in SQLite), `IS DISTINCT FROM`;
-- `INNER` and `LEFT JOIN`, subqueries, `json_each(…)` on D1 (PostgreSQL: `jsonb_array_elements_text(…) WITH ORDINALITY AS j(value, n)`);
-- `GROUP BY`, `HAVING`, `count`, `sum`, `min`, `max`, `avg`,
-  `json_group_array`, `json_group_object`; `row_number()`, `rank()` and running
-  aggregates;
-- `ORDER BY … NULLS FIRST | LAST`, `LIMIT` (it needs an `ORDER BY`),
-  `DISTINCT`;
-- `now()`, `date_trunc`, `extract`, `ts ± interval '<n> seconds|minutes|hours'`;
-- `mantle.search`, `mantle.search_rank`, `mantle.near`, `mantle.distance`.
-
-Refused: `OFFSET` (page with cursors), `RIGHT`/`FULL`/`CROSS JOIN`, any table
-that is not a declared Schema, and SQLite's own clock (`CURRENT_TIMESTAMP`,
-`'now'`).
-
-PostgreSQL is the reference dialect (ADR-0037): on it a View may also use `WITH`
-(recursive too), `UNION` and `DISTINCT ON` inside a `WITH` or subquery,
-`LATERAL`, window frames, `FILTER`, jsonb operators, `ILIKE` and regular
-expressions. D1 refuses them as needing the PostgreSQL dialect. On every
-dialect a View may read an internal View in `FROM`, which is inlined; that is
-how a rule many Views share is written once.
-
-## Policies the runtime injects
-
-Every Schema reference, in `FROM`, joins and subqueries, is replaced by a
-subquery that keeps only visible rows:
-
-- **scope**: on a scoped Schema, a user caller's own rows (an anonymous caller
-  sees none);
-- **TTL**: unexpired rows;
-- **published-only**: on a `public` View, published rows of `publishing`
-  Schemas.
-
-So the join in `my-orders` sees only the caller's orders, and the View never
-says so. A public View that joins a Schema without `publishing` to one with it
-must join them by an explicit condition, or validation refuses it.
-
-## Output names and types
-
-- A column that reads a Schema field unchanged comes back under the field's
-  declared name and type (`o.orderStatus` is `orderStatus`).
-- Anything else keeps its alias. SQL folds unquoted names to lower case, so
-  `count(o.id) AS orderCount` comes back as `ordercount`; write
-  `AS "orderCount"` to keep the case.
-- `*` expands to the declared fields, never the scope field or native columns.
-- The generated `ViewRow_<name>` types each column the same way; an expression
-  is `unknown`.
-
-## Surfaces
-
-| `surface` | Served at |
-|---|---|
-| `public` | `GET /api/views/<name>` (REST) and a tool on the public MCP surface (`/mcp`) |
-| `staff` | `GET /admin/api/views/<name>`, with CSV at `/export`, and a tool on the staff MCP surface (`/mcp/staff`) |
-| `internal` | no surface: `ctx.store.view(...)` and `runtime.store` only |
-
-`requires` gates every path: an anonymous caller is 401 `UNAUTHENTICATED`, a
-signed-in one who fails a predicate is 403 `AUTH_DENIED`. A staff View still
-needs its own `requires` to limit roles beyond Admin's gate.
-
-## Input and paging
-
-`input` is a JSON Schema object; the SQL reads `input.<name>`. Over REST the
-properties are query parameters, coerced to their declared types; a missing
-required one is 400 `INPUT_VALIDATION_FAILED`. `limit` and `cursor` are
-reserved names.
-
-Every surface pages the same way: `limit` (default 50, at most 500) and an
-opaque `cursor`. The response is `{ "rows": [...], "nextCursor": "…" }`, with
-`nextCursor` only when more rows exist. The compiler appends `id` to the
-`ORDER BY` so the order is total. A View's own `LIMIT` caps the whole result.
-
-## MCP
-
-Each View of a surface is a read-only tool named after it in snake case
-(`my-orders` is `my_orders`), whose input is the View's `input` plus `limit`
-and `cursor`. `description` becomes the tool's description. See
-[MCP and agents](./mcp-and-agents.md).
-
-## Further reading
-
-- [View reference](../reference/view.md)
-- [Query from TypeScript](../guides/typed-queries.md)
+See the [View reference](../reference/view.md), [surface contracts](../reference/surface.md) and [native value contract](../guides/native-execution.md).

package/docs/handbook/examples/hub.md

@@ -1,21 +1,5 @@
----
-description: Index of the Mantle 0.2.0 examples — whole services in the v2 grammar, each compiled by mantle generate, and the runnable reference service.
----
 # Examples
 
-Each example is a whole service whose manifests compile with `mantle generate`;
-its handlers are written against the generated types. They live beside this
-handbook in [`docs/examples/`](../../examples/README.md).
+Use the [Worker quickstart](../start/quickstart-worker.md) for a complete native manifest and entry, [typed queries](../guides/typed-queries.md) for embedding, and [service composition](../cloudflare/service-entry.md) for optional surfaces.
 
-| Example | Shows |
-|---|---|
-| [Reference service](../../examples/reference-service/README.md) | a runnable service with its smoke test: scope, SQL Views and Procedures, hooks, a cron, REST, both MCP surfaces, Admin's API and sign-in |
-| [Intake form](../../examples/intake.md) | an anonymous form: one SQL `INSERT` and a staff View |
-| [Intake with bot check and notification](../../examples/intake-hooks.md) | a guard and an after hook |
-| [Reservation requests](../../examples/reservation.md) | a request queue with a `check` |
-| [Publication](../../examples/publication.md) | localized posts, per-locale Views and `mantle.search` |
-| [Legal documents and consent](../../examples/legal-documents.md) | immutable revisions and a conditional insert |
-| [Procurement approvals](../../examples/procurement.md) | own rows through `auth.uid()`, a locked staff review |
-| [Commerce catalog and orders](../../examples/commerce.md) | a published catalog and guest orders |
-| [Commerce inventory](../../examples/commerce-inventory.md) | atomic stock reservation, a scheduled expiry, a verified payment callback |
-| [Guarded API access](../../examples/guarded-api.md) | API keys, scopes and an entitlement guard |
+The runnable [reference service](https://github.com/aotter/mantle/blob/develop/docs/examples/reference-service/README.md) exercises the native package integration. See the [generated public website](../../examples/generated-web/README.md) for a native Worker example.

package/docs/handbook/guides/adapter-guide.md

@@ -0,0 +1,11 @@
+# Another host or database handle
+
+Mantle has an open driver boundary and exactly two closed dialects in 0.2.0, postgres and sqlite. Choose the generation target whose emitted SQL and handle calls match your host. The app owns its router, resources, lifetime and scheduler.
+
+PostgreSQL's `Postgres` in `kernel/contracts.ts` needs `unsafe(text, values)` and `begin(options, fn)`. Bun.SQL and postgres.js fit without wrappers. [The node-postgres example](postgres-adapters.md) shows the transaction and result-count contract. SQLite handle contracts are exported by `@aotter/mantle/driver/d1` and `/driver/bun-sqlite`: D1 prepare/bind/all/batch, or SQLite query/exec/transaction. Reads may need only the narrower reader shape.
+
+A third-party driver must preserve result, binding, atomicity and uncertain-outcome semantics. A handle that cannot transact must reject before invoking the callback. Never emulate an atomic Procedure with unrelated autocommit HTTP calls.
+
+Users may choose another SQL executor, including WASM SQLite persisted to IndexedDB, at their own risk. Mantle supports bun:sqlite, D1, Bun.SQL and postgres.js; there is no bundled Durable Object adapter. The app owns any custom adapter and its tests. A third SQL engine requires forking the compiler and Store runtime, not installing a dialect plugin.
+
+No runtime performs DDL, introspection or schema checks. Install initial SQL and rehearse migrations explicitly; see [database ownership](../concepts/runtime-and-adapters.md).

package/docs/handbook/guides/admin-extensions.md

@@ -1,191 +1,20 @@
----
-description: Add your own pages, settings, actions, record panels and field widgets to Admin in 0.2.0, bind them from manifest uiSchema, and verify them.
----
 # Extend Admin
 
-Manifests decide most of what Admin shows ([Customize Admin from
-manifests](admin-ui.md)). When a project needs UI of its own, it adds an
-**Admin extension**: a declaration that is plain data, server handlers, and
-optionally one ES module with renderers. The contract is
-[ADR-lite 1376](../../adr/adr-lite-1376-admin-extensions.md).
+Native Admin accepts app-owned extension declarations, executable server handlers and optional same-origin client modules. Import client `defineAdminExtension` from `@aotter/mantle-admin/extension` and UI primitives from `@aotter/mantle-ui/kit`. Server types live in `@aotter/mantle-admin/server`.
 
-For a new project with feature `admin`, the preset writes
-`src/admin-extensions.ts` (yours to edit) and passes its `adminExtensions` to
-`createAdminSurface`. The preset is written once: when `src/service.ts`
-already exists, `mantle generate` leaves it alone, so add the file and
-`extensions: adminExtensions` to your `createAdminSurface` call yourself.
+| Contribution | Placement |
+| --- | --- |
+| pages/settings | Extension page; settings forms are generated from the supported form subset |
+| actions | record, list selection or list toolbar |
+| panels | record sidebar or home |
+| fields | field input or cell |
 
-## What you can add
+Admin contributions sit behind the admin-layer gate; optional field roles default to `admin`. Server authorization is checked on every route. Handlers own finer business permissions.
 
-| Contribution | Where it appears | Client code |
-|---|---|---|
-| `pages` | `/admin/x/{extension}/{page}`; in **More** when it declares `nav` | a renderer |
-| `settings` | `/admin/x/{extension}/{id}`, always in **More** | none: Admin renders a form from `schema`, which must be the form subset (a flat object whose properties are `string`, `number`, `integer` or `boolean`, with `title`, `description`, `default`, `enum`, `oneOf`, `minimum`, `maximum`, `minLength`, `maxLength`) |
-| `actions` | `record/v1` (a record's header), `list.selection/v1` (the bulk bar), `list.toolbar/v1` (a list's toolbar) | none for `run` and `confirm` (a server `run`); a renderer for `dialog` |
-| `panels` | `record.sidebar/v1` (a record's side column), `home/v1` (the home page) | a renderer |
-| `fields` | `field.input/v1` (a form control), `field.cell/v1` (a list cell) | a renderer |
+Pass full declarations to `mantle generate … --admin --admin-extensions <module>` (named/default `adminExtensions` array). Generation checks contributions, manifest uiSchema references and settings schemas, then emits `extensionMetadata` and compiled `extensionBindings` in `admin-extensions.ts`. Bind the same runtime definitions with `extensionBindings(adminExtensions)` and merge its extensions/routes into `admin()` options. Drift is refused before execution.
 
-Pages, settings, actions and panels need a minimum staff `role`; a field
-widget's `role` is optional and defaults to `contributor` (below it, Admin's
-own control is used). The server sends each staff member only the
-contributions their role reaches, and checks the session and role again on
-every extension route: hiding a button is never the only guard.
+Serve each `module` at a same-origin absolute path and install its integrity in the host shell's import map. Native Admin does not serve `source` modules or inject integrity; generation rejects source. Share React and the UI kit via the built import map, rather than bundling a second React. Canonical Admin refuses framing; use its separate same-origin preview contract.
 
-- A settings page and an action are checked against their own `role`.
-- The extension's `api` and its served `source` are shared by all its
-  contributions, so they need only the **lowest** role among them: an owner-only
-  page does not make the `api` owner-only.
+Raw API handlers receive the original Request. Declared `bodyLimit` checks Content-Length before DB access, but the app must bound unknown-length streams. Built-in JSON routes use the shared bounded reader after caller/origin checks. Do not lose exact OCC or uncertain-outcome handling in custom actions.
 
-Finer rules belong in your handlers, which receive the caller.
-
-## A complete extension
-
-```ts
-// src/admin-extensions.ts
-import type { AdminExtension } from "@aotter/mantle/admin";
-
-const brand: AdminExtension = {
-  apiVersion: 1,
-  id: "brand",
-  title: { en: "Brand", "zh-TW": "品牌" },
-  // Admin serves this at /admin/extensions/brand.js, with its integrity computed
-  source: BRAND_MODULE,
-  contributes: {
-    pages: [{ id: "palette", title: "Palette", role: "editor", nav: { group: "more" } }],
-    settings: [{ id: "defaults", title: "Brand defaults", role: "owner", schema: {
-      type: "object", required: ["accent"],
-      properties: { accent: { type: "string", title: "Accent", enum: ["teal", "navy"] }, limit: { type: "integer", minimum: 1, maximum: 20 } },
-    } }],
-    actions: [{ id: "reindex", title: "Re-index colors", role: "editor", target: "record/v1", presentation: "confirm", when: { schema: ["products"] } }],
-    panels: [{ id: "usage", title: "Where it is used", role: "contributor", target: "record.sidebar/v1", when: { schema: ["products"] } }],
-    fields: [
-      { id: "color", target: "field.input/v1", optionsSchema: { type: "object", properties: { palette: { type: "string", enum: ["brand", "web"] } } } },
-      { id: "swatch", target: "field.cell/v1" },
-    ],
-  },
-  handlers: {
-    settings: { defaults: { load: async () => ({ accent: "teal" }), save: async (_caller, value) => value } },
-    actions: { reindex: { run: async (caller, { record }) => ({ message: `Re-indexed ${record!.id}` }) } },
-    // GET/POST /admin/api/x/brand/api/{path}; null answers 404
-    api: async (request, { caller, path }) => (path === "usage" ? Response.json({ count: 3 }) : null),
-  },
-};
-
-export const adminExtensions: readonly AdminExtension[] = [brand];
-```
-
-`source` is the module's code (or a function returning it). How you load the
-text is up to your host: a string constant, a Wrangler `Text` module rule, or
-Bun's `with { type: "text" }` import. A host that serves the file itself sets
-`module: "/path.js"` (same-origin) and optionally `integrity` instead.
-
-## The module
-
-The module needs no build step. Admin's import map provides `react`,
-`react/jsx-runtime`, `react-dom`, `react-dom/client`,
-`@aotter/mantle-ui/kit` and `@aotter/mantle-ui/extension`, so the module
-uses Admin's own React and kit and looks like the rest of Admin. If you do
-bundle it, mark those specifiers external.
-
-```js
-import { jsx } from "react/jsx-runtime";
-import { useEffect, useState } from "react";
-import { createRoot } from "react-dom/client";
-import { Badge, Input } from "@aotter/mantle-ui/kit";
-import { defineAdminExtension } from "@aotter/mantle-ui/extension";
-
-// a renderer gets an element and a context; it may return a cleanup or { update, unmount }
-const react = (Component) => (element, context) => {
-  const root = createRoot(element);
-  root.render(jsx(Component, { context }));
-  return { update: (next) => root.render(jsx(Component, { context: next })), unmount: () => root.unmount() };
-};
-
-function Usage({ context }) {
-  const [count, setCount] = useState(null);
-  useEffect(() => { fetch(`${context.apiBase}/usage`).then((r) => r.json()).then((b) => setCount(b.count)); }, [context.apiBase]);
-  return jsx(Badge, { children: count === null ? "…" : `${count} pages` });
-}
-function Color({ context }) {
-  return jsx(Input, { "aria-label": context.field.name, value: String(context.field.value ?? ""), onChange: (e) => context.onChange(e.target.value) });
-}
-
-export default defineAdminExtension({
-  pages: { palette: react(() => jsx("p", { children: "Palette" })) },
-  panels: { usage: react(Usage) },
-  fields: {
-    color: react(Color),
-    swatch: (element, context) => { element.textContent = `■ ${context.field.value ?? ""}`; },
-  },
-});
-```
-
-The context holds `extension`, `contribution`, `apiBase` (your `api`
-handler), `language`, `theme`, `caller.role`, and where it applies `record`
-(`{ schema, id, version }`), `selection`, `schema`, `field`, `options` and,
-for `field.input/v1`, `onChange`. `host.navigate(path)`, `host.notify(text)`
-and `host.close()` (a dialog action) are the supported console API. They are
-not a sandbox: a module is trusted same-origin code and can still reach the
-DOM, `fetch` and whatever the signed-in session may do (see Trust).
-
-## Bind contributions from manifests
-
-A manifest's `uiSchema` can name a project contribution as
-`<extension>/<contribution>`. The binding sits next to the field it changes,
-so one change (and one review) covers both:
-
-```yaml
-apiVersion: cms.mantle.aotter.net/v2
-kind: Schema
-metadata: { name: products }
-spec:
-  title: Products
-  lifecycle: operational
-  uiSchema:
-    fields:
-      color: { widget: brand/color, options: { palette: brand } }
-    list:
-      columns: [color]
-      cells: { color: brand/swatch }
-    panels: [brand/usage]
-  schema:
-    type: object
-    required: [name]
-    properties:
-      name: { type: string }
-      color: { type: string }
-```
-
-- `fields.<name>.widget` names a `field.input/v1` contribution (any field type);
-  `options` must satisfy its `optionsSchema`.
-- `list.cells.<field>` (Schemas, and staff Views by output name) names a
-  `field.cell/v1` contribution.
-- `panels` (Schemas) names `record.sidebar/v1` contributions.
-- Procedure `uiSchema.fields.<name>.widget` works like a Schema's.
-
-`mantle generate` checks the shape of the names. `createAdminSurface` checks
-that each named contribution exists, has the right target and accepts its
-`options`, and refuses to start otherwise (`UI_EXTENSION_UNKNOWN`,
-`UI_EXTENSION_TARGET`, `UI_EXTENSION_OPTIONS`). Name only your project's own
-extensions, so the project renders the same locally and deployed; a host that
-adds extensions attaches them with `when`. Core checks that a name exists, not
-whose extension it is. When a manifest names a widget for a field (even
-`textarea`), a matching `when` does not replace it. `uiSchema` stays presentation only: the field's JSON Schema
-still validates whatever a widget sends.
-
-## Trust
-
-An extension's module runs in Admin's origin with the viewer's session. It
-has no more power than the project already has: whoever deploys the project
-already controls its handlers and storage. Keep host routes that act beyond
-this project (an organization console, other projects) on another origin.
-
-## Verify
-
-- `createAdminSurface` validates every declaration at start
-  (`UI_EXTENSION_INVALID` names the first problem).
-- `ADMIN_EXTENSION_JSON_SCHEMA` (from `@aotter/mantle/admin`) describes a
-  declaration for tooling; `diffAdminExtensions(before, after)` lists added,
-  removed and changed contributions for review.
-- Sign in as each role and check what appears; call
-  `/admin/api/x/{extension}/...` as a lower role and expect 403.
+See [native Admin](native-admin.md) for mounting and acceptance and [generated descriptors](../reference/admin-descriptors.md) for build-time metadata.