@aotter/mantle 0.1.2-alpha.6 → 0.1.2

package/docs/examples/builtin-procurement.md

@@ -0,0 +1,241 @@
+---
+description: Members submit purchase requisitions they can only see themselves; staff review them with optimistic concurrency.
+---
+# Procurement approvals with member and staff roles
+
+**Handler class:** builtin · **Builder:** yes · [Examples hub](./README.md).
+
+This example separates two audiences: signed-in members who submit and track their own requisitions, and staff who approve or reject them. Every Procedure is `handler.kind: builtin`. Read it if you need per-user rows and a staff decision step.
+
+## Problem
+
+A signed-in member submits a purchase requisition: a request number, an item, a quantity, a need-by date and a justification. The member sees only their own requisitions and their current status. Staff with the `owner` or `editor` role see the queue of `submitted` requisitions ordered by need-by date and mark each `approved` or `rejected` with a note. Two reviewers must not silently overwrite each other's decision. Requisitions are live operational records.
+
+## Manifest
+
+```yaml
+apiVersion: cms.mantle.aotter.net/v1
+kind: Schema
+metadata:
+  name: purchase-requisitions
+spec:
+  title: Purchase requisitions
+  description: Member-submitted purchase needs waiting for staff review.
+  lifecycle: operational
+  uniqueIndexes:
+    - [requestNumber]
+  indexes:
+    - [requestedBy, requestedAt]
+    - [requestStatus, needBy]
+  schema:
+    type: object
+    additionalProperties: false
+    required: [requestNumber, requestedBy, item, quantity, needBy, justification, requestStatus, requestedAt]
+    properties:
+      requestNumber: { type: string, pattern: "^REQ-[A-Z0-9-]+$" }
+      requestedBy: { type: string, x-mantle-bind: ctx.user }
+      item: { type: string, minLength: 1, maxLength: 160 }
+      quantity: { type: integer, minimum: 1 }
+      needBy: { type: number, x-mcp-hint: timestamp-ms }
+      justification: { type: string, minLength: 1, maxLength: 1000 }
+      requestStatus: { type: string, enum: [submitted, approved, rejected] }
+      reviewerNote: { type: string, maxLength: 1000 }
+      requestedAt: { type: number, x-mcp-hint: timestamp-ms, x-mantle-bind: now }
+---
+apiVersion: cms.mantle.aotter.net/v1
+kind: View
+metadata:
+  name: my-requisitions
+spec:
+  title: My requisitions
+  surface: public
+  from: purchase-requisitions
+  requires:
+    auth:
+      all: [ctx.user]
+  fields: [id, requestNumber, item, quantity, needBy, justification, requestStatus, reviewerNote, requestedAt]
+  filter:
+    eq: { field: requestedBy, value: { "$ctx.user": id } }
+  orderBy:
+    - { field: requestedAt, direction: desc }
+  limit: 100
+---
+apiVersion: cms.mantle.aotter.net/v1
+kind: View
+metadata:
+  name: pending-approvals
+spec:
+  title: Pending approvals
+  surface: staff
+  from: purchase-requisitions
+  requires:
+    auth:
+      all:
+        - { "ctx.staff": [owner, editor] }
+  fields: [id, version, requestNumber, requestedBy, item, quantity, needBy, justification, requestedAt]
+  filter:
+    eq: { field: requestStatus, value: submitted }
+  orderBy:
+    - { field: needBy, direction: asc }
+  limit: 100
+---
+apiVersion: cms.mantle.aotter.net/v1
+kind: Procedure
+metadata:
+  name: submit-requisition
+spec:
+  title: Submit requisition
+  requires:
+    auth:
+      all: [ctx.user]
+  input:
+    type: object
+    additionalProperties: false
+    required: [requestNumber, item, quantity, needBy, justification, requestStatus]
+    properties:
+      requestNumber: { type: string, pattern: "^REQ-[A-Z0-9-]+$" }
+      item: { type: string, minLength: 1, maxLength: 160 }
+      quantity: { type: integer, minimum: 1 }
+      needBy: { type: number, x-mcp-hint: timestamp-ms }
+      justification: { type: string, minLength: 1, maxLength: 1000 }
+      requestStatus: { type: string, enum: [submitted] }
+  output: { type: object }
+  handler: { kind: builtin, op: create, schema: purchase-requisitions }
+---
+apiVersion: cms.mantle.aotter.net/v1
+kind: Procedure
+metadata:
+  name: review-requisition
+spec:
+  title: Review requisition
+  requires:
+    auth:
+      all:
+        - { "ctx.staff": [owner, editor] }
+  input:
+    type: object
+    additionalProperties: false
+    required: [id, expectedVersion, requestStatus]
+    properties:
+      id: { type: string }
+      expectedVersion: { type: number, minimum: 1 }
+      requestStatus: { type: string, enum: [approved, rejected] }
+      reviewerNote: { type: string, maxLength: 1000 }
+  output: { type: object }
+  handler: { kind: builtin, op: update, schema: purchase-requisitions }
+---
+apiVersion: cms.mantle.aotter.net/v1
+kind: Trigger
+metadata:
+  name: submit-requisition-http
+spec:
+  source: { kind: http, method: POST, path: /api/requisitions }
+  target: { procedure: submit-requisition }
+---
+apiVersion: cms.mantle.aotter.net/v1
+kind: Trigger
+metadata:
+  name: submit-requisition-mcp
+spec:
+  source: { kind: mcp, surface: public }
+  target: { procedure: submit-requisition }
+---
+apiVersion: cms.mantle.aotter.net/v1
+kind: Trigger
+metadata:
+  name: review-requisition-mcp
+spec:
+  source: { kind: mcp, surface: staff }
+  target: { procedure: review-requisition }
+```
+
+### Ownership without trusting the caller
+
+`requestedBy` carries `x-mantle-bind: ctx.user`. On create the server stamps the signed-in user's id and ignores any caller value; on update the stamp is preserved. `requestedAt` is stamped the same way with `now`. Because both are in `required`, and because `submit-requisition` requires `ctx.user`, an anonymous caller is rejected with `UNAUTHENTICATED` before the row is even projected.
+
+`my-requisitions` filters with the closed sentinel `{ "$ctx.user": id }`. The caller never supplies this value, so the same View is safe over REST and public MCP. Three rules make the sentinel legal, and the parser enforces each:
+
+| Rule | Diagnostic when violated |
+|---|---|
+| The View's `requires.auth.all` includes `ctx.user` | `VIEW_FILTER_CTX_USER_REF_REQUIRES_AUTH` |
+| The sentinel appears only under `eq`, as a single-key object whose value is the literal `id` | `VIEW_FILTER_CTX_USER_REF_INVALID` |
+| The filtered field is the leftmost field of a declared index (`[requestedBy, requestedAt]` here) | `VIEW_FILTER_CTX_USER_REF_REQUIRES_INDEX` |
+
+A missing identity fails with 401; the runtime never drops the filter and never falls back to all rows.
+
+`pending-approvals` uses the staff predicate `{ "ctx.staff": [owner, editor] }`. It includes `version` in `fields` so a reviewer can pass it back as `expectedVersion`.
+
+### Optimistic concurrency
+
+`review-requisition` is a builtin `update`. Its input must declare `id` (string) and `expectedVersion` (number) in `required`; the parser rejects the Manifest otherwise. `expectedVersion` is the version the reviewer **read**, not that value plus one. At runtime the row is loaded, the patch is merged over existing data (omitted fields and server stamps survive), and the write is applied only if the stored version equals `expectedVersion`. A stale version fails with `CONFLICT` (HTTP 409) and nothing changes; the reviewer re-reads and decides again. Admin binds and hides `expectedVersion` on row-bound forms. `requestStatus` is narrowed to `approved | rejected`, so this Procedure cannot move a row back to `submitted`.
+
+### Review operation
+
+`pending-approvals` exposes the entry `id` and `version` required by `review-requisition`. Drive reviews from that View through Staff MCP or `POST /admin/api/operations/review-requisition`.
+
+The Procedure deliberately does not mark `id` with `x-mantle-ref`. This Schema's lone single-field unique index is `[requestNumber]`; a row-bound Admin action would therefore prefill the reference with the request number, while builtin `update` requires the entry id. Leaving the field unbound keeps every advertised path executable instead of publishing a row action that returns `NOT_FOUND`.
+
+See [Authorization](../handbook/concepts/authorization.md) and the [Procedure reference](../handbook/reference/procedure.md).
+
+## Worker and handlers
+
+None. Both Procedures are builtin and the Worker is `export default createMantleWorker({ plan })`. Sign-in is provided by the conventional Worker's Auth; see [Authentication](../handbook/cloudflare/authentication.md).
+
+## Try it
+
+Anonymous read of the member View:
+
+```sh
+curl -i http://localhost:8787/api/views/my-requisitions
+```
+
+```txt
+HTTP/1.1 401 Unauthorized
+{"ok":false,"diagnostic":{"code":"UNAUTHENTICATED","phase":"runtime","severity":"error","path":"...#/requires/auth/all/0", ...}}
+```
+
+Signed in (session cookie), the same request returns only rows whose `requestedBy` equals the caller's id:
+
+```sh
+curl -sS http://localhost:8787/api/views/my-requisitions \
+  -H "cookie: $SESSION_COOKIE"
+# {"ok":true,"data":{"rows":[{"id":"pr_01j...","requestNumber":"REQ-2026-0001","item":"Standing desk","quantity":1,"needBy":1791475200000,"justification":"...","requestStatus":"submitted","requestedAt":1788879363492}],"page":1,"show":100,"hasMore":false}}
+```
+
+Submit as a member (mutations authenticated by a session cookie also pass a same-origin check):
+
+```sh
+curl -sS -X POST http://localhost:8787/api/requisitions \
+  -H 'content-type: application/json' -H "cookie: $SESSION_COOKIE" \
+  -d '{"requestNumber":"REQ-2026-0002","item":"Monitor arm","quantity":2,"needBy":1791475200000,"justification":"Second screen for review work.","requestStatus":"submitted"}'
+```
+
+The response is `{ ok: true, data: <EntryRow> }`; `data.requestedBy` is the caller's id even if the body tried to set it. A duplicate `requestNumber` is HTTP 409 `CONFLICT`.
+
+Staff review through Staff MCP on `/mcp/staff`. First `query_view_pending_approvals` returns `id` and `version`; then:
+
+```json
+{
+  "jsonrpc": "2.0", "id": 2, "method": "tools/call",
+  "params": {
+    "name": "review_requisition",
+    "arguments": { "id": "pr_01j...", "expectedVersion": 1, "requestStatus": "approved", "reviewerNote": "Within budget." }
+  }
+}
+```
+
+A second reviewer replaying `expectedVersion: 1` after that succeeds receives a JSON-RPC error whose `error.data.code` is `CONFLICT`. A contributor-role session is denied with `AUTH_DENIED`. `review_requisition` appears only in `tools/list` on `/mcp/staff`; the public surface lists `submit_requisition` and `query_view_my_requisitions`.
+
+## What this deliberately leaves out
+
+- **Multi-step approval chains.** One decision by one staff member. Sequential approvers would add a step field, more enum states and a `before_update` hook that validates the transition.
+- **Budgets.** No cost field and no per-department limit; add a `ref` guard Procedure when a live check is needed.
+- **Notifications.** Neither the submitter nor the reviewer is emailed. The [intake form](./cf-primitives-intake-hooks.md) shows the `after_create` pattern.
+
+Related: [Guarded API access](./cf-primitives-guarded-api.md) covers credentials and scopes for non-browser callers.
+
+## Source
+
+- [Procedure reference](../handbook/reference/procedure.md) — `x-mantle-bind`, `x-mantle-ref`, builtin `update` contract, RBAC
+- [`packages/mantle-admin/src/mountMantleAdmin.ts`](../../packages/mantle-admin/src/mountMantleAdmin.ts) — `discoverRowBindings` and `rowField` derivation
+- [`packages/mantle-runtime/src/domain/service/AuthPredicateEvaluator.ts`](../../packages/mantle-runtime/src/domain/service/AuthPredicateEvaluator.ts) — `UNAUTHENTICATED` versus `AUTH_DENIED`

