@aotter/mantle 0.2.0-alpha.1 → 0.2.0-alpha.10

package/dist/usecase/adminBindings.js

@@ -0,0 +1,143 @@
+import { userReferences } from "../domain/userReferences.js";
+/** Selected application bindings: compiled checks/native SQL; only the app depends on Admin adapters. */
+import { isPrimaryCollection } from "../build/compiler.js";
+import { enumOptions } from "../build/compiler.js";
+import { databaseImport, isSqlite, literal as q } from "../domain/entry.js";
+import { conversions, authLines } from "../domain/input.js";
+import { recipesOf } from "../domain/recipes.js";
+import { boundaryType, conversion, serverOwned } from "../domain/columns.js";
+import { adminOrder } from "../domain/adminOrder.js";
+import { emitValidation } from "./validation.js";
+const scalar = (type) => ["text", "integer", "int4", "int8", "real", "float8", "bool", "date", "timestamptz"].includes(type ?? "");
+const wire = (fields, sqlite) => {
+    const columns = fields.flatMap(([name, type]) => conversion(name, type, sqlite));
+    const geo = fields.filter(([, type]) => type === "geo").map(([field]) => `row[${q(field)}]=row[${q(field + "_lat")}] == null || row[${q(field + "_lng")}] == null ? null : {lat:row[${q(field + "_lat")}],lng:row[${q(field + "_lng")}]};delete row[${q(field + "_lat")}];delete row[${q(field + "_lng")}];`);
+    return `(raw:Row):Row=>{const row=${columns.length ? `wireRows([raw],${q(columns)})[0]!` : geo.length ? "{...raw}" : "raw"};${geo.join("")}return row;}`;
+};
+/** Core's titled string choices are enum checks; constrained or general oneOf remains refused. */
+function adminProperty(property) {
+    const choices = enumOptions(property);
+    if (!property.oneOf || property.enum || !choices || !property.oneOf.every(branch => Object.entries(branch).every(([key, value]) => key === "const" || key === "title" || key === "type" && value === "string")) || new Set(choices.map(c => c.value)).size !== choices.length)
+        return property;
+    const { oneOf, ...base } = property;
+    return { ...base, enum: choices.map(c => c.value) };
+}
+function checks(s, full) {
+    const properties = Object.fromEntries(Object.entries(s.schema.properties ?? {}).filter(([name]) => name.toLowerCase() !== s.scope && s.fields[name.toLowerCase()] !== "geo").map(([name, property]) => [name, adminProperty(property)]));
+    return { ...s.schema, properties, required: full ? (s.schema.required ?? []).filter(name => Object.hasOwn(properties, name) && !(s.userScopes ?? []).some(u => u.column === name.toLowerCase())) : [], additionalProperties: false };
+}
+const allowed = (requires, path) => {
+    const lines = authLines(requires, path);
+    return lines.length ? `(caller:Caller)=>{try{${lines.join("")}return true;}catch{return false;}}` : "(_caller:Caller)=>true";
+};
+/** Share repeated compiler SQL constants; generated modules evaluate no decoder or kernel at import. */
+function sqlConstants(value) {
+    const counts = new Map();
+    const visit = (v) => { if (typeof v === "string" && v.length > 80)
+        counts.set(v, (counts.get(v) ?? 0) + 1);
+    else if (Array.isArray(v))
+        v.forEach(visit);
+    else if (v && typeof v === "object")
+        Object.values(v).forEach(visit); };
+    visit(value);
+    const pool = new Map([...counts].filter(([, count]) => count > 1).map(([text], n) => [text, `sql${n}`]));
+    const literal = (v) => typeof v === "string" ? pool.get(v) ?? q(v) : Array.isArray(v) ? "[" + v.map(literal).join(",") + "]" : v && typeof v === "object" ? "{" + Object.entries(v).map(([name, child]) => `${name === "__proto__" ? `[${q(name)}]` : q(name)}:${literal(child)}`).join(",") + "}" : q(v);
+    return { code: literal(value), constants: [...pool].map(([text, name]) => `const ${name}=${q(text)};`) };
+}
+export function emitAdminBindings(input, refuse) {
+    if (!input.admin)
+        return {};
+    const { plan, lowered, target } = input, sqlite = isSqlite(target), refs = Object.values(plan.procedures).some(p => "ref" in p.handler), files = {};
+    const user = userReferences(plan, sqlite);
+    const imports = [...(user.used ? [user.code, 'import {userBinds} from "@aotter/mantle/user-fields";'] : []), databaseImport(target), 'import {wireRows,type Caller,type Row} from "@aotter/mantle/contracts";', 'import {deny,isAdmin,isUser} from "@aotter/mantle/contracts";', 'import {invalid} from "@aotter/mantle/surface";', 'import type {Handlers} from "./generated.js";', 'import {bootstrap,allCollections} from "./admin-descriptors.js";', 'import type {View,Operation} from "@aotter/mantle-admin/server";', 'import type {EntrySchema} from "@aotter/mantle-admin/server/entries";'];
+    imports.push('import {nativePage,nativeStatistics,nativeText} from "@aotter/mantle-admin/server/native";', `import * as D from "@aotter/mantle/dialect/${sqlite ? "sqlite" : "postgres"}";`, `import {read,procedure} from "@aotter/mantle/driver/${target === "bun-sqlite" ? "bun-sqlite" : target === "cloudflare-d1" ? "d1" : "postgres"}";`, `const adapter={read,procedure,values:${sqlite ? (user.used ? "{...D,...USER_VALUES}" : "D") : `{...D,${user.used ? "...USER_VALUES," : ""}timestamp:(v:Parameters<typeof D.timestamp>[0])=>{if(typeof v==="string"&&/^0000-/.test(v.trim()))invalid("PostgreSQL timestamps require a nonzero year.","admin/input");return D.timestamp(v);},date:(v:string)=>{if(/^0000-/.test(v.trim()))invalid("PostgreSQL dates require a nonzero year.","admin/input");return D.date(v);}}`},param:D.param,escapeLike:D.escapeLike,sqlite:${sqlite}} as const;`);
+    const schemas = [], views = [], adminViews = [], operations = [], pageSpecs = [];
+    for (const [n, s] of Object.values(plan.schemas).entries()) {
+        const schemaPath = `schemas/${s.name}/admin`, declared = Object.keys(s.fields).filter(f => f !== s.scope), writable = declared.filter(f => scalar(s.fields[f]) || s.fields[f] === "json");
+        // readOnly properties are server-maintained: values() pins them to their default, and they have no Admin UPDATE.
+        const server = Object.fromEntries(writable.filter(f => serverOwned(s.schema, f)).map(f => [f, Object.entries(s.schema.properties ?? {}).find(([k]) => k.toLowerCase() === f)?.[1]?.default ?? null]));
+        // Experimental geo collections remain readable; edits require a declared Procedure.
+        const validators = emitValidation({ views: {}, procedures: { full: { input: checks(s, true) }, partial: { input: checks(s, false) } } }, (path, message) => refuse(schemaPath + "/" + path, message));
+        for (const mode of ["full", "partial"]) {
+            const name = `validation/admin/${encodeURIComponent(s.name)}-${mode}.ts`;
+            files[name] = validators[`validation/procedures/${mode}.ts`].replaceAll(`procedures/${mode}/input`, schemaPath + "/input");
+            imports.push(`import {validate as ${mode}${n}} from "./${name.replace(/\.ts$/, ".js")}";`);
+        }
+        const names = Object.fromEntries(writable.map(f => [s.names[f] ?? f, f])), allNames = { ...names, id: "id", version: "version", createdAt: "created_at", updatedAt: "updated_at", authorId: "author_id", ...(s.publishing ? { status: "status", publishedAt: "published_at" } : {}) };
+        const temporal = writable.filter(f => ["date", "timestamptz"].includes(s.fields[f])).map(f => s.names[f] ?? f);
+        const yearZero = sqlite ? "" : `for(const key of ${q(temporal)})if(typeof data[key]==="string"&&/^0000-/.test(data[key].trim()))invalid("PostgreSQL dates require a nonzero year.",${q(schemaPath)});`;
+        const coercers = Object.entries(allNames).filter(([, f]) => scalar(s.fields[f] ?? (f === "version" ? "integer" : "text"))).map(([name, f]) => {
+            const type = s.fields[f] ?? (f === "version" ? "integer" : "text");
+            const value = type === "bool" ? `raw === "true" ? true : raw === "false" ? false : fail("Expected true or false.")` : ["integer", "int4", "int8", "real", "float8"].includes(type) ? `number(raw,${["integer", "int4", "int8"].includes(type)})` : `raw`;
+            return `case ${q(name)}:return {column:${q(f)},value:${value}};`;
+        });
+        const order = adminOrder(s), orderNames = Object.fromEntries(Object.keys(order).map(f => [f === "updated_at" ? "updatedAt" : s.names[f] ?? f, f]));
+        const parent = s.translates && plan.schemas[s.translates.parent.toLowerCase()];
+        const inherited = parent ? Object.keys(parent.fields).filter(f => f !== parent.scope && !Object.hasOwn(s.fields, f)) : [];
+        const rowNames = { ...(parent ? parent.names : {}), ...s.names };
+        const rowFields = [...declared.map(f => [f, s.fields[f]]), ...inherited.map(f => [f, parent && parent.fields[f]]), ...["version"].map(f => [f, "integer"])];
+        const named = `(raw:Row):Row=>{const row=row${n}(raw);return Object.fromEntries(Object.entries(row).map(([key,value])=>[Object.hasOwn(fieldNames${n},key)?fieldNames${n}[key as keyof typeof fieldNames${n}]:key,value]));}`;
+        const entrySpec = `entrySpecs[${q(s.name)}]`;
+        if (!input.adminEntries?.[s.name]) {
+            refuse(schemaPath, "Missing compiler-authorized entry queries and Procedures.");
+            continue;
+        }
+        const defaults = Object.fromEntries(Object.entries(checks(s, true).properties ?? {}).flatMap(([key, p]) => p.default !== undefined ? [[key, p.default]] : []));
+        const primary = isPrimaryCollection(s, Object.values(plan.schemas));
+        const schemaCode = `{
+      name:${q(s.name)},primary:${primary},descriptor:allCollections[${q(s.name)}],publishing:${!!s.publishing},readOnly:${s.schema.readOnly === true || declared.some(f => s.fields[f] === "geo")},fields:names${n},defaults:${q(defaults)},
+      binding:${entrySpec},
+      query:query${n},validate:(data,full)=>{const checked=Object.fromEntries(Object.entries(data).filter(([key,v])=>v!==null||${q(s.schema.required ?? [])}.includes(key)));(full?full${n}:partial${n})(checked);${sqlite ? "" : "nativeText(data);"}${yearZero}return data;},
+      values:values${n},row:${named},
+      ${sqlite ? "" : "native:nativeText,"}
+      ${s.publishing ? `transition:async(db,caller,verb,id,expectedVersion)=>{const run=await ({publish:()=>import("./procedures/${encodeURIComponent(s.name + ".publish")}.js"),unpublish:()=>import("./procedures/${encodeURIComponent(s.name + ".unpublish")}.js"),archive:()=>import("./procedures/${encodeURIComponent(s.name + ".archive")}.js")})[verb]();const version=wireRows([{version:expectedVersion}],[["version","int"]])[0]!.version;return run.default(db,caller,{id,expectedVersion:version} as Parameters<typeof run.default>[2]);},` : ""}
+    }`;
+        schemas.push(schemaCode);
+        files[`admin/entries-${encodeURIComponent(s.name)}.ts`] = `import {invalid} from "@aotter/mantle/surface";\nimport {wireRows,type Row} from "@aotter/mantle/contracts";\nimport type {EntryPageQuery} from "@aotter/mantle-admin/server/entries";\nimport {entriesQuery,scalarNumber,nativeText} from "@aotter/mantle-admin/server/native";\nconst fail=(message:string):never=>invalid(message,${q(schemaPath)});\nconst number=(raw:string,integer:boolean)=>scalarNumber(raw,integer,${q(schemaPath)});\nimport * as D from "@aotter/mantle/dialect/${sqlite ? "sqlite" : "postgres"}";\nexport const names=${q(names)} as const;\nfunction encode(column:string,value:unknown):unknown{if(value==null)return value;switch(column){${[...writable, ...["created_at", "updated_at", ...(s.publishing ? ["published_at"] : [])]].map(f => { const type = s.fields[f] ?? "timestamptz"; return type === "date" || type === "timestamptz" ? `case ${q(f)}:return D.${type === "date" ? "date" : "timestamp"}(value as string);` : type === "json" ? `case ${q(f)}:return JSON.stringify(value);` : sqlite && type === "bool" ? `case ${q(f)}:return Number(value);` : ""; }).join("")}default:return value;}}\nconst server:Row=${q(server)};\n// Server-maintained (readOnly) fields: create stores their default, an edit drops them (the console echoes whole records).\nexport const values=(data:Row,patch=false):Row=>Object.fromEntries(Object.entries(data).flatMap(([key,value])=>{const column=names[key as keyof typeof names];return Object.hasOwn(server,column)?patch?[]:[[column,encode(column,server[column])]]:[[column,encode(column,value)]];}));\nexport const row=${wire(rowFields, sqlite)};\nfunction coerce(name:string,raw:string):{column:string;value:string|number|boolean}{${sqlite ? "" : "nativeText(raw);" + (temporal.length ? "if(" + q(temporal) + ".includes(name)&&/^0000-/.test(raw.trim()))fail(\"PostgreSQL dates require a nonzero year.\");" : "")}switch(name){${coercers.join("")}default:return fail("Unknown scalar filter field.");}}\nimport {validate as checkFilter} from "../validation/admin/${encodeURIComponent(s.name)}-partial.js";\nfunction field(name:string,raw:string){const f=coerce(name,raw);if(Object.hasOwn(names,name))checkFilter({[name]:f.value});return {...f,value:encode(f.column,f.value) as string|number|boolean};}\nexport const query=(params:URLSearchParams):EntryPageQuery|null=>entriesQuery(params,{path:${q(schemaPath)},orderFields:${q(orderNames)},publishing:${!!s.publishing},sqlite:${sqlite},field});\n`;
+        imports.push(`const fieldNames${n}=${q(rowNames)} as const;`);
+        imports.push(`import {names as names${n},row as row${n},query as query${n},values as values${n}} from "./admin/entries-${encodeURIComponent(s.name)}.js";`);
+    }
+    for (const [name, v] of Object.entries(plan.views).filter(([, v]) => v.surface !== "internal")) {
+        const n = views.length, encoded = encodeURIComponent(name), converted = conversions(v.input?.properties, (lowered.views[name]?.public ?? lowered.views[name]?.caller)?.binds ?? [], target);
+        imports.push(`import {query as queryView${n}} from "./validation/views/${encoded}.js";`);
+        const rename = Object.fromEntries(Object.entries(v.columns ?? {}).map(([key, col]) => [key, key === col.field ? plan.schemas[col.schema].names[col.field] ?? key : key]));
+        imports.push(`const viewNames${n}=${q(rename)} as const;`);
+        const pageData = input.adminPages?.[name];
+        // A supplied page map omits only Views its producer already refused (at `views/<name>` or `views/<name>/admin`).
+        if (!pageData) {
+            if (!input.adminPages)
+                refuse(`views/${name}/admin`, "Admin list was not generated: no compiler-authorized matching pages were supplied for this View.");
+            continue;
+        }
+        const kinds = (v.uiSchema?.list ?? {});
+        const filters = Object.fromEntries((kinds.filterFields ?? []).map(field => {
+            const lineage = v.columns?.[field] ?? v.columns?.[field.toLowerCase()], schema = lineage && plan.schemas[lineage.schema];
+            return [field, adminProperty(schema?.schema.properties?.[schema.names[lineage.field] ?? lineage.field] ?? { type: "string" })];
+        }));
+        const filterChecks = emitValidation({ procedures: { filters: { input: { type: "object", properties: filters, additionalProperties: false } } }, views: {} }, (path, msg) => refuse(`views/${name}/admin/` + path, msg));
+        files[`validation/admin/view-${encoded}.ts`] = filterChecks["validation/procedures/filters.ts"];
+        imports.push(`import {validate as filters${n}} from "./validation/admin/view-${encoded}.js";`);
+        const filterTransforms = Object.keys(filters).flatMap(field => { const col = v.columns?.[field] ?? v.columns?.[field.toLowerCase()], type = col && plan.schemas[col.schema]?.fields[col.field]; const convert = type === "date" && sqlite ? "encodeDate" : type === "timestamptz" && sqlite ? "encodeTimestamptz" : type === "bool" && sqlite ? "Number" : undefined; return convert ? [`if(Object.hasOwn(filters,${q(field)}))filters[${q(field)}]=${convert}(filters[${q(field)}] as ${type === "bool" ? "boolean" : "string"});`] : []; });
+        if (filterTransforms.some(t => t.includes("encode")))
+            imports.push('import {encodeDate,encodeTimestamptz} from "@aotter/mantle/scalars";');
+        const filterReads = Object.entries(filters).map(([field, s]) => { const type = [s.type].flat().find(t => t && t !== "null"); return `if(params.has(${q("filter." + field)})&&params.get(${q("filter." + field)})!=="")filters[${q(field)}]=${type === "boolean" ? `params.get(${q("filter." + field)})==="true"?true:params.get(${q("filter." + field)})==="false"?false:invalid("Expected true or false.",${q("views/" + name)})` : ["number", "integer"].includes(type ?? "") ? `Number(params.get(${q("filter." + field)}))` : `params.get(${q("filter." + field)})!`};`; });
+        const cursorKinds = (input.paging?.[name]?.types ?? []).map(type => type === "bool" ? "bool" : type === "integer" || type === "int8" ? "int" : type === "int4" ? "int4" : type.startsWith("numeric(") ? "numeric" : type === "real" || type === "float8" ? "float" : type === "date" ? "date" : type === "timestamptz" ? "timestamp" : "text");
+        const modes = Object.fromEntries(Object.entries({ caller: pageData.caller, trusted: pageData.trusted }).map(([mode, p]) => [mode, { ...p, binds: recipesOf(p, Object.keys(v.input?.properties ?? {}), message => refuse(`views/${name}/admin`, message)) }]));
+        pageSpecs.push(`const viewPage${n}=${q({ path: "views/" + name, cap: v.stmts[0]?.SelectStmt.limitCount?.A_Const?.ival?.ival ?? 500, cursorKinds, ...modes })} as const;`);
+        imports.push(`const allowsView${n}=${allowed(v.requires, `views/${name}`)};`);
+        if (v.surface === "admin")
+            adminViews.push(`view${n}`);
+        views.push(`{${user.used ? `check:(caller)=>{${authLines(undefined, `views/${name}`, pageData.caller.binds, sqlite).join("")}},` : ""}name:${q(name)},allows:allowsView${n},query:(params)=>{const result=queryView${n}(params),filters:Record<string,unknown>=Object.create(null);${filterReads.join("")}filters${n}(filters);${filterTransforms.join("")}${sqlite ? "" : "nativeText(result.input);nativeText(filters);"}${kinds.searchFields?.length ? `const search=params.get("search")?.trim();` : ""}return {...result,match:{filters${kinds.searchFields?.length ? ",...(search?{search}:{})" : ""}}};},page:(db,caller,input,paging)=>{deny(caller,allowsView${n}(caller),${q("views/" + name)});return nativePage(viewPage${n},adapter,db,caller,input,paging);},${converted ? `convert:${converted},` : ""}row:(raw)=>{const row=(${wire((input.viewKeys[name] ?? []).map(key => [key, boundaryType(plan, name, key)]), sqlite)})(raw);return Object.fromEntries(Object.entries(row).map(([key,value])=>[Object.hasOwn(viewNames${n},key)?viewNames${n}[key as keyof typeof viewNames${n}]:key,value]));}}`);
+    }
+    for (const [name, p] of Object.entries(plan.procedures).filter(([name]) => Object.values(plan.triggers).some(t => t.procedure === name && t.source.kind === "mcp" && t.source.surface === "admin"))) {
+        const n = operations.length, ref = "ref" in p.handler, encoded = encodeURIComponent(name), converted = conversions(p.input?.properties, lowered.procedures[name]?.caller?.flatMap(s => s.binds) ?? [], target);
+        imports.push(`import {validate as operation${n}} from "./validation/procedures/${encoded}.js";`);
+        operations.push(`{${input.description.targets.find(t => t._meta.id === `procedure:${name}`)?._meta.readOnly ? "readOnly:true," : ""}${user.used || p.trustedOnly ? `check:(caller)=>{${authLines(undefined, `procedures/${name}`, lowered.procedures[name]?.caller?.flatMap(s => s.binds), sqlite, p.trustedOnly).join("")}},` : ""}name:${q(name)},allows:${allowed(p.requires, `procedures/${name}`)},validate:operation${n},${converted ? `convert:${converted},` : ""}run:${ref ? `async(db,caller,input)=>(await import("./generated.js")).store(db,caller,{handlers:options.handlers}).procedures[${q(name)}](input)` : `async(db,caller,input)=>(await import("./procedures/${encoded}.js")).default(db,caller,input)`}}`);
+    }
+    const entryData = sqlConstants(input.adminEntries);
+    imports.push(...views.map((view, n) => `const view${n}=${view} satisfies View<Database>;`), ...pageSpecs, ...entryData.constants, `const entrySpecs=${entryData.code} as const;`);
+    imports.push(`export const statisticsView=(db:Database,caller:Caller,collection:keyof typeof entrySpecs,args:{from:number;to:number;bucketMs:number})=>nativeStatistics(entrySpecs,adapter,db,caller,collection,args);`);
+    const metadataGuards = [...Object.entries(plan.views).map(([name, v]) => `case ${q("view:" + name)}: return (${allowed(v.requires, `views/${name}`)})(caller);`), ...Object.entries(plan.procedures).map(([name, p]) => `case ${q("procedure:" + name)}: return (${allowed(p.requires, `procedures/${name}`)})(caller);`), ...Object.values(plan.schemas).filter(s => s.publishing).flatMap(s => ["publish", "unpublish", "archive"].map(verb => `case ${q("procedure:" + s.name + "." + verb)}: return isAdmin(caller);`))];
+    files["admin-bindings.ts"] = `${imports.filter(Boolean).join("\n")}\nexport function adminBindings${refs ? "<const H extends Handlers>(options:{handlers:H & Record<Exclude<keyof H,keyof Handlers>,never>})" : "(_options?:{handlers?:Handlers})"}{\nreturn {metadata:{...bootstrap,accessTargets:()=>import("./access-targets.js").then(m=>m.targets),${plan.access ? `userFields:${q(plan.access.userFields)} as const,` : ""}allows:(target:import("@aotter/mantle/contracts").Target,caller:Caller)=>{switch(target.kind+":"+target.name){${metadataGuards.join("")}default:return target.kind==="schema";}}},adapter,schemas:[${schemas.join(",\n")}] satisfies readonly EntrySchema<Database>[],views:[${adminViews.join(",")}],developerViews:[${views.map((_, n) => `view${n}`).join(",")}],operations:[${operations.join(",\n")}] satisfies readonly Operation<Database,${refs ? "Handlers" : "never"}>[]};\n}\n`;
+    return files;
+}

