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

package/docs/examples/purchasing/smoke.mjs

@@ -0,0 +1,191 @@
+// Purchase requests end to end: submit, guarded transitions, admin-only approve/reject (Admin + admin MCP),
+// optimistic concurrency, one-transaction approval with a budget check, supplier order + signed callback, emails, cron.
+import assert from "node:assert/strict";
+import { createHmac } from "node:crypto";
+import { createServer } from "node:http";
+import { assertMcpDiscovery, smoke } from "./smoke-kit.mjs";
+import { developerConsole } from "./generated/admin-descriptors.ts";
+
+const SECRET = "local-supplier-secret", DAILY = "0 9 * * *", DAY_US = 86_400 * 1_000_000;
+
+// A stand-in supplier API: accepts an order and answers with its order id, or 503 while `supplierDown`.
+const received = [];
+let supplierDown = false;
+const supplier = createServer((request, response) => {
+  let body = "";
+  request.on("data", chunk => { body += chunk; });
+  request.on("end", () => {
+    if (supplierDown) return response.writeHead(503).end();
+    received.push({ ...JSON.parse(body), idempotencyKey: request.headers["idempotency-key"] });
+    response.writeHead(200, { "content-type": "application/json" }).end(JSON.stringify({ orderId: `SUP-${received.length}` }));
+  });
+});
+await new Promise(resolve => supplier.listen(0, "127.0.0.1", resolve));
+
+try {
+  await smoke(async ({ origin, owner, call, mcp, signIn, sql, cron, waitForLog, step, logs }) => {
+    const query = sql;
+    const row = async id => (await query(`SELECT requeststatus AS status, version, supplierorderid AS "supplierOrderId" FROM requests WHERE id = '${id}'`))[0];
+    const statusAndOrder = async id => { const { status, supplierOrderId } = await row(id); return { status, supplierOrderId }; };
+    const remaining = async department => (await query(`SELECT remaining FROM budgets WHERE department = '${department}'`))[0].remaining;
+    const ledgerRows = () => query("SELECT requestid AS \"requestId\", amount, remainingafter AS \"remainingAfter\" FROM ledger");
+    const operation = (cookie, name, body) => call("POST", `/admin/api/operations/${name}`, { cookie, body });
+    const signed = (payload, secret = SECRET) => {
+      const body = JSON.stringify(payload), timestamp = String(Math.floor(Date.now() / 1000));
+      const signature = createHmac("sha256", secret).update(`${timestamp}.${body}`).digest("hex");
+      return call("POST", "/callbacks/supplier", { body, headers: { "x-supplier-timestamp": timestamp, "x-supplier-signature": signature } });
+    };
+
+    const admin = await signIn(owner), alice = await signIn("alice@example.test"), bob = await signIn("bob@example.test");
+    const carol = await signIn("carol@example.test");
+    await query(`UPDATE "user" SET role = 'admin' WHERE email = 'carol@example.test'`);
+    assert.equal((await call("GET", "/admin/api/me", { cookie: carol })).status, 200);
+
+    const submit = async (cookie, title, amount, department) => {
+      const response = await call("POST", "/api/requests", { cookie, body: { title, amount, department } });
+      assert.equal(response.status, 200, JSON.stringify(response.body));
+      return response.body.results[0][0]?.id;
+    };
+    assert.equal((await call("POST", "/api/requests", { body: { title: "Pens", amount: 5, department: "Design" } })).status, 401);
+    const laptop = await submit(alice, "Laptop", 1200, "Engineering");
+    const monitors = await submit(alice, "Monitors", 1500, "Design");
+    const chairs = await submit(alice, "Chairs", 300, "Design");
+    const desk = await submit(bob, "Desk", 400, "Engineering");
+    const projector = await submit(bob, "Projector", 600, "Engineering");
+    assert.equal(await submit(bob, "Rocket", 10, "Space"), undefined);
+    assert.equal((await query("SELECT count(*) AS n FROM requests"))[0].n, 5);
+    const mine = (await call("GET", "/api/views/my-requests", { cookie: alice })).body.rows;
+    assert.deepEqual(mine.map(r => r.title).sort(), ["Chairs", "Laptop", "Monitors"]);
+    assert.deepEqual((await call("GET", "/api/views/my-requests", { cookie: bob })).body.rows.map(r => r.title).sort(), ["Desk", "Projector"]);
+    step("employees submit requests (unknown department creates nothing) and see only their own");
+
+    // fetch follows the 303, so an anonymous visitor ends on the sign-in page.
+    assert.match((await call("GET", "/requests")).body, /<h1>Sign in<\/h1>/);
+    assert.match((await call("GET", "/sign-in?return=%2Frequests")).body, /sign-in\/email-otp/);
+    const page = (await call("GET", "/requests", { cookie: bob })).body;
+    assert.match(page, /Projector/); assert.doesNotMatch(page, /Laptop/); assert.match(page, /<option>Design<\/option>/);
+    // Writes go through the REST Trigger the page's form names, never through the page itself.
+    assert.match(page, /<form action="\/api\/requests" method="post"/);
+    assert.equal((await call("POST", "/requests", { cookie: bob })).status, 404);
+    assert.equal((await call("POST", "/api/requests", { cookie: bob, body: { title: "Pens", amount: 0, department: "Design" } })).status, 400);
+    step("the /requests page sends anonymous visitors to /sign-in, lists only the employee's own requests and submits to the REST Trigger");
+
+    assert.equal((await operation(admin, "open-budget", { department: "Marketing", remaining: 500 })).status, 200);
+    assert.equal((await operation(admin, "open-budget", { department: "Design", remaining: 1 })).status, 409);
+    assert.equal(await remaining("Marketing"), 500);
+    assert.equal((await operation(alice, "open-budget", { department: "Ops", remaining: 1 })).status, 403);
+    step("admins open a department budget from the Budgets list header (open-budget; a second one for the same department is 409); employees cannot");
+
+    const version = async id => (await row(id)).version;
+    assert.equal((await operation(alice, "approve-request", { id: laptop, expectedVersion: await version(laptop) })).status, 403);
+    // Generated static metadata uses the MCP tool names; the app chooses the surface and test identity.
+    const declared = developerConsole.interfaces.callable;
+    const publicTools = await assertMcpDiscovery(`${origin}/mcp`, { headers: { cookie: alice, origin }, tools: declared.filter(tool => tool.surface === "public") });
+    assert.ok(!publicTools.includes("approve_request") && !publicTools.includes("reject_request"), publicTools.join());
+    const adminTools = await assertMcpDiscovery(`${origin}/mcp/admin`, { headers: { cookie: admin, origin }, tools: declared.filter(tool => tool.surface === "admin") });
+    // Denial is separate from successful initialized discovery.
+    assert.equal((await mcp("/mcp/admin")).status, 401);
+    assert.equal((await mcp("/mcp/admin", alice)).status, 403);
+    assert.ok(adminTools.includes("approve_request") && adminTools.includes("reject_request"), adminTools.join());
+    for (const hidden of ["confirm_order", "mark_ordered", "approve_request_write", "reject_request_write"])
+      assert.ok(!adminTools.includes(hidden) && !publicTools.includes(hidden), hidden);
+    step("approve/reject are admin-only: an employee gets 403 in Admin and the tools exist only on /mcp/admin");
+
+    const rejected = await mcp("/mcp/admin", admin, "reject_request", { id: chairs, expectedVersion: await version(chairs) });
+    assert.equal(rejected.body.result.isError, undefined, JSON.stringify(rejected.body));
+    assert.equal((await row(chairs)).status, "rejected");
+    await waitForLog(/purchasing\.rejected → alice@example\.test[\s\S]*?Rejected: Chairs/);
+    const guarded = await operation(admin, "approve-request", { id: chairs, expectedVersion: await version(chairs) });
+    assert.equal(guarded.status, 409, JSON.stringify(guarded.body));
+    assert.equal((await row(chairs)).status, "rejected");
+    step("admin MCP rejects (requester emailed); approving it with its current version is 409: WHERE requestStatus = 'submitted' matched 0 rows");
+
+    const overBudget = await operation(admin, "approve-request", { id: monitors, expectedVersion: await version(monitors) });
+    assert.equal(overBudget.status, 409, JSON.stringify(overBudget.body));
+    assert.match(overBudget.body.error.message, /budget cannot cover/);
+    assert.equal((await row(monitors)).status, "submitted");
+    assert.equal(await remaining("Design"), 1000);
+    assert.equal((await ledgerRows()).length, 0);
+    step("over budget: remaining >= 0 fails statement 2, so the status change and ledger insert roll back too");
+
+    const seen = await version(monitors); // the version the admin reviewed
+    const generic = await call("PATCH", `/admin/api/entries/${monitors}?collection=requests`, { cookie: admin, body: { expectedVersion: seen, data: { requestStatus: "approved" } } });
+    assert.ok(generic.status >= 400 && generic.status < 500, JSON.stringify(generic.body));
+    assert.deepEqual([(await row(monitors)).status, await version(monitors)], ["submitted", seen]);
+    const changeAmount = (cookie, expectedVersion) => call("POST", `/api/requests/${monitors}/amount`, { cookie, body: { expectedVersion, amount: 900 } });
+    assert.equal((await changeAmount(bob, seen)).status, 409);
+    const changed = await changeAmount(alice, seen);
+    assert.equal(changed.status, 200, JSON.stringify(changed.body));
+    assert.equal((await changeAmount(alice, seen)).status, 409);
+    const stale = await operation(admin, "approve-request", { id: monitors, expectedVersion: seen });
+    assert.equal(stale.status, 409, JSON.stringify(stale.body));
+    assert.equal((await row(monitors)).status, "submitted");
+    assert.equal(await remaining("Design"), 1000);
+    step("Admin cannot edit requests generically; once the requester changes the amount, approving the reviewed version is 409");
+
+    const lock = (await call("GET", "/api/views/my-requests", { cookie: alice })).body.rows.find(r => r.id === laptop).version;
+    const race = await Promise.all([admin, carol].map(cookie => operation(cookie, "approve-request", { id: laptop, expectedVersion: lock })));
+    assert.deepEqual(race.map(r => r.status).sort(), [200, 409], JSON.stringify(race.map(r => r.body)));
+    assert.equal(await remaining("Engineering"), 3800);
+    assert.deepEqual(await ledgerRows(), [{ requestId: laptop, amount: 1200, remainingAfter: 3800 }]);
+    step("two admins approve the same version at once: one 200, one 409; the budget and ledger change once");
+
+    assert.deepEqual(received, [{ reference: laptop, item: "Laptop", amount: 1200, idempotencyKey: laptop }]);
+    assert.deepEqual(await row(laptop), { status: "ordered", version: lock + 2, supplierOrderId: "SUP-1" });
+    await waitForLog(/purchasing\.approved → alice@example\.test[\s\S]*?Approved: Laptop/);
+    step("approval places the supplier order (status 'ordered') and emails the requester");
+
+    supplierDown = true;
+    const viaAi = await mcp("/mcp/admin", admin, "approve_request", { id: desk, expectedVersion: await version(desk) });
+    assert.equal(viaAi.body.result.isError, undefined, JSON.stringify(viaAi.body));
+    assert.equal((await operation(carol, "approve-request", { id: projector, expectedVersion: await version(projector) })).status, 200);
+    assert.deepEqual([(await row(desk)).status, (await row(projector)).status], ["approved", "approved"]);
+    assert.equal(await remaining("Engineering"), 2800);
+    await waitForLog(/purchasing\.approved → bob@example\.test[\s\S]*?Approved: Desk/);
+    step("the admin MCP tool approves too; with the supplier down, approvals still commit and stay 'approved'");
+
+    assert.equal((await signed({ reference: laptop, orderId: "SUP-1" }, "wrong-secret")).status, 401);
+    const tampered = await call("POST", "/callbacks/supplier", { body: JSON.stringify({ reference: laptop, orderId: "SUP-1" }),
+      headers: { "x-supplier-timestamp": String(Math.floor(Date.now() / 1000)), "x-supplier-signature": "0".repeat(64) } });
+    assert.equal(tampered.status, 401);
+    assert.equal((await row(laptop)).status, "ordered");
+    assert.equal((await signed({ reference: laptop, orderId: "SUP-9" })).status, 409);
+    assert.equal((await signed({ reference: laptop, orderId: "SUP-1" })).status, 204);
+    assert.equal((await row(laptop)).status, "confirmed");
+    assert.equal((await signed({ reference: laptop, orderId: "SUP-1" })).status, 204);
+    assert.equal((await signed({ reference: monitors, orderId: "SUP-1" })).status, 409);
+    // The callback can beat mark-ordered: an 'approved' request is confirmed and keeps the supplier's order id.
+    assert.equal((await signed({ reference: desk, orderId: "SUP-EARLY" })).status, 204);
+    assert.deepEqual(await statusAndOrder(desk), { status: "confirmed", supplierOrderId: "SUP-EARLY" });
+    step("supplier callback: bad signatures are 401 with no change; a signed one confirms (also before 'ordered'); a replay is 204; a wrong order id or a submitted request is 409");
+
+    const late = await submit(bob, "Whiteboard", 150, "Engineering");
+    await query(`UPDATE requests SET created_at = created_at - ${4 * DAY_US} WHERE id = '${late}'`);
+    const before = logs().length;
+    supplierDown = false;
+    assert.equal(await cron(DAILY), 200);
+    for (const to of [owner, "carol@example.test"])
+      await waitForLog(new RegExp(`purchasing\\.reminder → ${to.replace(/[.+]/g, "\\$&")}[\\s\\S]*?Whiteboard`));
+    const reminder = logs().slice(before);
+    assert.ok(!reminder.includes("Monitors"), "a request submitted today is not in the reminder");
+    assert.deepEqual(received.map(order => order.reference), [laptop, projector]);
+    assert.deepEqual(await statusAndOrder(projector), { status: "ordered", supplierOrderId: "SUP-2" });
+    step("daily cron retries the failed supplier order (system caller) and emails every admin about requests pending more than 3 days, and only those");
+
+    const small = await call("POST", "/api/requests", { cookie: bob, body: { title: "Pens", amount: 50, department: "Engineering" } });
+    assert.equal(small.status, 200, JSON.stringify(small.body));
+    const pens = small.body.results[0][0];
+    assert.equal(pens.requestStatus, "approved");
+    const spent = await remaining("Engineering");
+    assert.deepEqual((await ledgerRows()).filter(r => r.requestId === pens.id), [{ requestId: pens.id, amount: 50, remainingAfter: spent }]);
+    await query(`UPDATE budgets SET remaining = 20 WHERE department = 'Design'`);
+    const ledgerBefore = (await ledgerRows()).length, requestsBefore = (await query("SELECT count(*) AS n FROM requests"))[0].n;
+    assert.equal((await call("POST", "/api/requests", { cookie: alice, body: { title: "Tape", amount: 30, department: "Design" } })).status, 409);
+    assert.equal(await remaining("Design"), 20);
+    assert.equal((await ledgerRows()).length, ledgerBefore);
+    assert.equal((await query("SELECT count(*) AS n FROM requests"))[0].n, requestsBefore);
+    step("CASE approves a request of 100 or less at submission: the status, the budget and the ledger row commit together, and one that would overspend is refused with nothing written");
+  }, { vars: { EMPLOYEE_DOMAIN: "example.test", SUPPLIER_API_URL: `http://127.0.0.1:${supplier.address().port}/orders`, SUPPLIER_WEBHOOK_SECRET: SECRET } });
+} finally {
+  supplier.close();
+}