package/docs/examples/builtin-publication.md

@@ -0,0 +1,241 @@
+---
+description: Localized blog posts with a stable parent identity, a public per-locale list and an optional reader suggestion box.
+---
+# Publication: localized posts with a public list
+
+**Handler class:** builtin · **Builder:** yes · [Examples hub](./README.md).
+
+This example publishes posts in several languages, serves a public list per locale, and accepts reader suggestions. It is fully declarative: every Procedure is `handler.kind: builtin`. Read it if you run a blog, a news section or any authored, translated content.
+
+## Problem
+
+Editors draft posts in one or more locales, review them in Admin, and publish each language version independently. Every language version of a post shares one stable identity (its slug) so the site can link translations together and Admin can show translation completeness. Visitors read a per-locale list of published posts, newest first, over REST and public MCP. Readers may suggest topics; those suggestions are live records staff read in Admin, not content that is published.
+
+## Manifest
+
+```yaml
+apiVersion: cms.mantle.aotter.net/v1
+kind: Schema
+metadata:
+  name: posts
+spec:
+  title: Posts
+  description: Stable post identities shared by every language version.
+  localized: false
+  lifecycle: publishing
+  uniqueIndexes:
+    - [slug]
+  schema:
+    type: object
+    required: [slug]
+    properties:
+      slug: { type: string, pattern: "^[a-z0-9-]+$" }
+---
+apiVersion: cms.mantle.aotter.net/v1
+kind: Schema
+metadata:
+  name: post-translations
+spec:
+  title: Post translations
+  description: Localized titles and bodies for each post.
+  localized: true
+  translates:
+    parent: posts
+    on: slug
+  lifecycle: publishing
+  uniqueIndexes:
+    - [slug, locale]
+  indexes:
+    - [locale, publishedAt]
+  schema:
+    type: object
+    required: [slug, locale, title, publishedAt]
+    properties:
+      slug: { type: string, pattern: "^[a-z0-9-]+$" }
+      locale: { type: string }
+      title: { type: string }
+      excerpt: { type: string }
+      body: { type: string, x-mcp-hint: markdown }
+      publishedAt: { type: number, x-mcp-hint: timestamp-ms }
+---
+apiVersion: cms.mantle.aotter.net/v1
+kind: View
+metadata:
+  name: published-posts
+spec:
+  title: Published posts
+  surface: public
+  from: post-translations
+  params:
+    type: object
+    additionalProperties: false
+    required: [locale]
+    properties:
+      locale: { type: string }
+  fields: [id, slug, locale, title, excerpt, body, publishedAt, updatedAt]
+  filter:
+    and:
+      - eq: { field: status, value: published }
+      - eq: { field: locale, value: { $param: locale } }
+      - gte: { field: publishedAt, value: 0 }
+  orderBy:
+    - { field: publishedAt, direction: desc }
+  limit: 50
+---
+apiVersion: cms.mantle.aotter.net/v1
+kind: Schema
+metadata:
+  name: post-suggestions
+spec:
+  title: Post suggestions
+  description: Reader suggestions for future posts.
+  lifecycle: operational
+  schema:
+    type: object
+    required: [title, email]
+    properties:
+      title: { type: string }
+      email: { type: string, format: email }
+      note: { type: string }
+      createdAt: { type: integer, x-mcp-hint: timestamp-ms, x-mantle-bind: now }
+---
+apiVersion: cms.mantle.aotter.net/v1
+kind: Procedure
+metadata:
+  name: submit-post-suggestion
+spec:
+  input:
+    type: object
+    additionalProperties: false
+    required: [title, email]
+    properties:
+      title: { type: string }
+      email: { type: string, format: email }
+      note: { type: string }
+  output: { type: object }
+  handler: { kind: builtin, op: create, schema: post-suggestions }
+---
+apiVersion: cms.mantle.aotter.net/v1
+kind: Trigger
+metadata:
+  name: submit-post-suggestion-http
+spec:
+  source: { kind: http, method: POST, path: /api/post-suggestions }
+  target: { procedure: submit-post-suggestion }
+```
+
+How the pieces fit:
+
+- `posts` is the non-localized parent. It holds only what every language shares; here that is the slug.
+- `post-translations` is the localized child. `translates: { parent: posts, on: slug }` requires `localized: true`, at least one content field besides `slug` and `locale`, and a parent that exists and is not itself localized. Admin renders the child as locale tabs inside the parent's editor.
+- `published-posts` takes a required `locale` parameter. `{ $param: locale }` must name a property in `params.properties` that is also in `params.required`. The `gte publishedAt 0` clause keeps the filter aligned with the declared `[locale, publishedAt]` index; confirm the plan with `mantle-harness indexes`.
+- Site locales must be configured. A localized Schema with zero `siteDefaults.locales` fails at boot with `SCHEMA_LOCALIZED_REQUIRES_SITE_LOCALES`, and a write whose `locale` is not in the site list fails with `INPUT_VALIDATION_FAILED`.
+
+See [Lifecycle and locales](../handbook/concepts/lifecycle-and-locales.md) and the [Schema reference](../handbook/reference/schema.md).
+
+## Worker and handlers
+
+There are none. Every Procedure here is `builtin`, and Views need no Trigger. The Worker is the minimal one:
+
+```ts
+import { createMantleWorker } from "@aotter/mantle/cloudflare";
+import { plan } from "../.mantle/generated/mantle.js";
+
+export default createMantleWorker({ plan });
+```
+
+### Rendering
+
+Public HTML pages are optional and separate from the data contract. If you want `/en/posts/<slug>` rendered by the Worker, register a template for the translations collection and pass it to `createMantleWorker({ templates, publicPathResolver })`. A trimmed entry template:
+
+```ts
+import { TemplateRegistry } from "@aotter/mantle/web";
+import MarkdownIt from "markdown-it";
+
+const markdown = new MarkdownIt({ html: false, linkify: true });
+
+export function createTemplates(): TemplateRegistry {
+  const templates = new TemplateRegistry();
+  templates.registerEntryTemplate("post-translations", ({ entry, site, seo }) => {
+    const title = typeof entry.data.title === "string" ? entry.data.title : site.title;
+    const body = typeof entry.data.body === "string" ? entry.data.body : "";
+    return `<html lang="${entry.locale ?? "en"}"><head><title>${escapeHtml(title)}</title></head>
+<body><main><h1>${escapeHtml(title)}</h1><div>${markdown.render(body)}</div></main></body></html>`;
+  });
+  return templates;
+}
+```
+
+The template receives `{ entry, site, seo, mediaAssets }` and returns a complete HTML string. Escape every field you interpolate; `body` is rendered from Markdown because the Schema marks it `x-mcp-hint: markdown`. Paths, Markdown mirrors, `llms.txt`, sitemap and cache headers are covered in [Public web, SEO and cache](../handbook/cloudflare/public-web.md).
+
+### The single-Schema alternative
+
+The simpler alternative is one localized `posts` Schema with `uniqueIndexes: [[slug, locale]]` and no parent. Each locale row is an independent record; nothing is shared except the slug convention. Choose that shape when translations do not need shared fields or Admin translation grouping. Choose the parent/child shape above when several locale rows are versions of one entity and editors need to see which languages are missing. Both shapes serve the same `published-posts` View contract.
+
+## Try it
+
+Public list for one locale:
+
+```sh
+curl -sS 'http://localhost:8787/api/views/published-posts?locale=en&show=10'
+```
+
+```json
+{
+  "ok": true,
+  "data": {
+    "rows": [
+      {
+        "id": "tr_01j...",
+        "slug": "hello-world",
+        "locale": "en",
+        "title": "Hello, world",
+        "excerpt": "First post.",
+        "body": "# Hello\n\nFirst post.",
+        "publishedAt": 1788879363492,
+        "updatedAt": 1788879400000
+      }
+    ],
+    "page": 1,
+    "show": 10,
+    "hasMore": false
+  }
+}
+```
+
+Omitting `locale` returns HTTP 400 `INPUT_VALIDATION_FAILED`. `show` is capped at the View's `limit` (50); `hasMore` is `rows.length === show`. A View may declare `cache.sharedMaxAge` to cache eligible anonymous REST responses under the Worker's deployment-scoped tag; publishing content changes purge that tag.
+
+Submit a suggestion:
+
+```sh
+curl -sS -X POST http://localhost:8787/api/post-suggestions \
+  -H 'content-type: application/json' \
+  -d '{"title":"Write about indexes","email":"reader@example.test"}'
+```
+
+The response is `{ ok: true, data: <EntryRow> }` with `collection: "post-suggestions"` and `status: "published"`.
+
+MCP tools:
+
+| Surface | Tool | Origin |
+|---|---|---|
+| `/mcp` | `query_view_published_posts` (arguments `locale`, `page`, `show`) | public View |
+| `/mcp/staff` | `create_draft_posts`, `update_draft_posts` | publishing Schema `posts` |
+| `/mcp/staff` | `create_draft_post_translations`, `update_draft_post_translations` | publishing Schema `post-translations` |
+| `/mcp/staff` | `create_record_post_suggestions`, `update_record_post_suggestions` | operational Schema `post-suggestions` |
+| `/mcp/staff` | `request_publish`, `unpublish_entry`, `archive_entry`, `delete_entry` | generic lifecycle tools |
+
+There is no `submit_post_suggestion` tool because no MCP Trigger targets that Procedure. See [MCP and agents](../handbook/concepts/mcp-and-agents.md).
+
+## What this deliberately leaves out
+
+- **Comments.** Reader comments would be another operational Schema with its own moderation Procedures.
+- **Search.** `searchableFields` powers Admin and Staff MCP substring search only; public full-text search is application code.
+- **Scheduling.** `publishedAt` is a display timestamp set by editors. Nothing publishes a draft at that time; publishing remains an explicit `request_publish` or Admin action.
+
+Related: [Intake form](./builtin-intake.md) is the same suggestion-box write without hooks; [Intake Turnstile and email hooks](./cf-primitives-intake-hooks.md) hardens it with a bot check.
+
+## Source
+
+- [Schema reference](../handbook/reference/schema.md) and [View reference](../handbook/reference/view.md) — `localized`, `translates`, param-driven Views
+- [`packages/mantle-web/src/model/TemplateRegistry.ts`](../../packages/mantle-web/src/model/TemplateRegistry.ts) — `registerEntryTemplate` and `EntryContext`

