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

package/docs/handbook/reference/procedure.md

@@ -12,8 +12,12 @@ A ref handler is application code called as `(ctx, input)`. Generation prints re
 
 `target: { schema, id, version? }` binds an Admin operation to a row. SQL targets can be inferred for a single locked row operation; declare a target for a ref operation when needed. Input fields must have the required shapes.
 
+## MCP tool hints
+
+Every generated AI-facing tool (MCP, WebMCP, publishing and media tools) carries a `title`, `readOnlyHint` and `destructiveHint`; clients such as Claude use them to decide between auto-approval and confirmation. The title is the declared `title`, else the name made readable (`add-item` reads `Add item`). A View is `readOnlyHint: true, destructiveHint: false`. A Procedure is `readOnlyHint: false`, and `destructiveHint` is `false` only when its SQL inserts without overwriting: any DELETE or UPDATE, an `ON CONFLICT DO UPDATE` or a ref handler makes it `true`. Of the generated publishing transitions only `archive` is destructive. The media tools always carry `openWorldHint: true`; the upload policy, list and get tools are read-only and only `delete_media_asset` is destructive. Admin's WebMCP navigation tools (`admin_get_context`, `admin_navigate`) are read-only. `spec.mcp` accepts `readOnlyHint`, `destructiveHint` and `openWorldHint`, and a declaration always wins; a declared `readOnlyHint: true` defaults `destructiveHint` to `false`. Outside the media tools `openWorldHint` appears only when declared. `idempotentHint` is never generated, and `spec.mcp` refuses it. Hints never change authorization.
+
 Generated requires checks gate calls. Boundary input validators are generated separately; direct queries accept driver-ready, app-validated input. Dynamic guards and lifecycle hooks are rejected. See [native execution](../guides/native-execution.md) and [surface contracts](surface.md).
 
 SQL INSERT/upsert into a user-field scoped Schema is system-only. For a verified user, insert through `ctx.store` so membership and single-partition autofill run before the native write. `ctx.store` speaks storage names, not the manifest's: the handler's `input` uses authored names (`input.parentId`), while Store writes, filters and rows use the folded column (`insert({ parentid: input.parentId })`, `where: { parentid }`, `row.parentid`); generated Store types show the exact names ([typed queries](../guides/typed-queries.md)). SET cannot change a field-scope column, including ON CONFLICT DO UPDATE. Scoped unique conflict targets gain the owner/field prefix automatically.
 
-Triggers are the only way request data reaches a Procedure: REST and MCP validate the input against the Procedure's schema, then call it. App code may also call a generated Procedure directly (`import run from "../generated/procedures/<name>.js"`, `await run(db, caller, input)`); `requires`, row policy and checks still apply, but input validation does not, so pass only data the app produced or has verified (a cron job, a callback after its signature check). A page that takes user input submits it to the Procedure's REST Trigger; see `docs/examples/purchasing/src/requests-page.ts`.
+Triggers are the only way request data reaches a Procedure: REST and MCP validate the input against the Procedure's schema, then call it. App code may also call a generated Procedure directly (`import run from "../generated/procedures/<name>.js"`, `await run(db, caller, input)`); `requires`, row policy and checks still apply, but input validation does not, so pass only data the app produced or has verified (a cron job, a callback after its signature check). A page that takes user input submits it to the Procedure's REST Trigger; see `node_modules/@aotter/mantle/docs/examples/purchasing/src/requests-page.ts`.

package/docs/handbook/reference/schema.md

@@ -54,7 +54,17 @@ Owner and field columns prefix every unique index in that order. User reads/writ
 
 ## Indexes, checks and search
 
