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

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, 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
@@ -57,14 +85,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 +118,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, 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.

package/docs/handbook/start/project-and-cli.md

@@ -1,166 +1,57 @@
 ---
-description: The files of a Mantle 0.2.0 project, who owns each, mantle.config.json, and every option of mantle generate.
+description: Generation targets, CLI options and ownership of native application files.
 ---
 # Project layout and CLI
 
-## Files
+| File | Owner |
+| --- | --- |
+| `manifests/*.yaml` | App: closed v2 declarations and SQL |
+| `src/worker.ts`, auth, handlers, frontend | App: routing, Caller verification and side effects |
+| `generated/` | Generator: TypeScript, native SQL and selected bindings |
+| `migrations/` | App's agent and native migration tool |
+| `wrangler.jsonc` | App configuration; generator maintains selected split-build keys |
+| `dist/` | Disposable bundle output; do not commit |
 
-| Path | Written by | Owner |
-|---|---|---|
-| `manifests/*.yaml` | you | you |
-| `mantle.config.json` | `mantle generate`, when the selection changes | you may edit it; generate keeps keys it does not know |
-| `.mantle/generated/plan.json` | every `mantle generate` | generated: never edit, commit it |
-| `.mantle/generated/mantle.ts` | every `mantle generate` | generated: never edit, commit it |
-| `src/service.ts`, `src/index.ts`, `src/handlers.ts`, `src/identity.ts` (identity `custom`) | the first `mantle generate` | yours from then on |
-| `wrangler.jsonc` (Cloudflare, unless a `wrangler.json` or `wrangler.toml` exists), `tsconfig.json`, `.dev.vars.example` (Cloudflare, identity `mantle`) or `.env.example` (Bun), `.gitignore` | the first `mantle generate`, each only if missing | yours |
-
-`mantle generate` writes each preset file only when it does not exist, and
-writes none once `src/service.ts` exists: from then on the application owns
-its composition. To get a fresh preset, move the old file aside and rerun.
-
-- `plan.json` is `{ "sourceHash": …, "plan": … }`: the sealed `RuntimePlan`
-  and the SHA-256 of the manifest sources. The plan's `fingerprint` is what
-  boot checks; reformatting a manifest changes `sourceHash` but not the
-  fingerprint.
-- `mantle.ts` exports `plan`, `sourceHash`, the `Mantle` namespace of row, input and output
-  types, `Store` and `CallerStore` typed over your Schemas and
-  Views, and `MantleHandlers`, which lists exactly the plan's `ref` handlers. A
-  missing or extra handler is a type error. See
-  [Query from TypeScript](../guides/typed-queries.md).
-
-## `mantle.config.json`
-
-```json
-{ "version": 2, "identity": "mantle", "features": ["mcp", "admin", "web"] }
-```
-
-| Key | Values | Meaning |
-|---|---|---|
-| `version` | `2` | `1` (a 0.1.x config) fails with exit 2 |
-| `identity` | `mantle`, `custom`, `none` | who the callers are. `mantle`: `@aotter/mantle/auth` (Better Auth sign-in, staff roles, OAuth for MCP). `custom`: your `src/identity.ts` maps your own sessions to callers. `none`: every caller is anonymous |
-| `features` | a subset of `mcp`, `admin`, `web`, in that order | `mcp`: the public MCP surface at `/mcp` (and staff MCP inside Admin). `admin`: the Admin console and its API at `/admin`, which needs an identity. `web`: reserved for public pages; REST at `/api` is always mounted |
-| `host` | `cloudflare`, `bun`, `none`, optional | where the service runs (ADR-0036); absent is `cloudflare`. `none` writes no preset: only the plan and its types, and your code calls `createMantle`. The host never enters the plan |
-| `dialect` | `sqlite` (alias `d1`), `postgres`, or a dialect package name, optional | the SQL engine; absent is `sqlite`, which runs on D1. `postgres` runs on PostgreSQL, through Hyperdrive on Cloudflare. The plan records the dialect (the SQLite dialect as `@aotter/mantle/d1`) |
-
-Without a config or flags, the selection is identity `mantle` and every
-feature. An explicit `--features` without `--identity` means identity `none`.
-A rerun keeps the saved identity, host and dialect; asking for another one is
-refused (exit 2), so switching never drops tables or orphans data. Change
-`mantle.config.json` deliberately once the data is moved.
-
-| | `cloudflare` | `bun` | `none` |
-|---|---|---|---|
-| `sqlite` | preset over D1 (the default) | native bun:sqlite | plan and types only |
-| `postgres` | preset over Hyperdrive and `pg` | preset over a `pg.Pool` (node-postgres) | plan and types only |
-| a dialect package | plan and types only; compose `src/service.ts` with its storage adapter | plan and types only | plan and types only |
-
-Each selection needs packages in the project. `mantle generate` checks them
-and stops before writing anything, naming the install command for your
-package manager. It never installs anything. The host and dialect rows, and the
-staff MCP App, are checked only while the preset is still to be written.
-
-Use the versions in the installed Core's `package.json` `peerDependencies`,
-not registry latest, for optional auth and MCP packages. The diagnostic's
-install command includes those versions and incompatible installed peers are
-refused before generation. Keep `@aotter/mantle-ui` at Core's
-exact version. A package manager accepting an incompatible peer does not make
-it a supported combination; inspect peer warnings before starting the service.
-
-| Selection | Packages |
-|---|---|
-| always | `@aotter/mantle` |
-| identity `mantle` | `better-auth`, `@better-auth/oauth-provider`, `@better-auth/mcp`, `@better-auth/cimd` |
-| feature `mcp` | `@modelcontextprotocol/server`, `@modelcontextprotocol/ext-apps` |
-| feature `admin` | `@aotter/mantle-ui` (its `dist/admin` is the console, bound as `ASSETS` in `wrangler.jsonc`) |
-| dialect `postgres` (host `cloudflare` or `bun`) | `pg` |
-| host `bun` | `bun-types` |
-| feature `mcp` with an identity, without `admin` | `@aotter/mantle-ui` (the staff MCP App) |
-
-On Cloudflare the project also installs `wrangler`, `@cloudflare/workers-types` and
-`@types/node` itself. A TypeScript PostgreSQL project, on Cloudflare or Bun, also installs
-`@types/pg` as a dev dependency for the generated `pg` import; node-postgres is
-the PostgreSQL driver on every host.
-
-## `mantle generate`
+## Commands
 
 ```sh
-mantle generate [--manifests <dir>] [--features <list>] [--identity <kind>] [--host <host>] [--dialect <name>]
-mantle generate --check [--database <file>]
+mantle generate <target> <output-directory> <manifest>... [options]
+mantle bundle <entry> <outdir>
 ```
 
