@aotter/mantle 0.1.4 → 0.2.0-alpha.1

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

@@ -1,221 +1,166 @@
 ---
-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.
+description: Procedures as SQL programs or ref handlers, atomic writes and optimistic locks, guards, lifecycle hooks, schedules, and how every source becomes one Invocation.
 ---
 # Writes: Procedures, Triggers and lifecycle hooks
 
-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.
+A Procedure is a write with a typed `input`, a typed `output` and a handler.
+A Trigger says when it runs.
 
-## A Procedure is a callable, not an endpoint
+## Two kinds of handler
 
-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.
+**SQL.** One or more `INSERT`, `UPDATE` or `DELETE` statements, separated by
+`;`, applied as one batch: all of them or none.
 
-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.
+```yaml
+handler:
+  sql: |
+    INSERT INTO orders (itemId, qty, orderStatus, placedAt)
+    SELECT id, input.qty, 'placed', now() FROM items WHERE id = input.itemId
+    RETURNING id, qty;
+    UPDATE items SET stock = stock - input.qty WHERE id = input.itemId
+```
 
-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`.
+The result is `{ "results": [...] }`, one array of `RETURNING` rows per
+statement. Statements pass values to each other only through tables. If the
+second statement fails a `check` (`stock >= 0`), the first is rolled back too.
 
-## A Trigger is the only binding
+**`ref`.** A TypeScript function in the service's `handlers` map, for anything
+SQL cannot do: calling another service, reading before writing, setting
+`status`, branching on what it read.
 
-`Trigger.spec.target.procedure` names a declared Procedure; `spec.source` says what reaches it. There are three source kinds.
+```yaml
+handler: { ref: cancelOrder }
+```
 
-| `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). |
+```ts
+export const handlers: MantleHandlers = {
+  cancelOrder: async ({ orderId, expectedVersion }, ctx) => {
+    await ctx.store.write([{ update: "orders", set: { orderStatus: "cancelled" }, where: { id: orderId }, lock: expectedVersion }]);
+    return { id: orderId };
+  },
+};
+```
 
-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.
+A handler receives `(input, ctx)`. `input` is already validated against
+`input`, and the return value is validated against `output`.
 
-## Builtin or `ref`
+| `ctx.` | Is |
+|---|---|
+| `caller` | the [Caller](./authorization.md): `anonymous`, `user` or `system` |
+| `cause` | why it runs: `{ kind: "http" \| "mcp" \| "internal" \| "schedule" \| "lifecycle", id, parent? }`, plus `cron` and `scheduledTime` for a schedule, `hook`, `schema` and `rows` for a hook. `id` is stable across retries |
+| `store` | the typed Store, bound to the caller |
+| `invoke(name, input)` | runs another Procedure with the same caller, re-checking its `requires` and guard |
+| `env`, `waitUntil` | the host's environment and background-task hook |
 
-`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.
+Invocations nest at most 8 deep (`INVOCATION_DEPTH_EXCEEDED`), counting hooks
+and `ctx.invoke`.
 
-| `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 |
+## What a write may not do
 
-`request_publish` and `publish` are deliberately not builtin ops. They are lifecycle operations, not CRUD primitives.
+- Name the scope field or a native column (`id` on update, `version`,
+  `status`, `created_at`, `updated_at`, `author_id`). Store fills them.
+- Name an `id` in an `INSERT` on a scoped Schema: the compiler generates it.
+- Use `last_insert_rowid()`, `OFFSET`, DDL, or a table that is not a Schema.
 
-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.
+Set a timestamp field from `now()` and an owner field from `auth.uid()` in
+the SQL, never from an input.
 
-### Side-channel input fields
+## Row ops, set ops and locks
 
-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.
+A statement is a **row op** when its `WHERE` pins `id` to one value
+(`WHERE id = input.id AND …`), or it is an `INSERT … VALUES` of one row
+without `ON CONFLICT`. Everything else (`INSERT … SELECT`, `ON CONFLICT`, an
+`UPDATE` by another column) is a **set op**.
 
-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.
+- A row op that writes no row fails with `CONFLICT`, and the batch is rolled
+  back. A set op that writes nothing is a normal result.
+- `AND version = input.expectedVersion` makes a row op an optimistic lock: the
+  caller sends the version it read, and a stale one is `CONFLICT` (HTTP 409).
+- A Procedure with exactly one row op that pins `id` (and optionally
+  `version`) to inputs gets its `target` inferred, which Admin uses to bind an
+  operation to a row.
 
