@aotter/mantle 0.1.5-alpha.1 → 0.2.0-alpha.10

package/docs/handbook/reference/surface.md

@@ -1,205 +1,396 @@
----
-description: Every surface Mantle exposes — Worker HTTP routes and their cache class, the MCP tool catalog, CLI flags, the generated module, packages and versions.
----
-# HTTP, MCP, CLI and package surface
-
-What a Mantle deployment exposes, in one place: the routes the conventional Cloudflare Worker owns, the MCP tools it advertises, the commands the package installs, the module `mantle generate` writes, and which package holds what. Route behaviour follows [Conventional Worker](../cloudflare/conventional-worker.md); this page is the index.
-
-## HTTP routes
-
-Every table below describes the conventional Cloudflare Worker assembled by `createMantleWorker`. The **cache** column is the class the final `applyCachePolicy` boundary assigns. Only an anonymous `200` `GET`/`HEAD` response that explicitly declares `public` plus a shared freshness lifetime stays cacheable, and it then varies on `Cookie` and `Authorization`; the request must carry neither header and the response must set no cookie. Everything else becomes `private, no-store` with any CDN cache override stripped.
-
-### Manifest routes
-
-| Route | Response | Cache |
-|---|---|---|
-| `GET /api/views` | `{ ok: true, data: [ { name, title?, description, inputSchema } ] }` — one descriptor per public View. | `private, no-store` |
-| `GET /api/views/<name>?page=&show=` | `{ ok: true, data: { rows, page, show, hasMore } }`. One route per View declaring `surface: public`. Query values are coerced against `params`; a bad value is `400`. | `private, no-store`, or the View's `cache.sharedMaxAge` for an anonymous eligible response |
-| `<METHOD> <path>` | Every manifest HTTP Trigger, at its declared `POST`, `PUT`, `PATCH` or `DELETE` and path under `/api/`. The JSON body must be an object. Success is `{ ok: true, data: … }`. | `private, no-store` |
-
-Staff Views are not mounted here; they live under `/admin/api/views/<name>`.
-
-### Admin
-
-All `/admin/api/*` routes require a staff session, carry a 1 MiB JSON body limit, and are `private, no-store`.
-
-| Route | Response |
-|---|---|
-| `GET /admin`, `/admin/`, `/admin/sign-in`, `/admin/c/:collection`, `/admin/c/:collection/:id`, `/admin/media`, `/admin/preferences`, `/admin/connected-apps`, `/admin/settings`, `/admin/staff`, `/admin/members`, `/admin/ops`, `/admin/dev`, `/admin/dev/model`, `/admin/dev/logic`, `/admin/dev/docs`, `/admin/views/:name` | The Admin SPA shell, read from `/_mantle/admin/index.html` through the assets binding. `503` with an explanatory body when the bundle is missing. |
-| `GET /admin/api/views/<name>` | Staff execution of any declared View, public or staff, with Admin search and filtering applied before pagination. |
-| `GET /admin/api/views/<name>/export` | The same query as CSV, covering every matching row rather than one page. |
-| `GET /admin/api/views-manifest` | `{ views: … }` — the View manifest projection the SPA renders from. |
-| `GET /admin/api/operations` | `{ operations: [ { name, title, description, input, uiSchema, triggers, rowBindings } ] }`, filtered per caller by re-evaluating each Procedure's `requires.auth.all`. |
-| `POST /admin/api/operations/:name` | Invokes a staff-operable Procedure through the same use case the staff MCP surface uses. `404` when the name is not staff-operable or when the caller's `requires.auth.all` predicates exclude it — the same filter the listing applies, so names cannot be probed. |
-| `GET /admin/api/me`, `/collections`, `/collections/:name/statistics`, `/entries`, `/entries/export`, `/entries/:id`, `/site` | Session, catalog and entry reads. Entry detail requires `?collection=<schema>`. |
-| `POST /admin/api/entries`, `PATCH /admin/api/entries/:id` | Create and edit. Entry mutation routes require `?collection=<schema>`; contributors are limited to drafts on publishing Schemas. |
-| `POST /admin/api/entries/:id/publish`, `/unpublish`, `DELETE /admin/api/entries/:id` | Lifecycle. Requires `?collection=<schema>` and editor or above. |
-| `POST /admin/api/media/uploads`, `POST /admin/api/media/uploads/:uploadGroupId/commit`, `GET /admin/api/media`, `GET`, `PATCH` and `DELETE /admin/api/media/:id` | Media lifecycle. Editor or above. |
-| `GET /admin/api/staff`, `PATCH /admin/api/staff/:id/role`, `POST /admin/api/staff/invitations`, `DELETE /admin/api/staff/invitations/:id`, `GET /admin/api/developer-console`, `GET` and `PATCH /admin/api/site-settings` | Owner only. |
-| `GET /admin/api/members` | Editor or above. |
-
-`/_mantle/*` holds the static Admin bundle. It is served by the Worker's static-assets layer from `public/_mantle/admin/`, which `mantle generate` syncs when `@aotter/mantle-admin-ui` is installed. The Worker registers no route there; the prefix is reserved so extensions cannot claim it.
-
-### Auth, OAuth and MCP
-
-| Route | Response | Cache |
-|---|---|---|
-| `GET /api/auth/methods` | `{ methods }` — the registered sign-in method kinds, no secrets. Explicitly `no-store` so a method change cannot be served stale. | `private, no-store` |
-| `ALL /api/auth/*` | Better Auth: sign-in, callback, session, magic link, OTP. `/api/auth` is the default base path. | `private, no-store` |
-| `ALL /api/auth/oauth2/*` | The site's OAuth provider endpoints, including consent. | `private, no-store` |
-| `ALL /.well-known/oauth-authorization-server/*`, `/.well-known/oauth-protected-resource`, `/.well-known/oauth-protected-resource/*` | RFC 8414 and RFC 9728 discovery metadata, registered explicitly so no catch-all can swallow them. `/.well-known/oauth-protected-resource/mcp` is the resource metadata the MCP `WWW-Authenticate` challenge points at. | `private, no-store` |
-| `ALL /oauth/*` | Consent and connected-apps pages: `/oauth/consent`, `/oauth/consent/data`, `/oauth/consents`, `/oauth/consents/data`, `/oauth/consents/revoke`. | `private, no-store` |
-| `ALL /mcp` | Public MCP surface. JSON-RPC. | `private, no-store` |
-| `ALL /mcp/staff` | Staff MCP surface. Rejects a verified caller with no staff row using `403` and `insufficient_scope`. | `private, no-store` |
-
-Both MCP surfaces resolve the caller exactly as the HTTP routes do — consumer credential, then an OAuth access token against one canonical resource, `${PUBLIC_ORIGIN}/mcp`, and one scope, `mcp`, then a same-origin cookie session, then anonymous. The surface adds one rule: `/mcp/staff` requires a staff caller. An invalid token, or an anonymous caller on the staff surface, is `401` with a `Bearer` challenge naming the resource metadata URL; DPoP failures answer with a `DPoP` challenge; on `/mcp` an anonymous `tools/call` whose target requires identity answers the same `401` challenge. Misconfigured or partial auth environment variables keep public routes serving and return `503 setup_incomplete` from every Auth-owned route above — see [Authentication](../cloudflare/authentication.md).
-
-### Public pages
-
-These are opt-in and application-declared. Public rendering needs three matching inputs: a `mountPublicRoutes(...)` call declaring the collection routes, a `TemplateRegistry` passed as `templates`, and a `publicPathResolver`. A headless deployment declares none of them and serves none of these routes; mounting every Schema automatically is deliberately not offered, because a collection can hold a slug and still be private. Bodies render from canonical database state.
-
-| Route | Response | Cache |
-|---|---|---|
-| `GET /` | `302` to `/{canonical locale}`. | `private, no-store` |
-| `GET /:locale` | Composed home page. | `public, max-age=0, s-maxage=300` + a deployment-scoped cache tag |
-| `GET /:locale.md` | Markdown mirror of the home page. | public |
-| `GET /:locale/:segment` | Collection list page. Opt-in per collection route. Paginates by `?cursor=` and adds `Link: <…>; rel="next"` plus an in-page next link. | public |
-| `GET /:locale/:segment.md` | Markdown mirror of the list. | public |
-| `GET /:locale/:segment/:slug` | Entry page. | public |
-| `GET /:locale/:segment/:slug.md` | Markdown mirror of one entry. Registered before the bare slug route, and the slug group stays single-segment. | public |
-| `GET /:locale/:segment/:slug?preview=1` | Live render of unpublished content. Gated on a staff session: `401` with no session, `403` for a non-staff user. | `private, no-store` |
-| `GET /llms.txt` | Composed agent index across every locale, with `?cursor=` continuation and `Link: rel="next"`. | public |
-| `GET /:locale/llms.txt` | The same, scoped to one locale. | public |
-| `GET /sitemap.xml` | Sitemap. `?part=1` returns a single part; otherwise a sitemap index is returned whenever a continuation exists, and `?cursor=` fetches the next part. Part size is `min(2000, floor(40000 / locale count))`, at least 1. | public |
-| `GET /robots.txt` | `User-agent: *`, `Allow: /`, and a `Sitemap:` pointer built from `siteDefaults.origin`. | public |
-| `GET /favicon.ico` | A convention, not a reserved path: an existing host route wins. Picks the first themeless PNG icon, else the first themeless icon, else the first icon; serves it from the assets binding when it resolves to `/favicon.ico` on this origin, and otherwise redirects to the icon `src`. | `private, no-store` |
-
-The first three rows register only when a home renderer is supplied; without one, `/` and `/{locale}` are not mounted at all. Unmatched paths fall through to the supplied not-found renderer. Setting `liveDev` switches entry and list HTML to `private, no-store`. `cacheScope` isolates each deployment's tag and optional KV key; without it the facade disables shared caching. Publishing-content and site-setting writes purge that scoped tag. Purge is best effort after the canonical write, and Cloudflare KV remains eventually consistent. Immutable assets and operational records stay outside that boundary. More in [Public web](../cloudflare/public-web.md).
-
-### Reserved paths
-
-Extensions may add routes but may not replace Core surfaces. These are reserved:
-
-- `/admin` and `/admin/*`
-- `/_mantle` and `/_mantle/*`
-- `/api/auth` and `/api/auth/*`
-- `/api/views` and `/api/views/*`
-- `/oauth` and `/oauth/*`
-- `/mcp` and `/mcp/*`
-- `/.well-known/oauth*`
-- the global `*` and `/*` registrations
-
-A custom Auth factory's `basePath` and every manifest-owned `(method, path)` pair are reserved as well. Static literal conflicts fail the consumer's TypeScript build; computed paths cannot be proven statically, so the facade inspects the assembled route table and fails closed before serving. A manifest HTTP Trigger under one of these prefixes is `TRIGGER_PATH_INVALID` at boot.
-
-## MCP tools
-
-Tool names are the mangled `metadata.name`: lower-cased, with `-` replaced by `_`. Discovery is filtered per caller, but discovery is never the enforcement boundary — every `tools/call` re-evaluates the target's `requires.auth.all` and its guard.
-
-| Tool | Surface | Registered when |
-|---|---|---|
-| `query_view_<segment>` | The View's own `surface` | One per public or staff View; internal Views have no tool. `annotations.readOnlyHint` is `true`; the input schema is the View's `params.properties` plus `page` and `show`. |
-| `<procedure_segment>` | The MCP Trigger's `surface` | One per `mcp` Trigger. `annotations` carry what Core can prove (`readOnlyHint: false` for every builtin handler, `destructiveHint: true` for `op: delete`, `idempotentHint: true` when an input carries `x-mcp-hint: idempotency-key`) plus whatever the Procedure declares under `spec.mcp`; `ref` handlers get nothing inferred beyond the idempotency key. Generic authoring, lifecycle and media tools are `readOnlyHint: false`; `delete_entry` is also `destructiveHint: true`. |
-| `<procedure segment>` | The Trigger's `surface` | One per `Trigger.source.kind: mcp`. A Procedure with no MCP Trigger is not exposed. |
-| `request_publish` | staff | Always. Rejected at call time for an operational Schema. |
-| `unpublish_entry` | staff | Always. Same restriction. |
-| `archive_entry` | staff | Always. Same restriction. |
-| `delete_entry` | staff | Always. |
-| `create_draft_<segment>`, `update_draft_<segment>` | staff | Per publishing Schema whose `schema.readOnly` is not `true`. |
-| `create_record_<segment>`, `update_record_<segment>` | staff | Per operational Schema whose `schema.readOnly` is not `true`. |
-| `create_media_upload`, `commit_media_upload` | staff | Only when a `mediaStorage` port is bound **and** at least one `media.purposes` entry is declared. |
-
-The public surface carries callable capabilities only — public Views and Procedures with a public MCP Trigger. No generic entry tool and no authoring tool is ever advertised there. Update tools add `id` and `expected_version` as required fields, and `x-mantle-bind` properties are stripped from authoring tool schemas because the server stamps them. Localized `title` and `description` collapse to their `en` value in tool schemas. Concepts are in [MCP and agents](../concepts/mcp-and-agents.md).
-
-## CLI
-
-The `@aotter/mantle` package installs two binaries, `mantle` and `mantle-harness`. Exit codes are `0` for success, `1` for a diagnostic failure and `2` for an invocation problem.
-
-| Command | Flags |
-|---|---|
-| `mantle generate` | `--manifests <dir>` (default `./manifests`), `-o, --output <dir>` (default `.mantle/generated`), `--namespace <name>` (default `Mantle`), `--host cf\|chatgpt-sites`, `--features <list>`, `--review-unique-indexes` (managed Sites only), `--check`, `-h, --help` |
-| `mantle skills` | `--check`, `-h, --help` |
-| `mantle validate` | `--manifests <dir>` (default `./manifests`), `--source <dir>` (default `./src`), `--no-source`, `--phase preview\|deploy` (default `preview`), `--format json\|text` (default by TTY), `--json`, `-h, --help` |
-| `mantle emit-openapi` | `--manifests <dir>`, `--title <str>` (default `mantle`), `--version <str>` (default `0.1.0`), `--session-cookie-name <str>`, `-o, --output <file>`, `-h, --help` |
-| `mantle-harness indexes` | `--manifests <dir>`, `--rows <n>`, `--require <view>` (repeatable), `--require-public`, `--format json\|text`, `-h, --help` |
-| `mantle-harness http` | `--route <name=url>` (repeatable, required), `--base-url <url>`, `--rounds <n>`, `--warmup <n>`, `--format json\|text`, `-h, --help` |
-
-`generate` assembles new hosted projects with full Spec/Runtime/API/MCP/Admin/Web by default, or a smaller positive `--features` selection, then validates and compiles manifests into a typed module. Saved selections rerun safely; legacy authored projects keep compile mode. Selected Admin syncs its prebuilt SPA into `public/_mantle/admin/`. `--check` fails without writing on drift. `skills` copies project-scoped skills into `.agents/skills/mantle-*` and `.claude/skills/mantle-*`. `validate --phase deploy` adds pre-deploy checks; `emit-openapi` covers HTTP Triggers and View REST routes. `mantle-harness indexes` checks SQLite plans, while `http` samples a running Worker. [Project and CLI](../start/project-and-cli.md) has the install and ownership sequence.
-
-## The generated module
-
-`mantle generate` writes one file, `.mantle/generated/mantle.ts`. It is generated code: do not edit it, and regenerate after any manifest change.
-
-| Export | Shape |
-|---|---|
-| `plan` | The sealed `RuntimePlan`, carrying a semantic fingerprint. |
-| `Mantle` (or `--namespace`) | Type namespace holding `Entry_*`, `ViewRow_*`, `ViewParams_*`, `ProcInput_*` and `ProcOutput_*` for every atom. |
-| `MantleViewOptions` | `{ page?, show?, ctx? }`. |
-| `MantleHandlers<Env>` | Typed map of every `handler.kind: ref` key the manifests declare. |
-| `CreateMantleOptions<Env>` | `BootMantleRuntimeArgs` without `plan` and `handlers`, plus the typed `handlers` map. |
-| `createMantle(options)` | Boots the runtime and returns the bound facade. Eager: it prepares once and neither caches nor retries. |
-| `bindMantle(runtime)` | Binds an already-booted runtime. Throws when `runtime.revision` does not equal the generated plan's fingerprint. |
-
-The bound object is deterministic lower-camel property names over the authored wire names:
+# Generated surfaces
+
+- The app mounts generated modules and passes `{ db, caller }`; `caller(request, env, { readOnly })`
+  is the app's own `resolveCaller(...)` call. There is no generated `service.ts`,
+  routing framework or Better Auth wrapper.
+- REST retains public `GET /api/views/<name>` (and bodyless HEAD) with declared query input plus
+  `limit` and `cursor`, answering `{ rows, nextCursor? }`. HTTP Triggers retain
+  their own method/path; JSON bodies and path parameters form the Procedure
+  input and responses contain its result. Errors remain
+  `{ error: { code, message, path } }` with the 0.2 status. Cookie sessions cannot
+  mutate across origins.
+- MCP retains public `POST /mcp`, admin `POST /mcp/admin`,
+  snake-cased View names on each declared surface, and snake-cased Procedure
+  names per MCP Trigger. Its SDK loads only through a request-time dynamic import.
+- HTTP/MCP Triggers declare exposure only. `mantle generate` refuses schedule
+  and lifecycle Triggers; host scheduling is a separate capability.
+- Native Admin retains selected 0.2 paths and the console contracts; see
+  [Native Admin](../guides/native-admin.md) for app-mounted
+  `adminBindings()` and `entries(bindings.schemas, bindings.adapter)`.
+
+Generated `rest.ts`, `mcp.ts`, `web.ts`, `paged/views/*` and `validation/*` hold
+only the app's tables: routes, tools, pages, operation bindings, compiled input
+checks and types. Request handling (matching, body and query decoding, dispatch,
+challenges, JSON-RPC, web rendering, keyset paging) lives in the package's
+`rest`, `mcp`, `web`, `paging` and `validation` kernel modules, so a runtime fix
+ships as a package update instead of a regeneration.
+
+Procedure surface selection follows the [HTTP/MCP pairing default and deliberate asymmetry exception](trigger.md); no surface is implied.
+
+The generated `validation/views/<name>.ts` and
+`validation/procedures/<name>.ts` export `validate(unknown)`. View validators
+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, `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. `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? }`.
+Bare `views/<name>.ts` retains native row arrays and accepts app-validated input;
+selecting neither boundary adds no validation or paging work to that query.
+Selected REST/MCP/Admin responses convert declared integer columns on every target
+to safe numbers or exact decimal strings. Their SQL reads integers as text before
+driver conversion; integer cursor keys retain that precision without changing native
+sort order. `views/<name>.ts` also exports `WireRow` for selected transport
+boundaries; declared wire fields agree across targets. Declared SQLite/D1
+JSON/boolean columns become JSON values and booleans. Aliases follow generated
+source-column lineage; computed values and Procedure/ref results retain
+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` 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; 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
+base references while preserving the base order/key tuple; joined fields remain
+nullable cursor keys. Refusals identify the nullable key, missing ORDER BY index,
+or fanning join and state a remedy. Relation aliases and nested CTE
+bindings keep their own identity; same-Schema aliases are not interchangeable.
+
+Grouped Views use every GROUP BY key as the tiebreak, with known non-null scalar
+keys; unfiltered, non-windowed `min`/`max` of a non-null column retain its native cursor type. Paging a
+grouped result does not avoid the native grouping/source scan. Authors own source
+predicate indexes and should inspect EXPLAIN for their workload. Nullable,
+unknown and JSON order expressions and unproved fanout remain refused.
+Trusted system reads retain their all-scope SQL: without an actual scope
+predicate, a scope-first index is not a proved range scan and native sorting or
+scanning may be needed. Caller equality-prefix proofs do not claim otherwise.
+
+Proved singletons (scalar/aggregate queries, unique-id lookups and singleton
+sources) run bounded first-page SQL, reject cursors and refuse overflow.
+Internal Views receive directly imported paged modules only when the same proofs
+hold; they gain no public route or tool. Their bare modules remain available for
+other native SQL and return full authored-query arrays.
+
+Cursors reuse the Store's percent-encoded JSON keyset codec. Selected View
+cursors include operation provenance; malformed, foreign and
+null-key cursors fail with `INPUT_VALIDATION_FAILED`. Each generated key has a
+scalar check; temporal keys keep database microseconds. Existing one/two-key
+formats and Store cursors are preserved; larger View tuples contain their full
+key list followed by operation provenance. They are opaque navigation
+values, not credentials; authorization and row predicates run on every page.
+
+## Mounting REST
+
+`rest.ts` exports `rest({ db, caller })`, returning an async
+`(request, env) => Response | undefined`. The app supplies its native handle and
+verified Caller; requests outside `/api` fall through to the app. Public Views
+use `/api/views/<name>`; HTTP Triggers keep their declared method and path.
+Known paths with another method return 405 with an `Allow` header. All responses use
+`cache-control: private, no-store`. JSON bodies and decoded path parameters
+are validated together, with path parameters taking precedence. Bodies larger
+than 1,000,000 bytes are refused; `content-length` is checked before reading.
+A resolver's `ContractError` keeps its status (an expired token is 401 with its challenge); any other resolver exception returns a redacted 500. Cookie-origin refusals retain
+`path: "request:origin"`; REST and MCP share the kernel check.
+
+When the manifest declares ref Procedures, pass the generated `Handlers` as
+`rest({ db, caller, handlers })`; the option is type-required. Handler dispatch
+uses the generated Store, preserving the Procedure's authorization contract.
+Publishing visibility belongs to generated SQL; the REST module adds no status
+filter. The app retains ownership of authentication and its other routes.
+
+## Optional web output
+
+`web.ts` exports `web({ db, caller, origin, title, description, locales?, pages,
+cacheControl? })`. `db` is the application-owned native handle, including callable
+PostgreSQL handles. `caller` is a verified Caller or the app's
+`(request, env, { readOnly }) => Caller | Promise<Caller>` resolver, evaluated once per request.
+Generated REST/MCP/web callbacks classify reads; forward the third argument to
+`resolveCaller` to permit an enabled cookie cache, as documented in
+[authentication](../cloudflare/authentication.md#explicit-read-only-cookie-snapshots).
+The module dispatches public Views only; it never invokes Procedures or needs handlers.
 
 ```ts
-import { createMantle } from "../.mantle/generated/mantle.js";
-
-const mantle = await createMantle({ storage, handlers });
-
-await mantle.views.publishedNotes({ page: 1, show: 20 });
-await mantle.procedures.expireOrder({ orderId }, { user: null, staff: null, env });
-await mantle.entries.orders.createDraft({ data, authorId: user.id });
-mantle.triggers.expireOrderHttp;   // { name, source, target }
-await mantle.runtime.archive.execute({ id, ctx });
+import { web } from './generated/web.js';
+const site = web({ db, caller, origin: 'https://example.com', title: 'Blog',
+  description: 'Articles', locales: ['en'],
+  pages: { '/posts/{slug}': { view: 'post-by-slug', list: 'posts', markdown: 'body' } }
+});
+const response = await site.fetch(request, env); // Response | undefined
+const tags = await site.head(request, env); // HTML string, empty for unknown/missing pages
 ```
 
-`entries.<collection>` exposes `createDraft`, `get`, `list`, `delete`, and the indexed field reads `readBySlug`, `readByDataField`, `readByDataFieldIn` and `findManyByDataField`, supplying the required collection identity to Core. The field reads accept only declared Schema fields and their scalar types, and return entries whose `data` is the generated Schema shape, so an author never has to drop to an untyped `runtime.entries` call or scan `list` to find rows by an indexed field. Generic MCP entry tools require a `collection` argument. `runtime` is the underlying Core runtime, so the typed projection never hides it. A host that owns its own lifecycle can skip generation entirely and call `runtime.executeView({ view: "published-notes" })` directly.
-
-## Packages
-
-The umbrella installs Spec and Runtime only. Web, Admin, Auth, Admin UI, Bun, Vercel and Cloudflare are optional peers; install one before importing its subpath. Every sub-package is also directly installable.
-
-| Package | Umbrella subpath | Holds |
-|---|---|---|
-| `@aotter/mantle` | root | Umbrella plus the `mantle` and `mantle-harness` binaries. |
-| `@aotter/mantle-spec` | `/spec` | Manifest grammar, parser, validators, JSON Schema to zod, site-config contract, diagnostic catalog. No environment, no IO. |
-| `@aotter/mantle-runtime` | `/runtime` | Hexagonal runtime: domain ports, use cases, MCP catalog, storage helpers. No adapter dependencies. |
-| — | `/runtime/testing` | Node-only crowded-SQLite planner and HTTP sampling helpers used by `mantle-harness`. |
-| — | `/codegen` | The pure linked-manifests or compiled-plan to typed-module emitter, with no IO. |
-| `@aotter/mantle-web` | `/web` | HTML, Markdown, `llms.txt`, sitemap, SEO and preview composition. No routes, no platform dependencies. |
-| `@aotter/mantle-admin` | `/admin` | Admin API, auth route mounting, OAuth pages, static-asset composition. |
-| `@aotter/mantle-auth` | `/auth` | Host-neutral Better Auth identity, staff roles, and OAuth 2.1 / MCP authorization. Adapters own IP headers and storage bindings. |
-| `@aotter/mantle-admin-ui` | `/admin-ui` | Pre-built React 19 Admin SPA bundle. |
-| `@aotter/mantle-bun` | `/bun` | Bun adapter over a caller-owned `bun:sqlite` database. |
-| `@aotter/mantle-vercel` | `/vercel` | Vercel Functions adapter with injected durable storage and platform `waitUntil`. |
-| — | `/vercel/libsql` | Optional application-owned Turso/libSQL driver. |
-| `@aotter/mantle-cloudflare` | `/cloudflare` | Cloudflare Workers adapter: D1, Workers Cache, R2, Queues, Better Auth 1.7 MCP and CIMD. |
-| `@aotter/mantle-indexeddb` | — | Browser IndexedDB adapter. Directly installable; no umbrella subpath. |
-
-## Versions
-
-This handbook describes the snapshot in this source tree. Pin every `@aotter/mantle*` package to one exact version and keep them together. For a registry installation, use the documentation at the matching release tag. For a source-built package, record the source commit as well as the package version.
-
-The documentation site pins its handbook commit in `docs/handbook.json` and records its vendored SDK source in `vendor/mantle/SOURCE.txt`. Those commits may differ when the intervening changes are behavior-neutral; the site verifies that condition during the build.
-
-New projects can use `generate` to assemble a blank hosted app. Existing authored Workers can keep their own entry and use the same CLI for typed compilation. Pin all selected packages to one exact SDK version; prerelease APIs can change until stable publication.
-
-## Source
-
-- [`packages/mantle/README.md`](../../../packages/mantle/README.md)
-- [`packages/mantle/src/cli/main.ts`](../../../packages/mantle/src/cli/main.ts)
-- [`packages/mantle/src/cli/generate.ts`](../../../packages/mantle/src/cli/generate.ts)
-- [`packages/mantle/src/cli/skills.ts`](../../../packages/mantle/src/cli/skills.ts)
-- [`packages/mantle/src/cli/harness.ts`](../../../packages/mantle/src/cli/harness.ts)
-- [`packages/mantle/src/codegen/emitMantleModule.ts`](../../../packages/mantle/src/codegen/emitMantleModule.ts)
-- [`packages/mantle-spec/src/infrastructure/cli/ValidateCommand.ts`](../../../packages/mantle-spec/src/infrastructure/cli/ValidateCommand.ts)
-- [`packages/mantle-spec/src/infrastructure/cli/EmitOpenapiCommand.ts`](../../../packages/mantle-spec/src/infrastructure/cli/EmitOpenapiCommand.ts)
-- [`packages/mantle-runtime/src/infrastructure/mcp/McpToolCatalog.ts`](../../../packages/mantle-runtime/src/infrastructure/mcp/McpToolCatalog.ts)
-- [`packages/mantle-admin/src/mountMantleAdmin.ts`](../../../packages/mantle-admin/src/mountMantleAdmin.ts)
-- [`packages/mantle-admin/src/mountMantleOAuth.ts`](../../../packages/mantle-admin/src/mountMantleOAuth.ts)
-- [`packages/adapters/cloudflare/README.md`](../../../packages/adapters/cloudflare/README.md)
-- [`packages/adapters/cloudflare/src/worker/createMantleWorker.ts`](../../../packages/adapters/cloudflare/src/worker/createMantleWorker.ts)
-- [`packages/adapters/cloudflare/src/mount/mountRuntimeEndpoints.ts`](../../../packages/adapters/cloudflare/src/mount/mountRuntimeEndpoints.ts)
-- [`packages/adapters/cloudflare/src/mount/mountPublicRoutes.ts`](../../../packages/adapters/cloudflare/src/mount/mountPublicRoutes.ts)
-- [`packages/adapters/cloudflare/src/mount/mountMcp.ts`](../../../packages/adapters/cloudflare/src/mount/mountMcp.ts)
-- [`packages/adapters/cloudflare/src/oauth/cachePolicy.ts`](../../../packages/adapters/cloudflare/src/oauth/cachePolicy.ts)
+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: 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
+read the current page View. SQL alone controls visibility, including publication.
+GET/HEAD responses include content-derived SHA-256 ETags. Anonymous responses use
+`cacheControl` or `public, max-age=60`; authenticated responses use
+`private, no-store`. `If-None-Match` returns 304 only after current content is read.
+Canonical URLs use the configured origin, independently of the request host.
+The current implementation adds hreflang only for `locales[0]`; translation-aware
+indexes and head tags are a follow-up below. Importing another generated entry
+does not import web output.
+
+Web indexes scan at most 50,000 rows for one sitemap and 5,000 for `llms.txt`,
+across all configured lists. Skipped `.`/`..` path segments consume the scan
+budget too. Output stops before exceeding 50 MiB of UTF-8 sitemap XML (including
+its closing tag) or 1 MiB of `llms.txt`; a sitemap index can be added separately.
+Each request also stops after 100 sitemap queries or 10 `llms.txt` queries,
+across all templates. Small authored SQL LIMITs or many templates can truncate
+output sooner. A sitemap index remains separate future work.
+
+`head` normalizes URLs from the queried row's page parameters, matching sitemap
+URLs; malformed paths, failed validation and unavailable rows return an empty
+string. A NULL Markdown field answers 404. Errors and missing Markdown responses
+use `cache-control: no-store`. A matching HTML page takes precedence over a `.md`
+alternate, including slugs ending in `.md`; a Markdown alternate may read the
+exact HTML candidate first and therefore performs at most two View queries.
+
+## Mounting MCP
+
+Mount the generated `mcp({ db: env => env.DB, caller })` handler in the app's
+Fetch entry. It returns `undefined` outside `/mcp` and `/mcp/admin`. Install the
+optional official `@modelcontextprotocol/server` peer when selecting MCP; its
+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`
+metadata route. Auth challenges point to that route. Presented bearer credentials
+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. Omitting
+MCP remains a deliberate asymmetric choice; an HTTP-only Procedure still generates
+successfully with the warning described in [Trigger](trigger.md). These
+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
+surface its generated `publish_<schema>`, `unpublish_<schema>` and
+`archive_<schema>` tools use the same snake-case naming rule, are admin-only
+and take `{ id, expectedVersion }` through the shared generated validation.
+
+`/mcp/admin` admits only admins: `isAdmin(caller)` must hold. It lists only admin-surface tools; public Views and Procedures stay on `/mcp`, and generation never copies them across. An admin's AI that changes records also needs admin Views to find them and read back the committed row and its version (search, detail), declared by the app; the [acceptance design audit](../guides/agent-workflow-acceptance.md#audit-mcp-tool-design-before-implementation) checks this. Better Auth’s admin plugin `adminRoles` defines this layer (default `["admin"]`); the application supplies its verified Caller. MCP bodies are limited
+to 1 MiB (1,048,576 bytes). Resource metadata challenges use the origin of
+`request.url`; behind a proxy, the app must pass a Request with its public
+origin so the audience and metadata URL point to the client-visible service.
+
+Selected integer cursor keys may be exact canonical decimal strings on either dialect; SQLite cursor binds are cast to INTEGER so grouped expressions and native columns compare the same value; they are bounded to the declared integer range. This applies to cursor metadata only and does not change bare query or Store integer outputs, or recover integers already rounded by a native driver. `validCursor` is shared with selected boundary adapters.
+
+Cursor casts target only proved AST bind nodes, preserving authored SQL literals. Paging proofs respect the compiler's lexical table/CTE identity. Explicit CTE or relation column renaming is currently refused for paging because uniqueness has not been proved through those aliases; internal bare queries remain available.
+
+A paged View's output names must not collide with its actual hidden cursor keys (`_k0` through `_kN-1`); SQLite compares aliases without case sensitivity. Such internal Views keep their bare entry but receive no paged entry. Other output names remain available.
+
+## Selected Admin bindings
+
+See [Native Admin](../guides/native-admin.md) for the single
+current contract: three packages, explicit generation and app mounting, shared
+whitelisted get/page/statistics templates, native Procedure fragments, generated
+input checks, exact OCC and optional capabilities. These features are implemented
+as an explicit option.
+
+
+### MCP catalogue and callbacks
+
+`mcp({ db, caller, handlers?, locale?, instructions?, serverInfo?, requiredScopes?,
+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. 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
+headers, bodies or tokens; delivery failures never change the business response
+and promises are not awaited. The application owns callback delivery.
+
+**Procedure output:** SQL Procedures retain the native `{ results }`
+contract rather than 0.2's authored output projection/validation; MCP advertises
+that object envelope, not the incompatible authored schema. Ref Procedures expose
+the application's typed return value and advertise their authored object output
+schema. The application owns ref output validation. MCP does not decode or
+revalidate native database rows. Business failures carry diagnostics in text;
+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
+boolean columns as booleans, including explicitly authored SQL aliases. SQLite
+and D1 conversions are compiled into only the selected boundary pages;
+PostgreSQL already-native JSON/boolean values pass through. SQL NULL stays null and absent
+fields stay absent. A computed output that is a JSON document by construction
+(`json_group_array`, `json_set`, `jsonb_agg`, `jsonb_build_object` and the like, a scalar
+subquery of one, or a `COALESCE` of those) is converted like a declared JSON column, so it
+is a JSON value on every target. Other expressions without declared column lineage stay native.
+Malformed persisted JSON becomes a redacted internal failure. The conversion
+adds no database operations and does not mutate native query rows.
+
+Bare Views, Store rows, native SQL Procedure `{ results }` and application-owned
+ref outputs retain their native contracts. Use the generated `rest()` / `mcp()`
+module for this client wire contract; do not duplicate JSON/boolean decoding in
+application route handlers or decode PostgreSQL JSON strings a second time.
+
+Declared integer columns (including a selected system `version`) on every target
+use the wire form: safe integers become JSON numbers; unsafe values remain exact
+decimal text. Selected-boundary SQL casts integers to text before driver conversion,
+preserving stored int64 values on D1 too. Values already rounded when written
+(e.g. by a JavaScript number) cannot be recovered. Computed outputs and native
+SQL Procedure/ref results retain their native values.
+Unexpected surface failures log only a stable wire classification.
+
+MCP locale fallback reads only own locale entries, then English, then the first
+own entry; inherited property names never become titles or descriptions.
+
+### Admin media MCP tools
+
+With generated site configuration, `mcp({ db, caller, media: env => storage })`
+loads the media module only on a configured admin MCP request and
+adds `get_media_upload_policy`, `create_media_upload`, `commit_media_upload`,
+`list_media_assets`, `get_media_asset`, `update_media_asset` and
+`delete_media_asset` to `/mcp/admin` only. `storage` is the same `MediaStorage`
+used by the Admin media library. Omitting `media` omits all seven tools.
+Admins can invoke them; cookie writes retain the origin check.
+Generated boundary code checks each input and advertises the 0.2 schemas and
+read-only/destructive/open-world hints. Image bytes are PUT directly to the
+returned short-lived URLs with their required headers, then committed; bytes
+never enter MCP. Store permanent asset ids, never upload URLs.
+
+Generation always emits a `Handlers` type (empty when no Procedure uses `handler: { ref }`), so every app wires the
+same way: `const handlers: Handlers = {...}`, then `store(db, caller, { handlers })`, `adminBindings({ handlers })`,
+`rest({ ...options, handlers })`, `mcp({ ...options, handlers })` and `webmcpRoutes(catalogue, tools, handlers)`.
+Type extra hand-written tools as `Tool<Handle, Handlers>` with the generated `Handlers` before combining them with
+the generated `tools`. Handler-less apps may still omit `{ handlers }` at `store()` and `adminBindings()`.