package/dist/usecase/adminClient.js

@@ -0,0 +1,87 @@
+/** `admin-client.ts`: the types Admin's data hooks bind to, for the application's browser-side `admin.tsx`. */
+import { BUILT_IN_NAV_GROUPS, mcpTools } from "../build/compiler.js";
+import { q } from "../domain/entry.js";
+/**
+ * The compatibility test of the application's Admin MCP App (`node --test generated/admin-mcp-app.check.mjs`): it loads the App
+ * `mantle bundle` built in the official MCP Apps host and fails on a network request, a console error or an exception. It needs
+ * `playwright-core` (a devDependency) and Chrome: `npx playwright-core install chromium`, or `MANTLE_TEST_CHROMIUM=<executable>`.
+ * Node strips the types of `admin-descriptors.ts` (Node 22.18 or newer).
+ */
+const MCP_APP_TEST = `import { existsSync } from "node:fs";
+import { test } from "node:test";
+import { checkMcpApp } from "@aotter/mantle-admin/testing";
+import { mcpAppCatalogues } from "./admin-descriptors.ts";
+
+// \`mantle bundle <entry> dist\` writes the App here; MANTLE_MCP_APP_HTML names another file
+const html = process.env.MANTLE_MCP_APP_HTML ?? "dist/client/admin/mcp-app.html";
+
+test("the Admin MCP App works in an MCP host", { timeout: 300_000 }, async () => {
+  if (!existsSync(html)) throw new Error(\`\${html} is missing: run \\\`npm run build\\\` first.\`);
+  await checkMcpApp({ catalogue: mcpAppCatalogues.admin, html });
+});
+`;
+/** A Schema, View input or Procedure input as a closed object type; one that is only a `$ref` stays open. */
+const closed = (typeOf, schema) => !schema ? "{}" : schema.properties || schema.type === "object" && !schema["$ref"] ? typeOf({ ...schema, additionalProperties: false }) : "{ readonly [key: string]: unknown }";
+/**
+ * Types are what the routes take and return, not the Store's rows: an entry's `data` keeps declared field names, an input is
+ * what the route validates, a View row is its wire row under the names the browser route gives its columns (an MCP App's
+ * `tools/call` returns the SQL names; the hooks rename them with `rowNames`), with `true` when it is an admin MCP tool, else null, which
+ * types `pages[].mcp.renders` (types only; nothing ships). The file imports `generated/*` as types only, so nothing of the
+ * Worker enters the browser bundle, and it is refused in the Worker's startup graph (`mantle bundle`).
+ */
+export function emitAdminClient(plan, typeOf) {
+    const tools = mcpTools(plan, "admin"), hasTool = (kind, source) => tools.some(t => t.kind === kind && t.source === source);
+    const views = Object.entries(plan.views).filter(([, v]) => v.surface === "admin").sort(([a], [b]) => a < b ? -1 : 1);
+    const operations = Object.entries(plan.procedures).filter(([name]) => hasTool("procedure", name)).sort(([a], [b]) => a < b ? -1 : 1);
+    const schemas = Object.values(plan.schemas).sort((a, b) => a.name < b.name ? -1 : 1);
+    // the scope column belongs to the caller, so an entry's data has no such field
+    const dataOf = (s) => {
+        const scope = s.scope ? s.names[s.scope] ?? s.scope : undefined, { [scope ?? ""]: _scope, ...properties } = s.schema.properties ?? {};
+        // a draft of a publishing collection is only partly validated, so none of its fields is certain to be there
+        const required = s.publishing ? [] : s.schema.required?.filter(f => f !== scope);
+        const schema = { ...s.schema, properties, ...(required ? { required } : {}) };
+        return s.translates ? typeOf(schema) : closed(typeOf, schema);
+    };
+    // the names the browser route gives a View's columns where they differ from the SQL output names, as it applies them
+    const renames = views.map(([, v]) => Object.fromEntries(Object.entries(v.columns ?? {}).flatMap(([key, c]) => {
+        const named = key === c.field ? plan.schemas[c.schema].names[c.field] ?? key : key;
+        return named !== key ? [[key, named]] : [];
+    })));
+    // every sidebar group an admin Schema or View places an item in; `defineAdmin` must declare the ones Admin does not have
+    // (the generate-time check of `uiSchema.nav.group` is this type)
+    const placed = (ui) => { const group = ui?.["nav"]?.group; return typeof group === "string" ? [group] : []; };
+    const used = [...new Set([...schemas.flatMap(s => placed(s.uiSchema)), ...views.flatMap(([, v]) => placed(v.uiSchema))])].sort();
+    const custom = used.filter(group => !BUILT_IN_NAV_GROUPS.has(group));
+    const union = (names) => names.length ? names.map(name => q(name)).join(" | ") : "never";
+    // whether an admin View is an MCP tool, which a page declared for an MCP App (`pages[].mcp.renders`) must have
+    const toolOf = (name) => hasTool("view", name) || null;
+    const rows = views.map(([name], n) => `import type { WireRow as View${n}Wire } from "./views/${encodeURIComponent(name)}.js";`);
+    const sql = operations.some(([, p]) => "sql" in p.handler);
+    return { "admin-mcp-app.check.mjs": MCP_APP_TEST, "admin-client.ts": [
+            "// Browser only: import this from src/admin.tsx, never from the Worker (`mantle bundle` refuses it there).",
+            'import type { AdminMeta } from "@aotter/mantle-admin/app";',
+            'import { createAdminHooks } from "@aotter/mantle-admin/hooks";',
+            ...(sql ? ['import type { Output } from "@aotter/mantle/contracts";'] : []),
+            ...rows,
+            "",
+            "type Renamed<Row, Names extends { readonly [from: string]: string }> = { [K in keyof Row as K extends keyof Names ? Names[K] : K]: Row[K] };",
+            ...views.map((_, n) => `type View${n}Row = Renamed<View${n}Wire, ${q(renames[n])}>;`),
+            "",
+            "/** Every sidebar group the manifest places an item in. */",
+            `export type ManifestNavGroup = ${union(used)};`,
+            "",
+            "/** The input and row of each admin View, the `data` of each collection's entries, and the input and output of each admin operation. */",
+            "export interface AppAdminTypes {",
+            `  readonly views: { ${views.map(([name, v], n) => `readonly ${q(name)}: { readonly input: ${closed(typeOf, v.input)}; readonly row: View${n}Row; readonly mcp: ${q(toolOf(name))} }`).join("; ")} };`,
+            `  readonly collections: { ${schemas.map(s => `readonly ${q(s.name)}: { readonly data: ${dataOf(s)} }`).join("; ")} };`,
+            `  readonly operations: { ${operations.map(([name, p]) => `readonly ${q(name)}: { readonly input: ${closed(typeOf, p.input)}; readonly output: ${"sql" in p.handler ? "Output" : "unknown"} }`).join("; ")} };`,
+            `  readonly navGroups: ${union(custom)};`,
+            "}",
+            "",
+            "/** Pass to `defineAdmin(admin)`: the column names a View's rows carry in the browser, for an MCP App to match. */",
+            `export const admin: AdminMeta<AppAdminTypes> = { rowNames: ${q(Object.fromEntries(views.flatMap(([name], n) => Object.keys(renames[n]).length ? [[name, renames[n]]] : [])))} };`,
+            "",
+            "export const { useView, useEntries, useEntry, useOperation, useCollectionTotal, useMe, useBadges } = createAdminHooks<AppAdminTypes>();",
+            "",
+        ].join("\n") };
+}

