@aotter/mantle 0.2.0-alpha.9 → 0.2.1-alpha.1

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`;
@@ -85,9 +93,9 @@ export function emitAdminBindings(input, refuse) {
         const defaults = Object.fromEntries(Object.entries(checks(s, true).properties ?? {}).flatMap(([key, p]) => p.default !== undefined ? [[key, p.default]] : []));
         const primary = isPrimaryCollection(s, Object.values(plan.schemas));
         const schemaCode = `{
-      name:${q(s.name)},primary:${primary},descriptor:allCollections[${q(s.name)}],publishing:${!!s.publishing},readOnly:${s.schema.readOnly === true || declared.some(f => s.fields[f] === "geo")},fields:names${n},defaults:${q(defaults)},
+      name:${q(s.name)},primary:${primary},descriptor:allCollections[${q(s.name)}],publishing:${!!s.publishing},${s.liveEdits ? "liveEdits:true," : ""}readOnly:${s.schema.readOnly === true || declared.some(f => s.fields[f] === "geo")},fields:names${n},defaults:${q(defaults)},
       binding:${entrySpec},
-      query:query${n},validate:(data,full)=>{const checked=Object.fromEntries(Object.entries(data).filter(([key,v])=>v!==null||${q(s.schema.required ?? [])}.includes(key)));(full?full${n}:partial${n})(checked);${sqlite ? "" : "nativeText(data);"}${yearZero}return data;},
+      query:query${n},validate:(data,full)=>{const checked=Object.fromEntries(Object.entries(data).filter(([key,v])=>v!==null||${s.publishing ? "full&&" : ""}${q(s.schema.required ?? [])}.includes(key)));(full?full${n}:partial${n})(checked);${sqlite ? "" : "nativeText(data);"}${yearZero}return data;},
       values:values${n},row:${named},
       ${sqlite ? "" : "native:nativeText,"}
       ${s.publishing ? `transition:async(db,caller,verb,id,expectedVersion)=>{const run=await ({publish:()=>import("./procedures/${encodeURIComponent(s.name + ".publish")}.js"),unpublish:()=>import("./procedures/${encodeURIComponent(s.name + ".unpublish")}.js"),archive:()=>import("./procedures/${encodeURIComponent(s.name + ".archive")}.js")})[verb]();const version=wireRows([{version:expectedVersion}],[["version","int"]])[0]!.version;return run.default(db,caller,{id,expectedVersion:version} as Parameters<typeof run.default>[2]);},` : ""}
@@ -104,7 +112,8 @@ export function emitAdminBindings(input, refuse) {
         imports.push(`const viewNames${n}=${q(rename)} as const;`);
         const pageData = input.adminPages?.[name];
         if (!pageData) {
-            refuse(`views/${name}/admin`, "Missing compiler-authorized matching pages.");
+            if (!input.adminPages)
+                refuse(`views/${name}/admin`, "Admin list was not generated: no compiler-authorized matching pages were supplied for this View.");
             continue;
         }
         const kinds = (v.uiSchema?.list ?? {});
@@ -121,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}`);
@@ -132,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,29 @@ 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 nullable = (p) => p.nullable === true || [p.type].flat().includes("null") || (p.enum ?? []).includes(null);
 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 scope = s.scope ? s.names[s.scope] ?? s.scope : undefined, { [scope ?? ""]: _scope, ...declared } = s.schema.properties ?? {};
+        const certain = (name) => !s.publishing && s.schema.required?.includes(name);
+        const properties = Object.fromEntries(Object.entries(declared).map(([name, p]) => [name, certain(name) || nullable(p) ? p : { ...p, nullable: true }]));
         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,6 +1,5 @@
 import { userReferences } from "../domain/userReferences.js";
-/** Canonical lowered programs become ordinary target-specific TypeScript, never a runtime plan. */
-import { parseNumeric } from "../build/compiler.js";
+import { parseNumeric, tableOutputs } from "../build/compiler.js";
 import { boundaryType, nativeType, outputType, wireType } from "../domain/columns.js";
 import { databaseImport, driverFor, entry, exportName, generatedFiles, isSqlite as sqlite, q } from "../domain/entry.js";
 import { authLines as auth } from "../domain/input.js";
@@ -62,11 +61,10 @@ export function generate(input) {
             if (!bind || bind.k !== "input")
                 return `readonly ${q(name)}${schema.required?.includes(name) ? "" : "?"}: ${typeOf(field)};`;
             const type = String(bind.type);
-            const driverType = type === "json" || type === "date" ? "string" : type === "timestamptz" ? "string | Date" : isSqlite
+            const driverType = type === "json" ? typeOf(field) : type === "date" ? "string" : type === "timestamptz" ? "string | Date" : isSqlite
                 ? type === "bool" || parseNumeric(type) ? "number" : typeOf(field)
                 : parseNumeric(type) ? "number | string" : typeOf(field);
             const nullable = field.nullable === true || Array.isArray(field.type) && field.type.includes("null") || !schema.required?.includes(name);
-            // D1 cannot bind undefined. Bound fields are explicit, null represents absence.
             return `readonly ${q(name)}: ${driverType}${nullable ? " | null" : ""};`;
         });
         return `{ ${properties.join(" ")} ${schema.additionalProperties !== false ? "readonly [key:string]: unknown;" : ""} }`;
@@ -77,18 +75,18 @@ 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) {
+        const recipes = recipesOf(s, fields, message => refuse(path, message)), probe = row && s.probe ? recipesOf(s.probe, fields, message => refuse(path, message)) : [];
+        for (const r of [...recipes, ...probe]) {
             if (r.k === "now" || r.k === "cutoff")
                 values.add(r.k);
             else if (r.k === "input" && r.type)
                 values.add(r.type === "date" ? "date" : "timestamp");
         }
-        return `{ sql: ${q(s.sql)}, binds: ${q(recipes)}${row ? ", row: true" : ""} }`;
+        const locks = Object.fromEntries((plan.schemas[s.schema ?? ""]?.locks ?? []).filter(l => l.on.includes(s.verb)).map(l => [l.name, l.message]));
+        const lock = row && s.probe ? `, lock: ${q({ sql: s.probe.sql, binds: probe, schema: plan.schemas[s.schema].name, verb: s.verb, locks })}` : "";
+        return `{ sql: ${q(s.sql)}, binds: ${q(recipes)}${row ? ", row: true" : s.onNoRows ? ', row: "some"' : ""}${lock} }`;
     };
     const declarations = [], views = [], procedures = [], refProcedures = [];
     const entries = {};
@@ -109,15 +107,14 @@ export function generate(input) {
             refuse(path, "Dynamic or repeated View outputs need an explicit generated row contract. Give each SELECT output a unique explicit alias.");
             continue;
         }
-        const output = [];
+        const output = [], direct = tableOutputs(view, plan.schemas);
         for (const key of keys) {
-            const type = outputType(plan, name, key);
-            // Declared timestamps and dates arrive formatted by the SQL itself (domain/wireScalars).
-            output.push(`readonly ${q(key)}: ${nativeType(type, isSqlite)};`);
+            const type = outputType(plan, name, key) ?? direct[key]?.type;
+            output.push(`readonly ${q(key)}: ${nativeType(type, isSqlite, direct[key]?.notNull)};`);
         }
         const fieldNames = inputFields(view.input, path + "/input");
         const callerStep = step(c, path, fieldNames), trustedStep = mode === "caller" ? step(trusted, path, fieldNames) : callerStep;
-        declarations.push(`export type View${index}Input = ${queryInputType(view.input ?? { type: "object", additionalProperties: false }, [c, ...(trusted ? [trusted] : [])])};`, `export type View${index}Row = { ${output.join(" ")} };`, `export type View${index}WireRow = { ${keys.map(key => `readonly ${q(key)}: ${boundaryType(plan, name, key) ? wireType(boundaryType(plan, name, key)) : `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));`, "}");
+        declarations.push(`export type View${index}Input = ${queryInputType(view.input ?? { type: "object", additionalProperties: false }, [c, ...(trusted ? [trusted] : [])])};`, `export type View${index}Row = { ${output.join(" ")} };`, `export type View${index}WireRow = { ${keys.map(key => `readonly ${q(key)}: ${boundaryType(plan, name, key) ? wireType(boundaryType(plan, name, key), direct[key]?.notNull) : `View${index}Row[${q(key)}]`};`).join(" ")} };`, `const ${fn}Caller = ${callerStep} as const;`, ...(trustedStep !== callerStep ? [`const ${fn}Trusted = ${trustedStep} as const;`] : []), `async function ${fn}(db: ${isSqlite ? "Database" : "Unsafe"}, caller: Caller, raw: View${index}Input): Promise<View${index}Row[]> {`, ...auth(view.requires, path), ...(user.used ? ['  USER.modeOf(caller);'] : []), `  const m = ${trustedStep !== callerStep ? `${user.used ? 'USER.modeOf(caller) === "trusted"' : 'caller.kind === "system"'} ? ${fn}Trusted : ` : ""}${fn}Caller;`, `  return DRIVER.read(db, ${user.used ? "USER.scoped(m.sql, caller)" : "m.sql"}, binds(D, m.binds, caller, raw));`, "}");
         views.push(`[${q(name)}]: ${fn}`);
         declarations.push(`export { ${fn} as ${exportName("view", name)} };`);
         entries[`views/${encodeURIComponent(name)}.ts`] = entry("view", name, `View${index}Input as Input, View${index}Row as Row, View${index}WireRow as WireRow`);
@@ -132,7 +129,7 @@ export function generate(input) {
             continue;
         }
         if ([...modes.caller, ...modes.trusted].some(s => s.publish || s.schema && plan.schemas[s.schema]?.publishing))
-            refuse(path, "Publishing writes are generated: use the Store and the `<schema>.publish` / `.unpublish` / `.archive` transitions.");
+            refuse(path, "A SQL Procedure cannot write a publishing Schema: create and edit its rows from a ref handler through the Store (`ctx.store.collection(...)`), and change status with the generated `<schema>.publish` / `.unpublish` / `.archive` transitions.");
         const fieldNames = inputFields(procedure.input, path + "/input");
         const steps = (statements) => `[${statements.map(s => step(s, path, fieldNames, s.kind === "row")).join(", ")}] as const`;
         const same = steps(modes.caller) === steps(modes.trusted);
@@ -142,8 +139,8 @@ export function generate(input) {
         entries[`procedures/${encodeURIComponent(name)}.ts`] = entry("procedure", name, `Procedure${index}Input as Input`, `export type { Output } from "${base}contracts";\n`);
     }
     emitTtl(plan, isSqlite, declarations, procedures, entries, refuse);
-    emitPublishing(plan, isSqlite, declarations, procedures, entries, values, refuse);
-    const stores = emitStores(plan.schemas, isSqlite, newId, refuse, hasHandlers);
+    emitPublishing(plan, isSqlite, declarations, procedures, entries, values, refuse, input.locks);
+    const stores = emitStores(plan.schemas, isSqlite, newId, refuse, hasHandlers, input.locks);
     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 };

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.
+    declarations.push('export type HandlerStore = Pick<ReturnType<typeof makeStore>, "collection" | "batch" | "views" | "procedures">;', 
     `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]));