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

package/docs/examples/app-shell/pnpm-workspace.yaml

@@ -0,0 +1,8 @@
+# pnpm 10+ blocks dependency build scripts by default; wrangler needs these two. `packages` keeps pnpm 9 happy.
+packages: ["."]
+allowBuilds:
+  esbuild: true
+  workerd: true
+onlyBuiltDependencies:
+  - esbuild
+  - workerd

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

@@ -0,0 +1,100 @@
+// Local acceptance kit: runs the app under `wrangler dev --local` on a fresh D1 and drives it over HTTP like a browser or agent.
+// Usage in smoke.mjs:
+//   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" } });
+import assert from "node:assert/strict";
+import { execFile, spawn, spawnSync } from "node:child_process";
+import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+
+const database = "mantle-app"; // wrangler.jsonc d1_databases[0].database_name
+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";
+  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"] : [])]) {
+    const applied = spawnSync("pnpm", ["exec", "wrangler", "d1", "execute", database, "--local", "--persist-to", state, "--file", file], { encoding: "utf8", env });
+    assert.equal(applied.status, 0, applied.stdout + applied.stderr);
+  }
+  const wrangler = spawn("pnpm", ["exec", "wrangler", "dev", "--local", "--ip", "127.0.0.1", "--port", String(port), "--inspector-port", "0", "--persist-to", state, "--test-scheduled",
+    "--var", `PUBLIC_ORIGIN:${origin}`, "--var", `ADMIN_EMAIL:${owner}`, "--var", "BETTER_AUTH_SECRET:local-smoke-secret-0123456789abcdef", ...Object.entries(vars).flatMap(([name, value]) => ["--var", `${name}:${value}`])],
+  // its own process group: pnpm does not pass a signal on to wrangler and workerd
+  { env: { ...env, CI: "1" }, stdio: ["ignore", "pipe", "pipe"], detached: true });
+  let logs = "";
+  wrangler.stdout.on("data", chunk => { logs += chunk; });
+  wrangler.stderr.on("data", chunk => { logs += chunk; });
+
+  // Better Auth limits OTP requests to 3 per minute per IP: each signed-in user gets its own client IP.
+  const ips = new Map();
+  const ipOf = email => ips.get(email) ?? (ips.set(email, `203.0.113.${ips.size + 1}`), ips.get(email));
+  /** method, path, { cookie, body, ip, headers } -> { status, body, headers } */
+  const call = async (method, path, { cookie, body, ip, headers = {} } = {}) => {
+    const response = await fetch(`${origin}${path}`, { method, headers: { "content-type": "application/json", origin, ...(cookie ? { cookie } : {}), ...(ip ? { "cf-connecting-ip": ip } : {}), ...headers },
+      ...(body === undefined ? {} : { body: typeof body === "string" ? body : JSON.stringify(body) }) });
+    const text = await response.text();
+    let parsed; try { parsed = text ? JSON.parse(text) : null; } catch { parsed = text; }
+    return { status: response.status, body: parsed, headers: response.headers };
+  };
+  /** MCP tools/list (no name) or tools/call on /mcp or /mcp/admin. */
+  const mcp = async (path, cookie, name, args) => {
+    const response = await fetch(`${origin}${path}`, { method: "POST", headers: { "content-type": "application/json", origin, accept: "application/json, text/event-stream", ...(cookie ? { cookie } : {}) },
+      body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: name ? "tools/call" : "tools/list", params: name ? { name, arguments: args } : {} }) });
+    const text = await response.text(), data = text.split("\n").find(line => line.startsWith("data:"));
+    return { status: response.status, body: data ? JSON.parse(data.slice(5)) : text ? JSON.parse(text) : null };
+  };
+  /** Console email OTP: request a code, read it from the wrangler log, sign in; returns the cookie header. */
+  const signIn = async email => {
+    const before = logs.length, ip = ipOf(email);
+    assert.equal((await call("POST", "/api/auth/email-otp/send-verification-otp", { body: { email, type: "sign-in" }, ip })).status, 200);
+    let code;
+    for (let i = 0; i < 40 && !code; i++) {
+      code = new RegExp(`${email.replace(/[.+]/g, "\\$&")}[\\s\\S]*?one-time code is (\\d{6})`).exec(logs.slice(before))?.[1];
+      if (!code) await new Promise(resolve => setTimeout(resolve, 100));
+    }
+    assert.ok(code, `no one-time code for ${email} in the log`);
+    const signed = await call("POST", "/api/auth/sign-in/email-otp", { body: { email, otp: code }, ip });
+    assert.equal(signed.status, 200, JSON.stringify(signed.body));
+    return signed.headers.getSetCookie().map(c => c.split(";")[0]).join("; ");
+  };
+  /** Run SQL against the local D1 (inspect state or inject a failure). Async, so the server's sockets stay serviced. */
+  const sql = async command => {
+    const { stdout } = await promisify(execFile)("pnpm", ["exec", "wrangler", "d1", "execute", database, "--local", "--persist-to", state, "--command", command, "--json"], { encoding: "utf8", env });
+    return JSON.parse(stdout)[0].results;
+  };
+  /** Fire the Worker's scheduled() handler (wrangler dev --test-scheduled). */
+  const cron = async expression => (await fetch(`${origin}/cdn-cgi/local/scheduled?cron=${encodeURIComponent(expression)}`)).status;
+  /** Wait until the wrangler log (console.log from the Worker, e.g. ConsoleEmailSender) matches. */
+  const waitForLog = async pattern => {
+    for (let i = 0; i < 40; i++) { if (pattern.test(logs)) return; await new Promise(resolve => setTimeout(resolve, 100)); }
+    assert.fail(`no log line matching ${pattern}`);
+  };
+  const step = name => console.log(`ok - ${name}`);
+  try {
+    for (let attempt = 0; ; attempt++) {
+      if (wrangler.exitCode !== null) throw new Error(`wrangler exited ${wrangler.exitCode}`);
+      try { await fetch(`${origin}/api/auth/ok`); break; } catch { /* starting */ }
+      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));
+    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 });
+  }
+}

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

