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

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

@@ -0,0 +1,57 @@
+/** Application-owned Better Auth; this module loads only on an auth request. */
+import { betterAuth } from "better-auth/minimal";
+import { admin, emailOTP, jwt } from "better-auth/plugins";
+import { createAccessControl } from "better-auth/plugins/access";
+import { defaultStatements } from "better-auth/plugins/admin/access";
+import { mcp } from "@better-auth/mcp";
+import { cimd } from "@better-auth/cimd";
+import { oauthGrantExtension, oauthGrantRevocation } from "@aotter/mantle/auth/oauth";
+import { d1Adapter } from "@aotter/mantle/auth/adapter";
+import { d1BootstrapAdmin } from "@aotter/mantle/auth/identity";
+import { authHardening, hashEmailOtp } from "@aotter/mantle/auth/hardening";
+import { APIError } from "better-auth/api";
+import type { BetterAuthOptions } from "better-auth/types";
+
+const ac = createAccessControl(defaultStatements);
+/** Schema generation (`mantle generate --auth src/auth.ts`) reads these options without constructing Better Auth. */
+export function authOptions(env: Env) {
+  const origin = env.PUBLIC_ORIGIN || "https://example.invalid";
+  const secret = env.BETTER_AUTH_SECRET || "schema-generation-placeholder-secret";
+  // The first verified sign-in with ADMIN_EMAIL becomes the admin while no admin exists.
+  const bootstrap = env.ADMIN_EMAIL ? d1BootstrapAdmin(env.DB, { match: "email", value: env.ADMIN_EMAIL }, () => ({ options: { plugins } })) : async () => {};
+  // Sign-up gate: runs only when Better Auth creates a user (never at schema generation). src/signup.ts loads lazily
+  // because it may import generated code; ADMIN_EMAIL is always allowed so the first officer can sign in.
+  const admit = async (user: { email: string }) => {
+    if (user.email === env.ADMIN_EMAIL?.trim().toLowerCase() || await (await import("./signup.js")).allowSignUp(env, user.email)) return;
+    // Throw rather than return false: email-OTP sign-in does not handle a refused create (it would be a 500).
+    throw new APIError("FORBIDDEN", { message: "Sign-up is limited to invited members." });
+  };
+  const plugins = [
+    // Two roles: admin (the admin layer: Admin console, admin MCP, `surface: admin`) and user (every signed-in member).
+    admin({ defaultRole: "user", adminRoles: ["admin"], ac, roles: { admin: ac.newRole(defaultStatements), user: ac.newRole({ user: [], session: [] }) } }),
+    emailOTP({ storeOTP: { hash: otp => hashEmailOtp(secret, otp) }, sendVerificationOTP: async ({ email, otp }) => {
+      // AGENT: replace with a real sender (see docs/handbook/guides/email.md) before deploying.
+      if (!/^http:\/\/(localhost|127\.0\.0\.1|\[::1\])(:\d+)?$/.test(origin)) throw new Error("Configure a production email sender.");
+      console.log(`${email}: one-time code is ${otp}`);
+    } }),
+    // --- MCP / OAuth (optional): delete these plugins, `disabledPaths` and the MCP block in service.ts if the app has no MCP.
+    jwt({ disableSettingJwtHeader: true }),
+    // Ends a user's OAuth grants (offline ones too) on password reset, admin ban or session revocation.
+    oauthGrantRevocation(),
+    mcp({ loginPage: "/admin/sign-in", consentPage: "/admin/oauth/consent", resource: `${origin}/mcp`, scopes: ["mcp"], extensions: [oauthGrantExtension], allowPublicClientPrelogin: true, clientRegistrationClientSecretExpiration: "90d" }),
+    cimd({ fetchClientMetadataResource: (input, init) => fetch(input, { ...init, redirect: "manual" }), metadataProfile: "mcp-2026-07-28" }),
+    // --- end MCP / OAuth
+  ];
+  return { database: d1Adapter(env.DB), secret, baseURL: origin, basePath: "/api/auth", plugins,
+    // The jwt plugin's cookie-to-JWT endpoint is unused; OAuth tokens come from the provider.
+    disabledPaths: ["/token"],
+    // Trusted client IP header and Better Auth's database rate limiter (3 OTP requests per minute per IP).
+    ...authHardening({ ipAddressHeaders: ["cf-connecting-ip"], baseURL: origin, errorURL: "/admin/sign-in" }),
+    databaseHooks: { user: { create: { before: admit, after: bootstrap }, update: { after: bootstrap } } },
+    session: { storeSessionInDatabase: true }, verification: { storeInDatabase: true },
+  } satisfies BetterAuthOptions;
+}
+export function createAuth(env: Env) {
+  if (!env.BETTER_AUTH_SECRET || !env.PUBLIC_ORIGIN || !env.ADMIN_EMAIL) throw new Error("Authentication setup is incomplete.");
+  return betterAuth(authOptions(env));
+}

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

