@aotter/mantle 0.2.0-alpha.6 → 0.2.0-alpha.8

package/docs/examples/club-events/smoke.mjs

@@ -0,0 +1,121 @@
+// Club events acceptance: only listed members sign up; officers create events in Admin, members register/cancel their own seats over REST and MCP.
+import assert from "node:assert/strict";
+import { smoke } from "./smoke-kit.mjs";
+
+await smoke(async ({ call, mcp, signIn, sql, owner, step, logs }) => {
+  assert.equal((await call("POST", "/api/registrations", { body: { eventId: "x" } })).status, 401);
+  assert.equal((await call("GET", "/api/views/events")).status, 401);
+  step("anonymous: register and the event list are 401");
+
+  const admin = await signIn(owner);
+  assert.equal((await call("GET", "/admin/api/me", { cookie: admin })).body.role.split(",")[0], "admin");
+  step("ADMIN_EMAIL signs in although the members list is empty, and becomes the officer (admin)");
+
+  // A verified email that is not on the list: the code is sent, but creating the account is refused.
+  const stranger = "stranger@example.test", ip = "198.51.100.7", logStart = logs().length;
+  assert.equal((await call("POST", "/api/auth/email-otp/send-verification-otp", { body: { email: stranger, type: "sign-in" }, ip })).status, 200);
+  let code;
+  for (let i = 0; i < 40 && !code; i++) {
+    code = /stranger@example\.test: one-time code is (\d{6})/.exec(logs().slice(logStart))?.[1];
+    if (!code) await new Promise(resolve => setTimeout(resolve, 100));
+  }
+  assert.ok(code, "no one-time code for the stranger");
+  const refused = await call("POST", "/api/auth/sign-in/email-otp", { body: { email: stranger, otp: code }, ip });
+  assert.equal(refused.status, 403, JSON.stringify(refused.body));
+  assert.equal(refused.headers.getSetCookie().length, 0);
+  assert.equal((await sql(`SELECT count(*) AS n FROM user WHERE email = '${stranger}'`))[0].n, 0);
+  step("an email not on the members list cannot sign up: 403, no session cookie, no user row");
+
+  for (const name of ["alice", "bob", "carol", "dave", "erin", "frank"]) {
+    const added = await call("POST", "/admin/api/operations/add-member", { cookie: admin, body: { email: `${name}@example.test`, name } });
+    assert.equal(added.status, 200, JSON.stringify(added.body));
+  }
+  const mixed = await call("POST", "/admin/api/operations/add-member", { cookie: admin, body: { email: "Grace@example.test" } });
+  assert.equal(mixed.status, 200, JSON.stringify(mixed.body));
+  assert.equal((await sql("SELECT email FROM members WHERE email = 'grace@example.test'")).length, 1);
+  step("the officer adds members through the add-member operation in Admin (a mixed-case email is stored lowercased)");
+  const create = async (title, seats, closed = false) => {
+    const created = await call("POST", "/admin/api/operations/create-event", { cookie: admin, body: { title, startsAt: "2026-11-01T10:00:00Z", capacity: seats } });
+    assert.equal(created.status, 200, JSON.stringify(created.body));
+    if (!closed) return;
+    // Closing is an ordinary Admin edit: operational collections are editable, only creation needs a Procedure.
+    const id = created.body.output.results[0][0].id;
+    const { version } = (await call("GET", `/admin/api/entries/${id}?collection=events`, { cookie: admin })).body.entry;
+    assert.equal((await call("PATCH", `/admin/api/entries/${id}?collection=events`, { cookie: admin, body: { data: { closed: true }, expectedVersion: version } })).status, 200);
+  };
+  await create("Hike", 3);
+  await create("Workshop", 1);
+  await create("Members' dinner", 10, true);
+  step("an officer creates events through the create-event operation and closes one with an ordinary edit");
+
+  const alice = await signIn("alice@example.test");
+  const events = async cookie => Object.fromEntries((await call("GET", "/api/views/events", { cookie })).body.rows.map(e => [e.title, e]));
+  const { Hike: hike, Workshop: workshop, "Members' dinner": dinner } = await events(alice);
+  const seatsOf = async id => (await sql(`SELECT capacity - seats_taken AS seats_left FROM events WHERE id = '${id}'`))[0].seats_left;
+  const mine = async cookie => (await call("GET", "/api/views/my-registrations", { cookie })).body.rows;
+
+  const registered = await call("POST", "/api/registrations", { cookie: alice, body: { eventId: hike.id } });
+  assert.equal(registered.status, 200, JSON.stringify(registered.body));
+  assert.equal(await seatsOf(hike.id), 2);
+  assert.deepEqual((await mine(alice)).map(r => r.title), ["Hike"]);
+  step("a member registers: the insert and seats_left 3 -> 2 run in one program");
+
+  const twice = await call("POST", "/api/registrations", { cookie: alice, body: { eventId: hike.id } });
+  assert.equal(twice.status, 409, JSON.stringify(twice.body));
+  assert.equal(await seatsOf(hike.id), 2);
+  step("registering twice is 409 (uniqueIndexes [eventId, member]) and takes no seat");
+
+  assert.equal((await call("POST", "/api/registrations", { cookie: alice, body: { eventId: dinner.id } })).status, 409);
+  assert.equal((await call("POST", "/api/registrations", { cookie: alice, body: { eventId: "no-such-event" } })).status, 404);
+  step("the register handler checks first: a closed event is 409, a missing one 404");
+
+  const bob = await signIn("bob@example.test");
+  const [aliceHike] = await mine(alice);
+  assert.deepEqual(await mine(bob), []);
+  const foreign = await call("POST", "/api/registrations/cancel", { cookie: bob, body: { id: aliceHike.id } });
+  assert.equal(foreign.status, 409, JSON.stringify(foreign.body));
+  assert.equal((await sql(`SELECT count(*) AS n FROM registrations WHERE id = '${aliceHike.id}'`))[0].n, 1);
+  assert.equal(await seatsOf(hike.id), 2);
+  step("another member neither sees nor cancels it: cancel is 409, the row and seats_left are unchanged (restrict)");
+
+  const racers = [];
+  for (const name of ["carol", "dave", "erin", "frank"]) racers.push(await signIn(`${name}@example.test`));
+  const race = await Promise.all(racers.map(cookie => call("POST", "/api/registrations", { cookie, body: { eventId: workshop.id } })));
+  assert.deepEqual(race.map(r => r.status).sort(), [200, 409, 409, 409], JSON.stringify(race.map(r => r.body)));
+  assert.equal(await seatsOf(workshop.id), 0);
+  assert.equal((await sql(`SELECT count(*) AS n FROM registrations WHERE eventId = '${workshop.id}'`))[0].n, 1);
+  step("four members race for the last seat: exactly one wins, seats_left is 0, the losers' inserts rolled back");
+
+  const cancelled = await call("POST", "/api/registrations/cancel", { cookie: alice, body: { id: aliceHike.id } });
+  assert.equal(cancelled.status, 200, JSON.stringify(cancelled.body));
+  assert.equal(await seatsOf(hike.id), 3);
+  assert.deepEqual(await mine(alice), []);
+  step("the member cancels their own registration and the seat returns (2 -> 3)");
+
+  assert.ok((await mcp("/mcp", bob)).body.result.tools.some(t => t.name === "register"));
+  const viaAi = await mcp("/mcp", bob, "register", { eventId: hike.id });
+  assert.equal(viaAi.body.result?.isError, undefined, JSON.stringify(viaAi.body));
+  assert.equal(await seatsOf(hike.id), 2);
+  assert.deepEqual((await mine(bob)).map(r => r.title), ["Hike"]);
+  step("the member's AI registers through the public MCP tool `register`");
+
+  const all = await call("GET", "/admin/api/entries?collection=registrations", { cookie: admin });
+  assert.equal(all.status, 200, JSON.stringify(all.body));
+  assert.deepEqual(all.body.items.map(r => r.data.eventId).sort(), [hike.id, workshop.id].sort());
+  assert.equal((await call("GET", "/admin/api/entries?collection=registrations", { cookie: bob })).status, 403);
+  assert.equal((await call("GET", "/admin/api/me", { cookie: bob })).status, 403);
+  assert.ok(all.body.items.every(r => r.data.memberName && r.data.memberName !== r.data.member), JSON.stringify(all.body.items));
+  step("officers see every member's registrations, with names, through Admin's API; a member gets 403 on Admin");
+
+  const entry = async id => (await call("GET", `/admin/api/entries/${id}?collection=events`, { cookie: admin })).body.entry;
+  const before = await seatsOf(hike.id), read = await entry(hike.id);
+  // The console saves whole records: an edit that echoes seats_taken (or tries to change it) only changes the other fields.
+  const edited = await call("PATCH", `/admin/api/entries/${hike.id}?collection=events`, { cookie: admin, body: { data: { ...read.data, title: "Hike (rescheduled)", seats_taken: 0 }, expectedVersion: read.version } });
+  assert.equal(edited.status, 200, JSON.stringify(edited.body));
+  assert.equal((await entry(hike.id)).data.title, "Hike (rescheduled)");
+  assert.equal(await seatsOf(hike.id), before);
+  const shrunk = await call("PATCH", `/admin/api/entries/${hike.id}?collection=events`, { cookie: admin, body: { data: { capacity: 0 }, expectedVersion: (await entry(hike.id)).version } });
+  assert.equal(shrunk.status, 409, JSON.stringify(shrunk.body));
+  assert.equal(await seatsOf(hike.id), before);
+  step("officers edit an event with the whole record; the server-maintained seats_taken is ignored, and capacity below the seats taken is 409");
+});

