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

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

@@ -1,36 +1,19 @@
 /** Build-time projections only; generated exports are static, independently tree-shakable data. */
-import { DiagnosticError, BUILT_IN_NAV_GROUPS, navGroupProblems, formSchemaProblem, mcpTools, mcpToolNameSegment, collectionOf, developerConsole, rowPreconditions, checkPlanUiExtensions, planUiExtensionRefs, appCatalog, entrySchema } from "../build/compiler.js";
+import { isPrimaryCollection, mcpTools, mcpToolNameSegment, toolTitle, collectionOf, developerConsole, rowPreconditions, appCatalog, entrySchema } from "../build/compiler.js";
 import { q } from "../domain/entry.js";
-import { emitValidation } from "./validation.js";
-import { publishingInput, publishingTransitions } from "./publishing.js";
-const adminEnum = (p) => { if (!p.oneOf)
-    return p; const { oneOf, ...rest } = p; return { ...rest, enum: oneOf.map(c => c.const) }; };
-export function emitAdminDescriptors({ plan, adminExtensions = [], navGroups = [], admin = false }, diagnostics) {
-    // Sidebar placement: every nav.group names a built-in group or a declared navGroups id (presentation only).
-    for (const [path, message] of navGroupProblems(navGroups))
-        diagnostics.push({ code: "SCHEMA_UI_INVALID", path, message });
-    const groupIds = new Set([...Object.keys(BUILT_IN_NAV_GROUPS), ...(Array.isArray(navGroups) ? navGroups.map(g => g.id) : [])]);
-    const placed = [...Object.values(plan.schemas).map(s => ["schemas/" + s.name, s.uiSchema]), ...Object.entries(plan.views).map(([name, v]) => ["views/" + name, v.uiSchema])];
-    for (const [path, ui] of placed) {
-        const group = ui?.["nav"]?.group;
-        if (typeof group === "string" && !groupIds.has(group))
-            diagnostics.push({ code: "SCHEMA_UI_INVALID", path: path + "/uiSchema/nav/group", message: `Unknown nav group '${group}': use content, operations, reports or more, or declare it in navGroups of the --admin-extensions module.` });
-    }
-    for (const e of adminExtensions)
-        for (const p of e.contributes.pages ?? []) {
-            const group = p.nav?.group;
-            if (group !== undefined && group !== "settings" && !groupIds.has(group))
-                diagnostics.push({ code: "UI_EXTENSION_INVALID", path: `admin/extensions/${e.id}/pages/${p.id}/nav/group`, message: `Unknown nav group '${group}'.` });
-        }
-    try {
-        checkPlanUiExtensions(plan, adminExtensions);
-    }
-    catch (error) {
-        if (!(error instanceof DiagnosticError))
-            throw error;
-        const { code, path, message } = error.diagnostic;
-        diagnostics.push({ code, path, message });
-        return {};
+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 {};
@@ -45,7 +28,7 @@ export function emitAdminDescriptors({ plan, adminExtensions = [], navGroups = [
             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 ?? [], cells: list.cells ?? {} }, columns, ...(v.uiSchema?.nav ? { nav: v.uiSchema.nav } : {}) };
+        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 => {
@@ -57,7 +40,7 @@ export function emitAdminDescriptors({ plan, adminExtensions = [], navGroups = [
     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 }) => ({ name, target: { kind, name: source }, ...(title ? { title: (kind === "view" ? plan.views[source] : plan.procedures[source]).title ?? title } : {}), description: (kind === "view" ? plan.views[source] : plan.procedures[source]).description ?? description, inputSchema, ...(outputSchema ? { outputSchema } : {}), ...(annotations ? { annotations } : {}) })), routes: Object.fromEntries(adminTools.flatMap(t => {
+    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;
@@ -79,41 +62,12 @@ export function emitAdminDescriptors({ plan, adminExtensions = [], navGroups = [
                     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({ name: tool, target: { kind: "procedure", name }, description, inputSchema: publishingInput, annotations: { readOnlyHint: false, destructiveHint: verb === "archive" } });
+            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 extensionIds = new Set();
-    const extensionMetadata = adminExtensions.map(extension => {
-        if (!/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(extension.id) || extensionIds.has(extension.id) || extension.apiVersion !== undefined && extension.apiVersion !== 1)
-            diagnostics.push({ code: "UI_EXTENSION_INVALID", path: "admin/extensions/" + extension.id, message: "Extensions need unique kebab-case ids and apiVersion 1." });
-        extensionIds.add(extension.id);
-        const { source, handlers: _handlers, bodyLimit: _bodyLimit, ...declaration } = extension;
-        if (source !== undefined)
-            diagnostics.push({ code: "GENERATE_UNSUPPORTED", path: "admin/extensions/" + extension.id, message: "Native Admin uses host-served module paths; source modules are not served. Set module and install its integrity in the host shell import map." });
-        if (extension.module && (!extension.module.startsWith("/") || extension.module.startsWith("//") || /[\\?#]/.test(extension.module)))
-            diagnostics.push({ code: "UI_EXTENSION_INVALID", path: "admin/extensions/" + extension.id, message: "module must be a same-origin absolute path." });
-        return { id: extension.id, declaration: JSON.stringify(declaration), public: declaration, ...(extension.module ? { module: extension.module } : {}), ...(extension.integrity ? { integrity: extension.integrity } : {}), source: false, settings: (extension.contributes.settings ?? []).map(s => s.id), actions: (extension.contributes.actions ?? []).map(a => ({ id: a.id, target: a.target, ...(a.when?.schema ? { schema: a.when.schema } : {}) })) };
-    });
-    const checks = [], validationFiles = {};
-    for (const extension of adminExtensions)
-        for (const settings of extension.contributes.settings ?? []) {
-            const key = extension.id + "/" + settings.id, problem = formSchemaProblem(settings.schema);
-            if (problem) {
-                diagnostics.push({ code: "UI_EXTENSION_INVALID", path: "admin/extensions/" + key, message: problem });
-                continue;
-            }
-            const input = { ...settings.schema, additionalProperties: false, properties: Object.fromEntries(Object.entries(settings.schema.properties ?? {}).map(([name, p]) => [name, adminEnum(p)])) };
-            const file = extension.id + "__" + settings.id; // ponytail: no "/" so Node ESM can import the emitted module
-            const generated = emitValidation({ views: {}, procedures: { [file]: { input } } }, (path, message) => diagnostics.push({ code: "GENERATE_UNSUPPORTED", path, message }));
-            Object.assign(validationFiles, generated);
-            const alias = "check" + checks.length;
-            checks.push(`import {validate as ${alias}} from "./validation/procedures/${encodeURIComponent(file)}.js";`);
-        }
-    const settingsKeys = adminExtensions.flatMap(e => (e.contributes.settings ?? []).map(s => e.id + "/" + s.id));
-    const bindings = "import {extensionOptions} from '@aotter/mantle-admin/server/extensions';\nimport type {AdminExtension} from '@aotter/mantle-admin/server/extensions';\nimport {extensionMetadata} from './admin-descriptors.js';\nimport {ContractError} from '@aotter/mantle/contracts';\n" + checks.join("\n") + "\nconst checks={" + settingsKeys.map((key, n) => `${q(key)}:(value:unknown)=>{try{check${n}(value);return {};}catch(error){if(!(error instanceof ContractError))throw error;return {[(error.path.split('/input/')[1]??'').replace(/~1/g,'/').replace(/~0/g,'~')]:error.message};}}`).join(",") + "};\nexport const extensionBindings=<Env,DB>(definitions:readonly AdminExtension<Env,DB>[])=>extensionOptions<Env,DB>(extensionMetadata,checks,definitions);\n";
-    const data = { allCollections, views, operations, navGroups, fieldNames: Object.fromEntries(schemas.map(s => [s.name, s.names])), viewNames, authorizations, developerConsole: snapshot, mcpAppCatalogues: catalogues, webmcp, extensionBindings: planUiExtensionRefs(plan), extensionMetadata };
-    return { ...validationFiles, ...(adminExtensions.length && admin ? { "admin-extensions.ts": bindings } : {}), "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, navGroups, webmcp, developerConsole} as const;\n" };
+    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

package/dist/usecase/generate.js

@@ -15,6 +15,7 @@ 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";
@@ -42,7 +43,7 @@ const typeOf = (s) => {
     }
 };
 export function generate(input) {
-    const { target, plan, lowered, viewKeys, newId, adminExtensions, site, admin, paging } = 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 }); };
@@ -116,7 +117,7 @@ export function generate(input) {
         }
         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)) : `View${index}Row[${q(key)}]`};`).join(" ")} };`, `const ${fn}Caller = ${callerStep} as const;`, ...(trustedStep !== callerStep ? [`const ${fn}Trusted = ${trustedStep} as const;`] : []), `async function ${fn}(db: Database, 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));`, "}");
+        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)) : `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`);
@@ -143,7 +144,7 @@ export function generate(input) {
     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, adminExtensions, navGroups: input.navGroups, admin }, diagnostics), ...emitAdminBindings(input, refuse), ...emitSite(target, site, refuse, Object.keys(plan.schemas)), ...emitTranslations(plan, target) };
+    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";
@@ -155,7 +156,7 @@ export function generate(input) {
             `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"] : []), "type Caller", ...(hasHandlers ? ["ContractError"] : []), ...(/^  deny\(/m.test(code) ? ["deny", ...(/\bisAdmin\(/.test(code) ? ["isAdmin"] : []), ...(/\bisUser\(/.test(code) ? ["isUser"] : [])] : []), ...(procedures.length ? ["type Output"] : [])];
+    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"] : [])])),

package/dist/usecase/mcp-media.js

@@ -1,8 +1,8 @@
 import { emitValidation } from "./validation.js";
 import { mediaDefinitions } from "../domain/generated-tools.js";
 export { mediaDefinitions };
-export function emitMcpMedia(refuse) {
-    const definitions = 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)' };

package/dist/usecase/mcp.js

@@ -1,19 +1,21 @@
 /** Emit the selected MCP boundary; the official transport loads on its first request. */
-import { mcpToolNameSegment } from "../build/compiler.js";
+import { mcpToolNameSegment, procedureAnnotations, toolTitle, viewAnnotations } from "../build/compiler.js";
 import { emitMcpMedia, mediaDefinitions } from "./mcp-media.js";
-import { emitValidation } from "./validation.js";
-import { databaseImport, q } from "../domain/entry.js";
+import { advertised, emitValidation } from "./validation.js";
+import { databaseImport, literal, q } from "../domain/entry.js";
 import { authLines, conversions } from "../domain/input.js";
-import { publishingInput } from "./publishing.js";
+import { publishingAnnotations, publishingInput } from "./publishing.js";
+import { versioned } from "./tool-version.js";
 import { boundaryPage, outputConversions } from "../domain/columns.js";
 export function emitMcp(plan, lowered, target, description, refuse, media = false) {
     if (!Object.values(plan.views).some(view => view.surface !== "internal") && !Object.values(plan.triggers).some(trigger => trigger.source.kind === "mcp"))
         return {};
     const reads = [];
     const imports = plan.access ? ['import { userBinds } from "@aotter/mantle/user-fields";'] : [], tools = [];
-    const files = media ? emitMcpMedia(refuse) : {};
+    const mediaTools = media ? mediaDefinitions().map(({ action, ...tool }) => ({ action, ...versioned({ ...tool, title: toolTitle(tool.name) }) })) : [];
+    const files = media ? emitMcpMedia(mediaTools, refuse) : {};
     let hasRef = false, hasWire = false;
-    const names = new Set(media ? mediaDefinitions().map(tool => "admin:" + tool.name) : []);
+    const names = new Set(mediaTools.map(tool => "admin:" + tool.name));
     const guard = (requires, path, binds = [], trustedOnly = false) => {
         const lines = authLines(requires, path, binds, !target.endsWith("postgres"), trustedOnly);
         return lines.length ? `, check: (caller) => {${lines.join("")}}` : "";
@@ -36,7 +38,7 @@ export function emitMcp(plan, lowered, target, description, refuse, media = fals
             imports.push(`const run${index}: typeof import(${q(module)}).default = async (...args) => (await import(${q(module)})).default(...args);`);
         }
         // The kernel adds a View tool's `limit` and `cursor` paging properties.
-        const schema = q(kind === "views" ? operation.input ?? { type: "object", additionalProperties: false } : operation.input);
+        const { inputSchema, description: about } = advertised(kind === "views" ? operation.input ?? { type: "object", additionalProperties: false } : operation.input, operation.description ?? operation.title ?? name), schema = literal(inputSchema);
         if (kind === "views" && ("limit" in (operation.input?.properties ?? {}) || "cursor" in (operation.input?.properties ?? {})))
             refuse(`views/${name}`, "MCP View input reserves limit and cursor for paging.");
         if (names.has(surface + ":" + tool))
@@ -45,12 +47,14 @@ export function emitMcp(plan, lowered, target, description, refuse, media = fals
         const convert = conversions(operation.input?.properties, binds, target), scopes = (operation.requires?.auth?.all ?? []).flatMap(p => typeof p === "object" && "ctx.auth.scope" in p ? [p["ctx.auth.scope"]] : []);
         const procedure = kind === "procedures" ? plan.procedures[name] : undefined;
         const output = kind === "procedures" ? ref ? (procedure?.output.type === "object" ? procedure.output : undefined) : { type: "object", properties: { results: { type: "array", items: { type: "array", items: { type: "object" } } } }, required: ["results"] } : undefined;
-        const annotations = kind === "views" ? { readOnlyHint: true } : procedure?.mcp;
+        const annotations = kind === "views" ? viewAnnotations : procedure ? procedureAnnotations(procedure) : operation.mcp;
         const wire = kind === "views" ? outputConversions(plan, name, target) : [];
+        // Hashed as listed: the kernel adds a View tool's paging properties exactly so.
+        const listed = versioned({ name: tool, title: operation.title ?? toolTitle(name), description: about, inputSchema: kind === "views" ? { ...inputSchema, properties: { ...inputSchema?.properties, limit: { type: "integer", minimum: 1, maximum: 500 }, cursor: { type: "string" } } } : inputSchema, outputSchema: output, annotations });
         hasWire ||= wire.length > 0;
-        const fields = [...(description.targets.find(t => t._meta.id === `${kind === "views" ? "view" : "procedure"}:${name}`)?._meta.readOnly ? ["readOnly: true"] : []), `target: ${q({ kind: kind === "views" ? "view" : "procedure", name })}${guard(operation.requires, `${kind}/${name}`, binds, procedure?.trustedOnly)}`, `name: ${q(tool)}`, `surface: ${q(surface)}`, ...(operation.title ? [`title: ${q(operation.title)}`] : []), `description: ${q(operation.description ?? operation.title ?? name)}`, "inputSchema", ...(output ? [`outputSchema: ${q(output)}`] : []), ...(annotations ? [`annotations: ${q(annotations)}`] : []), ...((operation.requires?.auth?.all.length ?? 0) > 0 ? ["closed: true"] : []), ...(scopes.length ? [`scopes: ${q(scopes)}`] : []), `validate: ${kind === "views" ? `validate${index}` : `async (raw) => (await import("./validation/procedures/${file}.js")).validate(raw)`}`, ...(convert ? [`convert: ${convert}`] : []),
+        const fields = [...(description.targets.find(t => t._meta.id === `${kind === "views" ? "view" : "procedure"}:${name}`)?._meta.readOnly ? ["readOnly: true"] : []), `target: ${q({ kind: kind === "views" ? "view" : "procedure", name })}${guard(operation.requires, `${kind}/${name}`, binds, procedure?.trustedOnly)}`, `name: ${q(tool)}`, `surface: ${q(surface)}`, `title: ${q(listed.title)}`, `description: ${q(listed.description)}`, "inputSchema", ...(output ? [`outputSchema: ${literal(output)}`] : []), ...(annotations ? [`annotations: ${q(annotations)}`] : []), ...((operation.requires?.auth?.all.length ?? 0) > 0 ? ["closed: true"] : []), ...(scopes.length ? [`scopes: ${q(scopes)}`] : []), `validate: ${kind === "views" ? `validate${index}` : `async (raw) => (await import("./validation/procedures/${file}.js")).validate(raw)`}`, ...(convert ? [`convert: ${convert}`] : []),
             ...(kind === "views" ? [`path: ${q(`views/${name}`)}`, `page: ${boundaryPage(`run${index}`, wire)}`] : [`run: ${ref ? `(db, caller, input, handlers) => store(db, caller, { handlers }).procedures[${q(name)}](input)` : `async (db, caller, input) => (await import("./procedures/${file}.js")).default(db, caller, input)`}`])];
-        tools.push({ fields, schema });
+        tools.push({ fields: [...fields, `version: ${q(listed.version)}`], schema });
     };
     for (const [name, view] of Object.entries(plan.views))
         if (view.surface !== "internal")
@@ -69,7 +73,7 @@ export function emitMcp(plan, lowered, target, description, refuse, media = fals
             for (const verb of ["publish", "unpublish", "archive"]) {
                 const name = `${schema.name}.${verb}`, input = publishingInput;
                 Object.assign(files, emitValidation({ views: {}, procedures: { [name]: { input } } }, refuse));
-                add(name, "procedures", "admin", { input, requires: { auth: { all: ["ctx.admin"] } } }, mcpToolNameSegment(`${verb}_${schema.name}`));
+                add(name, "procedures", "admin", { input, title: toolTitle(`${verb}_${schema.name}`), requires: { auth: { all: ["ctx.admin"] } }, mcp: publishingAnnotations(verb) }, mcpToolNameSegment(`${verb}_${schema.name}`));
             }
     if (hasWire)
         imports.push('import { wireRows } from "@aotter/mantle/contracts";');
@@ -90,7 +94,7 @@ export const tools: readonly Tool<Database, Handlers>[] = [
 ${tools.map(({ fields, schema }) => `  { ${fields.map(field => field === "inputSchema" ? `inputSchema: ${shared.get(schema) ?? schema}` : field).join(", ")} },`).join("\n")}
 ];
 export function mcp<Env = unknown>(options: Options<Env>): (request: Request, env: Env, ctx?: import("@aotter/mantle/contracts").RequestContext) => Promise<Response | undefined> {
-  return serve<Env, Database, Handlers>(${media ? `async (request, env) => [...tools, ...(options.media && new URL(request.url).pathname.replace(/\\/+$/, "") === "/mcp/admin" ? (await import("./mcp-media.js")).mediaTools<Handlers>(() => options.media!(env)) : [])]` : "tools"}, ${plan.access ? `{...options, fields: ${q(plan.access.userFields)}, accessTargets: () => import("./access-targets.js").then(m => m.targets)}` : '{...options, accessTargets: () => import("./access-targets.js").then(m => m.targets)}'}, ${media ? `[...${q(reads)}, ...(options.media ? ${q(mediaDefinitions().filter(tool => tool.annotations.readOnlyHint).map(tool => ({ name: tool.name, surface: "admin" })))} : [])]` : q(reads)});
+  return serve<Env, Database, Handlers>(${media ? `async (request, env) => [...tools, ...(options.media && new URL(request.url).pathname.replace(/\\/+$/, "") === "/mcp/admin" ? (await import("./mcp-media.js")).mediaTools<Handlers>(() => options.media!(env)) : [])]` : "tools"}, ${plan.access ? `{...options, fields: ${q(plan.access.userFields)}, accessTargets: () => import("./access-targets.js").then(m => m.targets)}` : '{...options, accessTargets: () => import("./access-targets.js").then(m => m.targets)}'}, ${media ? `[...${q(reads)}, ...(options.media ? ${q(mediaTools.filter(tool => tool.annotations.readOnlyHint).map(tool => ({ name: tool.name, surface: "admin" })))} : [])]` : q(reads)});
 }
 ` };
 }

