@aotter/mantle 0.2.1 → 0.2.2-alpha.1

package/docs/examples/README.md

@@ -9,6 +9,8 @@ take the pattern into your own manifests and `src/`. Do not copy an example dire
 | [App shell](./app-shell/README.md) | Better Auth (email OTP, `admin` + `user`), one Worker fetch, Admin, MCP, REST, local acceptance kit. No business manifests. |
 | [Recipes](./recipes/README.md) | Publishing (draft → publish), translations, visitor pages with SEO, JSON-LD, `llms.txt`, Markdown and hreflang alternates, R2 media. |
 | [Club events](./club-events/README.md) | Members who see and change only their own rows, no duplicates, capacity that never oversells, a handler that checks before writing, a member MCP tool, members-only sign-up. |
+| [Posts and revisions](../handbook/guides/revisions.md) | A focused recipe for live editing without downtime: editable revisions, frozen preview, atomic selection, immutable history and rollback. |
+| [Frontend MCP App](./frontend-mcp-app/README.md) | An application-owned interactive MCP App with its own frontend entry and authorized tools. |
 | [Purchasing](./purchasing/README.md) | An internal workflow: guarded status transitions, admin-only approval (Admin and admin MCP), optimistic concurrency, several writes in one transaction, an external API with a signed callback, email and cron. |
 | [Generated website](./generated-web/README.md) | The smallest public site: list and detail pages, REST, `llms.txt`, sitemap, Markdown alternates. |
 
@@ -28,6 +30,8 @@ take the pattern into your own manifests and `src/`. Do not copy an example dire
 | 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 |
+| Edit published content without downtime, preview the exact revision and roll back | [Posts and revisions](../handbook/guides/revisions.md): a stable publishing parent, operational revisions, a same-row seal and atomic pointer switch |
+| An interactive frontend inside an MCP host | [Frontend MCP App](./frontend-mcp-app/README.md): an app-owned renderer and authorized tools |
 | 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` |
@@ -39,5 +43,5 @@ shell's allow-all `src/signup.ts`, unless sign-up should be invite-only. Purchas
 
 Every example uses two roles: `admin` (the admin layer) and `user`.
 
-[Reference service](https://github.com/aotter/mantle/tree/v0.2.1/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.2-alpha.1/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](../handbook/releases/upgrade-0.1-to-0.2.md).

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

@@ -73,11 +73,15 @@ 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). |
+| `public/` | Optional static files. `mantle bundle` copies them into `dist/client`: `public/assets/*` is served at `/assets/*` by the edge without running the Worker; other files (for example `public/favicon.ico`) go through the Worker, which serves them from `ASSETS`. `public/admin` is reserved. Cloudflare's default is `Cache-Control: max-age=0, must-revalidate` with an ETag; for content-hashed files add a `public/_headers` rule with `immutable`, and keep the `/admin/assets/*` rule the build prints. `wrangler dev` rebuilds on changes under `src` and `generated` only: after editing `public/`, save a file in `src` or restart it. |
 | `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`;
-HTTP-only Procedures will keep generating with a warning.
+HTTP-only Procedures will keep generating with a warning. `src/jwks.ts` (installed by `service.ts`) is a temporary
+Workers workaround: it answers the app's own JWKS URL in process when access tokens are verified; delete it with the
+MCP / OAuth blocks, and once Better Auth can take an in-process key source
+([Verifying access tokens on Workers](../../handbook/cloudflare/authentication.md#verifying-access-tokens-on-workers)).
 
 Search for `AGENT:` to find what an app must fill in.
 

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

@@ -15,17 +15,17 @@
     "accept": "node accept.mjs"
   },
   "dependencies": {
-    "@aotter/mantle": "0.2.1",
-    "@aotter/mantle-ui": "0.2.1",
-    "@better-auth/cimd": "1.7.7",
-    "@better-auth/core": "1.7.7",
-    "@better-auth/mcp": "1.7.7",
-    "@better-auth/oauth-provider": "1.7.7",
-    "@better-auth/utils": "0.4.2",
+    "@aotter/mantle": "0.2.2-alpha.1",
+    "@aotter/mantle-ui": "0.2.2-alpha.1",
+    "@better-auth/cimd": "1.7.12",
+    "@better-auth/core": "1.7.12",
+    "@better-auth/mcp": "1.7.12",
+    "@better-auth/oauth-provider": "1.7.12",
+    "@better-auth/utils": "0.5.0",
     "@modelcontextprotocol/ext-apps": "2.0.0",
     "@modelcontextprotocol/server": "2.3.1",
-    "better-auth": "1.7.7",
-    "@aotter/mantle-admin": "0.2.1",
+    "better-auth": "1.7.12",
+    "@aotter/mantle-admin": "0.2.2-alpha.1",
     "react": "19.3.0",
     "react-dom": "19.3.0"
   },

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

@@ -0,0 +1,22 @@
+/**
+ * Answers this Worker's own JWKS URL in process (aotter/mantle#1932). `resolveCaller` verifies OAuth access tokens
+ * with Better Auth's resource client, which fetches `<baseURL>/jwks` by URL: on Workers that is a public-network
+ * round trip back into this same Worker (which then reads D1) before most MCP calls, because Better Auth's key cache
+ * lives per isolate. Only a GET of exactly that URL is answered here, from `auth.api.getJwks()` (public keys only,
+ * the jwt plugin's own rotation and grace rules); Better Auth still verifies the token and its DPoP binding and still
+ * caches the keys by that URL, and Mantle still checks the grant. Any other request, or a URL that does not match
+ * exactly, uses the real `fetch`. The call skips Better Auth's HTTP router, so it shares no rate-limit bucket and needs
+ * no ExecutionContext. A failed key read fails verification as a failed network fetch did.
+ * Delete this module once Better Auth's resource client accepts an in-process key source (better-auth/better-auth#11604).
+ */
+export function withInProcessJwks(outer: typeof fetch, url: string, keys: () => Promise<unknown>): typeof fetch {
+  const inProcess = (input: Parameters<typeof fetch>[0], init?: Parameters<typeof fetch>[1]) => {
+    const request = input instanceof Request ? input : undefined;
+    const method = (init?.method ?? request?.method ?? "GET").toUpperCase();
+    return method === "GET" && (request ? request.url : String(input)) === url
+      ? keys().then(body => Response.json(body))
+      : outer(input, init);
+  };
+  // keeps whatever else the platform's fetch carries (a runtime may add properties to it)
+  return Object.assign(inProcess, outer);
+}

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