package/docs/examples/club-events/src/handlers.ts

@@ -0,0 +1,25 @@
+import { ContractError } from "@aotter/mantle/contracts";
+import { userOf } from "@aotter/mantle/auth";
+import type { Handlers } from "../generated/generated.js";
+
+export const handlers: Handlers = {
+  register: async ({ caller, store }, { eventId }) => {
+    if (caller.kind !== "user") throw new ContractError("AUTH_DENIED", "Sign in as a member to register.", "procedures/register");
+    // Check before writing: a clear refusal for a missing or closed event. Seats are NOT checked here;
+    // the `seats_taken <= capacity` check in register-write is what holds under concurrent requests.
+    const event = await store.collection("events").findById(eventId);
+    if (!event) throw new ContractError("NOT_FOUND", "No such event.", "procedures/register");
+    if (event.closed) throw new ContractError("CONFLICT", "Registration for this event is closed.", "procedures/register");
+    try {
+      // `member` comes from the verified caller, never from request input; uniqueIndexes [eventId, member] refuses a second seat.
+      // userOf: the Better Auth user record the caller was resolved from (any credential), so officers see who registered.
+      const user = userOf(caller);
+      return await store.procedures["register-write"]({ eventId, member: caller.subject, memberName: user?.name || user?.email || caller.subject });
+    } catch (error) {
+      // register-write's only Schema check is the capacity one.
+      if (error instanceof ContractError && error.code === "CONFLICT" && error.message.startsWith("A check of the Schema failed"))
+        throw new ContractError("CONFLICT", "The event is full.", "procedures/register");
+      throw error;
+    }
+  },
+};