package/dist/usecase/paging.js

@@ -58,9 +58,8 @@ export function emitPaging(plan, lowered, target, refuse, proofs, boundary = fal
         const auth = authLines(view.requires, path);
         const spec = [`path: ${q(path)}`, `cap: ${cap}`, `sqlite: ${sqlite}`, `cursor: ${q(kinds)}`, `keys: ${c.nkeys}`, `values: {${user.used ? [...values].sort().concat(user.values).join(", ") : values.size ? ` ${[...values].sort().join(", ")} ` : ""}}`, "read", `caller: ${variants[0]}`, ...(trusted ? [`trusted: ${variants[1]}`] : []), ...(auth.length ? [`auth: (caller: Caller) => {\n${auth.join("\n")}\n  }`] : [])];
         files[`paged/${boundary ? "wire/" : ""}views/${encodeURIComponent(name)}.ts`] = `${user.code ? user.code + "\n" : ""}import { page, type Paged } from "${base}paging";
-import { ${auth.length ? "deny, isAdmin, isUser, " : ""}type Caller } from "${base}contracts";
-${databaseImport(target)}
-import { read } from "${base}driver/${driver}";
+import { ${auth.length ? "deny, isAdmin, isUser, " : ""}type Caller${sqlite ? "" : ", type Unsafe as Database"} } from "${base}contracts";
+${sqlite ? databaseImport(target) + "\n" : ""}import { read } from "${base}driver/${driver}";
 ${values.size ? `import { ${[...values].sort().join(", ")} } from "${base}dialect/${sqlite ? "sqlite" : "postgres"}";\n` : ""}import type { Input, Row } from "${boundary ? "../../../" : "../../"}views/${encodeURIComponent(name)}.js";
 const spec: Paged<Database> = {
   ${spec.join(",\n  ")},

package/dist/usecase/publishing.js

@@ -5,8 +5,8 @@ import { dialect as postgres } from "../kernel/dialect/postgres.js";
 import { renderTerm } from "../kernel/store.js";
 import { publishedParent } from "./translations.js";
 import { entry, exportName, q } from "../domain/entry.js";
-import { publishingInput, publishingTransitions } from "../domain/generated-tools.js";
-export { publishingInput, publishingTransitions };
+import { publishingAnnotations, publishingInput, publishingTransitions } from "../domain/generated-tools.js";
+export { publishingAnnotations, publishingInput, publishingTransitions };
 export function emitPublishing(plan, isSqlite, declarations, procedures, entries, values, refuse) {
     const d = isSqlite ? sqlite : postgres;
     const translations = Object.values(plan.schemas).some(s => s.translates);
@@ -36,7 +36,7 @@ export function emitPublishing(plan, isSqlite, declarations, procedures, entries
                 // the status term is replaced by the transition's own `status IN (...)`.
                 for (const term of rowPolicy(schema, trusted ? "trusted" : "caller", plan.schemas))
                     if (term[1] !== "admin")
-                        conditions.push(renderTerm(d, term, "", recipe => (recipes.push(recipe), d.param(recipes.length))));
+                        conditions.push(renderTerm(d, term, term[1] === "parent" ? d.ident(s.name) + "." : "", recipe => (recipes.push(recipe), d.param(recipes.length))));
                 if (verb === "publish")
                     for (const field of s.schema.required ?? []) {
                         const column = Object.keys(s.fields).find(c => (s.names?.[c] ?? c) === field);

package/dist/usecase/site.js

@@ -32,7 +32,6 @@ export function site(db: Database, caller: Caller) { return createSite({read:(sq
 `, "site-seed.sql": seed + "\n", "site-schema.sql": `CREATE TABLE site_config (key TEXT PRIMARY KEY, value TEXT NOT NULL);
 CREATE TABLE media_assets (id TEXT PRIMARY KEY, created_at ${pg ? "BIGINT" : "INTEGER"} NOT NULL, owner_id TEXT, alt TEXT, caption TEXT, variants TEXT NOT NULL, metadata TEXT);
 CREATE INDEX media_assets_by_created_id ON media_assets (created_at DESC, id DESC);
-CREATE INDEX media_assets_by_owner_created ON media_assets (owner_id, created_at DESC);
 CREATE TABLE pending_media_uploads (id TEXT PRIMARY KEY, record TEXT NOT NULL, expires_at ${pg ? "BIGINT" : "INTEGER"} NOT NULL);
 CREATE INDEX pending_media_uploads_expires_at ON pending_media_uploads (expires_at);
 ${seed}

package/dist/usecase/tool-version.js

@@ -0,0 +1,9 @@
+/** Generate-time tool versions: a stale host copy shows the model an older version than results carry. */
+import { canonical, fnv } from "../build/compiler.js";
+/** A hash of what a catalogue lists, so an unchanged definition keeps its version across deploys. */
+export const versionOf = (value) => fnv(canonical(value));
+/** A listed tool: its version, and its description (each locale's) ending with that version. */
+export function versioned(tool) {
+    const v = versionOf(tool), mark = (text) => `${text} (tool version ${v})`;
+    return { ...tool, description: typeof tool.description === "string" ? mark(tool.description) : Object.fromEntries(Object.entries(tool.description).map(([locale, text]) => [locale, mark(text)])), version: v };
+}

package/dist/usecase/translations.js

@@ -44,7 +44,7 @@ export function emitTranslations(plan, target) {
         declarations.push(`${q(schema.name)}: Pick<Tables[${q(schema.name)}]["row"],${["id", ...columns.filter(c => c !== schema.scope)].map(value => q(value)).join("|")}>${schema.scope && columns.includes(schema.scope) ? ` & {readonly ${q(schema.scope)}?:string|null}` : ""};`);
         descriptors.push(`${q(schema.name)}:[${entries.join(",")}]`);
     }
-    return { "translations.ts": `${user.code ? user.code + "\n" : ""}import {ContractError,type Caller${driver === "postgres" ? ",type Postgres as Database" : ""}} from "@aotter/mantle/contracts";
+    return { "translations.ts": `${user.code ? user.code + "\n" : ""}import {ContractError,type Caller${driver === "postgres" ? ",type Unsafe as Database" : ""}} from "@aotter/mantle/contracts";
 ${driver !== "postgres" ? `import type {Handle as Database} from "@aotter/mantle/driver/${driver}";` : ""}
 import {read} from "@aotter/mantle/driver/${driver}";
 import {binds,encode} from "@aotter/mantle/binds";