@@ -17,6 +17,7 @@ import { mcpAppCatalogues } from "../generated/admin-descriptors.js";
 import type { Handlers } from "../generated/generated.js";
 import { handlers } from "./handlers.js";
 import { appRoutes } from "./routes.js";
+import { withInProcessJwks } from "./jwks.js";
 
 let auth: ReturnType<typeof authLoader<ReturnType<typeof import("./auth.js").createAuth>>> | undefined;
 const authorities = new WeakMap<Request, () => Promise<Caller>>();
@@ -26,7 +27,12 @@ let serveMcpHandler: ReturnType<typeof serveMcp<Env, Handle, Handlers>> | undefi
 const serveRest = rest(options);
 
 export async function fetchService(request: Request, env: Env, context: ExecutionContext): Promise<Response> {
-  auth ??= authLoader(() => import("./auth.js").then(m => m.createAuth(env)));
+  if (!auth) {
+    auth = authLoader(() => import("./auth.js").then(m => m.createAuth(env)));
+    // Once per isolate: Better Auth's JWKS fetch for verifying access tokens stays in process (see src/jwks.ts).
+    const loader = auth;
+    globalThis.fetch = withInProcessJwks(globalThis.fetch, `${env.PUBLIC_ORIGIN}/api/auth/jwks`, async () => (await loader.get()).api.getJwks());
+  }
   const headers = new Headers();
   let authority: Promise<Caller> | undefined;
   // One Caller per request, resolved on first use; every surface below shares it.
@@ -66,6 +72,11 @@ export async function fetchService(request: Request, env: Env, context: Executio
     if (response) return respond(response);
     const shell = await adminShell(request, path => env.ASSETS.fetch(new Request(new URL("/admin/" + path, url), request)));
     if (shell) return shell;
+    // public/ files outside /assets/* (for example /favicon.ico) reach the Worker first; serve them from ASSETS.
+    if (request.method === "GET" || request.method === "HEAD") {
+      const file = await env.ASSETS.fetch(request);
+      if (file.status !== 404) return file;
+    }
     return new Response("Not found", { status: 404, headers: { "cache-control": "no-store" } });
   } catch (error) { return surfaceFailure(error); }
 }

