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

package/dist/infrastructure/generate.js

@@ -90,6 +90,14 @@ function outputNameWarnings(plan) {
             inspect("Procedure", name, procedure.handler.sql.stmts);
     return [...new Set(warnings)];
 }
+function missingMcpWarnings(plan) {
+    const mcp = new Set(Object.values(plan.triggers).flatMap(trigger => trigger.source.kind === "mcp" ? [trigger.procedure] : []));
+    const http = new Set(Object.values(plan.triggers).flatMap(trigger => trigger.source.kind === "http" ? [trigger.procedure] : []));
+    return [...http].filter(name => !mcp.has(name)).map(name => {
+        const surface = plan.procedures[name]?.requires?.auth?.all.includes("ctx.admin") ? "admin" : "public";
+        return `Procedure '${name}' has an http Trigger but no mcp Trigger, so the user's AI cannot reach this operation. Add a Trigger with spec.source: { kind: mcp, surface: ${surface} } and spec.target: { procedure: ${name} }.`;
+    });
+}
 export async function generateFromSources(request, schema) {
     const postgres = request.target.endsWith("postgres");
     const compiler = postgres ? postgresCompiler : sqliteCompiler;
@@ -109,7 +117,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 +163,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));
@@ -170,5 +178,5 @@ export async function generateFromSources(request, schema) {
     const gatewayFiles = generatedFiles({ "access-targets.ts": `import type { AccessTarget } from "@aotter/mantle/contracts";\nexport const targets: Readonly<Record<string, AccessTarget>> = ${JSON.stringify(accessTargets)};\n` });
     const ddl = [...(postgres ? postgresSchema : sqliteSchema)(compiled.plan.schemas), ...publishingSql(compiled.plan.schemas, !postgres), ...(request.admin ? adminIndexes(compiled.plan.schemas, !postgres) : []), ...(schema?.() ?? [])];
     const { "site-schema.sql": siteSql = "", ...files } = result.files;
-    return { ...result, warnings: [...outputNameWarnings(compiled.plan), ...(request.admin ? adminCreateWarnings(compiled.plan) : []), ...(compiled.plan.access?.warnings ?? [])], files: { ...files, ...gatewayFiles, ...generatedFiles({ "schema.sql": ddl.join(";\n\n") + ";\n" + siteSql }) } };
+    return { ...result, warnings: [...missingMcpWarnings(compiled.plan), ...outputNameWarnings(compiled.plan), ...(request.admin ? adminCreateWarnings(compiled.plan) : []), ...(compiled.plan.access?.warnings ?? [])], files: { ...files, ...gatewayFiles, ...generatedFiles({ "schema.sql": ddl.join(";\n\n") + ";\n" + siteSql }) } };
 }

package/dist/infrastructure/generateAuth.js

@@ -1,4 +1,5 @@
 import { generateFromSources as generate } from "./generate.js";
+import { admin, anonymous, jwt, phoneNumber, siwe, twoFactor } from "better-auth/plugins";
 import { authSchemaSql } from "./authSchema.js";
 /** One or more Better Auth instances (each with its own table names); their DDL is merged. */
 export function generateFromSources(request) {
@@ -6,6 +7,14 @@ 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.");
+    }
+    if (instances.length > 1)
+        refuseSharedPluginMappings(instances);
     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.
@@ -15,3 +24,51 @@ function authSql(instances, dialect) {
         throw new Error(`Better Auth instances define table ${twice} differently; give each instance its own table names (user.modelName, session.modelName, ...).`);
     return statements;
 }
