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

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

@@ -0,0 +1,138 @@
+---
+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):
+
+```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),
+};
+
+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.
+
+## Add your own routes
+
+Put them in the function `mount` returns, where they belong in the order:
+
+```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;
+  …
+};
+```
+
+- 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.
+
+- 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.
+
+## `src/index.ts`
+
+```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>;
+```
+
+- `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
+
+`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:
+
+```jsonc
+"assets": { "directory": "node_modules/@aotter/mantle-ui/dist/admin", "binding": "ASSETS", "run_worker_first": true, "html_handling": "none" }
+```
+
+`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`.

package/docs/handbook/concepts/authorization.md

@@ -1,116 +1,126 @@
 ---
-description: One authorization pipeline for REST, MCP and Admin — identity kinds, static predicates, the dynamic guard, staff roles and 401/403/402.
+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 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).
+Mantle never owns your users. The service resolves who is calling once per
+request, and Mantle enforces the manifests against that answer.
 
-## The fixed order
-
-Every protected invocation runs the same five steps:
-
-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.
-
-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.
-
-## Identity kinds
-
-The adapter verifies the transport, then hands the runtime normalized, non-secret metadata. Handlers see this and nothing else:
+## The Caller
 
 ```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[];
-  };
-}
+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 };
 ```
 
-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.
+- `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.
 
-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:
+## One boundary: `CallerResolver` and `withCaller`
 
 ```ts
-throw new DiagnosticError(
-  runtimeDiagnostic({
-    code: "ENTITLEMENT_REQUIRED",
-    severity: "error",
-    path: `site:membership/${ctx.user!.id}`,
-    message: "Active membership is required.",
-  }),
-);
+type CallerResolver = (request: Request) =>
+  Promise<{ caller: Caller } | { invalid: true; challenge?: string; status?: 401 | 403 }>;
 ```
 
-## 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:
+The generated `src/service.ts` wraps every surface in
+`withCaller(resolver, surface)`:
+
+- 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 }
+```
 
-| Outcome | Meaning |
+| Predicate | Holds when |
 |---|---|
-| `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.
+| `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, …]
+```
 
-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.
+- 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();
+```
 
-## MCP is the same pipeline
+The writer comes from the caller, never from an input. See
+[Procurement approvals](../../examples/procurement.md).
 
-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).
+## Admin
 
-## Related
+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).
 
-- [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.
+## Further reading
 
-## 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)
+- [Authorization reference](../reference/authorization.md)
+- [Guarded API access](../../examples/guarded-api.md)

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

@@ -1,173 +1,97 @@
 ---
-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.
+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
 
-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 four kinds
-
-They map one-to-one onto the primitives Postgres has shipped for thirty years.
-
-| 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`.
+Every manifest document is one atom:
 
 ```yaml
-apiVersion: cms.mantle.aotter.net/v1
+apiVersion: cms.mantle.aotter.net/v2
 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 }
+metadata: { name: <name> }
+spec: { … }
 ```
 
-Parsing is all-or-nothing: one error in one document means no `ParsedManifestSet` at all.
+| 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 |
 
-## Schema — the entity
+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`.
 
-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`.
+## How they reference each other
 
-```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
+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
 ```
 
-`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.
+- 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.
 
-```yaml
-spec:
-  handler: { kind: builtin, op: create, schema: notes }
-```
+`mantle generate` links every reference and refuses a dangling one, a
+duplicate name, or two names that differ only in case.
 
-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).
+## Native columns
 
-## Trigger — the binding
+Every Schema table carries native columns that Store fills and no write may
+set:
 
-A Trigger says "when X happens, run Procedure Y". Its `source` is one of three kinds, and its `target.procedure` names a declared Procedure.
+| 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 |
 
-```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 }
-```
+SQL spells them snake_case; the JSON of `ctx.store` keeps camelCase. A Schema
+field may not reuse these names.
 
-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).
+## Values in SQL
 
-## How to think when extending
+| 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 |
 
-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).
+A SQL literal is a literal. There are no `$`-prefixed references and no
+positional `$1`.
 
-## The Postgres heuristic
+## What the runtime adds
 
-When you are unsure whether something deserves to be an atom, ask what it would be in Postgres.
+Every Schema reference in every statement, joins and subqueries included, is
+rewritten before it runs:
 
-- 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`.
+- **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`.
 
-Postgres exposes roughly twenty-five object kinds; an application developer writes four to six of them. That is the same ratio Mantle ships.
+Authors write the business query; they never repeat these rules. See
+[Authorization](./authorization.md) and [Lifecycle and locales](./lifecycle-and-locales.md).
 
-## Source
+## Further reading
 
-- [`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)
+- [Reads: Views, REST and MCP](./views.md)
+- [Writes: Procedures, Triggers and hooks](./procedures-and-triggers.md)
+- [Feature table](../reference/features.md)