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

package/docs/handbook/reference/authorization.md

@@ -1,295 +1,68 @@
----
-description: The requires grammar — closed auth predicates, guard Procedures, staff roles, HandlerContext, evaluation order and the 401/402/403 mapping.
----
-# Authorization
+# Authorization requirements
 
-`requires` is the whole authorization grammar. It appears on [Procedure](./procedure.md) and [View](./view.md) and nowhere else; Schemas and Triggers carry no `requires`. This page is the field-level contract and the runtime behaviour it produces. The narrative version is [Authorization](../concepts/authorization.md), and a worked deployment is [Guarded API](../../examples/cf-primitives-guarded-api.md). Diagnostic codes named here are catalogued in [Diagnostics](./diagnostics.md).
-
-## `requires`
+Views and Procedures accept:
 
 ```yaml
-spec:
-  requires:
-    auth:
-      all:
-        - ctx.auth
-        - ctx.user
-        - { "ctx.auth.scope": "orders:read" }
-    guard:
-      procedure: require-active-subscription
+requires:
+  auth:
+    all:
+      - ctx.user
+      - ctx.admin
+      - { ctx.auth.scope: "exports:read" }
 ```
 
-| Key | Type | Required | Rules |
-|---|---|---|---|
-| `requires` | mapping | no | Omitted means the target is anonymous. Only `auth` and `guard` are accepted. |
-| `requires.auth` | mapping | no | Only `all` is accepted. `any`, `none` and negation do not exist in v0.1. |
-| `requires.auth.all` | array | yes when `auth` is present | Non-empty array of predicates. Every entry must pass. |
-| `requires.guard` | mapping | no | Exactly one key, `procedure`, holding a non-empty Procedure name. |
-
-`auth` and `guard` are independent: a target may declare a guard with no static predicates, or predicates with no guard. Shape violations are `INVALID_MANIFEST_ENVELOPE` with a JSON Pointer to the offending key.
-
-## Predicates
+| 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 |
 
-The vocabulary is closed. A bare string form is either `ctx.user` or `ctx.auth`; an object form carries exactly one key.
+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.
 
-| Predicate | Written as | Passes when |
-|---|---|---|
-| Signed-in user | `ctx.user` | `ctx.user` is not `null`. A service API key with no user subject fails this. |
-| Verified credential | `ctx.auth` | `ctx.auth` is present, that is, the adapter verified some credential. There is no credential-kind predicate. |
-| Scope | `{ "ctx.auth.scope": "orders:read" }` | `ctx.auth.scopes` contains that exact opaque string. Repeat the predicate under `all` to require several scopes. |
-| Staff role | `{ "ctx.staff": [owner, editor] }` | `ctx.staff` is present and `ctx.staff.role` is one of the listed roles. This is exact membership, not role-or-above. |
+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)`.
 
-| Validation rule | Diagnostic |
-|---|---|
-| Predicate is one of the four forms above. | `INVALID_MANIFEST_ENVELOPE` at `/spec/requires/auth/all/<i>` |
-| Object form has exactly one key, `ctx.staff` or `ctx.auth.scope`. | `INVALID_MANIFEST_ENVELOPE` |
-| `ctx.auth.scope` value is a non-empty string. | `INVALID_MANIFEST_ENVELOPE` |
-| `ctx.staff` value is a non-empty array of strings. | `INVALID_MANIFEST_ENVELOPE` |
-| Every `ctx.staff` role is `owner`, `editor` or `contributor`. | `AUTH_PREDICATE_NOT_IN_ENUM` |
+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.
 
-Scope strings are opaque to Core. Mantle neither issues credentials nor defines a scope catalog; the deployment owns both.
+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.
 
-## Denial
+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).
 
-Predicates are evaluated in declaration order and the first failure denies the call.
+## User fields
 
-| Caller state | Code | HTTP |
-|---|---|---|
-| No `ctx.auth`, no `ctx.user` and no `ctx.staff`. | `UNAUTHENTICATED` | `401` |
-| Authenticated in any of those three ways but a predicate is unsatisfied. | `AUTH_DENIED` | `403` |
+A user field is a value the identity provider verified on the user, such as `region`. It limits rows in two places only:
 
-Both diagnostics carry the failing predicate's position: the `path` is `<target path>#/requires/auth/all/<i>`, where `<target path>` is `manifest:Procedure/<name>` or `manifest:View/<name>` unless the caller supplied its own prefix. `expected` describes the predicate in prose; the offending value is not echoed. An auth-gated View invoked with no caller context at all is denied `UNAUTHENTICATED` at `<target path>#/requires/auth` before any predicate runs.
+- 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).
 