package/docs/examples/purchasing/src/admin.tsx

@@ -0,0 +1,13 @@
+import { defineAdmin } from "@aotter/mantle-admin/app";
+import { admin } from "../generated/admin-client.js";
+
+/**
+ * The Admin entry, built by `mantle bundle`. The approver's daily work gets its own sidebar group above Admin's
+ * built-in ones (content 10, operations 20, reports 30; More stays last); manifests place `pending-requests` and
+ * `requests` in it with `uiSchema.nav`. `tsc` refuses a manifest group left undeclared here.
+ * AGENT: add groups for how the staff work; titles take one string or a { locale: text } map.
+ */
+export default defineAdmin(admin, {
+  nav: { groups: { approvals: { title: { en: "Approvals", "zh-TW": "簽核" }, order: 5 } } },
+  pages: [{ path: "guide", title: "Approver guide", element: <p>Approve a request when the amount fits the budget; reject it with a reason otherwise.</p>, nav: { group: "approvals", order: 9 } }],
+});

package/docs/examples/purchasing/src/handlers.ts

@@ -0,0 +1,33 @@
+import { ContractError } from "@aotter/mantle/contracts";
+import type { Handlers } from "../generated/generated.js";
+import { notifyUser } from "./notify.js";
+import { placeOrder } from "./supplier.js";
+
+type Decided = { id: string; title: string; amount: number; authorId: string };
+
+export const handlers: Handlers = {
+  "approve-request": async ({ store }, input) => {
+    let decided: Decided;
+    try {
+      // One transaction: the guarded status change, the budget deduction and the ledger row.
+      decided = (await store.procedures["approve-request-write"](input)).results[0]![0] as Decided;
+    } catch (error) {
+      // The declared budget check is a business refusal, not a server error. Nothing was written.
+      // The approval's only Schema check is the budget one.
+      if (error instanceof ContractError && error.code === "CONFLICT" && error.fields?.kind === "check" && error.fields.schema === "budgets")
+        throw new ContractError("CONFLICT", "The department budget cannot cover this request.", "procedures/approve-request");
+      throw error;
+    }
+    // After commit: nothing below may turn the committed approval into an error response.
+    const ordered = await placeOrder(store, decided);
+    await notifyUser(decided.authorId, `Approved: ${decided.title}`,
+      `Your purchase request "${decided.title}" was approved${ordered ? " and ordered from the supplier" : ""}.`, "purchasing.approved");
+    return { id: decided.id, requestStatus: ordered ? "ordered" : "approved" };
+  },
+  "reject-request": async ({ store }, input) => {
+    const decided = (await store.procedures["reject-request-write"](input)).results[0]![0] as Decided;
+    await notifyUser(decided.authorId, `Rejected: ${decided.title}`,
+      `Your purchase request "${decided.title}" was rejected.`, "purchasing.rejected");
+    return { id: decided.id, requestStatus: "rejected" };
+  },
+};

