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

package/docs/handbook/navigation.json

@@ -4,67 +4,200 @@
     {
       "text": "Start here",
       "items": [
-        { "text": "Handbook overview", "link": "/start/overview" },
-        { "text": "Quickstart: a service on Workers", "link": "/start/quickstart-worker" },
-        { "text": "Project layout and CLI", "link": "/start/project-and-cli" }
+        {
+          "text": "Handbook overview",
+          "link": "/start/overview"
+        },
+        {
+          "text": "Quickstart: a service on Workers",
+          "link": "/start/quickstart-worker"
+        },
+        {
+          "text": "Project layout and CLI",
+          "link": "/start/project-and-cli"
+        }
       ]
     },
     {
       "text": "Task guides",
       "items": [
-        { "text": "Agent installation and handoff", "link": "/guides/agent-setup" },
-        { "text": "Query from TypeScript", "link": "/guides/typed-queries" },
-        { "text": "Customize Admin from manifests", "link": "/guides/admin-ui" },
-        { "text": "Extend Admin", "link": "/guides/admin-extensions" }
+        {
+          "text": "Agent installation and handoff",
+          "link": "/guides/agent-setup"
+        },
+        {
+          "text": "Query from TypeScript",
+          "link": "/guides/typed-queries"
+        },
+        {
+          "text": "Public pages: SEO, AEO and languages",
+          "link": "/guides/public-pages"
+        },
+        {
+          "text": "Native Admin",
+          "link": "/guides/native-admin"
+        },
+        {
+          "text": "Customize Admin",
+          "link": "/guides/admin-ui"
+        },
+        {
+          "text": "Extend Admin",
+          "link": "/guides/admin-extensions"
+        },
+        {
+          "text": "Another host or engine",
+          "link": "/guides/adapter-guide"
+        },
+        {
+          "text": "Native execution",
+          "link": "/guides/native-execution"
+        },
+        {
+          "text": "PostgreSQL adapters",
+          "link": "/guides/postgres-adapters"
+        },
+        {
+          "text": "OAuth and consent",
+          "link": "/guides/oauth"
+        },
+        {
+          "text": "Transactional email",
+          "link": "/guides/email"
+        },
+        {
+          "text": "MCP Apps",
+          "link": "/guides/mcp-apps"
+        },
+        {
+          "text": "Size and startup",
+          "link": "/guides/size-and-startup"
+        }
       ]
     },
     {
       "text": "Concepts",
       "items": [
-        { "text": "The four atoms", "link": "/concepts/four-atoms" },
-        { "text": "Lifecycle and locales", "link": "/concepts/lifecycle-and-locales" },
-        { "text": "Reads: Views, REST and MCP", "link": "/concepts/views" },
-        { "text": "Writes: Procedures, Triggers and hooks", "link": "/concepts/procedures-and-triggers" },
-        { "text": "Authorization", "link": "/concepts/authorization" },
-        { "text": "MCP and agents", "link": "/concepts/mcp-and-agents" },
-        { "text": "Runtime, Store and dialects", "link": "/concepts/runtime-and-adapters" }
+        {
+          "text": "The four atoms",
+          "link": "/concepts/four-atoms"
+        },
+        {
+          "text": "Lifecycle and locales",
+          "link": "/concepts/lifecycle-and-locales"
+        },
+        {
+          "text": "Reads: Views, REST and MCP",
+          "link": "/concepts/views"
+        },
+        {
+          "text": "Writes: Procedures and Triggers",
+          "link": "/concepts/procedures-and-triggers"
+        },
+        {
+          "text": "Authorization",
+          "link": "/concepts/authorization"
+        },
+        {
+          "text": "MCP and agents",
+          "link": "/concepts/mcp-and-agents"
+        },
+        {
+          "text": "Runtime, Store and dialects",
+          "link": "/concepts/runtime-and-adapters"
+        }
       ]
     },
     {
       "text": "Reference",
       "items": [
-        { "text": "Manifest feature table", "link": "/reference/features" },
-        { "text": "Manifest envelope", "link": "/reference/manifest" },
-        { "text": "Schema", "link": "/reference/schema" },
-        { "text": "View", "link": "/reference/view" },
-        { "text": "Procedure", "link": "/reference/procedure" },
-        { "text": "Trigger", "link": "/reference/trigger" },
-        { "text": "Authorization requirements", "link": "/reference/authorization" },
-        { "text": "Site defaults and site_config", "link": "/reference/site-config" },
-        { "text": "Diagnostic codes", "link": "/reference/diagnostics" },
-        { "text": "HTTP, MCP, CLI and packages", "link": "/reference/surface" }
+        {
+          "text": "Manifest feature table",
+          "link": "/reference/features"
+        },
+        {
+          "text": "Manifest envelope",
+          "link": "/reference/manifest"
+        },
+        {
+          "text": "Schema",
+          "link": "/reference/schema"
+        },
+        {
+          "text": "View",
+          "link": "/reference/view"
+        },
+        {
+          "text": "Procedure",
+          "link": "/reference/procedure"
+        },
+        {
+          "text": "Trigger",
+          "link": "/reference/trigger"
+        },
+        {
+          "text": "Authorization requirements",
+          "link": "/reference/authorization"
+        },
+        {
+          "text": "Site defaults and site_config",
+          "link": "/reference/site-config"
+        },
+        {
+          "text": "Diagnostic codes",
+          "link": "/reference/diagnostics"
+        },
+        {
+          "text": "HTTP, MCP, CLI and packages",
+          "link": "/reference/surface"
+        },
+        {
+          "text": "Generated Admin descriptors",
+          "link": "/reference/admin-descriptors"
+        }
       ]
     },
     {
       "text": "Cloudflare",
       "items": [
-        { "text": "The service and its entry", "link": "/cloudflare/service-entry" },
-        { "text": "Authentication", "link": "/cloudflare/authentication" },
-        { "text": "Media uploads with R2", "link": "/cloudflare/media-r2" },
-        { "text": "Deploy and operate", "link": "/cloudflare/deploy-and-operate" },
-        { "text": "Mantle on ChatGPT Sites", "link": "/cloudflare/chatgpt-sites" }
+        {
+          "text": "The service and its entry",
+          "link": "/cloudflare/service-entry"
+        },
+        {
+          "text": "Authentication",
+          "link": "/cloudflare/authentication"
+        },
+        {
+          "text": "Media uploads with R2",
+          "link": "/cloudflare/media-r2"
+        },
+        {
+          "text": "Deploy and operate",
+          "link": "/cloudflare/deploy-and-operate"
+        },
+        {
+          "text": "Mantle on ChatGPT Sites",
+          "link": "/cloudflare/chatgpt-sites"
+        }
       ]
     },
     {
       "text": "Examples",
       "items": [
-        { "text": "Examples", "link": "/examples/hub" }
+        {
+          "text": "Examples",
+          "link": "/examples/hub"
+        }
       ]
     },
     {
       "text": "Releases",
       "items": [
-        { "text": "Releases", "link": "/releases/index" }
+        {
+          "text": "Releases",
+          "link": "/releases/index"
+        }
       ]
     }
   ]