-## Guards
+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 })`.
 
-`requires.guard.procedure` names one ordinary Procedure. It is not a fifth atom, and it is not a policy language: it is a handler that is allowed to say no.
+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.
 
-- The guard receives the target's **already-validated** input (Procedure) or params (View) and the **same** `HandlerContext`.
-- It runs through the identical pipeline: its own `requires.auth.all`, its own `input` schema, its handler, its `output` schema.
-- It runs on every call and is never cached.
-- It fails closed. Any non-`ok` guard result is returned to the caller unchanged and the target handler is never invoked.
+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, integers when the field scopes an `integer` column; 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.
 
-| Rule | Diagnostic | Where checked |
-|---|---|---|
-| The named Procedure is declared. | `GUARD_PROCEDURE_UNKNOWN` | validate and runtime |
-| A Procedure does not guard itself. | `GUARD_SELF_REFERENCE` | validate and runtime |
-| The guard uses `handler.kind: ref`, not `builtin`. | `GUARD_PROCEDURE_BUILTIN` | validate and runtime |
-| The guard does not itself declare `requires.guard`. Guard chains are one level deep, never more. | `GUARD_CHAIN_NOT_ALLOWED` | validate and runtime |
+## Gateway mode
 
-All four report at `<target path>#/requires/guard/procedure`; diagnostics raised inside the guard itself are prefixed `<target path>#/requires/guard/<guard name>`. The runtime repeats every check the validator already made, so a boot-bypassing embedding still fails closed.
+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.
 