package/docs/examples/purchasing/src/notify.ts

@@ -0,0 +1,29 @@
+import { ConsoleEmailSender, type EmailSender } from "@aotter/mantle/email";
+import { env } from "cloudflare:workers";
+
+// AGENT: replace with a real sender before deploying (Cloudflare `send_email` binding, docs/handbook/guides/email.md).
+// ConsoleEmailSender only logs; it sends nothing.
+export const sender: EmailSender = new ConsoleEmailSender();
+
+// Recipients come from Better Auth through Mantle's server-side read (no session, no SQL on Better Auth's tables).
+// Loaded lazily: Better Auth stays out of the Worker's startup graph.
+const identity = async () => (await import("@aotter/mantle/auth/identity")).readIdentity((await import("./auth.js")).createAuth(env));
+
+/** Active admins (Better Auth adminRoles / adminUserIds). */
+export async function adminEmails(): Promise<string[]> {
+  return (await (await identity()).admins()).map(user => user.email);
+}
+
+/** Email failures never undo a decision that has already committed. */
+export async function notify(to: string, subject: string, text: string, category: string) {
+  try { await sender.send({ to, subject, text, locale: "en", category }); }
+  catch (error) { console.error(`[purchasing] ${category} email failed`, error); }
+}
+
+/** Looks up the user's email and sends; a failed lookup is logged like a failed send. */
+export async function notifyUser(userId: string, subject: string, text: string, category: string) {
+  let to: string | undefined;
+  try { to = (await (await identity()).user(userId))?.email; }
+  catch (error) { console.error(`[purchasing] ${category} recipient lookup failed`, error); }
+  if (to) await notify(to, subject, text, category);
+}

