@aotter/mantle 0.2.0-alpha.5 → 0.2.0-alpha.7

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.ts` declares an Approvals group (`navGroups`) 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.

package/docs/examples/purchasing/manifests/purchasing.yaml

@@ -0,0 +1,341 @@
+# Internal purchase requests: employees submit, admins approve or reject, approval spends a department budget.
+# requestStatus: submitted -> approved -> ordered -> confirmed, or submitted -> rejected.
+apiVersion: cms.mantle.aotter.net/v2
+kind: Schema
+metadata: { name: budgets }
+spec:
+  title: Budgets
+  lifecycle: operational
+  uniqueIndexes: [[department]]
+  # An approval that would overspend fails this check and the whole approval rolls back.
+  checks: ["remaining >= 0"]
+  uiSchema: { list: { primaryField: department, columns: [remaining] } }
+  schema:
+    type: object
+    additionalProperties: false
+    required: [department, remaining]
+    properties:
+      department: { type: string }
+      remaining: { type: integer }
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Schema
+metadata: { name: requests }
+spec:
+  title: Purchase requests
+  lifecycle: operational
+  indexes: [[authorId, createdAt, id], [requestStatus, createdAt, id]]
+  # Sidebar: in the Approvals group (src/admin.ts), after the queue of requests waiting for a decision.
+  uiSchema: { list: { primaryField: title, columns: [department, amount, requestStatus], filterField: requestStatus }, nav: { group: approvals, order: 2 } }
+  schema:
+    type: object
+    # Admin reads requests but cannot edit them generically: a generic edit could move requestStatus back to
+    # 'submitted' and spend the budget twice. Every change goes through the guarded Procedures below.
+    readOnly: true
+    additionalProperties: false
+    required: [title, amount, department, requestStatus]
+    properties:
+      title: { type: string, minLength: 1 }
+      amount: { type: integer, minimum: 1 }
+      department: { type: string }
+      requestStatus: { type: string, enum: [submitted, approved, rejected, ordered, confirmed] }
+      supplierOrderId: { type: string }
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Schema
+metadata: { name: ledger }
+spec:
+  title: Budget ledger
+  lifecycle: operational
+  indexes: [[createdAt, id]]
+  uiSchema: { list: { primaryField: department, columns: [amount, remainingAfter, requestId] } }
+  schema:
+    type: object
+    readOnly: true # written only by approve-request-write
+    additionalProperties: false
+    required: [requestId, department, amount, remainingAfter]
+    properties:
+      requestId: { type: string }
+      department: { type: string }
+      amount: { type: integer }
+      remainingAfter: { type: integer }
+---
+# Employees see only the requests they submitted.
+apiVersion: cms.mantle.aotter.net/v2
+kind: View
+metadata: { name: my-requests }
+spec:
+  surface: public
+  requires: { auth: { all: [ctx.user] } }
+  restrict: { requests: "author_id = auth.uid()" }
+  sql: |
+    SELECT id, title, amount, department, requestStatus AS "requestStatus", version
+    FROM requests ORDER BY created_at DESC, id DESC
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: View
+metadata: { name: pending-requests }
+spec:
+  title: Pending purchase requests
+  surface: admin
+  requires: { auth: { all: [ctx.admin] } }
+  uiSchema: { nav: { group: approvals, order: 1 } }
+  sql: |
+    SELECT id, title, amount, department, version
+    FROM requests WHERE requestStatus = 'submitted' ORDER BY created_at, id
+---
+# The daily reminder reads this from src/schedule.ts; no route or tool exposes it.
+apiVersion: cms.mantle.aotter.net/v2
+kind: View
+metadata: { name: stale-requests }
+spec:
+  surface: internal
+  input:
+    type: object
+    additionalProperties: false
+    required: [before]
+    properties:
+      before: { type: string, format: date-time }
+  sql: |
+    SELECT id, title, amount, department FROM requests
+    WHERE requestStatus = 'submitted' AND created_at < input.before
+    ORDER BY created_at, id LIMIT 100
+---
+# Approved but not yet ordered (the supplier call failed): the cron retries these.
+apiVersion: cms.mantle.aotter.net/v2
+kind: View
+metadata: { name: approved-requests }
+spec:
+  surface: internal
+  sql: |
+    SELECT id, title, amount FROM requests WHERE requestStatus = 'approved'
+    ORDER BY created_at, id LIMIT 20
+---
+# Selecting from budgets refuses a department that has no budget, so approval always has a budget row to deduct.
+apiVersion: cms.mantle.aotter.net/v2
+kind: Procedure
+metadata: { name: submit-request }
+spec:
+  title: Submit a purchase request
+  requires: { auth: { all: [ctx.user] } }
+  input:
+    type: object
+    additionalProperties: false
+    required: [title, amount, department]
+    properties:
+      title: { type: string, minLength: 1 }
+      amount: { type: integer, minimum: 1 }
+      department: { type: string }
+  output: { type: object }
+  handler:
+    sql: |
+      INSERT INTO requests (title, amount, department, requestStatus)
+      SELECT input.title, input.amount, b.department, 'submitted' FROM budgets b WHERE b.department = input.department
+      RETURNING id, version
+---
+# The requester may change the amount while the request is still 'submitted'. The version moves on, so an admin
+# approving the version they reviewed before the change gets a 409 and looks again.
+apiVersion: cms.mantle.aotter.net/v2
+kind: Procedure
+metadata: { name: change-amount }
+spec:
+  title: Change the amount of my request
+  requires: { auth: { all: [ctx.user] } }
+  restrict: { requests: "author_id = auth.uid()" }
+  input:
+    type: object
+    additionalProperties: false
+    required: [id, expectedVersion, amount]
+    properties:
+      id: { type: string }
+      expectedVersion: { type: integer }
+      amount: { type: integer, minimum: 1 }
+  output: { type: object }
+  handler:
+    sql: |
+      UPDATE requests SET amount = input.amount
+      WHERE id = input.id AND version = input.expectedVersion AND requestStatus = 'submitted'
+      RETURNING id, version
+---
+# Admin-only. The ref handler runs the write below, then places the supplier order and emails the requester.
+apiVersion: cms.mantle.aotter.net/v2
+kind: Procedure
+metadata: { name: approve-request }
+spec:
+  title: Approve a purchase request
+  description: Approve a submitted request; deducts the department budget, records a ledger row and places the supplier order.
+  requires: { auth: { all: [ctx.admin] } }
+  target: { schema: requests, id: id, version: expectedVersion }
+  input:
+    type: object
+    additionalProperties: false
+    required: [id, expectedVersion]
+    properties:
+      id: { type: string }
+      expectedVersion: { type: integer }
+  output: { type: object }
+  handler: { ref: approve-request }
+---
+# One program, one transaction. Statement 1 is the guarded transition: a stale version or a request that is no longer
+# 'submitted' matches 0 rows -> CONFLICT (409). Statement 2 fails remaining >= 0 when over budget. Either failure rolls
+# back all three statements.
+apiVersion: cms.mantle.aotter.net/v2
+kind: Procedure
+metadata: { name: approve-request-write }
+spec:
+  requires: { auth: { all: [ctx.admin] } }
+  input:
+    type: object
+    additionalProperties: false
+    required: [id, expectedVersion]
+    properties:
+      id: { type: string }
+      expectedVersion: { type: integer }
+  output: { type: object }
+  handler:
+    sql: |
+      UPDATE requests SET requestStatus = 'approved'
+      WHERE id = input.id AND version = input.expectedVersion AND requestStatus = 'submitted'
+      RETURNING id, title, amount, author_id AS "authorId";
+      UPDATE budgets SET remaining = remaining - (SELECT r.amount FROM requests r WHERE r.id = input.id)
+      WHERE department = (SELECT r.department FROM requests r WHERE r.id = input.id);
+      INSERT INTO ledger (requestId, department, amount, remainingAfter)
+      SELECT r.id, r.department, r.amount, b.remaining FROM requests r JOIN budgets b ON b.department = r.department
+      WHERE r.id = input.id
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Procedure
+metadata: { name: reject-request }
+spec:
+  title: Reject a purchase request
+  requires: { auth: { all: [ctx.admin] } }
+  target: { schema: requests, id: id, version: expectedVersion }
+  input:
+    type: object
+    additionalProperties: false
+    required: [id, expectedVersion]
+    properties:
+      id: { type: string }
+      expectedVersion: { type: integer }
+  output: { type: object }
+  handler: { ref: reject-request }
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Procedure
+metadata: { name: reject-request-write }
+spec:
+  requires: { auth: { all: [ctx.admin] } }
+  input:
+    type: object
+    additionalProperties: false
+    required: [id, expectedVersion]
+    properties:
+      id: { type: string }
+      expectedVersion: { type: integer }
+  output: { type: object }
+  handler:
+    sql: |
+      UPDATE requests SET requestStatus = 'rejected'
+      WHERE id = input.id AND version = input.expectedVersion AND requestStatus = 'submitted'
+      RETURNING id, title, author_id AS "authorId"
+---
+# Called after the supplier accepted the order: by the approve handler (admin caller) and by the cron retry (system
+# caller). System callers satisfy no `requires` predicate, so it has none; no Trigger exposes it.
+apiVersion: cms.mantle.aotter.net/v2
+kind: Procedure
+metadata: { name: mark-ordered }
+spec:
+  input:
+    type: object
+    additionalProperties: false
+    required: [id, supplierOrderId]
+    properties:
+      id: { type: string }
+      supplierOrderId: { type: string }
+  output: { type: object }
+  handler:
+    sql: |
+      UPDATE requests SET requestStatus = 'ordered', supplierOrderId = input.supplierOrderId
+      WHERE id = input.id AND requestStatus = 'approved'
+      RETURNING id
+---
+# Called only by POST /callbacks/supplier (src/routes.ts) as a system caller after the signature checks out.
+# The callback can arrive before mark-ordered ran, so 'approved' is accepted too.
+# No Trigger exposes it; system callers satisfy no `requires` predicate, so it has none.
+apiVersion: cms.mantle.aotter.net/v2
+kind: Procedure
+metadata: { name: confirm-order }
+spec:
+  input:
+    type: object
+    additionalProperties: false
+    required: [id, supplierOrderId]
+    properties:
+      id: { type: string }
+      supplierOrderId: { type: string }
+  output: { type: object }
+  handler:
+    sql: |
+      UPDATE requests SET requestStatus = 'confirmed', supplierOrderId = input.supplierOrderId
+      WHERE id = input.id AND (
+        (requestStatus = 'ordered' AND supplierOrderId = input.supplierOrderId)
+        OR requestStatus = 'approved')
+      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: change-amount-http }
+spec:
+  source: { kind: http, method: POST, path: '/api/requests/{id}/amount' }
+  target: { procedure: change-amount }
+---
+# Admin MCP tools: an AI agent connected to /mcp/admin can approve or reject.
+apiVersion: cms.mantle.aotter.net/v2
+kind: Trigger
+metadata: { name: approve-request-mcp }
+spec:
+  source: { kind: mcp, surface: admin }
+  target: { procedure: approve-request }
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Trigger
+metadata: { name: reject-request-mcp }
+spec:
+  source: { kind: mcp, surface: admin }
+  target: { procedure: reject-request }
+---
+# Admins open a department's budget from the Budgets list header (operational collections have no generic create);
+# adjusting `remaining` later is an ordinary Admin edit.
+apiVersion: cms.mantle.aotter.net/v2
+kind: Procedure
+metadata: { name: open-budget }
+spec:
+  title: Open a budget
+  description: Give a department a purchasing budget.
+  requires: { auth: { all: [ctx.admin] } }
+  uiSchema: { collectionAction: budgets }
+  input:
+    type: object
+    required: [department, remaining]
+    additionalProperties: false
+    properties:
+      department: { type: string, minLength: 1, maxLength: 100, title: Department }
+      remaining: { type: integer, minimum: 0, title: Budget }
+  output: { type: object }
+  handler:
+    sql: |
+      INSERT INTO budgets (department, remaining) VALUES (input.department, input.remaining) RETURNING id
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Trigger
+metadata: { name: open-budget-admin }
+spec:
+  source: { kind: mcp, surface: admin }
+  target: { procedure: open-budget }

package/docs/examples/purchasing/seed.sql

@@ -0,0 +1,4 @@
+-- Department budgets (whole currency units). Admins edit them in Admin > Budgets.
+INSERT INTO budgets (id, created_at, updated_at, department, remaining) VALUES
+  ('budget-engineering', 1767225600000000, 1767225600000000, 'Engineering', 5000),
+  ('budget-design', 1767225600000000, 1767225600000000, 'Design', 1000);

package/docs/examples/purchasing/smoke.mjs

@@ -0,0 +1,171 @@
+// 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 { smoke } from "./smoke-kit.mjs";
+
+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 ({ 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);
+    const publicTools = (await mcp("/mcp", alice)).body.result.tools.map(t => t.name);
+    assert.ok(!publicTools.includes("approve_request") && !publicTools.includes("reject_request"), publicTools.join());
+    const adminTools = (await mcp("/mcp/admin", admin)).body.result.tools.map(t => t.name);
+    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");
+  }, { 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.ts

@@ -0,0 +1,12 @@
+import type { AdminExtension, AdminNavGroup } from "@aotter/mantle-admin/server/extensions";
+
+/**
+ * Admin presentation, read by `mantle generate --admin-extensions src/admin.ts` (no runtime code).
+ * 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`.
+ * AGENT: add groups for how the staff work; titles take one string or a { locale: text } map.
+ */
+export const navGroups: AdminNavGroup[] = [
+  { id: "approvals", title: { en: "Approvals", "zh-TW": "簽核" }, order: 5 },
+];
+export const adminExtensions: AdminExtension[] = [];

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.message.startsWith("A check of the Schema failed"))
+        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" };
+  },
+};