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

package/docs/examples/intake-hooks.md

@@ -0,0 +1,237 @@
+---
+description: A public intake form with a Turnstile bot check as the Procedure's guard and a staff email from an after hook.
+---
+# Intake form with bot check and notification
+
+[Examples hub](./README.md) · Without the bot check and email, this is [Intake form](./intake.md).
+
+Anonymous visitors submit a request. A Cloudflare Turnstile token is verified
+before anything is written, and staff get an email after the row is committed.
+The write stays one SQL statement; two small `ref` handlers carry the
+integrations.
+
+## Problem
+
+The public write must reject automated submissions before anything is stored.
+A new row should email the team, without making the visitor wait for the email
+or fail when email is not configured. Submissions are records, so the Schema is
+`operational`.
+
+## Manifest
+
+```yaml
+apiVersion: cms.mantle.aotter.net/v2
+kind: Schema
+metadata: { name: requests }
+spec:
+  title: Requests
+  description: Requests submitted through the public intake form.
+  lifecycle: operational
+  schema:
+    type: object
+    additionalProperties: false
+    required: [name, email, message]
+    properties:
+      name: { type: string, minLength: 1, maxLength: 120 }
+      email: { type: string, format: email }
+      message: { type: string, minLength: 1, maxLength: 2000 }
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: View
+metadata: { name: recent-requests }
+spec:
+  title: Recent requests
+  surface: staff
+  requires: { auth: { all: [{ ctx.staff: [owner, editor, contributor] }] } }
+  sql: |
+    SELECT id, name, email, message, created_at FROM requests
+    ORDER BY created_at DESC LIMIT 50
+---
+# The guard runs first, with this Procedure's validated input, token included. The INSERT never stores the token.
+apiVersion: cms.mantle.aotter.net/v2
+kind: Procedure
+metadata: { name: submit-request }
+spec:
+  title: Submit request
+  description: Create a new public request after a Turnstile check.
+  requires: { guard: { procedure: verify-turnstile } }
+  input:
+    type: object
+    additionalProperties: false
+    required: [name, email, message]
+    properties:
+      name: { type: string, minLength: 1, maxLength: 120 }
+      email: { type: string, format: email }
+      message: { type: string, minLength: 1, maxLength: 2000 }
+      turnstileToken: { type: string }
+  output: { type: object }
+  handler:
+    sql: |
+      INSERT INTO requests (name, email, message)
+      VALUES (input.name, input.email, input.message)
+      RETURNING id
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Procedure
+metadata: { name: verify-turnstile }
+spec:
+  input:
+    type: object
+    properties:
+      turnstileToken: { type: string }
+  output: { type: object }
+  handler: { ref: verifyTurnstile }
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Procedure
+metadata: { name: notify-requests }
+spec:
+  input: { type: object }
+  output: { type: object }
+  handler: { ref: notifyRequests }
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Trigger
+metadata: { name: submit-request-http }
+spec:
+  source: { kind: http, method: POST, path: /api/requests }
+  target: { procedure: submit-request }
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Trigger
+metadata: { name: submit-request-mcp }
+spec:
+  source: { kind: mcp, surface: public }
+  target: { procedure: submit-request }
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Trigger
+metadata: { name: requests-notify }
+spec:
+  source: { kind: lifecycle, schema: requests, on: [after_create] }
+  target: { procedure: notify-requests }
+```
+
+Why each check sits where it does:
+
+- **The bot check is a guard, not a before hook.** A guard receives the target
+  Procedure's validated input, so it can read `turnstileToken`. A before hook
+  receives only the row about to be written (`ctx.cause.rows`), and the token is
+  never part of the row. A guard belongs to one Procedure, which is right here:
+  staff creating a row through Admin are not asked for a token.
+- **The guard's input schema leaves `additionalProperties` open.** It receives
+  `name`, `email` and `message` too.
+- **The email is an after hook.** It runs only after the commit, and a failure
+  never undoes the row. One statement can write many rows, so the handler loops
+  over `ctx.cause.rows`.
+
+## Handlers
+
+```ts
+// src/handlers.ts
+import { DiagnosticError, runtimeDiagnostic } from "@aotter/mantle";
+import type { MantleHandlers } from "../.mantle/generated/mantle.js";
+import type { Env } from "./service.js";
+
+const reject = (message: string, value?: unknown): never => {
+  throw new DiagnosticError(runtimeDiagnostic({ code: "AUTH_DENIED", severity: "error", path: "/turnstileToken", value, message }));
+};
+
+export const handlers: MantleHandlers<Env> = {
+  verifyTurnstile: async (input, ctx) => {
+    const secret = ctx.env.TURNSTILE_SECRET_KEY?.trim();
+    if (!secret) return {}; // fails open until the secret exists; see below
+    const token = (input as { turnstileToken?: string }).turnstileToken?.trim();
+    if (!token) reject("Turnstile verification is required.");
+    const body = new FormData();
+    body.set("secret", secret);
+    body.set("response", token!);
+    const response = await fetch("https://challenges.cloudflare.com/turnstile/v0/siteverify", { method: "POST", body });
+    const result = response.ok ? ((await response.json().catch(() => null)) as { success?: boolean; "error-codes"?: string[] } | null) : null;
+    if (!result?.success) reject("Turnstile verification failed.", result?.["error-codes"]);
+    return {};
+  },
+
+  // an after hook gets every row the statement wrote: loop, never rows[0]
+  notifyRequests: async (_input, ctx) => {
+    const { EMAIL, INTAKE_NOTIFY_TO, INTAKE_NOTIFY_FROM } = ctx.env;
+    if (ctx.cause.kind !== "lifecycle" || !EMAIL || !INTAKE_NOTIFY_TO || !INTAKE_NOTIFY_FROM) return {};
+    for (const row of ctx.cause.rows) {
+      await EMAIL.send({
+        to: INTAKE_NOTIFY_TO,
+        from: INTAKE_NOTIFY_FROM,
+        subject: `New request from ${String(row.name)}`,
+        text: [`Name: ${String(row.name)}`, `Email: ${String(row.email)}`, "", String(row.message)].join("\n"),
+        replyTo: String(row.email),
+      });
+    }
+    return {};
+  },
+};
+```
+
+`src/service.ts` is the application's own file after the first
+`mantle generate`. Add the bindings to its `Env`:
+
+```ts
+interface EmailBinding {
+  send(message: { to: string; from: string; subject: string; text?: string; replyTo?: string }): Promise<unknown>;
+}
+
+export interface Env {
+  readonly DB: D1Database;
+  // ...the generated fields...
+  readonly TURNSTILE_SECRET_KEY?: string;
+  readonly EMAIL?: EmailBinding;
+  readonly INTAKE_NOTIFY_TO?: string;
+  readonly INTAKE_NOTIFY_FROM?: string;
+}
+```
+
+Put `send_email` (`[{ "name": "EMAIL" }]`) and the two `vars` in
+`wrangler.jsonc`, and set the secret with
+`wrangler secret put TURNSTILE_SECRET_KEY`.
+
+A handler throws `DiagnosticError` to answer with that code's status
+(`AUTH_DENIED` is 403). Any other throw is logged and answered as 500
+`INTERNAL_ERROR`. Import it from `@aotter/mantle`, not `@aotter/mantle/spec`:
+the root carries no SQL parser, while `/spec` bundles it into the Worker.
+
+Two policies are deliberate:
+
+- **The bot check fails open while the secret is unset,** so a first deploy
+  still accepts submissions. To fail closed, make the missing secret a
+  `reject(...)`.
+- **The notification fails soft.** After hooks are best effort: a throw is
+  logged and the row stays. `ctx.cause.id` is stable across a replay, so a
+  handler that must not send twice can deduplicate on it.
+
+## Try it
+
+```sh
+curl -sS -X POST http://127.0.0.1:8787/api/requests \
+  -H 'content-type: application/json' \
+  -d '{"name":"Ada","email":"ada@example.test","message":"Please call me back.","turnstileToken":"<token>"}'
+```
+
+The answer is `{ "results": [[{ "id": "…" }]] }`. With the secret set, a bad
+token is HTTP 403 with `{ "error": { "code": "AUTH_DENIED", … } }`, and no row
+exists. A missing `name` is HTTP 400 `INPUT_VALIDATION_FAILED` before the guard
+runs.
+
+An agent calling `submit_request` on `/mcp` has no browser widget. With the
+secret set, it is refused unless it brings a valid token. Keep or remove
+`submit-request-mcp` deliberately.
+
+## What this leaves out
+
+- **Deduplication.** Add a `uniqueIndexes` tuple and `ON CONFLICT DO NOTHING`
+  if duplicates matter.
+- **Rate limiting beyond Turnstile.** Put a quota in the service's own `fetch`.
+- **Reliable delivery.** After hooks run inline after the commit. A CRM sync
+  that must not be lost needs the service's own queue or outbox.
+
+## Source
+
+- [Writes: Procedures, Triggers and hooks](../handbook/concepts/procedures-and-triggers.md)
+- [Authorization reference](../handbook/reference/authorization.md): guards

