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

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

@@ -0,0 +1,239 @@
+# 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
+// 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.
+        return new Response('Not found', { status: 404, headers: { 'cache-control': 'no-store' } });
+      } catch (error) { return surfaceFailure(error); }
+    });
+  },
+};
+```
+
+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:
+
+```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" }]
+}
+```
+
+`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.
+
+Commit `.dev.vars.example` containing variable names and placeholders only:
+
+```dotenv
+PUBLIC_ORIGIN=http://localhost:8787
+ADMIN_EMAIL=you@example.test
+BETTER_AUTH_SECRET=replace-with-a-random-secret
+```
+
+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" } }
+```
+
+The optional host reader is independent of the query target:
+
+```ts
+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 });
+```
+
+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
+```
+
+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.
+
+```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
+```
+
+`--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,116 +1,19 @@
----
-description: One authorization pipeline for REST, MCP and Admin — identity kinds, static predicates, the dynamic guard, staff roles and 401/403/402.
----
 # Authorization
 
-Mantle has one authorization pipeline. A manifest HTTP Trigger, a View over REST, an MCP `tools/call` and an Admin operation all reach the same evaluator, so a rule written once holds on every surface. This page explains the model; the exact `requires` grammar is in the [authorization reference](../reference/authorization.md), and a worked ladder of four access levels is in [Guarded API access](../../examples/cf-primitives-guarded-api.md).
+The app verifies credentials and supplies a `Caller` from `@aotter/mantle/contracts`:
 
-## The fixed order
+- 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.
 
-Every protected invocation runs the same five steps:
+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.
 
-1. Verify and normalize the transport credential.
-2. Evaluate the static predicates in `requires.auth.all`, before any input-schema detail is exposed.
-3. Validate and coerce the target input, or the View params.
-4. Invoke the guard Procedure with that validated value and the same context.
-5. Invoke the target only after the guard succeeds.
+## Operations and rows
 
-Static predicates run before validation so an unauthorized caller cannot probe a schema by reading its error messages. The guard runs after validation so it can decide on the actual arguments. Every stage fails closed.
+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.
 
-## Identity kinds
+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 adapter verifies the transport, then hands the runtime normalized, non-secret metadata. Handlers see this and nothing else:
+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.
 
-```ts
-interface HandlerContext {
-  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[];
-  };
-}
-```
-
-Three things are distinct:
-
-- **`ctx.user`** is the end-user identity: a row in the site's own Better Auth user table. A service API key may have no user at all.
-- **`ctx.staff`** is a role overlay on top of a user, not a separate account. A user with no overlay is `null` here.
-- **`ctx.auth`** is the verified credential itself, of kind `session`, `oauth`, `api-key` or `personal-token`. Raw keys, refresh tokens and cookies never enter the runtime; `credentialId` is an opaque record id.
-
-The predicate vocabulary is closed and maps onto those three: `ctx.user`, `ctx.auth`, `{ "ctx.auth.scope": "<scope>" }` (repeat it to require several), and `{ "ctx.staff": [roles] }`. There is no credential-kind predicate — a target that must reject browser sessions does so by requiring a scope no session grant carries.
-
-## Predicates versus the guard
-
-| | Static predicates | Guard Procedure |
-|---|---|---|
-| Declared as | `requires.auth.all` | `requires.guard.procedure` |
-| Answers | Is this caller of the right kind, with the right role and scopes? | Is this verified caller allowed to do this business action right now? |
-| Evaluated | Before input validation | After input validation, on every call, never cached |
-| Reads | The compiled plan only | Your tables, your provider state, `ctx.env` |
-| Typical failure | `401` or `403` | `402` |
-
-Anything that changes independently of the credential belongs in the guard: payment state, subscription or membership status, seat counts, per-tenant entitlement. A key stays valid while a subscription lapses, so the fact that a caller paid is not something a token can carry. The guard is an ordinary unguarded `handler.kind: ref` Procedure — not a fifth atom — and it throws a structured diagnostic to deny:
-
-```ts
-throw new DiagnosticError(
-  runtimeDiagnostic({
-    code: "ENTITLEMENT_REQUIRED",
-    severity: "error",
-    path: `site:membership/${ctx.user!.id}`,
-    message: "Active membership is required.",
-  }),
-);
-```
-
-## 401, 403 and 402
-
-| Status | Diagnostic | Meaning |
-|---|---|---|
-| `401` | `UNAUTHENTICATED` | No credential, or a recognized credential that is bad, revoked or expired. |
-| `403` | `AUTH_DENIED` | Verified caller, but a required predicate failed — a missing scope, a missing user subject, an insufficient staff role. |
-| `402` | `ENTITLEMENT_REQUIRED` | Verified and permitted caller whose current business state does not allow the action. |
-
-The split is the point: `401` says *who are you*, `403` says *you may not*, `402` says *not until you settle something*. Only the guard produces `402`, and on `402` the target handler is never invoked. See [Diagnostic codes](../reference/diagnostics.md) for the full mapping.
-
-## Staff roles
-
-Staff roles are `owner`, `editor` and `contributor`. Owners manage staff and site settings; editors publish, approve and manage entries; contributors work on drafts.
-
-A manifest predicate tests **exact membership**, not rank: `{ "ctx.staff": [editor] }` admits editors and nobody else, an owner included. List every role you mean, as in `{ "ctx.staff": [owner, editor] }`. Rank ordering does exist, but only Admin's own route table uses it, which is why an owner passes an Admin route gated at editor. See [Authorization requirements](../reference/authorization.md).
-
-The role is re-read from the database on every protected REST and MCP call. A token snapshot or a consent-time role is not an authorization boundary, so demoting or revoking a user in Admin locks them out on their very next request — no token revocation, no cache flush, no waiting for expiry.
-
-## The credential resolver seam
-
-Sites that issue their own API keys or personal tokens supply one `ConsumerCredentialResolver` through the Worker's `extend` seam. It returns exactly one of three outcomes:
-
-| Outcome | Meaning |
-|---|---|
-| `not-handled` | The request carries none of the site's credential formats. Resolution moves on. |
-| `invalid` | The request carries a recognized format that is bad, revoked or malformed. |
-| `verified` | The site's authoritative record was checked; normalized metadata is returned. |
-
-Resolution precedence is site resolver, then configured OAuth bearer, then cookie session. A recognized-but-invalid credential never falls back to a valid cookie: presenting a revoked key is a failure, not an invitation to be treated as an anonymous browser. Return `not-handled`, never `invalid`, for a request your resolver simply does not recognize.
-
-Scopes are opaque strings the site defines and grants. Mantle compares them; it does not interpret `catalog:read`, publish a scope catalog, or infer a hierarchy. Correspondingly, Mantle issues and stores no API keys or personal tokens, and holds no payment or subscription state. Those tables, their issuance, hashing, rotation and revocation, and whatever fills them from a billing provider, are application code. Mantle owns verification, normalization and enforcement.
-
-## MCP is the same pipeline
-
-An MCP `tools/call` runs the identical evaluator, in the identical order, with the identical diagnostics — surfaced as JSON-RPC errors carrying `error.data.code` instead of an HTTP status. A Trigger's `source.surface` selects which catalog lists a tool, and `tools/list` hides what the caller cannot see. That filtering is discovery UX, not enforcement: a client that guesses a tool name still meets every predicate and the guard. Discovery is never the authorization boundary. See [MCP and agents](./mcp-and-agents.md).
-
-## Related
-
-- [Authorization requirements](../reference/authorization.md) — the `requires` shape, predicate forms, guard rules, OpenAPI projection.
-- [Guarded API access](../../examples/cf-primitives-guarded-api.md) — a full resolver, guards and the REST/MCP outcome tables.
-- [Reads: Views, REST and MCP](./views.md) — the `$ctx.user` identity-View sentinel.
-- [Authentication](../cloudflare/authentication.md) — sessions, first owner, role management routes.
-
-## Source
-- [`docs/adapter-guide.md`](../../../docs/adapter-guide.md)
-- [`packages/mantle-runtime/src/domain/model/HandlerContext.ts`](../../../packages/mantle-runtime/src/domain/model/HandlerContext.ts)
-- [`packages/mantle-runtime/src/usecase/procedure/InvokeProcedureUseCase.ts`](../../../packages/mantle-runtime/src/usecase/procedure/InvokeProcedureUseCase.ts)
-- [`packages/adapters/cloudflare/src/mount/resolveCaller.ts`](../../../packages/adapters/cloudflare/src/mount/resolveCaller.ts)
-- [`packages/mantle-spec/src/domain/service/StaffRoleHierarchy.ts`](../../../packages/mantle-spec/src/domain/service/StaffRoleHierarchy.ts)
+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,173 +1,14 @@
----
-description: Schema, View, Procedure and Trigger — what each atom owns, why reads and writes are asymmetric, and how to compose everything else from four kinds.
----
 # The four atoms
 
-A Mantle Manifest declares exactly four resource kinds under the `cms.mantle.aotter.net/v1` API group. This page explains what each atom owns, how they compose, and how to decide where a new feature belongs. Field-level rules live in the [Reference](../reference/manifest.md) section.
+The manifest grammar is closed: Schema, View, Procedure and Trigger.
 
-## The four kinds
+| 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 |
 
-They map one-to-one onto the primitives Postgres has shipped for thirty years.
+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.
 
-| Atom | Postgres equivalent | Externally exposed by itself? | Has user code? |
-|---|---|---|---|
-| `Schema` | `CREATE TABLE` | No. Reached only through a View or a Procedure. | No |
-| `View` | `CREATE VIEW` | Yes. Auto-mounted on its declared `public` or `staff` REST and MCP surface. | No |
-| `Procedure` | `CREATE FUNCTION` | No. Transport-agnostic; needs a Trigger to gain a surface. | Yes — a handler in your project's registry. |
-| `Trigger` | `CREATE TRIGGER` plus route and tool binding | Yes. It is the binding atom. | No |
-
-A four-word gloss covers most questions: Schema is state, View is the read API, Procedure is the write API, Trigger is the binding.
-
-## Reads and writes are asymmetric on purpose
-
-Views mount themselves; Procedures do not. That asymmetry matches HTTP safe-versus-unsafe semantics. A View is a named, read-only query: idempotent, cacheable, and safe to expose the moment its `surface` is declared. A Procedure changes state, so its path, method, tool name and authorization are decisions an author must make explicitly, one Trigger at a time. There is no `Schema.spec.expose.rest` switch and no `/api/<collection>` shortcut; exposing collections directly was considered and rejected, because a Schema stores drafts, server-stamped fields and rows the author never meant to publish.
-
-The consequence for authors: a Procedure that has no Trigger is unreachable from outside the runtime, and calling its name as a URL returns `404`.
-
-## The composition rule
-
-Anything more domain-shaped than these four is not an atom. A Form, Membership, Email, Webhook, Workflow or ScheduledJob is a composition of Schemas, Views, Procedures and Triggers plus your own TypeScript. A fifth kind would recreate the same overlap: authors would have to decide whether a contact form was a Form, a Workflow or an Email.
-
-If you find yourself wanting another kind, sketch the same thing as a composition of the four first. Almost always it works.
-
-## The Manifest envelope
-
-Every document carries the same four top-level keys. Unknown keys at any known level are rejected with `INVALID_MANIFEST_ENVELOPE`.
-
-```yaml
-apiVersion: cms.mantle.aotter.net/v1
-kind: Schema | View | Procedure | Trigger
-metadata:
-  name: posts
-spec: {}
-```
-
-There is no `namespace` field. Names are unique within a kind, so a Schema and a View may share a name; two Schemas may not. Multi-tenancy belongs in your application layer, not in manifest metadata.
-
-One feature usually needs several atoms, so YAML's `---` separator keeps the file count down. Core reads every immediate `.yaml` and `.yml` file in the manifest directory and parses each document independently:
-
-```yaml
-# manifests/contact.yaml
-apiVersion: cms.mantle.aotter.net/v1
-kind: Procedure
-metadata:
-  name: send-contact-message
-spec:
-  input:
-    type: object
-    additionalProperties: false
-    required: [name, message]
-    properties:
-      name: { type: string, minLength: 1, maxLength: 80 }
-      message: { type: string, minLength: 1, maxLength: 4000 }
-  output: { type: object }
-  handler: { kind: ref, ref: send-contact-message }
----
-apiVersion: cms.mantle.aotter.net/v1
-kind: Trigger
-metadata:
-  name: contact-http
-spec:
-  source: { kind: http, method: POST, path: /api/contact }
-  target: { procedure: send-contact-message }
-```
-
-Parsing is all-or-nothing: one error in one document means no `ParsedManifestSet` at all.
-
-## Schema — the entity
-
-A Schema declares one collection: the JSON Schema for each entry's `data`, its indexes, its Admin presentation and its [lifecycle mode](./lifecycle-and-locales.md). Entries also carry six [native columns](../reference/schema.md#reserved-entry-columns) outside `data`.
-
-```yaml
-apiVersion: cms.mantle.aotter.net/v1
-kind: Schema
-metadata:
-  name: notes
-spec:
-  title: Notes
-  lifecycle: publishing
-  schema:
-    type: object
-    additionalProperties: false
-    required: [title, body]
-    properties:
-      title: { type: string, minLength: 1, maxLength: 200 }
-      body: { type: string, x-mcp-hint: markdown }
-  searchableFields: [title]
-```
-
-Full field rules, the JSON Schema subset and the `x-mantle-bind` / `x-mantle-ref` / `x-mcp-hint` keywords are in the [Schema reference](../reference/schema.md).
-
-## View — the read surface
-
-A View is a named read-only query over Schemas, mounted on exactly one surface. No Trigger is involved.
-
-```yaml
-apiVersion: cms.mantle.aotter.net/v1
-kind: View
-metadata:
-  name: published-notes
-spec:
-  title: Published notes
-  surface: public
-  from: notes
-  fields: [id, title, updatedAt]
-  filter:
-    eq: { field: status, value: published }
-  orderBy:
-    - { field: updatedAt, direction: desc }
-  limit: 20
-```
-
-`surface: public` serves `GET /api/views/published-notes` and the `query_view_published_notes` MCP tool on `/mcp`; `surface: staff` moves both behind the staff gate. See [Reads: Views, REST and MCP](./views.md) and the [View reference](../reference/view.md).
-
-## Procedure — the typed callable
-
-A Procedure declares typed `input`, typed `output`, optional `requires`, and one `handler`. It is the only atom with a code seam. The handler is either `kind: builtin` — a CRUD shortcut over one Schema — or `kind: ref`, an opaque key into the `handlers` map your project registers.
-
-```yaml
-spec:
-  handler: { kind: builtin, op: create, schema: notes }
-```
-
-Builtin ops are `create`, `update`, `upsert`, `delete` and `archive`. `request_publish` and `publish` are deliberately absent: they are lifecycle operations, not CRUD primitives. See [Writes: Procedures, Triggers and lifecycle hooks](./procedures-and-triggers.md) and the [Procedure reference](../reference/procedure.md).
-
-## Trigger — the binding
-
-A Trigger says "when X happens, run Procedure Y". Its `source` is one of three kinds, and its `target.procedure` names a declared Procedure.
-
-```yaml
-spec:
-  source: { kind: http, method: POST, path: /api/contact }
-  # or: { kind: mcp, surface: public }
-  # or: { kind: lifecycle, schema: notes, on: [before_create] }
-  target: { procedure: send-contact-message }
-```
-
-Several Triggers may target one Procedure, which is how the same handler becomes an HTTP endpoint, an MCP tool and a lifecycle hook without duplicated logic. Adding a transport is additive; the Procedure never changes. See the [Trigger reference](../reference/trigger.md).
-
-## How to think when extending
-
-1. **What entities does the feature need?** One `Schema` each.
-2. **What named queries?** One `View` each. Ad-hoc reads stay inside handler code; only sanctioned queries become Views, because a View is an external read endpoint.
-3. **What operations?** One `Procedure` each. One Procedure equals one typed function call. Compose in handler code, not in YAML.
-4. **What invokes them?** One `Trigger` per declared HTTP, MCP or lifecycle source.
-5. **Who is allowed?** `requires.auth` for static identity and scope, plus one optional `requires.guard.procedure` for a live business check. See [Authorization](./authorization.md).
-
-## The Postgres heuristic
-
-When you are unsure whether something deserves to be an atom, ask what it would be in Postgres.
-
-- If it is a `CREATE X` an **application developer** writes — `TABLE`, `VIEW`, `FUNCTION`, `TRIGGER` — it maps to one of the four.
-- If it is a `CREATE X` Postgres only needs because it is a database engine — `INDEX`, `MATERIALIZED VIEW`, `TABLESPACE`, `STATISTICS`, `EVENT TRIGGER`, `EXTENSION`, `LANGUAGE`, `PUBLICATION`, `FOREIGN TABLE`, `RULE` — it does not map, and it belongs behind the storage adapter.
-- If it is a type-system extension — `TYPE`, `DOMAIN`, `SEQUENCE`, `COLLATION`, `CAST`, `AGGREGATE`, `OPERATOR` — it folds into the JSON Schema inside a `Schema`.
-
-Postgres exposes roughly twenty-five object kinds; an application developer writes four to six of them. That is the same ratio Mantle ships.
-
-## Source
-
-- [`docs/adr/0001-four-atom-manifest-model.md`](../../../docs/adr/0001-four-atom-manifest-model.md)
-- [`docs/adr/0012-views-as-public-rest.md`](../../../docs/adr/0012-views-as-public-rest.md)
-- [`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)
-- [`docs/skills/develop/SKILL.md`](../../skills/develop/SKILL.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).