@@ -0,0 +1,5 @@
+import type { Handlers } from "../generated/generated.js";
+
+// `mantle generate` lists every `handler: { ref }` Procedure it needs; implement each one here.
+// Each handler receives a Store bound to the same caller, so scope and restrict still apply.
+export const handlers: Handlers = {};

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

@@ -0,0 +1,4 @@
+import { fetchService } from "./service.js";
+import { scheduled } from "./schedule.js";
+
+export default { fetch: fetchService, scheduled } satisfies ExportedHandler<Env>;

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

@@ -0,0 +1,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.
+ * 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.
+ */
+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();
+  return undefined;
+}

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

@@ -0,0 +1,8 @@
+/**
+ * Scheduled work is app code: list each cron in wrangler.jsonc `triggers.crons` and branch on `controller.cron`
+ * (`toCloudflareCron` from "@aotter/mantle/cron" converts a standard expression).
+ * AGENT: call the Store or a generated Procedure here; schedules are not manifest Triggers.
+ */
+export async function scheduled(controller: ScheduledController, _env: Env): Promise<void> {
+  throw new Error(`No application schedule runs on '${controller.cron}'`);
+}

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

@@ -0,0 +1,70 @@
+/** One Worker fetch: Better Auth routes, Admin console + API, MCP, generated REST, then the Admin shell. */
+import { authLoader, resolveCaller } from "@aotter/mantle/auth";
+import { authRoutes } from "@aotter/mantle/auth/routes";
+import { withAuthTasks } from "@aotter/mantle/auth/hardening";
+import { checkOrigin, surfaceFailure, type Caller } from "@aotter/mantle/contracts";
+import { admin, adminShell } from "@aotter/mantle-admin/server";
+import { entries } from "@aotter/mantle-admin/server/entries";
+import { siteRoutes } from "@aotter/mantle-admin/server/site";
+import { webmcpRoutes } from "@aotter/mantle-admin/server/webmcp";
+import { adminMcpApps } from "@aotter/mantle-admin/mcp";
+import { mcp as serveMcp } from "@aotter/mantle/mcp";
+import type { Handle } from "@aotter/mantle/driver/d1";
+import { adminBindings } from "../generated/admin-bindings.js";
+import { rest } from "../generated/rest.js";
+import { tools } from "../generated/mcp.js";
+import { mcpAppCatalogues } from "../generated/admin-descriptors.js";
+import type { Handlers } from "../generated/generated.js";
+import { handlers } from "./handlers.js";
+import { appRoutes } from "./routes.js";
+
+let auth: ReturnType<typeof authLoader<ReturnType<typeof import("./auth.js").createAuth>>> | undefined;
+const authorities = new WeakMap<Request, () => Promise<Caller>>();
+const options = { db: (env: Env) => env.DB, caller: (request: Request) => authorities.get(request)!(), handlers };
+let serveAdmin: ReturnType<typeof admin<Env, Handle, Handlers>> | undefined;
+let serveMcpHandler: ReturnType<typeof serveMcp<Env, Handle, Handlers>> | undefined;
+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)));
+  const headers = new Headers();
+  let authority: Promise<Caller> | undefined;
+  // One Caller per request, resolved on first use; every surface below shares it.
+  const caller = () => authority ??= resolveCaller(request, auth!, { audience: `${env.PUBLIC_ORIGIN}/mcp`, responseHeaders: headers }).then(value => { checkOrigin(request, value); return value; });
+  authorities.set(request, caller);
+  const respond = (response: Response) => {
+    if (!headers.has("set-cookie")) return response;
+    // Copy first: some responses (Response.redirect, fetched ones) have immutable headers.
+    const copy = new Response(response.body, response);
+    for (const cookie of headers.getSetCookie()) copy.headers.append("set-cookie", cookie);
+    return copy;
+  };
+  try {
+    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) });
+    if (own) return respond(own);
+    let response: Response | undefined;
+    if (url.pathname === "/admin/api" || url.pathname.startsWith("/admin/api/")) {
+      if (!serveAdmin) {
+        const bindings = adminBindings({ handlers });
+        const adminOptions = { ...options, mcpEndpoints: { public: "/mcp", admin: "/mcp/admin" },
+          identity: { directory: async ({ caller, request, db }: { caller: Caller; request: Request; db: Handle }) => (await import("@aotter/mantle/auth/identity")).d1Identity(db, await auth!.get(), caller, request.headers) } };
+        serveAdmin = admin(bindings.metadata, bindings.views, bindings.operations, { ...adminOptions, developerViews: bindings.developerViews,
+          routes: [...entries(bindings.schemas, bindings.adapter), ...siteRoutes(adminOptions), ...webmcpRoutes(bindings.metadata.webmcp, tools, handlers)] });
+      }
+      response = await serveAdmin(request, env);
+    } else if (/^\/mcp(?:\/admin)?\/*$/.test(url.pathname)) {
+      // --- MCP (optional): delete this branch with the MCP plugins in auth.ts if the app has no MCP.
+      serveMcpHandler ??= serveMcp(tools, { ...options, apps: { admin: adminMcpApps({ catalogue: mcpAppCatalogues.admin }) } });
+      response = await serveMcpHandler(request, env);
+    } else {
+      response = await serveRest(request, env);
+    }
+    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;
+    return new Response("Not found", { status: 404, headers: { "cache-control": "no-store" } });
+  } catch (error) { return surfaceFailure(error); }
+}

package/docs/examples/app-shell/src/sign-in.ts

@@ -0,0 +1,41 @@
+/**
+ * Member sign-in for app pages (Admin has its own at /admin/sign-in). Email one-time code through Better Auth's own
+ * endpoints, then back to `?return=`. A member page calls `signInRedirect(request)` when `await caller()` is anonymous.
+ * AGENT: unstyled on purpose; add the app's styling and copy. Delete this file and its route if the app has no
+ * member pages.
+ */
+export function signInRedirect(request: Request): Response {
+  const url = new URL(request.url);
+  return new Response(null, { status: 303, headers: { location: `/sign-in?return=${encodeURIComponent(url.pathname + url.search)}`, "cache-control": "no-store" } });
+}
+
+export function signInPage(): Response {
+  return new Response(`<!doctype html>
+<html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="robots" content="noindex"><title>Sign in</title>
+<h1>Sign in</h1>
+<form id="email" action="/api/auth/email-otp/send-verification-otp" method="post"><label>Email <input type="email" name="email" autocomplete="email" required></label> <button>Send code</button></form>
+<form id="code" action="/api/auth/sign-in/email-otp" method="post" hidden><label>Code <input name="otp" inputmode="numeric" autocomplete="one-time-code" required></label> <button>Sign in</button></form>
+<p id="status" role="status"></p>
+<script type="module">
+const status = document.getElementById("status"), email = document.getElementById("email"), code = document.getElementById("code");
+// Only same-site paths: an open redirect would hand the fresh session's tab to another site.
+const back = new URLSearchParams(location.search).get("return");
+const target = back && new URL(back, location.origin).origin === location.origin ? back : "/";
+// Better Auth takes JSON: each form keeps its action and method, and the script sends its fields as JSON there.
+const post = (form, body) => fetch(form.action, { method: form.method, headers: { "content-type": "application/json" }, body: JSON.stringify(body) });
+email.onsubmit = async event => {
+  event.preventDefault();
+  const response = await post(email, { email: email.email.value, type: "sign-in" });
+  status.textContent = response.ok ? "We sent a code to your email." : "Could not send a code. Try again later.";
+  code.hidden = !response.ok;
+};
+code.onsubmit = async event => {
+  event.preventDefault();
+  const response = await post(code, { email: email.email.value, otp: code.otp.value });
+  if (response.ok) location.assign(target);
+  else status.textContent = response.status === 403 ? "This email cannot sign up here." : "Wrong or expired code.";
+};
+</script>
+`, { headers: { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" } });
+}

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

@@ -0,0 +1,8 @@
+/**
+ * Who may create an account. Better Auth calls this (through `databaseHooks.user.create.before` in auth.ts) only when a
+ * verified email has no user yet; existing users and ADMIN_EMAIL always sign in. Return false to refuse sign-up (403).
+ * AGENT: for invite-only or members-only sign-up, look the email up here (e.g. an allowlist Schema read through the Store).
+ */
+export async function allowSignUp(_env: Env, _email: string): Promise<boolean> {
+  return true;
+}

package/docs/examples/{reference-service → app-shell}/tsconfig.json

@@ -2,8 +2,10 @@
   "compilerOptions": {
     "target": "ES2022",
     "lib": [
-      "ES2023"
+      "ES2023",
+      "DOM"
     ],
+    "jsx": "react-jsx",
     "module": "ESNext",
     "moduleResolution": "Bundler",
     "strict": true,
@@ -16,7 +18,9 @@
     ]
   },
   "include": [
+    "worker-configuration.d.ts",
     "src/**/*.ts",
-    ".mantle/generated/**/*.ts"
+    "src/**/*.tsx",
+    "generated/**/*.ts"
   ]
 }

package/docs/examples/app-shell/worker-configuration.d.ts

@@ -0,0 +1,22 @@
+/* eslint-disable */
+// Generated by Wrangler by running `wrangler types --include-runtime=false` (hash: 1091fee65f95f8f0fa1b8353572138b4)
+interface __BaseEnv_Env {
+	DB: D1Database;
+	ASSETS: Fetcher;
+	BETTER_AUTH_SECRET: string;
+	PUBLIC_ORIGIN: string;
+	ADMIN_EMAIL: string;
+}
+declare namespace Cloudflare {
+	interface GlobalProps {
+		mainModule: typeof import("./dist/worker/index");
+	}
+	interface Env extends __BaseEnv_Env {}
+}
+interface Env extends __BaseEnv_Env {}
+type StringifyValues<EnvType extends Record<string, unknown>> = {
+	[Binding in keyof EnvType]: EnvType[Binding] extends string ? EnvType[Binding] : string;
+};
+declare namespace NodeJS {
+	interface ProcessEnv extends StringifyValues<Pick<Cloudflare.Env, "BETTER_AUTH_SECRET" | "PUBLIC_ORIGIN" | "ADMIN_EMAIL">> {}
+}

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

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

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

@@ -0,0 +1,60 @@
+# Club events
+
+A club's event sign-up. Officers (the `admin` layer) create events with their seats in the Admin console; signed-in
+members list events, register, and see and cancel only their own registrations, from a page or through their own AI
+over MCP. Only members the officers listed in Admin can sign up. Officers see every registration in Admin. Seats never oversell, even when members race for the last one.
+
+## 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
+  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.
+- **Capacity that never oversells**: officers edit `capacity`; `seats_taken` is a `readOnly` property, so Admin's
+  generic edit never writes it, and `checks: ["seats_taken <= capacity"]` guards both. `register-write` inserts the
+  registration and adds to `seats_taken` in one program, so a full event fails the check and the insert rolls back;
+  `cancel-registration` returns the seat in the same program as the delete.
+- **A `ref` handler that checks before writing**: `register` refuses a missing (404) or closed (409) event, then calls
+  the internal SQL Procedure. It does not pre-check seats: the database check is what holds under concurrency.
+- **Who registered**: the handler stores a `memberName` snapshot from Better Auth's `user` row, since `member` is an
+  opaque id; Admin's registration list shows it.
+- **Members-only sign-up**: officers list members' emails in the `members` Schema in Admin (unique, lower case by a
+  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.
+- **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.
+
+## Combine with
+
+- Need members to see only their own rows? Add a `restrict: { <schema>: "author_id = auth.uid()" }` like `my-registrations`.
+- Need a stock, quota or budget that never goes negative? A `readOnly` counter, a Schema `checks`, and a relative
+  `UPDATE ... SET n = n + 1` in the same Procedure as the write.
+- Need invite-only sign-up? club-events' members allowlist + `src/signup.ts`.
+- Need "one per member"? A handler-written column from `caller.subject` in `uniqueIndexes`.
+
+## Run it
+
+```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/
+cd my-app && pnpm install && pnpm generate && pnpm types && pnpm check
+cp .dev.vars.example .dev.vars && pnpm db:init && pnpm dev
+pnpm smoke
+```
+
+Members use `GET /api/views/events`, `GET /api/views/my-registrations`, `POST /api/registrations { eventId }` and
+`POST /api/registrations/cancel { id }`. AGENT: build the member pages in `src/routes.ts` (the shell's Admin console is
+for officers only).
+
+## What `pnpm smoke` proves
+
+Anonymous calls are 401. `ADMIN_EMAIL` signs in with an empty members list; an email not on the list gets a code but
+its sign-in is 403 and creates no user row. The officer adds the members in Admin (a mixed-case email is refused), and
+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.
+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

@@ -0,0 +1,225 @@
+# Club events: officers (admin) create events in Admin; signed-in members register and cancel their own seats.
+apiVersion: cms.mantle.aotter.net/v2
+kind: Schema
+metadata: { name: events }
+spec:
+  title: Events
+  lifecycle: operational
+  # Registering adds to seats_taken in the same program as the insert: past capacity the check fails and the insert rolls back.
+  # It also refuses an officer lowering capacity below the seats already taken.
+  checks: ["seats_taken <= capacity"]
+  indexes: [[startsAt, id]]
+  uiSchema: { list: { primaryField: title, columns: [startsAt, capacity, seats_taken, closed] } }
+  schema:
+    type: object
+    required: [title, startsAt, capacity, closed]
+    properties:
+      title: { type: string, minLength: 1 }
+      startsAt: { type: string, format: date-time }
+      capacity: { type: integer, minimum: 0, title: Capacity }
+      # readOnly: server-maintained. Admin's generic create/edit never writes it; only register/cancel change it.
+      seats_taken: { type: integer, minimum: 0, default: 0, readOnly: true, title: Seats taken }
+      closed: { type: boolean, default: false }
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Schema
+metadata: { name: registrations }
+spec:
+  title: Registrations
+  lifecycle: operational
+  # No `scope` here: a field scope would hide rows from officers too. Members are narrowed by `restrict` below.
+  # `member` is written by the register handler from the caller; native authorId cannot be in a unique index.
+  uniqueIndexes: [[eventId, member]]
+  indexes: [[authorId, createdAt, id]]
+  # Officers read registrations in Admin; generic edits would bypass seats_taken, so writes go through the Procedures.
+  uiSchema: { list: { primaryField: eventId, columns: [memberName] } }
+  schema:
+    type: object
+    readOnly: true
+    required: [eventId, member]
+    properties:
+      eventId: { type: string, x-mantle-ref: events }
+      member: { type: string }
+      # 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 }
+---
+# The sign-up allowlist: officers add members in Admin; src/signup.ts lets only these emails create an account.
+# No View or Trigger reads it, so it stays out of the public API and MCP.
+apiVersion: cms.mantle.aotter.net/v2
+kind: Schema
+metadata: { name: members }
+spec:
+  title: Members
+  lifecycle: operational
+  uniqueIndexes: [[email]]
+  # Better Auth lowercases emails; the check refuses a mixed-case entry that would never match.
+  checks: ["email = lower(email)"]
+  uiSchema: { list: { primaryField: email, columns: [name] } }
+  schema:
+    type: object
+    required: [email]
+    properties:
+      email: { type: string, format: email, maxLength: 254, title: Email }
+      name: { type: string, maxLength: 200, title: Name }
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: View
+metadata: { name: events }
+spec:
+  surface: public
+  description: Upcoming club events with the seats still available.
+  requires: { auth: { all: [ctx.user] } }
+  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.
+apiVersion: cms.mantle.aotter.net/v2
+kind: View
+metadata: { name: my-registrations }
+spec:
+  surface: public
+  description: The signed-in member's registrations.
+  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"
+    FROM registrations r JOIN events e ON e.id = r.eventId
+    ORDER BY r.created_at DESC, r.id DESC
+---
+# The member-facing entry: a ref handler checks the event, then runs register-write.
+apiVersion: cms.mantle.aotter.net/v2
+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.
+  requires: { auth: { all: [ctx.user] } }
+  input:
+    type: object
+    required: [eventId]
+    additionalProperties: false
+    properties:
+      eventId: { type: string }
+  output: { type: object }
+  handler: { ref: register }
+---
+# Internal (no Trigger): one program, so a failed seat check rolls back the insert too.
+apiVersion: cms.mantle.aotter.net/v2
+kind: Procedure
+metadata: { name: register-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) VALUES (input.eventId, input.member, input.memberName) 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.
+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.
+  requires: { auth: { all: [ctx.user] } }
+  restrict: { registrations: "author_id = auth.uid()" }
+  input:
+    type: object
+    required: [id]
+    additionalProperties: false
+    properties:
+      id: { type: string }
+  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
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Trigger
+metadata: { name: register-http }
+spec:
+  source: { kind: http, method: POST, path: /api/registrations }
+  target: { procedure: register }
+---
+# "Your AI" registers for the member over the member MCP endpoint (/mcp) with the member's own sign-in.
+apiVersion: cms.mantle.aotter.net/v2
+kind: Trigger
+metadata: { name: register-mcp }
+spec:
+  source: { kind: mcp, surface: public }
+  target: { procedure: register }
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Trigger
+metadata: { name: cancel-registration-http }
+spec:
+  source: { kind: http, method: POST, path: /api/registrations/cancel }
+  target: { procedure: cancel-registration }
+---
+# Officers add records through declared Procedures: operational collections have no generic create in Admin.
+# collectionAction puts the Procedure's button and input form in that collection's list header; the admin MCP
+# Trigger is what makes it an Admin operation (and lets the officers' AI do the same).
+apiVersion: cms.mantle.aotter.net/v2
+kind: Procedure
+metadata: { name: create-event }
+spec:
+  title: New event
+  description: Create a club event with its capacity.
+  requires: { auth: { all: [ctx.admin] } }
+  uiSchema: { collectionAction: events }
+  input:
+    type: object
+    required: [title, startsAt, capacity]
+    additionalProperties: false
+    properties:
+      title: { type: string, minLength: 1, maxLength: 200, title: Title }
+      startsAt: { type: string, format: date-time, title: Starts at }
+      capacity: { type: integer, minimum: 1, title: Capacity }
+  output: { type: object }
+  handler:
+    sql: |
+      INSERT INTO events (title, startsAt, capacity, closed, seats_taken) VALUES (input.title, input.startsAt, input.capacity, false, 0) RETURNING id
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Procedure
+metadata: { name: add-member }
+spec:
+  title: Add a member
+  description: Let an email sign up as a club member.
+  requires: { auth: { all: [ctx.admin] } }
+  uiSchema: { collectionAction: members }
+  input:
+    type: object
+    required: [email]
+    additionalProperties: false
+    properties:
+      email: { type: string, format: email, maxLength: 254, title: Email }
+      name: { type: string, maxLength: 200, title: Name }
+  output: { type: object }
+  handler:
+    # Better Auth lowercases emails, so the list stores them lowercased too.
+    sql: |
+      INSERT INTO members (email, name) VALUES (lower(input.email), input.name) RETURNING id
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Trigger
+metadata: { name: create-event-admin }
+spec:
+  source: { kind: mcp, surface: admin }
+  target: { procedure: create-event }
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Trigger
+metadata: { name: add-member-admin }
+spec:
+  source: { kind: mcp, surface: admin }
+  target: { procedure: add-member }