package/docs/examples/builtin-reservation.md

@@ -0,0 +1,149 @@
+---
+description: Accept public reservation requests and expose the queue to staff. Every Procedure is builtin create.
+---
+# Reservation requests
+
+**Handler class:** builtin · **Builder:** yes · [Examples hub](./README.md).
+
+This example accepts reservation requests from the public and lists them for staff. The published Manifest is fully declarative: every Procedure is `handler.kind: builtin`. Read it if you take appointments, bookings or table requests and confirm them by hand. A `before_create` date guard is application code; see [Intake Turnstile and email hooks](./cf-primitives-intake-hooks.md) for that `ref` pattern.
+
+## Problem
+
+A visitor asks for a reservation by giving a name, an email address, the requested date or slot, an optional party size and a note. Staff see the newest requests first in Admin, over the staff View REST route, or through Staff MCP, and follow up outside the system. Requests are live operational records; nothing is drafted or published. The system does not decide whether a slot is free.
+
+## Manifest
+
+```yaml
+apiVersion: cms.mantle.aotter.net/v1
+kind: Schema
+metadata:
+  name: reservations
+spec:
+  title: Reservations
+  lifecycle: operational
+  schema:
+    type: object
+    additionalProperties: false
+    required: [name, email, requestedFor]
+    properties:
+      name: { type: string, minLength: 1, maxLength: 120 }
+      email: { type: string, format: email }
+      requestedFor: { type: string, description: Requested date, time, or slot. }
+      partySize: { type: integer, minimum: 1 }
+      note: { type: string, maxLength: 1000 }
+      createdAt: { type: number, x-mcp-hint: timestamp-ms, x-mantle-bind: now }
+---
+apiVersion: cms.mantle.aotter.net/v1
+kind: View
+metadata:
+  name: reservation-queue
+spec:
+  title: Reservation queue
+  surface: staff
+  from: reservations
+  fields: [id, name, email, requestedFor, partySize, note, createdAt]
+  orderBy:
+    - { field: createdAt, direction: desc }
+  limit: 50
+---
+apiVersion: cms.mantle.aotter.net/v1
+kind: Procedure
+metadata:
+  name: submit-reservation
+spec:
+  title: Submit reservation
+  input:
+    type: object
+    additionalProperties: false
+    required: [name, email, requestedFor]
+    properties:
+      name: { type: string, minLength: 1, maxLength: 120 }
+      email: { type: string, format: email }
+      requestedFor: { type: string }
+      partySize: { type: integer, minimum: 1 }
+      note: { type: string, maxLength: 1000 }
+  output: { type: object }
+  handler: { kind: builtin, op: create, schema: reservations }
+---
+apiVersion: cms.mantle.aotter.net/v1
+kind: Trigger
+metadata:
+  name: submit-reservation-http
+spec:
+  source: { kind: http, method: POST, path: /api/reservations }
+  target: { procedure: submit-reservation }
+---
+apiVersion: cms.mantle.aotter.net/v1
+kind: Trigger
+metadata:
+  name: submit-reservation-mcp
+spec:
+  source: { kind: mcp, surface: public }
+  target: { procedure: submit-reservation }
+```
+
+`createdAt` is stamped by the server (`x-mantle-bind: now`); a caller-supplied value is ignored. `requestedFor` is a free string on purpose: this example does not impose a calendar model. The staff View orders by `createdAt`, so the newest request is first regardless of the requested slot.
+
+## Worker and handlers
+
+None are required. The Manifest above runs on the minimal Worker:
+
+```ts
+import { createMantleWorker } from "@aotter/mantle/cloudflare";
+import { plan } from "../.mantle/generated/mantle.js";
+
+export default createMantleWorker({ plan });
+```
+
+A `before_create` guard that rejects ISO dates already in the past is a `handler.kind: ref` Procedure. It is not part of this Manifest. The abort-hook shape, `InvokeFailure`, and `LIFECYCLE_HOOK_REJECTED` (HTTP 409) are in [Intake Turnstile and email hooks](./cf-primitives-intake-hooks.md) and [Writes: Procedures, Triggers and hooks](../handbook/concepts/procedures-and-triggers.md).
+
+## Try it
+
+```sh
+curl -sS -X POST http://localhost:8787/api/reservations \
+  -H 'content-type: application/json' \
+  -d '{"name":"Ada","email":"ada@example.test","requestedFor":"2026-10-03T19:00:00+08:00","partySize":4}'
+```
+
+```json
+{
+  "ok": true,
+  "data": {
+    "id": "res_01j...",
+    "collection": "reservations",
+    "status": "published",
+    "version": 1,
+    "data": { "name": "Ada", "email": "ada@example.test", "requestedFor": "2026-10-03T19:00:00+08:00", "partySize": 4, "createdAt": 1788879363492 },
+    "authorId": null,
+    "createdAt": 1788879363492,
+    "updatedAt": 1788879363492
+  }
+}
+```
+
+A `partySize` of `0` is HTTP 400 `INPUT_VALIDATION_FAILED`.
+
+Staff list the queue at `GET /admin/api/views/reservation-queue?page=1&show=50` (staff session required); `GET /admin/api/views/reservation-queue/export` returns the matching rows as CSV.
+
+MCP tools:
+
+| Surface | Tool | Origin |
+|---|---|---|
+| `/mcp` | `submit_reservation` | `submit-reservation-mcp` Trigger |
+| `/mcp/staff` | `query_view_reservation_queue` | `reservation-queue` View |
+| `/mcp/staff` | `create_record_reservations`, `update_record_reservations` | operational Schema `reservations` |
+
+## What this deliberately leaves out
+
+Requests are **not confirmed automatically**. A successful `POST` means the request was recorded, nothing more. The pattern omits:
+
+- **Slot inventory.** There is no `slots` Schema and no capacity count.
+- **Double-booking prevention.** Two requests for the same time both succeed. Preventing that needs an authority that serializes reservations, as the [commerce example](./cf-primitives-commerce-inventory.md) does for stock with a Durable Object.
+- **Calendar sync, payments, deposits.**
+- **Confirmation messages.** Add an `after_create` handler as in the [intake form](./cf-primitives-intake-hooks.md) when staff want a notification.
+
+## Source
+
+- [`README.md`](../../README.md) — reservations excerpt
+- [Procedure reference](../handbook/reference/procedure.md) — builtin `create`
+- [Intake Turnstile and email hooks](./cf-primitives-intake-hooks.md) — optional `before_create` `ref` guard