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

package/dist/usecase/validation.js

@@ -1,7 +1,98 @@
-import { q } from "../domain/entry.js";
+/** Compile boundary checks into each operation; no schema enters the request bundle. */
+import { INPUT_RULE_KEYWORDS, lookupLocalRef as lookup, rootRefChain } from "../build/compiler.js";
+import { literal, q } from "../domain/entry.js";
 import { publishingInput } from "./publishing.js";
+import { equal } from "../kernel/validation.js";
 const pointer = (key) => key.replace(/~/g, "~0").replace(/\//g, "~1");
-const supported = new Set("$defs $ref $schema $id type nullable properties required additionalProperties items enum format pattern minLength maxLength minimum maximum exclusiveMinimum exclusiveMaximum multipleOf minItems maxItems title description default readOnly writeOnly examples deprecated x-mantle-ref x-mcp-hint".split(" "));
+const supported = new Set([..."$defs $ref $schema $id type nullable properties required additionalProperties items enum const format pattern minLength maxLength minimum maximum exclusiveMinimum exclusiveMaximum multipleOf minItems maxItems title description default readOnly writeOnly examples deprecated x-mantle-ref x-mcp-hint".split(" "), ...INPUT_RULE_KEYWORDS]);
+const shapes = "see docs/handbook/reference/surface.md";
+// YAML .inf and .nan parse to numbers that JSON writes as null.
+const finite = (value) => typeof value === "number" ? Number.isFinite(value) : !!value && typeof value === "object" ? Object.values(value).every(finite) : true;
+const has = (key) => `Object.hasOwn(object,${q(key)})`;
+const exactly = (value, keys) => !!value && typeof value === "object" && !Array.isArray(value) && Object.keys(value).sort().join(" ") === keys;
+/**
+ * An object schema's rules, each failing `when` (JavaScript on `object`) with its sentence at the missing field `key`, or the
+ * reason a rule has an unsupported shape.
+ */
+function rules(schema) {
+    const declared = (names) => Array.isArray(names) && names.length > 0 && names.every(name => typeof name === "string" && Object.hasOwn(schema.properties ?? {}, name));
+    const list = (names) => names.map(name => `'${name}'`).join(" and ");
+    const found = [], { dependentRequired: dependent, anyOf, if: condition, then, else: otherwise } = schema;
+    if (dependent !== undefined) {
+        if (!dependent || typeof dependent !== "object" || Array.isArray(dependent) || !declared(Object.keys(dependent)) || !Object.values(dependent).every(declared))
+            return `dependentRequired maps declared properties to lists of declared properties; ${shapes}.`;
+        for (const [key, names] of Object.entries(dependent))
+            for (const name of names)
+                found.push({ when: `${has(key)} && !${has(name)}`, key: name, message: `'${name}' is required when '${key}' is present.` });
+    }
+    if (anyOf !== undefined) {
+        if (!Array.isArray(anyOf) || !anyOf.length || !anyOf.every(branch => exactly(branch, "required") && declared(branch.required)))
+            return `anyOf is supported only as branches of exactly { required: [declared properties] }; ${shapes}.`;
+        const branches = anyOf.map(branch => branch.required);
+        found.push({ when: `!(${branches.map(names => names.map(has).join(" && ")).join(" || ")})`, message: `At least one of ${branches.map(names => names.length > 1 ? `(${list(names)})` : list(names)).join(", ")} is required.` });
+    }
+    if (condition !== undefined || then !== undefined || otherwise !== undefined) {
+        const [key] = exactly(condition, "properties required") ? Object.keys(condition.properties) : [];
+        const value = key === undefined ? undefined : condition.properties[key];
+        // Without required: [key], an absent key satisfies `if`.
+        if (key === undefined || !exactly(condition.properties, key) || !exactly(value, "const") || !(["string", "boolean"].includes(typeof value.const) || Number.isFinite(value.const) || value.const === null) || q(condition.required) !== q([key]) || !declared([key]))
+            return `if is supported only as exactly { properties: { <field>: { const: <string, finite number, boolean or null> } }, required: [<field>] }, so an absent field does not satisfy it; ${shapes}.`;
+        if (then === undefined && otherwise === undefined || [then, otherwise].some(branch => branch !== undefined && !(exactly(branch, "required") && declared(branch.required))))
+            return `then and else are supported only as exactly { required: [declared properties] } after an if; ${shapes}.`;
+        const met = `${has(key)} && object[${q(key)}] === ${q(value.const)}`;
+        for (const name of then?.required ?? [])
+            found.push({ when: `${met} && !${has(name)}`, key: name, message: `'${name}' is required when '${key}' is ${q(value.const)}.` });
+        for (const name of otherwise?.required ?? [])
+            found.push({ when: `!(${met}) && !${has(name)}`, key: name, message: `'${name}' is required unless '${key}' is ${q(value.const)}.` });
+    }
+    return found;
+}
+/** Whether an input schema accepts `{}`: a list View is read with no input, so web indexes need this. */
+export function acceptsEmpty(input) {
+    if (input === undefined)
+        return true;
+    // Validation applies a root `$ref`'s target too, so each schema along the chain must accept `{}`; an unresolved or cyclic chain does not.
+    // dependentRequired needs a present key; an if needs its field, so `{}` meets only an else. An enum or const must admit `{}`.
+    return rootRefChain(input)?.every(schema => !schema.required?.length && schema.anyOf === undefined && !schema.else?.required?.length
+        && (schema.enum === undefined || schema.enum.some(option => equal({}, option))) && (schema.const === undefined || equal({}, schema.const)) && (schema.type === undefined || [schema.type].flat().includes("object"))) ?? false;
+}
+/**
+ * An input schema as an AI tool catalogue advertises it: some model APIs refuse rules (a root `anyOf`, `if`), so each rule leaves
+ * the schema and becomes a sentence of the description.
+ */
+export function advertised(input, description) {
+    if (!input)
+        return { inputSchema: input, description };
+    const sentences = [], copy = JSON.parse(q(input));
+    const strip = (node, at) => {
+        if (!node || typeof node !== "object")
+            return;
+        const schema = node;
+        // An MCP View tool keeps each rule set of its root `$ref` chain as an `allOf` branch over the merged properties.
+        const branches = Array.isArray(schema.allOf) ? schema.allOf : [];
+        for (const branch of [schema, ...branches.map(branch => ({ ...branch, properties: schema.properties }))]) {
+            const found = rules(branch);
+            if (typeof found !== "string")
+                for (const rule of found)
+                    sentences.push(at ? `In '${at}': ${rule.message}` : rule.message);
+        }
+        if (branches.length && branches.every(branch => Object.keys(branch).every(key => INPUT_RULE_KEYWORDS.includes(key))))
+            delete schema.allOf;
+        for (const keyword of INPUT_RULE_KEYWORDS)
+            delete schema[keyword];
+        for (const [key, child] of Object.entries((schema.properties ?? {})))
+            strip(child, `${at}/${key}`);
+        for (const [key, child] of Object.entries((schema.$defs ?? {})))
+            strip(child, `#/$defs/${key}`);
+        strip(schema.items, `${at}/*`);
+        strip(schema.additionalProperties, `${at}/*`);
+    };
+    strip(copy, "");
+    if (!sentences.length)
+        return { inputSchema: input, description };
+    const text = sentences.join(" ");
+    return { inputSchema: copy, description: typeof description === "string" ? `${description} ${text}` : Object.fromEntries(Object.entries(description).map(([locale, value]) => [locale, `${value} ${text}`])) };
+}
 const bounds = [
     ["string", "[...value].length", { minLength: "<", maxLength: ">" }],
     ["number", "value", { minimum: "<", maximum: ">", exclusiveMinimum: "<=", exclusiveMaximum: ">=" }],
@@ -23,21 +114,13 @@ export function emitValidation(plan, refuse = (path, message) => { throw Error(`
             // Only a local `$ref`, or more than 100 nested objects and arrays, can reach the nesting limit: only then is `depth` passed.
             const recursive = json.includes('"$ref"') || json.split(/[[{]/).length > 101, depth = recursive ? ",depth+1" : "";
             // Identical bodies share one function.
-            const nodes = new Map(), bodies = new Map(), functions = [], formats = new Set();
+            const nodes = new Map(), bodies = new Map(), functions = [], formats = new Set(), patterns = new Map();
             let equality = false;
             const resolve = (ref) => {
-                let value = root;
-                try {
-                    if (typeof ref !== "string" || !ref.startsWith("#/"))
-                        throw Error();
-                    for (const key of decodeURIComponent(ref.slice(2)).split("/").map(key => key.replace(/~1/g, "/").replace(/~0/g, "~")))
-                        value = value && typeof value === "object" && Object.hasOwn(value, key) ? value[key] : undefined;
-                    if (value && typeof value === "object")
-                        return value;
-                }
-                catch { }
-                refuse(base, "Input ref must be a valid local JSON pointer.");
-                return {};
+                const found = lookup(root, ref);
+                if (!found)
+                    refuse(base, "Input ref must be a valid local JSON pointer.");
+                return found ?? {};
             };
             const emit = (schema) => {
                 if (nodes.has(schema))
@@ -63,9 +146,25 @@ export function emitValidation(plan, refuse = (path, message) => { throw Error(`
                 const only = types.length === 1 ? types[0] : undefined;
                 const guard = (type, test = `(${condition(type)})`) => only === type || type === "number" && only === "integer" ? "" : test + " && ";
                 if (schema.enum) {
+                    if (!finite(schema.enum))
+                        refuse(base, "Input enum numbers must be finite; JSON has no Infinity or NaN.");
+                    equality = true;
+                    check(`!${literal(schema.enum)}.some(option=>equal(value,option))`, "Value is not in enum.");
+                }
+                if (schema.const !== undefined) {
+                    if (!finite(schema.const))
+                        refuse(base, "Input const numbers must be finite; JSON has no Infinity or NaN.");
                     equality = true;
-                    check(`!${q(schema.enum)}.some(option=>equal(value,option))`, "Value is not in enum.");
+                    check(`!equal(value,${literal(schema.const)})`, "Value violates const.");
                 }
+                for (const key of ["minLength", "maxLength", "minItems", "maxItems"])
+                    if (schema[key] !== undefined && (!Number.isSafeInteger(schema[key]) || schema[key] < 0))
+                        refuse(base, `${key} must be a non-negative safe integer.`);
+                for (const key of ["minimum", "maximum", "exclusiveMinimum", "exclusiveMaximum"])
+                    if (schema[key] !== undefined && (typeof schema[key] !== "number" || !Number.isFinite(schema[key])))
+                        refuse(base, `${key} must be a finite number.`);
+                if (schema.multipleOf !== undefined && (typeof schema.multipleOf !== "number" || !Number.isFinite(schema.multipleOf) || schema.multipleOf <= 0))
+                    refuse(base, "multipleOf must be a positive finite number.");
                 for (const [type, measure, keywords] of bounds)
                     for (const [key, operator] of Object.entries(keywords))
                         if (schema[key] !== undefined)
@@ -79,13 +178,17 @@ export function emitValidation(plan, refuse = (path, message) => { throw Error(`
                     catch {
                         refuse(base, "Input pattern is not a valid regular expression.");
                     }
-                    check(`${guard("string", 'typeof value === "string"')}!new RegExp(${q(schema.pattern)}).test(value)`, "String does not match pattern.");
+                    if (!patterns.has(schema.pattern))
+                        patterns.set(schema.pattern, `pattern${patterns.size}`);
+                    check(`${guard("string", 'typeof value === "string"')}!${patterns.get(schema.pattern)}.test(value)`, "String does not match pattern.");
                 }
                 if (schema.format) {
                     if (schema.format === "email")
                         check(`${guard("string", 'typeof value === "string"')}!/^[^\\s@]+@[^\\s@]+$/u.test(value)`, "Expected an email with one @, non-empty local and domain parts, and no whitespace.");
+                    else if (schema.format === "uri")
+                        lines.push(`${only === "string" ? "" : 'if (typeof value === "string") '}{ let url: URL | undefined; try { url = new URL(value); } catch {} if (url?.protocol !== "http:" && url?.protocol !== "https:") fail(path, "Expected an absolute http or https URL."); }`);
                     else if (!["date", "date-time"].includes(schema.format))
-                        refuse(base, `Generated input validation does not support format '${schema.format}'.`);
+                        refuse(base, `Generated input validation does not support format '${schema.format}'; ${shapes} for the supported formats.`);
                     else {
                         const scalar = schema.format === "date" ? "encodeDate" : "encodeTimestamptz";
                         formats.add(scalar);
@@ -105,6 +208,12 @@ export function emitValidation(plan, refuse = (path, message) => { throw Error(`
                         object.push(`if (Object.hasOwn(object,${q(key)})) ${fn}(object[${q(key)}],path+${q("/" + pointer(key))}${depth});`);
                 if (schema.additionalProperties === false || typeof schema.additionalProperties === "object")
                     object.push(`for (const key of Object.keys(object)) if (!(${q(Object.keys(schema.properties ?? {}))} as readonly string[]).includes(key)) { const childPath = path+"/"+key.replace(/~/g,"~0").replace(/\\//g,"~1"); ${schema.additionalProperties === false ? 'fail(childPath,"Unknown field.");' : `${emit(schema.additionalProperties)}(object[key],childPath${depth});`} }`);
+                const checked = rules(schema);
+                if (typeof checked === "string")
+                    refuse(base, checked);
+                else
+                    for (const rule of checked)
+                        object.push(`if (${rule.when}) fail(path${rule.key === undefined ? "" : `+${q("/" + pointer(rule.key))}`}, ${q(rule.message)});`);
                 if (object.length)
                     lines.push(`${only === "object" ? "" : `if (${condition("object")}) `}{ const object = value as Record<string,unknown>;\n${object.join("\n")}\n}`);
                 const body = lines.join("\n");
@@ -123,7 +232,7 @@ export function emitValidation(plan, refuse = (path, message) => { throw Error(`
                 return type === "boolean" || type === "integer" || type === "number" ? [key, type] : [key];
             }) : undefined;
             const helpers = [...(functions.length ? ["fail"] : []), ...(equality ? ["equal"] : []), ...(fields ? ["query as read"] : [])];
-            const code = `${helpers.length ? `import { ${helpers.join(", ")} } from "@aotter/mantle/validation";\n` : ""}${formats.size ? `import { ${[...formats].join(", ")} } from "@aotter/mantle/scalars";\n` : ""}${functions.join("\n")}
+            const code = `${helpers.length ? `import { ${helpers.join(", ")} } from "@aotter/mantle/validation";\n` : ""}${formats.size ? `import { ${[...formats].join(", ")} } from "@aotter/mantle/scalars";\n` : ""}${[...patterns].map(([pattern, name]) => `const ${name} = new RegExp(${q(pattern)});\n`).join("")}${functions.join("\n")}
 export function validate(raw:unknown):Record<string,unknown> { ${validate}(raw,${q(base)}${recursive ? ",0" : ""}); return raw as Record<string,unknown>; }
 ${fields ? `export const query = (params:URLSearchParams) => read(params, validate, ${q(`${kind}/${name}`)}, ${q(fields)});\n` : ""}`;
             files[file] = code;

package/dist/usecase/web.js

@@ -1,12 +1,13 @@
 import { databaseImport, q } from "../domain/entry.js";
 import { authLines, conversions } from "../domain/input.js";
+import { acceptsEmpty } from "./validation.js";
 export function emitWeb(plan, lowered, target) {
     const views = Object.entries(plan.views).filter(([, v]) => v.surface === "public");
     const table = views.map(([name, v], i) => {
         const binds = lowered.views[name]?.public?.binds ?? [], convert = conversions(v.input?.properties, binds, target);
         const booleans = Object.keys(v.input?.properties ?? {}).filter(field => binds.some(b => b.k === "input" && String(b.name).toLowerCase() === field.toLowerCase() && String(b.type) === "bool"));
         const check = authLines(v.requires, `views/${name}`, binds, !target.endsWith("postgres"));
-        return `[${q(name)}, { ${check.length ? `check: (caller) => {${check.join("")}}, ` : ""}query: input${i}, page: async (db, caller, input, paging) => (await import("./paged/views/${encodeURIComponent(name)}.js")).default(db, caller, input, paging)${convert ? `, convert: ${convert}` : ""}${booleans.length ? `, booleans: ${q(booleans)}` : ""} }]`;
+        return `[${q(name)}, { ${check.length ? `check: (caller) => {${check.join("")}}, ` : ""}${acceptsEmpty(v.input) ? "" : "unlisted: true, "}query: input${i}, page: async (db, caller, input, paging) => (await import("./paged/views/${encodeURIComponent(name)}.js")).default(db, caller, input, paging)${convert ? `, convert: ${convert}` : ""}${booleans.length ? `, booleans: ${q(booleans)}` : ""} }]`;
     });
     return { "web.ts": [
             ...(plan.access ? ['import { userBinds } from "@aotter/mantle/user-fields";'] : []),
@@ -14,7 +15,7 @@ export function emitWeb(plan, lowered, target) {
             ...views.flatMap(([n], i) => [`import { query as input${i} } from "./validation/views/${encodeURIComponent(n)}.js";`, `import type { Row as Row${i} } from "./views/${encodeURIComponent(n)}.js";`]),
             'import { web as site, type Options, type Page } from "@aotter/mantle/web";',
             databaseImport(target),
-            `type App = { Rows: {${views.map(([n], i) => `${q(n)}:Row${i}`).join(";")}}; Inputs: {${views.map(([n, v]) => `${q(n)}:${Object.keys(v.input?.properties ?? {}).map(k => q(k)).join(" | ") || "never"}`).join(";")}}; List: ${views.filter(([, v]) => !v.input?.required?.length).map(([n]) => q(n)).join(" | ") || "never"} };`,
+            `type App = { Rows: {${views.map(([n], i) => `${q(n)}:Row${i}`).join(";")}}; Inputs: {${views.map(([n, v]) => `${q(n)}:${Object.keys(v.input?.properties ?? {}).map(k => q(k)).join(" | ") || "never"}`).join(";")}}; List: ${views.filter(([, v]) => acceptsEmpty(v.input)).map(([n]) => q(n)).join(" | ") || "never"} };`,
             "export function web<const P extends Record<string, Page<App>>, E = unknown>(options: Options<App, Database, P, E>) {",
             `  return site<Database, E>(${plan.access ? `{...options, fields: ${q(plan.access.userFields)}, accessTargets: () => import("./access-targets.js").then(m => m.targets)}` : '{...options, accessTargets: () => import("./access-targets.js").then(m => m.targets)}'}, [${table.join(", ")}]);`,
             "}"

package/docs/examples/README.md

@@ -31,5 +31,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](./reference-service/README.md) is the release smoke test for packed packages, not a starting point.
+[Reference service](https://github.com/aotter/mantle/tree/v0.2.0-alpha.9/docs/examples/reference-service) is the release smoke test for packed packages, not a starting point. Its source lives in the tagged repository; it is not included in the npm docs.
 Projects on 0.1.x move with [the upgrade guide](../upgrade-0.1-to-0.2.md).

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

@@ -20,6 +20,11 @@ pnpm dev                       # one-time codes print to this log
 pnpm smoke                     # when the copied example has smoke.mjs
 ```
 
+npm works too (`npm install`, `npm run …`). `package.json` pins `@better-auth/core` and `@better-auth/utils` even though
+the shell does not import them: they are the exact versions the SDK's Better Auth peers require, and without them a fresh
+install resolves newer ones (npm ERESOLVE, or a second Better Auth type tree under pnpm). Keep every Better Auth package
+on one version.
+
 ## Files you edit
 
 | File | What it is for |
@@ -27,15 +32,16 @@ pnpm smoke                     # when the copied example has smoke.mjs
 | `manifests/*.yaml` | Your Schemas, Views, Procedures and Triggers. `pnpm generate` compiles every file here. |
 | `src/handlers.ts` | Code for each `handler: { ref }` Procedure. The Store it receives is bound to the same caller. |
 | `src/routes.ts` | App-owned routes: visitor pages, SEO files, webhooks and callbacks. |
-| `src/admin.ts` | Admin presentation for `--admin-extensions`: `navGroups` (sidebar groups) and `adminExtensions`. Empty by default. |
+| `src/admin.tsx` | Optional, not shipped: the Admin entry (`defineAdmin(admin, { nav, pages, home, components, plugins, mcp })`) `mantle bundle` builds instead of the built-in one. Add it to group the sidebar or replace Admin regions; see docs/handbook/guides/native-admin.md. |
 | `src/sign-in.ts` | Member sign-in page at `/sign-in` (email code, then back to `?return=`) and `signInRedirect(request)` for pages that need a signed-in visitor. Unstyled; delete it if the app has no member pages. |
 | `src/schedule.ts` | Cron work. Add the cron to `wrangler.jsonc` `triggers.crons`. |
 | `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). |
 
-`src/service.ts` and `src/index.ts` rarely change. Delete the blocks marked `MCP / OAuth (optional)` in `auth.ts`
-and `service.ts` if the app has no MCP.
+`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.
 
 Search for `AGENT:` to find what an app must fill in.
 
@@ -46,3 +52,39 @@ Search for `AGENT:` to find what an app must fill in.
 - `ADMIN_EMAIL`'s first verified sign-in becomes `admin` while no admin exists. The sign-in response may still show
   the previous role; `/admin/api/me` shows the current one.
 - Admin HTTP routes are listed in `docs/handbook/guides/native-admin.md`.
+
+Scripted smoke is not independent acceptance; before reporting a user-facing
+deliverable done, follow the [independent acceptance guide](../../handbook/guides/agent-workflow-acceptance.md).
+
+### MCP acceptance
+
+Generation declares tools; the app owns whether and where a remote endpoint is mounted.
+In your `smoke.mjs`, reuse the generated static tool names rather than maintaining a second list:
+
+```js
+import assert from "node:assert/strict";
+import { assertMcpDiscovery, smoke } from "./smoke-kit.mjs";
+import { developerConsole } from "./generated/admin-descriptors.ts";
+
+await smoke(async ({ origin, owner, signIn, mcp }) => {
+  const cookie = await signIn(owner);
+  const tools = developerConsole.interfaces.callable.filter(tool => tool.surface === "admin");
+  await assertMcpDiscovery(`${origin}/mcp/admin`, { tools, headers: { cookie, origin } });
+  // Denial is a separate assertion, not successful discovery.
+  assert.equal((await mcp("/mcp/admin")).status, 401);
+});
+```
+
+Node 22.22+ can read this pure static
+TypeScript descriptor directly; no generated request handlers are executed to derive expected names.
+A TypeScript smoke scenario can instead import `tools` from generated `mcp.ts`.
+Explicitly select the permitted subset if the app narrows authorization, and include any app-composed tools.
+The assertion initializes MCP, forwards supplied identity/session headers, reads all tools/list pages,
+and compares exact names without calling business tools. JSON/SSE protocol failures, missing routes,
+unexpected/missing tools and repeated/excessive pagination fail; it never obtains credentials or mounts routes.
+
+This local cookie test does not prove OAuth Bearer or an external client's connection. Test those separately
+with supplied credentials and record their results. For each declared interface, the existing handoff/README/test
+report must say verified (command, identity and result), intentionally not exposed, or deferred/unverified with a
+reason. WebMCP-only applications remain valid; an interrupted preview must retain the remote acceptance item
+as deferred rather than silently claiming completion.

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

@@ -3,28 +3,36 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "generate": "mantle generate cloudflare-d1 generated manifests/*.yaml --auth src/auth.ts --entry src/index.ts --admin --admin-extensions src/admin.ts",
+    "generate": "mantle generate cloudflare-d1 generated manifests/*.yaml --auth src/auth.ts --entry src/index.ts --admin",
     "types": "wrangler types --include-runtime=false",
     "db:init": "wrangler d1 execute mantle-app --local --file generated/schema.sql",
     "db:seed": "wrangler d1 execute mantle-app --local --file seed.sql",
+    "build": "mantle bundle src/index.ts dist",
+    "test": "node --test generated/admin-mcp-app.check.mjs",
     "dev": "wrangler dev --local --ip 127.0.0.1 --port 8787",
-    "check": "mantle generate cloudflare-d1 generated manifests/*.yaml --auth src/auth.ts --entry src/index.ts --admin --admin-extensions src/admin.ts --check && wrangler types --include-runtime=false --check && tsc --noEmit",
+    "check": "mantle generate cloudflare-d1 generated manifests/*.yaml --auth src/auth.ts --entry src/index.ts --admin --check && wrangler types --include-runtime=false --check && tsc --noEmit",
     "smoke": "node smoke.mjs"
   },
   "dependencies": {
-    "@aotter/mantle": "0.2.0-alpha.7",
-    "@aotter/mantle-ui": "0.2.0-alpha.7",
+    "@aotter/mantle": "0.2.0-alpha.9",
+    "@aotter/mantle-ui": "0.2.0-alpha.9",
     "@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",
     "@modelcontextprotocol/ext-apps": "2.0.0",
-    "@modelcontextprotocol/server": "2.1.0",
+    "@modelcontextprotocol/server": "2.2.0",
     "better-auth": "1.7.7",
-    "@aotter/mantle-admin": "0.2.0-alpha.7"
+    "@aotter/mantle-admin": "0.2.0-alpha.9",
+    "react": "19.3.0",
+    "react-dom": "19.3.0"
   },
   "devDependencies": {
     "@cloudflare/workers-types": "5.20260904.1",
     "@types/node": "^26",
+    "@types/react": "^19.3.0",
+    "playwright-core": "1.62.1",
     "typescript": "^6.0.3",
     "wrangler": "4.129.0"
   },

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

@@ -10,6 +10,60 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { promisify } from "node:util";
 
+/** Read-only remote acceptance. Pass generated tools filtered for this surface and the supplied test identity. */
+export async function assertMcpDiscovery(endpoint, { tools, headers = {} }) {
+  const expected = tools.map(tool => tool.name).sort();
+  assert.equal(new Set(expected).size, expected.length, "expected tools contain duplicate names");
+  const requestHeaders = new Headers(headers);
+  requestHeaders.set("content-type", "application/json");
+  requestHeaders.set("accept", "application/json, text/event-stream");
+  let id = 0;
+  const rpc = async (method, params, notification = false) => {
+    const message = { jsonrpc: "2.0", ...(notification ? {} : { id: ++id }), method, ...(params === undefined ? {} : { params }) };
+    const response = await fetch(endpoint, { method: "POST", headers: requestHeaders, redirect: "error", signal: AbortSignal.timeout(10_000), body: JSON.stringify(message) });
+    assert.equal(response.status, notification ? 202 : 200, `MCP ${method}: HTTP ${response.status}`);
+    if (notification) { await response.body?.cancel(); return; }
+    const text = await response.text(), type = response.headers.get("content-type") ?? "";
+    let replies;
+    if (type.includes("text/event-stream")) {
+      replies = text.replace(/\r\n/g, "\n").split("\n\n").map(event => event.split("\n").filter(line => line.startsWith("data:")).map(line => line.slice(5).trimStart()).join("\n")).filter(Boolean).map(data => JSON.parse(data));
+    } else {
+      assert.ok(type.includes("application/json"), `MCP ${method}: expected JSON or SSE`);
+      replies = [JSON.parse(text)];
+    }
+    const matches = replies.filter(reply => reply?.id === message.id);
+    assert.equal(matches.length, 1, `MCP ${method}: expected one response with the request id`);
+    const reply = matches[0];
+    assert.equal(reply.jsonrpc, "2.0", `MCP ${method}: invalid JSON-RPC version`);
+    assert.ok(!Object.hasOwn(reply, "error"), `MCP ${method}: returned a JSON-RPC error`);
+    assert.ok(reply.result && typeof reply.result === "object" && !Array.isArray(reply.result), `MCP ${method}: missing result object`);
+    const session = response.headers.get("mcp-session-id");
+    if (session) requestHeaders.set("mcp-session-id", session);
+    return reply.result;
+  };
+  const initialized = await rpc("initialize", { protocolVersion: "2025-11-25", capabilities: {}, clientInfo: { name: "mantle-smoke", version: "1" } });
+  assert.equal(initialized.protocolVersion, "2025-11-25", "MCP initialize: unsupported protocol version");
+  assert.ok(initialized.capabilities?.tools && typeof initialized.capabilities.tools === "object" && !Array.isArray(initialized.capabilities.tools), "MCP initialize: no tools capability");
+  assert.ok(typeof initialized.serverInfo?.name === "string" && typeof initialized.serverInfo?.version === "string", "MCP initialize: invalid serverInfo");
+  requestHeaders.set("mcp-protocol-version", initialized.protocolVersion);
+  await rpc("notifications/initialized", undefined, true);
+  const names = [], cursors = new Set();
+  let cursor;
+  do {
+    assert.ok(cursors.size < 100, "MCP tools/list: exceeded 100 pages");
+    const page = await rpc("tools/list", cursor === undefined ? {} : { cursor });
+    assert.ok(Array.isArray(page.tools) && page.tools.every(tool => tool && typeof tool.name === "string" && tool.name.length > 0 && tool.inputSchema && typeof tool.inputSchema === "object" && !Array.isArray(tool.inputSchema) && tool.inputSchema.type === "object"), "MCP tools/list: invalid tools");
+    names.push(...page.tools.map(tool => tool.name));
+    cursor = page.nextCursor;
+    if (cursor !== undefined) {
+      assert.ok(typeof cursor === "string" && cursor.length > 0 && !cursors.has(cursor), "MCP tools/list: invalid or repeated cursor");
+      cursors.add(cursor);
+    }
+  } while (cursor !== undefined);
+  assert.deepEqual(names.sort(), expected, "MCP tools/list: discovered tools differ from the expected permitted tools");
+  return names;
+}
+
 const database = "mantle-app"; // wrangler.jsonc d1_databases[0].database_name
 const env = { ...process.env, WRANGLER_SEND_METRICS: "false" };
 

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

@@ -5,7 +5,7 @@ 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 { 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";
@@ -34,9 +34,12 @@ export function authOptions(env: Env) {
       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.
+    // --- MCP / OAuth (deliberate exception): remove only when the app intentionally chooses asymmetric exposure.
     jwt({ disableSettingJwtHeader: true }),
-    mcp({ loginPage: "/admin/sign-in", consentPage: "/admin/oauth/consent", resource: `${origin}/mcp`, scopes: ["mcp"], extensions: [oauthGrantExtension], allowPublicClientPrelogin: true, clientRegistrationClientSecretExpiration: "90d" }),
+    // Ends a user's OAuth grants (offline ones too) on password reset, admin ban or session revocation.
+    oauthGrantRevocation(),
+    // The client must request and consent to offline_access to receive a rotating refresh token.
+    mcp({ loginPage: "/admin/sign-in", consentPage: "/admin/oauth/consent", resource: `${origin}/mcp`, scopes: ["mcp", "offline_access"], clientRegistrationDefaultScopes: ["mcp", "offline_access"], extensions: [oauthGrantExtension], allowDynamicClientRegistration: true, allowUnauthenticatedClientRegistration: true, allowPublicClientPrelogin: true, clientRegistrationClientSecretExpiration: "90d" }),
     cimd({ fetchClientMetadataResource: (input, init) => fetch(input, { ...init, redirect: "manual" }), metadataProfile: "mcp-2026-07-28" }),
     // --- end MCP / OAuth
   ];

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

@@ -56,14 +56,14 @@ export async function fetchService(request: Request, env: Env, context: Executio
       }
       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 }) } });
+      // --- MCP / OAuth (deliberate exception): remove with the auth plugins only for intentional asymmetric exposure.
+      serveMcpHandler ??= serveMcp(tools, { ...options, authorizationScopes: ["offline_access"], 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("/" + path, url), request)));
+    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/tsconfig.json

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

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

@@ -1,5 +1,5 @@
 /* eslint-disable */
-// Generated by Wrangler by running `wrangler types --include-runtime=false` (hash: a915f363a88b93fd3b80de7926237051)
+// Generated by Wrangler by running `wrangler types --include-runtime=false` (hash: 1091fee65f95f8f0fa1b8353572138b4)
 interface __BaseEnv_Env {
 	DB: D1Database;
 	ASSETS: Fetcher;
@@ -9,7 +9,7 @@ interface __BaseEnv_Env {
 }
 declare namespace Cloudflare {
 	interface GlobalProps {
-		mainModule: typeof import("./dist/index");
+		mainModule: typeof import("./dist/worker/index");
 	}
 	interface Env extends __BaseEnv_Env {}
 }

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

@@ -1,10 +1,11 @@
 {
   "$schema": "node_modules/wrangler/config-schema.json",
   "name": "mantle-app",
-  "main": "dist/index.js",
+  "main": "dist/worker/index.js",
   "compatibility_date": "2026-09-01",
   "compatibility_flags": [
-    "nodejs_compat"
+    "nodejs_compat",
+    "global_fetch_strictly_public"
   ],
   "secrets": {
     "required": [
@@ -31,7 +32,7 @@
     }
   ],
   "assets": {
-    "directory": "node_modules/@aotter/mantle-admin/dist/admin",
+    "directory": "dist/client",
     "binding": "ASSETS",
     "run_worker_first": true,
     "html_handling": "none"
@@ -41,7 +42,7 @@
   },
   "no_bundle": true,
   "find_additional_modules": true,
-  "base_dir": "dist",
+  "base_dir": "dist/worker",
   "build": {
     "command": "mantle bundle src/index.ts dist",
     "watch_dir": [

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

@@ -165,6 +165,13 @@ spec:
   source: { kind: http, method: POST, path: /api/registrations/cancel }
   target: { procedure: cancel-registration }
 ---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Trigger
+metadata: { name: cancel-registration-mcp }
+spec:
+  source: { kind: mcp, surface: public }
+  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).

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

@@ -17,7 +17,7 @@ export const handlers: Handlers = {
       return await store.procedures["register-write"]({ eventId, member: caller.subject, memberName: user?.name || user?.email || caller.subject });
     } catch (error) {
       // register-write's only Schema check is the capacity one.
-      if (error instanceof ContractError && error.code === "CONFLICT" && error.message.startsWith("A check of the Schema failed"))
+      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;
     }

package/docs/examples/generated-web/README.md

@@ -65,8 +65,12 @@ total). Markdown may perform two View reads when checking an exact `.md` page
 before its alternate.
 
 Web indexes have deliberate ceilings: 5,000 scanned rows, 10 queries and 1 MiB
-for `llms.txt`; 50,000 rows, 100 queries and 50 MiB for a sitemap. Small SQL LIMITs
-can truncate sooner. Translation-aware web indexes/hreflang remain a separate
+for `llms.txt`; 50,000 rows, 100 queries and 50 MiB for a sitemap. An authored SQL `LIMIT 3` means at most three rows in the entire index,
+not three rows per query. Omit SQL LIMIT to enumerate the whole authorized
+result up to these web ceilings. The renderer requests pages of up to 500
+through generated paging options; transport page size does not expand the
+authored result set. Migration: remove LIMIT only when it was mistakenly
+being used as a page-size setting; retain a business-defined top-N limit. Translation-aware web indexes/hreflang remain a separate
 follow-up; `locales[0]` supplies the currently supported locale alternate.
 
 The SDK runs this exact Worker against a native SQLite database in

package/docs/examples/generated-web/wrangler.jsonc

@@ -2,6 +2,7 @@
   "name": "mantle-generated-web",
   "main": "src/worker.ts",
   "compatibility_date": "2026-09-28",
+  "compatibility_flags": ["nodejs_compat", "global_fetch_strictly_public"],
   "vars": { "PUBLIC_ORIGIN": "http://localhost:8787" },
   "d1_databases": [{ "binding": "DB", "database_name": "mantle-generated-web", "database_id": "local-example" }]
 }

package/docs/examples/purchasing/README.md

@@ -37,7 +37,7 @@ that have been waiting too long.
   `wrangler.jsonc`. The cron retries failed orders (internal View `approved-requests`) and sends the reminder
   (internal View `stale-requests`) to admins who are not banned.
 - Employees see only their own requests through `my-requests` (`restrict: { requests: "author_id = auth.uid()" }`).
-- **Sidebar for the approver's day**: `src/admin.ts` declares an Approvals group (`navGroups`) above Admin's built-in
+- **Sidebar for the approver's day**: `src/admin.tsx` declares an Approvals group (`defineAdmin` `nav.groups`) above Admin's built-in
   groups; `pending-requests` and `requests` move into it with `uiSchema.nav: { group, order }`.
 - **A page only signed-in employees reach**: `src/requests-page.ts` serves `GET /requests`. An anonymous visitor gets a
   303 to the shell's `/sign-in?return=/requests` (`src/sign-in.ts`, email code, then back). Signed in, the table reads