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

package/docs/handbook/cloudflare/service-entry.md

@@ -1,138 +1,242 @@
----
-description: The generated src/service.ts and src/index.ts of a Mantle 0.2.0 Cloudflare service — how the surfaces are mounted, and how to add your own routes, bindings and scheduled work.
----
-# The service and its entry
-
-On host `cloudflare`, `mantle generate` writes two files once, then they are
-yours (host `bun` writes a `Bun.serve` entry instead, ADR-0038):
-
-- `src/service.ts` composes the service: storage, identity, surfaces, and the
-  `mantle` object from `createMantle`;
-- `src/index.ts` is the Cloudflare entry: `fetch` and `scheduled`.
-
-Mantle owns no route of its own. What is mounted, and where, is this code.
-
-## `src/service.ts`
-
-With identity `mantle` and every feature (the
-[reference service](../../examples/reference-service/src/service.ts) is this
-file, unchanged):
+# Application-owned service composition
+
+Read the exact installed SDK/Admin versions. The [Native Admin guide](../guides/native-admin.md)
+is the authority for generated collection bindings and retained console behavior.
+
+The app owns `fetch`, native database handles, pools, auth options and deployment.
+Select generated modules by importing them; omitted modules stay out of the bundle.
+Keep application routing source outside
+the generated directory. The [auth template](authentication.md), [surface contracts](../reference/surface.md)
+and [media wiring](media-r2.md) describe the selected capabilities.
+
+Mount auth (including discovery), consent, Admin, MCP and REST in that order,
+matching 0.2. `authRoutes` owns both auth and consent paths. Supply one lazy,
+request-local resolver to those surfaces, memoizing read-only and fresh authority
+separately so a cached read cannot authorize a write. All cookie-session mutations
+use the shared origin check. A custom identity
+supplies the same verified `Caller`; absent directory/role facets remain absent.
+Never construct a system Caller from credentials or request input.
+
+Generate `Env` from the Wrangler config; do not hand-write it. Declare secrets
+under `secrets.required`, run `pnpm exec wrangler types --include-runtime=false`,
+add `worker-configuration.d.ts` to `tsconfig.json` and commit it.
+`@cloudflare/workers-types` still supplies runtime types. Rerun after every binding
+change; `wrangler types --include-runtime=false --check` fails on drift.
+Once `secrets.required` is set, `wrangler dev` loads only those keys from
+`.dev.vars`/`.env`, so declare every secret the app reads.
 
 ```ts
-function mount(runtime: MantleRuntime, env: Env) {
-  const auth = createAuth(env, origin);                       // createMantleAuth, or a setup-incomplete stub
-  const resolver = createCallerResolver(auth, { jwtBearer: { audience: `${origin}/mcp`, scopes: ["mcp"] } });
-  const authRoutes = createAuthRoutes(auth, { resolver });
-  const guard = (surface, options?) => withCaller(resolver, surface, options);
-  const admin = guard(createAdminSurface(runtime, { basePath: "/admin", assets: (path) => adminAsset(env.ASSETS, path), identity: { … }, site: { mcpEndpoints: { public: "/mcp", staff: "/mcp/staff" } } }));
-  const mcp = guard(createMcpSurface(runtime, { basePath: "/mcp", surface: "public", resourceMetadata }), { resourceMetadata });
-  // MCP Apps hosts render each staff View's rows, and the operations on one row, in the chat
-  const staffMcp = guard(createMcpSurface(runtime, { basePath: "/mcp/staff", surface: "staff", apps: { resources: [planApp(runtime.plan, { surface: "staff", html: mantleAppHtml })] }, resourceMetadata }), { resourceMetadata });
-  const rest = guard(createRestSurface(runtime, { basePath: "/api" }));
-  return async (request, waitUntil) => {
-    const owned = await authRoutes(request, { waitUntil });
-    if (owned) return owned;
-    if (under("/admin")) return admin(request);
-    if (under("/mcp/staff")) return staffMcp(request);
-    if (under("/mcp")) return mcp(request);
-    return rest(request);
-  };
-}
-
-const service: MantleService<Env> = {
-  handlers,
-  fetch: (request, env, { runtime, waitUntil }) => (routes ??= mount(runtime, env))(request, waitUntil),
+// src/worker.ts — application-owned; choose imports for the features you use.
+import { authLoader, resolveCaller } from '@aotter/mantle/auth';
+import { authRoutes } from '@aotter/mantle/auth/routes';
+import { withAuthTasks } from '@aotter/mantle/auth/hardening';
+import { checkOrigin, surfaceFailure, type Caller } from '@aotter/mantle/contracts';
+import { admin, adminShell } from '@aotter/mantle-admin/server';
+import { adminMcpApps } from '@aotter/mantle-admin/mcp';
+import { entries } from '@aotter/mantle-admin/server/entries';
+import { adminBindings } from '../generated/admin-bindings.js';
+import { mcpAppCatalogues } from '../generated/admin-descriptors.js';
+import { mcp } from '../generated/mcp.js';
+import { rest } from '../generated/rest.js';
+import { handlers } from './handlers.js'; // omit when there are no ref Procedures
+
+// Env comes from worker-configuration.d.ts: declare DB, ASSETS, the email provider binding
+// and the PUBLIC_ORIGIN, BETTER_AUTH_SECRET and ADMIN_EMAIL secrets in Wrangler.
+// createAuth(env) is exported by the app's src/auth.ts (see the auth template).
+let auth: import('@aotter/mantle/auth').AuthLoader<ReturnType<typeof import('./auth.js').createAuth>> | undefined;
+export default {
+  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
+    return withAuthTasks(ctx.waitUntil.bind(ctx), async () => {
+      auth ??= authLoader(() => import('./auth.js').then(m => m.createAuth(env)));
+      const headers = new Headers(); // retain Better Auth's sliding-session cookies
+      let authority: Promise<Caller> | undefined, readAuthority: Promise<Caller> | undefined;
+      const resolve = (readOnly: boolean) => resolveCaller(request, auth!, {
+        readOnly,
+        audience: [`${env.PUBLIC_ORIGIN}/mcp`, `${env.PUBLIC_ORIGIN}/mcp/admin`],
+        responseHeaders: headers,
+      }).then(value => { checkOrigin(request, value); return value; });
+      const caller = (_request?: Request, _env?: Env, classification = { readOnly: false }) =>
+        classification.readOnly ? readAuthority ??= resolve(true) : authority ??= resolve(false);
+      const options = { db: (env: Env) => env.DB, caller, handlers };
+      const bindings = adminBindings({ handlers }); // use adminBindings() without ref Procedures
+      const routes = [
+        authRoutes(auth, { methods: [{ kind: 'email-otp' }], resolver: caller }),
+        admin(bindings.metadata, bindings.views, bindings.operations, {
+          ...options, developerViews: bindings.developerViews, routes: entries(bindings.schemas, bindings.adapter),
+        }),
+        mcp({ ...options, apps: { admin: adminMcpApps({ catalogue: mcpAppCatalogues.admin }) } }),
+        rest(options),
+      ];
+      try {
+        for (const route of routes) {
+          const response = await route(request, env);
+          if (!response) continue;
+          if (!headers.getSetCookie().length) return response;
+          const result = new Response(response.body, response);
+          for (const cookie of headers.getSetCookie()) result.headers.append('set-cookie', cookie);
+          return result;
+        }
+        // Serves the built Admin shell for /admin and its client routes; undefined for any other path.
+        const shell = await adminShell(request, path => env.ASSETS.fetch(new Request(new URL('/admin/' + path, request.url), request)));
+        if (shell) return shell;
+        // Your public frontend/web.ts routes can use an anonymous Caller without
+        // loading auth; their generated SQL still controls publication visibility.
+        // Mounted here, after every Mantle surface, a root catch-all page (/:slug)
+        // cannot shadow /admin, /mcp or REST. Mount them earlier only behind a
+        // guard that skips those paths, as the app shell does.
+        return new Response('Not found', { status: 404, headers: { 'cache-control': 'no-store' } });
+      } catch (error) { return surfaceFailure(error); }
+    });
+  },
 };
-
-export const mantle = createMantle(service, { plan, storage: (env) => d1Storage(env.DB), schedules: true });
 ```
 