package/docs/examples/club-events/src/signup.ts

@@ -0,0 +1,9 @@
+import { store } from "../generated/generated.js";
+import { handlers } from "./handlers.js";
+
+/** Members-only sign-up: an email may create an account only when officers listed it in the `members` Schema (Admin). */
+export async function allowSignUp(env: Env, email: string): Promise<boolean> {
+  // No user exists yet, so the lookup runs as an application-created system caller (never wire input).
+  const members = store(env.DB, { kind: "system", reason: "sign-up allowlist" }, { handlers }).collection("members");
+  return (await members.count({ email: email.toLowerCase() })) > 0;
+}

package/docs/examples/generated-web/README.md

@@ -0,0 +1,78 @@
+# Generated public website
+
+A minimal application-owned Cloudflare D1 Worker: an HTML list and detail page,
+REST, `llms.txt`, sitemap, Markdown alternates and canonical head tags. It uses the
+positional native generator documented by the installed `@aotter/mantle` version.
+The frontend has no runtime dependencies. It renders Markdown as escaped text,
+preserving the source for the `.md` alternate.
+
+Copy this directory outside the SDK checkout. In that directory, set
+`"type": "module"` in `package.json`, install the exact selected Mantle version
+and host tools, then run:
+
+```sh
+npm install --save-exact @aotter/mantle@<version>
+npm install --save-dev typescript @cloudflare/workers-types wrangler
+npx mantle generate cloudflare-d1 generated posts.yaml
+npx tsc --noEmit
+git init
+git add generated src/worker.ts wrangler.jsonc
+git commit -m "Generate native website contracts"
+npx wrangler d1 execute mantle-generated-web --local --file generated/schema.sql
+npx wrangler d1 execute mantle-generated-web --local --file seed.sql
+npx wrangler dev --local
+```
+
+Keep generated TypeScript, `schema.sql` and the configured Wrangler file in
+version control. The workflow is generate → typecheck → implement any listed ref
+handlers → typecheck → commit generated output. This manifest has no ref handlers.
+Use the installed version's documented commands. CI runs
+`mantle generate cloudflare-d1 generated posts.yaml --check` to refuse stale or
+missing generated files without writing them. `dist/`
+and local Wrangler state stay ignored.
+
+For a linked pre-release SDK, use its installed `mantle` CLI instead of installing
+an unpublished version. Generation adds Wrangler's split build automatically.
+The seed is local test data; never apply it to an existing production database.
+For deployment, set the real D1 binding and `PUBLIC_ORIGIN` to the public origin.
+The app passes a verified anonymous Caller for this public-only site; an
+application with sign-in resolves its Caller once and supplies it to each entry.
+
+Open `/`, `/posts/hello`, `/posts/hello.md`, `/api/views/posts`, `/llms.txt` and
+`/sitemap.xml`. The list pages with an opaque cursor; the detail reads the Store,
+which enforces publication in SQL. `site.head()` reads the declared public View
+and supplies canonical and Markdown alternate tags, even when the request host
+differs from `PUBLIC_ORIGIN`. Both HTML pages have Markdown alternates (`/.md`
+for the index) and a canonical. REST and web fall through to the HTML renderer.
+
+Acceptance:
+
+- Walk every `/api/views/posts` cursor: its rows must match the `llms.txt` detail
+  links and sitemap detail URLs below the documented index caps.
+- Each HTML page includes `rel="canonical"` and a `type="text/markdown"`
+  alternate whose GET returns its current source. The index canonical is `/`.
+- `/posts/draft` and `/posts/draft.md` return 404; the draft is absent from REST,
+  HTML links, `llms.txt` and sitemap. HTML source escapes the fixture's `<world>`.
+- Malformed/foreign list cursors return structured 400 errors with `no-store`.
+- HTML HEAD has no body. Unknown pages return 404 with `no-store`.
+
+Ordinary HTML detail performs two native reads: one Store read for the body, then one
+public View read in `site.head()`. The index likewise performs two reads (list
+and home head). The current head API accepts no preloaded row; there is no
+request cache or extra authentication lookup in this public example. IDs ending
+in `.md` need one additional exact-page probe before HTML rendering (three reads
+total). Markdown may perform two View reads when checking an exact `.md` page
+before its alternate.
+
+Web indexes have deliberate ceilings: 5,000 scanned rows, 10 queries and 1 MiB
+for `llms.txt`; 50,000 rows, 100 queries and 50 MiB for a sitemap. An authored SQL `LIMIT 3` means at most three rows in the entire index,
+not three rows per query. Omit SQL LIMIT to enumerate the whole authorized
+result up to these web ceilings. The renderer requests pages of up to 500
+through generated paging options; transport page size does not expand the
+authored result set. Migration: remove LIMIT only when it was mistakenly
+being used as a page-size setting; retain a business-defined top-N limit. Translation-aware web indexes/hreflang remain a separate
+follow-up; `locales[0]` supplies the currently supported locale alternate.
+
+The SDK runs this exact Worker against a native SQLite database in
+`tests/web-example.test.ts` and bundles/typechecks its D1 form. No measurement
+scripts or benchmark data are part of the example.