package/docs/handbook/reference/admin-descriptors.md

@@ -0,0 +1,88 @@
+# Generated Admin descriptors
+
+Experimental native preview; use the matching installed SDK/Admin versions.
+[Native Admin](../guides/native-admin.md) explains execution and mounting
+with `entries(bindings.schemas, bindings.adapter)`. Descriptors remain static
+data, not runtime authorization or a storage interpreter.
+
+`mantle generate` emits `admin-descriptors.ts`. Its exports are static data;
+importing a query does not import them. Selecting only `collections` also drops
+the developer snapshot and MCP catalogues from a bundle. No request-time parser,
+execution plan or SQL AST, storage access or execution observer is included.
+
+- `collections` matches the 0.2 navigation projection: translation Schemas fold
+  into their parents; composition, parent picker, media fields, indexed sorts,
+  enum filters and list presentation retain their declared field names.
+- `allCollections` includes translation and child editor descriptors by name.
+  `scopeField` identifies the private scope field; `exportFields` lists only
+  declared, exportable data fields (excluding scope/geo). CSV uses these facts
+  instead of guessing from row keys. `fieldNames` maps storage column names to authored names; `viewNames` does the
+  same for admin View outputs whose fields are read unchanged.
+- `views` and `operations` preserve the 0.2 admin descriptor shapes. Generated
+  publishing transitions stay out of Admin operations and WebMCP, preserving
+  the SPA's native Publish/Unpublish buttons. Operation
+  bindings use declared targets and version inputs; `preconditions` contains
+  necessary string (including enum) and boolean equality/IN predicates from one
+  target-row write. Numeric, temporal and JSON fields are skipped; these hints
+  do not authorize execution.
+- `authorizations` is a separate View/Procedure lookup for the generated Admin
+  handler to filter descriptors by the resolved Caller. These constants do not
+  authorize a request; session/admin gates and execution checks remain required.
+- `developerConsole` is the 0.2 data-model, logic, interface, relationship and
+  operations snapshot, derived once during generation. SQL logic is display
+  data, not executable IR. Observations remain unavailable and run history empty.
+- `mcpAppCatalogues` contains public/admin App catalogues. Row actions require
+  the same single-table, unchanged-id provenance as 0.2. Publishing transitions
+  use the actual `<schema>.<verb>` Procedures and canonical `<verb>_<schema>`
+  admin tool names. A conflicting declared admin tool is refused.
+- `webmcp` carries static tool declarations and Admin page routes. `bootstrap`
+  combines `collections`, `operations`, `views` and `webmcp`; the handler adds
+  request-owned `me`, `site` and any selected entries page.
+
+Generation reuses the 0.2 projection and SQL-logic helpers. View columns come
+from the compiled plan (Core's `viewOutputs` provenance, including aliases,
+stars, CTEs and subqueries). Translation
+metadata and selected execution share the generated translation policy. Child
+fields win; private scope fields cannot be overlaid by inherited parent fields.
+
+Pass declarations with `mantle generate --admin-extensions ./admin-extensions.mjs`.
+The module exports a named `adminExtensions` array or a default array; it should
+contain plain declarations, without constructing runtime services:
+
+```js
+export const adminExtensions = [{ id: 'audit', contributes: {
+  fields: [{ id: 'color', target: 'field.input/v1',
+    optionsSchema: { type: 'object', properties: { palette: { type: 'string' } } }
+  }]
+}}];
+```
+
+The programmatic generation options accept the same declarations:
+
+```ts
+await generateFromSources({ target, sources,
+  adminExtensions: [{ id: 'audit', contributes: {
+    fields: [{ id: 'color', target: 'field.input/v1',
+      optionsSchema: { type: 'object', properties: { palette: { type: 'string' } } }
+    }]
+  }}]
+});
+```
+
+Only `id` and `contributes` are needed at generation. `extensionBindings` records
+Schema/Procedure field widgets, Schema/admin View cells and sidebar panels.
+Unknown contributions, wrong targets and invalid options fail generation with
+`UI_EXTENSION_UNKNOWN`, `UI_EXTENSION_TARGET` or `UI_EXTENSION_OPTIONS`, retaining
+0.2 paths. Serving extension modules and handling extension actions is separate.
+
+`adminBindings()` provides the selected adapter and checked entry/View/operation
+bindings. The server shares native read templates across collections; descriptors
+carry compiler-verified policy/field fragments and generated validators, not a
+copy of full SQL for every order/direction. Metadata endpoints perform no storage
+read of their own; caller resolution and optional site/user enrichment may query.
+Statistics capability is advertised only when its native route is mounted.
+
+Full extension declarations also emit `extensionMetadata` and, with Admin selected,
+`admin-extensions.ts` with a runtime `extensionBindings` function and compiled
+settings checks. Native modules are host-served; install integrity in the host
+shell import map. `source` modules are refused.

