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

package/docs/handbook/concepts/lifecycle-and-locales.md

@@ -1,142 +1,19 @@
----
-description: Choose between publishing and operational Schemas, and understand how site locales, localized Schemas and translation children fit together.
----
 # Lifecycle and locales
 
-Two per-Schema decisions shape how an entry behaves for its whole life: which state machine it follows, and whether it carries a locale. Both are declared on the [Schema](../reference/schema.md); neither is a site-wide setting.
+Schemas default to `operational`: rows are live immediately and edit in place. Opt-in `publishing` adds `status` (draft/published/archived), nullable `published_at` and a scope-aware `(published_at, id)` index.
 
-## Publishing versus operational
+Generated `<table>.publish`, `.unpublish` and `.archive` Procedures take `{ id, expectedVersion }`, require admin/system and perform one atomic UPDATE. Publish checks required fields, visibility, TTL, source state and OCC. A failed guard is `CONFLICT`. Store cannot write status/published_at directly. Admin permits generic publishing edits only on drafts; Store does not add that separate Admin editing rule.
 
-`spec.lifecycle` is `publishing` (the default) or `operational`. The modes mix freely inside one site.
+Public Views see published rows only. Other reads expose drafts only to admin/system. This policy applies to joins and nested queries too.
 
-**`publishing`** is for content a person stages and then releases: posts, pages, announcements, product copy. The point of the mode is that a draft exists and is not readable by the public until someone publishes it. The runtime enforces this: a public declarative View over a publishing Schema is compiled with `status = published` even when the manifest omits the filter ([View reference](../reference/view.md#surfaces)).
+## Translations
 
-**`operational`** is for records written as a side effect rather than drafted: submissions, inquiries, orders, inventory snapshots, grant and audit rows. The point of the mode is that the row is real the moment it is created. Declare it on any Schema whose rows a human should inspect and correct, never stage and publish.
+`localized: true` declares a locale string. `translates: { parent, on }` declares a localized child sharing a join key with its parent. A scoped parent needs the same child scope column. A publishing translation can publish only when its caller-visible parent is published (or operational); the parent guard is inside the atomic UPDATE. Unpublishing a parent hides translations without changing their status.
 
-| `publishing` — from | To |
-|---|---|
-| `draft` | `published`, `archived` |
-| `published` | `archived`, `draft` |
-| `archived` | `draft` |
+Store translation reads merge visible parent fields, with child fields taking precedence. Authored Views return only their SELECT outputs. Generated `translations.ts` exports `translationLocales(db, caller, parent, rows)` for a parent page (up to 500 storage-named rows); it uses batched authorized child reads rather than one query per parent. Stored locale values remain plain strings; site locales do not rewrite or validate them automatically.
 
-| `operational` | Behavior |
-|---|---|
-| On create | `status: published` immediately |
-| Editing | In place, in any status |
-| Transitions | None. Publish, unpublish and archive all reject. |
+SQLite/PostgreSQL interactive Store transactions refuse to combine translation publication and a parent status change in either order. D1 has no interactive Store transactions. The app owns consistency for native transactions outside Store.
 
-Any transition the machine does not allow returns `CONFLICT` (HTTP 409). That includes every transition request against an operational Schema, and deleting a `published` entry of a publishing Schema — unpublish it first. Operational entries can be deleted in any status. A builtin `archive` Procedure may only target a publishing Schema.
+## Expiry
 
-`status: published` on an operational row is not a grant of public read access. Reads are still authorized by the [View](./views.md) that exposes them.
-
-### What each surface shows
-
-| Surface | `publishing` | `operational` |
-|---|---|---|
-| Admin | Draft and published buckets, publish and unpublish controls, archive | Flat list, no lifecycle chrome; `uiSchema.list` supplies the columns |
-| Staff MCP | `create_draft_<schema>`, `update_draft_<schema>` | `create_record_<schema>`, `update_record_<schema>` |
-| Staff MCP, both modes | `request_publish`, `unpublish_entry`, `archive_entry`, `delete_entry` | same generic lifecycle tools |
-
-### Procedure-managed collections
-
-Root `schema.readOnly: true` marks a collection whose authority lives in its declared Procedures, not in generic authoring. Staff MCP emits no `create_*` or `update_*` tool for it, and Admin's generic create, update, status change and delete return `CONFLICT` with a message saying the Schema is read-only on generic authoring surfaces. Declared Views and Procedures keep working. Use it for operational mirrors, projections and audit rows.
-
-## Locales in three layers
-
-Localization is not one switch. Three independent layers have to agree.
-
-| Layer | Where | What it decides |
-|---|---|---|
-| `Schema.spec.localized` | Manifest | Whether rows of this collection may carry `data.locale` |
-| `site_config.locales` | Adapter `siteDefaults.locales`, boot-synced into the `site_config` row | Which locale tags exist for this deployment; the first entry is the canonical locale |
-| `data.locale` | The entry | Which locale this particular row is |
-
-`siteDefaults.locales` is code-owned: Core rewrites the stored row at boot whenever the declared list differs, so the code stays canonical. Brand, title and description seed once and are then edited through site settings. See [Site defaults and site_config](../reference/site-config.md).
-
-### Canonical tags
-
-Mantle accepts a deliberately narrow subset of BCP 47: a two- or three-letter language, plus an optional two-letter region. Mixed spellings are canonicalized, so `zh-tw`, `ZH_TW` and `zhTW` all become `zh-TW`, and the list is deduplicated in place. Anything else fails at boot with `InvalidSiteDefaultsError`.
-
-> **Script subtags are unsupported**
-> `zh-Hant`, `zh-Hans`, `sr-Latn` and `sr-Cyrl` are valid BCP 47 but rejected in this version. Use region tags: `zh-TW` for Traditional Chinese, `zh-CN` for Simplified.
-
-### The write-time gate
-
-Every authoring path — Admin, Staff MCP and builtin Procedures — runs the same guard, per request, against the current site locales.
-
-| Condition | Result |
-|---|---|
-| Non-localized Schema, `data.locale` present | `INPUT_VALIDATION_FAILED` |
-| Localized Schema, `data.locale` missing or empty | `INPUT_VALIDATION_FAILED`, skipped for partial draft saves |
-| Localized Schema, `data.locale` not in the site locales | `INPUT_VALIDATION_FAILED`, with the enabled locales as candidates |
-| Site locales list is empty | Membership is not checked |
-
-`locale` is a reserved data field. A non-localized Schema that declares it is rejected outright; when such a Schema genuinely needs a language value, name it after its domain meaning — `replyLocale` on a support ticket, `orderLocale` on an order — and validate it with an `enum` like any other field.
-
-### Boot checks versus per-request resolution
-
-Boot validates shape only: the locale tags canonicalize, every `translates` reference resolves, and a `localized: true` Schema has at least one site locale (`SCHEMA_LOCALIZED_REQUIRES_SITE_LOCALES`). The active locale set is read from `site_config` per request, so changing the list does not require a redeploy of the manifest — but it does require the code-owned `siteDefaults` to agree, because boot resynchronizes the row.
-
-## Versions of one entity versus independent rows
-
-Two shapes are legal, and the choice is about identity, not about language count.
-
-**A standalone localized Schema** treats each locale row as an independent record. Use it when nothing is shared between languages except a naming convention. A blog whose translations are independent posts does this: one localized `posts` Schema with `uniqueIndexes: [[slug, locale]]`.
-
-**A non-localized parent plus a localized `translates` child** treats locale rows as versions of one entity. Use it when several rows describe the same thing and editors need to see which languages are missing. Only this shape powers Admin's translation grouping and completeness; Admin renders the child as locale tabs inside the parent's editor rather than as its own collection.
-
-```yaml
-apiVersion: cms.mantle.aotter.net/v1
-kind: Schema
-metadata:
-  name: products
-spec:
-  title: Products
-  localized: false
-  lifecycle: publishing
-  uniqueIndexes: [[sku]]
-  schema:
-    type: object
-    additionalProperties: false
-    required: [sku, priceMinor]
-    properties:
-      sku: { type: string, pattern: "^[A-Z0-9-]+$" }
-      priceMinor: { type: integer, x-mcp-hint: money-minor }
----
-apiVersion: cms.mantle.aotter.net/v1
-kind: Schema
-metadata:
-  name: product-translations
-spec:
-  title: Product translations
-  localized: true
-  translates: { parent: products, on: sku }
-  lifecycle: publishing
-  uniqueIndexes: [[sku, locale]]
-  indexes: [[locale, sku]]
-  schema:
-    type: object
-    additionalProperties: false
-    required: [sku, name]
-    properties:
-      sku: { type: string, pattern: "^[A-Z0-9-]+$" }
-      locale: { type: string }
-      name: { type: string, minLength: 1 }
-      summary: { type: string, x-mcp-hint: markdown }
-```
-
-The parent holds what every language shares and stays non-localized. The child sets `localized: true`, declares `locale` without listing it in `required` — the write-time gate enforces presence — and owns at least one content field besides the join field and `locale`. A parent that is itself localized, a missing join field on either side, or a child with no content field are all rejected at parse or validate time; the codes are listed in the [Schema reference](../reference/schema.md#translates).
-
-When you keep parallel locale rows in step, translate display strings only. Field names, option values, step identifiers and result keys must stay identical across locales, or the same View and the same MCP tool stop describing the same thing.
-
-The full worked version of this pattern, with a locale-parameterized public View and its REST response, is [Publication](../../examples/builtin-publication.md).
-
-## Source
-
-- [`packages/mantle-spec/src/domain/service/LifecycleStateMachine.ts`](../../../packages/mantle-spec/src/domain/service/LifecycleStateMachine.ts)
-- [`packages/mantle-spec/src/domain/service/LocaleCanonicalizer.ts`](../../../packages/mantle-spec/src/domain/service/LocaleCanonicalizer.ts)
-- [`packages/mantle-spec/src/domain/service/SiteDefaultsValidator.ts`](../../../packages/mantle-spec/src/domain/service/SiteDefaultsValidator.ts)
-- [`packages/mantle-spec/src/domain/model/SiteConfig.ts`](../../../packages/mantle-spec/src/domain/model/SiteConfig.ts)
-- [`packages/mantle-runtime/src/domain/service/io/EntryWriteGuard.ts`](../../../packages/mantle-runtime/src/domain/service/io/EntryWriteGuard.ts)
-- [`packages/mantle-runtime/src/infrastructure/mcp/McpToolCatalog.ts`](../../../packages/mantle-runtime/src/infrastructure/mcp/McpToolCatalog.ts)
-- [`docs/skills/develop/SKILL.md`](../../skills/develop/SKILL.md)
+TTL hides expired rows but does not delete them. Use generated system-only `<schema>.sweepExpired` from an application scheduler; [TTL maintenance](../guides/native-execution.md#ttl-maintenance) defines limits and cursors. Until removed, expired rows still occupy unique keys.

package/docs/handbook/concepts/mcp-and-agents.md

@@ -1,134 +1,37 @@
----
-description: Mantle serves /mcp and /mcp/staff from the same Manifest — tool naming, the OAuth model, connecting a client, llms.txt, WebMCP and skills.
----
 # MCP and agents
 
-Mantle is an MCP server out of the box. Nothing is registered, exported or annotated to make it one: the same compiled plan that produces REST and Admin also produces the tool catalog, so an agent and a browser reach identical behavior through different transports. `/mcp` and `/mcp/staff` are that live-app catalog — Manifest → RuntimePlan verbs — not a how-to-author-Mantle manual. The CLI and pinned package docs are the authoring SSOT; MCP does not mirror the CLI. This page covers the two surfaces, how tools are named, how a client authenticates, and the rest of the agent-facing surface area.
+Mount generated `mcp()` with the app's native handle and verified Caller resolver. The official MCP SDK loads only on a matching request. Optional auth stays behind the application's dynamic auth import.
 
-## Two surfaces
+| Endpoint | Tools |
+| --- | --- |
+| `/mcp` | Public Views and Procedures exposed by public MCP Triggers |
+| `/mcp/admin` | Admin Views, admin Trigger Procedures, generated publishing transitions and selected product tools |
 
-| Mount | Caller | Exposes |
-|---|---|---|
-| `/mcp` | Any caller the site's HTTP routes would accept: OAuth bearer, same-origin cookie session, or anonymous. Each tool's `requires` decides; a `tools/call` that needs identity answers `401` with the OAuth challenge | Views with `surface: public`, and Procedures reached by an MCP Trigger with `surface: public` |
-| `/mcp/staff` | Authenticated caller holding a staff role | Views with `surface: staff`, the generic authoring tools (rank-gated at `tools/call`), Procedures reached by an MCP Trigger with `surface: staff` |
+Names are snake-case; a View named `my-orders` becomes `my_orders`. Each call retains declared authorization, scoped/TTL/publication SQL and input checks. Admin tools require admin authority. Tool visibility and UI hints grant no authority. Cookie-session mutations retain origin checks.
 
-Both accept tokens for one canonical protected resource, `${PUBLIC_ORIGIN}/mcp`. `/mcp/staff` is a stricter server-side role projection, not a second OAuth audience.
+Views return structured `{ rows, nextCursor? }`. SQL Procedures retain native `{ results }`; application ref results remain app-owned. Selected boundaries redact native errors. Never retry an uncertain write automatically.
 
-## Tool naming
+The app owns OAuth configuration, discovery and consent; follow [OAuth](../guides/oauth.md) and [authentication](../cloudflare/authentication.md). Public anonymous reads can avoid auth entirely; invalid supplied credentials cannot become anonymous. Authority-sensitive endpoints retain fresh primary checks.
 
-A tool name is derived from a manifest name by `mcpToolNameSegment`: lowercased, with `-` replaced by `_`.
+[MCP Apps](../guides/mcp-apps.md) add static UI resources through the public contributor hook. Admin uses the same hook from its separate package. Credentials never go in App HTML. WebMCP catalogues are generated display/tool metadata for the mounted Admin product; server checks remain authoritative.
 
-| Tool | Produced by | Surface |
-|---|---|---|
-| `query_view_<segment>` | Public or staff View (never internal) | The View's own `surface` |
-| `create_draft_<schema>`, `update_draft_<schema>` | A Schema with `lifecycle: publishing` | Staff |
-| `create_record_<schema>`, `update_record_<schema>` | A Schema with `lifecycle: operational` | Staff |
-| `request_publish`, `unpublish_entry`, `archive_entry`, `delete_entry` | Present when an applicable Schema exists | Staff |
-| `create_media_upload`, `commit_media_upload` | Media storage bound and at least one purpose declared | Staff |
-| `<procedure segment>` | A Trigger with `source.kind: mcp` | The Trigger's `source.surface` |
+See [surface contracts](../reference/surface.md) for tool schemas, challenges and scalar conversion.
 
-A Schema whose root `schema` sets `readOnly: true` gets no authoring tools; its declared Procedures still work. Update tools add required `id` and `expected_version` arguments, and fields carrying `x-mantle-bind` are stripped from authoring tool schemas because the runtime stamps them. Those generic names and the `create_draft_`, `update_draft_`, `create_record_`, `update_record_` and `query_view_` prefixes are reserved; a collision is rejected at validation with `MCP_TOOL_NAME_COLLISION`.
+## When a host shows old tools
 
-Procedures are never exposed on their own. A Procedure becomes a tool only through a Trigger of `kind: mcp`, exactly as it becomes a route only through a Trigger of `kind: http`. Writing a Procedure with no Trigger gives you typed logic that nothing can call from outside — which is what a guard Procedure or a cron-invoked Procedure wants. See [Writes: Procedures, Triggers and hooks](./procedures-and-triggers.md).
+A fresh `tools/list` always returns the deployed tools, but many hosts keep their own copy and do not ask again after a deploy. Mantle sends no list-changed notifications: tools change only at deploy, and the hosts that keep copies do not act on them. Instead each generated tool's description ends with its own version, and the results of a call that reaches the tool carry the deployed version, so a model holding an older definition can see it, correct its call or ask the user to refresh. Failures also state the input schema the tool is listed with now, except authorization refusals. A call naming a tool the catalogue no longer has gets the protocol's unknown-tool error, whose message gives `serverInfo.version`: unless the application sets it, a hash of every tool the endpoint serves, before per-caller filtering. Refusals before a call reaches its tool, such as authentication challenges, carry neither.
 
-## The OAuth model
+In Admin, WebMCP results from the tool route carry the version, and refusals add it with the input schema, except authorization refusals; a tool removed since the page loaded is refused as not found, without a catalogue version. Admin's two navigation tools, `admin_get_context` and `admin_navigate`, carry no version: the page defines and runs them without a server call, so it cannot list one definition and run another, and a reload after a deploy replaces both. The exact shapes are in [surface contracts](../reference/surface.md#tool-versions).
 
-The Cloudflare adapter runs one Better Auth 1.7 instance for staff identity, authorization, consent, client registration and MCP resource verification. Client identity is CIMD-first — the MCP 2026-07-28 Client ID Metadata Document profile, which is why the Worker needs the `global_fetch_strictly_public` flag to fetch client metadata across the public Internet boundary. Unauthenticated Dynamic Client Registration remains available as a bounded path with a 90-day default lifetime for clients that do not present CIMD. One non-colon scope, `mcp`, is advertised in `scopes_supported`, because clients such as claude.ai reject colon-shaped scopes; per-surface enforcement then happens server-side, not through scope strings. Authorization is session-bound: the JWT's originating Better Auth session must still exist and be unexpired, so signing out of Admin also ends that session's MCP access, and a refresh token is not an independent authorization. Invalid credentials on either mount, and anonymous requests to `/mcp/staff`, answer `401` with a `WWW-Authenticate` challenge pointing at the RFC 9728 protected-resource metadata document served under the auth mount; on `/mcp` an anonymous caller can list tools and call anonymous ones, and receives the same `401` challenge from the first `tools/call` whose target requires identity. Authorization endpoints live under `/api/auth/oauth2/*` and are discovered from the advertised metadata, never hard-coded.
+How each client refreshes its copy (as of 2026-10):
 
-## Connecting a local client
-
-Start the dev server and use the exact origin it prints. Before touching client configuration, confirm the endpoint is reachable and protected:
-
-```sh
-curl -i http://localhost:8787/mcp
-```
-
-An OAuth-protected endpoint answers `401` with a `WWW-Authenticate` resource-metadata challenge before sign-in. A `503 setup_incomplete` instead means Auth configuration is missing; see [Authentication](../cloudflare/authentication.md).
-
-Prefer the client's native remote HTTP and OAuth support. Use a standard HTTP-to-stdio bridge only when the client accepts stdio MCP servers and cannot connect to remote HTTP directly:
-
-```sh
-npx -y mcp-remote http://localhost:8787/mcp
-```
-
-Mantle owns no local proxy and no auth-bypass mode. After connecting, inspect `tools/list`, then make one read-only `query_view_*` call before invoking any mutation — it proves the credential, the surface and the data path in one step that cannot damage anything. Use project-scoped client configuration where the client offers it, and never commit OAuth tokens or the bridge's token cache.
-
-> **Discovery is not enforcement**
-> `tools/list` filtering is UX. Every `tools/call` re-evaluates the manifest predicates and the guard through the same evaluator REST uses, so a guessed tool name gains nothing. See [Authorization](./authorization.md).
-
-## The agent-readable web surface
-
-When a Worker mounts public pages, the same content is served in a form agents can read without parsing HTML:
-
-- **Markdown mirrors.** Every entry page has a `.md` twin at the same path, and entry pages advertise it with `<link rel="alternate" type="text/markdown">`.
-- **`llms.txt` indexes.** `GET /llms.txt` lists the site; `GET /:locale/llms.txt` lists one locale. Pages hold 50 entries, ordered `updatedAt DESC, id DESC`, with a forward `cursor`, a `Link: ...; rel="next"` header and a `## Continue` section.
-- **Sitemap.** `GET /sitemap.xml` returns a urlset, or an index linking `/sitemap.xml?part=1&cursor=...` parts of up to 2,000 URLs each.
-
-Only `status: published` entries appear anywhere in that set. Details are in [Public web, SEO and cache](../cloudflare/public-web.md).
-
-## WebMCP in the browser
-
-### Admin: tools for the signed-in staff member
-
-Admin UI registers staff tools in browsers supporting `document.modelContext`.
-The catalog comes from `GET /admin/api/webmcp`; calls use
-`POST /admin/api/mcp` with the current staff session. Server-side role checks,
-Procedure authorization, and optimistic concurrency remain in force.
-`admin_get_context` and `admin_navigate` add page context and navigation.
-The WebMCP control appears after registration succeeds; unsupported browsers
-can continue using the regular Admin UI.
-
-Owners can explore application API documentation in Developer UI:
-`/admin/dev/docs/api` for HTTP, `/admin/dev/docs/mcp` for remote MCP, and
-`/admin/dev/docs/webmcp` for the Admin catalog and public-page capabilities.
-These pages show projected definitions. Remote clients connect to the host's
-advertised MCP endpoints using the authentication described above.
-See the [Admin API guide](../../../packages/mantle-admin/README.md#admin-webmcp).
-
-### Public pages: opt-in registration
-
-`@aotter/mantle-web/webmcp` exposes public capabilities as tools inside a page, for browsers implementing the draft imperative WebMCP API. Importing the subpath has no side effect; registration starts only when `bindWebMcp()` is called.
-
-```ts
-import { bindWebMcp } from "@aotter/mantle-web/webmcp";
-
-const binding = await bindWebMcp();
-// later, when the page or app scope ends
-binding.dispose();
-```
-
-It feature-detects `document.modelContext` and returns `{ supported: false }` on browsers without it. This public-page binding registers only public capabilities. Staff tools use the separate authenticated Admin integration above. Existing host tool names are inspected and skipped, never replaced. A server-backed page discovers the safe descriptors published at `GET /api/views` and calls the same-origin `GET /api/views/<name>` routes; a browser-local SPA passes `projectCallableCapabilities(plan, { surface: "public" })` and its own invoker. Procedure tools must still originate from an explicit public MCP Trigger, and invocation enters the runtime through that Trigger, so browser tools cannot bypass validation or authorization. See [Runtime pipeline and adapters](./runtime-and-adapters.md).
-
-## Skills for your coding agent
-
-The installed SDK ships version-matched instructions for agents working on a Mantle project. Project them into the repository:
-
-```sh
-pnpm exec mantle skills
-pnpm exec mantle skills --check
-```
-
-This copies every skill the installed package marks `projection: project` — the develop skill among them — into matching `.agents/skills/mantle-*` and `.claude/skills/mantle-*` paths. Both layouts receive identical bytes; `--check` detects drift without writing. Skills that act destructively or target one platform stay out of that set and are opt-in. Manifest generation never rewrites agent instructions.
-
-The bootstrap `mantle` skill is also available from the plugin marketplace.
-The ongoing workflows come from the installed SDK through `mantle skills`:
-
-```sh
-# Canonical
-npx skills add aotter/mantle
-
-# Claude Code — two separate prompts
-/plugin marketplace add aotter/mantle
-/plugin install mantle@mantle
-```
-
-Never point a versioned project at a mutable branch. See [Project layout and the CLI loop](../start/project-and-cli.md).
-
-## Source
-- [`docs/adapter-guide.md`](../../../docs/adapter-guide.md)
-- [`docs/adr/0014-auth-better-auth-and-multi-tenant-mcp.md`](../../../docs/adr/0014-auth-better-auth-and-multi-tenant-mcp.md)
-- [`packages/mantle-spec/src/domain/service/McpToolNaming.ts`](../../../packages/mantle-spec/src/domain/service/McpToolNaming.ts)
-- [`packages/mantle-web/README.md`](../../../packages/mantle-web/README.md)
-- [`packages/mantle/README.md`](../../../packages/mantle/README.md)
-- [`packages/adapters/cloudflare/README.md`](../../../packages/adapters/cloudflare/README.md)
-- [`docs/skills/develop/SKILL.md`](../../skills/develop/SKILL.md)
+| Client | Refresh |
+| --- | --- |
+| claude.ai connectors | A server-side copy keyed by URL, kept about an hour (users report up to 24 hours). Only adding the connector again under a new URL, such as `?v=2`, forces a refresh, and that needs authorization again. |
+| Claude Code | `/mcp` reconnect, or a new session |
+| ChatGPT developer mode | Refresh the connection, then start a new chat |
+| Published ChatGPT apps | A daily scan, or Rescan, followed by review; keep tools compatible meanwhile |
+| Cursor | Quit fully and reopen |
+| VS Code | Run "MCP: Reset Cached Tools", or restart the server |
+| Gemini CLI | `/mcp reload` |
+| MCP Inspector | The refresh button |

package/docs/handbook/concepts/procedures-and-triggers.md

@@ -1,221 +1,9 @@
----
-description: How writes work — typed Procedures with a code seam, the three Trigger kinds that bind them, builtin ops, lifecycle hooks and the HTTP envelope.
----
-# Writes: Procedures, Triggers and lifecycle hooks
+# Writes: Procedures and Triggers
 
-Every write goes through a Procedure, and every Procedure that anything outside the runtime can reach has a Trigger. This page explains the split and the lifecycle hook contract. Field-level rules are in the [Procedure](../reference/procedure.md) and [Trigger](../reference/trigger.md) references.
+Writes use Store or declared Procedures. Raw SQL writes bypass scope, TTL, publishing and system-column rules.
 
-## A Procedure is a callable, not an endpoint
+SQL Procedures compile to native statements and return `{ results }`, one row array per statement. Row operations must affect exactly one row; a stale explicit version lock or unique clash is `CONFLICT`. Multi-statement Procedures run atomically; single-statement writes use native autocommit. See [native execution](../guides/native-execution.md) for uncertain outcomes. Never retry an `OUTCOME_UNKNOWN` write automatically.
 
-A Procedure declares typed `input`, typed `output`, optional `requires`, and one `handler`. It contains no path, no method and no tool name; it is transport-agnostic on purpose, so calling a Procedure name as a URL returns `404`. Exposing a write is a separate, explicit decision.
+A ref Procedure generates a typed `Handlers` key. Its handler receives `(ctx, input)` with `{ caller, db, store }` bound to the same Caller and transaction. Generated `requires` runs first. Handlers own side effects and their transaction boundaries.
 
-Invocation runs in a fixed order: static auth predicates, input validation, the optional guard Procedure, the handler, then output validation — which checks the returned value but does not strip extra fields.
-
-The Procedure is also the only atom with a code seam. `handler: { kind: ref, ref: <key> }` names an opaque registration key — not a file path — that your project maps to a function in its `handlers` object. A key with no registered function fails at boot with `HANDLER_NOT_REGISTERED`.
-
-## A Trigger is the only binding
-
-`Trigger.spec.target.procedure` names a declared Procedure; `spec.source` says what reaches it. There are three source kinds.
-
-| `source.kind` | Binds to | Notes |
-|---|---|---|
-| `http` | `method` and `path` | `POST`, `PUT`, `PATCH`, `DELETE` only. `GET` is absent because reads belong to [Views](./views.md). The path must start `/api/`, must not collide with another Trigger or an adapter-reserved prefix, and may use OpenAPI `{param}` segments that auto-bind to same-named input fields. |
-| `mcp` | `surface: public` or `staff` | The tool is named after the Procedure, lowercased with hyphens replaced by underscores. Surface controls discovery only; `requires` is re-evaluated on every `tools/call`. |
-| `lifecycle` | `schema`, `on: [<hook>]`, optional `errorPolicy` | Fires around entry mutations. See [Lifecycle hooks](#lifecycle-hooks). |
-
-One Procedure may carry several Triggers, and that is how the same handler becomes an HTTP endpoint, an MCP tool and a hook without duplicated logic. Adding a transport is additive: write another Trigger, leave the Procedure alone.
-
-## Builtin or `ref`
-
-`handler.kind: builtin` is a thin shortcut over the storage adapter. The rule is simple: **use `builtin` when the body of the operation is "insert a row", "update a row" or "delete a row"; reach for `ref` when there is real business logic.** A guard Procedure can never be builtin.
-
-| `op` | What it does | Input contract |
-|---|---|---|
-| `create` | Projects `input ∩ Schema.properties`, stamps `x-mantle-bind` fields, inserts. Status is `draft`, or `published` for an operational Schema. Returns the created `EntryRow`. | An object schema |
-| `update` | Loads, merges the patch, bumps `version` under optimistic concurrency using the caller's observed `expectedVersion` (not `version+1`) | `id` (strict string) and `expectedVersion` (strict number), both required |
-| `upsert` | With `match`, looks the row up by natural key: update with the caller token, or create when no row exists and no version was sent | `match` equals one `uniqueIndexes` tuple exactly, in order; no `id`; `expectedVersion` declared as strict number but not globally required |
-| `delete` | Hard delete by id | `id` (strict string) required |
-| `archive` | Transitions to `archived`, or `CONFLICT` if the machine disallows it | `id` required; publishing Schemas only |
-
-`request_publish` and `publish` are deliberately not builtin ops. They are lifecycle operations, not CRUD primitives.
-
-Every builtin write runs the same guards: locale gate, then a unique-index preflight. A race that slips past the preflight is caught by the database constraint and surfaces as `CONFLICT` (409) with no automatic retry.
-
-### Side-channel input fields
-
-A Procedure's `input` is the contract with the caller, not with the Schema. It may declare fields the Schema does not — a Turnstile token, a honeypot value, a referrer. The builtin op projects `input ∩ Schema.properties` and silently drops the rest, so nothing extra is stored.
-
-Those fields are still readable where it matters: a `before_create` or `before_update` hook receives the **original, pre-projection** input. Every `after_*` hook receives only the persisted `entry.data`. That asymmetry is why bot checks are `before_*` hooks and notifications are `after_*` hooks.
-
-## Lifecycle hooks
-
-| Hook | Fires | Default `errorPolicy` |
-|---|---|---|
-| `before_create` | Before insert | `abort` |
-| `after_create` | After insert | `continue` |
-| `before_update` | Before an update, or a status transition whose target is not `published` | `abort` |
-| `after_update` | After an update, or a status transition whose target is not `published` | `continue` |
-| `before_delete` | Before delete | `abort` |
-| `after_delete` | After delete | `continue` |
-| `before_publish` | Before a transition to `published` | `abort` |
-| `after_publish` | After a transition to `published` | `continue` |
-
-> **Update hooks are not edit-only**
-> There are no unpublish-specific or archive-specific hooks. `before_update` and `after_update` also fire for unpublish, archive and every other transition whose target is not `published`. A hook that assumes "the row was edited" will run on state changes you did not intend.
-
-`abort` means a throwing handler cancels the surrounding mutation and the caller receives `LIFECYCLE_HOOK_REJECTED` (409). `continue` means the committed mutation stands: on the inline or `waitUntil` path the failure is logged and swallowed. Authors may set `errorPolicy` explicitly, but `abort` is rejected on a Trigger whose `on` list contains any `after_*` hook — a committed write cannot be un-committed.
-
-Hooks are wired through the entry repository, so Admin, Staff MCP and builtin Procedures all fire the same hooks. When several lifecycle Triggers bind the same schema and hook, they fire **alphabetically by `Trigger.metadata.name`**; number them (`010-bot-check`, `020-rate-limit`) so the order is visible.
-
-Handlers receive `ctx.event = { id, trigger, hook, schema, entry }`. `id` is stable across retries, `trigger` is the current Trigger name, and `entry` is `null` only for `before_create`; otherwise it is the pre-mutation row for `before_*` and the persisted row for `after_*`.
-
-### Deferred `after_*` delivery
-
-With an optional `DeferredHookDispatcher`, `after_*` hooks leave the request path and run under the delivery adapter's at-least-once retry and dead-letter policy instead of being swallowed. Delivery is not transactional with the database and exactly-once is not promised, so handlers must be idempotent; the conventional key is `${ctx.event.id}:${ctx.event.trigger}`. Cloudflare wiring, the envelope and DLQ configuration are in [Deferred hooks with Queues](../cloudflare/deferred-hooks-queues.md).
-
-## The HTTP envelope
-
-An HTTP Trigger wraps the handler's result as `{ "ok": true, "data": <result> }`, or returns the redacted diagnostic with the code's mapped status:
-
-```json
-{ "ok": false, "diagnostic": { "code": "INPUT_VALIDATION_FAILED", "path": "POST /api/contact#/name" } }
-```
-
-For a builtin `create`, `data` is the whole `EntryRow`: `id`, `collection`, `status`, `version`, `data`, nullable `authorId`, millisecond `createdAt` and `updatedAt`, and `locale` on localized rows. Declare `spec.output` against that row, not against the envelope. The request body must be a JSON object; anything else is a 400, and an oversize body is a 413.
-
-| Code | HTTP | When |
-|---|---|---|
-| `INPUT_VALIDATION_FAILED` | 400 | Input fails the converted schema, or the body is not a JSON object |
-| `UNAUTHENTICATED` | 401 | No verified credential at all |
-| `ENTITLEMENT_REQUIRED` | 402 | A guard Procedure denied the current business entitlement |
-| `AUTH_DENIED` | 403 | Authenticated, but a `requires.auth` predicate was false |
-| `NOT_FOUND` | 404 | Unknown entry id or View name |
-| `CONFLICT` | 409 | Illegal lifecycle transition, or a unique-index collision |
-| `LIFECYCLE_HOOK_REJECTED` | 409 | A `before_*` hook aborted the mutation |
-| `OUTPUT_VALIDATION_FAILED` | 500 | The handler returned a value its `output` schema rejects |
-| `HANDLER_NOT_REGISTERED` | 500 | A `ref` key has no registered function |
-| `INTERNAL_ERROR` | 500 | Uncaught handler exception |
-
-The full catalog is in [Diagnostic codes](../reference/diagnostics.md).
-
-## Worked example: a contact form
-
-One builtin write, one `before_create` check that can abort it, one `after_create` notification that cannot.
-
-```yaml
-apiVersion: cms.mantle.aotter.net/v1
-kind: Schema
-metadata:
-  name: contact-messages
-spec:
-  title: Contact messages
-  lifecycle: operational
-  schema:
-    type: object
-    additionalProperties: false
-    required: [name, email, message]
-    properties:
-      name: { type: string, minLength: 1, maxLength: 80 }
-      email: { type: string, format: email }
-      message: { type: string, minLength: 1, maxLength: 4000 }
-      submittedAt: { type: integer, x-mcp-hint: timestamp-ms, x-mantle-bind: now }
----
-apiVersion: cms.mantle.aotter.net/v1
-kind: Procedure
-metadata:
-  name: send-contact-message
-spec:
-  title: Send contact message
-  input:
-    type: object
-    additionalProperties: false
-    required: [name, email, message, botToken]
-    properties:
-      name: { type: string, minLength: 1, maxLength: 80 }
-      email: { type: string, format: email }
-      message: { type: string, minLength: 1, maxLength: 4000 }
-      botToken: { type: string, minLength: 1 }
-  output:
-    type: object
-    required: [id]
-    properties:
-      id: { type: string }
-  handler: { kind: builtin, op: create, schema: contact-messages }
----
-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 }
----
-apiVersion: cms.mantle.aotter.net/v1
-kind: Procedure
-metadata:
-  name: check-contact-bot
-spec:
-  input:
-    type: object
-    properties:
-      botToken: { type: string }
-  output: { type: object }
-  handler: { kind: ref, ref: check-contact-bot }
----
-apiVersion: cms.mantle.aotter.net/v1
-kind: Trigger
-metadata:
-  name: 010-contact-bot-check
-spec:
-  source:
-    kind: lifecycle
-    schema: contact-messages
-    on: [before_create]
-    errorPolicy: abort
-  target: { procedure: check-contact-bot }
----
-apiVersion: cms.mantle.aotter.net/v1
-kind: Procedure
-metadata:
-  name: notify-contact-message
-spec:
-  input:
-    type: object
-    properties:
-      name: { type: string }
-      email: { type: string }
-      message: { type: string }
-  output: { type: object }
-  handler: { kind: ref, ref: notify-contact-message }
----
-apiVersion: cms.mantle.aotter.net/v1
-kind: Trigger
-metadata:
-  name: 020-contact-notify
-spec:
-  source:
-    kind: lifecycle
-    schema: contact-messages
-    on: [after_create]
-    errorPolicy: continue
-  target: { procedure: notify-contact-message }
-```
-
-What each piece is doing:
-
-- `botToken` is declared on the Procedure input but not on the Schema, so it is validated, read by the hook, and never stored.
-- `010-contact-bot-check` runs first because Triggers on the same hook fire alphabetically. Throwing from its handler cancels the insert and the caller receives 409 `LIFECYCLE_HOOK_REJECTED`; nothing is written.
-- `020-contact-notify` runs after the row exists and receives only `entry.data`. A failing mailer is logged, not fatal — the visitor's message is already saved.
-- `submittedAt` is stamped by the runtime, so it is absent from the Procedure input and from Staff MCP authoring tools.
-- Adding `{ kind: mcp, surface: public }` as a fourth Trigger would publish the same Procedure as an agent tool without touching a handler.
-
-Register the two `ref` keys in the project's handlers map, then run the check loop from [Project layout and the CLI loop](../start/project-and-cli.md). The complete version with real Turnstile and email handlers is [Intake Turnstile and email hooks](../../examples/cf-primitives-intake-hooks.md). The Builder-safe Manifest without those hooks is [Intake form](../../examples/builtin-intake.md).
-
-## Source
-
-- [`docs/adr/0001-four-atom-manifest-model.md`](../../../docs/adr/0001-four-atom-manifest-model.md)
-- [`docs/deferred-lifecycle-queues.md`](../../../docs/deferred-lifecycle-queues.md)
-- [`packages/mantle-spec/src/domain/model/ManifestGrammar.ts`](../../../packages/mantle-spec/src/domain/model/ManifestGrammar.ts)
-- [`packages/mantle-runtime/src/domain/service/BuiltinProjector.ts`](../../../packages/mantle-runtime/src/domain/service/BuiltinProjector.ts)
-- [`packages/mantle-runtime/src/infrastructure/http/createMantleRequestHandler.ts`](../../../packages/mantle-runtime/src/infrastructure/http/createMantleRequestHandler.ts)
-- [`docs/skills/develop/SKILL.md`](../../skills/develop/SKILL.md)
+HTTP and MCP Triggers expose a declared Procedure with its existing authorization. Lifecycle and schedule Triggers are rejected by generation. Put side effects in app-owned handlers, and wire scheduled system maintenance with the host's scheduler. See [Procedure](../reference/procedure.md), [Trigger](../reference/trigger.md) and [Store](../guides/typed-queries.md).