@aotter/mantle 0.1.0-alpha.9 → 0.1.2-alpha.2

package/docs/handbook/reference/surface.md

@@ -0,0 +1,207 @@
+---
+description: Every surface Mantle exposes — Worker HTTP routes and their cache class, the MCP tool catalog, CLI flags, the generated module, packages and versions.
+---
+# HTTP, MCP, CLI and package surface
+
+What a Mantle deployment exposes, in one place: the routes the conventional Cloudflare Worker owns, the MCP tools it advertises, the commands the package installs, the module `mantle generate` writes, and which package holds what. Route behaviour follows [Conventional Worker](../cloudflare/conventional-worker.md); this page is the index.
+
+## HTTP routes
+
+Every table below describes the conventional Cloudflare Worker assembled by `createMantleWorker`. The **cache** column is the class the final `applyCachePolicy` boundary assigns. Only an anonymous `200` `GET`/`HEAD` response that explicitly declares `public` plus a shared freshness lifetime stays cacheable, and it then varies on `Cookie` and `Authorization`; the request must carry neither header and the response must set no cookie. Everything else becomes `private, no-store` with any CDN cache override stripped.
+
+### Manifest routes
+
+| Route | Response | Cache |
+|---|---|---|
+| `GET /api/views` | `{ ok: true, data: [ { name, title?, description, inputSchema } ] }` — one descriptor per public View. | `private, no-store` |
+| `GET /api/views/<name>?page=&show=` | `{ ok: true, data: { rows, page, show, hasMore } }`. One route per View declaring `surface: public`. Query values are coerced against `params`; a bad value is `400`. | `private, no-store`, or the View's `cache.sharedMaxAge` for an anonymous eligible response |
+| `<METHOD> <path>` | Every manifest HTTP Trigger, at its declared `POST`, `PUT`, `PATCH` or `DELETE` and path under `/api/`. The JSON body must be an object. Success is `{ ok: true, data: … }`. | `private, no-store` |
+
+Staff Views are not mounted here; they live under `/admin/api/views/<name>`.
+
+### Admin
+
+All `/admin/api/*` routes require a staff session, carry a 1 MiB JSON body limit, and are `private, no-store`.
+
+| Route | Response |
+|---|---|
+| `GET /admin`, `/admin/`, `/admin/sign-in`, `/admin/c/:collection`, `/admin/c/:collection/:id`, `/admin/media`, `/admin/preferences`, `/admin/connected-apps`, `/admin/settings`, `/admin/staff`, `/admin/members`, `/admin/ops`, `/admin/dev`, `/admin/dev/model`, `/admin/dev/logic`, `/admin/dev/docs`, `/admin/views/:name` | The Admin SPA shell, read from `/_mantle/admin/index.html` through the assets binding. `503` with an explanatory body when the bundle is missing. |
+| `GET /admin/api/views/<name>` | Staff execution of any declared View, public or staff, with Admin search and filtering applied before pagination. |
+| `GET /admin/api/views/<name>/export` | The same query as CSV, covering every matching row rather than one page. |
+| `GET /admin/api/views-manifest` | `{ views: … }` — the View manifest projection the SPA renders from. |
+| `GET /admin/api/operations` | `{ operations: [ { name, title, description, input, uiSchema, triggers, rowBindings } ] }`, filtered per caller by re-evaluating each Procedure's `requires.auth.all`. |
+| `POST /admin/api/operations/:name` | Invokes a staff-operable Procedure through the same use case the staff MCP surface uses. `404` when the name is not staff-operable. |
+| `GET /admin/api/me`, `/collections`, `/collections/:name/statistics`, `/entries`, `/entries/export`, `/entries/:id`, `/site` | Session, catalog and entry reads. Entry detail requires `?collection=<schema>`. |
+| `POST /admin/api/entries`, `PATCH /admin/api/entries/:id` | Create and edit. Entry mutation routes require `?collection=<schema>`; contributors are limited to drafts on publishing Schemas. |
+| `POST /admin/api/entries/:id/publish`, `/unpublish`, `DELETE /admin/api/entries/:id` | Lifecycle. Requires `?collection=<schema>` and editor or above. |
+| `POST /admin/api/media/uploads`, `POST /admin/api/media/uploads/:uploadGroupId/commit`, `GET /admin/api/media`, `GET`, `PATCH` and `DELETE /admin/api/media/:id` | Media lifecycle. Editor or above. |
+| `GET /admin/api/staff`, `PATCH /admin/api/staff/:id/role`, `POST /admin/api/staff/invitations`, `DELETE /admin/api/staff/invitations/:id`, `GET /admin/api/developer-console`, `GET` and `PATCH /admin/api/site-settings` | Owner only. |
+| `GET /admin/api/members` | Editor or above. |
+
+`/_mantle/*` holds the static Admin bundle. It is served by the Worker's static-assets layer from `public/_mantle/admin/`, which `mantle generate` syncs when `@aotter/mantle-admin-ui` is installed. The Worker registers no route there; the prefix is reserved so extensions cannot claim it.
+
+### Auth, OAuth and MCP
+
+| Route | Response | Cache |
+|---|---|---|
+| `GET /api/auth/methods` | `{ methods }` — the registered sign-in method kinds, no secrets. Explicitly `no-store` so a method change cannot be served stale. | `private, no-store` |
+| `ALL /api/auth/*` | Better Auth: sign-in, callback, session, magic link, OTP. `/api/auth` is the default base path. | `private, no-store` |
+| `ALL /api/auth/oauth2/*` | The site's OAuth provider endpoints, including consent. | `private, no-store` |
+| `ALL /.well-known/oauth-authorization-server/*`, `/.well-known/oauth-protected-resource`, `/.well-known/oauth-protected-resource/*` | RFC 8414 and RFC 9728 discovery metadata, registered explicitly so no catch-all can swallow them. `/.well-known/oauth-protected-resource/mcp` is the resource metadata the MCP `WWW-Authenticate` challenge points at. | `private, no-store` |
+| `ALL /oauth/*` | Consent and connected-apps pages: `/oauth/consent`, `/oauth/consent/data`, `/oauth/consents`, `/oauth/consents/data`, `/oauth/consents/revoke`. | `private, no-store` |
+| `ALL /mcp` | Public MCP surface. JSON-RPC. | `private, no-store` |
+| `ALL /mcp/staff` | Staff MCP surface. Rejects a verified caller with no staff row using `403` and `insufficient_scope`. | `private, no-store` |
+
+Both MCP surfaces verify an OAuth access token against one canonical resource, `${PUBLIC_ORIGIN}/mcp`, and one scope, `mcp`. A missing or invalid token is `401` with a `Bearer` challenge naming the resource metadata URL; DPoP failures answer with a `DPoP` challenge. Misconfigured or partial auth environment variables keep public routes serving and return `503 setup_incomplete` from every Auth-owned route above — see [Authentication](../cloudflare/authentication.md).
+
+### Public pages
+
+These are opt-in and application-declared. Public rendering needs three matching inputs: a `mountPublicRoutes(...)` call declaring the collection routes, a `TemplateRegistry` passed as `templates`, and a `publicPathResolver`. A headless deployment declares none of them and serves none of these routes; mounting every Schema automatically is deliberately not offered, because a collection can hold a slug and still be private. Bodies render from canonical database state.
+
+| Route | Response | Cache |
+|---|---|---|
+| `GET /` | `302` to `/{canonical locale}`. | `private, no-store` |
+| `GET /:locale` | Composed home page. | `public, max-age=0, s-maxage=300` + a deployment-scoped cache tag |
+| `GET /:locale.md` | Markdown mirror of the home page. | public |
+| `GET /:locale/:segment` | Collection list page. Opt-in per collection route. Paginates by `?cursor=` and adds `Link: <…>; rel="next"` plus an in-page next link. | public |
+| `GET /:locale/:segment.md` | Markdown mirror of the list. | public |
+| `GET /:locale/:segment/:slug` | Entry page. | public |
+| `GET /:locale/:segment/:slug.md` | Markdown mirror of one entry. Registered before the bare slug route, and the slug group stays single-segment. | public |
+| `GET /:locale/:segment/:slug?preview=1` | Live render of unpublished content. Gated on a staff session: `401` with no session, `403` for a non-staff user. | `private, no-store` |
+| `GET /llms.txt` | Composed agent index across every locale, with `?cursor=` continuation and `Link: rel="next"`. | public |
+| `GET /:locale/llms.txt` | The same, scoped to one locale. | public |
+| `GET /sitemap.xml` | Sitemap. `?part=1` returns a single part; otherwise a sitemap index is returned whenever a continuation exists, and `?cursor=` fetches the next part. Part size is `min(2000, floor(40000 / locale count))`, at least 1. | public |
+| `GET /robots.txt` | `User-agent: *`, `Allow: /`, and a `Sitemap:` pointer built from `siteDefaults.origin`. | public |
+| `GET /favicon.ico` | A convention, not a reserved path: an existing host route wins. Picks the first themeless PNG icon, else the first themeless icon, else the first icon; serves it from the assets binding when it resolves to `/favicon.ico` on this origin, and otherwise redirects to the icon `src`. | `private, no-store` |
+
+The first three rows register only when a home renderer is supplied; without one, `/` and `/{locale}` are not mounted at all. Unmatched paths fall through to the supplied not-found renderer. Setting `liveDev` switches entry and list HTML to `private, no-store`. `cacheScope` isolates each deployment's tag and optional KV key; without it the facade disables shared caching. Publishing-content and site-setting writes purge that scoped tag. Purge is best effort after the canonical write, and Cloudflare KV remains eventually consistent. Immutable assets and operational records stay outside that boundary. More in [Public web](../cloudflare/public-web.md).
+
+### Reserved paths
+
+Extensions may add routes but may not replace Core surfaces. These are reserved:
+
+- `/admin` and `/admin/*`
+- `/_mantle` and `/_mantle/*`
+- `/api/auth` and `/api/auth/*`
+- `/api/views` and `/api/views/*`
+- `/oauth` and `/oauth/*`
+- `/mcp` and `/mcp/*`
+- `/.well-known/oauth*`
+- the global `*` and `/*` registrations
+
+A custom Auth factory's `basePath` and every manifest-owned `(method, path)` pair are reserved as well. Static literal conflicts fail the consumer's TypeScript build; computed paths cannot be proven statically, so the facade inspects the assembled route table and fails closed before serving. A manifest HTTP Trigger under one of these prefixes is `TRIGGER_PATH_INVALID` at boot.
+
+## MCP tools
+
+Tool names are the mangled `metadata.name`: lower-cased, with `-` replaced by `_`. Discovery is filtered per caller, but discovery is never the enforcement boundary — every `tools/call` re-evaluates the target's `requires.auth.all` and its guard.
+
+| Tool | Surface | Registered when |
+|---|---|---|
+| `query_view_<segment>` | The View's own `surface` | One per declared View. `annotations.readOnlyHint` is `true`; the input schema is the View's `params.properties` plus `page` and `show`. |
+| `<procedure segment>` | The Trigger's `surface` | One per `Trigger.source.kind: mcp`. A Procedure with no MCP Trigger is not exposed. |
+| `request_publish` | staff | Always. Rejected at call time for an operational Schema. |
+| `unpublish_entry` | staff | Always. Same restriction. |
+| `archive_entry` | staff | Always. Same restriction. |
+| `delete_entry` | staff | Always. |
+| `create_draft_<segment>`, `update_draft_<segment>` | staff | Per publishing Schema whose `schema.readOnly` is not `true`. |
+| `create_record_<segment>`, `update_record_<segment>` | staff | Per operational Schema whose `schema.readOnly` is not `true`. |
+| `create_media_upload`, `commit_media_upload` | staff | Only when a `mediaStorage` port is bound **and** at least one `media.purposes` entry is declared. |
+
+The public surface carries callable capabilities only — public Views and Procedures with a public MCP Trigger. No generic entry tool and no authoring tool is ever advertised there. Update tools add `id` and `expected_version` as required fields, and `x-mantle-bind` properties are stripped from authoring tool schemas because the server stamps them. Localized `title` and `description` collapse to their `en` value in tool schemas. Concepts are in [MCP and agents](../concepts/mcp-and-agents.md).
+
+## CLI
+
+The `@aotter/mantle` package installs two binaries, `mantle` and `mantle-harness`. Exit codes are `0` for success, `1` for a diagnostic failure and `2` for an invocation problem.
+
+| Command | Flags |
+|---|---|
+| `mantle generate` | `--manifests <dir>` (default `./manifests`), `-o, --output <dir>` (default `.mantle/generated`), `--namespace <name>` (default `Mantle`), `--check`, `-h, --help` |
+| `mantle skills` | `--check`, `-h, --help` |
+| `mantle validate` | `--manifests <dir>` (default `./manifests`), `--source <dir>` (default `./src`), `--no-source`, `--phase preview\|deploy` (default `preview`), `--format json\|text` (default by TTY), `--json`, `-h, --help` |
+| `mantle emit-openapi` | `--manifests <dir>`, `--title <str>` (default `mantle`), `--version <str>` (default `0.1.0`), `--session-cookie-name <str>`, `-o, --output <file>`, `-h, --help` |
+| `mantle-harness indexes` | `--manifests <dir>`, `--rows <n>`, `--require <view>` (repeatable), `--require-public`, `--format json\|text`, `-h, --help` |
+| `mantle-harness http` | `--route <name=url>` (repeatable, required), `--base-url <url>`, `--rounds <n>`, `--warmup <n>`, `--format json\|text`, `-h, --help` |
+
+`generate` validates and compiles the manifest directory, writes the typed module, and — when `@aotter/mantle-admin-ui` is installed — syncs the Admin SPA into `public/_mantle/admin/`, excluding `server.*` files. `--check` fails without writing when either output is stale. `skills` copies every skill the installed package marks `projection: project` into `.agents/skills/mantle-*` and `.claude/skills/mantle-*`; both layouts receive identical bytes. `validate --phase deploy` adds the pre-deploy-only gates on top of the grammar and cross-Schema checks. `emit-openapi` covers HTTP Triggers and View REST routes; MCP is out of scope. `mantle-harness indexes` executes compiled Views against crowded SQLite and inspects query plans; `http` samples a running Worker for p50 and p95. Day-to-day use is in [Project and CLI](../start/project-and-cli.md).
+
+## The generated module
+
+`mantle generate` writes one file, `.mantle/generated/mantle.ts`. It is generated code: do not edit it, and regenerate after any manifest change.
+
+| Export | Shape |
+|---|---|
+| `plan` | The sealed `RuntimePlan`, carrying a semantic fingerprint. |
+| `Mantle` (or `--namespace`) | Type namespace holding `Entry_*`, `ViewRow_*`, `ViewParams_*`, `ProcInput_*` and `ProcOutput_*` for every atom. |
+| `MantleViewOptions` | `{ page?, show?, ctx? }`. |
+| `MantleHandlers<Env>` | Typed map of every `handler.kind: ref` key the manifests declare. |
+| `CreateMantleOptions<Env>` | `BootMantleRuntimeArgs` without `plan` and `handlers`, plus the typed `handlers` map. |
+| `createMantle(options)` | Boots the runtime and returns the bound facade. Eager: it prepares once and neither caches nor retries. |
+| `bindMantle(runtime)` | Binds an already-booted runtime. Throws when `runtime.revision` does not equal the generated plan's fingerprint. |
+
+The bound object is deterministic lower-camel property names over the authored wire names:
+
+```ts
+import { createMantle } from "../.mantle/generated/mantle.js";
+
+const mantle = await createMantle({ storage, handlers });
+
+await mantle.views.publishedNotes({ page: 1, show: 20 });
+await mantle.procedures.expireOrder({ orderId }, { user: null, staff: null, env });
+await mantle.entries.orders.createDraft({ data, authorId: user.id });
+mantle.triggers.expireOrderHttp;   // { name, source, target }
+await mantle.runtime.archive.execute({ id, ctx });
+```
+
+`entries.<collection>` exposes `createDraft`, `get`, `list` and `delete`, supplying the required collection identity to Core. Generic MCP entry tools require a `collection` argument. `runtime` is the underlying Core runtime, so the typed projection never hides it. A host that owns its own lifecycle can skip generation entirely and call `runtime.executeView({ view: "published-notes" })` directly.
+
+## Packages
+
+The umbrella installs Spec and Runtime only. Web, Admin, Admin UI, Bun, Vercel and Cloudflare are optional peers; install one before importing its subpath. Every sub-package is also directly installable.
+
+| Package | Umbrella subpath | Holds |
+|---|---|---|
+| `@aotter/mantle` | root | Umbrella plus the `mantle` and `mantle-harness` binaries. |
+| `@aotter/mantle-spec` | `/spec` | Manifest grammar, parser, validators, JSON Schema to zod, site-config contract, diagnostic catalog. No environment, no IO. |
+| `@aotter/mantle-runtime` | `/runtime` | Hexagonal runtime: domain ports, use cases, MCP catalog, storage helpers. No adapter dependencies. |
+| — | `/runtime/testing` | Node-only crowded-SQLite planner and HTTP sampling helpers used by `mantle-harness`. |
+| — | `/codegen` | The pure linked-manifests to typed-module emitter, with no IO. |
+| `@aotter/mantle-web` | `/web` | HTML, Markdown, `llms.txt`, sitemap, SEO and preview composition. No routes, no platform dependencies. |
+| `@aotter/mantle-admin` | `/admin` | Admin API, auth route mounting, OAuth pages, static-asset composition. |
+| `@aotter/mantle-admin-ui` | `/admin-ui` | Pre-built React 19 Admin SPA bundle. |
+| `@aotter/mantle-bun` | `/bun` | Bun adapter over a caller-owned `bun:sqlite` database. |
+| `@aotter/mantle-vercel` | `/vercel` | Vercel Functions adapter with injected durable storage and platform `waitUntil`. |
+| — | `/vercel/libsql` | Optional application-owned Turso/libSQL driver. |
+| `@aotter/mantle-cloudflare` | `/cloudflare` | Cloudflare Workers adapter: D1, Workers Cache, R2, Queues, Better Auth 1.7 MCP and CIMD. |
+| `@aotter/mantle-indexeddb` | — | Browser IndexedDB adapter. Directly installable; no umbrella subpath. |
+
+## Versions
+
+This handbook was added on the development branch after `v0.1.0-alpha.17`. It describes that development snapshot and will ship with a future release; it is not included in the published `0.1.0-alpha.17` package. For a registry installation, use the documentation at the matching release tag. For a source-built package, record the source commit as well as the package version: a development checkout can still carry the previous release version.
+
+The documentation site pins its handbook commit in `docs/handbook.json` and records its vendored SDK source in `vendor/mantle/SOURCE.txt`. Those commits may differ when the intervening changes are behavior-neutral; the site verifies that condition during the build. The site's source-built tarballs are not the npm `alpha.17` artifacts.
+
+`0.1.0-alpha.17` is immutable and no stable `0.1.0` is planned; the first stable target is `0.1.2`. That line removes the scaffolding path — the `mantle create` command, the bundle-oriented `mantle update` command, and the `@aotter/mantle/provision` subpath — with no aliases and no replacement scaffold command. `generate`, `skills`, `validate` and `emit-openapi` remain, and generation and runtime Web rendering keep their existing responsibilities. New projects are authored directly: write the manifests, run `generate`, wire the Worker. The reasoning is [ADR-0021](../../../docs/adr/0021-retire-starter-scaffolding.md).
+
+Prerelease packages take their exact version from their own `package.json`, which is the authority; APIs may change between prereleases until `0.1.2`.
+
+## Source
+
+- [`packages/mantle/README.md`](../../../packages/mantle/README.md)
+- [`packages/mantle/src/cli/main.ts`](../../../packages/mantle/src/cli/main.ts)
+- [`packages/mantle/src/cli/generate.ts`](../../../packages/mantle/src/cli/generate.ts)
+- [`packages/mantle/src/cli/skills.ts`](../../../packages/mantle/src/cli/skills.ts)
+- [`packages/mantle/src/cli/harness.ts`](../../../packages/mantle/src/cli/harness.ts)
+- [`packages/mantle/src/codegen/emitMantleModule.ts`](../../../packages/mantle/src/codegen/emitMantleModule.ts)
+- [`packages/mantle-spec/src/infrastructure/cli/ValidateCommand.ts`](../../../packages/mantle-spec/src/infrastructure/cli/ValidateCommand.ts)
+- [`packages/mantle-spec/src/infrastructure/cli/EmitOpenapiCommand.ts`](../../../packages/mantle-spec/src/infrastructure/cli/EmitOpenapiCommand.ts)
+- [`packages/mantle-runtime/src/infrastructure/mcp/McpToolCatalog.ts`](../../../packages/mantle-runtime/src/infrastructure/mcp/McpToolCatalog.ts)
+- [`packages/mantle-admin/src/mountMantleAdmin.ts`](../../../packages/mantle-admin/src/mountMantleAdmin.ts)
+- [`packages/mantle-admin/src/mountMantleOAuth.ts`](../../../packages/mantle-admin/src/mountMantleOAuth.ts)
+- [`packages/adapters/cloudflare/README.md`](../../../packages/adapters/cloudflare/README.md)
+- [`packages/adapters/cloudflare/src/worker/createMantleWorker.ts`](../../../packages/adapters/cloudflare/src/worker/createMantleWorker.ts)
+- [`packages/adapters/cloudflare/src/mount/mountRuntimeEndpoints.ts`](../../../packages/adapters/cloudflare/src/mount/mountRuntimeEndpoints.ts)
+- [`packages/adapters/cloudflare/src/mount/mountPublicRoutes.ts`](../../../packages/adapters/cloudflare/src/mount/mountPublicRoutes.ts)
+- [`packages/adapters/cloudflare/src/mount/mountMcp.ts`](../../../packages/adapters/cloudflare/src/mount/mountMcp.ts)
+- [`packages/adapters/cloudflare/src/oauth/cachePolicy.ts`](../../../packages/adapters/cloudflare/src/oauth/cachePolicy.ts)
+- [`docs/adr/0021-retire-starter-scaffolding.md`](../../../docs/adr/0021-retire-starter-scaffolding.md)
+- [`docs/migration-0.1.2.md`](../../../docs/migration-0.1.2.md)