-Indexes are ordered composite scalar/native columns. A paged View's `ORDER BY` must match an index on the base Schema after any fixed equality prefix, ending with `id` as the tiebreak: `ORDER BY createdAt DESC, id DESC` needs `indexes: [[createdAt, id]]` (generation reports `Missing index for ORDER BY ...` otherwise). Required operational fields are NOT NULL; publishing drafts may be incomplete. Store sortable types use indexed/non-null columns, with explicit nullable published_at support.
+Indexes are ordered composite scalar/native columns. A paged View's `ORDER BY` must match an index on the base Schema after any fixed equality prefix ([index prefixes](#index-prefixes-for-paged-views)), ending with `id` as the tiebreak: `ORDER BY created_at DESC, id DESC` needs `indexes: [[createdAt, id]]` (generation reports `Missing index for ORDER BY ...` otherwise). Required operational fields are NOT NULL; publishing drafts may be incomplete. Store sortable types use indexed/non-null columns, with explicit nullable published_at support.
+
+### Index prefixes for paged Views
+
+Only equality fixes an index prefix: `col = input.x`, `col = 'literal'` and an `= auth.uid()` scope or restrict. A user-field term (`region IN auth.user('region')`, as a `scope` or `restrict`) binds a set of values, so it never fixes a prefix, even when the caller holds one value or `{ all: true }`: the statement is prepared for a set, and an `ORDER BY` after that column would read and sort all of the caller's rows on every page. With `scope: "region IN auth.user('region')"`, `indexes: [[region, orderNo, id]]` and `ORDER BY orderNo`, generation refuses the View, names the bounded order and links here. The bounded ways:
+
+- `ORDER BY region, orderNo`, served by the same index: rows come back grouped by region. `region DESC, orderNo DESC` reads it backwards; on PostgreSQL confirm with `EXPLAIN` that no Sort remains. Every column added to the `ORDER BY` must be non-null and nameable in SQL; a `publishing` Schema field other than a user-field scope column can be null, and the `scope` owner column cannot be named, so the refusal then says this order is unavailable.
+- A View input bound with equality, `WHERE region = input.region ORDER BY orderNo`: the input fixes the prefix, and the scope still applies. Every set-bound column before the ordered ones needs its own equality.
+- For `{ all: true }` callers, an index on the equality-fixed columns, then the ordered columns, then `id`: `[orderNo, id]` here, `[tier, orderNo, id]` with `WHERE tier = input.tier`. It is not bounded for scoped callers, who scan the index and filter, and it does not help a View with any `restrict`, which [`{ all: true }` never lifts](view.md#restrict).
+
+Declaring both indexes does not make one View bounded for every caller. System (trusted) reads drop scope terms, so a scope-first index such as `[owner, at]` is not a proved range scan for them.
 
 `uniqueIndexes` accept declared fields only, never native entry columns such as `authorId`. For per-member uniqueness, declare a required string `member` field, write `member: caller.subject` in a handler, and use `uniqueIndexes: [[member, orderNumber]]`; do not take `member` from client input.
 
@@ -68,9 +78,9 @@ The runtime never creates, alters or checks tables. Initial DDL is for an empty
 
 A property marked `readOnly: true` in the JSON Schema is server-maintained (a counter, a total): Admin's generic create stores its `default` whatever the input says, Admin edits ignore it, and only Procedures (or server code through the Store) change it afterwards. JSON Schema defaults are applied by Admin and the Store, not by the database: a SQL Procedure that inserts the row sets the field itself. A root `readOnly: true` makes the whole Schema read-only in Admin.
 
-`fields.<name>.widget/options` select supported controls or extension contributions; `list.primaryField`, columns/cells and enum `filterField` select list presentation; `nav.standalone/parentField` control child navigation; `nav.group/order/hidden` place it in the sidebar ([sidebar](../guides/native-admin.md#sidebar)); panels select record sidebars. Generation validates these against declared fields/indexes and selected extension declarations. JSON Schema root `schema.readOnly: true` disables generic Admin writes, not declared Procedures; `uiSchema.readOnly` is rejected with `SCHEMA_UI_INVALID`. `x-mantle-ref` relates a field to another Schema id or single-field unique field.
+`fields.<name>.widget` selects a built-in control (`textarea`); `list.primaryField`, `list.columns` and enum `filterField` select list presentation; `nav.parentField` chooses the parent a child folds under (required when two or more required `id` references exist) and `nav.standalone` lists the child in the sidebar; `nav.group/order/hidden` place it in the sidebar ([sidebar](../guides/native-admin.md#sidebar)). `list.columns` must not repeat `list.primaryField` or itself (`SCHEMA_UI_INVALID`). Generation validates these against declared fields/indexes. Components that render a field, cell or record aside are not manifest references: they live in `defineAdmin` ([customising Admin](../guides/native-admin.md#customising-admin)), and a manifest that still names one (`widget: <extension>/<contribution>`, `widget` `options`, `list.cells`, `panels`) is refused. JSON Schema root `schema.readOnly: true` disables generic Admin writes, not declared Procedures; `uiSchema.readOnly` is rejected with `SCHEMA_UI_INVALID`. `x-mantle-ref` relates a field to another Schema id or single-field unique field.
 
-See [Admin](../guides/admin-ui.md), [extensions](../guides/admin-extensions.md) and [diagnostics](diagnostics.md).
+See [Admin](../guides/admin-ui.md) and [diagnostics](diagnostics.md).
 
 ### Field scope
 

package/docs/handbook/reference/surface.md

@@ -30,16 +30,36 @@ The generated `validation/views/<name>.ts` and
 also export `query(URLSearchParams)` returning `{ input, limit?, cursor? }`.
 REST and MCP use the same generated checks, with no runtime schema interpreter.
 Supported checks are types/unions and nullable, required/properties/additionalProperties,
-arrays/items and length bounds, enum, local `$defs`/`$ref`, string length/pattern,
-numeric bounds/`multipleOf`, and date/date-time/email. The deliberately permissive
+arrays/items and length bounds, enum, `const`, local `$defs`/`$ref`, string length/pattern,
+numeric bounds/`multipleOf`, and the formats `date`, `date-time`, `email` and `uri`. The deliberately permissive
 email check requires exactly one `@`, non-empty local and domain parts, and no
 whitespace; it does not require a dot, verify deliverability, or implement full
-RFC mailbox syntax. Integers must be safe; fractional
-`multipleOf` uses a 1e-9 quotient tolerance. `const`, `oneOf`, `uniqueItems` and
-object property-count bounds are refused, alongside other unsupported keywords
-and formats. Defaults remain
+RFC mailbox syntax. `uri` means an absolute `http:` or `https:` URL, stricter than
+JSON Schema's any-scheme URI, so `javascript:` and `data:` links fail. Integers must be safe; fractional
+`multipleOf` uses a 1e-9 quotient tolerance. Defaults remain
 annotations and are not inserted into request input.
 
+View and Procedure input objects (not Schemas or outputs) also take three rules
+between their declared properties, each failing with one `INPUT_VALIDATION_FAILED`
+error whose message names the rule:
+
+- `dependentRequired: { weight: [unit] }`: "'unit' is required when 'weight' is
+  present.", at the missing field.
+- `anyOf` whose every branch is exactly `{ required: [...] }`: "At least one of
+  'weight', 'heightCm' is required.", at the object.
+- `if: { properties: { undo: { const: true } }, required: [undo] }` with `then`
+  and/or `else` each exactly `{ required: [...] }`: "'item' is required unless
+  'undo' is true.", at the missing field. `if` must list its field in `required`:
+  otherwise an absent field would satisfy it.
+
+Any other `anyOf`/`if`/`then`/`else`, `oneOf`, `uniqueItems`, object property-count
+bounds and other keywords and formats are refused at generation. The rules only
+validate: types, SQL binds and Admin forms keep the declared fields, and Admin
+shows the server's error at its field. `describe` keeps them as written; MCP and
+WebMCP tools advertise the schema without them and append each rule's sentence to
+the tool description, since some model APIs refuse these keywords in a tool's
+input schema. [Trigger](trigger.md#input-rules) has an example.
+
 Native `paged/views/<name>.ts` has a default export, callable as
 `page(db, caller, input, { limit?, cursor? })` after importing it as `page`,
 answering `{ rows, nextCursor? }`.
@@ -56,10 +76,18 @@ their contracts. Native integer bigint cursor keys are serialized separately.
 REST/MCP use separate `paged/wire/views/<name>.ts` SQL when declared integers
 require exact transport projections. Web pages and internal paged Views keep
 driver-native rows. Internal paging creates no public route/tool.
-Authored SQL `LIMIT` caps each page, up to 500, rather than the whole cursor walk.
+Authored SQL `LIMIT` bounds the complete ordered row set, including across cursor pages.
+Use `limit` in the paging options to choose each page size (up to 500); it does not expand the View's declared result set.
+An MCP View page keeps the `limit` of 1 to 500 but holds only as many of those rows
+as fit 60,000 characters of JSON, so a result stays under host truncation limits. It
+is cut before the first row that overflows and its next cursor resumes at that row.
+A single row over the budget is returned alone with the cursor, and a View without an
+order stays one whole page; a page still over the budget carries a notice that hosts
+may truncate it.
 A pageable Schema View has a complete NOT NULL scalar tuple ending in the
 compiler's `id` tiebreak. Its ordered columns must match an index after fixed
-equality prefixes (including caller scope); multiple columns and mixed directions
+equality prefixes; a user-field `IN` scope or restrict is not one (see
+[index prefixes](schema.md#index-prefixes-for-paged-views)); multiple columns and mixed directions
 retain the authored order. CTE projections preserve the proof; joins must have a
 proved singleton side, or equality on the joined Schema's `id` or single-field
 unique key, so the base id cannot fan out. LEFT JOIN accepts nullable or missing
@@ -132,7 +160,10 @@ const tags = await site.head(request, env); // HTML string, empty for unknown/mi
 ```
 
 Page parameter names must exactly match the View's declared input properties.
-Page and list Views must return the page parameters; list Views must accept empty input. Markdown
+Page and list Views must return the page parameters; list Views must accept empty input: no
+`required`, no root `anyOf`, `enum` or `const`, no `else` rule, and a root `type`, when given, that includes `object`.
+These conditions also apply to each schema a root `$ref` chain reaches, and an unresolved or cyclic chain fails them.
+`web()` throws a `TypeError` for any other list View. Markdown
 must name a textual output column. HTML remains application-owned.
 
 `/llms.txt` and `/sitemap.xml` traverse each list's `nextCursor`; `.md` and head
@@ -169,6 +200,19 @@ transport loads on the first matching request. Pass `handlers` when ref
 Procedures are declared, as for REST. Admin tools are listed only on the admin
 endpoint, and publishing visibility belongs to the generated SQL.
 
+`apps.public` and `apps.admin` accept a `McpAppsSource` or an array mixing static
+contributors with async `({ env, request }) => McpApps` factories. Static resources
+are checked once at construction; factories resolve only after the endpoint's
+origin and caller gates, and their resource identities and ownership are checked
+on each request even when the tool names are unchanged.
+
+Discovery is caller-independent by default (ADR-0014); listing a tool grants no
+execution authority. Configure `authorize` to filter `tools/list` and the tool
+names supplied to resource HTML loaders: that mode also excludes tools refused
+by declared identity, scope and `check` requirements. Without `authorize`, the
+complete endpoint catalogue is not a permission-filtered catalogue. Operation
+validation, guards and credential checks still apply to calls.
+
 The app resolves bearer tokens with `resolveCaller(request, auth, { audience:
 new URL('/mcp', request.url).href })` (both surfaces use `<origin>/mcp`). The app
 must also mount Better Auth's `/.well-known/oauth-protected-resource/mcp`
@@ -176,7 +220,8 @@ metadata route. Auth challenges point to that route. Presented bearer credential
 need the `mcp` scope; cookie sessions use the same-origin mutation checks.
 
 Generation emits `mcp.ts` only for a non-internal View or MCP Trigger. These
-surfaces typecheck without the `@modelcontextprotocol/server` 2.1.0 peer.
+surfaces typecheck without the optional `@modelcontextprotocol/server` peer;
+install the exact version declared in the installed SDK's `peerDependencies`.
 The peer loads by dynamic import on the first matching `/mcp` request; if
 missing, that request fails at runtime. Publishing alone does not select MCP;
 on a selected
@@ -207,15 +252,42 @@ as an explicit option.
 ### MCP catalogue and callbacks
 
 `mcp({ db, caller, handlers?, locale?, instructions?, serverInfo?, requiredScopes?,
-resourceMetadata?, onObservation?, onRefusal? })` keeps the SDK behind its first
+resourceMetadata?, allowedOrigins?, onObservation?, onRefusal? })` keeps the SDK behind its first
 request. Locale defaults to `en`; localized titles/descriptions fall back to
-English, then their first entry. Views advertise `readOnlyHint`; Procedures use
-their declared MCP annotations. `instructions` is returned by initialize.
+English, then their first entry. Tools carry the [tool hints](procedure.md#mcp-tool-hints). `instructions` is returned by initialize.
 The scope floor defaults to `["mcp"]` for every credential except cookie sessions;
 `requiredScopes: []` disables that floor. An anonymous closed surface challenges
 from initialize, and every call in a batch is checked before any call runs.
 `resourceMetadata` overrides the challenge URL for reverse proxies.
 
+Both endpoints answer a request without `Origin`, which is what server-side MCP
+clients send; a bearer credential needs none. A cookie session is ambient authority, so
+`checkOrigin` also guards it: on a request that is not GET, HEAD or OPTIONS, at least one of
+`Origin` and `Sec-Fetch-Site` must be present and every present one must agree (`Origin` equal
+to the request's own origin; `Sec-Fetch-Site` `same-origin` or `none`), else `AUTH_DENIED` at
+`request:origin`. On MCP it runs only for a tool call that executes (not a read-only call from an
+App host), not for initialize or `tools/list`; `allowedOrigins` does not lift it. A present `Origin` marks a browser: it must name a loopback host
+(`localhost`, `127.0.0.1`, `[::1]`, any port) or an `allowedOrigins` entry, else
+403 before authentication on every credential; `Origin: null` is refused. The
+site's own origin is not implied, because a DNS-rebinding page sends an `Origin`
+equal to the `Host` it rebound, so a browser client served from your deployed
+site lists that origin: `allowedOrigins: ["https://app.example"]`. Entries are
+compared by hostname as the official SDK does (not scheme or port); each is a
+full origin (`https://console.example`) or the SDK's bare host
+(`console.example`, `localhost:8787`), and anything else, such as a path, throws
+when `mcp(...)` is configured; so does a wildcard such as `*` or
+`https://*.example.com`, since entries are matched by exact hostname. `Host` is
+not checked. Cookie writes also need the full same-origin check.
+
+`/mcp` sends no CORS headers. `allowedOrigins` therefore serves pages on the
+same origin as the endpoint, or clients behind a proxy that forwards their
+`Origin`; a browser client on another origin also needs the app to answer
+preflight and add CORS headers itself. Under `wrangler dev` with `routes` or
+`dev.host`, Miniflare rewrites an `Origin` equal to the request's own origin to
+the route or `dev.host` origin, and a DNS-rebinding request always has that
+shape. Listing that host would admit rebinding against the local server, so keep
+the route and `dev.host` hosts out of `allowedOrigins` in local development.
+
 `onObservation` receives request refusals and invocation attempt/completion
 metadata, including duration and outcome. Its Caller and scopes are frozen copies.
 `onRefusal` receives credential/origin refusals. Neither callback receives request
@@ -232,6 +304,44 @@ with an output schema they omit `structuredContent` to avoid validating an error
 against a success schema. Without one they also expose diagnostic structured
 content. MCP adds no prompts or non-UI resources.
 
+### Tool versions
+
+Each generated tool (MCP, media, publishing and WebMCP) carries `version`, a
+short hash computed by `mantle generate` of the definition as listed: name,
+title, description without the marker, input schema (a View tool's with its
+`limit` and `cursor` paging properties), output schema and annotations. A
+localized title or description is hashed with all its locales. The description
+ends with `(tool version <version>)`, so an unchanged tool keeps a
+byte-identical description across deploys.
+
+MCP results of a call that reaches the tool add a second text block,
+`tool version <version>`; failures other than authorization refusals append
+`; input schema <JSON>`, the input schema the tool is listed with.
+`structuredContent` is unchanged. A `tools/call` naming a tool the endpoint
+serves but the caller may not use is answered by the authentication or
+authorization challenge (HTTP 401 or 403) before the SDK's transport and
+request checks, even though that caller's `tools/list` omits the tool. A
+`tools/call` naming a tool not in the endpoint's catalogue, in a batch or not
+and from a host caller too, is answered with JSON-RPC error `-32602` and the
+message
+`No tool named "<name>" exists in the current catalogue (catalogue version <serverInfo.version>).`
+For such a name the SDK's transport and request checks (headers, protocol
+version, JSON-RPC shape) answer first, so a malformed request gets the same
+refusal as one naming a served tool the caller may use.
+Unless `serverInfo.version` is given, the kernel's `mcp()` sets it to
+a hash of the `surface:name:version` of every tool the endpoint serves, before
+per-caller filtering, so `/mcp` and `/mcp/admin` each report their own catalogue
+version, and it changes when a generated tool's definition changes or a tool is
+added or removed, however the tools are wired.
+
+`POST /admin/api/webmcp/{tool}` returns `{ output, version }`. A refusal's
+diagnostic adds `toolVersion`, and `inputSchema` unless it is an authorization
+refusal; internal errors and refusals before the call carry neither. Admin's
+WebMCP results repeat these as the same text block MCP adds. The navigation
+tools `admin_get_context` and `admin_navigate` have no version. Tools an
+application adds itself carry a version only if it sets one. Why: [MCP and
+agents](../concepts/mcp-and-agents.md#when-a-host-shows-old-tools).
+
 ### Declared View scalars on the wire
 
 REST and MCP View pages expose declared JSON columns as JSON values and declared

package/docs/handbook/reference/trigger.md

@@ -28,8 +28,41 @@ spec:
 
 The target names a declared Procedure. `http` sources use POST/PUT/PATCH/DELETE and an `/api/` path. Path parameters bind to corresponding declared input fields and override JSON-body values. The generated REST module retains the Procedure's authorization and validates boundary input.
 
-An MCP source is `{ kind: mcp, surface: public }` or admin. The selected MCP module exposes the Procedure as a snake-case tool with its declared description/annotations and requires checks.
+An MCP source is `{ kind: mcp, surface: public }` or admin. The selected MCP module exposes the Procedure as a snake-case tool with its description, [tool hints](procedure.md#mcp-tool-hints) and requires checks.
 
 Lifecycle and schedule sources are rejected at generation with `GENERATE_UNSUPPORTED`, including disabled schedules. Use an app-owned handler or scheduler. For signed webhooks, verify the original raw Request in the app and call a generated Procedure with validated input; do not route it through a JSON boundary before signature verification.
 
+## Input rules
+
+The admin MCP tool below lists `reason` and `closed` without the rules, and its
+description ends "'reason' is required when 'closed' is false."; a call with
+`closed: false` and no `reason` fails with `INPUT_VALIDATION_FAILED` at
+`procedures/set-ticket/input/reason` (the error path is
+`procedures/<name>/input/<field>`). See [surface contracts](surface.md) for the
+supported rules.
+
+```yaml
+apiVersion: cms.mantle.aotter.net/v2
+kind: Procedure
+metadata: { name: set-ticket }
+spec:
+  description: Open or close a ticket.
+  input:
+    type: object
+    required: [id, closed]
+    properties: { id: { type: string }, closed: { type: boolean }, reason: { type: string, maxLength: 200 } }
+    additionalProperties: false
+    if: { properties: { closed: { const: false } }, required: [closed] }
+    then: { required: [reason] }
+  output: { type: object }
+  handler: { sql: 'UPDATE tickets SET closed=input.closed WHERE id=input.id RETURNING id,closed' }
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Trigger
+metadata: { name: set-ticket-mcp }
+spec:
+  source: { kind: mcp, surface: admin }
+  target: { procedure: set-ticket }
+```
+
 See [surfaces](surface.md) for mounted paths, error mapping and origin checks.

package/docs/handbook/reference/view.md

@@ -29,7 +29,7 @@ Store keeps `find`/`first` search and `count`. `count` scans every matching row;
 
 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.
+Bare `views/<encoded-name>.ts` returns row arrays. Proved pageable exposed/internal Views also receive native `paged/views/*`, returning `{ rows, nextCursor? }`. Selected REST/MCP boundaries use separate `paged/wire/views/*` SQL when declared integers require exact transport projections; bare modules also export `WireRow`. Indexed ordering after fixed equality prefixes ([index prefixes](schema.md#index-prefixes-for-paged-views)), non-null typed keys, complete groups and singleton joins/lookups are checked at generation. Unsupported internal paging retains its bare View; exposure requires a supported page contract. Aggregates still scan/group their sources: inspect EXPLAIN.
 
 Publishing Schema fields may be NULL in drafts even when required, so public View paging cannot order by them. `published_at` is accepted by Store ordering but rejected as a View paging key. Use `ORDER BY id`, or keep the business date in an operational Schema as an indexed, required non-null field.
 

package/docs/handbook/releases/index.md

@@ -17,6 +17,78 @@ Pin every package you use to the same exact version and upgrade them together.
 
 ## 0.2.0 — in preparation
 
+### Upgrading to 0.2.0-alpha.8
+
+Pin every selected `@aotter/mantle`, `@aotter/mantle-ui` and
+`@aotter/mantle-admin` dependency to `0.2.0-alpha.8`, refresh the lockfile,
+then regenerate and check the application's owned artifacts. Keep existing
+production migrations application-owned; generated initial DDL is for an empty
+database. This alpha includes breaking Admin authoring and paging changes.
+
+1. **Build output and host configuration.** `mantle bundle` writes server
+   modules to `dist/worker` and static files to `dist/client`, including
+   `dist/client/admin`. Rerun `mantle generate` with the application's `--entry`
+   and check the resulting Wrangler `main`, `base_dir`, asset directory and
+   build command. See [CLI and generated ownership](../start/project-and-cli.md).
+2. **Application-owned React.** Install React and React DOM in the application
+   at the same exact version (the examples use `19.3.0`). Admin takes them as
+   peers; a mismatched pair fails its build.
+3. **Replace extensions with application composition.** Move to
+   `defineAdmin(meta, { nav, pages, home, components, plugins, mcp })` in
+   `src/admin.tsx`. Remove `--admin-extensions`, `adminExtensions`,
+   `defineAdminExtension`, extension handlers and removed manifest widget,
+   `list.cells` and panel references. `navGroups` becomes `nav.groups`.
+   Use the [Admin migration table](../guides/native-admin.md#migrating-from-admin-extensions)
+   rather than carrying the former registration layer forward.
+4. **Build the MCP App with the application.** The prebuilt
+   `@aotter/mantle-admin/mcp-app` / `mantleAppHtml` export is gone. Use
+   `adminMcpApps({ catalogue: mcpAppCatalogues.admin })` with the generated
+   catalogue; it reads the built asset. Declare CSP once in `defineAdmin`.
+   The default resource URI hashes the built HTML, catalogue and metadata;
+   custom HTML functions need an explicit immutable URI. Load interactive
+   host HTML through authenticated `resources/read`, which embeds its
+   catalogue. See [MCP Apps](../guides/mcp-apps.md).
+5. **Run the generated compatibility check.** Run
+   `node --test generated/admin-mcp-app.check.mjs` after building. Install
+   the optional `playwright-core` peer and a browser, or set
+   `MANTLE_TEST_CHROMIUM`; a missing browser fails rather than skips. This
+   checks rendering with a synthetic catalogue, not application authorization
+   or completion of a Procedure action.
+6. **Keep the host graph safe.** The MCP build rejects `/admin/api` access,
+   cookies and undeclared remote loads. Its entry must be readable in Node.
+   An optional `src/admin.mcp.tsx` (or `buildAdmin({ mcpEntry })`) isolates
+   browser-only integrations; both roots can reuse one host-safe config,
+   components and CSS. Without it the whole shared entry graph is checked.
+7. **Distinguish total bounds from page sizes.** Authored SQL `LIMIT` now
+   bounds the complete ordered result set across cursor pages, including web
+   indexes. Use paging `options.limit` for page size; remove an authored limit
+   only if it was incorrectly being used as a page-size setting. MCP accepts
+   sizes of 1–500, but a response budget can return fewer rows: append pages
+   until `nextCursor` is absent, not until a short page. See
+   [View paging](../reference/surface.md).
+8. **Install build dependencies where the build runs.** Wrangler dev/deploy
+   runs its configured build command, so that environment needs
+   `node_modules`. The resulting built server/assets do not read
+   `node_modules` when served. See the
+   [application shell](../../examples/app-shell/README.md).
+
+Record/collection cells, inputs, record actions, asides and `RecordView` are
+now truthfully browser-only (`surface: "browser"`); remove unreachable MCP
+branches. View cells remain `both`, and pages opt in through `pages[].mcp`.
+A Procedure action's input is distinct from a collection record input: use a
+Procedure target and MCP Trigger with the View's unchanged `id` and observed
+`version` for native row actions. [Shared custom-page headers](../guides/mcp-apps.md#customising-admin-for-mcp-hosts)
+can compose localized title, description and actions on both surfaces; omit the
+option to keep prior behavior, or use `header: false` for an element-owned heading.
+
+OAuth issuer verification now follows Better Auth's normalized URL while
+preserving explicit issuer/JWKS settings. Cloudflare OAuth configurations need
+`global_fetch_strictly_public` for public JWKS fetches; generated settings and
+the official examples retain it. Native MCP Apps use the official ext-apps
+client. Browser Admin now displays a localized explicit reload action when a
+lazy page fails, rather than going blank; it does not reload automatically or
+replay writes.
+
 ### Native SDK migration (alpha.7)
 
 Alpha.7 replaces the previous Core runtime and generated service contract.
@@ -32,7 +104,7 @@ Existing alpha.6 applications require a source migration:
   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.
+- Install the separate `@aotter/mantle-admin` package when selecting Admin, with `react` and `react-dom` in the application pinned to one identical exact version (Admin no longer installs them).
   Compose its [native bindings](../guides/native-admin.md) in the application.
   Bare queries retain driver-native values; selected REST/MCP/Admin boundaries
   own validation and declared-column wire conversion.
@@ -40,7 +112,7 @@ Existing alpha.6 applications require a source migration:
   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
+The [reference Worker](https://github.com/aotter/mantle/tree/v0.2.0-alpha.8/docs/examples/reference-service) and
 [app shell](../../examples/app-shell/) demonstrate the current composition.
 The following earlier-alpha notes are historical; the current handbook and
 the native migration above supersede their runtime and CLI instructions.

package/docs/handbook/start/overview.md

@@ -9,7 +9,7 @@ Mantle compiles a closed v2 manifest into native SQL and typed TypeScript. The a
 | --- | --- |
 | `@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 |
+| `@aotter/mantle-admin` | Admin server, app-built SPA library, preview and MCP App; SDK peer |
 
 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).
 

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

@@ -10,13 +10,13 @@ description: Generation targets, CLI options and ownership of native application
 | `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 |
+| `dist/` | Disposable bundle output (`dist/worker`, `dist/client`); do not commit |
 
 ## Commands
 
 ```sh
 mantle generate <target> <output-directory> <manifest>... [options]
-mantle bundle <entry> <outdir>
+mantle bundle <entry> <outdir> [--assets <dir>]
 ```
 
 | Target | Dialect | Handle |
@@ -34,24 +34,24 @@ Other handles may adapt to the same [structural driver contracts](../guides/adap
 | `--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. |
+| `--outdir <path>` | Bundle output; default `dist`. The Worker goes to `<outdir>/worker`. Keep separate from source/generated files. |
+| `--assets <path>` | With `--admin`: the static assets directory `mantle bundle` builds Admin into (`<assets>/admin`); default `<outdir>/client`. Written to Wrangler's `assets.directory`, and to the build command when not the default. |
 
 ## Outputs
 
-`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
+`generated/.mantle-inputs.json` records the Mantle version, the target, and a hash of every input the run read (manifests and the
+`--auth` and `--site` 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`.
 
-`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.
+`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`, `admin-client.ts` (browser-side types and hooks for `admin.tsx`) and `admin/*` require `--admin`. Auth and site are explicit options.
 
 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.
 
 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.
 
-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).
+On Workers, generation configures `mantle bundle` as Wrangler's build command. It emits minified split ESM into `<outdir>/worker` with a startup guard for eager Better Auth imports and for Admin's browser code (`@aotter/mantle-admin/app` and `/hooks`, which `generated/admin-client.ts` imports; they belong to `admin.tsx`). When the Worker imports `@aotter/mantle-admin/server`, it also builds Admin with Vite into `<assets>/admin` (`--assets`, default `<outdir>/client`), from `admin.tsx` beside the Worker entry or Admin's built-in entry; `src/admin.ts` is not an entry. The assets directory must not overlap the Worker directory, and neither the outdir nor the assets directory may be the working directory or contain the Worker entry. The built-in entry is not rebuilt while the installed `@aotter/mantle-admin` keeps its path and version and its direct dependencies and its `react`/`react-dom` peers keep theirs; an `admin.tsx` entry builds every time. The build needs no install scripts (`npm ci --ignore-scripts` works). A `package-lock.json` made on one OS can lack the native build binaries (rolldown, `@tailwindcss/oxide`, lightningcss) that npm installs per platform from `optionalDependencies`, so a lockfile made on macOS can fail the build on a Linux host; create the lockfile on the build platform or use pnpm. `wrangler dev` and `wrangler deploy` run that build command, so they need `node_modules`. The built output (`<outdir>/worker`, `<assets>`) never reads it, so a pipeline that deletes `node_modules` must run `wrangler deploy` first. On Bun, the app owns `Bun.serve`, its Database/SQL pool and scheduler; Bun runs the server as TypeScript, so for a `bun-*` target recorded in `.mantle-inputs.json`, `mantle bundle src/server.ts dist` skips the Worker bundle and builds only Admin, into `dist/client/admin` (read with `bunAdminAssets("dist/client/admin")`, adapted for `adminShell` as in service composition). See [service composition](../cloudflare/service-entry.md).

package/docs/handbook/start/quickstart-worker.md

@@ -3,7 +3,7 @@ description: Generate a small native D1 service and mount an application-owned W
 ---
 # Quickstart: a service on Workers
 
-Create an application outside the SDK checkout. Install an exact released `@aotter/mantle` version, TypeScript, Wrangler and Cloudflare Worker types. Read that installed version's handbook; this page describes the native 0.2.0 contract.
+Create an application outside the SDK checkout. Install an exact released `@aotter/mantle` version, TypeScript, Wrangler and Cloudflare Worker types; `node_modules/@aotter/mantle/docs/examples/app-shell/package.json` lists the versions this release is tested with. Read that installed version's handbook; this page describes the native 0.2.0 contract.
 
 Save `manifests/tickets.yaml`:
 

package/docs/skills/develop/SKILL.md

@@ -18,7 +18,7 @@ Follow the installed [native generation and service workflow](../../handbook/clo
 with its [native contract](../../handbook/guides/native-execution.md) and [supported declarations](../../handbook/reference/features.md). Commit
 all generated output, run the same generation command with `--check`, and keep
 bundle `dist/` untracked. The app owns its verified Caller, handlers and native
-resources; Better Auth’s admin plugin `adminRoles` defines the admin layer (default `["admin"]`); `ctx.admin` accepts open role names.
+resources; Better Auth’s admin plugin `adminRoles` defines the admin layer (default `["admin"]`); `ctx.admin` takes no role list ([authorization](../../handbook/cloudflare/authentication.md)).
 
 Use the native Store/query/surface entries and app-owned fetch from the service composition guide.
 Keep optional modules out of unused entry imports and auth dynamically loaded.
@@ -41,8 +41,9 @@ version? }` selects row actions and binds the row id / reviewed OCC version to
 the named inputs. Other admin operations appear under Operations in the sidebar.
 Keep state conditions in the SQL WHERE: simple AND equality/IN literals become
 row-menu hints, while the Procedure remains the authority. Required-ref child
-collections fold under their parent's sidebar group; use Schema
-`uiSchema.nav.standalone: true` for a top-level entry.
+collections fold under their parent's sidebar group; with two or more required
+`id` refs, set Schema `uiSchema.nav.parentField` to the parent's ref (generate
+refuses otherwise); use `uiSchema.nav.standalone: true` for a top-level entry.
 
 ## Database changes
 

package/docs/skills/integrate/SKILL.md

@@ -18,7 +18,7 @@ Follow the installed [native generation and service workflow](../../handbook/clo
 with its [native contract](../../handbook/guides/native-execution.md) and [supported declarations](../../handbook/reference/features.md). Commit
 all generated output, run the same generation command with `--check`, and keep
 bundle `dist/` untracked. The app owns its verified Caller, handlers and native
-resources; Better Auth’s admin plugin `adminRoles` defines the admin layer (default `["admin"]`); `ctx.admin` accepts open role names.
+resources; Better Auth’s admin plugin `adminRoles` defines the admin layer (default `["admin"]`); `ctx.admin` takes no role list ([authorization](../../handbook/cloudflare/authentication.md)).
 
 Keep the application router, database/pool, identity and frontend. Replace
 Core consumers explicitly and compose only selected generated entries. Resolve

package/docs/skills/media-gc/SKILL.md

@@ -41,11 +41,13 @@ objects approved by the user.
 
 `POST /admin/api/media/uploads` issues presigned PUT URLs that expire after 15
 minutes, for keys under `uploads/<purpose>/<group>/<role>.<ext>`. Commit
-copies each checked object to `<purpose>/<group>/<role>.<ext>` (with
-`committedAt` metadata) and deletes the upload key; a rejected group's upload
-keys are deleted. So an object still under `uploads/` long after its URL
-expired belongs to an upload that was never committed, and nothing can commit
-it any more. Objects outside `uploads/` are committed media: never candidates.
+copies each checked object to `committed/<group>/<attempt>/<role>.<ext>` (with
+`committedAt` metadata); the attempt UUID isolates concurrent commits. Upload
+keys are removed after the database commit succeeds, or when a group is
+rejected. An old upload key may also be leftover cleanup from a successful or
+uncertain commit: it is not evidence that the media row is absent. Once expired,
+it cannot create a new asset. Objects outside `uploads/` are never candidates;
+reconcile attempt copies separately with live database references.
 
 ## Audit
 

package/docs/skills/provision/SKILL.md

@@ -19,7 +19,7 @@ Follow the installed [native generation and service workflow](../../handbook/clo
 with its [native contract](../../handbook/guides/native-execution.md) and [supported declarations](../../handbook/reference/features.md). Commit
 all generated output, run the same generation command with `--check`, and keep
 bundle `dist/` untracked. The app owns its verified Caller, handlers and native
-resources; Better Auth’s admin plugin `adminRoles` defines the admin layer (default `["admin"]`); `ctx.admin` accepts open role names.
+resources; Better Auth’s admin plugin `adminRoles` defines the admin layer (default `["admin"]`); `ctx.admin` takes no role list ([authorization](../../handbook/cloudflare/authentication.md)).
 
 Deploy/create resources only within the user's authorization; reuse configured
 host resources. Apply reviewed and rehearsed migrations before routing traffic;
@@ -27,6 +27,9 @@ imports/first requests perform no DDL or schema checks. Keep auth dynamic, produ
 secrets in the host store, trusted HTTPS origin and verified bootstrap rule,
 production email and selected media wiring. Configure Admin ASSETS worker-first
 as in [Workers assets and secrets](../../handbook/cloudflare/service-entry.md#workers-assets-and-secrets). Hyperdrive caching stays off; PG settings are deployment-owned.
+Keep the Workers [public-fetch flags](../../handbook/cloudflare/deploy-and-operate.md#public-fetch-routing),
+including environment overrides; verify deployed MCP with a real OAuth bearer
+(`initialize` and `tools/list`), not only a browser session cookie.
 Bun uses native Database/SQL, an app server and scheduler. Verify admin sign-in
 (role admin), denied access, public reads, a persisted write, MCP and selected UI.
 Report artifact/resources/checks and keep rollback artifacts.

package/docs/skills/update/SKILL.md

@@ -18,7 +18,7 @@ Follow the installed [native generation and service workflow](../../handbook/clo
 with its [native contract](../../handbook/guides/native-execution.md) and [supported declarations](../../handbook/reference/features.md). Commit
 all generated output, run the same generation command with `--check`, and keep
 bundle `dist/` untracked. The app owns its verified Caller, handlers and native
-resources; Better Auth’s admin plugin `adminRoles` defines the admin layer (default `["admin"]`); `ctx.admin` accepts open role names.
+resources; Better Auth’s admin plugin `adminRoles` defines the admin layer (default `["admin"]`); `ctx.admin` takes no role list ([authorization](../../handbook/cloudflare/authentication.md)).
 
 Pin exact target SDK/peer versions and read its release notes and Admin asset
 installation instructions. Core-to-native replaces app imports/wiring; it is not

package/docs/upgrade-0.1-to-0.2.md

@@ -13,12 +13,12 @@ The remainder describes the earlier alpha contract for historical reference.
 
 No codemod, and no in-place upgrade of a 0.1.x database. A coding agent moves
 one project by hand with this guide. When it and
-[ADR-0032](https://github.com/aotter/mantle/blob/develop/docs/adr/0032-store-centric-core-and-service-contract.md),
-[ADR-0033](https://github.com/aotter/mantle/blob/develop/docs/adr/0033-storage-converges-to-the-plan.md),
-[ADR-0034](https://github.com/aotter/mantle/blob/develop/docs/adr/0034-store-is-authored-as-sql.md),
-[ADR-0035](https://github.com/aotter/mantle/blob/develop/docs/adr/0035-sql-dialects.md),
-[ADR-0036](https://github.com/aotter/mantle/blob/develop/docs/adr/0036-host-and-dialect.md) or
-[ADR-0038](https://github.com/aotter/mantle/blob/develop/docs/adr/0038-bun-native-host.md) disagree, the ADR wins.
+[ADR-0032](https://github.com/aotter/mantle/blob/v0.2.0-alpha.7/docs/adr/0032-store-centric-core-and-service-contract.md),
+[ADR-0033](https://github.com/aotter/mantle/blob/v0.2.0-alpha.7/docs/adr/0033-storage-converges-to-the-plan.md),
+[ADR-0034](https://github.com/aotter/mantle/blob/v0.2.0-alpha.7/docs/adr/0034-store-is-authored-as-sql.md),
+[ADR-0035](https://github.com/aotter/mantle/blob/v0.2.0-alpha.7/docs/adr/0035-sql-dialects.md),
+[ADR-0036](https://github.com/aotter/mantle/blob/v0.2.0-alpha.7/docs/adr/0036-host-and-dialect.md) or
+[ADR-0038](https://github.com/aotter/mantle/blob/v0.2.0-alpha.7/docs/adr/0038-bun-native-host.md) disagree, the ADR wins.
 
 ## Rules
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aotter/mantle",
-  "version": "0.2.0-alpha.7",
+  "version": "0.2.0-alpha.8",
   "type": "module",
   "sideEffects": false,
   "engines": {
@@ -92,6 +92,7 @@
     }
   },
   "devDependencies": {
+    "@modelcontextprotocol/client": "2.1.0",
     "@modelcontextprotocol/server": "2.2.0",
     "@better-auth/core": "1.7.7",
     "@better-auth/oauth-provider": "1.7.7",