package/dist/usecase/adminDescriptors.js

@@ -0,0 +1,107 @@
+/** Build-time projections only; generated exports are static, independently tree-shakable data. */
+import { isPrimaryCollection, mcpTools, mcpToolNameSegment, toolTitle, collectionOf, developerConsole, rowPreconditions, appCatalog, entrySchema } from "../build/compiler.js";
+import { q } from "../domain/entry.js";
+import { advertised } from "./validation.js";
+import { publishingAnnotations, publishingInput, publishingTransitions } from "./publishing.js";
+import { versioned } from "./tool-version.js";
+export function emitAdminDescriptors({ plan, admin = false }, diagnostics) {
+    const schemaList = Object.values(plan.schemas);
+    const placed = [...schemaList.map(s => ["schemas/" + s.name, s.uiSchema, s]), ...Object.entries(plan.views).map(([name, v]) => ["views/" + name, v.uiSchema, null])];
+    for (const [path, ui, s] of placed) {
+        const nav = (ui?.["nav"] ?? {}), group = nav["group"];
+        // a child folded under its parent, or a translation on its parent's language tabs, has no sidebar entry to place
+        if (s && !isPrimaryCollection(s, schemaList))
+            for (const key of ["group", "order", "hidden"])
+                if (nav[key] !== undefined)
+                    diagnostics.push({ code: "SCHEMA_UI_INVALID", path: `${path}/uiSchema/nav/${key}`, message: s.translates ? `Schema '${s.name}' has no sidebar entry to place: it is a translation, shown on its parent's language tabs.` : `Schema '${s.name}' has no sidebar entry to place: it is folded under its parent${collectionOf(s, schemaList).parent?.parentField === "id" ? "; nav.standalone: true lists it in the sidebar." : " and opens from its parent's workbench (standalone needs a required id reference)."}` });
+    }
+    if (diagnostics.length)
+        return {};
+    const schemas = Object.values(plan.schemas);
+    const allCollections = Object.fromEntries(schemas.map(s => [s.name, { ...collectionOf(s, schemas), ...(admin ? { scopeField: s.scope ? s.names[s.scope] ?? s.scope : null, exportFields: Object.keys(s.fields).filter(f => f !== s.scope && s.fields[f] !== "geo").map(f => s.names[f] ?? f) } : {}) }]));
+    const viewNames = Object.create(null);
+    const views = Object.entries(plan.views).filter(([, v]) => v.surface === "admin").map(([name, v]) => {
+        const columns = Object.fromEntries(Object.entries(v.columns ?? {}).map(([key, column]) => {
+            const schema = plan.schemas[column.schema], field = schema.names[column.field] ?? column.field;
+            const output = key === column.field ? field : key;
+            (viewNames[name] ??= Object.create(null))[key] = output;
+            return [output, { schema: schema.name, field }];
+        }));
+        const list = (v.uiSchema?.list ?? {});
+        return { name, title: v.title ?? null, description: v.description ?? null, input: v.input ?? null, list: { columns: list.columns ?? [], searchFields: list.searchFields ?? [], filterFields: list.filterFields ?? [] }, columns, ...(v.uiSchema?.nav ? { nav: v.uiSchema.nav } : {}) };
+    });
+    const adminTools = mcpTools(plan, "admin"), toolNames = new Set(adminTools.map(t => t.name));
+    const operations = adminTools.filter(t => t.kind === "procedure").map(t => {
+        const p = plan.procedures[t.source];
+        const preconditions = p.target && "sql" in p.handler ? rowPreconditions(p.handler.sql.stmts, p.target.schema, p.target.id, plan.schemas[p.target.schema.toLowerCase()]?.schema ?? {}) : [];
+        return { ...(preconditions.length ? { preconditions } : {}), name: t.source, title: p.title ?? null, description: p.description ?? null, input: p.input, uiSchema: p.uiSchema ?? null, interactions: p.target ? [{ collection: p.target.schema, bind: [{ input: p.target.id, field: "id" }], ...(p.target.version ? { version: p.target.version } : {}), mutates: true }] : [] };
+    });
+    const authorizations = { views: Object.fromEntries(views.map(v => [v.name, plan.views[v.name].requires ?? null])), procedures: Object.fromEntries(Object.entries(plan.procedures).map(([name, p]) => [name, p.requires ?? null])) };
+    const adminCatalogue = appCatalog(plan, "admin");
+    const catalogues = { public: appCatalog(plan, "public"), admin: { views: Object.fromEntries(Object.entries(adminCatalogue.views).map(([name, v]) => [name, { ...v, actions: [...v.actions] }])), actions: { ...adminCatalogue.actions } } };
+    const snapshot = developerConsole(plan);
+    const webmcp = { tools: adminTools.map(({ name, source, kind, title, description, inputSchema, outputSchema, annotations }) => ({ target: { kind, name: source }, ...versioned({ name, ...(title ? { title: (kind === "view" ? plan.views[source] : plan.procedures[source]).title ?? title } : {}), ...advertised(inputSchema, (kind === "view" ? plan.views[source] : plan.procedures[source]).description ?? description), ...(outputSchema ? { outputSchema } : {}), ...(annotations ? { annotations } : {}) }) })), routes: Object.fromEntries(adminTools.flatMap(t => {
+            if (t.kind === "view")
+                return [[t.name, { path: "/admin/views/" + encodeURIComponent(t.source) }]];
+            const target = plan.procedures[t.source].target;
+            return target ? [[t.name, { path: "/admin/c/" + encodeURIComponent(plan.schemas[target.schema.toLowerCase()]?.name ?? target.schema), entry: true }]] : [];
+        })) };
+    // These are the actual generated transitions, not authored ref handlers or SQL IR.
+    for (const schema of schemas.filter(s => s.publishing))
+        for (const [verb] of publishingTransitions) {
+            const name = schema.name + "." + verb, tool = mcpToolNameSegment(verb + "_" + schema.name);
+            if (toolNames.has(tool)) {
+                diagnostics.push({ code: "GENERATE_UNSUPPORTED", path: "schemas/" + schema.name, message: "Generated publishing tool '" + tool + "' conflicts with an admin tool." });
+                continue;
+            }
+            toolNames.add(tool);
+            const action = { capability: tool, inputSchema: publishingInput, bind: [{ input: "id", field: "id" }], version: "expectedVersion", mutates: true };
+            catalogues.admin.actions[tool] = action;
+            for (const t of adminTools.filter(t => t.kind === "view"))
+                if (entrySchema(plan, plan.views[t.source]) === schema.name.toLowerCase())
+                    catalogues.admin.views[t.name].actions.push(tool);
+            authorizations.procedures[name] = { auth: { all: ["ctx.admin"] } };
+            const description = verb + " an entry in " + schema.name + ".";
+            webmcp.tools.push({ target: { kind: "procedure", name }, ...versioned({ name: tool, title: toolTitle(verb + "_" + schema.name), description, inputSchema: publishingInput, annotations: publishingAnnotations(verb) }) });
+            webmcp.routes[tool] = { path: "/admin/c/" + encodeURIComponent(schema.name), entry: true };
+            snapshot.interfaces.callable.push({ kind: "procedure", name: tool, target: name, surface: "admin", audience: "admin", title: null, description, input: publishingInput, output: null, trigger: null });
+        }
+    const data = { allCollections, views, operations, fieldNames: Object.fromEntries(schemas.map(s => [s.name, s.names])), viewNames, authorizations, developerConsole: snapshot, mcpAppCatalogues: catalogues, webmcp };
+    return { "admin-descriptors.ts": "// Generated static Admin metadata. Import only the exports the application uses.\n" + literals(data) + "\nexport const collections = [" + schemas.filter(s => !s.translates).map(s => "allCollections[" + q(s.name) + "]").join(",") + "] as const;\nexport const bootstrap = {collections, allCollections, operations, views, webmcp, developerConsole} as const;\n" };
+}
+/**
+ * Each export as a JSON literal; a subtree of 40 or more bytes that would be printed more than once is printed once, as a
+ * module-private constant the exports reference (a bundler keeps only those an imported export reaches).
+ */
+function literals(exports) {
+    const data = JSON.parse(q(exports)), count = new Map(), hoisted = new Map(), constants = [];
+    const each = (value, visit) => { if (value && typeof value === "object")
+        for (const child of Object.values(value))
+            if (child && typeof child === "object")
+                visit(q(child), child); };
+    const tally = (json, value, by = 1) => { if (json.length >= 40)
+        count.set(json, (count.get(json) ?? 0) + by); each(value, (json, child) => tally(json, child, by)); };
+    for (const value of Object.values(data))
+        each(value, tally);
+    // Longest first: once a subtree is printed once, what it contains occurs (copies - 1) times fewer per occurrence in it.
+    for (const json of [...count.keys()].sort((a, b) => b.length - a.length)) {
+        const copies = count.get(json);
+        if (copies > 1) {
+            hoisted.set(json, "");
+            each(JSON.parse(json), (inner, child) => tally(inner, child, 1 - copies));
+        }
+    }
+    let named = 0;
+    const print = (value) => !value || typeof value !== "object" ? q(value) : Array.isArray(value) ? "[" + value.map(reference).join(",") + "]" : "{" + Object.entries(value).map(([key, child]) => (key === "__proto__" ? "[" + q(key) + "]" : q(key)) + ":" + reference(child)).join(",") + "}";
+    const reference = (value) => {
+        const json = q(value);
+        if (hoisted.get(json) === "") {
+            const name = "$" + named++;
+            hoisted.set(json, name);
+            constants.push("const " + name + " = " + print(value) + " as const;");
+        }
+        return hoisted.get(json) ?? print(value);
+    };
+    const lines = Object.entries(data).map(([name, value]) => "export const " + name + " = " + print(value) + " as const;");
+    return [...constants, ...lines].join("\n");
+}