package/docs/handbook/reference/trigger.md

@@ -0,0 +1,193 @@
+---
+description: Trigger field reference — http, mcp and lifecycle sources, path and tool-name rules, the eight lifecycle hooks and their timing and error policy.
+---
+# Trigger
+
+A Trigger binds one source to one [Procedure](./procedure.md). Every external surface for a write — an HTTP endpoint, an MCP tool, an entry-lifecycle hook — is a Trigger, and there is no other way to expose a Procedure. This page is the field-level contract; the concepts are in [Procedures and Triggers](../concepts/procedures-and-triggers.md). Envelope rules are in [Manifest envelope and conventions](./manifest.md), and diagnostic codes are catalogued in [Diagnostics](./diagnostics.md).
+
+## Fields
+
+`spec` accepts exactly two keys.
+
+| Field | Type | Required | Rules |
+|---|---|---|---|
+| `source` | mapping | yes | Discriminated by `kind`; the accepted sibling keys depend on it. |
+| `target` | `{ procedure }` | yes | Only the key `procedure`, naming a declared Procedure (`TRIGGER_TARGET_PROCEDURE_UNKNOWN`). |
+
+| `source.kind` | Other keys | Binds |
+|---|---|---|
+| `http` | `method`, `path` | One REST endpoint under `/api/`. |
+| `mcp` | `surface` | One tool on `/mcp` or `/mcp/staff`. |
+| `lifecycle` | `schema`, `on`, `errorPolicy` | Entry-writer hooks on one Schema. |
+
+An unknown `kind`, a missing `kind`, or a key that does not belong to the chosen kind is `INVALID_MANIFEST_ENVELOPE`. One Procedure may carry several Triggers — that is how the same handler becomes an HTTP endpoint and an MCP tool without duplicating logic.
+
+## `http` source
+
+```yaml
+apiVersion: cms.mantle.aotter.net/v1
+kind: Trigger
+metadata:
+  name: inventory-level-http
+spec:
+  source:
+    kind: http
+    method: PUT
+    path: /api/inventory/{sku}/level
+  target:
+    procedure: sync-inventory-level
+```
+
+| Field | Rules |
+|---|---|
+| `method` | `POST`, `PUT`, `PATCH` or `DELETE`. |
+| `path` | Non-empty string starting with `/`. OpenAPI `{param}` syntax for path params. No optional segments. |
+
+`GET` is deliberately absent. Reads are [Views](./view.md), which mount themselves from `surface` and need no Trigger at all; a Procedure is a write.
+
+### Path rules
+
+| Phase | Rule | Diagnostic |
+|---|---|---|
+| parse | `path` starts with `/`. | `INVALID_MANIFEST_ENVELOPE` |
+| validate | `path` starts with `/api/`, so adapters can route public pages and Procedure endpoints without ambiguity. | `TRIGGER_PATH_INVALID` |
+| validate | `(method, path)` is unique across every `http` Trigger. | `TRIGGER_PATH_COLLISION`, naming the Trigger that claimed it first. |
+| boot | `path` falls outside the adapter's reserved prefixes. | `TRIGGER_PATH_INVALID` |
+
+Only well-prefixed paths are tracked for collisions, so a path missing `/api/` produces one diagnostic rather than two. The Cloudflare Worker reserves `/admin`, `/_mantle`, `/api/auth`, `/api/views`, `/oauth`, `/mcp`, anything starting `/.well-known/oauth`, and the exact registrations `*` and `/*`; a prefix matches the path itself or a `/` or `{` boundary after it. See [Conventional Worker](../cloudflare/conventional-worker.md).
+
+### Routing and binding
+
+| Behavior | Detail |
+|---|---|
+| Path params | Each `{param}` binds to the identically named field on the target Procedure's `input`, which must declare it. |
+| Precedence | The invocation merges the body first and the path params second, so **the path wins** over a same-named body field. |
+| Trailing slash | `/api/posts` and `/api/posts/` are the same route; the root `/` is preserved. |
+| Percent-encoding | Each request segment is decoded once, so `/api/by%2Dtag` matches the literal `/api/by-tag`. Malformed encoding such as `%GG` is a routing miss (404), not a 500. |
+| Body | Must be a JSON object. Anything else is `INPUT_VALIDATION_FAILED` (400) with *HTTP Trigger request body must be a JSON object*. A body over 1 MiB is the same code at 413. |
+| Empty body | A `DELETE`, or any request without a JSON content type, is treated as `{}` — bind those inputs through path params. |
+
+A success is `{ "ok": true, "data": <handler result> }`; a failure is `{ "ok": false, "diagnostic": ... }` at the diagnostic's mapped status. `http` Triggers are also what the OpenAPI emitter projects into operations.
+
+## `mcp` source
+
+```yaml
+apiVersion: cms.mantle.aotter.net/v1
+kind: Trigger
+metadata:
+  name: approve-purchase-order-mcp
+spec:
+  source:
+    kind: mcp
+    surface: staff
+  target:
+    procedure: approve-purchase-order
+```
+
+| `surface` | Endpoint | Gate |
+|---|---|---|
+| `public` | `/mcp` | Bearer token. |
+| `staff` | `/mcp/staff` | Bearer token plus a staff role read from storage on every invocation. |
+
+`surface` is **discovery only**. It decides which tools appear in `tools/list` on which endpoint; it authorizes nothing. The target Procedure's `requires.auth.all` predicates and its optional guard are re-evaluated on every `tools/call` against the authenticated caller, exactly as they are over HTTP. A `public`-surface Procedure that requires `ctx.staff` is discoverable on `/mcp` and will still be denied there.
+
+The tool name is derived from the **Procedure's** `metadata.name`, not the Trigger's: lower-cased, with `-` replaced by `_`. Only one Trigger may claim a given `(surface, tool name)` pair; a second is `MCP_TOOL_NAME_COLLISION`. The same code also fires when the mangled name hits a reserved generic tool name or prefix, or a Schema's or another Procedure's segment — see [Reserved names](./manifest.md#reserved-names).
+
+The tool carries the Procedure's `title` and `description`, with a short authorization summary appended to the description. `output` is not surfaced; MCP clients infer the response shape from the `tools/call` result. See [MCP and agents](../concepts/mcp-and-agents.md).
+
+## `lifecycle` source
+
+```yaml
+apiVersion: cms.mantle.aotter.net/v1
+kind: Trigger
+metadata:
+  name: 010-verify-purchase-token
+spec:
+  source:
+    kind: lifecycle
+    schema: purchase-orders
+    on: [before_create]
+    errorPolicy: abort
+  target:
+    procedure: verify-purchase-token
+```
+
+| Field | Type | Required | Default | Rules |
+|---|---|---|---|---|
+| `schema` | string | yes | — | A declared Schema (`LIFECYCLE_SCHEMA_UNKNOWN`). |
+| `on` | `LifecycleHook[]` | yes | — | Non-empty; every entry from the closed list below. |
+| `errorPolicy` | `abort` \| `continue` | no | `abort` for `before_*`, `continue` for `after_*` | See below. |
+
+`errorPolicy: abort` is rejected at parse time when **any** `after_*` hook appears in `on`: an `after_*` hook runs once the response has already been sent, so an abort could never reach the caller. Split the `after_*` hooks into their own Trigger, or declare `continue`.
+
+> **Info**
+> `Schema.spec.lifecycle` (`publishing` / `operational`) is a different domain that shares the word. That setting governs which states an entry may be in; a lifecycle Trigger governs what fires around a mutation. See [Schema](./schema.md#lifecycle).
+
+### Hooks
+
+| Hook | Fires |
+|---|---|
+| `before_create` | Before the insert. |
+| `after_create` | After the insert. |
+| `before_update` | Before an update **or** any status transition whose target is not `published` — this includes unpublish and archive. |
+| `after_update` | After an update or such a transition. |
+| `before_delete` | Before the delete. |
+| `after_delete` | After the delete, only when a row was actually removed. |
+| `before_publish` | Before a transition to `published`. |
+| `after_publish` | After a transition to `published`. |
+
+There are no unpublish-specific or archive-specific hooks. Do not read `before_update` / `after_update` as edit-only.
+
+### Error policy
+
+| Phase | Default | Behavior |
+|---|---|---|
+| `before_*` | `abort` | A throwing hook cancels the surrounding mutation and the caller receives the hook's own diagnostic. A hook that rejects a write on purpose raises `LIFECYCLE_HOOK_REJECTED` (409). Under `continue` the failure is logged and the mutation proceeds. |
+| `after_*` | `continue` | The committed mutation stands. On the inline or `waitUntil` path a failure is logged and swallowed. With a deferred dispatcher wired in, the failure reaches the delivery adapter so its at-least-once retry and dead-letter policy can run. Neither path ever rolls back. |
+
+### Handler input and `ctx.event`
+
+Hook input is phase-specific.
+
+| Phase | Handler input |
+|---|---|
+| `before_*` | The original **pre-projection** Procedure input, so a hook can read side-channel fields the row never stores — a CAPTCHA token, a client nonce. It falls back to the row's `data` when there is no caller input. |
+| `after_*` | The persisted `entry.data` only. Deferred envelopes deliberately never carry arbitrary request input. |
+
+Every hook handler also receives `ctx.event`:
+
+| Field | Value |
+|---|---|
+| `id` | Stable event id, unchanged across enqueue fallback and deferred retries. |
+| `trigger` | The firing Trigger's `metadata.name`. |
+| `hook` | The hook name. |
+| `schema` | The watched Schema name. |
+| `entry` | `null` only on `before_create`; the pre-mutation row for the other `before_*` hooks; the persisted post-mutation row for every `after_*`. |
+
+Deferred handlers key on `${ctx.event.id}:${ctx.event.trigger}`. See [Procedure](./procedure.md#conflicts-and-idempotency).
+
+### Ordering and coverage
+
+When several lifecycle Triggers bind the same `(schema, hook)`, they fire **alphabetically by `Trigger.metadata.name`**. Choose names that sort the way you want them to run — the `010-`, `020-` convention exists for exactly this, and the code generator handles the leading digits.
+
+Hooks are wired through a repository decorator that wraps the single entry-writer chokepoint, so **Staff MCP, Admin and builtin Procedure writes all fire the same hooks**. There is no write path that bypasses them.
+
+For deferred `after_*` delivery, the ordered Trigger-name list is captured into one versioned envelope carrying the persisted row and a small identity snapshot. Every captured Trigger runs before a failure is reported back, so a retry may replay Triggers that already succeeded — hence the idempotency key. Queue acceptance is not transactional with the entry write, the `waitUntil` fallback is best-effort, and exactly-once is not promised. See [Deferred hooks on Queues](../cloudflare/deferred-hooks-queues.md).
+
+## Source
+
+- [`packages/mantle-spec/src/domain/model/ManifestGrammar.ts`](../../../packages/mantle-spec/src/domain/model/ManifestGrammar.ts)
+- [`packages/mantle-spec/src/domain/service/ManifestParser.ts`](../../../packages/mantle-spec/src/domain/service/ManifestParser.ts)
+- [`packages/mantle-spec/src/domain/service/ManifestGraphValidator.ts`](../../../packages/mantle-spec/src/domain/service/ManifestGraphValidator.ts)
+- [`packages/mantle-spec/src/domain/service/McpToolNaming.ts`](../../../packages/mantle-spec/src/domain/service/McpToolNaming.ts)
+- [`packages/mantle-runtime/src/domain/service/PathMatcher.ts`](../../../packages/mantle-runtime/src/domain/service/PathMatcher.ts)
+- [`packages/mantle-runtime/src/domain/service/TriggerIndex.ts`](../../../packages/mantle-runtime/src/domain/service/TriggerIndex.ts)
+- [`packages/mantle-runtime/src/usecase/lifecycle/RunLifecycleHooksUseCase.ts`](../../../packages/mantle-runtime/src/usecase/lifecycle/RunLifecycleHooksUseCase.ts)
+- [`packages/mantle-runtime/src/infrastructure/persistence/LifecycleHookingEntryRepository.ts`](../../../packages/mantle-runtime/src/infrastructure/persistence/LifecycleHookingEntryRepository.ts)
+- [`packages/mantle-runtime/src/domain/port/DeferredHookDispatcher.ts`](../../../packages/mantle-runtime/src/domain/port/DeferredHookDispatcher.ts)
+- [`packages/mantle-runtime/src/infrastructure/http/createMantleRequestHandler.ts`](../../../packages/mantle-runtime/src/infrastructure/http/createMantleRequestHandler.ts)
+- [`packages/mantle-runtime/src/infrastructure/http/readJsonBody.ts`](../../../packages/mantle-runtime/src/infrastructure/http/readJsonBody.ts)
+- [`packages/mantle-runtime/src/usecase/boot/ValidateBootUseCase.ts`](../../../packages/mantle-runtime/src/usecase/boot/ValidateBootUseCase.ts)
+- [`packages/mantle/src/codegen/emitMantleModule.ts`](../../../packages/mantle/src/codegen/emitMantleModule.ts)
+- [`packages/adapters/cloudflare/src/worker/createMantleWorker.ts`](../../../packages/adapters/cloudflare/src/worker/createMantleWorker.ts)
+- [`packages/adapters/cloudflare/src/mount/mountMcp.ts`](../../../packages/adapters/cloudflare/src/mount/mountMcp.ts)