-- `Env` lists the bindings and vars the service reads. Add yours there.
-- The surfaces are built once per isolate, on the first request.
-- With identity `custom` the resolver is your `src/identity.ts`; with `none`
-  every surface gets `{ kind: "anonymous" }` and no auth routes are mounted.
+Keep the MCP and REST entries together for the normal symmetric path. For a deliberate
+asymmetric exception, remove the omitted surface's imports and array entry. `mcp.ts`
+exists only when the manifest has an MCP surface and requires the documented optional
+MCP peer. An application that deliberately does not mount MCP need not import generated
+`mcp.ts`; outside the entry import graph, it contributes nothing to the bundle.
+Pass the same handlers to each selected surface that exposes ref Procedures.
+Bind site/media/identity capabilities through the selected Admin/MCP
+options; do not expose native auth administrative routes without `authRoutes` or
+`guardAuthAdminRequest`. `withAuthTasks` retains background callbacks on the
+current request's context; `authHardening` configures the background handler.
+Select `--admin` to emit `admin-bindings.ts`. Admin's API is a separate
+`@aotter/mantle-admin` package; the SDK never imports it. The API handles only
+`/admin/api`. `adminShell` (in the block above) serves the built shell for `/admin` and
+client routes, including `/admin/sign-in`; it sets `frame-ancestors 'none'`, `X-Frame-Options: DENY`, `no-store` and `nosniff`
+on the shell, answers a missing file under `/admin` with a 404 `Response`, and returns `undefined` for other paths and
+non-GET requests. The app owns the rest of the CSP and the asset cache headers.
+Collection statistics use the generated shared `statisticsView`:
+its collection parameter selects only a generated table and visibility policy.
+
+## Workers assets and secrets
+
+`mantle generate --admin --wrangler wrangler.jsonc` sets the selected assets
+directory. A new assets block defaults to `binding: "ASSETS"`, `run_worker_first: true`
+and `html_handling: "none"`. Existing blocks keep their binding and routing; when
+`run_worker_first` is already true, a missing `html_handling` defaults to `none`.
+A different binding needs a custom Admin HTML loader. Deploy the built assets and
+Worker together.
+
+`mantle generate cloudflare-d1 generated manifests/*.yaml --auth src/auth.ts --admin`
+updates the split-build Wrangler keys (`main` and `base_dir` under `dist/worker`),
+ensures `nodejs_compat` and defaults to `global_fetch_strictly_public` ([public fetch routing](deploy-and-operate.md#public-fetch-routing))
+and, with `--admin`, `assets.directory`: `mantle bundle` builds Admin into
+`dist/client/admin`, served at `/admin`. Configure existing assets blocks explicitly;
+JSONC comments and unrelated settings survive regeneration:
 
-## Add your own routes
+```jsonc
+{
+  "assets": {
+    "directory": "dist/client",
+    "binding": "ASSETS",
+    "run_worker_first": true,
+    "html_handling": "none"
+  },
+  "d1_databases": [{ "binding": "DB", "database_name": "your-database", "database_id": "your-id" }]
+}
+```
 
-Put them in the function `mount` returns, where they belong in the order:
+`run_worker_first` lets the application supply shell/security/cache headers;
+`none` keeps `index.html` available by name. `adminShell(request, assets)` passes
+paths relative to the Admin directory, so the app fetches them under `/admin/`:
+`path => env.ASSETS.fetch(new Request(new URL("/admin/" + path, request.url), request))`. Admin assets are not a public database
+API. PostgreSQL uses application-owned Hyperdrive/postgres.js wiring,
+with Hyperdrive query caching disabled for authority and mutation visibility.
 
-```ts
-return async (request, waitUntil) => {
-  const { pathname } = new URL(request.url);
-  await auth.ready?.catch((error) => { routes = undefined; throw error; }); // first, before any route answers
-  if (pathname === "/healthz") return new Response("ok");            // no caller
-  if (pathname === "/payments/callback") return handleCallback(request, runtime, env);
-  const owned = await authRoutes(request, { waitUntil });
-  if (owned) return owned;
-  …
-};
-```
+Commit `.dev.vars.example` containing variable names and placeholders only:
 
-- With identity `mantle`, keep `await auth.ready` above every route. `mount`
-  starts Better Auth inside an isolate's first request, and Workers cancels I/O
-  that a finished request started: a route that answers that first request
-  before `auth.ready` settles leaves the context pending for ever, and every
-  later request waits on it (under `wrangler dev` too). The wait costs only the
-  isolate's first request.
+```dotenv
+PUBLIC_ORIGIN=http://localhost:8787
+ADMIN_EMAIL=you@example.test
+BETTER_AUTH_SECRET=replace-with-a-random-secret
+```
 
-- A route that acts for a caller resolves it the same way:
-  `withCaller(resolver, (request, caller) => …)` gives you the caller, the 401
-  for a bad credential, and the cross-origin check.
-- Reach data through `runtime.store.as(caller)` or
-  `runtime.invokeProcedure({ procedure, input, caller, cause: { kind: "internal", id } })`;
-  `runtime.store` alone is unscoped, for trusted code only.
-- Server-rendered pages, a SPA's assets, a signed webhook: all are routes
-  here. Mantle renders no public pages in 0.2.0.
+Copy it to ignored `.dev.vars`; use deployment secrets for production. Configure
+an app-owned [`EmailSender`](../guides/email.md#application-wiring) and call its
+`send({ to, subject, text, html?, locale, category? })` from Better Auth's email
+callbacks. Adapt the auth template's `MAIL.otp`/`MAIL.link` callbacks to this
+sender; it is an object, not a `.dev.vars` value. The auth
+module wires `ADMIN_EMAIL` to the bootstrap helper, which requires verified email.
+Name the variables as your `auth.ts` reads them (the app shell uses these three) and keep the trusted origin consistent.
+
+## Scheduling and Bun
+
+Scheduling remains app-owned; schedule/lifecycle Triggers are refused. Import
+only the desired generated `sweepExpired` entry in `scheduled()`, pass a system
+Caller with a reason, and choose an application-owned page budget for each
+invocation; see the [TTL contract](../guides/native-execution.md#ttl-maintenance). Configure `triggers.crons` yourself;
+`toCloudflareCron` converts POSIX schedules without adding a dispatcher. Keep
+larger sweeps' cursors for a later invocation instead of scanning without a bound.
+
+On Bun, reuse a process-owned `Database` or `SQL` pool and call the same generated
+surfaces from `Bun.serve({fetch})`. Bun runs the server as TypeScript, so
+`mantle bundle` builds only Admin for it: the `bun-*` target that
+`generated/.mantle-inputs.json` records skips the Worker bundle, and Admin goes
+to `dist/client/admin` (`--assets` as on Workers) when the server imports
+`@aotter/mantle-admin/server`. Add it as the build script and run it before
+starting the server:
+
+```json
+{ "scripts": { "build": "mantle bundle src/server.ts dist" } }
+```
 
-## `src/index.ts`
+The optional host reader is independent of the query target:
 
 ```ts
-export default {
-  fetch: (request, env) => mantle.fetch(request, env, ctx),
-  async scheduled(controller, env) { … mantle.invokeSchedule(cron, controller.scheduledTime, env, ctx) … },
-} satisfies ExportedHandler<Env>;
+import { bunAdminAssets } from '@aotter/mantle/bun/assets';
+const assets = bunAdminAssets('dist/client/admin');
+const bindings = adminBindings({ handlers });
+const serveAdmin = admin(bindings.metadata, bindings.views, bindings.operations, {
+  db: () => db, caller, handlers, routes: entries(bindings.schemas, bindings.adapter),
+});
+// Call assets(path) from your separate shell/static route. adminShell(request, reader) wants
+// paths without a leading slash and a Response (404 when missing), so adapt the reader:
+const reader = async (path: string) => (await assets('/' + path)) ?? new Response(null, { status: 404 });
 ```
 
-- `ctx` is `{ waitUntil }` from `cloudflare:workers`, which is not bound to one
-  request, so a handler's `ctx.waitUntil` never lands on a finished request.
-- Manifest crons are POSIX; Cloudflare names a cron as `wrangler.jsonc` spells
-  it. The entry maps each Cloudflare cron back to every POSIX expression that
-  shares it, runs them all, and reports every failure together. A cron no
-  Trigger maps to throws.
-- There is no `queue` handler: no Mantle path produces queue messages. Add
-  your own `queue` beside `fetch` if your service uses one.
-
-## Bindings
+The reader returns a native `Response` or `null`, rejects traversal/control
+characters and escaping symlinks; the app owns shell, CSP and cache headers.
+Use ignored `.env` on Bun.
+
+Admin's build tools and UI packages are dependencies of `@aotter/mantle-admin`,
+so a production install carries them (about 65 MB). For a container image, use a
+multi-stage build: the build stage installs everything and runs `mantle bundle`
+and `bun build src/server.ts --target bun --outdir dist/server`; the runtime stage
+copies only `dist/` (plus any files the server reads at runtime) and starts
+`bun dist/server/server.js`. Neither the Admin assets nor the bundled server read
+`node_modules` once built. Run cron work with your native scheduler; neither
+imports nor ordinary requests execute DDL, migrations or cron work. OAuth resource
+rows are inserted on first OAuth use from runtime configuration, with no deploy
+step; auth initialization and cookie/bearer/MCP/REST requests do no resource work.
+
+## Commit generated output and verify it in CI
+
+Commit every file written by `mantle generate`: TypeScript, `schema.sql`, optional
+seed SQL and Wrangler edits. Never hand-edit generated output. Every emitted
+TypeScript/SQL file carries the ownership header. Add the line printed by
+generation to `.gitattributes`, for example:
+
+```gitattributes
+generated/** linguist-generated=true
+```
 
-`wrangler.jsonc` starts with `DB` (D1), or with dialect `postgres` a
-`HYPERDRIVE` binding whose `id` is a placeholder until
-`wrangler hyperdrive create <name> --caching-disabled --connection-string=…`
-gives one, `triggers.crons`, and with feature `admin` the console's files:
+Resolve generated merge conflicts by merging authored manifests/options first,
+then regenerating with the same options. Review the SQL/policy diff and write
+explicit migrations before deployment. Keep `dist/` (the `mantle bundle` output)
+untracked. Deployment uses committed generated source; it does not regenerate.
 
-```jsonc
-"assets": { "directory": "node_modules/@aotter/mantle-ui/dist/admin", "binding": "ASSETS", "run_worker_first": true, "html_handling": "none" }
+```sh
+# CI, with the project's exact installed SDK and peer versions:
+pnpm exec mantle generate cloudflare-d1 generated manifests/*.yaml --auth src/auth.ts --admin --check
+pnpm exec tsc --noEmit
+pnpm exec mantle bundle src/worker.ts dist   # dist/worker, and dist/client/admin with --admin
 ```
 
-`run_worker_first` sends every request through the Worker, so Admin answers
-every `/admin` path and nothing is served at the files' bare paths; keep it
-when you add assets of your own (serve those through the same binding or a
-route). `mantle generate` warns when `admin` is selected and no `ASSETS` is
-bound. Add the rest:
-
-| Need | `wrangler.jsonc` | Code |
-|---|---|---|
-| Media | `r2_buckets: [{ binding: "MEDIA", bucket_name: … }]` | [Media uploads with R2](./media-r2.md) |
-| A secret | `wrangler secret put NAME` (`.dev.vars` locally) | `env.NAME` |
-| A plain var | `vars: { NAME: "…" }` | `env.NAME` |
-| Email | `send_email: [{ name: "EMAIL" }]` | your `EmailSender` for sign-in, or a handler's `ctx.env.EMAIL` |
-| KV, Queues, Durable Objects | their usual keys | your own code; Mantle reads none of them |
-
-Handlers receive the same `env` as `ctx.env`. Mantle-owned rows are reached
-only through Store; never write a Schema's table with `env.DB` directly. Your
-own tables in the same database are yours.
-
-## When the preset changes
-
-The preset is never rewritten. After an SDK upgrade, compare your files with
-a fresh preset: generate into an empty directory with the same manifests and
-`mantle.config.json`, and diff `src/service.ts` and `src/index.ts`.
+`--check` regenerates in memory, lists missing/changed/obsolete SDK-owned files
+and stale Wrangler build settings, exits nonzero, and writes nothing. Unmarked
+application files are preserved. TOML generation prints manual edits, so an
+exact Wrangler `--check` requires JSON/JSONC. Use all the same `--site`, `--auth` and `--admin` options as normal generation. The check needs no database,
+network access, credentials or deployment. Imported configuration modules must
+remain pure: exporting `authOptions(env)` avoids constructing Better Auth at build time.

package/docs/handbook/concepts/authorization.md

@@ -1,126 +1,19 @@
----
-description: The Caller, the one CallerResolver at the service entry, requires predicates, guards, Schema scope and auth.uid(), and how staff roles fit.
----
 # Authorization
 
-Mantle never owns your users. The service resolves who is calling once per
-request, and Mantle enforces the manifests against that answer.
+The app verifies credentials and supplies a `Caller` from `@aotter/mantle/contracts`:
 
-## The Caller
+- Anonymous: `{ kind: 'anonymous' }`.
+- User: `kind`, stable opaque `subject`, optional `issuer`, `role: string | null`, `admin?: boolean`, `scopes`, `credential`, `credentialId` and `clientId`. Credentials are session, OAuth, API key or personal token; never put raw credentials in the Caller.
+- System: `{ kind: 'system', reason }`, constructed only by trusted application code for maintenance. Request data cannot grant system authority.
 
-```ts
-type Caller =
-  | { kind: "anonymous" }
-  | { kind: "user"; subject: string; issuer?: string; role: "owner" | "editor" | "contributor" | null;
-      scopes: readonly string[]; credential: "session" | "oauth" | "api-key" | "personal-token";
-      credentialId: string | null; clientId: string | null }
-  | { kind: "system"; reason: string };
-```
+Resolve once per request. Invalid presented credentials must fail; do not downgrade them to anonymous. Use `checkOrigin(request, caller)` for cookie-session mutations; generated boundaries enforce it too. Keep response cookie headers from `resolveCaller` so sessions can slide.
 
-- `subject` is the application's subject key: opaque, stable, unique across
-  every issuer, never an email. `auth.uid()`, a scope field and `author_id`
-  store it. A resolver over several identity providers namespaces it
-  (`chatgpt:<sub>`, `account:<id>`).
-- `role` is a staff role or `null`. Admin's vocabulary is `owner`, `editor`,
-  `contributor`; a resolver maps its own roles onto it, or leaves `null` and
-  uses scopes and guards.
-- The `system` caller comes only from host code (`systemCaller(reason)`):
-  schedules, maintenance, a verified webhook. No request can produce one.
+## Operations and rows
 
-## One boundary: `CallerResolver` and `withCaller`
+View/Procedure `requires.auth.all` gates invocation. `ctx.user` / `ctx.auth` require a user; `ctx.admin` requires the admin layer; `ctx.auth.scope` checks a scope. Which admin role may call which target is application code, decided before the call. [Requirements](../reference/authorization.md) lists the vocabulary. Store collections do not check these operation gates: authorize before using Store.
 
-```ts
-type CallerResolver = (request: Request) =>
-  Promise<{ caller: Caller } | { invalid: true; challenge?: string; status?: 401 | 403 }>;
-```
+The compiler adds row policy to every Schema relation, including joins and nested SQL. Scope limits a user to their subject or to their [user field](../reference/authorization.md#user-fields) values and gives anonymous callers no scoped rows. System calls bypass scope. TTL hides expired rows. Public Views see only published rows on publishing Schemas; caller reads expose drafts only to admin/system. Translations also retain parent visibility.
 
-The generated `src/service.ts` wraps every surface in
-`withCaller(resolver, surface)`:
+Field `scope` hides rows even from admin callers; use View/Procedure [`restrict`](../reference/view.md#restrict) to limit member access while Admin collection reads see all rows allowed by the Schema's scope.
 
-- A credential that was presented but fails is answered 401 before any
-  surface runs. It is never treated as anonymous; only "no credential" is.
-- A cookie session may not mutate across origins: a non-GET request with a
-  session needs a same-origin `Origin` or `Sec-Fetch-Site`, or it is 403.
-- Identity `mantle` resolves Better Auth sessions and OAuth bearer tokens;
-  identity `custom` is your `src/identity.ts`; identity `none` passes
-  `{ kind: "anonymous" }`. See [Authentication](../cloudflare/authentication.md).
-
-## `requires`
-
-Views and Procedures take the same block:
-
-```yaml
-requires:
-  auth:
-    all:
-      - ctx.user
-      - { ctx.staff: [owner, editor] }
-      - { ctx.auth.scope: "exports:read" }
-  guard: { procedure: require-active-plan }
-```
-
-| Predicate | Holds when |
-|---|---|
-| `ctx.user` | the caller is a `user` |
-| `ctx.auth` | the caller is a `user` (any verified credential) |
-| `{ ctx.staff: [roles] }` | the caller's `role` is one of them |
-| `{ ctx.auth.scope: "<scope>" }` | the caller's `scopes` include it; repeat for several |
-
-Every predicate in `all` must hold. A system or anonymous caller satisfies
-none. A failure is 401 `UNAUTHENTICATED` for an anonymous caller and 403
-`AUTH_DENIED` for a signed-in one. The optional guard is a `ref` Procedure
-that runs next and may reject with any code, for example
-`ENTITLEMENT_REQUIRED` (402).
-
-`requires` is checked on every path: REST, MCP, Admin operations,
-`ctx.invoke` and `runtime.invokeProcedure`. Listing a tool is not permission
-to call it.
-
-## Rows: scope and `auth.uid()`
-
-`requires` decides whether a caller may run a View or Procedure. Which
-**rows** it reaches is decided in the data:
-
-**Scope** hides rows from everyone but their owner:
-
-```yaml
-kind: Schema
-metadata: { name: orders }
-spec:
-  scope: { owner: auth.uid() }
-  indexes: [[owner]]
-  schema:
-    required: [owner, …]
-```
-
-- The scope field is a required string, the first column of an index, and the
-  first column of every `uniqueIndexes` entry.
-- Every read and write of a user caller is limited to rows whose `owner` is its
-  subject key; an anonymous caller reaches none. Store fills `owner` on insert,
-  and no write may set it, so a row can never move to another owner.
-- Staff are user callers too: scope hides other users' rows from them as
-  well. Use scope only for rows that no one but the owner may ever see.
-- `runtime.store` and the system caller are not scoped.
-
-**`auth.uid()` in SQL** covers the rest. When staff must see every row but a
-member sees only their own, store the writer and filter on it:
-
-```sql
-INSERT INTO requisitions (requestedBy, item) VALUES (auth.uid(), input.item);
-SELECT … FROM requisitions WHERE requestedBy = auth.uid();
-```
-
-The writer comes from the caller, never from an input. See
-[Procurement approvals](../../examples/procurement.md).
-
-## Admin
-
-Admin's gate admits any staff role, and each Admin route names the least role
-it needs. Admin reads and writes through `runtime.store.as(caller)`, so scope
-and `requires` apply to staff exactly as to anyone. See
-[Customize Admin](../guides/admin-ui.md).
-
-## Further reading
-
-- [Authorization reference](../reference/authorization.md)
-- [Guarded API access](../../examples/guarded-api.md)
+The app owns custom identity and roles. Better Auth’s admin plugin `adminRoles` (default `["admin"]`) classifies comma-separated `user.role` values. `resolveCaller` carries this layer as `admin`; `isAdmin(caller)` and `hasAdminRole(caller, name)` consult it. Callers come from `resolveCaller` over Better Auth; an existing identity provider connects through Better Auth's OAuth or SSO plugins, since no public API builds a Caller from another provider's session (`authenticatedAs` in `@aotter/mantle/testing` is for tests). Setting `admin: true` on a plain object grants no privilege. Member role names alone do not grant privilege. Optional [Better Auth](../cloudflare/authentication.md) helpers use fresh primary authority by default. Admin additionally requires an admin cookie session. UI visibility never replaces a server authorization check.

package/docs/handbook/concepts/four-atoms.md

@@ -1,97 +1,14 @@
----
-description: The four manifest atoms of Mantle 0.2.0 (Schema, View, Procedure, Trigger), what each compiles to, and how they reference each other.
----
 # The four atoms
 
-Every manifest document is one atom:
+The manifest grammar is closed: Schema, View, Procedure and Trigger.
 
-```yaml
-apiVersion: cms.mantle.aotter.net/v2
-kind: Schema | View | Procedure | Trigger
-metadata: { name: <name> }
-spec: { … }
-```
+| Atom | Declares | Native output |
+| --- | --- | --- |
+| Schema | Fields, indexes, scope, TTL, lifecycle and Admin presentation | Initial DDL and typed Store collection |
+| View | One SQL SELECT with input, authorization and surface | Typed query; optional paging and exposure |
+| Procedure | SQL statements or a ref handler contract | Typed operation with declared authorization |
+| Trigger | HTTP or MCP exposure of a Procedure | Selected route/tool binding |
 
-| Atom | Declares | Compiles to | Code |
-|---|---|---|---|
-| **Schema** | rows: a JSON Schema of fields, indexes, `checks`, scope, TTL, lifecycle | one table (`STRICT` on SQLite) with native columns and one column per scalar field | none |
-| **View** | a read: one SQL `SELECT`, its `input`, `surface` and `requires` | validated SQL IR in the plan | none |
-| **Procedure** | a write: `input`, `output`, `requires` and a handler, either SQL statements or a `ref` | IR for `sql`, a name for `ref` | only `ref` |
-| **Trigger** | when a Procedure runs: an HTTP route, an MCP tool, a lifecycle hook or a schedule | a binding in the plan | none |
+Generation rejects lifecycle and schedule Triggers, although they exist in the v2 grammar. Application code owns scheduling and side effects. Unknown manifest keys fail validation; a new runtime capability does not open the grammar.
 
-Views read and Procedures write; a View never writes and a Procedure's SQL
-holds write statements only. Custom code exists only behind a Procedure's
-`ref`.
-
-## How they reference each other
-
-```
-Trigger ──target──▶ Procedure ──SQL writes / ctx.store──▶ Schema
-                       ▲  │                                  ▲
-         requires.guard│  └─ctx.invoke──▶ Procedure          │
-                       │                                     │
-View ────────────SQL SELECT (joins, subqueries)──────────────┘
-Trigger(lifecycle) ◀── a write to its Schema
-```
-
-- A View's or Procedure's SQL names Schemas by `metadata.name`; a name that is
-  not a plain identifier is quoted (`"support-tickets"`).
-- A Trigger targets one Procedure. A lifecycle Trigger also names the Schema
-  it watches.
-- `requires.guard` names a `ref` Procedure that runs before the target.
-- `x-mantle-ref` on a field points at another Schema's `id` or unique field;
-  Admin uses it to relate rows and bind operations.
-
-`mantle generate` links every reference and refuses a dangling one, a
-duplicate name, or two names that differ only in case.
-
-## Native columns
-
-Every Schema table carries native columns that Store fills and no write may
-set:
-
-| SQL name | Store JSON name | Meaning |
-|---|---|---|
-| `id` | `id` | text id, generated unless a `ref` handler passes `ctx.store.id()` |
-| `status` | `status` | `draft`, `published` or `archived`; on a `publishing` Schema only (an `operational` one has no `status` column) |
-| `version` | `version` | starts at 1, bumps on every write; the optimistic lock |
-| `created_at`, `updated_at` | `createdAt`, `updatedAt` | timestamps |
-| `author_id` | `authorId` | the subject key of the caller that created the row |
-
-SQL spells them snake_case; the JSON of `ctx.store` keeps camelCase. A Schema
-field may not reuse these names.
-
-## Values in SQL
-
-| Reference | Is |
-|---|---|
-| `input.<name>` | a declared `input` property |
-| `auth.uid()` | the caller's subject key (`NULL` for an anonymous caller) |
-| `auth.role()` | the caller's staff role, or `NULL` |
-| `now()` | the invocation time |
-| `mantle.search(t, q)`, `mantle.search_rank(t)`, `mantle.near(...)`, `mantle.distance(...)` | full-text search and geo functions |
-
-A SQL literal is a literal. There are no `$`-prefixed references and no
-positional `$1`.
-
-## What the runtime adds
-
-Every Schema reference in every statement, joins and subqueries included, is
-rewritten before it runs:
-
-- **Scope**: on a Schema with `scope`, a user caller sees and writes only the
-  rows whose scope field is its own subject key.
-- **TTL**: expired rows are invisible.
-- **Published-only**: a public View reading a `publishing` Schema sees
-  published rows only.
-- **Locks**: `WHERE id = … AND version = input.…` pins one row; writing none is
-  `CONFLICT`.
-
-Authors write the business query; they never repeat these rules. See
-[Authorization](./authorization.md) and [Lifecycle and locales](./lifecycle-and-locales.md).
-
-## Further reading
-
-- [Reads: Views, REST and MCP](./views.md)
-- [Writes: Procedures, Triggers and hooks](./procedures-and-triggers.md)
-- [Feature table](../reference/features.md)
+SQL is authored in PostgreSQL syntax and rendered for exactly postgres or sqlite. Generation applies row policy; the app supplies its own native handle and verified Caller. See [manifest reference](../reference/manifest.md) and [supported declarations](../reference/features.md).