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

package/dist/infrastructure/generate.js

@@ -109,7 +109,7 @@ export async function generateFromSources(request, schema) {
             // a trusted all-scope read does not acquire a fictional scope predicate.
             if (!Object.hasOwn(paging, name))
                 paging[name] = provePaging(compiled.plan, ast);
-            return { SelectStmt: { ...ast.SelectStmt, limitCount: undefined, limitOption: "LIMIT_OPTION_DEFAULT" } };
+            return ast;
         },
         project(ast, kind, name, page) {
             if (kind === "procedure")
@@ -155,7 +155,7 @@ export async function generateFromSources(request, schema) {
     const adminReads = request.admin ? await adminBindingsOf(compiled.plan, dialect, paging, wire, refusals) : undefined;
     const { adminPages, adminEntries } = adminReads ?? {};
     const report = await describeApp(compiled.plan);
-    const result = generate({ description: report, target: request.target, admin: request.admin, adminPages, adminEntries, site: request.site, plan: compiled.plan, lowered, wireLowered, viewKeys, newId: coreNewId(dialect, compiled.plan.schemas), adminExtensions: request.adminExtensions, navGroups: request.navGroups, paging });
+    const result = generate({ description: report, target: request.target, admin: request.admin, adminPages, adminEntries, site: request.site, plan: compiled.plan, lowered, wireLowered, viewKeys, newId: coreNewId(dialect, compiled.plan.schemas), paging });
     if (refusals.length) {
         const diagnostics = result.ok ? [] : result.diagnostics.filter(d => !searchProblems.some(p => p.path === d.path) ||
             !["Every reachable visibility mode must have canonical lowered SQL.", "Both caller and trusted SQL must be lowered."].includes(d.message));

package/dist/infrastructure/generateAuth.js

@@ -6,6 +6,12 @@ export function generateFromSources(request) {
     return generate(request, instances.length ? () => authSql(instances, request.target.endsWith("postgres") ? "postgres" : "sqlite") : undefined);
 }
 function authSql(instances, dialect) {
+    for (const options of instances) {
+        const ids = (options.plugins ?? []).map(plugin => plugin.id);
+        // Offline OAuth grants outlive sessions; without the revocation plugin a password reset or ban would not end them. mcp() spreads oauthProvider, id included.
+        if (ids.includes("oauth-provider") && !ids.includes("mantle-oauth-grant-revocation") /* oauthGrantRevocation().id */)
+            throw new Error("Better Auth has an OAuth provider (oauthProvider or mcp) without oauthGrantRevocation(): add it from @aotter/mantle/auth/oauth to the plugins, so a password reset, an admin ban or session revocation ends that user's OAuth grants.");
+    }
     const statements = [...new Set(instances.flatMap(options => authSchemaSql(options, dialect)))];
     // CREATE TABLE IF NOT EXISTS would silently keep the first of two different definitions.
     // Identical statements are already merged, so a repeated table name means two different definitions.

package/dist/infrastructure/inputs.js

@@ -7,10 +7,15 @@ export const INPUTS_FILE = ".mantle-inputs.json";
 const MANTLE_VERSION = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8")).version;
 // Line endings are normalized so a CRLF checkout (core.autocrlf) matches the LF fingerprint.
 const digest = (path) => existsSync(path) ? createHash("sha256").update(readFileSync(path, "utf8").replaceAll("\r\n", "\n")).digest("hex") : null;
-/** The manifests and option modules (`--auth`, `--site`, `--admin-extensions`) one generate run read, by path relative to its output. */
-export function inputsFingerprint(destination, paths) {
+/** The target and the manifests and option modules (`--auth`, `--site`) one generate run read, by path relative to its output. */
+export function inputsFingerprint(destination, paths, target) {
     const inputs = Object.fromEntries(paths.map(path => [relative(resolve(destination), resolve(path)).replaceAll("\\", "/"), digest(path)]));
-    return JSON.stringify({ mantle: MANTLE_VERSION, inputs }, null, 2) + "\n";
+    return JSON.stringify({ mantle: MANTLE_VERSION, target, inputs }, null, 2) + "\n";
+}
+/** The generate target recorded beside `generatedModule` (undefined without a fingerprint, or one written before targets were recorded). */
+export function generatedTarget(generatedModule) {
+    const file = resolve(dirname(generatedModule), INPUTS_FILE);
+    return existsSync(file) ? JSON.parse(readFileSync(file, "utf8")).target : undefined;
 }
 /** Why the generated output that holds `generatedModule` no longer matches its inputs (empty when it does, or when it has no fingerprint). */
 export function staleInputs(generatedModule) {

package/dist/infrastructure/wrangler.js

@@ -3,6 +3,7 @@ import { createRequire } from "node:module";
 import { basename, dirname, join, relative, resolve } from "node:path";
 import { isDeepStrictEqual } from "node:util";
 import { applyEdits, modify, parse } from "jsonc-parser";
+const requiredFlags = ["nodejs_compat", "global_fetch_strictly_public"];
 /** Newest date the project's installed workerd supports, as create-cloudflare picks it; a fixed date before Wrangler is installed. */
 function compatibilityDate(dir) {
     try {
@@ -16,22 +17,26 @@ function compatibilityDate(dir) {
     catch { }
     return "2026-09-28";
 }
-export function configureWrangler(configPath, entry, outdir, generated, check = false) {
+/** `assets`: with `--admin`, the static assets directory `mantle bundle` builds Admin into (`<assets>/admin`). */
+export function configureWrangler(configPath, entry, outdir, generated, check = false, assets, publicFetchRequired = false) {
     const configDir = dirname(resolve(configPath));
     const local = (path) => relative(configDir, resolve(path)).replaceAll("\\", "/") || ".";
     const output = local(outdir);
     const quote = (arg) => /^[\w./-]+$/.test(arg) ? arg : `'${arg.replaceAll("'", "'\\''")}'`;
+    const worker = `${output}/worker`;
+    const assetsFlag = assets !== undefined && resolve(assets) !== resolve(outdir, "client") ? ` --assets ${quote(assets)}` : "";
     const keys = {
-        main: `${output}/${basename(entry).replace(/\.[^.]+$/, "")}.js`, no_bundle: true,
-        find_additional_modules: true, base_dir: output,
+        main: `${worker}/${basename(entry).replace(/\.[^.]+$/, "")}.js`, no_bundle: true,
+        find_additional_modules: true, base_dir: worker,
         rules: [{ type: "ESModule", globs: ["**/*.js"], fallthrough: true }],
-        build: { command: `mantle bundle ${quote(entry)} ${quote(outdir)}`, watch_dir: [local(dirname(entry)), local(generated)] },
+        build: { command: `mantle bundle ${quote(entry)} ${quote(outdir)}${assetsFlag}`, watch_dir: [local(dirname(entry)), local(generated)] },
     };
     if (configPath.endsWith(".toml")) {
         if (check)
             throw new Error("--check requires a JSON or JSONC Wrangler config; TOML generation only prints manual edits.");
-        console.log(`Leave ${configPath} unchanged. Add these Wrangler TOML keys (include nodejs_compat in any existing compatibility_flags):\n` +
-            `main = ${JSON.stringify(keys.main)}\nno_bundle = true\nfind_additional_modules = true\nbase_dir = ${JSON.stringify(output)}\ncompatibility_flags = ["nodejs_compat"]\n\n` +
+        console.log(`Leave ${configPath} unchanged. Add these Wrangler TOML keys (include nodejs_compat and global_fetch_strictly_public in every compatibility_flags override):\n` +
+            `main = ${JSON.stringify(keys.main)}\nno_bundle = true\nfind_additional_modules = true\nbase_dir = ${JSON.stringify(worker)}\ncompatibility_flags = ${JSON.stringify(requiredFlags)}\n\n` +
+            (assets === undefined ? "" : `[assets]\ndirectory = ${JSON.stringify(local(assets))}\n\n`) +
             `[[rules]]\ntype = "ESModule"\nglobs = ["**/*.js"]\nfallthrough = true\n\n[build]\ncommand = ${JSON.stringify(keys.build.command)}\nwatch_dir = ${JSON.stringify(keys.build.watch_dir)}`);
         return false;
     }
@@ -42,10 +47,6 @@ export function configureWrangler(configPath, entry, outdir, generated, check =
     const config = parse(text, errors, { allowTrailingComma: true });
     if (errors.length || !config || typeof config !== "object" || Array.isArray(config))
         throw new Error(`${configPath} must be a valid JSONC object.`);
-    if (config.compatibility_flags !== undefined && (!Array.isArray(config.compatibility_flags) || !config.compatibility_flags.every((flag) => typeof flag === "string"))) {
-        throw new Error(`${configPath}: compatibility_flags must be an array of strings.`);
-    }
-    const flags = config.compatibility_flags ?? [];
     const indent = text.match(/\n([ \t]+)"/)?.[1] ?? "  ";
     const formattingOptions = { insertSpaces: !indent.includes("\t"), tabSize: indent.length, eol: text.includes("\r\n") ? "\r\n" : "\n" };
     // Merge, never replace: the user's own module rules and build options survive.
@@ -54,14 +55,36 @@ export function configureWrangler(configPath, entry, outdir, generated, check =
         if (!isDeepStrictEqual(path.reduce((v, k) => v?.[k], config), value))
             text = applyEdits(text, modify(text, path, value, { formattingOptions }));
     };
+    // Public routing is the default; an explicit private origin remains app-owned without OAuth/CIMD.
+    const ensureFlags = (path, flags) => {
+        if (flags !== undefined && (!Array.isArray(flags) || !flags.every(flag => typeof flag === "string")))
+            throw new Error(`${configPath}: ${path.join(".")} must be an array of strings.`);
+        const privateFetch = Array.isArray(flags) && flags.includes("global_fetch_private_origin");
+        if (privateFetch && (publicFetchRequired || flags.includes("global_fetch_strictly_public")))
+            throw new Error(`${configPath}: ${path.join(".")} includes global_fetch_private_origin, which conflicts with public OAuth/CIMD fetch routing. Remove it and use global_fetch_strictly_public.`);
+        const required = privateFetch ? ["nodejs_compat"] : requiredFlags;
+        if (flags === undefined)
+            edit(path, required);
+        else
+            for (const flag of required)
+                if (!flags.includes(flag))
+                    edit([...path, -1], flag);
+    };
+    ensureFlags(["compatibility_flags"], config.compatibility_flags);
+    // Wrangler environment arrays replace the top-level flags rather than inheriting them.
+    for (const [name, environment] of Object.entries(config.env ?? {})) {
+        if (environment?.compatibility_flags !== undefined)
+            ensureFlags(["env", name, "compatibility_flags"], environment.compatibility_flags);
+    }
     for (const [key, value] of Object.entries(top))
         edit([key], value);
     for (const [key, value] of Object.entries(buildKeys))
         edit(["build", key], value);
+    // Only the directory: the binding, run_worker_first and html_handling stay the application's.
+    if (assets !== undefined)
+        edit(["assets", "directory"], local(assets));
     if (!(config.rules ?? []).some((r) => isDeepStrictEqual(r, rule)))
         edit(config.rules === undefined ? ["rules"] : ["rules", -1], config.rules === undefined ? [rule] : rule);
-    if (!flags.includes("nodejs_compat"))
-        edit(config.compatibility_flags === undefined ? ["compatibility_flags"] : ["compatibility_flags", -1], config.compatibility_flags === undefined ? ["nodejs_compat"] : "nodejs_compat");
     const changed = !exists || text !== original;
     if (changed && !check)
         writeFileSync(configPath, text);

package/dist/kernel/drain.d.ts

@@ -0,0 +1,5 @@
+/** Request-time only: no Worker startup path imports this. */
+/** A request handler that drains the body once it has answered or thrown. `undefined` and `null` mean the request is not this
+ *  handler's, so the next handler can still read it. A handler that answers and reads the request later (in `waitUntil`) must
+ *  read or lock the body before answering. */
+export declare const draining: <A extends [Request, ...any[]], R>(handle: (...args: A) => Promise<R>) => (...args: A) => Promise<R>;

package/dist/kernel/drain.js

@@ -0,0 +1,35 @@
+/** Request-time only: no Worker startup path imports this. */
+/** Read and discard what is left of a request body, at most 1 MiB and 1 s. A response sent over an unread POST body makes local
+ *  `wrangler dev` break the connection, and the next request fails with "Network connection lost". */
+async function drain(request) {
+    let reader;
+    const timer = setTimeout(() => reader?.cancel().catch(() => { }), 1000);
+    try {
+        reader = request.body?.getReader(); // a body the app consumed is done; one it still holds is locked and throws
+        for (let read = 0, chunk; reader && !(chunk = await reader.read()).done;)
+            if ((read += chunk.value.byteLength) > 1024 * 1024) {
+                await reader.cancel();
+                return;
+            }
+    }
+    catch { /* the client went away */ }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** A request handler that drains the body once it has answered or thrown. `undefined` and `null` mean the request is not this
+ *  handler's, so the next handler can still read it. A handler that answers and reads the request later (in `waitUntil`) must
+ *  read or lock the body before answering. */
+export const draining = (handle) => async (...args) => {
+    let response;
+    try {
+        response = await handle(...args);
+    }
+    catch (error) {
+        await drain(args[0]);
+        throw error;
+    }
+    if (response != null)
+        await drain(args[0]);
+    return response;
+};

package/dist/kernel/driver/postgres.js

@@ -59,6 +59,9 @@ export async function transaction(db, fn, options = {}, path = "store/transactio
     guard(db);
     if (transactions.has(db))
         throw new Error("Nested transactions are not supported.");
+    // a transaction handle the app opened (postgres.js types it without `begin`) only suits reads and single statements
+    if (typeof db.begin !== "function")
+        throw new Error("This PostgreSQL handle is a transaction the app opened and cannot begin another: open the transaction with store(pool, caller).transaction and call Procedures through its tx.");
     let committing = false;
     const state = { outer: db };
     try {

package/dist/kernel/host-caller.d.ts

@@ -1,4 +1,5 @@
 /** Request-only host contract validation. */
+export { draining } from "./drain.js";
 import { type Caller, type Gateway, type RequestContext } from "./contracts.js";
 import type { UserFields, UserValue } from "./user-fields.js";
 /** The complete JSON supplied as ctx.props.mantle by a trusted gateway. */

package/dist/kernel/host-caller.js

@@ -1,4 +1,5 @@
 /** Request-only host contract validation. */
+export { draining } from "./drain.js";
 import { forwarded, ContractError, surfaceError, surfaceFailure } from "./contracts.js";
 import { userCaller } from "./user-caller.js";
 import { identities, isHostCaller } from "./caller-identity.js";

package/dist/kernel/mcp-apps.d.ts

@@ -1,18 +1,34 @@
 /** MCP Apps (ADR-0029 D7): UI resources served beside the tools that render in them. */
 export declare const RESOURCE_MIME_TYPE = "text/html;profile=mcp-app";
+/** What `resources/read` passes an HTML loader. */
+export interface McpAppRender {
+    /** The tools this caller's `tools/list` shows on the endpoint, so the HTML names none it cannot see. */
+    readonly tools: ReadonlySet<string>;
+    /** The request's environment as the handler received it: Worker bindings such as `ASSETS`, or whatever a Bun host passes. */
+    readonly env: unknown;
+    /** The `resources/read` request, for its origin. */
+    readonly request: Request;
+}
+/** The CSP a resource asks its host for, as `_meta.ui.csp`. */
+export type McpAppCsp = {
+    readonly connectDomains?: readonly string[];
+    readonly resourceDomains?: readonly string[];
+    readonly frameDomains?: readonly string[];
+    readonly baseUriDomains?: readonly string[];
+};
+/** What a loader may return beside a plain string: the HTML and a CSP known only when it is read. It is sent on `resources/read` and replaces the resource's static `csp` (lists are not merged). */
+export interface McpAppPage {
+    readonly html: string;
+    readonly csp?: McpAppCsp;
+}
 /** One `ui://` resource. The HTML is a reusable asset and never carries caller data: that travels in tool results. */
 export interface McpAppResource {
     readonly uri: string;
     readonly name: string;
     readonly title?: string;
     readonly description?: string;
-    readonly html: string | (() => string | Promise<string>);
-    readonly csp?: {
-        readonly connectDomains?: readonly string[];
-        readonly resourceDomains?: readonly string[];
-        readonly frameDomains?: readonly string[];
-        readonly baseUriDomains?: readonly string[];
-    };
+    readonly html: string | ((render: McpAppRender) => string | McpAppPage | Promise<string | McpAppPage>);
+    readonly csp?: McpAppCsp;
     readonly permissions?: {
         readonly camera?: Record<string, never>;
         readonly microphone?: Record<string, never>;
@@ -20,6 +36,8 @@ export interface McpAppResource {
         readonly clipboardWrite?: Record<string, never>;
     };
     readonly prefersBorder?: boolean;
+    /** `_meta.ui.domain`: the dedicated sandbox origin a host should serve this App from, in the form that host documents. */
+    readonly domain?: string;
     /** Tool names whose results this resource renders. */
     readonly renders?: readonly string[];
     /** Views only this App may call (`visibility: ["app"]`); a client without MCP Apps does not see them. A Procedure cannot be hidden from the model. */
@@ -28,9 +46,11 @@ export interface McpAppResource {
 export interface McpApps {
     readonly resources: readonly McpAppResource[];
 }
-/** The resources of one endpoint's contributors; a contributor's `resources` may be a getter, so `mcp(...)` reads it once. */
+/** An application-owned contributor resolved after the endpoint's caller gate. */
+export type McpAppsSource = McpApps | ((context: Pick<McpAppRender, "env" | "request">) => McpApps | Promise<McpApps>);
+/** Flatten contributors; `mcp(...)` reads static resources getters once at construction. */
 export declare const resourcesOf: (apps: McpApps | readonly McpApps[]) => McpApps;
-/** Checked when `mcp(...)` is built; without a tool table (a request-bound one) only the configuration itself is checked, the tool links wait for the first request. */
+/** Static contributors are checked at construction; resolved factories are checked per request. A request-bound tool table defers tool-link checks until its first request. */
 export declare function linkApps(apps: McpApps | readonly McpApps[], tools?: ReadonlySet<string>, views?: ReadonlySet<string>): {
     resources: McpAppResource[];
     renders: Map<string, string>;

package/dist/kernel/mcp-apps.js

@@ -1,9 +1,9 @@
 import { ContractError } from "./contracts.js";
 /** MCP Apps (ADR-0029 D7): UI resources served beside the tools that render in them. */
 export const RESOURCE_MIME_TYPE = "text/html;profile=mcp-app";
-/** The resources of one endpoint's contributors; a contributor's `resources` may be a getter, so `mcp(...)` reads it once. */
+/** Flatten contributors; `mcp(...)` reads static resources getters once at construction. */
 export const resourcesOf = (apps) => ({ resources: (Array.isArray(apps) ? apps : [apps]).flatMap(app => app.resources) });
-/** Checked when `mcp(...)` is built; without a tool table (a request-bound one) only the configuration itself is checked, the tool links wait for the first request. */
+/** Static contributors are checked at construction; resolved factories are checked per request. A request-bound tool table defers tool-link checks until its first request. */
 export function linkApps(apps, tools, views) {
     const resources = resourcesOf(apps).resources;
     const uris = new Set(), names = new Set(), renders = new Map(), appOnly = new Set();

package/dist/kernel/mcp-handler.js

@@ -1,8 +1,9 @@
 /** Request-only MCP implementation, excluded from Worker startup. */
 import { authorized, authorizeTarget } from "./authorization.js";
 import { forwarded, isAdmin, ContractError, checkOrigin, surfaceCaller, surfaceError, wire } from "./contracts.js";
+import { draining } from "./drain.js";
 import { callToolLazy as callTool } from "./mcp-call.js";
-import { RESOURCE_MIME_TYPE, linkSurface } from "./mcp-apps.js";
+import { RESOURCE_MIME_TYPE, linkSurface, resourcesOf } from "./mcp-apps.js";
 const text = (value, locale) => {
     if (typeof value === "string")
         return value;
@@ -18,11 +19,18 @@ function observe(listener, event) {
         catch { }
 }
 const paging = (schema) => ({ ...schema, properties: { ...schema.properties, limit: { type: "integer", minimum: 1, maximum: 500 }, cursor: { type: "string" } } });
+/**
+ * Characters of `JSON.stringify(page)` an MCP View page may hold. A result carries its rows twice (text block and
+ * `structuredContent`) and hosts are reported to truncate near 150k characters, so one copy stays at 60k.
+ * ponytail: one fixed number; raise it or make it an option if hosts publish their limits.
+ */
+const MCP_PAGE_BUDGET = 60_000;
 /** The scopes a challenge asks for: the credential's, plus what the request needs. */
 const union = (scopes, extra) => [...new Set([...scopes, ...extra])].join(" ");
 /** The handler for `/mcp` (public tools) and `/mcp/admin` (tools for `admin` roles); other paths are undefined. */
 export function handler(tools, options, apps = {}, reads = []) {
-    return async (request, env, ctx) => {
+    const allowed = options.allowedOrigins ?? [];
+    return draining(async (request, env, ctx) => {
         const access = options.gateway ? (await import("./host-access.js")).accessRequest(ctx, options) : undefined;
         let resolved;
         try {
@@ -30,6 +38,18 @@ export function handler(tools, options, apps = {}, reads = []) {
             const url = new URL(request.url), path = url.pathname.replace(/\/+$/, ""), surface = path === "/mcp" ? "public" : path === "/mcp/admin" ? "admin" : undefined;
             if (!surface)
                 return;
+            // MCP transport MUST: a present Origin is a browser, answered only for loopback or `allowedOrigins`. The request's own
+            // host is not implied, since a DNS-rebinding page sends Origin == its rebound Host; a missing Origin is a server client.
+            if (request.headers.has("origin")) {
+                const sdk = await import("@modelcontextprotocol/server");
+                const foreign = sdk.originValidationResponse(request, [...sdk.localhostAllowedOrigins(), ...allowed]);
+                if (foreign) {
+                    access?.finish(new ContractError("AUTH_DENIED", "Origin is not allowed.", "request:origin"));
+                    observe(options.onObservation, { kind: "request-refused", at: Date.now(), surface, status: 403 });
+                    observe(options.onRefusal, { at: Date.now(), status: 403, reason: "origin" });
+                    return foreign;
+                }
+            }
             const select = async () => (typeof tools === "function" ? await tools(request, env) : tools).filter(tool => tool.surface === surface);
             // Dynamic admin tables stay behind the admin gate; cache classification uses generated metadata only.
             let selected = surface === "public" ? await select() : [];
@@ -100,7 +120,9 @@ export function handler(tools, options, apps = {}, reads = []) {
             }
             if (surface === "admin")
                 selected = await select();
-            const { McpServer, createMcpHandler, fromJsonSchema } = await import("@modelcontextprotocol/server");
+            // Before per-caller filtering, so every caller of a deploy sees one catalogue version.
+            const version = catalogueVersion(selected);
+            const { McpServer, ProtocolError, ProtocolErrorCode, createMcpHandler, fromJsonSchema } = await import("@modelcontextprotocol/server");
             if (request.method === "POST" && !cookieOnly && !options.gateway)
                 await parse();
             if (tooLarge && access)
@@ -149,7 +171,17 @@ export function handler(tools, options, apps = {}, reads = []) {
                 }
             }
             const app = options.apps?.[surface];
-            const links = app ? (apps[surface] = linkSurface(app, selected, apps[surface])).links : undefined;
+            let links;
+            if (app) {
+                const sources = (Array.isArray(app) ? app : [app]);
+                const dynamic = sources.some(source => typeof source === "function");
+                const resolved = resourcesOf(await Promise.all(sources.map(source => typeof source === "function" ? source({ env, request }) : source)));
+                // Equal tool names say nothing about request-bound resource identity or ownership.
+                const current = linkSurface(resolved, selected, dynamic ? undefined : apps[surface]);
+                if (!dynamic)
+                    apps[surface] = current;
+                links = current.links;
+            }
             if (options.authorize) {
                 try {
                     for (const message of Array.isArray(parsedBody) ? parsedBody : [parsedBody]) {
@@ -161,7 +193,8 @@ export function handler(tools, options, apps = {}, reads = []) {
                         tool.check?.(caller);
                         await authorizeTarget(options.authorize, tool.target ?? { kind: tool.page ? "view" : "procedure", name: tool.name }, caller);
                     }
-                    if ((Array.isArray(parsedBody) ? parsedBody : [parsedBody]).some(message => message?.method === "tools/list")) {
+                    // an App's HTML is rendered for the same tools the caller's tools/list shows
+                    if ((Array.isArray(parsedBody) ? parsedBody : [parsedBody]).some(message => message?.method === "tools/list" || message?.method === "resources/read")) {
                         const visible = [];
                         for (const tool of selected) {
                             if (caller.kind === "anonymous" && tool.closed || !options.gateway && caller.kind === "user" && caller.credential === "oauth" && tool.scopes?.some(scope => !caller.scopes.includes(scope)))
@@ -184,17 +217,31 @@ export function handler(tools, options, apps = {}, reads = []) {
                     return challenge(error);
                 }
             }
+            const serverInfo = { name: "aotter.mantle", ...options.serverInfo, version: options.serverInfo?.version ?? version };
             // Host calls execute in the SDK callback, after transport validation.
             const handler = createMcpHandler(() => {
                 const schema = (value) => fromJsonSchema(value, { getValidator() { return (input) => ({ valid: true, data: input, errorMessage: undefined }); } });
-                const server = new McpServer({ name: "aotter.mantle", version: "0.2.0", ...options.serverInfo }, { capabilities: { tools: { listChanged: false } }, ...(options.instructions ? { instructions: options.instructions } : {}) });
+                // Tools capability after construction: given to the constructor, the SDK installs its tools/call handler before the wrap below.
+                const server = new McpServer(serverInfo, options.instructions ? { instructions: options.instructions } : {});
+                server.server.registerCapabilities({ tools: { listChanged: false } });
                 if (host)
                     server.server.onclose = () => access?.finish(isRecord(parsedBody) && parsedBody.method === "initialize" ? undefined : new ContractError("INPUT_VALIDATION_FAILED", "MCP request refused.", "mcp", { status: 400 }));
-                const appMeta = links ? registerApps(server, links, parsedBody) : undefined;
+                const appMeta = links ? registerApps(server, links, parsedBody, new Set(selected.map(tool => tool.name)), { env, request }) : undefined;
+                // A host's stale copy names a tool this catalogue lacks: say so, with the catalogue version, instead of the SDK's bare "not found".
+                // Wrapped where the SDK stores it, so transport and request validation still answer first.
+                const registered = new Set(), set = server.server.setRequestHandler.bind(server.server);
+                server.server.setRequestHandler = ((method, handler) => set(method, method === "tools/call" && typeof handler === "function" ? (request, context) => {
+                    if (!registered.has(request.params.name))
+                        throw new ProtocolError(ProtocolErrorCode.InvalidParams, `No tool named ${JSON.stringify(request.params.name)} exists in the current catalogue (catalogue version ${serverInfo.version}).`);
+                    return handler(request, context);
+                } : handler));
                 for (const tool of selected) {
                     const meta = appMeta?.(tool.name);
                     if (meta === false)
                         continue;
+                    registered.add(tool.name);
+                    // Not part of structured output: the version, and on failure the current input contract.
+                    const about = (contract) => { const text = [tool.version && `tool version ${tool.version}`, contract && `input schema ${JSON.stringify(tool.page ? paging(tool.inputSchema) : tool.inputSchema)}`].filter(Boolean).join("; "); return text ? [{ type: "text", text }] : []; };
                     server.registerTool(tool.name, { ...(meta ? { _meta: meta } : {}), ...(tool.title ? { title: text(tool.title, locale) } : {}), description: text(tool.description, locale) ?? text(tool.title, locale) ?? tool.name, inputSchema: schema(tool.page ? paging(tool.inputSchema) : tool.inputSchema), ...(tool.outputSchema ? { outputSchema: schema(tool.outputSchema) } : {}), ...(tool.annotations ? { annotations: tool.annotations } : {}) }, async (raw) => {
                         const metadata = options.onObservation ? { kind: "invocation", surface, invocationId: crypto.randomUUID(), tool: tool.name, caller: Object.freeze(caller.kind === "user" ? { ...caller, scopes: Object.freeze([...caller.scopes]) } : { ...caller }) } : undefined;
                         const started = metadata ? performance.now() : 0;
@@ -206,10 +253,34 @@ export function handler(tools, options, apps = {}, reads = []) {
                                 tool.check?.(caller);
                             if (tool.run && (!host || !tool.readOnly))
                                 checkOrigin(request, caller);
-                            const data = await callTool(tool, raw, () => options.db(env), caller, options.handlers, access?.dryRun ? () => ({ dryRun: true, event: access.finish() }) : undefined);
+                            let db;
+                            const run = (input) => callTool(tool, input, () => db ??= options.db(env), caller, options.handlers, access?.dryRun ? () => ({ dryRun: true, event: access.finish() }) : undefined);
+                            let data = await run(raw);
+                            // A page is cut before the first row that overflows the budget: the same page re-runs with the limit that fits, so the cursor is the View's own.
+                            // Data can change between reads, so the re-run is measured again. A View without an order is one page and refuses a smaller limit: it stays whole.
+                            for (let tries = 0; tool.page && isRecord(data) && Array.isArray(data.rows); tries++) {
+                                const rows = data.rows, total = JSON.stringify(data).length;
+                                if (total <= MCP_PAGE_BUDGET)
+                                    break;
+                                if (rows.length === 1 || tries === 4)
+                                    break;
+                                const sizes = rows.map(row => JSON.stringify(row).length);
+                                let size = total - sizes.reduce((sum, n) => sum + n, 0) - (rows.length - 1), fit = 0;
+                                for (const n of sizes) {
+                                    size += n + (fit ? 1 : 0);
+                                    if (size > MCP_PAGE_BUDGET)
+                                        break;
+                                    fit++;
+                                }
+                                const cut = await run({ ...raw, limit: Math.max(1, fit) }).catch(() => undefined);
+                                if (cut === undefined)
+                                    break;
+                                data = cut;
+                            }
                             if (host)
                                 access?.finish();
-                            return { ...(meta ? { _meta: { "net.aotter.mantle/tool": tool.name } } : {}), content: [{ type: "text", text: JSON.stringify(data) }], ...(data && typeof data === "object" && !Array.isArray(data) ? { structuredContent: data } : {}) };
+                            const text = JSON.stringify(data), notice = tool.page && text.length > MCP_PAGE_BUDGET;
+                            return { ...(meta ? { _meta: { "net.aotter.mantle/tool": tool.name } } : {}), content: [{ type: "text", text }, ...about(false), ...(notice ? [{ type: "text", text: `This page is larger than the ${MCP_PAGE_BUDGET}-character page size budget (a single row over it, or a View without an order, is returned whole), so a host may truncate it. Continue with nextCursor, if any.` }] : [])], ...(data && typeof data === "object" && !Array.isArray(data) ? { structuredContent: data } : {}) };
                         }
                         catch (error) {
                             if (host)
@@ -220,7 +291,7 @@ export function handler(tools, options, apps = {}, reads = []) {
                             if (diagnostic.path === "request:origin")
                                 observe(options.onRefusal, { at: Date.now(), status: 403, reason: "origin" });
                             const payload = { diagnostics: [diagnostic] };
-                            return { ...(meta ? { _meta: { "net.aotter.mantle/tool": tool.name } } : {}), isError: true, content: [{ type: "text", text: JSON.stringify(payload) }], ...(tool.outputSchema ? {} : { structuredContent: payload }) };
+                            return { ...(meta ? { _meta: { "net.aotter.mantle/tool": tool.name } } : {}), isError: true, content: [{ type: "text", text: JSON.stringify(payload) }, ...about(outcome === "failed")], ...(tool.outputSchema ? {} : { structuredContent: payload }) };
                         }
                         finally {
                             if (metadata)
@@ -228,6 +299,11 @@ export function handler(tools, options, apps = {}, reads = []) {
                         }
                     });
                 }
+                // An empty catalogue still answers tools/list and refuses calls the same way.
+                if (registered.size === 0) {
+                    server.server.setRequestHandler("tools/list", () => ({ tools: [] }));
+                    server.server.setRequestHandler("tools/call", () => ({ content: [] }));
+                }
                 return server;
             }, { legacy: "stateless", maxRequestBodySize: 1024 * 1024, onerror: error => console.error("[mantle mcp] request failed", error) });
             const response = await handler.fetch(request, { parsedBody });
@@ -241,7 +317,12 @@ export function handler(tools, options, apps = {}, reads = []) {
             access?.finish(error);
             return (await import("./host-caller.js")).hostFailure(error, resolved, "mcp");
         }
-    };
+    });
+}
+/** A hash of the tools an endpoint serves (`surface:name:version`, sorted), as 32-bit FNV-1a hex: it changes with any tool's definition. */
+function catalogueVersion(tools) {
+    const text = JSON.stringify(tools.map(tool => `${tool.surface}:${tool.name}:${tool.version ?? ""}`).sort());
+    return [...text].reduce((h, c) => Math.imul(h ^ c.codePointAt(0), 16777619) >>> 0, 2166136261).toString(16).padStart(8, "0");
 }
 const CLIENT_CAPABILITIES_META_KEY = "io.modelcontextprotocol/clientCapabilities";
 const isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
@@ -259,22 +340,24 @@ function clientUiSupport(message) {
     }
     return "unknown";
 }
-function appMeta(r) {
-    const ui = { ...(r.csp ? { csp: r.csp } : {}), ...(r.permissions ? { permissions: r.permissions } : {}), ...(r.prefersBorder !== undefined ? { prefersBorder: r.prefersBorder } : {}) };
+function appMeta(r, csp = r.csp) {
+    const ui = { ...(csp ? { csp } : {}), ...(r.permissions ? { permissions: r.permissions } : {}), ...(r.domain !== undefined ? { domain: r.domain } : {}), ...(r.prefersBorder !== undefined ? { prefersBorder: r.prefersBorder } : {}) };
     return Object.keys(ui).length > 0 ? { ui } : undefined;
 }
 /** Registration uses the official SDK; HTML loaders run only on resources/read. */
-function registerApps(server, links, message) {
+function registerApps(server, links, message, tools, request) {
     const enabled = clientUiSupport(message) !== "unsupported";
     if (enabled)
         for (const resource of links.resources) {
             const meta = appMeta(resource);
             server.registerResource(resource.name, resource.uri, { mimeType: RESOURCE_MIME_TYPE, title: resource.title, description: resource.description, ...(meta ? { _meta: meta } : {}) }, async () => {
                 try {
-                    return { contents: [{ uri: resource.uri, mimeType: RESOURCE_MIME_TYPE, text: typeof resource.html === "string" ? resource.html : await resource.html(), ...(meta ? { _meta: meta } : {}) }] };
+                    const loaded = typeof resource.html === "string" ? resource.html : await resource.html({ tools, ...request });
+                    const page = typeof loaded === "string" ? { html: loaded } : loaded, read = page.csp ? appMeta(resource, page.csp) : meta;
+                    return { contents: [{ uri: resource.uri, mimeType: RESOURCE_MIME_TYPE, text: page.html, ...(read ? { _meta: read } : {}) }] };
                 }
-                catch {
-                    console.error("[mantle mcp] resource rendering failed");
+                catch (error) {
+                    console.error("[mantle mcp] resource rendering failed:", error instanceof Error ? error.message : String(error));
                     throw new Error("Internal error.");
                 }
             });

package/dist/kernel/mcp.d.ts

@@ -1,11 +1,12 @@
 /** MCP request handling for a generated tool table; the official SDK loads on the first MCP request. */
 import type { Caller, Target, Authorize, Gateway, RequestContext, GatewayOptions } from "./contracts.js";
 import type { Conversions } from "./surface.js";
+import { type McpAppsSource } from "./mcp-apps.js";
 export { callTool, callToolLazy } from "./mcp-call.js";
-export type { McpApps, McpAppResource } from "./mcp-apps.js";
+export type { McpApps, McpAppsSource, McpAppResource, McpAppRender, McpAppPage, McpAppCsp } from "./mcp-apps.js";
 /** Options of a generated `mcp(...)`; it adds required `handlers` when the app declares ref Procedures. */
 export interface Options<Env, Database> extends GatewayOptions {
-    apps?: Readonly<Partial<Record<"public" | "admin", import("./mcp-apps.js").McpApps | readonly import("./mcp-apps.js").McpApps[]>>>;
+    apps?: Readonly<Partial<Record<"public" | "admin", McpAppsSource | readonly McpAppsSource[]>>>;
     authorize?: Authorize;
     gateway?: Gateway;
     fields?: import("./user-fields.js").UserFields;
@@ -28,6 +29,8 @@ export interface Options<Env, Database> extends GatewayOptions {
     };
     requiredScopes?: readonly string[];
     resourceMetadata?: string;
+    /** Browser origins MCP answers besides loopback, compared by hostname: `https://console.example` or the official SDK's bare `console.example`. The site's own origin is not implied. */
+    allowedOrigins?: readonly string[];
     onObservation?: (event: McpObservation) => void | Promise<void>;
     onRefusal?: (event: CallerRefusal) => void | Promise<void>;
 }
@@ -79,6 +82,8 @@ export interface Tool<Database, Handlers = never> {
         readonly idempotentHint?: boolean;
     };
     readonly inputSchema: unknown;
+    /** The listed definition's version; results carry it so a model holding an older definition can tell. */
+    readonly version?: string;
     /** Declares an auth requirement: anonymous callers are challenged. */
     readonly closed?: boolean;
     /** OAuth scopes the requirement names. */

package/dist/kernel/mcp.js

@@ -3,18 +3,29 @@ export { callTool, callToolLazy } from "./mcp-call.js";
 /** The selected MCP routes; all request work loads only when an MCP request arrives. */
 export function mcp(tools, options, reads = []) {
     let serve;
-    // a bad App configuration fails here, not on the first request
+    // Check known static App configuration now; factories wait for the request caller gate.
     const linked = {};
     const apps = {};
     for (const surface of ["public", "admin"]) {
         const declared = options.apps?.[surface];
         if (declared) {
-            const app = resourcesOf(declared);
-            apps[surface] = app;
-            typeof tools === "function" ? linkApps(app) : linked[surface] = linkSurface(app, tools.filter(tool => tool.surface === surface));
+            // Read each static contributor's resources getter once, including mixed arrays.
+            const sources = (Array.isArray(declared) ? declared : [declared])
+                .map(source => typeof source === "function" ? source : resourcesOf(source));
+            const fixed = resourcesOf(sources.filter(source => typeof source !== "function"));
+            const dynamic = sources.some(source => typeof source === "function");
+            apps[surface] = dynamic ? sources : fixed;
+            // Known static conflicts still fail before any request or dynamic factory runs.
+            if (typeof tools === "function")
+                linkApps(fixed);
+            else {
+                const current = linkSurface(fixed, tools.filter(tool => tool.surface === surface));
+                if (!dynamic)
+                    linked[surface] = current;
+            }
         }
     }
-    options = { ...options, apps };
+    options = { ...options, apps, allowedOrigins: originHostnames(options.allowedOrigins) };
     return async (request, env, ctx) => {
         if (!/^\/mcp(?:\/admin)?\/*$/.test(new URL(request.url).pathname))
             return;
@@ -23,3 +34,16 @@ export function mcp(tools, options, reads = []) {
         return serve(request, env, ctx);
     };
 }
+/** `allowedOrigins` as the hostnames the official SDK compares; a bad entry fails here, not on each request. */
+function originHostnames(origins = []) {
+    return Object.freeze(origins.map(origin => {
+        let url;
+        try {
+            url = new URL(/^[a-z][a-z\d+.-]*:\/\//i.test(origin) ? origin : `http://${origin}`);
+        }
+        catch { }
+        if (origin.includes("*") || !url?.hostname || url.username || url.password || url.pathname !== "/" || url.search || url.hash)
+            throw new TypeError(`mcp allowedOrigins: "${origin}" is not an origin (https://host[:port]) or a host[:port]; wildcards never match.`);
+        return url.hostname;
+    }));
+}