+// Plugins whose factory hands back one module-level schema object (mergeSchema writes `schema` options into it); no options leaves it untouched.
+const sharedSchema = {
+    jwt: () => jwt().schema, admin: () => admin().schema, anonymous: () => anonymous().schema,
+    "phone-number": () => phoneNumber({}).schema, siwe: () => siwe({}).schema, "two-factor": () => twoFactor().schema,
+};
+// Plugins that share field objects (device-authorization) or copy per call (oauth-provider, listed on request) are only checked for equal resolved names.
+const checkedPlugins = new Set([...Object.keys(sharedSchema), "device-authorization", "oauth-provider"]);
+/** Names a plugin's tables and fields resolve to, keyed `table` / `table.field`; only mappings that differ from the key are listed. */
+function mapped(schema) {
+    const names = new Map();
+    for (const [table, model] of Object.entries(schema)) {
+        if (model.modelName && model.modelName !== table)
+            names.set(table, model.modelName);
+        for (const [field, type] of Object.entries(model.fields ?? {})) {
+            const name = type.fieldName;
+            if (name && name !== field)
+                names.set(`${table}.${field}`, name);
+        }
+    }
+    return names;
+}
+/** Better Auth plugin factories share their schema object, so differing plugin field/model mappings across instances in one Worker override each other. */
+function refuseSharedPluginMappings(instances) {
+    const byPlugin = new Map();
+    instances.forEach((options, index) => (options.plugins ?? []).forEach(plugin => {
+        const schema = plugin.schema;
+        if (schema && checkedPlugins.has(plugin.id))
+            byPlugin.set(plugin.id, [...(byPlugin.get(plugin.id) ?? []), { index, schema }]);
+    }));
+    for (const [id, uses] of byPlugin) {
+        const names = uses.map(use => mapped(use.schema));
+        if (uses.length < 2 || !names.some(own => own.size))
+            continue;
+        const fail = (reason, which) => { throw new Error(`Better Auth plugin ${id} is used by instances ${which.join(", ")} (--auth order, from 0) and ${reason}. Plugin factories share their schema object, so differing plugin field/model mappings across instances in one Worker override each other: pass an explicit \`schema\` mapping to the ${id} plugin in every instance, with names that differ between instances, and give each instance its own copy right after constructing it, \`{ ...plugin, schema: structuredClone(plugin.schema) }\`; or keep the ${id} plugin at its defaults and separate the instances by core table names.`); };
+        const shared = sharedSchema[id]?.();
+        const holders = uses.filter(use => use.schema === shared).map(use => use.index);
+        if (holders.length)
+            fail("a non-default mapping exists while an instance holds the plugin's shared schema object (no own copy)", holders);
+        for (const [i, a] of uses.entries())
+            for (const [j, b] of uses.entries()) {
+                if (j <= i)
+                    continue;
+                for (const [key, name] of names[i])
+                    if (names[j].get(key) === name)
+                        fail(`both resolve ${key} to "${name}"; non-default plugin names must differ between instances, because generate cannot tell an identical mapping from an inherited one`, [a.index, b.index]);
+            }
+    }
+}

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))}\nbinding = "ASSETS"\nrun_worker_first = true\nhtml_handling = "none"\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,51 @@ 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);
+    if (assets !== undefined) {
+        const wireAssets = (path, current) => {
+            edit([...path, "directory"], local(assets));
+            const ownsDefaults = current === undefined || current?.binding === undefined;
+            if (ownsDefaults && current?.binding === undefined)
+                edit([...path, "binding"], "ASSETS");
+            if (ownsDefaults && current?.run_worker_first === undefined)
+                edit([...path, "run_worker_first"], true);
+            // The shell fetches index.html itself; asset canonicalization would redirect it back to /admin/ forever.
+            if (current?.html_handling === undefined && (current?.run_worker_first === true || (ownsDefaults && current?.run_worker_first === undefined)))
+                edit([...path, "html_handling"], "none");
+        };
+        wireAssets(["assets"], config.assets);
+        for (const [name, environment] of Object.entries(config.env ?? {})) {
+            if (environment?.assets !== undefined)
+                wireAssets(["env", name, "assets"], environment.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/binds.d.ts

@@ -36,9 +36,6 @@ export type Bound = {
 };
 /** The dialect functions the recipes in use call; generated code passes only those. */
 export type Values = Partial<Pick<Dialect, "now" | "cutoff" | "timestamp" | "date">> & {
-    readonly user?: (recipe: Extract<Recipe, {
-        k: "user";
-    }>, caller: Caller) => unknown;
     readonly scopeInsert?: Dialect['scopeInsert'];
     readonly userRefs?: (recipe: Recipe, caller: Caller) => unknown;
     /** Present only in apps with user fields: keeps, per caller, one printed form of each Schema scope term. */

package/dist/kernel/contracts.d.ts

@@ -111,7 +111,7 @@ export declare function deny(caller: Caller, allowed: boolean, path: string): vo
 /** CONFLICT for a write the database refused: a unique-index clash, or a row statement that did not change exactly one row. */
 export declare const conflict: (path: string, unique: boolean, cause?: unknown) => ContractError;
 /** A Schema `checks` violation (Mantle's SQLite check trigger, or PostgreSQL SQLSTATE 23514) is a CONFLICT naming the check. */
-export declare const checkConflict: (path: string, error: unknown, violated?: boolean) => ContractError | undefined;
+export declare const checkConflict: (path: string, error: unknown) => ContractError | undefined;
 /** One result of `unsafe`: the rows (typed by the generated function), plus the affected count. */
 export type PostgresResult = any[] & {
     readonly count: number | null;

package/dist/kernel/contracts.js

@@ -54,11 +54,11 @@ export function deny(caller, allowed, path) {
 /** CONFLICT for a write the database refused: a unique-index clash, or a row statement that did not change exactly one row. */
 export const conflict = (path, unique, cause) => new ContractError("CONFLICT", unique ? "A unique constraint of the Schema was violated." : "Expected one affected row.", path, { cause });
 /** A Schema `checks` violation (Mantle's SQLite check trigger, or PostgreSQL SQLSTATE 23514) is a CONFLICT naming the check. */
-export const checkConflict = (path, error, violated = /MANTLE_CHECK /.test(String(error?.message))) => {
-    if (!violated)
+export const checkConflict = (path, error) => {
+    const message = error?.message ?? "", marker = /MANTLE_CHECK ([^:\n]+): (.+)/.exec(message);
+    if (!/MANTLE_CHECK /.test(message))
         return undefined;
-    const message = String(error?.message ?? "");
-    return new ContractError("CONFLICT", `A check of the Schema failed: ${/MANTLE_CHECK [^\n'"]+/.exec(message)?.[0] ?? message}`, path, { cause: error });
+    return new ContractError("CONFLICT", `A check of the Schema failed: ${marker?.[0] ?? message}`, path, { cause: error, fields: { kind: "check", schema: marker?.[1], check: marker?.[2]?.replace(/: SQLITE_CONSTRAINT.*$/, "") } });
 };
 /** A cookie is ambient authority; bearer credentials deliberately supplied by the app are not. */
 export function checkOrigin(request, caller) {

package/dist/kernel/dialect/common.d.ts

@@ -10,7 +10,6 @@ export declare const likeEscape = " ESCAPE '\\'";
  */
 export interface Dialect {
     readonly userRefs?: import('../binds.js').Values['userRefs'];
-    readonly user?: import('../binds.js').Values['user'];
     readonly anyOf?: (column: string, placeholder: string, type: 'string' | 'number') => string;
     readonly scopeInsert?: (scopes: readonly {
         readonly column: string;

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

@@ -1,4 +1,4 @@
-import { checkConflict, conflict, ContractError } from "../contracts.js";
+import { conflict, ContractError } from "../contracts.js";
 import { context, guard } from "./transaction-context.js";
 const transactions = new WeakSet();
 const ISOLATION = ["serializable", "repeatable read", "read committed", "read uncommitted"];
@@ -9,6 +9,7 @@ export async function run(db, sql, binds) {
 }
 /** SQLSTATE of a server error: `errno` on Bun.SQL, `code` on postgres.js. */
 const sqlstate = (error) => { const e = error; return typeof e?.errno === "string" ? e.errno : e?.code; };
+const check = (path, e) => new ContractError("CONFLICT", `A check of the Schema failed: ${e.message}`, path, { cause: e, fields: { kind: "check", schema: e.table ?? e.table_name, check: e.constraint ?? e.constraint_name } });
 /** A structured server ErrorResponse proves rollback; missing evidence is uncertain. */
 export function definitive(error) {
     if (error instanceof ContractError)
@@ -35,7 +36,7 @@ export async function procedure(db, steps, path) {
     const execute = async (handle) => {
         const results = [];
         for (const s of steps) {
-            const { rows, changes } = await run(handle, s.sql, s.binds).catch(error => { throw sqlstate(error) === "23505" ? conflict(path, true, error) : checkConflict(path, error, sqlstate(error) === "23514") ?? error; });
+            const { rows, changes } = await run(handle, s.sql, s.binds).catch(error => { throw sqlstate(error) === "23505" ? conflict(path, true, error) : sqlstate(error) === "23514" ? check(path, error) : error; });
             if (s.row && changes !== 1)
                 throw conflict(path, false);
             results.push(rows);
@@ -59,6 +60,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();
@@ -35,6 +35,6 @@ export function linkApps(apps, tools, views) {
 }
 /** One endpoint's Apps bound to its tool table; `previous` is reused while the table's names are unchanged. */
 export function linkSurface(apps, selected, previous) {
-    const key = JSON.stringify(selected.map(tool => tool.name).sort());
+    const key = JSON.stringify(selected.map(tool => [tool.name, !!tool.page]).sort(([a], [b]) => a.localeCompare(b)));
     return previous?.key === key ? previous : { key, links: linkApps(apps, new Set(selected.map(tool => tool.name)), new Set(selected.filter(tool => tool.page).map(tool => tool.name))) };
 }