package/docs/handbook/reference/authorization.md

@@ -1,76 +1,68 @@
----
-description: The requires block of Views and Procedures, its closed predicate vocabulary, guard rules, evaluation order and failure codes, and the Caller each predicate reads.
----
 # Authorization requirements
 
+Views and Procedures accept:
+
 ```yaml
 requires:
   auth:
-    all:                       # every predicate must hold
+    all:
       - ctx.user
-      - { ctx.staff: [owner, editor] }
+      - ctx.admin
       - { ctx.auth.scope: "exports:read" }
-  guard:
-    procedure: require-active-plan
 ```
 
-Both keys are optional; without `requires` anyone may call, including
-anonymous callers. Views and Procedures take the same block.
+| Predicate | Holds when |
+| --- | --- |
+| `ctx.user`, `ctx.auth` | Caller is a verified user |
+| `ctx.admin` | Caller is in the admin layer |
+| `{ ctx.auth.scope: "scope" }` | User scopes include that scope |
 
-## Predicates
+Selected REST, MCP and Admin boundaries accept an optional `authorize(target, caller)` callback. `Target`, exported by `@aotter/mantle/contracts`, contains `kind` (`view`, `procedure` or `schema`) and the manifest `name`; Admin generic entry routes also supply `action` (`read`, `create`, `update` or `delete`). The callback runs after credentials and `requires` pass, before execution and row policy. A false result or rejected promise returns `AUTH_DENIED` (HTTP 403); a synchronous exception is an internal error. MCP tool lists and Admin navigation metadata hide denied targets. Omitting the callback preserves existing behavior; direct generated typed functions do not invoke it.
 
-The vocabulary is closed (`AUTH_PREDICATE_NOT_IN_ENUM`). Each reads the
-request's [Caller](../concepts/authorization.md):
+An impersonated session exposes `caller.impersonatedBy`, the real actor’s subject, only on the original branded Caller; applications decide impersonation policy in `authorize(target, caller)`.
 