package/docs/examples/generated-web/posts.yaml

@@ -0,0 +1,38 @@
+apiVersion: cms.mantle.aotter.net/v2
+kind: Schema
+metadata: {name: posts}
+spec:
+  title: Posts
+  lifecycle: publishing
+  schema:
+    type: object
+    required: [title, body]
+    properties:
+      title: {type: string}
+      body: {type: string}
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: View
+metadata: {name: posts}
+spec:
+  surface: public
+  sql: SELECT id, title FROM posts WHERE id <> 'home' ORDER BY id
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: View
+metadata: {name: post}
+spec:
+  surface: public
+  input:
+    type: object
+    required: [id]
+    additionalProperties: false
+    properties: {id: {type: string, minLength: 1}}
+  sql: SELECT id, title, body FROM posts WHERE id = input.id ORDER BY id
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: View
+metadata: {name: home}
+spec:
+  surface: public
+  sql: SELECT id, title, body FROM posts WHERE id = 'home' ORDER BY id

package/docs/examples/generated-web/seed.sql

@@ -0,0 +1,6 @@
+-- Local fixture only. Production publishing goes through the generated Procedures.
+INSERT INTO posts (id, version, created_at, updated_at, title, body, status, published_at) VALUES
+('home', 1, 0, 0, 'Posts', '# Posts — browse the HTML index for articles.', 'published', 0),
+('hello', 1, 0, 0, 'Hello <world>', '# Hello world', 'published', 0),
+('second', 1, 0, 0, 'Second post', '# Second post', 'published', 0),
+('draft', 1, 0, 0, 'Hidden draft', '# Draft', 'draft', NULL);