package/dist/usecase/generate.js

@@ -0,0 +1,166 @@
+import { userReferences } from "../domain/userReferences.js";
+/** Canonical lowered programs become ordinary target-specific TypeScript, never a runtime plan. */
+import { parseNumeric, tableOutputs } from "../build/compiler.js";
+import { boundaryType, nativeType, outputType, wireType } from "../domain/columns.js";
+import { databaseImport, driverFor, entry, exportName, generatedFiles, isSqlite as sqlite, q } from "../domain/entry.js";
+import { authLines as auth } from "../domain/input.js";
+import { recipesOf } from "../domain/recipes.js";
+import { emitTtl } from "./ttl.js";
+import { emitPublishing } from "./publishing.js";
+import { emitStores } from "./stores.js";
+import { emitPaging } from "./paging.js";
+import { emitWeb } from "./web.js";
+import { emitMcp } from "./mcp.js";
+import { emitValidation } from "./validation.js";
+import { refuseDeclarations } from "./refusals.js";
+import { emitHandlers } from "./handlers.js";
+import { emitAdminDescriptors } from "./adminDescriptors.js";
+import { emitAdminClient } from "./adminClient.js";
+import { emitSite } from "./site.js";
+import { emitTranslations } from "./translations.js";
+import { emitAdminBindings } from "./adminBindings.js";
+import { emitRest } from "./rest.js";
+const typeOf = (s) => {
+    if (!s)
+        return "unknown";
+    if (s.nullable === true)
+        return `${typeOf({ ...s, nullable: false })} | null`;
+    if (s.enum)
+        return s.enum.map(v => q(v)).join(" | ") || "never";
+    if (s.const !== undefined)
+        return q(s.const);
+    if (Array.isArray(s.type))
+        return s.type.map(type => typeOf({ ...s, type })).join(" | ") || "never";
+    switch (s.type) {
+        case "string": return "string";
+        case "integer":
+        case "number": return "number";
+        case "boolean": return "boolean";
+        case "null": return "null";
+        case "array": return `ReadonlyArray<${Array.isArray(s.items) ? "unknown" : typeOf(s.items)}>`;
+        case "object": return `{ ${Object.entries(s.properties ?? {}).map(([key, child]) => `readonly ${q(key)}${s.required?.includes(key) ? "" : "?"}: ${typeOf(child)};`).join(" ")} ${s.additionalProperties !== false ? "readonly [key: string]: unknown;" : ""} }`;
+        default: return "unknown";
+    }
+};
+export function generate(input) {
+    const { target, plan, lowered, viewKeys, newId, site, admin, paging } = input;
+    const diagnostics = [];
+    refuseDeclarations({ plan }, diagnostics);
+    const refuse = (path, message) => { diagnostics.push({ code: "GENERATE_UNSUPPORTED", path, message }); };
+    const isSqlite = sqlite(target);
+    const user = userReferences(plan, isSqlite);
+    const expected = isSqlite ? "@aotter/mantle/d1" : "@aotter/mantle/postgres";
+    if (lowered.dialect.name !== expected || plan.dialect.name !== expected)
+        refuse("target", `Target '${target}' needs canonical '${expected}' compilation and lowering.`);
+    const driver = driverFor(target);
+    const queryInputType = (schema, statements) => {
+        if (!schema?.properties)
+            return typeOf(schema);
+        const binds = statements.flatMap(s => s.binds).filter(b => b.k === "input");
+        const properties = Object.entries(schema.properties).map(([name, field]) => {
+            const bind = binds.find(b => b.k === "input" && name.toLowerCase() === String(b.name).toLowerCase());
+            if (!bind || bind.k !== "input")
+                return `readonly ${q(name)}${schema.required?.includes(name) ? "" : "?"}: ${typeOf(field)};`;
+            const type = String(bind.type);
+            const driverType = type === "json" ? typeOf(field) : type === "date" ? "string" : type === "timestamptz" ? "string | Date" : isSqlite
+                ? type === "bool" || parseNumeric(type) ? "number" : typeOf(field)
+                : parseNumeric(type) ? "number | string" : typeOf(field);
+            const nullable = field.nullable === true || Array.isArray(field.type) && field.type.includes("null") || !schema.required?.includes(name);
+            // D1 cannot bind undefined. Bound fields are explicit, null represents absence.
+            return `readonly ${q(name)}: ${driverType}${nullable ? " | null" : ""};`;
+        });
+        return `{ ${properties.join(" ")} ${schema.additionalProperties !== false ? "readonly [key:string]: unknown;" : ""} }`;
+    };
+    const inputFields = (schema, path) => {
+        const fields = Object.keys(schema?.properties ?? {});
+        if (new Set(fields.map(field => field.toLowerCase())).size !== fields.length)
+            refuse(path, "Input properties must have unique case-insensitive names. Rename input properties to be unique without regard to case.");
+        return fields;
+    };
+    // The dialect functions the bind recipes call, so a bundle carries only those (`binds` takes this object).
+    const values = new Set();
+    /** A statement as a constant: its text and how to bind it. */
+    const step = (s, path, fields, row = false) => {
+        const recipes = recipesOf(s, fields, message => refuse(path, message));
+        for (const r of recipes) {
+            if (r.k === "now" || r.k === "cutoff")
+                values.add(r.k);
+            else if (r.k === "input" && r.type)
+                values.add(r.type === "date" ? "date" : "timestamp");
+        }
+        return `{ sql: ${q(s.sql)}, binds: ${q(recipes)}${row ? ", row: true" : ""} }`;
+    };
+    const declarations = [], views = [], procedures = [], refProcedures = [];
+    const entries = {};
+    const base = "@aotter/mantle/";
+    const refNames = emitHandlers(plan, target !== "cloudflare-d1", typeOf, declarations, refProcedures);
+    const hasHandlers = refNames.length > 0;
+    for (const [index, [name, view]] of Object.entries(plan.views).sort().entries()) {
+        const path = `views/${name}`, fn = `view${index}`;
+        const modes = lowered.views[name];
+        const mode = view.surface === "public" ? "public" : "caller";
+        const c = modes?.[mode], trusted = modes?.trusted;
+        if (!c || (mode === "caller" && !trusted)) {
+            refuse(path, "Every reachable visibility mode must have canonical lowered SQL.");
+            continue;
+        }
+        const keys = Object.hasOwn(viewKeys, name) ? viewKeys[name] : undefined;
+        if (!keys || new Set(keys).size !== keys.length) {
+            refuse(path, "Dynamic or repeated View outputs need an explicit generated row contract. Give each SELECT output a unique explicit alias.");
+            continue;
+        }
+        const output = [], direct = tableOutputs(view, plan.schemas);
+        for (const key of keys) {
+            // A table column read unchanged keeps its NOT NULL (and gives a native column such as `id` its type); anything else may be NULL.
+            const type = outputType(plan, name, key) ?? direct[key]?.type;
+            // Declared timestamps and dates arrive formatted by the SQL itself (domain/wireScalars).
+            output.push(`readonly ${q(key)}: ${nativeType(type, isSqlite, direct[key]?.notNull)};`);
+        }
+        const fieldNames = inputFields(view.input, path + "/input");
+        const callerStep = step(c, path, fieldNames), trustedStep = mode === "caller" ? step(trusted, path, fieldNames) : callerStep;
+        declarations.push(`export type View${index}Input = ${queryInputType(view.input ?? { type: "object", additionalProperties: false }, [c, ...(trusted ? [trusted] : [])])};`, `export type View${index}Row = { ${output.join(" ")} };`, `export type View${index}WireRow = { ${keys.map(key => `readonly ${q(key)}: ${boundaryType(plan, name, key) ? wireType(boundaryType(plan, name, key), direct[key]?.notNull) : `View${index}Row[${q(key)}]`};`).join(" ")} };`, `const ${fn}Caller = ${callerStep} as const;`, ...(trustedStep !== callerStep ? [`const ${fn}Trusted = ${trustedStep} as const;`] : []), `async function ${fn}(db: ${isSqlite ? "Database" : "Unsafe"}, caller: Caller, raw: View${index}Input): Promise<View${index}Row[]> {`, ...auth(view.requires, path), ...(user.used ? ['  USER.modeOf(caller);'] : []), `  const m = ${trustedStep !== callerStep ? `${user.used ? 'USER.modeOf(caller) === "trusted"' : 'caller.kind === "system"'} ? ${fn}Trusted : ` : ""}${fn}Caller;`, `  return DRIVER.read(db, ${user.used ? "USER.scoped(m.sql, caller)" : "m.sql"}, binds(D, m.binds, caller, raw));`, "}");
+        views.push(`[${q(name)}]: ${fn}`);
+        declarations.push(`export { ${fn} as ${exportName("view", name)} };`);
+        entries[`views/${encodeURIComponent(name)}.ts`] = entry("view", name, `View${index}Input as Input, View${index}Row as Row, View${index}WireRow as WireRow`);
+    }
+    for (const [index, [name, procedure]] of Object.entries(plan.procedures).sort().entries()) {
+        const path = `procedures/${name}`, fn = `procedure${index}`;
+        if (!("sql" in procedure.handler))
+            continue;
+        const modes = lowered.procedures[name];
+        if (!modes?.caller || !modes.trusted) {
+            refuse(path, "Both caller and trusted SQL must be lowered.");
+            continue;
+        }
+        if ([...modes.caller, ...modes.trusted].some(s => s.publish || s.schema && plan.schemas[s.schema]?.publishing))
+            refuse(path, "A SQL Procedure cannot write a publishing Schema: create and edit its rows from a ref handler through the Store (`ctx.store.collection(...)`), and change status with the generated `<schema>.publish` / `.unpublish` / `.archive` transitions.");
+        const fieldNames = inputFields(procedure.input, path + "/input");
+        const steps = (statements) => `[${statements.map(s => step(s, path, fieldNames, s.kind === "row")).join(", ")}] as const`;
+        const same = steps(modes.caller) === steps(modes.trusted);
+        declarations.push(`export type Procedure${index}Input = ${queryInputType(procedure.input, [...modes.caller, ...modes.trusted])};`, `const ${fn}Caller = ${steps(modes.caller)};`, ...(same ? [] : [`const ${fn}Trusted = ${steps(modes.trusted)};`]), `async function ${fn}(db: Database, caller: Caller, raw: Procedure${index}Input): Promise<Output> {`, ...(modes.caller.some(s => s.kind !== "read") ? [`  if ("authenticatedAs" in caller && caller.authenticatedAs === "snapshot") (await import("@aotter/mantle/host-caller")).checkFresh(caller, false, ${q(path)});`] : []), ...auth(procedure.requires, path), ...(user.used ? ['  USER.modeOf(caller);'] : []), ...(procedure.trustedOnly ? [`  deny(caller, USER.modeOf(caller) === "trusted", ${q(path)});`] : []), `  return { results: await DRIVER.procedure(db, bound(D, ${user.used ? "USER.scopedAll(" : ""}${same ? "" : `${user.used ? 'USER.modeOf(caller) === "trusted"' : 'caller.kind === "system"'} ? ${fn}Trusted : `}${fn}Caller${user.used ? ", caller)" : ""}, caller, raw), ${q(path)}) };`, "}");
+        procedures.push(`[${q(name)}]: ${fn}`);
+        declarations.push(`export { ${fn} as ${exportName("procedure", name)} };`);
+        entries[`procedures/${encodeURIComponent(name)}.ts`] = entry("procedure", name, `Procedure${index}Input as Input`, `export type { Output } from "${base}contracts";\n`);
+    }
+    emitTtl(plan, isSqlite, declarations, procedures, entries, refuse);
+    emitPublishing(plan, isSqlite, declarations, procedures, entries, values, refuse);
+    const stores = emitStores(plan.schemas, isSqlite, newId, refuse, hasHandlers);
+    const surfaces = { ...emitPaging(plan, lowered, target, refuse, paging), ...emitPaging(plan, input.wireLowered ?? lowered, target, refuse, paging, true), ...emitValidation(plan, refuse), ...emitRest(plan, lowered, target, input.description), ...emitWeb(plan, lowered, target), ...emitMcp(plan, lowered, target, input.description, refuse, !!site), ...emitAdminDescriptors({ plan, admin }, diagnostics), ...emitAdminBindings(input, refuse), ...(admin ? emitAdminClient(plan, typeOf) : {}), ...emitSite(target, site, refuse, Object.keys(plan.schemas)), ...emitTranslations(plan, target) };
+    if (diagnostics.length)
+        return { ok: false, diagnostics };
+    const storeProcedures = hasHandlers ? "storeProcedures" : "procedures";
+    const code = [...(Object.keys(plan.access?.userFields ?? {}).length ? [`export const userFields = ${q(plan.access.userFields)} as const;`] : []), ...declarations, `export const views = { ${views.join(", ")} };`, `export const procedures = { ${procedures.join(", ")} };`, ...(stores ? [
+            `export type Tables = ${stores.tables};`, `const RULES = ${stores.rules} as const;`,
+            ...(hasHandlers ? [`const storeProcedures = { ${[...procedures, ...refProcedures].join(", ")} };`] : []),
+            `const initStore = () => createStore<Database, Tables, typeof DRIVER, { views: typeof views; procedures: typeof ${storeProcedures} }${hasHandlers ? ", { handlers: Handlers }" : ""}>(${user.used ? "{...DIALECT.dialect, ...USER_VALUES}" : "DIALECT.dialect"}, DRIVER, RULES, ${stores.facts}, { views, procedures: ${storeProcedures} });`,
+            `let makeStore: ReturnType<typeof initStore>;`,
+            `export function store${hasHandlers ? "<const H extends Handlers>" : ""}(db: Database, caller: Caller${hasHandlers ? ", options: { handlers: H & Record<Exclude<keyof H, keyof Handlers>, never> }" : ", _options?: { handlers?: Handlers }"}): ReturnType<typeof makeStore> { return (makeStore ??= initStore())(db, caller${hasHandlers ? ", options" : ""}); }`,
+        ] : [])].join("\n");
+    const dialect = `${base}dialect/${isSqlite ? "sqlite" : "postgres"}`;
+    const contracts = [...(target.endsWith("postgres") ? ["type Postgres as Database", ...(views.length ? ["type Unsafe"] : [])] : []), "type Caller", ...(hasHandlers ? ["ContractError"] : []), ...(/^  deny\(/m.test(code) ? ["deny", ...(/\bisAdmin\(/.test(code) ? ["isAdmin"] : []), ...(/\bisUser\(/.test(code) ? ["isUser"] : [])] : []), ...(procedures.length ? ["type Output"] : [])];
+    const dbType = isSqlite ? databaseImport(target) : "";
+    return { ok: true, refProcedures: refNames, files: generatedFiles({ ...surfaces, ...entries, "generated.ts": ["// Generated native application SQL. No runtime plan or interpreter.", user.code, dbType, `import { ${contracts.join(", ")} } from "${base}contracts";`,
+                ...(values.size || stores ? [`import * as DIALECT from "${dialect}";`] : []), `import * as DRIVER from "${base}driver/${driver}";`, ...((names => names.length ? [`import { ${names.join(", ")} } from "${base}store";`] : [])([...(stores ? ["createStore"] : []), ...(hasHandlers && target !== "cloudflare-d1" ? ["handlerTransaction"] : [])])),
+                `import { ${procedures.length ? "binds, bound" : "binds"} } from "${base}binds";`,
+                `const D = { ${[...values].sort().map(v => `${v}: DIALECT.${v}`).concat(user.values ? [user.values] : []).join(", ")} };`, code].filter(Boolean).join("\n") + "\n" }) };
+}

package/dist/usecase/handlers.js

@@ -0,0 +1,21 @@
+import { authLines as auth } from "../domain/input.js";
+import { q } from "../domain/entry.js";
+export function emitHandlers(plan, interactive, typeOf, declarations, procedures) {
+    const refs = Object.entries(plan.procedures).sort().map(([name, procedure], index) => ({ name, procedure, index })).filter(({ procedure }) => "ref" in procedure.handler);
+    // An empty contract keeps app wiring (`handlers: Handlers = {}`) identical whether or not any ref Procedure exists.
+    if (!refs.length) {
+        declarations.push("export interface Handlers {}");
+        return [];
+    }
+    declarations.push('export type HandlerStore = Pick<ReturnType<typeof makeStore>, "collection" | "views" | "procedures">;', 
+    // D1 has no interactive transactions, so its handlers get no `transaction`: using one there fails typecheck.
+    `export interface HandlerContext { readonly caller: Caller; readonly db: Database; readonly store: HandlerStore;${interactive ? " readonly transaction: <R>(fn: (ctx: { readonly store: HandlerStore; readonly db: Database }) => Promise<R>) => Promise<R>;" : ""} }`, "export interface Handlers {", ...refs.map(({ name, index }) => `  readonly [${q(name)}]: (ctx: HandlerContext, input: Procedure${index}Input) => Promise<Procedure${index}Output>;`), "}");
+    for (const { name, procedure, index } of refs) {
+        const path = `procedures/${name}`, fn = `procedure${index}`;
+        declarations.push(`export type Procedure${index}Input = ${typeOf(procedure.input ?? { type: "object", additionalProperties: false })};`, `export type Procedure${index}Output = ${typeOf(procedure.output)};`, `async function ${fn}(db: Database, caller: Caller, raw: Procedure${index}Input, context: { handlers: Handlers; store: HandlerContext["store"] }): Promise<Procedure${index}Output> {`, `  if ("authenticatedAs" in caller && caller.authenticatedAs === "snapshot") (await import("@aotter/mantle/host-caller")).checkFresh(caller, false, ${q(path)});`, ...auth(procedure.requires, path), "  const handlers = context?.handlers;", `  const handler = handlers && Object.hasOwn(handlers, ${q(name)}) ? handlers[${q(name)}] : undefined;`, `  if (!handler) throw new ContractError("HANDLER_NOT_REGISTERED", "Procedure handler is not registered.", ${q(path)});`, 
+        // TODO #1470: REST/MCP use shared generated validators at the boundary; bare calls stay typed.
+        `  return handler({ caller, db, store: context.store${interactive ? ", transaction: handlerTransaction(context.store, db)" : ""} }, raw);`, "}");
+        procedures.push(`[${q(name)}]: ${fn}`);
+    }
+    return refs.map(({ name }) => name);
+}

package/dist/usecase/mcp-media.js

@@ -0,0 +1,17 @@
+import { emitValidation } from "./validation.js";
+import { mediaDefinitions } from "../domain/generated-tools.js";
+export { mediaDefinitions };
+/** `definitions` are the versioned media tools, computed once by the MCP emitter. */
+export function emitMcpMedia(definitions, refuse) {
+    const inputs = Object.fromEntries(definitions.map(tool => [tool.name, { input: tool.inputSchema }]));
+    const checks = Object.fromEntries(Object.entries(emitValidation({ views: {}, procedures: inputs }, refuse)).map(([path, code]) => [path.replace("validation/procedures/", "validation/media/"), code]));
+    const invoke = { policy: 'async (db,caller) => ({purposes:(await site(db,caller).read()).media.purposes})', create: '(db,caller,input:Record<string,unknown>) => site(db,caller).media(storage()).createUpload(input)', commit: '(db,caller,input:Record<string,unknown>) => site(db,caller).media(storage()).commitUpload(input.uploadGroupId as string,input)', list: '(db,caller,input:Record<string,unknown>) => site(db,caller).media(storage()).list(input)', get: '(db,caller,input:Record<string,unknown>) => site(db,caller).media(storage()).get(input.id as string)', update: '(db,caller,input:Record<string,unknown>) => site(db,caller).media(storage()).update(input.id as string,input)', delete: '(db,caller,input:Record<string,unknown>) => site(db,caller).media(storage()).delete(input.id as string)' };
+    return { ...checks, "mcp-media.ts": `import { site } from "./site.js";
+import type { MediaStorage } from "@aotter/mantle/site";
+import type { Tool } from "@aotter/mantle/mcp";
+${definitions.map((tool, i) => `import { validate as v${i} } from "./validation/media/${tool.name}.js";`).join("\n")}
+export function mediaTools<Handlers = never>(storage: () => MediaStorage): Tool<Parameters<typeof site>[0], Handlers>[] { return [
+${definitions.map(({ action, ...tool }, i) => `{...${JSON.stringify({ ...tool, ...(tool.annotations.readOnlyHint ? { readOnly: true } : {}) })},surface:"admin",closed:true,validate:v${i},run:${invoke[action]}}`).join(",\n")}
+]; }
+` };
+}