@@ -0,0 +1,10 @@
+import type { AdminExtension, AdminNavGroup } from "@aotter/mantle-admin/server/extensions";
+
+/**
+ * Admin presentation, read by `mantle generate --admin-extensions src/admin.ts` (no runtime code).
+ * AGENT: to group the sidebar for how staff work, declare groups here and place Schemas and admin Views in them with
+ * `uiSchema.nav: { group, order, hidden }` (docs/handbook/guides/native-admin.md, "Sidebar"). Built-in groups need no
+ * declaration: content, operations, reports, more. Admin extensions also go here.
+ */
+export const navGroups: AdminNavGroup[] = [];
+export const adminExtensions: AdminExtension[] = [];

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

@@ -0,0 +1,55 @@
+/** 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 } 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 three plugins, `disabledPaths` and the MCP block in service.ts if the app has no MCP.
+    jwt({ disableSettingJwtHeader: true }),
+    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, html: async () => (await import("@aotter/mantle-admin/mcp-app")).mantleAppHtml }) } });
+      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("/" + 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

@@ -16,7 +16,8 @@
     ]
   },
   "include": [
+    "worker-configuration.d.ts",
     "src/**/*.ts",
-    ".mantle/generated/**/*.ts"
+    "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: a915f363a88b93fd3b80de7926237051)
+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/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,61 @@
+{
+  "$schema": "node_modules/wrangler/config-schema.json",
+  "name": "mantle-app",
+  "main": "dist/index.js",
+  "compatibility_date": "2026-09-01",
+  "compatibility_flags": [
+    "nodejs_compat"
+  ],
+  "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": "node_modules/@aotter/mantle-admin/dist/admin",
+    "binding": "ASSETS",
+    "run_worker_first": true,
+    "html_handling": "none"
+  },
+  "triggers": {
+    "crons": []
+  },
+  "no_bundle": true,
+  "find_additional_modules": true,
+  "base_dir": "dist",
+  "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.