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

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,84 +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 |
-| `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.

package/docs/handbook/reference/features.md

@@ -1,53 +1,45 @@
----
-description: A task-to-feature table for Mantle 0.2.0 manifests — what to declare for each common need, with links to the field reference and an example.
----
-# Manifest feature reference
-
-| You need | Declare | Reference | Example |
-|---|---|---|---|
-| A table | a Schema with a JSON Schema | [Schema](./schema.md) | every example |
-| Authored content with drafts and publishing | `lifecycle: publishing` (the default) | [Lifecycle](../concepts/lifecycle-and-locales.md) | [Publication](../../examples/publication.md) |
-| Records written by the system | `lifecycle: operational` | [Lifecycle](../concepts/lifecycle-and-locales.md) | [Intake form](../../examples/intake.md) |
-| Rows only their owner may ever see | `scope: { owner: auth.uid() }` | [Authorization](../concepts/authorization.md) | reference service `orders` |
-| A member sees their own rows, staff see all | store `auth.uid()` in the SQL, filter `WHERE x = auth.uid()` | [Authorization](../concepts/authorization.md) | [Procurement](../../examples/procurement.md) |
-| A rule every write obeys | `checks: ["stock >= 0"]` | [Schema](./schema.md#checks) | [Commerce inventory](../../examples/commerce-inventory.md) |
-| Uniqueness | `uniqueIndexes` | [Schema](./schema.md#indexes) | [Commerce](../../examples/commerce.md) |
-| Full-text search | `searchableFields` and `mantle.search` | [View](./view.md) | [Publication](../../examples/publication.md) |
-| Places | `format: geo` and `mantle.near` / `mantle.distance` | [View](./view.md) | |
-| Rows that expire | `ttl`, then `sweepExpired` | [Lifecycle](../concepts/lifecycle-and-locales.md#ttl) | |
-| Translations | `localized`, `translates` | [Schema](./schema.md#localized-and-translates) | [Publication](../../examples/publication.md) |
-| A public read | a View, `surface: public` | [View](./view.md) | every example |
-| A staff report with CSV | a View, `surface: staff`, `uiSchema.list` | [Admin](../guides/admin-ui.md) | [Reservation](../../examples/reservation.md) |
-| A read only code uses | a View, `surface: internal` | [Query from TypeScript](../guides/typed-queries.md) | [Commerce inventory](../../examples/commerce-inventory.md) |
-| Joins, aggregates, windows | the View's SQL | [View](./view.md#what-the-d1-dialect-accepts) | reference service `sales-by-item` |
-| A write | a Procedure with `handler: { sql }` | [Procedure](./procedure.md) | every example |
-| Several writes, all or nothing | several statements in one `sql` | [Procedure](./procedure.md#handlersql) | reference service `place-order` |
-| An upsert | `INSERT … ON CONFLICT (…) DO UPDATE` | [Procedure](./procedure.md) | reference service `restock` |
-| No lost updates | `WHERE id = input.id AND version = input.expectedVersion` | [Procedure](./procedure.md#row-ops-and-set-ops) | [Commerce](../../examples/commerce.md) |
-| Code: call a service, read then write, set `status` | `handler: { ref }` | [Procedure](./procedure.md#handlerref) | [Commerce inventory](../../examples/commerce-inventory.md) |
-| An HTTP route | a Trigger `kind: http` | [Trigger](./trigger.md#http) | every example |
-| An agent tool | a Trigger `kind: mcp`, or a View | [MCP and agents](../concepts/mcp-and-agents.md) | every example |
-| An Admin operation | a Trigger `kind: mcp, surface: staff` | [Admin](../guides/admin-ui.md) | [Procurement](../../examples/procurement.md) |
-| Signed-in callers only | `requires: { auth: { all: [ctx.user] } }` | [Authorization requirements](./authorization.md) | [Procurement](../../examples/procurement.md) |
-| Staff roles | `{ ctx.staff: [owner, editor] }` | [Authorization requirements](./authorization.md) | [Commerce](../../examples/commerce.md) |
-| API keys and scopes | a custom `CallerResolver`, `{ ctx.auth.scope: … }` | [Authorization](../concepts/authorization.md) | [Guarded API access](../../examples/guarded-api.md) |
-| A live check before one action | `requires.guard` | [Authorization requirements](./authorization.md#guard) | [Intake with bot check](../../examples/intake-hooks.md) |
-| A rule before every write of a Schema | a `before_*` lifecycle Trigger | [Trigger](./trigger.md#lifecycle) | |
-| Side effects after a write | an `after_*` lifecycle Trigger | [Trigger](./trigger.md#lifecycle) | [Intake with bot check](../../examples/intake-hooks.md) |
-| A recurring job | a Trigger `kind: schedule` (POSIX cron) | [Trigger](./trigger.md#schedule) | [Commerce inventory](../../examples/commerce-inventory.md) |
-| A signed webhook | a route in the service's `fetch`, then `runtime.invokeProcedure` | [Writes](../concepts/procedures-and-triggers.md#webhooks) | [Commerce inventory](../../examples/commerce-inventory.md) |
-| Media uploads | `d1Storage(db, { site })` and `r2MediaStorage` | [Media uploads with R2](../cloudflare/media-r2.md) | |
-
-## Not in 0.2.0
-
-| 0.1.x feature | In 0.2.0 |
-|---|---|
-| builtin handlers (`create`, `update`, `upsert`, `delete`, `archive`) | SQL statements; `archive` is a `ref` handler setting `status` |
-| the Filter AST, `params`, `$param`, `$ctx.user` | the View's SQL, `input`, `input.<name>`, `auth.uid()` |
-| `page` / `show` | `limit` / `cursor` |
-| `x-mantle-bind` | `scope`, or `auth.uid()` / `now()` in the SQL |
-| generated record tools on Staff MCP | declared Procedures with `mcp` Triggers |
-| `errorPolicy` on lifecycle hooks | before hooks fail closed; after hooks are best effort |
-| deferred hooks on a Queue | after hooks run after the commit; a queue is the service's own |
-| Mantle-rendered public pages, templates, sitemap | not ported; render from your own `fetch` |
-| `mantle validate`, `emit-openapi`, `mantle skills` | `mantle generate` and `mantle generate --check` |
+# Supported declarations
+
+The native 0.2.0 SDK compiles the closed v2 grammar for four targets. Generation diagnostics, rather than historical APIs or release plans, define the checked-out implementation. Existing integrations require explicit app wiring and data migration; initial schema.sql is for an empty database.
+
+## Supported
+
+| Feature | Availability / agent action |
+| --- | --- |
+| Closed v2 Schema/View/Procedure grammar, PostgreSQL SQL authoring | Generated for Bun SQLite, Bun PostgreSQL, Cloudflare D1 and Cloudflare PostgreSQL; dialect behavior stays native. |
+| Operational Schemas, scope, TTL read visibility, indexes, checks, native SQL facilities | Generated initial DDL and compiled SQL policy; run migrations and TTL maintenance in application code. |
+| System-only TTL maintenance | Generated `<schema>.sweepExpired`, bounded cursor scans and optional dry-run; app owns `scheduled()` wiring and cron configuration. See [TTL maintenance](../guides/native-execution.md#ttl-maintenance). |
+| Typed SQL Views and Procedures, auth predicates, OCC, atomic writes | Generated bare queries accept validated inputs and a verified Caller; date/date-time outputs are ISO strings, native errors stay internal. |
+| Typed Store collections and internal Views/Procedures | Shared Store, AND-only filters, indexed non-null keyset ordering, atomic batches; interactive transactions on SQLite/PostgreSQL. |
+| Searchable fields, Store search and SQL search/rank | Generated SQLite/D1 FTS5 trigram table and maintenance triggers; PostgreSQL ILIKE. Store find/first trim non-empty search and match exact id OR declared fields, within the caller's row rules. |
+| Better Auth integration and Workers builds | App owns `auth.ts` and `resolveCaller`; optional [OAuth helpers](../guides/oauth.md) provide consent/connected apps, live grant/session checks and DPoP. `mantle generate` emits native Wrangler build configuration. Keep heavy auth imports lazy. |
+| Transactional email port, English templates and dev console sender | Optional `@aotter/mantle/email`; app supplies the sender and passes locale through. See [email wiring](../guides/email.md). |
+| View keyset pages, generated boundary validation and HTTP error mapping | Generated `paged/views/*` for proved exposed/internal Views: indexed non-null tuples, complete groups and singleton joins/lookups; `validation/*` and `wire`; see [surface contracts](surface.md). |
+| REST and `http` Trigger exposure | Supported generated `rest.ts`; app mounts with `{ db, caller }` and required `handlers` for ref contracts. Public Views page at `/api/views/<name>`; HTTP Triggers keep method/path. |
+| Generated MCP and `mcp` Trigger exposure | Public/admin tools, shared generated checks, publishing transitions on admin only; SDK loads on matching requests. Install the official MCP peer for manifests selecting this surface. |
+| Dynamic `web.ts` (`llms.txt`, sitemap, `.md` alternates, head tags) | Generated; mount `web({ ... })`; see [surface contracts](surface.md#optional-web-output). |
+| Native Admin bindings, server and console | Supported; select `--admin` / `admin: true` and mount `entries(bindings.schemas, bindings.adapter)`. Shared authorized read templates, native Procedure writes and the console; see [Native Admin](../guides/native-admin.md).  |
+| Localized Schemas and translations | Plain-string locale values, atomic published-parent guard, SQL parent visibility and generated page locale helper; see [Translations](../concepts/lifecycle-and-locales.md#translations). |
+| Opt-in `lifecycle: publishing` | Generated status, `published_at`, admin-only transitions and published-only public reads; see [Publishing](../concepts/lifecycle-and-locales.md). |
+| `ref` Procedures and typed `Handlers` | Generated `Handlers` type; pass implementations at `store(db, caller, { handlers })`; `mantle generate` lists them. See [ref Procedures](../guides/native-execution.md#ref-procedures). |
+| Optional site settings and media | Select `site` defaults at generation to emit the generated `site` module and deployment tables; native media upload lifecycle, app-owned R2/signing. See [media](../cloudflare/media-r2.md). |
+
+## Refused
+
+Each unsupported declaration produces `GENERATE_UNSUPPORTED`, its manifest path,
+and the following hint. Invalid grammar/SQL retains the compiler's own diagnostic
+codes and paths. Multiple declarations produce multiple diagnostics.
+
+| Declaration | Do instead |
+| --- | --- |
+| `schedule` Triggers, including disabled ones | Wire `scheduled()` yourself. |
+| `lifecycle` Triggers: before/after hooks, including targets using `ref` | Write a custom handler. |
+| `requires.guard` on a View or Procedure | Write a custom handler that checks authorization before executing queries. |
+| A View projecting a native `geo` value | Select the latitude and longitude columns explicitly. |
+| Dynamic or repeated View output names | Give each SELECT output a unique explicit alias. |
+| Declared date/date-time outputs without one SELECT item per output | Expand the SELECT list explicitly. |
+| Input properties differing only in case | Rename input properties to be unique without regard to case. |
+| PostgreSQL JSON/date/date-time parameters used without the declared cast | Wrap each occurrence in the concrete `CAST(... AS <type>)` shown by the diagnostic. |
+
+
+Store handles simple AND reads and writes; use internal Views for OR, joins, aggregates and reuse. Ref Procedures are supported with a typed caller/transaction-bound Store. See [typed queries](../guides/typed-queries.md), [lifecycle/locales](../concepts/lifecycle-and-locales.md) and [database ownership](../concepts/runtime-and-adapters.md).

package/docs/handbook/reference/manifest.md

@@ -1,74 +1,11 @@
----
-description: The manifest envelope of Mantle 0.2.0 — apiVersion, kind, metadata, files and documents, names, localized text, and the SQL naming conventions every atom shares.
----
-# Manifest envelope and conventions
+# Manifest envelope
 
-```yaml
-apiVersion: cms.mantle.aotter.net/v2
-kind: Schema            # Schema | View | Procedure | Trigger
-metadata:
-  name: orders          # required, unique per kind
-spec: { … }             # kind-specific
-```
+Every YAML document has `apiVersion: cms.mantle.aotter.net/v2`, `kind`, `metadata.name` and `spec`. Kinds are Schema, View, Procedure and Trigger. Pass explicit file paths to `mantle generate`; a file may contain several documents separated by `---`.
 
-- `apiVersion` is exactly `cms.mantle.aotter.net/v2`. A `v1` document fails
-  and names the upgrade guide.
-- `metadata` has `name` only.
-- Unknown keys anywhere in `spec` are refused, not ignored.
+The grammar is closed. Unknown keys and invalid declarations fail generation. Names are unique per kind; Schema and field names cannot differ only by case. Quote non-identifier Schema names in SQL. `input` and `auth` are reserved.
 
-## Files
+Titles and descriptions accept a string or locale map, such as `{ en: Products, zh-TW: 商品 }`. Selected UI/MCP chooses the configured locale with fallback.
 
-`mantle generate` reads every `.yaml` and `.yml` file directly in the manifest
-directory (`./manifests`, or `--manifests <dir>`), not subdirectories. A file
-may hold several documents separated by `---`. File names and order do not
-matter to the plan; they enter only `sourceHash`.
+Author SQL in PostgreSQL syntax. Generation renders it for postgres or sqlite, including bound inputs and compiled row policy. SQL native columns use `id`, `version`, `created_at`, `updated_at`, `author_id`, plus `status` / `published_at` for publishing. Store uses storage names too. Manifest index declarations use authored field/native names (`createdAt`), which compile to storage names.
 
-## Names
-
-- Names are unique per kind (`DUPLICATE_NAME`). Two Schemas, or two fields of
-  one Schema, may not differ only in case: SQL resolves identifiers
-  case-insensitively.
-- A Schema name that is not a plain identifier (`support-tickets`) is written
-  quoted in SQL: `"support-tickets"`.
-- `input` and `auth` are reserved and cannot name a Schema or an alias. On
-  the `sqlite` dialect, SQL may not name a Schema, field or alias that is one
-  of the 14 words SQLite refuses unquoted (`SQL_UNSUPPORTED`):
-  `add alter autoincrement commit delete drop escape index insert nothing raise set transaction update`.
-- MCP tool names are the View or Procedure name in snake case.
-
-## Localized text
-
-`title` and `description` on every atom, and `title` and `description` on
-JSON Schema properties, take a string or a locale map:
-
-```yaml
-title: { en: Products, zh-TW: 商品 }
-```
-
-Admin chooses the viewer's locale and MCP the surface's `locale` option (default `en`), then `en`, then the first entry.
-
-## SQL conventions
-
-| | |
-|---|---|
-| Syntax | PostgreSQL, parsed by PostgreSQL 18's parser; a dialect decides what runs |
-| Native columns | snake_case in SQL: `id`, `status`, `version`, `created_at`, `updated_at`, `author_id`. In `ctx.store` JSON, in `indexes` and in Schema `uiSchema`: `createdAt`, `updatedAt`, `authorId` |
-| References | `input.<name>`, `auth.uid()`, `auth.role()`, `now()` |
-| Mantle functions | `mantle.search`, `mantle.search_rank`, `mantle.near`, `mantle.distance` |
-| Literals | SQL literals; strings in single quotes |
-| Multi-line SQL | a YAML block scalar (`sql: \|`) |
-
-## Wire values
-
-| JSON Schema | On the wire |
-|---|---|
-| `format: date-time`, and the native `createdAt` / `updatedAt` | an ISO 8601 string |
-| `format: date` | `YYYY-MM-DD` |
-| `boolean` | `true` / `false` |
-| `object`, `array` | JSON |
-
-## Generated output
-
-`plan.json` and `mantle.ts` under `.mantle/generated/` are rewritten by every
-`mantle generate` and compared by `--check`. Commit them; never edit them. See
-[Project layout and CLI](../start/project-and-cli.md).
+Use `input.<name>`, `auth.uid()`, `now()` and supported `mantle.*` functions. Only declared relations and allowed SQL constructs may be referenced. See [Schema](schema.md), [View](view.md), [Procedure](procedure.md), [Trigger](trigger.md) and [CLI](../start/project-and-cli.md).