@aotter/mantle 0.2.0-alpha.1 → 0.2.0-alpha.11

package/docs/handbook/reference/surface.md

@@ -1,93 +1,396 @@
----
-description: Every HTTP route the generated Mantle 0.2.0 service mounts (REST, auth, MCP, Admin), the package subpaths and their exports, and the CLI.
----
-# HTTP, MCP, CLI and packages
-
-## Routes of the generated service
-
-`src/service.ts` mounts, in this order. Each surface runs behind
-`withCaller(resolver, …)`; with identity `none`, every caller is anonymous.
-
-| Path | Surface | Mounted when |
-|---|---|---|
-| `/api/auth/*`, `/.well-known/oauth-authorization-server/*`, `/.well-known/oauth-protected-resource[/*]`, `/oauth/consent[/data]`, `/oauth/consents[/data\|/revoke]` | `createAuthRoutes` | identity `mantle` |
-| `/admin/*` | `createAdminSurface`: the console (from `ASSETS`) and `/admin/api/*` | feature `admin` |
-| `/mcp/staff` | `createMcpSurface`, `surface: staff`, with `planApp`'s MCP App | feature `mcp` and an identity |
-| `/mcp` | `createMcpSurface`, `surface: public` | feature `mcp` |
-| everything else | `createRestSurface` at `/api` | always |
-
-### REST
-
-| Route | |
-|---|---|
-| `GET /api/views/<name>` | a `public` View; query parameters are its `input` plus `limit` and `cursor`. Answers `{ rows, nextCursor? }` |
-| `<METHOD> <path>` | each `http` Trigger; the JSON body and path parameters are the input. Answers the Procedure's output |
-
-A failure is `{ "error": <diagnostic> }` with the code's status
-([Diagnostics](./diagnostics.md)). A cookie session cannot mutate across
-origins.
-
-### Auth (identity `mantle`)
-
-| Route | |
-|---|---|
-| `GET /api/auth/methods` | the sign-in methods this service offers |
-| `/api/auth/*` | Better Auth: email OTP (`/email-otp/send-verification-otp`, `/sign-in/email-otp`), magic link, social and generic OAuth sign-in, sessions, sign-out, the OAuth provider |
-| `/.well-known/oauth-authorization-server/*`, `/.well-known/oauth-protected-resource[/mcp]` | OAuth metadata, served by Better Auth |
-| `/oauth/consent`, `/oauth/consents` | consent and connected apps, session only |
-
-### MCP
-
-| Route | |
-|---|---|
-| `POST /mcp` | the public surface (Streamable HTTP, JSON-RPC) |
-| `POST /mcp/staff` | the staff surface: staff only, the same token as `/mcp`; see [MCP and agents](../concepts/mcp-and-agents.md) |
-
-### Admin API
-
-Every route needs a staff caller; the column names the least role.
-
-| Route | Role | |
-|---|---|---|
-| `GET /admin/api/me`, `GET /admin/api/bootstrap` | contributor | the caller; the console's first load |
-| `GET /admin/api/collections`, `GET …/collections/{name}/statistics` | contributor | Schemas; statistics answer 501 in 0.2.0 |
-| `GET /admin/api/entries?collection=`, `GET …/entries/export`, `GET …/entries/{id}` | contributor | list (with `search`, `limit`, `cursor`), CSV, one row |
-| `POST /admin/api/entries`, `PATCH …/entries/{id}` (with `expectedVersion`) | contributor | create, edit (contributors: drafts only) |
-| `POST …/entries/{id}/publish`, `…/unpublish`, `DELETE …/entries/{id}` | editor | |
-| `GET /admin/api/views-manifest`, `GET …/views/{name}`, `GET …/views/{name}/export` | contributor | staff Views (`{ name, title, description, input, list: { columns, searchFields, filterFields }, columns }`); rows by `limit`/`cursor` with `search` and `filter.<output>`; CSV |
-| `GET /admin/api/operations`, `POST …/operations/{name}` | contributor | Procedures bound to the staff MCP surface |
-| `GET /admin/api/site` | contributor | site metadata, `mcpEndpoints`, and `capabilities: { siteSettings, media, invitationEmail, statistics }` (what this deployment turned on; the console hides what is off) |
-| `GET`, `PATCH /admin/api/site-settings` | owner | 501 `SITE_NOT_CONFIGURED` without `runtime.site` |
-| `POST /admin/api/media/uploads`, `POST …/media/uploads/{groupId}/commit`, `GET …/media`, `GET`, `PATCH`, `DELETE …/media/{id}` | editor | with `media` and `runtime.site` |
-| `GET /admin/api/webmcp`, `POST …/webmcp/{tool}` | contributor | the staff tools for a browser agent (`{ tools, routes }`); a call runs one as `/mcp/staff` does and answers `{ output }` |
-| `GET /admin/api/staff`, `PATCH …/staff/{id}/role`, `POST …/staff/invitations`, `DELETE …/staff/invitations/{id}` | owner | with an `AdminIdentity` that has `directory` / `roles` |
-| `GET /admin/api/members` | editor | with `directory` |
-| `GET /admin/api/developer-console` | owner | the plan's data model, logic and schedules |
-
-## Packages
-
-Two npm packages, always published together at one version.
-
-| Import | Exports |
-|---|---|
-| `@aotter/mantle` | `createMantle`, `createMantleRuntime`, `verifyPlan` and its `PLAN_LIMITS`, `withCaller`, `systemCaller`, the `Caller`, `CallerResolver`, `MantleService`, `HandlerContext`, `Invocation` and Store types, `EmailSender`, `DiagnosticError`, `makeDiagnostic`, `runtimeDiagnostic`, `STAFF_ROLES`, `isStaffRole` |
-| `@aotter/mantle/spec` | the grammar types, `compilePlan`, `mcpTools` (the CLI side; it bundles the SQL parser, so a Worker or handler imports `DiagnosticError` from the root) |
-| `@aotter/mantle/d1`, `/d1/compile` | the `sqlite` dialect: `sqliteStorage` over any `DatabaseDriver`; its compile side |
-| `@aotter/mantle/postgres`, `/postgres/compile` | the `postgres` dialect: `postgresStorage`, `postgresDialect`, `pgDatabaseDriver`, `pgPool`, the `PgClient` and `PgConnect` types; its compile side |
-| `@aotter/mantle/cloudflare` | `d1Storage`, `d1Driver`, `r2MediaStorage`, `toCloudflareCron` |
-| `@aotter/mantle/auth` | `createMantleAuth`, `createSetupIncompleteAuth`, `createCallerResolver`, `createAuthRoutes`, `ConsoleEmailSender`, `appleClientSecret` |
-| `@aotter/mantle/admin` | `createAdminSurface`, `AdminIdentity` |
-| `@aotter/mantle/mcp` | `createMcpSurface`, `planApp` and `appCatalog` (the MCP App's catalog) |
-| `@aotter/mantle/web` | `createRestSurface` |
-| `@aotter/mantle/bun` | `bunPostgresStorage`, `bunSqliteStorage`, `bunPgConnect`, `bunDatabaseDriver`, `bunSqliteDriver`, `bunAuthDatabase`, `bunAdminAssets` |
-| `@aotter/mantle/testing` | `runStorageConformance`, the dialect compliance suite |
-| `@aotter/mantle-ui` | the root (React operation components and the controller), `/controller`, `/kit`, `/kit.css`, `/tokens.css`, `/mcp-app` (`mantleAppHtml`, the App `planApp` serves), and the prebuilt Admin console in `dist/admin` (exported as `./admin/index.html`), which the preset serves at `/admin` |
-
-A subpath that is not imported is never loaded: a service with identity
-`none` bundles no Better Auth, and no Worker bundles the SQL parser.
-
-## CLI
-
-`mantle generate [--manifests <dir>] [--features <list>] [--identity <kind>] [--host <host>] [--dialect <name>]`
-and `mantle generate --check [--database <file>]`. See
-[Project layout and CLI](../start/project-and-cli.md).
+# 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 { 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
+```
+
+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()`.