-## Lifecycle hooks
+## Triggers
 
-| Hook | Fires | Default `errorPolicy` |
+| `source.kind` | Fields | Runs the Procedure |
 |---|---|---|
-| `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.
+| `http` | `method` (`POST`, `PUT`, `PATCH`, `DELETE`), `path` | at that route on the REST surface. `path` starts with `/api/`; `{param}` segments bind to inputs of the same name |
+| `mcp` | `surface: public \| staff` | as a tool on that MCP surface. `staff` also lists it as an Admin operation |
+| `lifecycle` | `schema`, `on: [hooks]` | around writes to that Schema |
+| `schedule` | `cron`, `enabled?` | on a five-field POSIX cron, UTC, weekday 0 = Sunday |
 
-`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.
+A Procedure with no Trigger can still be run by `ctx.invoke` or from service
+code with `runtime.invokeProcedure`. Every source becomes the same
+`Invocation` (`{ procedure, input, caller, cause }`), so `requires`, the
+guard, input and output validation run the same way for all of them.
 
-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.
+## Guards
 
-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_*`.
+`requires.guard.procedure` names a `ref` Procedure that runs after
+`requires.auth` and input validation, before the target. It receives the
+target's validated input and caller, gets a read-only Store, cannot invoke,
+and rejects by throwing. Use it for a check that belongs to one action: an
+entitlement, a bot token, a business rule. See
+[Guarded API access](../../examples/guarded-api.md).
 
-### 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:
+## Lifecycle hooks
 
-```json
-{ "ok": false, "diagnostic": { "code": "INPUT_VALIDATION_FAILED", "path": "POST /api/contact#/name" } }
+```yaml
+kind: Trigger
+spec:
+  source: { kind: lifecycle, schema: orders, on: [after_create, after_update] }
+  target: { procedure: record-orders }
 ```
 
-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.
+Hooks are `before_create`, `after_create`, `before_update`, `after_update`,
+`before_delete`, `after_delete`, `before_publish` and `after_publish`. The
+target is always a `ref` handler.
+
+**Before hooks** are read-only checks for rules every path must obey, Admin and
+imports included. A hook receives the one row in `ctx.cause.rows` (for an
+insert, the row about to be written), reads with a read-only Store, and
+rejects by throwing; nothing in the batch is applied. The write then carries
+the version the hook saw, so a change in between is `CONFLICT`. A set op on a
+Schema with a before hook for that operation is refused. Hooks run in op order,
+and for one op in Trigger-name order.
+
+**After hooks** run only after a commit, once per statement and Trigger, with
+every row the statement wrote in `ctx.cause.rows`. Each row is the whole entry
+as `ctx.store.select` returns it (`id`, `version`, `createdAt`, `updatedAt`,
+`authorId`, every declared field), whatever the statement's own `RETURNING`
+asked for: that only shapes the Procedure's result. Loop over them; never read
+only `rows[0]`. A failure is logged and never undoes the commit, and a write
+the hook makes is a new transaction. Delivery is best effort: a handler that
+must not act twice deduplicates on `ctx.cause.id`.
+
+## Schedules
 
 ```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 }
+  source: { kind: schedule, cron: "0 3 * * 0" }   # Sundays 03:00 UTC
+  target: { procedure: weekly-digest }
 ```
 
-What each piece is doing:
+The target runs as the system caller: no caller scope, and no `requires.auth`
+predicate holds for it, so it declares none. `ctx.cause.id` is
+`<trigger>:<scheduledTime>`, the same for a replay. The service must pass
+`schedules: true` to `createMantle` (the preset does); without it boot refuses
+an enabled schedule with `SCHEDULE_NOT_WIRED`. The generated Cloudflare entry
+maps Cloudflare's cron spelling back to the plan's; see
+[The service and its entry](../cloudflare/service-entry.md). The Bun preset
+has no cron dispatcher: `mantle generate --host bun` refuses an enabled
+schedule Trigger, and a service with its own scheduler uses `host: none` and
+calls `mantle.invokeSchedule`.
 
-- `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.
+## Webhooks
 
-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).
+An HTTP Trigger receives parsed JSON, never the raw body. For a signed
+webhook, add a route to the service's own `fetch`: verify the signature over
+the raw body, then call `runtime.invokeProcedure` with a system caller. See
+[Commerce inventory](../../examples/commerce-inventory.md).
 
-## Source
+## Further reading
 
-- [`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)
+- [Procedure reference](../reference/procedure.md)
+- [Trigger reference](../reference/trigger.md)