package/docs/examples/generated-web/src/worker.ts

@@ -0,0 +1,43 @@
+import { surfaceFailure } from "@aotter/mantle/contracts";
+import { store } from '../generated/generated.js';
+import { rest } from '../generated/rest.js';
+import { web } from '../generated/web.js';
+import page from '../generated/paged/views/posts.js';
+
+interface Env { DB: Parameters<typeof store>[0]; PUBLIC_ORIGIN: string }
+const caller = { kind: 'anonymous' } as const;
+const escape = (text: unknown) => String(text).replace(/[&<>"']/g, c => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]!));
+const segment = (text: string) => encodeURIComponent(text).replace(/[()]/g, c => '%' + c.charCodeAt(0).toString(16).toUpperCase());
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    try {
+      const site = web({ db: env.DB, caller, origin: env.PUBLIC_ORIGIN, title: 'Posts', description: 'A small public website',
+        pages: { '/': { view: 'home', markdown: 'body' }, '/posts/{id}': { view: 'post', list: 'posts', markdown: 'body' } } });
+      const api = await rest<Env>({ db: env => env.DB, caller: async () => caller })(request, env);
+      if (api) return api;
+      const output = await site.fetch(request, env);
+      if (output) return output;
+      const url = new URL(request.url), detail = /^\/posts\/([^/]+)$/.exec(url.pathname);
+      if (url.pathname !== '/' && !detail) return new Response('Not found', { status: 404, headers: { 'cache-control': 'no-store' } });
+      if (!['GET', 'HEAD'].includes(request.method)) return new Response(null, { status: 405, headers: { allow: 'GET, HEAD', 'cache-control': 'no-store' } });
+      let title = 'Posts', body: string;
+      if (detail) {
+        let id: string;
+        try { id = decodeURIComponent(detail[1]!); } catch { return new Response('Invalid path', { status: 400, headers: { 'cache-control': 'no-store' } }); }
+        // The Store applies publishing visibility in SQL. An anonymous caller cannot read a draft.
+        const post = await store(env.DB, caller).collection('posts').findById(id);
+        if (!post) return new Response('Not found', { status: 404, headers: { 'cache-control': 'no-store' } });
+        title = post.title ?? 'Untitled';
+        // Markdown stays plain text here; no untrusted HTML or Markdown renderer is needed.
+        body = `<p><a href="/">All posts</a></p><pre>${escape(post.body ?? '')}</pre>`;
+      } else {
+        const result = await page(env.DB, caller, {}, { limit: 50, cursor: url.searchParams.get('cursor') ?? undefined });
+        body = '<ul>' + result.rows.map(row => `<li><a href="/posts/${segment(String(row.id))}">${escape(row.title)}</a></li>`).join('') + '</ul>';
+        if (result.nextCursor) body += `<a href="/?cursor=${encodeURIComponent(result.nextCursor)}">Next page</a>`;
+      }
+      const html = `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width"><title>${escape(title)}</title>${await site.head(request, env)}</head><body><h1>${escape(title)}</h1>${body}</body></html>`;
+      return new Response(request.method === 'HEAD' ? null : html, { headers: { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store' } });
+    } catch (error) { return surfaceFailure(error); }
+  }
+};

package/docs/examples/generated-web/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "compilerOptions": {
+    "target": "ES2022", "module": "NodeNext", "moduleResolution": "NodeNext",
+    "strict": true, "noEmit": true, "skipLibCheck": true, "lib": ["ES2022", "DOM"],
+    "types": ["@cloudflare/workers-types"]
+  },
+  "include": ["src", "generated"]
+}

package/docs/examples/generated-web/wrangler.jsonc

@@ -0,0 +1,8 @@
+{
+  "name": "mantle-generated-web",
+  "main": "src/worker.ts",
+  "compatibility_date": "2026-09-28",
+  "compatibility_flags": ["nodejs_compat", "global_fetch_strictly_public"],
+  "vars": { "PUBLIC_ORIGIN": "http://localhost:8787" },
+  "d1_databases": [{ "binding": "DB", "database_name": "mantle-generated-web", "database_id": "local-example" }]
+}

package/docs/examples/purchasing/.dev.vars.example

@@ -0,0 +1,6 @@
+# Copy to .dev.vars for local sign-in: one-time codes are printed to the wrangler log. Never deploy these values.
+PUBLIC_ORIGIN=http://127.0.0.1:8787
+ADMIN_EMAIL=you@example.com
+BETTER_AUTH_SECRET=replace-with-a-random-32-byte-secret
+SUPPLIER_API_URL=http://127.0.0.1:9999/orders
+SUPPLIER_WEBHOOK_SECRET=replace-with-the-secret-the-supplier-signs-with

package/docs/examples/purchasing/README.md

@@ -0,0 +1,90 @@
+# Purchasing
+
+An internal purchase-request workflow. Any signed-in employee submits a request against a department budget. An admin
+approves or rejects it, in Admin or through an AI agent on the admin MCP endpoint. Approval spends the budget and writes a
+ledger row in one transaction. The app then orders from the supplier's API and waits for the supplier's signed callback
+to mark the request confirmed. Requesters get an email on each decision, and a daily cron emails admins about requests
+that have been waiting too long.
+
+## Capabilities shown
+
+- **Status workflow with guarded transitions**: the write Procedures use
+  `UPDATE requests SET requestStatus = 'approved' ... WHERE id = input.id AND requestStatus = 'submitted'`. A match on
+  0 rows is a `CONFLICT` (409). See `manifests/purchasing.yaml` (`approve-request-write`, `reject-request-write`,
+  `change-amount`, `mark-ordered`, `confirm-order`). The column is `requestStatus` because `status` is reserved for
+  publishing Schemas. `requests` and `ledger` set `readOnly: true`, so Admin's generic editor cannot bypass the state
+  machine (for example by moving an ordered request back to `submitted` and approving it again).
+- **Admin-only operations**: `approve-request` and `reject-request` declare `requires: ctx.admin` and a `target`, so
+  Admin shows them as operations on a request. Their `kind: mcp, surface: admin` Triggers make them
+  `approve_request` / `reject_request` tools on `/mcp/admin`. They are not listed on `/mcp`.
+- **Optimistic concurrency**: clients send `expectedVersion`, and the SQL matches `version = input.expectedVersion`.
+  If the requester changes the amount (`change-amount`, only their own request and only while it is `submitted`)
+  after an admin reviewed it, that admin's approval is a 409. When two admins approve the same version, one succeeds
+  and the other gets a 409.
+- **Several writes in one transaction**: `approve-request-write` runs three statements as one program: the status
+  change, `UPDATE budgets SET remaining = remaining - ...` and `INSERT INTO ledger`. If the request would overspend,
+  `checks: ["remaining >= 0"]` on `budgets` rolls back all three. `src/handlers.ts` turns that failure into a 409.
+- **External API + signed callback**: after the transaction commits, `src/supplier.ts` POSTs the order to
+  `env.SUPPLIER_API_URL` (request id as the idempotency key, 10 s timeout) and then sets the request to `ordered`.
+  If the supplier cannot be reached, the request stays `approved` and the daily cron retries it as a system caller
+  (`mark-ordered` has no `requires` for that reason, and no Trigger).
+  `src/routes.ts` serves `POST /callbacks/supplier`. It first checks an HMAC-SHA256 of the timestamp and the **raw**
+  body with `env.SUPPLIER_WEBHOOK_SECRET`, and only then parses the JSON. It then calls the generated `confirm-order`
+  Procedure as a `system` caller. No Trigger exposes that Procedure. The callback may arrive before `ordered` is
+  written, so `approved` is confirmed too. A replay of an applied callback answers 204 again.
+- **Email + cron as app code**: `src/notify.ts` sends through an `EmailSender` from `@aotter/mantle/email`
+  (`ConsoleEmailSender` locally). `src/schedule.ts` uses `toCloudflareCron`, and its cron is listed in
+  `wrangler.jsonc`. The cron retries failed orders (internal View `approved-requests`) and sends the reminder
+  (internal View `stale-requests`) to admins who are not banned.
+- Employees see only their own requests through `my-requests` (`restrict: { requests: "author_id = auth.uid()" }`).
+- **Sidebar for the approver's day**: `src/admin.tsx` declares an Approvals group (`defineAdmin` `nav.groups`) above Admin's built-in
+  groups; `pending-requests` and `requests` move into it with `uiSchema.nav: { group, order }`.
+- **A page only signed-in employees reach**: `src/requests-page.ts` serves `GET /requests`. An anonymous visitor gets a
+  303 to the shell's `/sign-in?return=/requests` (`src/sign-in.ts`, email code, then back). Signed in, the table reads
+  `my-requests` as the visitor's own caller. The form keeps `action="/api/requests" method="post"`; a small script sends
+  its fields as JSON to that REST Trigger, so the manifest's validation, `requires` and origin check apply and app code
+  never hands request data to a Procedure. Unstyled on purpose. `src/signup.ts` lets only `@EMPLOYEE_DOMAIN` emails
+  create an account (`vars` in `wrangler.jsonc`).
+
+Search for `AGENT:` to find what a real app must still provide: an email sender, the supplier's real API and signature
+scheme.
+
+## Combine with
+
+- Need members to own rows, prevent duplicates or cap capacity? Add club-events' `uniqueIndexes` and capacity `checks`.
+- Need public pages, SEO or media for the approved items? Add recipes' publishing lifecycle and visitor pages.
+- Need another approval flow? Copy the pattern: a ref Procedure (admin-only, side effects) that wraps a guarded SQL
+  write Procedure (one transaction).
+
+## Copy
+
+```sh
+cp -R node_modules/@aotter/mantle/docs/examples/app-shell/. my-app/
+cp -R node_modules/@aotter/mantle/docs/examples/purchasing/. my-app/
+cd my-app && pnpm install && pnpm generate && pnpm types && pnpm check
+cp .dev.vars.example .dev.vars          # then set SUPPLIER_API_URL and SUPPLIER_WEBHOOK_SECRET
+pnpm db:init && pnpm db:seed && pnpm dev
+```
+
+## What `pnpm smoke` proves
+
+`smoke.mjs` starts a stand-in supplier API on a local port (which it can switch to 503) and passes its URL and the
+webhook secret through `smoke(scenario, { vars })`. It then checks the following:
+
+1. Employees submit requests and see only their own. A department without a budget creates nothing.
+2. An employee gets 403 on the Admin operation. The approve and reject tools exist only on `/mcp/admin`, and the
+   internal write Procedures are on neither MCP surface.
+3. Rejecting through the admin MCP tool emails the requester. Approving that request afterwards, with its current
+   version, is a 409 because the `requestStatus` guard matches no row.
+4. Approving more than the department has left is a 409. The request stays `submitted`, and the budget and ledger are
+   unchanged.
+5. Admin's generic editor cannot change a request. Another employee cannot change its amount (409); the requester can,
+   and then approving the version the admin reviewed is a 409 that changes nothing.
+6. Two admins approve the same version at the same time: one gets 200 and the other 409. The budget is deducted and
+   the ledger row written once.
+7. Approval places exactly one supplier order, sets `ordered` and emails the requester.
+8. The admin MCP tool approves too. With the supplier down, approvals still commit and stay `approved`.
+9. A callback with a bad signature is a 401 and changes nothing. A correctly signed callback sets `confirmed`, also
+   while the request is still `approved`; a replay is 204; a wrong order id or a `submitted` request is 409.
+10. The daily cron places the failed order (`ordered`) and emails every admin about requests pending more than 3
+    days, and only about those.