package/docs/examples/app-shell/wrangler.jsonc

@@ -34,7 +34,7 @@
   "assets": {
     "directory": "dist/client",
     "binding": "ASSETS",
-    "run_worker_first": true,
+    "run_worker_first": ["/*", "!/admin/assets/*", "!/assets/*"],
     "html_handling": "none"
   },
   "triggers": {

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

@@ -6,8 +6,8 @@ over MCP. Only members the officers listed in Admin can sign up. Officers see ev
 
 ## Capabilities shown
 
-- **Member-owned rows**: `restrict: { registrations: "author_id = auth.uid()" }` on the `my-registrations` View and the
-  `cancel-registration` Procedure (`manifests/club-events.yaml`). Registrations have no field `scope`, which would hide
+- **Member-owned rows**: `restrict: { registrations: "author_id = auth.uid()" }` on the `my-registrations` View
+  (`manifests/club-events.yaml`); `cancel-registration` pins the caller's row inline instead (see the waiting list). Registrations have no field `scope`, which would hide
   rows from officers too; Admin lists all of them.
 - **No duplicates**: `uniqueIndexes: [[eventId, member]]`. Native `authorId` is not allowed in a unique index, so the
   `register` handler writes `member` from the verified caller (`src/handlers.ts`); a second registration is 409.
@@ -26,6 +26,11 @@ over MCP. Only members the officers listed in Admin can sign up. Officers see ev
 - **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`.
+- **A waiting list**: `register` with `waitlist: true` on a full event writes the member's own row with
+  `waitlisted: true` (`waitlist-write`), which takes no seat. `cancel-registration` has no `restrict`, because
+  promoting the earliest waiter changes another member's row; each statement pins the caller's row with
+  `author_id = auth.uid()` inline, and the final own-row DELETE makes another member's id 409 and rolls back the rest.
+  See `mantle help sql-patterns` ("Change another member's row").
 - **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.
 
@@ -60,6 +65,8 @@ its sign-in is 403 and creates no user row. The officer adds the members in Admi
 they sign in. An officer creates events in Admin. A member registers (seats 3 → 2); registering twice is 409
 and takes no seat; a closed event is 409 and a missing one 404. Another member cannot see or cancel the registration
 (cancel is 409; the row and seats stay). Four members race for a 1-seat event: exactly one succeeds, the rest are 409,
-no seat is left and only one row exists. Cancelling returns the seat. A member registers through the MCP tool.
+no seat is left and only one row exists. Cancelling returns the seat. A member registers through the MCP tool. On a full event, registering is 409 unless the
+member asks for the waiting list; cancelling a seat promotes the earliest waiter (another member's cancel is still 409
+and promotes nobody), leaving the waiting list frees nothing, and with nobody waiting the seat returns.
 The officer sees every registration, with the member's name, through Admin's API; a member gets 403 on Admin.
 Admin cannot write `seats_taken` or lower `capacity` below the seats taken.

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

@@ -37,10 +37,12 @@ spec:
   schema:
     type: object
     readOnly: true
-    required: [eventId, member]
+    required: [eventId, member, waitlisted]
     properties:
       eventId: { type: string, x-mantle-ref: events }
       member: { type: string }
+      # true: on the waiting list, holding no seat. Cancelling a seat promotes the earliest waiter.
+      waitlisted: { type: boolean, title: Waiting }
       # A snapshot of the member's name at sign-up, so officers see who registered (member is an opaque id).
       memberName: { type: string, maxLength: 200 }
 ---
@@ -74,7 +76,7 @@ spec:
   sql: |
     SELECT id, title, startsAt AS "startsAt", capacity - seats_taken AS seats_left, closed FROM events ORDER BY startsAt, id
 ---
-# Only the caller's own rows: restrict narrows registrations to author_id = the caller.
+# Only the caller's own rows, seats and waiting places: restrict narrows registrations to author_id = the caller.
 apiVersion: cms.mantle.aotter.net/v2
 kind: View
 metadata: { name: my-registrations }
@@ -84,7 +86,7 @@ spec:
   requires: { auth: { all: [ctx.user] } }
   restrict: { registrations: "author_id = auth.uid()" }
   sql: |
-    SELECT r.id, r.eventId AS "eventId", e.title, e.startsAt AS "startsAt"
+    SELECT r.id, r.eventId AS "eventId", e.title, e.startsAt AS "startsAt", r.waitlisted
     FROM registrations r JOIN events e ON e.id = r.eventId
     ORDER BY r.created_at DESC, r.id DESC
 ---
@@ -100,7 +102,7 @@ spec:
   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
+      (SELECT json_group_array(json_set('{}', '$.memberName', r.memberName)) FROM registrations r WHERE r.eventId = e.id AND NOT r.waitlisted) 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.
@@ -109,7 +111,7 @@ kind: Procedure
 metadata: { name: register }
 spec:
   title: Register for an event
-  description: Take one seat at a club event for the signed-in member. Fails when the event is closed, full or already registered.
+  description: Take one seat at a club event for the signed-in member, or with waitlist true a place on its waiting list when it is full. Fails when the event is closed, full (without waitlist) or already registered.
   requires: { auth: { all: [ctx.user] } }
   input:
     type: object
@@ -117,6 +119,7 @@ spec:
     additionalProperties: false
     properties:
       eventId: { type: string }
+      waitlist: { type: boolean, description: "When the event is full, join its waiting list instead of failing." }
   output: { type: object }
   handler: { ref: register }
 ---
@@ -136,18 +139,38 @@ spec:
   output: { type: object }
   handler:
     sql: |
-      INSERT INTO registrations (eventId, member, memberName) VALUES (input.eventId, input.member, input.memberName) RETURNING id, eventId AS "eventId";
+      INSERT INTO registrations (eventId, member, memberName, waitlisted) VALUES (input.eventId, input.member, input.memberName, false) RETURNING id, eventId AS "eventId";
       UPDATE events SET seats_taken = seats_taken + 1 WHERE id = input.eventId RETURNING capacity - seats_taken AS seats_left
 ---
-# restrict: another member's registration is invisible here, so the UPDATE matches no row -> CONFLICT, nothing changes.
+# Internal: a place on the waiting list takes no seat. The member's own insert, so author_id is the member.
+apiVersion: cms.mantle.aotter.net/v2
+kind: Procedure
+metadata: { name: waitlist-write }
+spec:
+  requires: { auth: { all: [ctx.user] } }
+  input:
+    type: object
+    required: [eventId, member]
+    properties:
+      eventId: { type: string }
+      member: { type: string }
+      memberName: { type: string, maxLength: 200 }
+  output: { type: object }
+  handler:
+    sql: |
+      INSERT INTO registrations (eventId, member, memberName, waitlisted) VALUES (input.eventId, input.member, input.memberName, true) RETURNING id, eventId AS "eventId", waitlisted
+---
+# No restrict: promoting the next waiter must see and change another member's row. Every statement instead pins the
+# caller's own row inline (author_id = auth.uid()). The DELETE must remove exactly one row, so another member's id is
+# CONFLICT and the whole program rolls back. The seat goes back only when nobody waits; otherwise it passes to the
+# earliest waiter. Both are decided before the promotion changes the waiting list. D1 runs the program serialized.
 apiVersion: cms.mantle.aotter.net/v2
 kind: Procedure
 metadata: { name: cancel-registration }
 spec:
   title: Cancel a registration
-  description: Cancel one of the signed-in member's registrations and return the seat.
+  description: Cancel one of the signed-in member's registrations or waiting places. A freed seat goes to the first member on the waiting list, or back to the event.
   requires: { auth: { all: [ctx.user] } }
-  restrict: { registrations: "author_id = auth.uid()" }
   input:
     type: object
     required: [id]
@@ -157,8 +180,16 @@ spec:
   output: { type: object }
   handler:
     sql: |
-      UPDATE events SET seats_taken = seats_taken - 1 WHERE id = (SELECT eventId FROM registrations WHERE id = input.id) RETURNING capacity - seats_taken AS seats_left;
-      DELETE FROM registrations WHERE id = input.id RETURNING id
+      UPDATE events SET seats_taken = seats_taken - 1
+        WHERE id = (SELECT r.eventId FROM registrations r WHERE r.id = input.id AND r.author_id = auth.uid() AND NOT r.waitlisted)
+          AND NOT EXISTS (SELECT 1 FROM registrations w WHERE w.eventId = events.id AND w.waitlisted)
+        RETURNING capacity - seats_taken AS seats_left;
+      UPDATE registrations SET waitlisted = false
+        WHERE id = (SELECT w.id FROM registrations w JOIN registrations r ON r.eventId = w.eventId
+            WHERE r.id = input.id AND r.author_id = auth.uid() AND NOT r.waitlisted AND w.waitlisted
+            ORDER BY w.created_at, w.id LIMIT 1)
+        RETURNING id AS promoted;
+      DELETE FROM registrations WHERE id = input.id AND author_id = auth.uid() RETURNING id
 ---
 apiVersion: cms.mantle.aotter.net/v2
 kind: Trigger

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

@@ -76,7 +76,7 @@ await smoke(async ({ call, mcp, signIn, sql, owner, step, logs }) => {
   assert.equal(foreign.status, 409, JSON.stringify(foreign.body));
   assert.equal((await sql(`SELECT count(*) AS n FROM registrations WHERE id = '${aliceHike.id}'`))[0].n, 1);
   assert.equal(await seatsOf(hike.id), 2);
-  step("another member neither sees nor cancels it: cancel is 409, the row and seats_left are unchanged (restrict)");
+  step("another member neither sees nor cancels it: cancel is 409, the row and seats_left are unchanged (author_id = auth.uid())");
 
   const racers = [];
   for (const name of ["carol", "dave", "erin", "frank"]) racers.push(await signIn(`${name}@example.test`));
@@ -124,4 +124,34 @@ await smoke(async ({ call, mcp, signIn, sql, owner, step, logs }) => {
   assert.equal(shrunk.status, 409, JSON.stringify(shrunk.body));
   assert.equal(await seatsOf(hike.id), before);
   step("officers edit an event with the whole record; the server-maintained seats_taken is ignored, and capacity below the seats taken is 409");
+
+  await create("Talk", 1);
+  const { Talk: talk } = await events(alice);
+  const carol = racers[0], register = (cookie, body) => call("POST", "/api/registrations", { cookie, body: { eventId: talk.id, ...body } });
+  const cancel = (cookie, id) => call("POST", "/api/registrations/cancel", { cookie, body: { id } });
+  const place = async cookie => (await mine(cookie)).find(r => r.eventId === talk.id);
+  assert.equal((await register(alice)).status, 200);
+  assert.equal((await register(bob)).status, 409);
+  for (const cookie of [bob, carol]) assert.equal((await register(cookie, { waitlist: true })).status, 200);
+  assert.equal(await seatsOf(talk.id), 0);
+  assert.equal(!!(await place(bob)).waitlisted, true);
+  step("a full event is 409, unless the member asks for the waiting list: then a place that takes no seat");
+
+  const seat = await place(alice), bobPlace = await place(bob), carolPlace = await place(carol);
+  assert.equal((await cancel(carol, seat.id)).status, 409);
+  assert.equal(!!(await place(bob)).waitlisted, true);
+  assert.equal((await place(alice)).id, seat.id);
+  step("another member cancelling the seat is still 409 and nobody is promoted: the whole program rolled back");
+
+  assert.equal((await cancel(alice, seat.id)).status, 200);
+  assert.equal(!!(await place(bob)).waitlisted, false);
+  assert.equal(!!(await place(carol)).waitlisted, true);
+  assert.equal(await seatsOf(talk.id), 0);
+  step("cancelling a seat promotes the earliest waiter; the seat passes on and seats_left stays 0");
+
+  assert.equal((await cancel(carol, carolPlace.id)).status, 200);
+  assert.equal(await seatsOf(talk.id), 0);
+  assert.equal((await cancel(bob, bobPlace.id)).status, 200);
+  assert.equal(await seatsOf(talk.id), 1);
+  step("leaving the waiting list frees no seat; cancelling with nobody waiting returns the seat");
 });

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

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

package/docs/examples/frontend-mcp-app/README.md

@@ -0,0 +1,23 @@
+# Application-owned frontend MCP App
+
+This small React entry uses the official ext-apps `useApp` and optional `mantle-ui` presentation. It imports no `mantle-admin`, Provider, Admin hooks or Admin API. The application owns its build and domain page. Keep React and React DOM pinned to one exact version; install the version-matched Core, optional UI, official ext-apps and its peers. Bundle `app.tsx` into a single-file HTML document containing `<div id="root"></div>` with your browser build tool.
+
+Generate the accompanying manifest with `mantle generate <target> generated manifest.yaml`. Register the built HTML through the existing Core contributor, on the frontend endpoint:
+
+```ts
+import { mcp } from "./generated/mcp.js";
+const handle = mcp({
+  db: env => env.DB,
+  caller: request => verifiedCaller(request),
+  apps: { public: { resources: [{
+    uri: "ui://my-tasks/build-1", name: "my-tasks", renders: ["my_tasks"],
+    html: builtHtml,
+  }] } },
+});
+```
+
+`verifiedCaller` is the application's real authentication integration; never derive authority from tool arguments, page state or a user-supplied owner ID. There are no credentials in the HTML. Change the resource URI for a new UI build and update registration consistently. Core owns resource/tool registration and caller enforcement; it neither builds this UI nor imports React. Official ext-apps owns the connection. UI only renders data and invokes callbacks.
+
+`public` names the frontend surface, **not anonymous permission**. `my-tasks` requires a verified user, and the Schema scope limits SQL rows to `auth.uid()`. Admin tools are a separate surface. UI visibility grants no access. The example's load-more calls the same declared View through the host; it does not fetch `/admin/api`. Opening it performs no write. The application reads its consumed row fields and cursor from structured output or a JSON text result; malformed results show an error, a fresh valid result restores the page, and a pending older page cannot append to a newer result. Protocol metadata remains the official client’s responsibility.
+
+Repository acceptance: `bun test packages/mantle/tests/frontend-mcp-app.test.ts` checks generated SQL scope, anonymous/member denials, owner paging and resource linkage. `MANTLE_BROWSER_TESTS=1 MANTLE_TEST_CHROMIUM=/path/to/chrome pnpm --filter @aotter/mantle-admin exec vitest run test/frontend-mcp-app-browser.test.ts` builds this entry without Admin runtime code and renders it in the official AppBridge. The latter command reuses repository browser tooling only; Admin is not an application dependency. This is not an independently installed packed consumer or a real ChatGPT/Claude acceptance result; those remain separate deployment checks.

package/docs/examples/frontend-mcp-app/app.tsx

@@ -0,0 +1,50 @@
+import { useRef, useState } from "react";
+import { createRoot } from "react-dom/client";
+import { useApp } from "@modelcontextprotocol/ext-apps/react";
+import { EntityPreview } from "@aotter/mantle-ui";
+
+interface Rows { rows: { id: string; title: string; version: number }[]; nextCursor?: string }
+const record = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value);
+function readRows(result: { isError?: boolean; structuredContent?: unknown; content: readonly { type: string; text?: string }[] }): Rows {
+  if (result.isError) throw new Error("Unable to read tasks");
+  const output: unknown = result.structuredContent ?? JSON.parse(result.content.find(block => block.type === "text")?.text ?? "");
+  if (!record(output) || !Array.isArray(output.rows) || (output.nextCursor != null && (typeof output.nextCursor !== "string" || !output.nextCursor))) throw new Error("Invalid task result");
+  const rows = output.rows.map((row: unknown) => {
+    if (!record(row) || typeof row.id !== "string" || typeof row.title !== "string" || typeof row.version !== "number" || !Number.isSafeInteger(row.version) || row.version < 1) throw new Error("Invalid task row");
+    return { id: row.id, title: row.title, version: row.version };
+  });
+  return { rows, ...(typeof output.nextCursor === "string" ? { nextCursor: output.nextCursor } : {}) };
+}
+function Frontend() {
+  const generation = useRef(0);
+  const [page, setPage] = useState<Rows>({ rows: [] });
+  const [failure, setFailure] = useState<string | null>(null);
+  const [busy, setBusy] = useState(false);
+  const { app, isConnected, error } = useApp({
+    appInfo: { name: "my-tasks", version: "1" }, capabilities: {},
+    onAppCreated: app => { app.ontoolresult = result => {
+      // This application consumes its declared View result, not Admin metadata.
+      generation.current++;
+      try { setPage(readRows(result)); setFailure(null); }
+      catch { setFailure("Unable to read tasks. Ask for the task list again."); }
+    }; },
+  });
+  if (error || failure) return <p role="alert">{error?.message ?? failure}</p>;
+  if (!isConnected) return <p>Connecting…</p>;
+  const more = async () => {
+    if (!app || busy || !page.nextCursor) return;
+    const opened = generation.current;
+    setBusy(true);
+    try {
+      const result = await app.callServerTool({ name: "my_tasks", arguments: { limit: 1, cursor: page.nextCursor } });
+      const next = readRows(result);
+      if (opened !== generation.current) return;
+      setPage(current => ({ rows: [...current.rows, ...next.rows], ...(next.nextCursor ? { nextCursor: next.nextCursor } : {}) }));
+    } catch { if (opened === generation.current) setFailure("Unable to load more tasks"); }
+    finally { setBusy(false); }
+  };
+  return <main aria-busy={busy}><h1>My tasks</h1>{page.rows.map(row => <EntityPreview key={row.id} entry={{ id: row.id, version: row.version, data: { title: row.title } }} />)}
+    {page.nextCursor && app?.getHostCapabilities()?.serverTools ? <button disabled={busy} onClick={() => { void more(); }}>Load more</button> : null}
+  </main>;
+}
+createRoot(document.getElementById("root")!).render(<Frontend />);

package/docs/examples/frontend-mcp-app/manifest.yaml

@@ -0,0 +1,30 @@
+apiVersion: cms.mantle.aotter.net/v2
+kind: Schema
+metadata: {name: tasks}
+spec:
+  title: Tasks
+  lifecycle: operational
+  scope: owner = auth.uid()
+  indexes: [[owner, id]]
+  schema:
+    type: object
+    required: [owner, title]
+    properties:
+      owner: {type: string}
+      title: {type: string}
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: View
+metadata: {name: my-tasks}
+spec:
+  surface: public
+  requires: {auth: {all: [ctx.user]}}
+  sql: SELECT id, title, version FROM tasks ORDER BY id
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: View
+metadata: {name: administration}
+spec:
+  surface: admin
+  requires: {auth: {all: [ctx.admin]}}
+  sql: SELECT id, title, version FROM tasks ORDER BY id

package/docs/examples/purchasing/README.md

@@ -8,6 +8,11 @@ that have been waiting too long.
 
 ## Capabilities shown
 
+- **Declared relationships**: each request stores a read-only `budgetId` reference to its budget. Each ledger row references
+  both its budget and its request; `uniqueIndexes: [[requestId]]` permits at most one ledger row per request. The ER diagram
+  shows budget-to-request and budget-to-ledger as one-to-many. Department names remain readable snapshots; spending joins
+  stable budget IDs. These references are model metadata, not database foreign keys. Requests and ledger remain available
+  as standalone Admin collections, with the ledger also grouped under its request.
 - **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`,
@@ -65,6 +70,10 @@ scheme.
 
 ## Run it
 
+Existing copies need a native migration for the new `budgetId` fields on requests
+and ledger: backfill them from the existing department budget and request,
+then enforce NOT NULL. Regeneration alone does not migrate an occupied database.
+
 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

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

@@ -25,21 +25,22 @@ metadata: { name: requests }
 spec:
   title: Purchase requests
   lifecycle: operational
-  indexes: [[authorId, createdAt, id], [requestStatus, createdAt, id]]
+  indexes: [[authorId, createdAt, id], [requestStatus, createdAt, id], [budgetId, createdAt, id]]
   searchableFields: [title, department]
   # Sidebar: in the Approvals group (src/admin.tsx), after the queue of requests waiting for a decision.
-  uiSchema: { list: { primaryField: title, columns: [department, amount, requestStatus], filterField: requestStatus }, nav: { group: approvals, order: 2 } }
+  uiSchema: { list: { primaryField: title, columns: [department, amount, requestStatus], filterField: requestStatus }, nav: { standalone: true, 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]
+    required: [title, amount, department, budgetId, requestStatus]
     properties:
       title: { type: string, minLength: 1 }
       amount: { type: integer, minimum: 1 }
       department: { type: string }
+      budgetId: { type: string, x-mantle-ref: budgets, readOnly: true }
       requestStatus: { type: string, enum: [submitted, approved, rejected, ordered, confirmed] }
       supplierOrderId: { type: string }
 ---
@@ -49,18 +50,19 @@ metadata: { name: ledger }
 spec:
   title: Budget ledger
   lifecycle: operational
-  indexes: [[createdAt, id]]
+  indexes: [[createdAt, id], [budgetId, createdAt, id]]
   # One row per spending request.
   uniqueIndexes: [[requestId]]
   searchableFields: [department]
-  uiSchema: { list: { primaryField: department, columns: [amount, remainingAfter, requestId] } }
+  uiSchema: { list: { primaryField: department, columns: [amount, remainingAfter, requestId] }, nav: { parentField: requestId, standalone: true } }
   schema:
     type: object
     readOnly: true # written only by approve-request-write and submit-request
     additionalProperties: false
-    required: [requestId, department, amount, remainingAfter]
+    required: [requestId, budgetId, department, amount, remainingAfter]
     properties:
-      requestId: { type: string }
+      requestId: { type: string, x-mantle-ref: requests }
+      budgetId: { type: string, x-mantle-ref: budgets }
       department: { type: string }
       amount: { type: integer }
       remainingAfter: { type: integer }
@@ -140,17 +142,17 @@ spec:
   # 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, CASE WHEN input.amount <= 100 THEN 'approved' ELSE 'submitted' END
+      INSERT INTO requests (title, amount, department, requestStatus, budgetId)
+      SELECT input.title, input.amount, b.department, CASE WHEN input.amount <= 100 THEN 'approved' ELSE 'submitted' END, b.id
       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
+      UPDATE budgets SET remaining = remaining - (SELECT SUM(r.amount) FROM requests r WHERE r.budgetId = budgets.id
           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()
+      WHERE id IN (SELECT r.budgetId 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
+      INSERT INTO ledger (requestId, budgetId, department, amount, remainingAfter)
+      SELECT r.id, r.budgetId, r.department, r.amount, b.remaining FROM requests r JOIN budgets b ON b.id = r.budgetId
       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)
 ---
@@ -220,9 +222,9 @@ spec:
       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 id = (SELECT r.budgetId FROM requests r WHERE r.id = input.id);
+      INSERT INTO ledger (requestId, budgetId, department, amount, remainingAfter)
+      SELECT r.id, r.budgetId, r.department, r.amount, b.remaining FROM requests r JOIN budgets b ON b.id = r.budgetId
       WHERE r.id = input.id
 ---
 apiVersion: cms.mantle.aotter.net/v2

package/docs/examples/purchasing/smoke.mjs

@@ -185,6 +185,11 @@ try {
     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");
+    const engineeringBudget = (await query("SELECT id FROM budgets WHERE department = 'Engineering'"))[0].id;
+    assert.equal((await query(`SELECT budgetid FROM requests WHERE id = '${laptop}'`))[0].budgetid, engineeringBudget);
+    assert.equal((await query(`SELECT budgetid FROM ledger WHERE requestid = '${pens.id}'`))[0].budgetid, engineeringBudget);
+    assert.equal((await query("SELECT COUNT(*) AS n FROM ledger l JOIN requests r ON r.id = l.requestid WHERE l.budgetid <> r.budgetid"))[0].n, 0);
+    step("requests and ledger rows reference the same stable budget, with at most one ledger row per request");
   }, { 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/wrangler.jsonc

@@ -39,7 +39,7 @@
   "assets": {
     "directory": "dist/client",
     "binding": "ASSETS",
-    "run_worker_first": true,
+    "run_worker_first": ["/*", "!/admin/assets/*", "!/assets/*"],
     "html_handling": "none"
   },
   "triggers": {

package/docs/examples/recipes/wrangler.jsonc

@@ -46,7 +46,7 @@
   "assets": {
     "directory": "dist/client",
     "binding": "ASSETS",
-    "run_worker_first": true,
+    "run_worker_first": ["/*", "!/admin/assets/*", "!/assets/*"],
     "html_handling": "none"
   },
   "triggers": {