-A guard denies by throwing a `DiagnosticError` carrying a runtime diagnostic. `ENTITLEMENT_REQUIRED` (`402`) is the conventional code for "verified caller, current business state says no" — an expired subscription, a revoked entitlement, an unpaid invoice. Any other runtime code works the same way and maps through the [status table](./diagnostics.md#runtime).
+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.
 
-## Staff roles
+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.
 
-| Role | Rank | Capabilities |
-|---|---|---|
-| `owner` | 3 | Full control. Staff list, role changes, invitations, site settings, developer console. |
-| `editor` | 2 | Publish, unpublish, delete and manage all entries; media uploads and assets; member list. |
-| `contributor` | 1 | Create and edit drafts. Cannot create or edit operational records, and cannot edit an entry that is no longer `draft`. |
+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.
 
-`users` is the base identity layer; `staff` is a privilege overlay with one row per privileged user, so `ctx.staff.id` always equals `ctx.user.id`. A signed-in user with no staff row is an ordinary site member with no Admin access and no `/mcp/staff` access.
+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.
 
-Rank ordering exists for "this role or above" gates — Admin's own route table uses it, so an `owner` passes an `editor`-gated Admin route. Generic staff MCP tools (including Admin WebMCP) use the same rank table: contributors may call `create_draft_*` / `update_draft_*`; publish, unpublish, archive, delete, media, and operational `create_record_*` / `update_record_*` require editor or owner. Declared Procedures still use their own `requires.auth.all`. The manifest predicate does not rank-order: `{ "ctx.staff": [editor] }` admits editors only. List every role you mean.
+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.
 
-The adapter re-reads the caller's current role from the database on every protected request. A role is never taken from a token, a consent snapshot or a cached catalog, so a demotion takes effect on the next call.
+`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.
 
-## `HandlerContext`
-
-Handlers, guards and predicate evaluation all see the same normalized value.
+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
-interface HandlerContext<Env = unknown> {
-  readonly user: { readonly id: string } | null;
-  readonly staff: { readonly id: string; readonly role: StaffRole } | null;
-  readonly auth?: {
-    readonly credential: "session" | "oauth" | "api-key" | "personal-token";
-    readonly credentialId: string | null;
-    readonly clientId: string | null;
-    readonly scopes: readonly string[];
-  };
-  readonly env: Env;
-  readonly waitUntil?: (p: Promise<unknown>) => void;
-  readonly event?: HandlerLifecycleEvent;
-}
-```
-
-| Field | Notes |
-|---|---|
-| `user` | `{ id }` of the site-local user row, or `null`. The id is the deployment's own user record, never a platform or upstream-provider subject. |
-| `staff` | Privilege overlay, or `null`. |
-| `auth` | Present only after a credential verified. `credentialId` is an opaque record id or token identifier; `clientId` names the OAuth client when there is one; `scopes` is the granted set. |
-| `env` | Adapter bindings. |
-| `waitUntil` | Platform fire-and-forget bridge, when the adapter has one. |
-| `event` | Populated only when the Procedure runs as a lifecycle hook target. See [Trigger](./trigger.md). |
-
-Raw credentials never enter this object: no cookie value, no API key, no bearer token, no refresh token. Resolution precedence on the Cloudflare adapter is the deployment's own credential resolver, then configured OAuth bearer verification, then the cookie session; a recognized-but-invalid credential is rejected outright and never falls back to a valid cookie. See [Authentication](../cloudflare/authentication.md).
-
-## Order of evaluation
-
-The order is fixed and identical on REST, MCP and in-process invocation.
-
-| Step | Procedure | View |
-|---|---|---|
-| 1 | Adapter verifies and normalizes the credential. | Same. |
-| 2 | `requires.auth.all` against the context. | `requires.auth.all` against the context. |
-| 3 | `input` validated and coerced. | `params` validated and coerced. |
-| 4 | Guard invoked with the validated value and the same context. | Guard invoked with the validated params and the same context. |
-| 5 | Handler dispatched. | Query executed. |
-| 6 | `output` validated. | Rows paginated and returned. |
-
-Static predicates run before input validation on purpose: an unauthorized caller learns that it is unauthorized, not what the input schema looks like.
-
-## Views
-
-Two consequences follow from that order.
-
-- **Static auth precedes param validation.** A protected View never reports a parameter error to a caller that failed its predicates.
-- **The guard authorizes the query, not the rows.** It sees the validated params and returns pass or fail for the whole call. It cannot rewrite the filter, drop columns or remove rows.
-
-Row-level scoping is a separate mechanism, described in [Views](../concepts/views.md): the closed `{ "$ctx.user": "id" }` filter sentinel. The caller never supplies that value, so the same View is safe on REST and on public MCP. Core rejects the sentinel unless the View declares `ctx.user` in `requires.auth.all` and the compared field is the leftmost field of a declared Schema index; a missing identity is `401`, never a dropped filter or a full-table read. The field-level rules are in [View](./view.md#value-forms).
-
-## Example
-
-```yaml
-apiVersion: cms.mantle.aotter.net/v1
-kind: Procedure
-metadata:
-  name: require-active-subscription
-spec:
-  title: Require an active subscription
-  input: { type: object }
-  output: { type: object }
-  handler: { kind: ref, ref: requireActiveSubscription }
----
-apiVersion: cms.mantle.aotter.net/v1
-kind: Procedure
-metadata:
-  name: download-report
-spec:
-  title: Download a report
-  requires:
-    auth:
-      all:
-        - ctx.user
-        - ctx.auth
-        - { "ctx.auth.scope": "reports:read" }
-    guard: { procedure: require-active-subscription }
-  input:
-    type: object
-    required: [reportId]
-    properties:
-      reportId: { type: string }
-  output:
-    type: object
-    required: [url]
-    properties:
-      url: { type: string, format: uri }
-  handler: { kind: ref, ref: downloadReport }
----
-apiVersion: cms.mantle.aotter.net/v1
-kind: Trigger
-metadata:
-  name: download-report-http
-spec:
-  source: { kind: http, method: POST, path: /api/reports/download }
-  target: { procedure: download-report }
----
-apiVersion: cms.mantle.aotter.net/v1
-kind: View
-metadata:
-  name: my-reports
-spec:
-  title: My reports
-  surface: public
-  from: reports
-  requires:
-    auth:
-      all: [ctx.user]
-    guard: { procedure: require-active-subscription }
-  filter:
-    and:
-      - { eq: { field: status, value: published } }
-      - { eq: { field: ownerId, value: { "$ctx.user": id } } }
-  fields: [title, publishedAt]
-  orderBy: [{ field: publishedAt, direction: desc }]
-  limit: 50
+{ v: 1, requestId, target, targetHash,
+  caller: { kind, subject, layer },
+  outcome: "allow" | "deny" | "error", reason?, field?,
+  dryRun }
 ```
 
-The guard handler denies with a structured diagnostic rather than a thrown string, so the boundary emits `402` instead of the `INTERNAL_ERROR` envelope:
-
-Because `my-reports` is guarded and binds `$ctx.user`, it must not declare `View.spec.cache`. Shared View caching is reserved for caller-independent anonymous reads; `VIEW_CACHE_INVALID` rejects guarded or identity-bound combinations.
-
-```ts
-import { DiagnosticError, runtimeDiagnostic } from "@aotter/mantle/spec";
-import type { HandlerContext } from "@aotter/mantle/runtime";
-
-export const requireActiveSubscription = async (
-  _input: unknown,
-  ctx: HandlerContext<{ DB: D1Database }>,
-) => {
-  const active = await ctx.env.DB
-    .prepare("SELECT 1 FROM site_memberships WHERE user_id = ? AND state = 'active' LIMIT 1")
-    .bind(ctx.user!.id)
-    .first();
-  if (active) return {};
-  throw new DiagnosticError(
-    runtimeDiagnostic({
-      code: "ENTITLEMENT_REQUIRED",
-      severity: "error",
-      path: `site:membership/${ctx.user!.id}`,
-      message: "An active subscription is required.",
-    }),
-  );
-};
-```
-
-`site_memberships` is deployment-owned. Core creates no credential, entitlement or billing tables and reads no payment-provider state.
-
-## OpenAPI projection
-
-`mantle emit-openapi` reflects authorization into the emitted OpenAPI 3.1 document. Only schemes the deployment actually accepts are configured, and only those become alternatives.
-
-| Manifest | OpenAPI |
-|---|---|
-| Any `requires.auth.all` predicate | `security` alternatives drawn from the configured `sessionCookie`, `oauthBearer`, `apiKey` and `personalToken` schemes, plus `x-mantle-auth-predicates`, a `401` response and a `403` response. |
-| Repeated `{ "ctx.auth.scope": … }` | OAuth scopes on the `oauthBearer` alternative, plus `x-mantle-required-scopes`. |
-| `requires.guard.procedure` | `x-mantle-guard-procedure` and a `402` response. |
-| No `requires` | No `security` requirement and no auth responses. |
-
-Cookie sessions are emitted as cookies, never relabelled as bearer tokens. A protected target with no configured security scheme is an emission error, not a silently unprotected operation. MCP is out of scope for the emitter; required scopes and guard behaviour reach agents through the standard Tool description, and every `tools/call` re-runs the predicates and the guard. Discovery is never the enforcement boundary — see [MCP and agents](../concepts/mcp-and-agents.md).
-
-Configure the accepted schemes through the public API:
-
-```ts
-import { EmitOpenapiUseCase } from "@aotter/mantle/spec";
-
-const { document } = EmitOpenapiUseCase.run({
-  linked, // successful linkManifestSet result
-  title: "Site API",
-  version: "1.0.0",
-  security: {
-    sessionCookie: false,
-    oauthBearer: {
-      openIdConnectUrl:
-        "https://platform.example.com/api/auth/.well-known/openid-configuration",
-    },
-    apiKey: { in: "header", name: "X-API-Key" },
-    personalToken: { bearerFormat: "PAT" },
-  },
-});
-```
-
-## Source
-
-- [`packages/mantle-spec/src/domain/model/ManifestGrammar.ts`](../../../packages/mantle-spec/src/domain/model/ManifestGrammar.ts)
-- [`packages/mantle-spec/src/domain/service/ManifestParser.ts`](../../../packages/mantle-spec/src/domain/service/ManifestParser.ts)
-- [`packages/mantle-spec/src/domain/service/ManifestGraphValidator.ts`](../../../packages/mantle-spec/src/domain/service/ManifestGraphValidator.ts)
-- [`packages/mantle-spec/src/domain/service/StaffRoleHierarchy.ts`](../../../packages/mantle-spec/src/domain/service/StaffRoleHierarchy.ts)
-- [`packages/mantle-spec/src/usecase/EmitOpenapiUseCase.ts`](../../../packages/mantle-spec/src/usecase/EmitOpenapiUseCase.ts)
-- [`packages/mantle-runtime/src/domain/model/HandlerContext.ts`](../../../packages/mantle-runtime/src/domain/model/HandlerContext.ts)
-- [`packages/mantle-runtime/src/domain/service/AuthPredicateEvaluator.ts`](../../../packages/mantle-runtime/src/domain/service/AuthPredicateEvaluator.ts)
-- [`packages/mantle-runtime/src/usecase/procedure/InvokeProcedureUseCase.ts`](../../../packages/mantle-runtime/src/usecase/procedure/InvokeProcedureUseCase.ts)
-- [`packages/mantle-runtime/src/usecase/view/ExecuteViewUseCase.ts`](../../../packages/mantle-runtime/src/usecase/view/ExecuteViewUseCase.ts)
-- [`packages/mantle-admin/src/mountMantleAdmin.ts`](../../../packages/mantle-admin/src/mountMantleAdmin.ts)
-- [`packages/adapters/cloudflare/src/mount/mountMcp.ts`](../../../packages/adapters/cloudflare/src/mount/mountMcp.ts)
+`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.