-| Option | Meaning |
-|---|---|
-| `--manifests <dir>` | the manifest directory, default `./manifests`. Every `.yaml` and `.yml` file directly in it is read |
-| `--features <list>` | comma-separated, a positive list. A missing dependency fails with `GENERATE_FEATURE_DEPENDENCY_MISSING`; an omitted feature is never added back |
-| `--identity <kind>` | `mantle`, `custom` or `none` |
-| `--host <host>` | `cloudflare`, `bun` or `none`, chosen on the first run. `bun` defaults the dialect to `postgres` |
-| `--dialect <name>` | `sqlite` (alias `d1`), `postgres` or a dialect package, chosen on the first run |
-| `--check` | writes nothing. Exits 1 when `plan.json`, `mantle.ts` or `mantle.config.json` differs from what generate would write, or a package is missing |
-| `--database <file>` | with `--check`: also read a local SQLite file (Wrangler's local D1 is under `.wrangler/state/v3/d1/`) read-only, and print the SQL storage convergence would run |
-
-Exit codes: 0 success, 1 a diagnostic or a stale file, 2 a usage or file
-error. Diagnostics name the manifest file, the path in it and, for SQL, the
-position in the statement.
-
-`--check` is the gate for CI and for agents: run `mantle generate`, then
-`mantle generate --check`, then your typecheck.
-
-### Schedules and Cloudflare crons
-
-On host `cloudflare`, schedule Triggers use POSIX cron. `mantle generate` translates each enabled
-one with `toCloudflareCron` and refuses (exit 1, before writing) one that
-Cloudflare cannot run the same way. It writes `triggers.crons` into a new
-`wrangler.jsonc`; once the file is yours it only warns when the crons differ
-from the plan, and you update them.
-
-### Storage SQL
-
-Boot creates what the plan adds (tables, columns, indexes, check triggers) and
-refuses what it cannot change safely. `--check --database` prints the same
-diff without applying it, for the `sqlite` dialect; see [Deploy and operate](../cloudflare/deploy-and-operate.md).
+| Target | Dialect | Handle |
+| --- | --- | --- |
+| `bun-sqlite` | sqlite | bun:sqlite Database |
+| `bun-postgres` | postgres | Bun.SQL |
+| `cloudflare-d1` | sqlite | D1 binding/session |
+| `cloudflare-postgres` | postgres | postgres.js, usually with Hyperdrive |
 
-### PostgreSQL on Cloudflare
+Other handles may adapt to the same [structural driver contracts](../guides/adapter-guide.md). Dialects are exactly postgres and sqlite in 0.2.0.
 
-`mantle generate --dialect postgres` writes the same preset over Hyperdrive:
-`src/service.ts` opens one `pg` client per request from `env.HYPERDRIVE`, and
-`wrangler.jsonc` binds `HYPERDRIVE` with a placeholder id and a
-`localConnectionString` for `wrangler dev`. Before deploying, create the config
-with caching off and put its id in place of the placeholder; generate warns
-until you do:
-
-```sh
-wrangler hyperdrive create my-app --caching-disabled --connection-string="postgres://user:pass@host:5432/db"
-```
-
-Reads run under the role's own statement limit, so give it one, and UTC, before
-the first boot (locally too); the boot error names any other setting:
+| Option | Meaning |
+| --- | --- |
+| `--check` | Compare generated owned files and Wrangler build keys without writing; stale output exits nonzero. No database or credentials are needed. |
+| `--admin` | Emit native Admin bindings and `admin/*` modules; install the separate Admin package. |
+| `--auth <module>` | Read plain `authOptions(env)` (or an exported auth instance's options) and append selected Better Auth DDL. Repeat it once per Better Auth instance. Prefer plain options without initialization side effects. |
+| `--site <module>` | Read `siteDefaults`; emit site/media bindings and deployment SQL. |
+| `--admin-extensions <module>` | Read the named/default `adminExtensions` array and the optional `navGroups` (sidebar groups; see native-admin.md "Sidebar"). The app shell passes `src/admin.ts`. |
+| `--wrangler <path>` | Existing JSONC/JSON/TOML config; default finds one or creates `wrangler.jsonc`. TOML receives manual-edit instructions. |
+| `--entry <path>` | Worker source entry; default `src/worker.ts`. |
+| `--outdir <path>` | Split bundle output; default `dist`. Keep separate from source/generated files. |
 
-```sql
-ALTER ROLE app SET statement_timeout = '10s';
-ALTER ROLE app SET TimeZone = 'UTC';
-```
+## Outputs
 
-## 0.1.x projects
+`generated/.mantle-inputs.json` records the Mantle version and a hash of every input the run read (manifests and the
+`--auth`, `--site`, `--admin-extensions` modules). `mantle bundle`, which Wrangler runs for `wrangler dev` and every
+deploy, refuses to build when an input changed since, so stale generated code cannot run; regenerate and rebuild.
+Commit it with the other generated files.
+The bundle also prints notes, never errors, for SQL in the app's own code against Better Auth's tables (read users
+through `userOf(caller)` or `readIdentity(auth)` instead) and for Better Auth roles beyond `admin` and `user`.
 
-`apiVersion: cms.mantle.aotter.net/v1` manifests, a `version: 1` config, `mantle validate`,
-`mantle emit-openapi`, `mantle skills` and the `mantle-harness` bin are gone.
-`docs/upgrade-0.1-to-0.2.md` in the installed package is the guide.
+`generated.ts` exports typed queries and Store. Direct `views/<encoded-name>.ts` and `procedures/<encoded-name>.ts` entries export an operation and its types. Proved pageable Views also have `paged/views/*`; boundary checks live in `validation/*`. `admin-descriptors.ts`, `rest.ts` and `web.ts` are always emitted. Manifest exposure selects `mcp.ts`; `admin-bindings.ts` and `admin/*` require `--admin`. Auth and site are explicit options.
 
-## Bun
+Apply `schema.sql` only to an empty database. Later changes require [explicit migrations](../concepts/runtime-and-adapters.md#schema-installation-and-migrations); generation and runtime do not inspect the database. Ref declarations print the `Handlers` keys to implement.
 
-`mantle generate --host bun` selects PostgreSQL on first run. Install `bun-types`
-for the generated project's typecheck, the selected feature/identity packages,
-then set DATABASE_URL in `.env` and run `bun src/index.ts`. For SQLite pass
-`--dialect sqlite` and optionally DATABASE_FILE (default mantle.sqlite).
-The preset is written once, uses `pg` for PostgreSQL and bun:sqlite for SQLite (`@aotter/mantle/bun`), and
-owns Bun.serve, trusted socket IP and shutdown/background work. Admin binds the
-installed UI bundle. Enabled schedule Triggers fail generation; use `host: none`
-with an explicit scheduler when schedules are required. Behind a reverse proxy,
-set TRUSTED_PROXIES to its addresses: otherwise every client shares the proxy's
-address, and with it one sign-in rate limit.
+Never edit generated output by hand. Merge manifests/options, regenerate with the same command, then review TypeScript and SQL diffs. Use that exact command with `--check` in CI. Unmarked app files are preserved. Imported option modules must be pure; generation does not make their side effects safe.
 
-PostgreSQL on Bun is node-postgres, as on Workers (ADR-0039): the entry builds a
-`pg.Pool` with `pipeline: true`, and each request borrows one pooled client
-(`requestScoped`). Install `pg`. The role needs no privilege beyond converging its
-tables (no `TEMPORARY`); set `statement_timeout` and `TimeZone` UTC on the role,
-which boot checks.
+On Workers, generation configures `mantle bundle` as Wrangler's build command. It emits minified split ESM with a startup guard for eager Better Auth imports. On Bun, the app owns `Bun.serve`, its Database/SQL pool and scheduler. See [service composition](../cloudflare/service-entry.md).