@aotter/mantle 0.2.0-alpha.9 → 0.2.0

package/dist/usecase/validation.js

@@ -1,4 +1,3 @@
-/** Compile boundary checks into each operation; no schema enters the request bundle. */
 import { INPUT_RULE_KEYWORDS, lookupLocalRef as lookup, rootRefChain } from "../build/compiler.js";
 import { literal, q } from "../domain/entry.js";
 import { publishingInput } from "./publishing.js";
@@ -6,14 +5,9 @@ import { equal } from "../kernel/validation.js";
 const pointer = (key) => key.replace(/~/g, "~0").replace(/\//g, "~1");
 const supported = new Set([..."$defs $ref $schema $id type nullable properties required additionalProperties items enum const format pattern minLength maxLength minimum maximum exclusiveMinimum exclusiveMaximum multipleOf minItems maxItems title description default readOnly writeOnly examples deprecated x-mantle-ref x-mcp-hint".split(" "), ...INPUT_RULE_KEYWORDS]);
 const shapes = "see docs/handbook/reference/surface.md";
-// YAML .inf and .nan parse to numbers that JSON writes as null.
 const finite = (value) => typeof value === "number" ? Number.isFinite(value) : !!value && typeof value === "object" ? Object.values(value).every(finite) : true;
 const has = (key) => `Object.hasOwn(object,${q(key)})`;
 const exactly = (value, keys) => !!value && typeof value === "object" && !Array.isArray(value) && Object.keys(value).sort().join(" ") === keys;
-/**
- * An object schema's rules, each failing `when` (JavaScript on `object`) with its sentence at the missing field `key`, or the
- * reason a rule has an unsupported shape.
- */
 function rules(schema) {
     const declared = (names) => Array.isArray(names) && names.length > 0 && names.every(name => typeof name === "string" && Object.hasOwn(schema.properties ?? {}, name));
     const list = (names) => names.map(name => `'${name}'`).join(" and ");
@@ -34,7 +28,6 @@ function rules(schema) {
     if (condition !== undefined || then !== undefined || otherwise !== undefined) {
         const [key] = exactly(condition, "properties required") ? Object.keys(condition.properties) : [];
         const value = key === undefined ? undefined : condition.properties[key];
-        // Without required: [key], an absent key satisfies `if`.
         if (key === undefined || !exactly(condition.properties, key) || !exactly(value, "const") || !(["string", "boolean"].includes(typeof value.const) || Number.isFinite(value.const) || value.const === null) || q(condition.required) !== q([key]) || !declared([key]))
             return `if is supported only as exactly { properties: { <field>: { const: <string, finite number, boolean or null> } }, required: [<field>] }, so an absent field does not satisfy it; ${shapes}.`;
         if (then === undefined && otherwise === undefined || [then, otherwise].some(branch => branch !== undefined && !(exactly(branch, "required") && declared(branch.required))))
@@ -47,19 +40,12 @@ function rules(schema) {
     }
     return found;
 }
-/** Whether an input schema accepts `{}`: a list View is read with no input, so web indexes need this. */
 export function acceptsEmpty(input) {
     if (input === undefined)
         return true;
-    // Validation applies a root `$ref`'s target too, so each schema along the chain must accept `{}`; an unresolved or cyclic chain does not.
-    // dependentRequired needs a present key; an if needs its field, so `{}` meets only an else. An enum or const must admit `{}`.
     return rootRefChain(input)?.every(schema => !schema.required?.length && schema.anyOf === undefined && !schema.else?.required?.length
         && (schema.enum === undefined || schema.enum.some(option => equal({}, option))) && (schema.const === undefined || equal({}, schema.const)) && (schema.type === undefined || [schema.type].flat().includes("object"))) ?? false;
 }
-/**
- * An input schema as an AI tool catalogue advertises it: some model APIs refuse rules (a root `anyOf`, `if`), so each rule leaves
- * the schema and becomes a sentence of the description.
- */
 export function advertised(input, description) {
     if (!input)
         return { inputSchema: input, description };
@@ -68,7 +54,6 @@ export function advertised(input, description) {
         if (!node || typeof node !== "object")
             return;
         const schema = node;
-        // An MCP View tool keeps each rule set of its root `$ref` chain as an `allOf` branch over the merged properties.
         const branches = Array.isArray(schema.allOf) ? schema.allOf : [];
         for (const branch of [schema, ...branches.map(branch => ({ ...branch, properties: schema.properties }))]) {
             const found = rules(branch);
@@ -111,9 +96,7 @@ export function emitValidation(plan, refuse = (path, message) => { throw Error(`
                 files[file] = `import { transition } from "@aotter/mantle/validation";\nexport const validate = (raw: unknown) => transition(${q(base)}, raw);\n`;
                 continue;
             }
-            // Only a local `$ref`, or more than 100 nested objects and arrays, can reach the nesting limit: only then is `depth` passed.
             const recursive = json.includes('"$ref"') || json.split(/[[{]/).length > 101, depth = recursive ? ",depth+1" : "";
-            // Identical bodies share one function.
             const nodes = new Map(), bodies = new Map(), functions = [], formats = new Set(), patterns = new Map();
             let equality = false;
             const resolve = (ref) => {
@@ -142,7 +125,6 @@ export function emitValidation(plan, refuse = (path, message) => { throw Error(`
                         refuse(base, `Unsupported input type '${type}'.`);
                 if (types.length)
                     lines.push(typeCheck(types));
-                // After a single type check `fail` (never) has narrowed `value`: that type's guard is implied.
                 const only = types.length === 1 ? types[0] : undefined;
                 const guard = (type, test = `(${condition(type)})`) => only === type || type === "number" && only === "integer" ? "" : test + " && ";
                 if (schema.enum) {
@@ -197,7 +179,6 @@ export function emitValidation(plan, refuse = (path, message) => { throw Error(`
                 }
                 if (schema.items)
                     lines.push(`${only === "array" ? "" : "if (Array.isArray(value)) "}for (let i=0;i<value.length;i++) ${emit(schema.items)}(value[i],path+"/"+i${depth});`);
-                // Several keys that need no JSON-pointer escaping are checked by one loop, in the same order.
                 const required = schema.required ?? [], checks = Object.entries(schema.properties ?? {}).map(([key, child]) => [key, emit(child)]);
                 const loop = (keys) => keys.length > 1 && keys.every(key => pointer(key) === key);
                 const object = loop(required) ? [`for (const key of ${q(required)}) if (!Object.hasOwn(object,key)) fail(path+"/"+key,"Required field is missing.");`] : required.map(key => `if (!Object.hasOwn(object,${q(key)})) fail(path+${q("/" + pointer(key))},"Required field is missing.");`);
@@ -217,7 +198,6 @@ export function emitValidation(plan, refuse = (path, message) => { throw Error(`
                 if (object.length)
                     lines.push(`${only === "object" ? "" : `if (${condition("object")}) `}{ const object = value as Record<string,unknown>;\n${object.join("\n")}\n}`);
                 const body = lines.join("\n");
-                // Without recursion nothing calls a check before its body is complete, so an identical body's function serves it.
                 const fn = recursive ? named : bodies.get(body) ?? named;
                 if (fn === named) {
                     bodies.set(body, fn);

package/docs/examples/README.md

@@ -1,7 +1,8 @@
 # Examples
 
-Start from the **app shell**, then copy the example closest to your app on top of it. Each example shows a few
-capabilities the others do not; combine them for anything else.
+Start an app with `mantle init`, which writes the **app shell** once. The examples are references: each shows a few
+capabilities the others do not. Find each need in **Combining** below, read that example's manifest and source, and
+take the pattern into your own manifests and `src/`. Do not copy an example directory over your app.
 
 | Example | Shows |
 |---|---|
@@ -16,20 +17,27 @@ capabilities the others do not; combine them for anything else.
 | You need | Take |
 |---|---|
 | Stock that never oversells (orders, tickets, bookings) | club-events' capacity: a Schema `checks` constraint plus the decrement in the same program |
+| An order, cart or import with several rows that must all commit or none | one SQL Procedure over `json_each(input.items)` with a counted check that refuses unknown lines (`mantle help typed-queries`, "Several rows that commit together") |
 | Employees or customers who see only their own records | club-events' `restrict: { <schema>: "author_id = auth.uid()" }` |
 | An approval step, or any state machine | purchasing's guarded `UPDATE ... WHERE requestStatus = ...` Procedures |
+| Approve first, then reserve or spend | purchasing's `approve-request-write`: the guarded status change and the budget deduction in one program (`mantle help sql-patterns`, "Approve before reserving") |
+| A status chosen while writing (auto-approve small requests) | purchasing's `submit-request`: `CASE` in the INSERT ("Choose a status while writing: CASE") |
+| Edit only the fields given | `COALESCE(input.field, field)` ("Change only the fields given") |
+| Create or add (restock, counters) | `INSERT ... ON CONFLICT (...) DO UPDATE` ("Create or add") |
+| Refuse while something still refers to it | a `NOT EXISTS` guard in the UPDATE (purchasing's `submit-request` ledger row; "Refuse while something refers to it") |
+| A record with its children in one read | club-events' `event-roster`: a JSON array per row ("A row with its children in one read") |
+| The latest row per group, rankings | `row_number() OVER (PARTITION BY ...)` ("The latest row of each group") |
 | A third-party API that answers later (webhooks, callbacks) | purchasing's `src/routes.ts`: verify the raw request, then call a Procedure |
 | Public, multilingual, search- and AI-friendly pages | recipes' `src/routes.ts` |
 | Invite-only or members-only sign-up | club-events' `members` allowlist + `src/signup.ts` |
 | Notifications and reminders | purchasing's `EmailSender` call and `src/schedule.ts` |
 
-When you copy an example only for one of its patterns, delete what your app does not need. Copying club-events, for
-example, also brings its `members` allowlist and `src/signup.ts` (members-only sign-up); remove both, or restore the
+If you do copy an example's files, delete what your app does not need. Copying club-events, for example, also brings its `members` allowlist and `src/signup.ts` (members-only sign-up); remove both, or restore the
 shell's allow-all `src/signup.ts`, unless sign-up should be invite-only. Purchasing brings its supplier callback
 (`src/routes.ts`, `src/supplier.ts`), email (`src/notify.ts`), cron (`src/schedule.ts` and `triggers.crons`) and its
 `wrangler.jsonc` secrets. `pnpm generate` and `tsc` point at leftovers that reference removed Schemas.
 
 Every example uses two roles: `admin` (the admin layer) and `user`.
 
-[Reference service](https://github.com/aotter/mantle/tree/v0.2.0-alpha.9/docs/examples/reference-service) is the release smoke test for packed packages, not a starting point. Its source lives in the tagged repository; it is not included in the npm docs.
+[Reference service](https://github.com/aotter/mantle/tree/v0.2.0/docs/examples/reference-service) is the release smoke test for packed packages, not a starting point. Its source lives in the tagged repository; it is not included in the npm docs.
 Projects on 0.1.x move with [the upgrade guide](../upgrade-0.1-to-0.2.md).

package/docs/examples/app-shell/README.md

@@ -2,22 +2,23 @@
 
 The wiring every Mantle Cloudflare app needs, ready to copy: Better Auth (email OTP, admin + user roles),
 one Worker fetch (auth routes → your routes → Admin → MCP → generated REST), the Admin console assets, and a
-local acceptance kit. It has no business manifests: add your own, or copy one of the examples on top of it.
+local acceptance kit. It has no business manifests: add your own, taking patterns from the examples (`mantle help examples`).
 
 ## Start an app
 
 ```sh
-cp -R node_modules/@aotter/mantle/docs/examples/app-shell/. my-app/   # or from this repository
-cp -R node_modules/@aotter/mantle/docs/examples/club-events/. my-app/ # optional: an example on top
+npx @aotter/mantle@<exact version> init my-app   # writes this shell once, Mantle packages pinned to that version
 cd my-app
-# package.json: pin the exact installed Mantle version for @aotter/mantle, -admin and -ui
 pnpm install
+# add manifests/*.yaml (mantle help four-atoms; patterns: mantle help examples)
 pnpm generate          # writes generated/ and lists any `handler: { ref }` to implement in src/handlers.ts
 pnpm types && pnpm check
 cp .dev.vars.example .dev.vars
-pnpm db:init && pnpm db:seed   # db:seed only when the example has seed.sql
+pnpm db:init                   # add seed.sql and run pnpm db:seed for fixtures
 pnpm dev                       # one-time codes print to this log
-pnpm smoke                     # when the copied example has smoke.mjs
+pnpm smoke                     # your smoke.mjs on smoke-kit.mjs (see Files you edit)
+pnpm accept                    # hand each role to a fresh evaluator (see Independent acceptance)
+pnpm test                      # Admin MCP App check: needs Chrome (npx playwright-core install chromium, or MANTLE_TEST_CHROMIUM=<executable>)
 ```
 
 npm works too (`npm install`, `npm run …`). `package.json` pins `@better-auth/core` and `@better-auth/utils` even though
@@ -38,6 +39,7 @@ on one version.
 | `src/signup.ts` | `allowSignUp(env, email)`: who may create an account (allow-all by default). `auth.ts` calls it before Better Auth creates a user; `ADMIN_EMAIL` is always allowed. |
 | `src/auth.ts` | Better Auth options. Two roles only: `admin` (the admin layer) and `user`. Replace the console OTP sender before deploying. |
 | `smoke.mjs` | Your acceptance steps on `smoke-kit.mjs` (fresh local D1, OTP sign-in per user, REST/MCP/Admin calls). |
+| `accept.mjs` | Independent acceptance setup: one URL per role that carries its session, plus a minimal MCP client. Add a fixtures module for realistic data. |
 
 `src/service.ts` and `src/index.ts` rarely change. The default shell mounts REST and MCP together. If the app deliberately
 chooses asymmetric exposure, delete the blocks marked `MCP / OAuth (deliberate exception)` in `auth.ts` and `service.ts`;
@@ -51,10 +53,39 @@ Search for `AGENT:` to find what an app must fill in.
   `cf-connecting-ip`; when testing by hand, wait a minute or vary that header.
 - `ADMIN_EMAIL`'s first verified sign-in becomes `admin` while no admin exists. The sign-in response may still show
   the previous role; `/admin/api/me` shows the current one.
+- More administrators: in Admin, **More → Administrators** invites by email and **More → Members** grants Admin to an
+  existing member. `docs/handbook/cloudflare/authentication.md` (Identity helpers) has the same operations as an API.
 - Admin HTTP routes are listed in `docs/handbook/guides/native-admin.md`.
 
+`mantle help local-testing` lists what the smoke covers: every Procedure at its edges, each caller's isolation,
+visitor pages without JavaScript, MCP discovery and Admin's MCP App.
 Scripted smoke is not independent acceptance; before reporting a user-facing
-deliverable done, follow the [independent acceptance guide](../../handbook/guides/agent-workflow-acceptance.md).
+deliverable done, follow the independent acceptance guide: `mantle help agent-workflow-acceptance`.
+
+### Independent acceptance
+
+`pnpm accept` (optionally `pnpm accept --fixtures fixtures.mjs --user member@example.test`; with npm, `npm run accept -- --fixtures …`) starts the app on a fresh local D1,
+signs the admin in, runs your fixtures module, signs the user in and prints one local URL per role:
+
+```text
+visitor (anonymous): http://127.0.0.1:18741
+admin (owner@example.test): http://127.0.0.1:46467  MCP http://127.0.0.1:46467/mcp/admin  Admin http://127.0.0.1:46467/admin
+user (member@example.test): http://127.0.0.1:42607  MCP http://127.0.0.1:42607/mcp
+```
+
+Each URL forwards to the app with that role's session; the evaluator never sees a cookie, and the URL refuses
+`/api/auth/*`, so it cannot sign out, sign in as someone else or mint credentials. Give an evaluator only its role's URL:
+
+- MCP: configure the URL as a streamable HTTP MCP server, or, without an MCP client,
+  `node accept.mjs mcp <url>/mcp` lists the tools and `node accept.mjs mcp <url>/mcp <tool> '<json>'` calls one.
+- Admin and member pages: open the URL in a browser (a person's, or Playwright for an agent); it is already
+  signed in.
+- REST: send requests to the URL with no credential.
+
+The fixtures module's default export receives `{ call, mcp, signIn, sql, sessions, user }` and runs between the two
+sign-ins, so an invite-only app can admit the user first. Create records through the app's own REST/MCP as real
+users (other members' records, several states, more than one page); `sql` is for what no surface may write, and returns storage column names (lower case unless aliased).
+Ctrl-C stops the app and deletes its data. To accept an external MCP host's OAuth connection instead, see the guide.
 
 ### MCP acceptance
 

package/docs/examples/app-shell/accept.mjs

@@ -0,0 +1,91 @@
+// Independent acceptance setup (mantle help agent-workflow-acceptance): hands each role to a fresh evaluator without a credential.
+//   node accept.mjs [--fixtures fixtures.mjs] [--user member@example.test]
+//     Starts the app on a fresh local D1 (schema.sql, then seed.sql), signs the admin in with email OTP, runs the optional
+//     fixtures module (default export async ({ call, mcp, signIn, sql, sessions, user }) => {...}: realistic records through
+//     the app's own REST/MCP as real users, e.g. other members' orders and more than one page), signs the user in, then
+//     serves one local proxy per role that adds that role's session to every request. Give an evaluator only its role's URL
+//     (a visitor gets the app's own origin):
+//     MCP at <proxy>/mcp (user) or <proxy>/mcp/admin (admin), Admin at <proxy>/admin, pages and REST at <proxy>/.
+//     The proxy refuses /api/auth/* so the evaluator cannot sign out, sign in or mint credentials. Ctrl-C stops everything.
+//   node accept.mjs mcp <endpoint> [tool [json-arguments]]
+//     A minimal MCP client for an evaluator without one: lists the tools, or calls one and prints the raw result.
+import { createServer } from "node:http";
+import { Readable } from "node:stream";
+import { parseArgs } from "node:util";
+import { pathToFileURL } from "node:url";
+import { resolve } from "node:path";
+
+if (process.argv[2] === "mcp") await client(process.argv[3], process.argv[4], process.argv[5]).catch(error => { console.error(error.message); process.exitCode = 1; });
+else await setup();
+
+async function setup() {
+  const { values } = parseArgs({ args: process.argv.slice(2).filter(arg => arg !== "--"), options: { fixtures: { type: "string" }, user: { type: "string", default: "member@example.test" } } });
+  const { startApp } = await import("./smoke-kit.mjs");
+  const app = await startApp();
+  const stop = async () => { await app.stop(); process.exit(0); };
+  process.on("SIGINT", stop);
+  process.on("SIGTERM", stop);
+  try {
+    // Fixtures run between the two sign-ins, so an invite-only app can admit the user first.
+    const sessions = { admin: await app.signIn(app.owner) };
+    if (values.fixtures) await (await import(pathToFileURL(resolve(values.fixtures)).href)).default({ ...app, sessions, user: values.user });
+    sessions.user = await app.signIn(values.user);
+    const lines = [`visitor (anonymous): ${app.origin}`];
+    for (const [role, cookie] of Object.entries(sessions)) {
+      const url = await proxy(app.origin, cookie);
+      lines.push(`${role} (${role === "admin" ? app.owner : values.user}): ${url}  MCP ${url}/mcp${role === "admin" ? "/admin" : ""}${role === "admin" ? `  Admin ${url}/admin` : ""}`);
+    }
+    console.log(lines.join("\n") + "\nReady. Ctrl-C stops the app and deletes its data.");
+  } catch (error) {
+    console.error(app.logs().slice(-4000));
+    await app.stop();
+    throw error;
+  }
+}
+
+/** A local origin that forwards to the app with one role's session; sliding Set-Cookie updates stay inside the proxy. */
+function proxy(origin, cookie) {
+  const jar = new Map(cookie.split("; ").map(pair => [pair.slice(0, pair.indexOf("=")), pair]));
+  const server = createServer(async (request, response) => {
+    const url = new URL(request.url, origin);
+    if (url.pathname.startsWith("/api/auth/")) { response.writeHead(403, { "content-type": "text/plain" }).end("Sign-in is handled by setup."); return; }
+    const chunks = [];
+    for await (const chunk of request) chunks.push(chunk);
+    const headers = new Headers();
+    for (const [name, value] of Object.entries(request.headers)) if (!["host", "cookie", "origin", "connection", "content-length"].includes(name)) headers.set(name, [value].flat().join(", "));
+    headers.set("cookie", [...jar.values()].join("; "));
+    headers.set("origin", origin);
+    const upstream = await fetch(url, { method: request.method, headers, redirect: "manual", body: chunks.length ? Buffer.concat(chunks) : undefined });
+    for (const set of upstream.headers.getSetCookie()) { const pair = set.split(";")[0]; jar.set(pair.slice(0, pair.indexOf("=")), pair); }
+    const out = {};
+    upstream.headers.forEach((value, name) => { if (!["set-cookie", "content-encoding", "content-length", "transfer-encoding"].includes(name)) out[name] = value; });
+    if (out.location) out.location = out.location.replace(origin, `http://${request.headers.host}`);
+    response.writeHead(upstream.status, out);
+    if (upstream.body) Readable.fromWeb(upstream.body).pipe(response); else response.end();
+  });
+  return new Promise(done => server.listen(0, "127.0.0.1", () => done(`http://127.0.0.1:${server.address().port}`)));
+}
+
+async function client(endpoint, tool, json) {
+  if (!endpoint) throw new Error("usage: node accept.mjs mcp <endpoint> [tool [json-arguments]]");
+  const headers = { "content-type": "application/json", accept: "application/json, text/event-stream" };
+  let id = 0;
+  const rpc = async (method, params) => {
+    const response = await fetch(endpoint, { method: "POST", headers, body: JSON.stringify({ jsonrpc: "2.0", ...(method.startsWith("notifications/") ? {} : { id: ++id }), method, params }) });
+    const session = response.headers.get("mcp-session-id");
+    if (session) headers["mcp-session-id"] = session;
+    const text = await response.text();
+    if (!response.ok && response.status !== 202) throw new Error(`MCP ${method}: HTTP ${response.status} ${text}`);
+    const data = text.split("\n").filter(line => line.startsWith("data:")).map(line => line.slice(5)).join("\n") || text;
+    return data ? JSON.parse(data) : null;
+  };
+  const init = await rpc("initialize", { protocolVersion: "2025-11-25", capabilities: {}, clientInfo: { name: "mantle-accept", version: "1" } });
+  headers["mcp-protocol-version"] = init.result?.protocolVersion ?? "2025-11-25";
+  await rpc("notifications/initialized");
+  if (!tool) {
+    const tools = [];
+    let cursor;
+    do { const page = (await rpc("tools/list", cursor ? { cursor } : {})).result; tools.push(...page.tools); cursor = page.nextCursor; } while (cursor);
+    console.log(JSON.stringify(tools, null, 2));
+  } else console.log(JSON.stringify(await rpc("tools/call", { name: tool, arguments: json ? JSON.parse(json) : {} }), null, 2));
+}

package/docs/examples/app-shell/gitignore

@@ -0,0 +1,7 @@
+node_modules/
+.wrangler/
+.dev.vars
+.env
+*.sqlite
+*.sqlite-shm
+*.sqlite-wal

package/docs/examples/app-shell/package.json

@@ -5,17 +5,18 @@
   "scripts": {
     "generate": "mantle generate cloudflare-d1 generated manifests/*.yaml --auth src/auth.ts --entry src/index.ts --admin",
     "types": "wrangler types --include-runtime=false",
-    "db:init": "wrangler d1 execute mantle-app --local --file generated/schema.sql",
-    "db:seed": "wrangler d1 execute mantle-app --local --file seed.sql",
+    "db:init": "wrangler d1 execute DB --local --file generated/schema.sql",
+    "db:seed": "wrangler d1 execute DB --local --file seed.sql",
     "build": "mantle bundle src/index.ts dist",
     "test": "node --test generated/admin-mcp-app.check.mjs",
     "dev": "wrangler dev --local --ip 127.0.0.1 --port 8787",
     "check": "mantle generate cloudflare-d1 generated manifests/*.yaml --auth src/auth.ts --entry src/index.ts --admin --check && wrangler types --include-runtime=false --check && tsc --noEmit",
-    "smoke": "node smoke.mjs"
+    "smoke": "node smoke.mjs",
+    "accept": "node accept.mjs"
   },
   "dependencies": {
-    "@aotter/mantle": "0.2.0-alpha.9",
-    "@aotter/mantle-ui": "0.2.0-alpha.9",
+    "@aotter/mantle": "0.2.0",
+    "@aotter/mantle-ui": "0.2.0",
     "@better-auth/cimd": "1.7.7",
     "@better-auth/core": "1.7.7",
     "@better-auth/mcp": "1.7.7",
@@ -24,7 +25,7 @@
     "@modelcontextprotocol/ext-apps": "2.0.0",
     "@modelcontextprotocol/server": "2.2.0",
     "better-auth": "1.7.7",
-    "@aotter/mantle-admin": "0.2.0-alpha.9",
+    "@aotter/mantle-admin": "0.2.0",
     "react": "19.3.0",
     "react-dom": "19.3.0"
   },

package/docs/examples/app-shell/smoke-kit.mjs

@@ -3,6 +3,7 @@
 //   import { smoke } from "./smoke-kit.mjs";
 //   await smoke(async ({ call, mcp, signIn, owner, step }) => { const admin = await signIn(owner); ... step("..."); });
 //   Extra Worker variables: await smoke(scenario, { vars: { SUPPLIER_API_URL: "http://127.0.0.1:9999" } });
+// accept.mjs uses startApp() to keep the app running for fresh evaluators.
 import assert from "node:assert/strict";
 import { execFile, spawn, spawnSync } from "node:child_process";
 import { existsSync, mkdtempSync, rmSync } from "node:fs";
@@ -64,11 +65,23 @@ export async function assertMcpDiscovery(endpoint, { tools, headers = {} }) {
   return names;
 }
 
-const database = "mantle-app"; // wrangler.jsonc d1_databases[0].database_name
+const database = "DB"; // the D1 binding (wrangler.jsonc d1_databases[0].binding), so renaming the database changes nothing here
 const env = { ...process.env, WRANGLER_SEND_METRICS: "false" };
 
-export async function smoke(scenario, { vars = {} } = {}) {
-  const port = 18000 + Math.floor(Math.random() * 1000), origin = `http://127.0.0.1:${port}`, owner = "owner@example.test";
+export async function smoke(scenario, options) {
+  const app = await startApp(options);
+  try {
+    await scenario(app);
+    console.log("smoke passed");
+  } catch (error) {
+    console.error(app.logs().slice(-4000));
+    throw error;
+  } finally { await app.stop(); }
+}
+
+/** Start the app on a fresh local D1 (schema.sql, then seed.sql when present); stop() ends wrangler and deletes the state. */
+export async function startApp({ vars = {}, port = 18000 + Math.floor(Math.random() * 1000) } = {}) {
+  const origin = `http://127.0.0.1:${port}`, owner = "owner@example.test";
   const state = mkdtempSync(join(tmpdir(), "mantle-smoke-"));
   // Deployment DDL is explicit: nothing at runtime creates tables.
   for (const file of ["generated/schema.sql", ...(existsSync("seed.sql") ? ["seed.sql"] : [])]) {
@@ -128,6 +141,17 @@ export async function smoke(scenario, { vars = {} } = {}) {
     assert.fail(`no log line matching ${pattern}`);
   };
   const step = name => console.log(`ok - ${name}`);
+  const stop = async () => {
+    const kill = signal => { try { process.kill(-wrangler.pid, signal); } catch { /* already gone */ } };
+    kill("SIGTERM");
+    await new Promise(resolve => {
+      if (wrangler.exitCode !== null) return resolve();
+      const timer = setTimeout(() => { kill("SIGKILL"); resolve(); }, 5_000);
+      wrangler.once("exit", () => { clearTimeout(timer); resolve(); });
+    });
+    kill("SIGKILL");
+    rmSync(state, { recursive: true, force: true });
+  };
   try {
     for (let attempt = 0; ; attempt++) {
       if (wrangler.exitCode !== null) throw new Error(`wrangler exited ${wrangler.exitCode}`);
@@ -135,20 +159,10 @@ export async function smoke(scenario, { vars = {} } = {}) {
       if (attempt > 240) throw new Error("the Worker did not start");
       await new Promise(resolve => setTimeout(resolve, 250));
     }
-    await scenario({ origin, owner, call, mcp, signIn, sql, cron, waitForLog, step, logs: () => logs });
-    console.log("smoke passed");
   } catch (error) {
     console.error(logs.slice(-4000));
+    await stop();
     throw error;
-  } finally {
-    const stop = signal => { try { process.kill(-wrangler.pid, signal); } catch { /* already gone */ } };
-    stop("SIGTERM");
-    await new Promise(resolve => {
-      if (wrangler.exitCode !== null) return resolve();
-      const timer = setTimeout(() => { stop("SIGKILL"); resolve(); }, 5_000);
-      wrangler.once("exit", () => { clearTimeout(timer); resolve(); });
-    });
-    stop("SIGKILL");
-    rmSync(state, { recursive: true, force: true });
   }
+  return { origin, owner, call, mcp, signIn, sql, cron, waitForLog, step, logs: () => logs, stop };
 }

package/docs/examples/app-shell/src/routes.ts

@@ -2,10 +2,13 @@ import type { Caller } from "@aotter/mantle/contracts";
 import { signInPage } from "./sign-in.js";
 
 /**
- * App-owned routes, tried before Admin, MCP and REST. Return undefined to fall through.
+ * App-owned routes, tried before REST. Return undefined to fall through. Paths under /admin and /mcp never reach here, and
+ * neither do Better Auth's (/api/auth/*, /oauth/consent*, /.well-known/oauth-*). A root catch-all page (/:slug) must
+ * still return undefined for the paths of the app's own HTTP Triggers (REST), or it shadows them.
  * GET /sign-in: member sign-in (src/sign-in.ts); a member page sends anonymous visitors there with signInRedirect.
- * AGENT: add visitor pages (HTML, SEO, feeds) and callbacks/webhooks here. A callback must verify the raw Request
- * (signature, timestamp) before it reads the body as JSON or calls a generated Procedure.
+ * AGENT: add visitor pages and callbacks/webhooks here. Visitor pages carry everything in `mantle help public-pages`
+ * (canonical, Open Graph, JSON-LD, answer block, .md alternates, sitemap.xml, robots.txt, llms.txt; recipes example).
+ * A callback must verify the raw Request (signature, timestamp) before it reads the body as JSON or calls a generated Procedure.
  */
 export async function appRoutes(request: Request, _env: Env, _context: { caller: () => Promise<Caller>; waitUntil: (task: Promise<unknown>) => void }): Promise<Response | undefined> {
   if (new URL(request.url).pathname === "/sign-in" && request.method === "GET") return signInPage();

package/docs/examples/app-shell/src/service.ts

@@ -43,7 +43,8 @@ export async function fetchService(request: Request, env: Env, context: Executio
     const ownAuth = await withAuthTasks(context.waitUntil.bind(context), () => authRoutes(auth!, { methods: [{ kind: "email-otp" }], resolver: caller })(request));
     if (ownAuth) return respond(ownAuth);
     const url = new URL(request.url);
-    const own = await appRoutes(request, env, { caller, waitUntil: context.waitUntil.bind(context) });
+    // /admin and /mcp belong to Admin and MCP: a root catch-all page in src/routes.ts (/:slug) never shadows them.
+    const own = /^\/(?:admin|mcp)(?:\/|$)/.test(url.pathname) ? undefined : await appRoutes(request, env, { caller, waitUntil: context.waitUntil.bind(context) });
     if (own) return respond(own);
     let response: Response | undefined;
     if (url.pathname === "/admin/api" || url.pathname.startsWith("/admin/api/")) {

package/docs/examples/club-events/README.md

@@ -23,6 +23,9 @@ over MCP. Only members the officers listed in Admin can sign up. Officers see ev
   Schema check; no View or Trigger exposes it). `src/signup.ts` replaces the shell's allow-all `allowSignUp` with a
   Store lookup as a system caller, so any other email gets 403 at sign-in and no account. To invite another officer
   through Admin, list their email in `members` first.
+- **An event with its attendees in one read**: the admin View `event-roster` returns each event with an `attendees`
+  JSON array built by `json_group_array(json_set('{}', ...))` in a correlated subquery, so an event nobody joined has
+  `[]`. PostgreSQL writes it with `jsonb_agg(jsonb_build_object(...))`; see `mantle help sql-patterns`.
 - **Member MCP tool**: the `register-mcp` Trigger (`surface: public`) exposes `register` on `/mcp`, so the member's AI
   registers with the member's own sign-in.
 
@@ -36,9 +39,11 @@ over MCP. Only members the officers listed in Admin can sign up. Officers see ev
 
 ## 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
-cp -R node_modules/@aotter/mantle/docs/examples/app-shell/. my-app/
-cp -R node_modules/@aotter/mantle/docs/examples/club-events/. my-app/
+npx mantle init my-app
+cp -R node_modules/@aotter/mantle/docs/examples/club-events/. my-app/   # run the example as is
 cd my-app && pnpm install && pnpm generate && pnpm types && pnpm check
 cp .dev.vars.example .dev.vars && pnpm db:init && pnpm dev
 pnpm smoke

package/docs/examples/club-events/manifests/club-events.yaml

@@ -86,6 +86,21 @@ spec:
     FROM registrations r JOIN events e ON e.id = r.eventId
     ORDER BY r.created_at DESC, r.id DESC
 ---
+# Officers' roster: each event with its attendees as one JSON array, so one read answers "who is coming".
+# The correlated subquery gives [] for an event nobody registered for (a LEFT JOIN + GROUP BY would give one empty object).
+# SQLite/D1 builds the objects with json_set; on PostgreSQL write jsonb_agg(jsonb_build_object('memberName', r.memberName)).
+apiVersion: cms.mantle.aotter.net/v2
+kind: View
+metadata: { name: event-roster }
+spec:
+  title: Event roster
+  surface: admin
+  requires: { auth: { all: [ctx.admin] } }
+  sql: |
+    SELECT e.id, e.title, e.startsAt AS "startsAt", e.seats_taken AS "seatsTaken",
+      (SELECT json_group_array(json_set('{}', '$.memberName', r.memberName)) FROM registrations r WHERE r.eventId = e.id) AS attendees
+    FROM events e ORDER BY e.startsAt, e.id
+---
 # The member-facing entry: a ref handler checks the event, then runs register-write.
 apiVersion: cms.mantle.aotter.net/v2
 kind: Procedure

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

@@ -105,7 +105,13 @@ await smoke(async ({ call, mcp, signIn, sql, owner, step, logs }) => {
   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 roster = await call("GET", "/admin/api/views/event-roster", { cookie: admin });
+  assert.equal(roster.status, 200, JSON.stringify(roster.body));
+  const attendees = row => (typeof row.attendees === "string" ? JSON.parse(row.attendees) : row.attendees).map(a => a.memberName).sort();
+  for (const row of roster.body.rows) assert.equal(attendees(row).length, row.seatsTaken, JSON.stringify(row));
+  assert.ok(roster.body.rows.some(row => attendees(row).length > 0), JSON.stringify(roster.body.rows));
+  assert.equal((await call("GET", "/admin/api/views/event-roster", { cookie: bob })).status, 403);
+  step("officers see every member's registrations, with names, through Admin's API; and every event with its attendees as one JSON array (event-roster); 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);

package/docs/examples/purchasing/README.md

@@ -14,6 +14,13 @@ that have been waiting too long.
   `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).
+- **A status chosen at submission**: `submit-request` uses `CASE WHEN input.amount <= 100 THEN 'approved' ELSE
+  'submitted' END`. A small request also spends the budget and writes its ledger row in the same program, so
+  `remaining >= 0` refuses all three when it would overspend. Those two statements find the request by
+  `created_at = now()` (the instant of this program) and `NOT EXISTS` a ledger row, so the threshold is written only in
+  the `CASE`. Larger requests wait for an admin. An auto-approved request sends no approval email, and the daily cron
+  orders it from the supplier (it already retries every `approved` request); route small requests through a `ref`
+  handler like `approve-request` if they must be ordered and announced at once.
 - **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`.
@@ -56,11 +63,13 @@ scheme.
 - Need another approval flow? Copy the pattern: a ref Procedure (admin-only, side effects) that wraps a guarded SQL
   write Procedure (one transaction).
 
-## Copy
+## 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
-cp -R node_modules/@aotter/mantle/docs/examples/app-shell/. my-app/
-cp -R node_modules/@aotter/mantle/docs/examples/purchasing/. my-app/
+npx mantle init my-app
+cp -R node_modules/@aotter/mantle/docs/examples/purchasing/. my-app/   # run the example as is
 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

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

@@ -48,10 +48,12 @@ spec:
   title: Budget ledger
   lifecycle: operational
   indexes: [[createdAt, id]]
+  # One row per spending request.
+  uniqueIndexes: [[requestId]]
   uiSchema: { list: { primaryField: department, columns: [amount, remainingAfter, requestId] } }
   schema:
     type: object
-    readOnly: true # written only by approve-request-write
+    readOnly: true # written only by approve-request-write and submit-request
     additionalProperties: false
     required: [requestId, department, amount, remainingAfter]
     properties:
@@ -117,7 +119,7 @@ kind: Procedure
 metadata: { name: submit-request }
 spec:
   title: Submit a purchase request
-  description: Submit a purchase request against an existing department budget.
+  description: Submit a purchase request against an existing department budget; a request of 100 or less is approved at once and spends the budget.
   requires: { auth: { all: [ctx.user] } }
   input:
     type: object
@@ -128,11 +130,26 @@ spec:
       amount: { type: integer, minimum: 1 }
       department: { type: string }
   output: { type: object }
+  # One program. CASE picks the status: up to 100 is approved now, more waits for an admin. The budget and ledger
+  # statements then act only on "the request this program approved": the caller's, created by this program
+  # (created_at = now(), the same instant Mantle writes into created_at), approved, and with no ledger row yet. So the
+  # threshold lives only in the CASE, and remaining >= 0 refuses all three statements when a small request would
+  # overspend. A pending request matches nothing there, which a set form (IN (SELECT ...), INSERT ... SELECT) allows.
   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
+      SELECT input.title, input.amount, b.department, CASE WHEN input.amount <= 100 THEN 'approved' ELSE 'submitted' END
+      FROM budgets b WHERE b.department = input.department
+      RETURNING id, version, requestStatus AS "requestStatus";
+      UPDATE budgets SET remaining = remaining - (SELECT SUM(r.amount) FROM requests r WHERE r.department = budgets.department
+          AND r.author_id = auth.uid() AND r.created_at = now() AND r.requestStatus = 'approved'
+          AND NOT EXISTS (SELECT 1 FROM ledger l WHERE l.requestId = r.id))
+      WHERE department IN (SELECT r.department FROM requests r WHERE r.author_id = auth.uid() AND r.created_at = now()
+          AND r.requestStatus = 'approved' AND NOT EXISTS (SELECT 1 FROM ledger l WHERE l.requestId = r.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.author_id = auth.uid() AND r.created_at = now() AND r.requestStatus = 'approved'
+        AND NOT EXISTS (SELECT 1 FROM ledger l WHERE l.requestId = r.id)
 ---
 # 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.