package/docs/examples/intake.md

@@ -0,0 +1,127 @@
+---
+description: A public intake form that inserts operational request rows with one SQL statement. No bot check or email hooks.
+---
+# Intake form
+
+[Examples hub](./README.md) · Bot checks and staff email are [Intake with bot check and notification](./intake-hooks.md).
+
+Anonymous visitors submit a request, and staff list recent submissions. The
+only Procedure is one SQL `INSERT`; there is no handler code. Use this shape for
+any form that anonymous visitors submit.
+
+## Problem
+
+Visitors send a name, an email address and a message. Staff read recent
+submissions through Admin's API or the staff MCP surface. Submissions are
+records, not authored content, so the Schema is `operational`: a row is live as
+soon as it is written.
+
+## Manifest
+
+```yaml
+apiVersion: cms.mantle.aotter.net/v2
+kind: Schema
+metadata: { name: requests }
+spec:
+  title: Requests
+  description: Requests submitted through the public intake form.
+  lifecycle: operational
+  schema:
+    type: object
+    additionalProperties: false
+    required: [name, email, message]
+    properties:
+      name: { type: string, minLength: 1, maxLength: 120 }
+      email: { type: string, format: email }
+      message: { type: string, minLength: 1, maxLength: 2000 }
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: View
+metadata: { name: recent-requests }
+spec:
+  title: Recent requests
+  surface: staff
+  requires: { auth: { all: [{ ctx.staff: [owner, editor, contributor] }] } }
+  sql: |
+    SELECT id, name, email, message, created_at FROM requests
+    ORDER BY created_at DESC LIMIT 50
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Procedure
+metadata: { name: submit-request }
+spec:
+  title: Submit request
+  description: Create a new public request.
+  input:
+    type: object
+    additionalProperties: false
+    required: [name, email, message]
+    properties:
+      name: { type: string, minLength: 1, maxLength: 120 }
+      email: { type: string, format: email }
+      message: { type: string, minLength: 1, maxLength: 2000 }
+  output: { type: object }
+  handler:
+    sql: |
+      INSERT INTO requests (name, email, message)
+      VALUES (input.name, input.email, input.message)
+      RETURNING id
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Trigger
+metadata: { name: submit-request-http }
+spec:
+  source: { kind: http, method: POST, path: /api/requests }
+  target: { procedure: submit-request }
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Trigger
+metadata: { name: submit-request-mcp }
+spec:
+  source: { kind: mcp, surface: public }
+  target: { procedure: submit-request }
+```
+
+The submission time is the native `created_at` column, which Store fills; a
+write can never set it. A column the SQL does not name keeps its default, so a
+caller cannot add fields: the `INSERT` lists exactly what is stored.
+
+## Handlers
+
+None. The plan has no `ref`, so the generated `src/handlers.ts` is an empty map.
+
+## Try it
+
+```sh
+curl -sS -X POST http://127.0.0.1:8787/api/requests \
+  -H 'content-type: application/json' \
+  -d '{"name":"Ada","email":"ada@example.test","message":"Please call me back."}'
+```
+
+An inline SQL Procedure answers `{ "results": [...] }`, one array of
+`RETURNING` rows per statement, here `[[{ "id": "…" }]]`. A missing `name` is
+HTTP 400 `INPUT_VALIDATION_FAILED`.
+
+Staff read the queue at `GET /admin/api/views/recent-requests?limit=50` with a
+staff session; the response is `{ rows, nextCursor? }`.
+
+| MCP surface | Tool | From |
+|---|---|---|
+| `/mcp` | `submit_request` | the `submit-request-mcp` Trigger |
+| `/mcp/staff` | `recent_requests` | the staff View |
+
+A Schema is never an MCP tool. Staff edit rows in Admin's API
+(`/admin/api/entries`), not through generated record tools.
+
+## What this leaves out
+
+- **Bot check and notification.** They are `ref` lifecycle hooks in
+  [Intake with bot check and notification](./intake-hooks.md).
+- **Deduplication.** Two identical submissions are two rows.
+- **Rate limiting.** Put a per-form quota in the service's own `fetch`, in
+  front of the REST surface.
+
+## Source
+
+- [Procedure reference](../handbook/reference/procedure.md)
+- [View reference](../handbook/reference/view.md)