-| Predicate | Holds when |
-|---|---|
-| `ctx.user` | `caller.kind === "user"` |
-| `ctx.auth` | `caller.kind === "user"` (any verified credential) |
-| `{ ctx.staff: [owner \| editor \| contributor, …] }` | `caller.role` is one of the listed roles |
-| `{ ctx.auth.scope: "<scope>" }` | `caller.scopes` includes it; repeat for several |
+All predicates must hold. Anonymous/system callers satisfy none of these predicates. Without `requires`, the invocation is ungated, while Schema row policy still applies. Role lists such as `{ ctx.admin: [editor] }` are refused: decide per-target roles in application code. Role names match `^[a-z][a-zA-Z0-9_-]{0,62}$`; an invalid name in a verified user's role fails identity resolution and names the role. Better Auth’s admin plugin `adminRoles` (trimmed, default `["admin"]`) and `adminUserIds` determine the admin layer; Mantle has no role setting of its own.
+
+Dynamic `requires.guard` is rejected with `GENERATE_UNSUPPORTED`. Implement custom checks in app-owned handlers before executing queries. Generated TypeScript does not validate arbitrary external input; selected boundaries validate inputs, and direct callers must do so themselves.
+
+Predicate failure is `UNAUTHENTICATED` for a non-user or `AUTH_DENIED` for a user. Scope, TTL and publishing independently limit rows; see [authorization](../concepts/authorization.md).
+
+## User fields
 
-The system and anonymous callers satisfy none. Roles are not ranked here: list
-every role that may call.
+A user field is a value the identity provider verified on the user, such as `region`. It limits rows in two places only:
 
