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

package/dist/kernel/web-gateway.js

@@ -1,4 +1,3 @@
-/** Selected web authorization loads on a request, outside the ordinary web startup graph. */
 import { web } from "./web.js";
 import { gatewayCaller, hostFailure } from "./host-caller.js";
 import { accessRequest } from "./host-access.js";
@@ -34,7 +33,6 @@ export function gatewayWeb(options, table) {
                             throw error;
                         }
                     } }]));
-            // The ordinary renderer validates query/path fields; wrapped pages decide before any SQL.
             const result = await site[method](request, env, options.gateway ? undefined : ctx);
             if (failure)
                 throw failure;

package/dist/kernel/web-head.js

@@ -1,4 +1,3 @@
-/** HTML head formatting loads only when the application asks for head tags. */
 const escape = (v) => String(v).replace(/[&<>"']/g, c => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[c]));
 export function headTags(canonical, row, markdown, locales) {
     let tags = '<link rel="canonical" href="' + escape(canonical) + '">';

package/dist/kernel/web-index.js

@@ -1,4 +1,3 @@
-/** /llms.txt and /sitemap.xml bodies; loaded only when an index is requested, so page Workers do not pay for it at startup. */
 const escape = (v) => String(v).replace(/[&<>"']/g, c => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[c]));
 const label = (v) => String(v).replace(/[\r\n]/g, " ").replace(/[\\[\]]/g, "\\$&");
 const size = (s) => new TextEncoder().encode(s).length;

package/dist/kernel/web-response.js

@@ -1,4 +1,3 @@
-/** Response hashing is needed only when a Web route actually renders. */
 export async function webResponse(request, body, type, cacheControl) {
     const hash = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(body));
     const etag = '"' + Array.from(new Uint8Array(hash), b => b.toString(16).padStart(2, '0')).join('') + '"';

package/dist/kernel/web-serve.js

@@ -0,0 +1,97 @@
+import { forwarded, wire, ContractError } from "./contracts.js";
+import { decode } from "./surface.js";
+const NO_STORE = { "cache-control": "no-store" };
+const notFound = () => new Response(null, { status: 404, headers: NO_STORE });
+export function serve(options, views, pages, query) {
+    const origin = new URL(options.origin);
+    const context = async (request, env, ctx) => ({ db: options.db, caller: forwarded(ctx, options.gateway)
+            ? (await import("./host-caller.js")).gatewayCaller(ctx, options.gateway, options.fields)
+            : typeof options.caller === "function" ? await options.caller(request, env, { readOnly: ["GET", "HEAD"].includes(request.method) }) : options.caller ?? { kind: "anonymous" } });
+    const urlFor = (path, row, view) => origin.origin + path.replace(/\{([^{}]+)\}/g, (_, key) => {
+        let value = row[key];
+        if (views.get(view).booleans?.includes(key) && (value === 0 || value === 1))
+            value = Boolean(value);
+        if (value === null || value === undefined)
+            throw new TypeError("List View must return every page parameter: " + key);
+        const segment = String(value);
+        if (segment === "." || segment === "..")
+            return "";
+        return encodeURIComponent(segment).replace(/[()]/g, c => "%" + c.charCodeAt(0).toString(16).toUpperCase());
+    });
+    const validUrl = (path, row, view) => { if ([...path.matchAll(/\{([^{}]+)\}/g)].some(([, key]) => row[key] === "." || row[key] === ".."))
+        return; return urlFor(path, row, view); };
+    const match = (path) => {
+        for (const entry of pages) {
+            const hit = entry.pattern.exec(path);
+            if (!hit)
+                continue;
+            return { ...entry, params: new URLSearchParams(decode(entry.keys, hit, "Malformed URL parameter.", "web/path")) };
+        }
+    };
+    const read = async (entry, ctx) => (await query(entry.page.view, ctx.db, ctx.caller, entry.params)).rows[0];
+    const response = async (request, body, type, caller) => {
+        const { webResponse } = await import('./web-response.js');
+        return webResponse(request, body, type, caller.kind === "anonymous" ? (options.cacheControl ?? "public, max-age=60") : "private, no-store");
+    };
+    return {
+        async fetch(request, env, execution) {
+            let caller;
+            try {
+                if (request.method !== "GET" && request.method !== "HEAD")
+                    return;
+                const path = new URL(request.url).pathname, index = path === "/llms.txt" || path === "/sitemap.xml";
+                const entry = !index && path.endsWith(".md") ? match(path.slice(0, -3)) : undefined, markdown = entry?.page.markdown;
+                if (!index && !markdown)
+                    return;
+                const ctx = await context(request, env, execution);
+                caller = ctx.caller;
+                if (index) {
+                    const sitemap = path === "/sitemap.xml";
+                    const body = await (await import("./web-index.js")).webIndex(sitemap, options, pages, (list, cursor) => query(list, ctx.db, ctx.caller, new URLSearchParams(), cursor), validUrl);
+                    return response(request, body, sitemap ? "application/xml" : "text/plain", ctx.caller);
+                }
+                const exact = match(path);
+                if (exact)
+                    try {
+                        if (await read(exact, ctx))
+                            return;
+                    }
+                    catch (error) {
+                        if (wire(error).status !== 400)
+                            throw error;
+                    }
+                const row = await read(entry, ctx);
+                if (!row)
+                    return notFound();
+                const body = row[markdown];
+                if (body == null)
+                    return notFound();
+                if (typeof body !== "string")
+                    throw new TypeError("Markdown field must return text.");
+                return response(request, body, "text/markdown", ctx.caller);
+            }
+            catch (error) {
+                return (await import("./host-caller.js")).hostFailure(error, caller, "web");
+            }
+        },
+        async head(request, env, execution) {
+            try {
+                const path = new URL(request.url).pathname, entry = match(path);
+                if (!entry)
+                    return "";
+                const ctx = await context(request, env, execution), row = await read(entry, ctx);
+                if (!row)
+                    return "";
+                const canonical = validUrl(entry.path, row, entry.page.view);
+                if (!canonical)
+                    return "";
+                return (await import("./web-head.js")).headTags(canonical, row, !!entry.page.markdown, options.locales);
+            }
+            catch (error) {
+                if (error instanceof ContractError && error.code === "HOST_CONTRACT")
+                    throw error;
+                return "";
+            }
+        },
+    };
+}

package/dist/kernel/web.d.ts

@@ -1,5 +1,5 @@
 /** Web output for a generated public View table: /llms.txt, /sitemap.xml, Markdown pages and head tags. SQL owns visibility. */
-import { type Caller, type Gateway, type RequestContext } from "./contracts.js";
+import type { Caller, Gateway, RequestContext } from "./contracts.js";
 import type { UserFields } from "./user-fields.js";
 import { type Conversions } from "./surface.js";
 /** An app's public Views: row type and input keys per View, and the Views a list may name (input that accepts no fields). */

package/dist/kernel/web.js

@@ -1,8 +1,4 @@
-/** Web output for a generated public View table: /llms.txt, /sitemap.xml, Markdown pages and head tags. SQL owns visibility. */
-import { forwarded, wire, ContractError } from "./contracts.js";
-import { convert, decode } from "./surface.js";
-const NO_STORE = { "cache-control": "no-store" };
-const notFound = () => new Response(null, { status: 404, headers: NO_STORE });
+import { convert } from "./surface.js";
 export function web(options, table) {
     const views = new Map(table);
     const query = (name, db, caller, params, cursor) => {
@@ -23,35 +19,6 @@ export function web(options, table) {
         const pattern = path.split(/(\{[^{}]+\})/).map(part => part.startsWith("{") ? (keys.push(part.slice(1, -1)), "([^/]+)") : part.replace(/[.*+?^$()|[\]\\]/g, "\\$&")).join("");
         return { path, page, keys, pattern: new RegExp("^" + pattern + "$") };
     }).sort((a, b) => a.keys.length - b.keys.length);
-    const context = async (request, env, ctx) => ({ db: options.db, caller: forwarded(ctx, options.gateway)
-            ? (await import("./host-caller.js")).gatewayCaller(ctx, options.gateway, options.fields)
-            : typeof options.caller === "function" ? await options.caller(request, env, { readOnly: ["GET", "HEAD"].includes(request.method) }) : options.caller ?? { kind: "anonymous" } });
-    const urlFor = (path, row, view) => origin.origin + path.replace(/\{([^{}]+)\}/g, (_, key) => {
-        let value = row[key];
-        if (views.get(view).booleans?.includes(key) && (value === 0 || value === 1))
-            value = Boolean(value);
-        if (value === null || value === undefined)
-            throw new TypeError("List View must return every page parameter: " + key);
-        const segment = String(value);
-        if (segment === "." || segment === "..")
-            return "";
-        return encodeURIComponent(segment).replace(/[()]/g, c => "%" + c.charCodeAt(0).toString(16).toUpperCase());
-    });
-    const validUrl = (path, row, view) => { if ([...path.matchAll(/\{([^{}]+)\}/g)].some(([, key]) => row[key] === "." || row[key] === ".."))
-        return; return urlFor(path, row, view); };
-    const match = (path) => {
-        for (const entry of pages) {
-            const hit = entry.pattern.exec(path);
-            if (!hit)
-                continue;
-            return { ...entry, params: new URLSearchParams(decode(entry.keys, hit, "Malformed URL parameter.", "web/path")) };
-        }
-    };
-    const read = async (entry, ctx) => (await query(entry.page.view, ctx.db, ctx.caller, entry.params)).rows[0];
-    const response = async (request, body, type, caller) => {
-        const { webResponse } = await import('./web-response.js');
-        return webResponse(request, body, type, caller.kind === "anonymous" ? (options.cacheControl ?? "public, max-age=60") : "private, no-store");
-    };
     if (options.gateway || options.authorize) {
         let handle;
         const load = async () => handle ??= (await import("./web-gateway.js")).gatewayWeb(options, table);
@@ -60,65 +27,17 @@ export function web(options, table) {
             head: async (request, env, ctx) => (await load()).head(request, env, ctx),
         };
     }
+    let served;
+    const serve = async () => served ??= (await import("./web-serve.js")).serve(options, views, pages, query);
     return {
         async fetch(request, env, execution) {
-            let caller;
-            try {
-                if (request.method !== "GET" && request.method !== "HEAD")
-                    return;
-                const path = new URL(request.url).pathname, index = path === "/llms.txt" || path === "/sitemap.xml";
-                const entry = !index && path.endsWith(".md") ? match(path.slice(0, -3)) : undefined, markdown = entry?.page.markdown;
-                if (!index && !markdown)
-                    return;
-                const ctx = await context(request, env, execution);
-                caller = ctx.caller;
-                if (index) {
-                    const sitemap = path === "/sitemap.xml";
-                    const body = await (await import("./web-index.js")).webIndex(sitemap, options, pages, (list, cursor) => query(list, ctx.db, ctx.caller, new URLSearchParams(), cursor), validUrl);
-                    return response(request, body, sitemap ? "application/xml" : "text/plain", ctx.caller);
-                }
-                const exact = match(path);
-                if (exact)
-                    try {
-                        if (await read(exact, ctx))
-                            return;
-                    }
-                    catch (error) {
-                        if (wire(error).status !== 400)
-                            throw error;
-                    }
-                const row = await read(entry, ctx);
-                if (!row)
-                    return notFound();
-                const body = row[markdown];
-                if (body == null)
-                    return notFound();
-                if (typeof body !== "string")
-                    throw new TypeError("Markdown field must return text.");
-                return response(request, body, "text/markdown", ctx.caller);
-            }
-            catch (error) {
-                return (await import("./host-caller.js")).hostFailure(error, caller, "web");
-            }
-        },
-        async head(request, env, execution) {
-            try {
-                const path = new URL(request.url).pathname, entry = match(path);
-                if (!entry)
-                    return "";
-                const ctx = await context(request, env, execution), row = await read(entry, ctx);
-                if (!row)
-                    return "";
-                const canonical = validUrl(entry.path, row, entry.page.view);
-                if (!canonical)
-                    return "";
-                return (await import("./web-head.js")).headTags(canonical, row, !!entry.page.markdown, options.locales);
-            }
-            catch (error) {
-                if (error instanceof ContractError && error.code === "HOST_CONTRACT")
-                    throw error;
-                return "";
-            }
+            if (request.method !== "GET" && request.method !== "HEAD")
+                return;
+            const path = new URL(request.url).pathname;
+            if (path !== "/llms.txt" && path !== "/sitemap.xml" && !path.endsWith(".md"))
+                return;
+            return (served ?? await serve()).fetch(request, env, execution);
         },
+        head: async (request, env, execution) => (served ?? await serve()).head(request, env, execution),
     };
 }

package/dist/kernel/where.js

@@ -1,10 +1,4 @@
 const COMPARE = { gt: ">", gte: ">=", lt: "<", lte: "<=" };
-/**
- * `column` is already quoted. `bind` registers one parameter and returns its placeholder. `insensitive` folds both sides of
- * eq/ne/in/notIn with LOWER (text only) and picks the dialect's case-insensitive LIKE. A null eq/ne is IS [NOT] NULL.
- * `like` takes a finished pattern (`escapeLike` the literal parts).
- * @internal
- */
 export function condition(d, column, operator, value, bind, insensitive = false) {
     const lhs = insensitive ? `LOWER(${column})` : column;
     const rhs = (v) => insensitive ? `LOWER(${bind(v)})` : bind(v);

package/dist/usecase/adminBindings.js

@@ -1,5 +1,4 @@
 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";
@@ -14,7 +13,6 @@ const wire = (fields, 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)
@@ -30,19 +28,31 @@ 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)};`) };
+function sqlConstants(values) {
+    const counts = new Map(), seen = new Map(), pool = new Map(), constants = [];
+    let named = 0;
+    const key = (v) => typeof v === "string" ? v.length > 80 ? q(v) : undefined : v && typeof v === "object" ? (text => text.length > 80 ? text : undefined)(q(v)) : undefined;
+    const children = (v) => v && typeof v === "object" ? Object.values(v) : [];
+    const tally = (v, by = 1) => { const k = key(v); if (k) {
+        counts.set(k, (counts.get(k) ?? 0) + by);
+        seen.set(k, v);
+    } children(v).forEach(child => tally(child, by)); };
+    values.forEach(value => children(value).forEach(child => tally(child)));
+    for (const [k, v] of [...seen].sort(([a], [b]) => b.length - a.length)) {
+        const copies = counts.get(k);
+        if (copies > 1) {
+            pool.set(k, "");
+            children(v).forEach(child => tally(child, 1 - copies));
+        }
+    }
+    const print = (v) => Array.isArray(v) ? "[" + v.map(reference).join(",") + "]" : v && typeof v === "object" ? "{" + Object.entries(v).map(([name, child]) => `${name === "__proto__" ? `[${q(name)}]` : q(name)}:${reference(child)}`).join(",") + "}" : q(v);
+    const reference = (v) => { const k = key(v); if (!k || pool.get(k) === undefined)
+        return print(v); if (pool.get(k) === "") {
+        const name = `sql${named++}`;
+        pool.set(k, name);
+        constants.push(`const ${name}=${print(v)}${typeof v === "string" ? "" : " as const"};`);
+    } return pool.get(k); };
+    return { code: values.map(print), constants };
 }
 export function emitAdminBindings(input, refuse) {
     if (!input.admin)
@@ -54,9 +64,7 @@ export function emitAdminBindings(input, refuse) {
     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`;
@@ -103,7 +111,6 @@ export function emitAdminBindings(input, refuse) {
         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.");
@@ -123,7 +130,7 @@ export function emitAdminBindings(input, refuse) {
         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;`);
+        pageSpecs.push({ path: "views/" + name, cap: v.stmts[0]?.SelectStmt.limitCount?.A_Const?.ival?.ival ?? 500, cursorKinds, ...modes });
         imports.push(`const allowsView${n}=${allowed(v.requires, `views/${name}`)};`);
         if (v.surface === "admin")
             adminViews.push(`view${n}`);
@@ -134,8 +141,8 @@ export function emitAdminBindings(input, refuse) {
         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;`);
+    const { code: [entrySpecs, ...pages], constants } = sqlConstants([input.adminEntries, ...pageSpecs]);
+    imports.push(...views.map((view, n) => `const view${n}=${view} satisfies View<Database>;`), ...constants, ...pages.map((page, n) => `const viewPage${n}=${page} as const;`), `const entrySpecs=${entrySpecs} 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`;

package/dist/usecase/adminClient.js

@@ -1,12 +1,5 @@
-/** `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";
@@ -20,40 +13,26 @@ test("the Admin MCP App works in an MCP host", { timeout: 300_000 }, async () =>
   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);

package/dist/usecase/adminDescriptors.js

@@ -1,4 +1,3 @@
-/** 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";
@@ -9,7 +8,6 @@ export function emitAdminDescriptors({ plan, admin = false }, diagnostics) {
     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)
@@ -46,7 +44,6 @@ export function emitAdminDescriptors({ plan, admin = false }, diagnostics) {
             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);
@@ -67,12 +64,9 @@ export function emitAdminDescriptors({ plan, admin = false }, diagnostics) {
             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" };
+    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: () => import(\"./admin-developer-console.js\").then(m => m.developerConsole)} as const;\n",
+        "admin-developer-console.ts": "// Generated developer snapshot, loaded by bootstrap.developerConsole.\n" + literals({ developerConsole: snapshot }) + "\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")
@@ -83,7 +77,6 @@ function literals(exports) {
         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) {

package/dist/usecase/generate.js

@@ -1,5 +1,4 @@
 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";
@@ -66,7 +65,6 @@ export function generate(input) {
                 ? 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;" : ""} }`;
@@ -77,9 +75,7 @@ export function generate(input) {
             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) {
@@ -111,9 +107,7 @@ export function generate(input) {
         }
         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");

package/dist/usecase/handlers.js

@@ -2,18 +2,15 @@ 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}`);
     }

package/dist/usecase/mcp-media.js

@@ -1,7 +1,6 @@
 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]));

package/dist/usecase/mcp.js

@@ -1,4 +1,3 @@
-/** Emit the selected MCP boundary; the official transport loads on its first request. */
 import { mcpToolNameSegment, procedureAnnotations, toolTitle, viewAnnotations } from "../build/compiler.js";
 import { emitMcpMedia, mediaDefinitions } from "./mcp-media.js";
 import { advertised, emitValidation } from "./validation.js";
@@ -37,7 +36,6 @@ export function emitMcp(plan, lowered, target, description, refuse, media = fals
             const module = `./${outputConversions(plan, name, target).some(([, type]) => type === "int") ? "paged/wire/views" : "paged/views"}/${file}.js`;
             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 { 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.");
@@ -49,7 +47,6 @@ export function emitMcp(plan, lowered, target, description, refuse, media = fals
         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" ? 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)}`, `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}`] : []),
@@ -77,7 +74,6 @@ export function emitMcp(plan, lowered, target, description, refuse, media = fals
             }
     if (hasWire)
         imports.push('import { wireRows } from "@aotter/mantle/contracts";');
-    // An input schema several tools share is one constant.
     const uses = new Map(), shared = new Map();
     for (const { schema } of tools)
         uses.set(schema, (uses.get(schema) ?? 0) + 1);

package/dist/usecase/paging.js

@@ -1,5 +1,4 @@
 import { userReferences } from "../domain/userReferences.js";
-/** Selected View boundary: Core prints keyset SQL once; bare operations retain native rows. */
 import { parseNumeric } from "../build/compiler.js";
 import { outputConversions } from "../domain/columns.js";
 import { authLines } from "../domain/input.js";
@@ -17,7 +16,6 @@ export function emitPaging(plan, lowered, target, refuse, proofs, boundary = fal
         const proof = proofs?.[name];
         if (boundary && (!proof || !proof.types.length && !proof.single))
             continue;
-        // Internal bare queries remain available even when they cannot be safely paged.
         if (!proof || !proof.types.length && !proof.single) {
             if (view.surface !== "internal")
                 refuse(path, proof?.reason ?? "Paged Views need a complete typed NOT NULL key tuple, indexed Schema order and a non-fanning relation, or a proved singleton. For a lookup by a unique field, end ORDER BY with the Schema's id (`ORDER BY t.id`).");

package/dist/usecase/publishing.js

@@ -1,4 +1,3 @@
-/** Opt-in lifecycle: one atomic, version-guarded statement per transition, with Core's row rules. */
 import { rowPolicy } from "../build/compiler.js";
 import { dialect as sqlite } from "../kernel/dialect/sqlite.js";
 import { dialect as postgres } from "../kernel/dialect/postgres.js";
@@ -32,8 +31,6 @@ export function emitPublishing(plan, isSqlite, declarations, procedures, entries
                 const schema = plan.schemas[s.name];
                 const recipes = [{ k: "now" }, { k: "input", name: "id" }, { k: "input", name: "expectedVersion" }];
                 const conditions = [`id = ${d.param(2)}`, `version = ${d.param(3)}`, `status IN (${from.map(v => `'${v}'`).join(", ")})`];
-                // Same visibility as Store and Admin writes, translation parent included (a child under an out-of-set parent is missing);
-                // 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, term[1] === "parent" ? d.ident(s.name) + "." : "", recipe => (recipes.push(recipe), d.param(recipes.length))));
@@ -56,7 +53,6 @@ export function emitPublishing(plan, isSqlite, declarations, procedures, entries
         }
     }
 }
-/** Publishing lists get one index, prefixed by scope when present. */
 export function publishingSql(schemas, isSqlite) {
     const d = isSqlite ? sqlite : postgres;
     return Object.values(schemas).filter(s => s.publishing).map(s => `CREATE INDEX ${d.ident(`_mantle_ix_${s.name}_published`)} ON ${d.ident(s.name)} (${[...(s.scope ? [s.scope] : []), ...(s.userScopes ?? []).map(u => u.column), "published_at", "id"].map(d.ident).join(", ")})`);