package/docs/examples/legal-documents.md

@@ -0,0 +1,218 @@
+---
+description: Localized Terms and Privacy documents with immutable revisions, a public lookup and signed-in acceptance records.
+---
+# Legal documents and consent
+
+[Examples hub](./README.md)
+
+A portable shape for Terms of Use, a Privacy Policy and consent receipts. Each
+`(kind, revision, locale)` row is one legal artifact. Every Procedure is SQL.
+Core does not install this or own the public pages.
+
+## Problem
+
+Staff add reviewed legal text as new revisions and publish them; a published
+revision that users accepted is never rewritten. The public reads the current
+revision for a kind and a locale. A signed-in user records acceptance of one
+published revision, and the receipt names who and when without trusting the
+caller.
+
+## Manifest
+
+```yaml
+apiVersion: cms.mantle.aotter.net/v2
+kind: Schema
+metadata: { name: legal-documents }
+spec:
+  title:
+    en: Legal documents
+    zh-TW: 法律文件
+  description:
+    en: Supply the site's complete, reviewed legal text. Never create empty, placeholder, or agent-invented terms. Create a new revision instead of rewriting a published document accepted by users.
+    zh-TW: 請填入網站已審閱的完整法律正文。不得建立空白、佔位或由 agent 虛構的條款；已有使用者同意的已發佈文件應建立新修訂，不得覆寫。
+  localized: true
+  lifecycle: publishing
+  uniqueIndexes: [[kind, revision, locale]]
+  indexes: [[kind, locale, effectiveAt]]
+  searchableFields: [title, revision]
+  schema:
+    type: object
+    readOnly: true
+    additionalProperties: false
+    required: [kind, revision, locale, title, body, effectiveAt]
+    properties:
+      kind: { type: string, enum: [terms, privacy] }
+      revision: { type: string, minLength: 1, maxLength: 100 }
+      locale: { type: string }
+      title: { type: string, minLength: 1, maxLength: 200 }
+      body:
+        type: string
+        minLength: 1
+        x-mcp-hint: markdown
+        description:
+          en: Complete reviewed legal text in Markdown; placeholders are not acceptable.
+          zh-TW: 已審閱的完整 Markdown 法律正文，不得使用佔位文字。
+      effectiveAt: { type: string, format: date-time }
+---
+# Public over a publishing Schema: drafts are never visible here.
+apiVersion: cms.mantle.aotter.net/v2
+kind: View
+metadata: { name: current-legal-document }
+spec:
+  title:
+    en: Current legal document
+    zh-TW: 現行法律文件
+  description: The newest published revision of one legal document in one locale.
+  surface: public
+  input:
+    type: object
+    additionalProperties: false
+    required: [kind, locale]
+    properties:
+      kind: { type: string, enum: [terms, privacy] }
+      locale: { type: string }
+  sql: |
+    SELECT id, kind, revision, locale, title, body, effectiveAt, updated_at
+    FROM "legal-documents"
+    WHERE kind = input.kind AND locale = input.locale AND effectiveAt <= now()
+    ORDER BY effectiveAt DESC LIMIT 1
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Procedure
+metadata: { name: create-legal-document }
+spec:
+  title:
+    en: Create legal document revision
+    zh-TW: 建立法律文件修訂
+  description:
+    en: Supply the site's complete, reviewed legal text. Never create empty, placeholder, or agent-invented terms. Create a new revision instead of rewriting a published document accepted by users.
+    zh-TW: 請填入網站已審閱的完整法律正文。不得建立空白、佔位或由 agent 虛構的條款；已有使用者同意的已發佈文件應建立新修訂，不得覆寫。
+  requires: { auth: { all: [{ ctx.staff: [owner, editor] }] } }
+  input:
+    type: object
+    additionalProperties: false
+    required: [kind, revision, locale, title, body, effectiveAt]
+    properties:
+      kind: { type: string, enum: [terms, privacy] }
+      revision: { type: string, minLength: 1, maxLength: 100 }
+      locale: { type: string }
+      title: { type: string, minLength: 1, maxLength: 200 }
+      body:
+        type: string
+        minLength: 1
+        x-mcp-hint: markdown
+        description:
+          en: Complete reviewed legal text in Markdown; placeholders are not acceptable.
+          zh-TW: 已審閱的完整 Markdown 法律正文，不得使用佔位文字。
+      effectiveAt: { type: string, format: date-time }
+  output: { type: object }
+  handler:
+    sql: |
+      INSERT INTO "legal-documents" (kind, revision, locale, title, body, effectiveAt)
+      VALUES (input.kind, input.revision, input.locale, input.title, input.body, input.effectiveAt)
+      RETURNING id, revision
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Trigger
+metadata: { name: create-legal-document-staff }
+spec:
+  source: { kind: mcp, surface: staff }
+  target: { procedure: create-legal-document }
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Schema
+metadata: { name: legal-acceptances }
+spec:
+  title:
+    en: Legal acceptances
+    zh-TW: 法律文件同意紀錄
+  description:
+    en: Append-only receipts bound by the server to the signed-in user and acceptance time.
+    zh-TW: 由伺服器綁定登入使用者與同意時間的唯增紀錄。
+  lifecycle: operational
+  uniqueIndexes: [[documentId, userId]]
+  indexes: [[userId]]
+  schema:
+    type: object
+    readOnly: true
+    additionalProperties: false
+    required: [documentId, userId]
+    properties:
+      documentId: { type: string, x-mantle-ref: legal-documents }
+      userId: { type: string }
+---
+# A conditional INSERT ... SELECT: it writes a receipt only for a published revision, and a repeat acceptance is ignored.
+apiVersion: cms.mantle.aotter.net/v2
+kind: Procedure
+metadata: { name: accept-legal-document }
+spec:
+  title:
+    en: Accept legal document
+    zh-TW: 同意法律文件
+  description:
+    en: Record the signed-in user's acceptance of one published legal document revision.
+    zh-TW: 記錄登入使用者對一份已發佈法律文件修訂的同意。
+  requires: { auth: { all: [ctx.user] } }
+  input:
+    type: object
+    additionalProperties: false
+    required: [documentId]
+    properties:
+      documentId: { type: string, x-mantle-ref: legal-documents }
+  output: { type: object }
+  handler:
+    sql: |
+      INSERT INTO "legal-acceptances" (documentId, userId)
+      SELECT d.id, auth.uid() FROM "legal-documents" d
+      WHERE d.id = input.documentId AND d.status = 'published'
+      ON CONFLICT (documentId, userId) DO NOTHING
+      RETURNING id
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Trigger
+metadata: { name: accept-legal-document-http }
+spec:
+  source: { kind: http, method: POST, path: /api/legal/acceptances }
+  target: { procedure: accept-legal-document }
+```
+
+How the guarantees are made:
+
+- **Who and when are the server's.** `accept-legal-document` writes
+  `auth.uid()` as `userId`, and the acceptance time is the native
+  `created_at`. The input carries only `documentId`.
+- **Only a published revision can be accepted.** The `INSERT … SELECT` writes
+  a row only when the document exists and is published. It is a set op, so
+  writing nothing is a normal result: `results` is `[[]]` for a draft, an
+  unknown id or a repeat acceptance. The client checks for a returned `id`.
+- **Revisions are immutable through generic surfaces.** The root
+  `readOnly: true` keeps Admin from offering generic edits, and the unique
+  `(kind, revision, locale)` index makes a new revision a new row. It is not a
+  storage lock: host code with `runtime.store` can still rewrite a row, so do
+  not write to this Schema from your own code.
+- **Agents are told not to invent terms.** The English Procedure description
+  is the staff MCP tool's description.
+- **`effectiveAt <= now()`** lets staff publish a revision ahead of the day it
+  takes effect.
+
+Do not add an MCP Trigger for `accept-legal-document`: accepting terms is an
+explicit action in the application's own interface.
+
+## Handlers
+
+None.
+
+## Serving the pages
+
+Serve `/terms` and `/privacy` from the service's own `fetch`: with the caller
+your `CallerResolver` returned, call
+`runtime.store.as(caller).view("current-legal-document", { input: { kind, locale } })`
+for the requested locale, fall back to the site's default
+locale, and render the Markdown as sanitized HTML. Answer with a clear
+unavailable page when no revision is published. The application owns the
+consent checkbox, sign-in, retention and export policy.
+
+## Source
+
+- [Publication](./publication.md): the localized publishing pattern
+- [Authorization](../handbook/concepts/authorization.md): server-bound identity