-## Guard
+- A Schema `scope` applies to every SQL relation, Store, REST/MCP and native Admin access: `scope: "region IN auth.user('region')"`. See [Schema](schema.md#field-scope).
+- A View or Procedure `restrict` applies to one target: `restrict: { orders: "region IN auth.user('region')" }`. See [View](view.md#restrict).
 
-`guard.procedure` names one Procedure that:
+Values come from the verified Better Auth user record. Declare stored fields with `input: false` in `user.additionalFields`, or produce derived fields through `customSession`. Session, OAuth and service credentials read roles, bans and stored fields from the same current database user record; customSession-only fields are refused on OAuth/service paths with `AUTH_CONFIGURATION_ERROR`. `input: false` protects only public endpoints. Anyone permitted to update users can change row-access field values through the admin API; control that authority with Better Auth access control (`user:update`, and `user:set-role` for roles). Store `{ all: true }` in a `json` additional field. Pass the generated `userFields` constant as `resolveCaller(request, auth, { fields: userFields })`.
 
-- is a `ref` handler (`GUARD_PROCEDURE_NOT_REF`), declared
-  (`GUARD_PROCEDURE_UNKNOWN`), not the Procedure itself
-  (`GUARD_SELF_REFERENCE`), and has no guard of its own
-  (`GUARD_CHAIN_NOT_ALLOWED`);
-- receives the target's validated input, so its own `input` schema must accept
-  the target's fields (leave `additionalProperties` open);
-- gets the same caller, a read-only `ctx.store`, and no `ctx.invoke`;
-- allows by returning and rejects by throwing. Throw a `DiagnosticError` to
-  choose the code; any other throw is a 500. Either way the target never runs.
+SQL cannot reference caller values: `auth.user()` fails with `USER_REF_SCOPE_ONLY`, and `auth.hasRole()` / `auth.role()` with `AUTH_ROLE_REMOVED`. Names are literals; Better Auth core fields and names beginning `mantle` are reserved.
 
-A guard runs on every call and is never cached.
+Values come from the original frozen Caller, which holds identity in a private WeakMap. Anonymous and copied/unbranded callers have no roles or user fields. Values are validated and frozen: finite numbers; strings of 1–256 UTF-8 bytes without NUL or lone surrogates; arrays of at most 64 items with duplicates removed, only for multi-valued fields. `{ all: true }` is the typed "every value" state of one field; storing it requires a Better Auth additional field of type `json`. Unknown user fields are discarded. A missing or empty value is refused before SQL runs (`UNAUTHENTICATED` for anonymous callers, otherwise `AUTH_DENIED`); it never matches every row. Never mint verified users from request data. Resolve credentials before constructing an identity, and pass the original Caller to generated operations.
 
-## Order
+## Gateway mode
 
-1. The service's `CallerResolver` (a failed credential is 401 here).
-2. `requires.auth.all`, in order: the first failure answers.
-3. `input` validation.
-4. The guard.
-5. The handler, then `output` validation.
+Selected `rest`, `mcp`, `admin` and `web` boundaries accept `gateway: { tenant: "example" }`. Forward the execution context: `api(request, env, ctx)` from `fetch(request, env, ctx)`. Set gateway mode on every boundary of the application, including web output (`web.fetch(request, env, ctx)` and `web.head(request, env, ctx)`). Only `ctx.props.mantle` supplies identity; absent props are anonymous. Application cookies and bearer tokens are ignored, and the application's auth instance is never loaded. Present `props.mantle` prevents falling back to application credentials. `props.mantle` on an entry without gateway mode fails with `HOST_CONTRACT` (412); the string-returning `web.head` throws this contract error.
 
-## Failures
+The v1 props contain `v: 1`, the configured `tenant`, `layer` (`admin` or `member`), `user` (`id`, optional `role` and declared user fields), `authenticatedAs` (`snapshot` or `fresh`), `credential` (`session` or `oauth`) and `requestId`. `target` and `targetHash` are required for admin callers and optional for members. The boolean `dryRun` is an optional forwarding control. `hostCaller(props, { tenant, fields })` from `@aotter/mantle/host-caller` validates and brands this shape. Generated boundaries supply inferred field types; manually composed boundaries may pass `fields`. Tests call `hostCaller(props, { tenant, fields })` with the same JSON.
 
-| Situation | HTTP | Code |
-|---|---|---|
-| a presented credential failed | 401 | `UNAUTHENTICATED` (with a `WWW-Authenticate` challenge on MCP mounts) |
-| an anonymous caller fails a predicate | 401 | `UNAUTHENTICATED` |
-| a signed-in caller fails a predicate | 403 | `AUTH_DENIED` |
-| a guard rejects | the guard's code, e.g. 402 | `ENTITLEMENT_REQUIRED` |
-| an OAuth token lacks a scope a tool requires (MCP) | 403 | `insufficient_scope` challenge |
+Admin-layer callers have kind `host`, subject `host:<id>` and the admin layer. Member-layer callers have kind `user`, subject `<id>` and no admin privilege, regardless of role names. Both retain ordinary scope checks and expose freshness, credential and request id to application code. Admin-layer callers see drafts; member management refuses host-built callers with 403 because gateway-mode applications load no Better Auth instance. Copies lose identity authority.
 
-The path of a predicate failure points at it:
-`manifest:Procedure/<name>#/requires/auth/all/<index>`.
+Snapshots may read only: SQL writes, Store/Admin mutations, publishing transitions and ref handlers fail before execution with `STALE_CALLER` (403). Boundary read classification comes from describe’s generated `_meta.readOnly`; generated SQL and Store writes retain their own freshness checks. Session writes keep origin checks. Both layers receive `{ error: { code, field?, target? } }`: 412 for invalid contracts, tenant mismatches or missing/empty required fields (naming the field), 403 for denials, and 400 for malformed bodies; never 401. MCP tool failures use the SDK error result with the same error fields.
 
-## Rows
+Pins use [describe](describe.md)'s `_meta.id`: `rest:<METHOD> <path>`, `admin:<METHOD> <path template>`, or the View/Procedure target for MCP and web. The route checks `target` and the generated target hash before execution: mismatches return 412 `TARGET_MISMATCH` or `TARGET_HASH_MISMATCH`. The generated `access-targets.ts` map loads only for gateway requests. Manually composed boundaries can supply an `accessTargets` loader returning the same metadata.
+
+MCP host callers may use `initialize` and `tools/call` of their pinned tool; batches stay refused and `tools/list` returns 403 because the host provides its catalogue.
+
+`dryRun: true` runs target/hash checks, input validation, generated caller checks, `authorize` and freshness, without SQL or side effects. It returns 200 `{ dryRun: true, event }`; MCP carries this result in the SDK tool response. Ref handlers, custom guards, uploads and opaque work return 412 `DRY_RUN_UNSUPPORTED`. Dry runs validate authority and input; they do not verify database state, row existence or OCC conflicts.
+
+Each boundary accepts `onAccess(event)`. Every forwarded request, including malformed contracts and denied requests in either layer, produces one event after its decision. Responses never await the hook; listener failures are swallowed and logged once per listener. Ordinary applications do not invoke it. The event is:
+
+```ts
+{ v: 1, requestId, target, targetHash,
+  caller: { kind, subject, layer },
+  outcome: "allow" | "deny" | "error", reason?, field?,
+  dryRun }
+```
 
-`requires` decides whether a caller may run the View or Procedure. Which rows
-it reaches comes from Schema `scope` and from `auth.uid()` in the SQL; see
-[Authorization](../concepts/authorization.md#rows-scope-and-authuid).
+`reason` is the error code. A successful dry run returns the same event the hook receives.

package/docs/handbook/reference/describe.md

@@ -0,0 +1,56 @@
+# Describe
+
+`mantle describe <target> <manifest>...` compiles manifests and prints JSON.
+An explicit target is required; use the generation target because hashes
+include the dialect. The command writes no project files. `--diff <old.json>` prints a JSON
+array of changes against a saved report.
+
+`describeApp(plan)` and `diffApp(a, b)` are exported by
+`@aotter/mantle/describe`. The `AppDescription` TypeScript type is the contract.
+`targetHash(plan, id)` is also exported by `@aotter/mantle/target-hash`.
+These exports use no Node APIs and load no SQL parser.
+
+The schemaVersion 1 report contains:
+
+- `access`: `plan.access.userFields`, mapping declared user fields to their
+  type, multiplicity and optional enum.
+- `targets`: MCP Tool-shaped objects with `name`, `title`, `description`,
+  `inputSchema`, `annotations` and `_meta`. View and Procedure names follow
+  MCP naming. Route inputs are plain objects with a name selector for known
+  dispatcher variants; their `variants` retain the selected input schemas.
+
+Each target’s `_meta` contains:
+
+- `id`: `view:<name>`, `procedure:<name>`, `rest:<METHOD> <path>` or
+  `admin:<METHOD> <path template>`. Parameters use `:name`; Admin paths are
+  relative to the API base. Publishing ids use `procedure:<schema>.<verb>`;
+  media tool ids use `admin:tool:<name>`.
+- `targetHash`: a hash of behavior, inputs, requirements, restrictions,
+  related Schema definitions, surfaces, Triggers and reachable hooks.
+  Optional lowering caches do not affect it. Ref registration keys are
+  included; application-owned handler implementations are not.
+- `scope` and `restrict`: per-Schema owner and user-field terms. Owner terms
+  use `owner`; user-field terms name their `column`, `field` and `type`.
+- `readOnly`: true only when all reachable statements are reads. Ref handlers
+  and routes without known dependencies are false.
+- `trustedOnly`, `opaque`, `unscopedReads`: trusted-only execution, ref-handler
+  opacity and reads of Schemas without row scope. Opaque code conservatively
+  includes every Schema available to its Store.
+- `surfaces` and `triggers`: every declared exposure and each Trigger’s id
+  and source. Views include `admin` for developer previews.
+- `requires`: conjunctive predicates in `all` and an optional `guard` name.
+  Admin-only targets include the admin gate.
+- `variants`: each selectable target’s id, input schema, requirements, flags
+  and row policies. Route restrictions contain terms common to all variants.
+
+Descriptions contain no SQL or rows. They describe declarations; application
+router additions and optional module mounting remain application-owned.
+
+Diff records contain `id`, `field`, `direction` and optional `before`/`after`.
+Removing a scope or restrict term widens access; adding one narrows it.
+Reading another Schema, dropping requirements, adding surfaces or Triggers,
+removing `readOnly` or `trustedOnly`, or enabling `opaque` or `unscopedReads`
+widens access. Variants are compared separately. Adding a target widens;
+removing one narrows. Every input schema change is `changed`, as are other
+behavior changes. Directions describe individual changes, not an overall
+proof when several fields change.

package/docs/handbook/reference/diagnostics.md

@@ -1,85 +1,21 @@
----
-description: The structured Diagnostic shape, the wire error envelope, HTTP statuses, and the diagnostic codes Mantle 0.2.0 raises from mantle generate, boot and run time.
----
-# Diagnostics
+# Diagnostics and errors
 
-Every refusal is a `Diagnostic`, from `mantle generate` to a REST call:
+Generation returns diagnostics with `code`, `path` and `message`. Grammar/SQL errors retain compiler codes and source locations. `GENERATE_UNSUPPORTED` identifies declarations or boundary features the native generator cannot honor; it must not silently omit behavior.
 
-```ts
-interface Diagnostic {
-  code: DiagnosticCode;          // the catalog below
-  phase: "validate" | "boot" | "runtime" | "test";
-  severity: "error" | "warning";
-  path: string;                  // where: a manifest pointer, a route, a field
-  message: string;               // for people; never parse it
-  source?: { sourceId, documentIndex, path, … };   // the manifest file and document
-  value?: unknown; expected?: string; candidates?: string[]; suggestion?: string;
-  failure?: { outcome: "not-applied" | "partial" | "unknown"; retry: "never" | "after-change" | "safe" | "reconcile"; resource? };
-  conflict?: { opIndex?: number; reason: "lock" | "expect" | "unique" };
-}
-```
+Bare queries preserve native errors except required conflict/uncertain-write classifications. At a JSON boundary, `wire(error)` or `surfaceFailure(error)` from `@aotter/mantle/contracts` redacts unclassified native failures. Selected generated REST/MCP/Admin boundaries apply their own error envelopes.
 
-`mantle generate` prints `CODE path: message`; a SQL diagnostic's message
-starts with `SQL <line>:<column> near "<token>"`. Over HTTP a failure is
-`{ "error": <diagnostic> }` with the status below; internal details are
-redacted. Over MCP it is a tool error result carrying the same code.
-Handler code catches `DiagnosticError` and reads `error.diagnostic.code`.
+| Core code | HTTP | Meaning |
+| --- | --- | --- |
+| INPUT_VALIDATION_FAILED | 400 | Invalid external input, paging or Store operation |
+| UNAUTHENTICATED | 401 | Caller lacks required authenticated authority |
+| AUTH_DENIED | 403 | Predicate, role or session-origin refusal |
+| NOT_FOUND | 404 | Missing or excluded resource |
+| METHOD_NOT_ALLOWED | 405 | Path exists for another method |
+| CONFLICT | 409 | Unique clash, stale lock or failed row/state guard |
+| OUTCOME_UNKNOWN | 503 | Write may have committed; reconcile without automatic retry |
 
-## Run time
+Unknown errors map to redacted `INTERNAL_ERROR` (500). A custom `ContractError` outside the core set must carry an explicit status. Media uses its selected `mediaError` contract. Never expose SQL errors, tokens or credentials.
 
-| Code | HTTP | Meaning |
-|---|---|---|
-| `INPUT_VALIDATION_FAILED` | 400 | input against its schema, a failed `check`, a malformed body or query |
-| `UNAUTHENTICATED` | 401 | no caller, or a presented credential that failed |
-| `ENTITLEMENT_REQUIRED` | 402 | a guard found no entitlement |
-| `AUTH_DENIED` | 403 | a signed-in caller fails a predicate or a role, or a cross-origin session write |
-| `NOT_FOUND` | 404 | no such route, View, row or operation for this caller |
-| `METHOD_NOT_ALLOWED` | 405 | |
-| `CONFLICT` | 409 | a lock, a row op that wrote nothing, a unique index; `conflict` says which and which op |
-| `LIFECYCLE_HOOK_REJECTED` | 409 | for a before hook that rejects with it |
-| `PRECONDITION_FAILED` | 412 | |
-| `RATE_LIMITED` | 429 | |
-| `INTERNAL_ERROR`, `OUTPUT_VALIDATION_FAILED` | 500 | a handler threw something that is not a `DiagnosticError`, or returned what `output` refuses |
-| `RESOURCE_UNAVAILABLE`, `OUTCOME_UNKNOWN`, `PARTIAL_FAILURE` | 503 | storage was unreachable; after `OUTCOME_UNKNOWN` the write may or may not have applied, so retry with the same ids and locks |
-| `RESOURCE_EXHAUSTED` | 507 | |
-| `INVOCATION_DEPTH_EXCEEDED` | 500 | more than 8 nested invocations (hooks and `ctx.invoke`) |
-| `PROCEDURE_NOT_FOUND` | 500 | `invokeProcedure` with a name the plan lacks |
-| `SITE_NOT_CONFIGURED` | 501 | Admin's `/site-settings` on a runtime without site defaults |
-| `MEDIA_*` | 400, 404, 409, 410, 501 | media uploads: `MEDIA_NOT_CONFIGURED` (501) without media storage and site defaults, `MEDIA_UPLOAD_EXPIRED` (410), `MEDIA_ASSET_NOT_FOUND` (404), `MEDIA_OBJECT_NOT_FOUND` and `MEDIA_CHECKSUM_MISMATCH` (409), and 400 for a refused type, size, purpose or variant set |
+The runtime runs no DDL or schema checks. Schema installation and failures belong to [the native migration tool](../concepts/runtime-and-adapters.md#schema-installation-and-migrations), not a boot diagnostic.
 
-Admin's statistics route answers 501 with the wire code
-`STATISTICS_UNAVAILABLE`, which is not a `DiagnosticCode`. `DISPATCHER_NOT_BUILT`
-(501) is in the catalog and not raised by 0.2.0.
-
-## Boot
-
-| Code | Meaning |
-|---|---|
-| `HANDLER_NOT_REGISTERED`, `HANDLER_NOT_DECLARED` | the handlers map lacks a plan ref, or has one the plan lacks |
-| `PLAN_FINGERPRINT_MISMATCH` | the plan is not the expected one, or was compiled for another dialect or plan version |
-| `SCHEDULE_NOT_WIRED` | an enabled schedule Trigger without `schedules: true` |
-| `STORAGE_CHANGE_BLOCKED` | storage has a difference boot will not change; the message names it and hints SQL |
-| `STORAGE_TABLE_NOT_OWNED` | a table Mantle would create exists and is not Mantle's |
-| `INVALID_LOCALE`, `SCHEMA_LOCALIZED_REQUIRES_SITE_LOCALES` | a site `locales` entry that is not a language with an optional 2-letter region, or a `localized` Schema without site `locales` |
-
-## `mantle generate`
-
-| Codes | About |
-|---|---|
-| `INVALID_MANIFEST_ENVELOPE`, `DUPLICATE_NAME`, `MANIFEST_ROOT_NOT_FOUND`, `MANIFEST_READ_FAILED` | files and the envelope; a `v1` apiVersion fails here and names the upgrade guide; `x-mantle-bind` fails and names its replacements (`spec.scope`, `auth.uid()`, `now()`) |
-| `REQUIRED_FIELD_UNKNOWN`, `INVALID_PATTERN`, `JSON_SCHEMA_UNSUPPORTED`, `JSON_SCHEMA_REF_INVALID`, `JSON_SCHEMA_LIMIT_EXCEEDED` | JSON Schemas |
-| `SCHEMA_INDEX_INVALID`, `SCHEMA_INDEX_FIELD_UNKNOWN`, `UNIQUE_INDEX_FIELD_UNKNOWN`, `SCHEMA_SEARCH_INVALID`, `SCHEMA_SEARCH_FIELD_UNKNOWN`, `SCHEMA_TTL_INVALID`, `SCHEMA_TTL_TRANSLATION_UNSUPPORTED`, `SCHEMA_UI_INVALID`, `SCHEMA_NAME_CASE_COLLISION`, `FIELD_NAME_CASE_COLLISION`, `MANTLE_REF_INVALID` | Schemas |
-| `UI_EXTENSION_INVALID`, `UI_EXTENSION_UNKNOWN`, `UI_EXTENSION_TARGET`, `UI_EXTENSION_OPTIONS` | Admin extensions, at `createAdminSurface`: a declaration it cannot honor, and a `uiSchema` contribution name that is missing, of the wrong target, or given options its `optionsSchema` refuses |
-| `TRANSLATES_PARENT_UNKNOWN`, `TRANSLATES_REQUIRES_LOCALIZED`, `TRANSLATES_REQUIRES_CONTENT_FIELD`, `TRANSLATES_FIELD_NOT_IN_PARENT`, `TRANSLATES_FIELD_NOT_IN_CHILD`, `TRANSLATES_PARENT_IS_LOCALIZED` | `translates` |
-| `VIEW_INPUT_INVALID_SHAPE`, `VIEW_INPUT_RESERVED_NAME`, `VIEW_CACHE_INVALID`, `VIEW_UI_INVALID` | Views |
-| `SQL_SYNTAX`, `SQL_UNSUPPORTED`, `SQL_FUNCTION`, `SQL_RELATION`, `SQL_COLUMN`, `SQL_WRITE`, `SQL_SHAPE`, `SQL_TYPE` | View and Procedure SQL, with a position |
-| `AUTH_PREDICATE_NOT_IN_ENUM`, `GUARD_PROCEDURE_UNKNOWN`, `GUARD_SELF_REFERENCE`, `GUARD_PROCEDURE_NOT_REF`, `GUARD_CHAIN_NOT_ALLOWED`, `PROCEDURE_TARGET_INVALID` | `requires` and `target` |
-| `TRIGGER_TARGET_PROCEDURE_UNKNOWN`, `TRIGGER_PATH_COLLISION`, `TRIGGER_PATH_INVALID`, `SCHEDULE_INPUT_INVALID`, `SCHEDULE_AUTH_INVALID`, `LIFECYCLE_SCHEMA_UNKNOWN`, `LIFECYCLE_TARGET_NOT_REF` | Triggers |
-| `MCP_TOOL_NAME_COLLISION`, `MCP_TOOL_DESCRIPTION_MISSING` (warning), `MCP_TOOL_INPUT_UNION_AMBIGUOUS`, `MCP_TOOL_INPUT_UNBOUNDED` | MCP tools |
-| `GENERATE_FEATURE_DEPENDENCY_MISSING` | a selected feature, identity, host or dialect whose package is not installed, or `admin` with identity `none`; the message carries the install command |
-
-A schedule Trigger whose cron Cloudflare cannot run the same way, or any
-enabled schedule Trigger on host `bun`, fails with exit 1 as
-`Trigger <name>: <message>` before anything is written.
-
-`FIXTURE_SCHEMA_VIOLATION` is reserved for consumer test diagnostics.
+User-field generation diagnostics are `AUTH_ROLE_REMOVED` (`auth.role` / `auth.hasRole`), `USER_REF_SCOPE_ONLY` (`auth.user` outside `scope` / `restrict`), `USER_FIELD_INVALID` (literal name/value or template grammar), `USER_FIELD_POSITION` (SET of a partition) and `USER_FIELD_CONFLICT` (column type/enum disagreement, or a reference to a field-scoped Schema without its scope terms). Warnings are `USER_FIELD_VALUES_UNENUMERATED` (no enum list), `USER_SCOPE_PUBLIC_ANON_EMPTY` (anonymous public reads are refused), `USER_SCOPE_ADMIN_VALUES` (an admin target reads field-scoped rows) and `USER_SCOPE_JOIN_DROPS` (a join of Schemas scoped by different fields). A generated app supplies the literal USER_REFS_V1 bind capability version; a mismatch throws `USER_REFS_VERSION` before native SQL.