package/docs/examples/purchasing/src/requests-page.ts

@@ -0,0 +1,57 @@
+import type { Caller } from "@aotter/mantle/contracts";
+import { store } from "../generated/generated.js";
+import myRequests from "../generated/paged/views/my-requests.js";
+import { handlers } from "./handlers.js";
+import { signInRedirect } from "./sign-in.js";
+
+/**
+ * GET /requests: the employee's own page. Anonymous visitors go to /sign-in and come back.
+ * Reads run here as the signed-in caller (`my-requests` restricts rows to `author_id = auth.uid()`). Writes do not:
+ * the form submits to `POST /api/requests`, the REST Trigger the manifest declares for `submit-request`, so input
+ * validation, `requires` and the origin check happen there. Request data never reaches a Procedure through app code.
+ * AGENT: unstyled on purpose; add the app's styling, copy and a change-amount action (its own Trigger) as needed.
+ */
+export async function requestsPage(request: Request, env: Env, caller: Caller): Promise<Response> {
+  if (caller.kind === "anonymous") return signInRedirect(request);
+  const mine = await myRequests(env.DB, caller, {}, { limit: 50 });
+  // Department names only; the budget amounts stay admin-side.
+  const budgets = await store(env.DB, { kind: "system", reason: "department list" }, { handlers }).collection("budgets").find({ limit: 100 });
+  return new Response(`<!doctype html>
+<html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="robots" content="noindex"><title>My purchase requests</title>
+<h1>My purchase requests</h1>
+<form action="/api/requests" method="post" id="new-request">
+  <label>What <input name="title" required></label>
+  <label>Amount <input name="amount" type="number" min="1" step="1" required></label>
+  <label>Department <select name="department" required>${budgets.rows.map(b => `<option>${escape(String(b.department))}</option>`).join("")}</select></label>
+  <button>Submit</button>
+  <p role="alert" id="error" hidden></p>
+</form>
+<table>
+  <tr><th>What</th><th>Amount</th><th>Department</th><th>Status</th></tr>
+  ${mine.rows.map(r => `<tr><td>${escape(String(r.title))}</td><td>${escape(String(r.amount))}</td><td>${escape(String(r.department))}</td><td>${escape(String(r.requestStatus))}</td></tr>`).join("\n  ")}
+</table>
+<script type="module">
+// The submit event fires only after the browser's own checks (required, min) pass; the Trigger checks again.
+const form = document.getElementById("new-request"), error = document.getElementById("error");
+form.addEventListener("submit", async event => {
+  event.preventDefault();
+  // Field types come from the inputs, so a number input sends a JSON number.
+  const body = Object.fromEntries([...form.elements].filter(field => field.name).map(field => [field.name, field.type === "number" ? field.valueAsNumber : field.value]));
+  const button = form.querySelector("button");
+  button.disabled = true;
+  try {
+    const response = await fetch(form.action, { method: form.method, headers: { "content-type": "application/json" }, body: JSON.stringify(body) });
+    if (response.ok) return location.reload(); // the page reads the list again
+    error.textContent = (await response.json().catch(() => null))?.error?.message ?? "Not submitted. Try again.";
+  } catch {
+    error.textContent = "Not submitted: the network is unavailable.";
+  }
+  error.hidden = false;
+  button.disabled = false;
+});
+</script>
+`, { headers: { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" } });
+}
+
+const escape = (text: string) => text.replace(/[&<>"']/g, c => `&#${c.charCodeAt(0)};`);

package/docs/examples/purchasing/src/routes.ts

@@ -0,0 +1,53 @@
+import { ContractError, type Caller } from "@aotter/mantle/contracts";
+import { store } from "../generated/generated.js";
+import confirmOrder from "../generated/procedures/confirm-order.js";
+import { handlers } from "./handlers.js";
+import { requestsPage } from "./requests-page.js";
+import { signInPage } from "./sign-in.js";
+
+const MAX_BODY = 64 * 1024, MAX_SKEW_SECONDS = 300;
+
+/**
+ * App-owned routes, tried before Admin, MCP and REST. Return undefined to fall through.
+ * GET /sign-in: member sign-in (src/sign-in.ts). GET /requests: the employee's page (src/requests-page.ts).
+ * POST /callbacks/supplier: the supplier confirms an order. The signature is checked over the RAW body before parsing.
+ * AGENT: match the real supplier's signature scheme (header names, what is signed, encoding).
+ */
+export async function appRoutes(request: Request, env: Env, context: { caller: () => Promise<Caller>; waitUntil: (task: Promise<unknown>) => void }): Promise<Response | undefined> {
+  const path = new URL(request.url).pathname;
+  if (path === "/sign-in" && request.method === "GET") return signInPage();
+  if (path === "/requests" && request.method === "GET") return requestsPage(request, env, await context.caller());
+  if (path !== "/callbacks/supplier") return undefined;
+  if (request.method !== "POST") return new Response(null, { status: 405, headers: { allow: "POST" } });
+  if (Number(request.headers.get("content-length") ?? MAX_BODY + 1) > MAX_BODY) return new Response(null, { status: 413 });
+  const raw = await request.arrayBuffer();
+  const timestamp = request.headers.get("x-supplier-timestamp") ?? "";
+  if (!(await verified(env.SUPPLIER_WEBHOOK_SECRET, timestamp, raw, request.headers.get("x-supplier-signature") ?? "")))
+    return new Response(null, { status: 401 });
+
+  let body: { reference?: unknown; orderId?: unknown };
+  try { body = JSON.parse(new TextDecoder().decode(raw)); } catch { return new Response(null, { status: 400 }); }
+  if (typeof body.reference !== "string" || typeof body.orderId !== "string") return new Response(null, { status: 400 });
+  // Trusted path: a system caller, after the signature proved the sender.
+  const system: Caller = { kind: "system", reason: "supplier callback" };
+  try {
+    await confirmOrder(env.DB, system, { id: body.reference, supplierOrderId: body.orderId });
+  } catch (error) {
+    if (!(error instanceof ContractError && error.code === "CONFLICT")) throw error;
+    // A replay of a callback already applied succeeds again, so the supplier stops retrying.
+    const current = await store(env.DB, system, { handlers }).collection("requests").findById(body.reference);
+    if (current?.requeststatus === "confirmed" && current.supplierorderid === body.orderId) return new Response(null, { status: 204 });
+    return new Response(null, { status: 409 }); // unknown request, another order id, or not approved/ordered
+  }
+  return new Response(null, { status: 204 });
+}
+
+/** HMAC-SHA256 over `${timestamp}.${raw body}`, hex encoded; crypto.subtle.verify compares in constant time. */
+async function verified(secret: string, timestamp: string, raw: ArrayBuffer, signature: string) {
+  if (!/^\d+$/.test(timestamp) || Math.abs(Date.now() / 1000 - Number(timestamp)) > MAX_SKEW_SECONDS) return false;
+  if (!/^[0-9a-f]{64}$/.test(signature)) return false;
+  const key = await crypto.subtle.importKey("raw", new TextEncoder().encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["verify"]);
+  const signed = new Uint8Array([...new TextEncoder().encode(`${timestamp}.`), ...new Uint8Array(raw)]);
+  const bytes = new Uint8Array(signature.match(/../g)!.map(pair => parseInt(pair, 16)));
+  return crypto.subtle.verify("HMAC", key, bytes, signed);
+}

package/docs/examples/purchasing/src/schedule.ts

@@ -0,0 +1,31 @@
+import { toCloudflareCron } from "@aotter/mantle/cron";
+import type { Caller } from "@aotter/mantle/contracts";
+import { store } from "../generated/generated.js";
+import approvedRequests from "../generated/views/approved-requests.js";
+import staleRequests from "../generated/views/stale-requests.js";
+import { handlers } from "./handlers.js";
+import { adminEmails, notify } from "./notify.js";
+import { placeOrder } from "./supplier.js";
+
+/** Daily 09:00 UTC; list the same expression in wrangler.jsonc `triggers.crons`. */
+export const DAILY = toCloudflareCron("0 9 * * *");
+/** Remind about requests still 'submitted' after this many days. */
+const PENDING_DAYS = 3;
+
+export async function scheduled(controller: ScheduledController, env: Env): Promise<void> {
+  if (controller.cron !== DAILY) throw new Error(`No application schedule runs on '${controller.cron}'`);
+  const system: Caller = { kind: "system", reason: "daily purchasing cron" };
+
+  // 1. Retry supplier orders that failed right after approval.
+  const data = store(env.DB, system, { handlers });
+  for (const { id, title, amount } of await approvedRequests(env.DB, system, {}))
+    await placeOrder(data, { id: String(id), title: String(title), amount: Number(amount) }); // View rows are typed loosely
+
+  // 2. Remind admins about requests waiting too long.
+  const before = new Date(controller.scheduledTime - PENDING_DAYS * 86_400_000).toISOString();
+  const stale = await staleRequests(env.DB, system, { before });
+  if (stale.length === 0) return;
+  const text = `${stale.length} purchase request(s) have waited more than ${PENDING_DAYS} days:\n` +
+    stale.map(r => `- ${r.title} (${r.department}, ${r.amount})`).join("\n");
+  for (const to of await adminEmails()) await notify(to, "Purchase requests waiting for approval", text, "purchasing.reminder");
+}

package/docs/examples/purchasing/src/signup.ts

@@ -0,0 +1,5 @@
+/** Employees only: an email may create an account only on the company's domain (ADMIN_EMAIL always signs in). */
+export async function allowSignUp(env: Env, email: string): Promise<boolean> {
+  // AGENT: set EMPLOYEE_DOMAIN in wrangler.jsonc vars; for a per-person list, see the club-events example.
+  return email.toLowerCase().endsWith(`@${env.EMPLOYEE_DOMAIN.toLowerCase()}`);
+}

package/docs/examples/purchasing/src/supplier.ts

@@ -0,0 +1,32 @@
+import { env } from "cloudflare:workers";
+import { ContractError } from "@aotter/mantle/contracts";
+import type { HandlerContext } from "../generated/generated.js";
+
+/**
+ * Orders an approved request from the supplier, then marks it 'ordered'. Returns false when the supplier could not be
+ * reached; the request stays 'approved' and the daily cron (src/schedule.ts) retries it.
+ * AGENT: use the supplier's real API, auth and payload.
+ */
+export async function placeOrder(store: HandlerContext["store"], request: { id: string; title: string; amount: number }) {
+  let orderId: string;
+  try {
+    const response = await fetch(env.SUPPLIER_API_URL, {
+      method: "POST",
+      // The request id as idempotency key: a retry after a lost response does not order twice.
+      headers: { "content-type": "application/json", "idempotency-key": request.id },
+      body: JSON.stringify({ reference: request.id, item: request.title, amount: request.amount }),
+      signal: AbortSignal.timeout(10_000),
+    });
+    if (!response.ok) throw new Error(`supplier answered ${response.status}`);
+    ({ orderId } = await response.json() as { orderId: string });
+  } catch (error) {
+    console.error(`[purchasing] supplier order for ${request.id} failed; it stays approved for the retry`, error);
+    return false;
+  }
+  try { await store.procedures["mark-ordered"]({ id: request.id, supplierOrderId: orderId }); }
+  catch (error) {
+    // The supplier's callback already confirmed it (it can arrive before this write).
+    if (!(error instanceof ContractError && error.code === "CONFLICT")) throw error;
+  }
+  return true;
+}

package/docs/examples/purchasing/wrangler.jsonc

@@ -0,0 +1,69 @@
+{
+  "$schema": "node_modules/wrangler/config-schema.json",
+  "name": "mantle-app",
+  "main": "dist/worker/index.js",
+  "compatibility_date": "2026-09-01",
+  "compatibility_flags": [
+    "nodejs_compat",
+    "global_fetch_strictly_public"
+  ],
+  "vars": {
+    "EMPLOYEE_DOMAIN": "example.com"
+  },
+  "secrets": {
+    "required": [
+      "BETTER_AUTH_SECRET",
+      "PUBLIC_ORIGIN",
+      "ADMIN_EMAIL",
+      "SUPPLIER_API_URL",
+      "SUPPLIER_WEBHOOK_SECRET"
+    ]
+  },
+  "observability": {
+    "enabled": true,
+    "logs": {
+      "enabled": true,
+      "head_sampling_rate": 1
+    },
+    "traces": {
+      "enabled": true,
+      "head_sampling_rate": 0.01
+    }
+  },
+  "d1_databases": [
+    {
+      "binding": "DB",
+      "database_name": "mantle-app"
+    }
+  ],
+  "assets": {
+    "directory": "dist/client",
+    "binding": "ASSETS",
+    "run_worker_first": true,
+    "html_handling": "none"
+  },
+  "triggers": {
+    "crons": [
+      "0 9 * * *"
+    ]
+  },
+  "no_bundle": true,
+  "find_additional_modules": true,
+  "base_dir": "dist/worker",
+  "build": {
+    "command": "mantle bundle src/index.ts dist",
+    "watch_dir": [
+      "src",
+      "generated"
+    ]
+  },
+  "rules": [
+    {
+      "type": "ESModule",
+      "globs": [
+        "**/*.js"
+      ],
+      "fallthrough": true
+    }
+  ]
+}

package/docs/examples/recipes/README.md

@@ -0,0 +1,60 @@
+# Recipes
+
+A multilingual recipe site. Admins write recipes in Admin as drafts and publish them; visitors read the published
+recipes in Traditional Chinese (`zh-TW`, the default) and English (`en`) without signing in. The visitor pages are
+plain app-owned HTML with the head tags search and answer engines read, plus Markdown and `llms.txt` for AI agents.
+
+## Capabilities shown
+
+- Publishing lifecycle (draft → publish): `lifecycle: publishing` on both Schemas in `manifests/recipes.yaml`;
+  Admin's publish action runs the generated `recipes.publish` Procedure. Public Views and anonymous Store reads see
+  published rows only.
+- Translations: `recipe_translations` is `localized` and `translates: { parent: recipes, on: slug }`. A translation
+  publishes only while its parent is published, and its reads merge the parent's `total_minutes`, `servings` and
+  `cover_url` (`src/routes.ts` `read`).
+- Visitor pages in `src/routes.ts` (routing, reads) and `src/pages.ts` (rendering), always read as an anonymous caller:
+  - every item of [public pages](../../handbook/guides/public-pages.md): head tags, Open Graph, JSON-LD `Recipe`, the
+    short answer block, hreflang and `x-default`, per-language Markdown alternates, `llms.txt`, sitemap and robots.
+- Cover images on R2: `wrangler.jsonc` (the shell's file plus the `MEDIA` bucket and two vars), `src/site-config.ts`
+  (media purpose `cover`) and `src/media.ts` (`r2MediaStorage`). See "Cover images" below to switch it on.
+
+Search for `AGENT:` for what an app must still provide: layout and styling, cache policy, list paging, the S3 signer.
+
+## Combine with
+
+- Need members to see or edit only their own rows? Add club-events' `restrict: { recipes: "author_id = auth.uid()" }` on a View.
+- Need review before publishing, or an AI that approves? Add purchasing's guarded status transitions and admin MCP.
+
+## Run it
+
+This runs the example by itself, to read and try. For your own app, run `mantle init` and take only the patterns you need into its manifests and `src/` (`mantle help examples`).
+
+```sh
+npx mantle init my-app
+cp -R node_modules/@aotter/mantle/docs/examples/recipes/. my-app/   # run the example as is
+cd my-app && pnpm install && pnpm generate && pnpm types && pnpm check
+```
+
+Then follow the shell README (`db:init`, `dev`). Sign in at `/admin`, add a recipe, publish it, open `/zh-TW/`.
+Add a translation from the recipe's language tab and publish it to get `/en/`.
+
+## Cover images
+
+The media library needs the generated site module, which the shell does not generate. To switch it on:
+
+1. In `package.json`, add `--site src/site-config.ts` to both the `generate` and `check` commands, then
+   `pnpm generate` (this adds the `site_config`/`media_assets` tables to `generated/schema.sql`).
+2. In `src/service.ts`, import `site` from `../generated/site.js` and `coverStorage` from `./media.js`, and add
+   `site, media: coverStorage(env, signer)` to `adminOptions`. The signer is app-owned (see `src/media.ts`).
+3. Create the bucket, set CORS and the two `vars` in `wrangler.jsonc` (see `docs/handbook/cloudflare/media-r2.md`).
+
+Admin's media library then uploads straight to R2 with presigned URLs; copy a committed image's URL into `cover_url`.
+The smoke does not cover upload: local `wrangler dev` has an R2 binding but no S3 endpoint to presign against.
+
+## `pnpm smoke` proves
+
+- Drafts (zh-TW and en) are absent from detail, `.md`, list and `llms.txt`, even when the request has an admin session.
+- A translation cannot publish before its parent; publishing both through the Admin API makes them visible.
+- Each locale's detail page has title, description, canonical, hreflang (`zh-TW`, `en`, `x-default`) and a switcher link.
+- JSON-LD parses as a `Recipe` with the recipe name; the en page inherits `totalTime` from its parent; the short answer is present.
+- `.md` returns `text/markdown`; `llms.txt` and both locale lists show the published recipe; `/` redirects to `/zh-TW/`.