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

package/dist/usecase/mcp.js

@@ -0,0 +1,100 @@
+/** 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";
+import { databaseImport, literal, q } from "../domain/entry.js";
+import { authLines, conversions } from "../domain/input.js";
+import { publishingAnnotations, publishingInput } from "./publishing.js";
+import { versioned } from "./tool-version.js";
+import { boundaryPage, outputConversions } from "../domain/columns.js";
+export function emitMcp(plan, lowered, target, description, refuse, media = false) {
+    if (!Object.values(plan.views).some(view => view.surface !== "internal") && !Object.values(plan.triggers).some(trigger => trigger.source.kind === "mcp"))
+        return {};
+    const reads = [];
+    const imports = plan.access ? ['import { userBinds } from "@aotter/mantle/user-fields";'] : [], tools = [];
+    const mediaTools = media ? mediaDefinitions().map(({ action, ...tool }) => ({ action, ...versioned({ ...tool, title: toolTitle(tool.name) }) })) : [];
+    const files = media ? emitMcpMedia(mediaTools, refuse) : {};
+    let hasRef = false, hasWire = false;
+    const names = new Set(mediaTools.map(tool => "admin:" + tool.name));
+    const guard = (requires, path, binds = [], trustedOnly = false) => {
+        const lines = authLines(requires, path, binds, !target.endsWith("postgres"), trustedOnly);
+        return lines.length ? `, check: (caller) => {${lines.join("")}}` : "";
+    };
+    const refs = Object.values(plan.procedures).some(p => "ref" in p.handler);
+    if (Object.values(plan.procedures).some(p => p.trustedOnly) || [...Object.values(plan.views), ...Object.values(plan.procedures)].some(p => p.requires?.auth?.all.length) || Object.values(plan.schemas).some(s => s.publishing))
+        imports.push('import { deny, isAdmin, isUser } from "@aotter/mantle/contracts";');
+    const add = (name, kind, surface, operation = kind === "views" ? plan.views[name] : plan.procedures[name], tool = mcpToolNameSegment(name)) => {
+        if (kind === "views")
+            reads.push({ name: tool, surface });
+        const ref = kind === "procedures" && !!plan.procedures[name] && "ref" in plan.procedures[name].handler;
+        hasRef ||= ref;
+        const statements = kind === "views" ? [lowered.views[name]?.public ?? lowered.views[name]?.caller] : lowered.procedures[name]?.caller ?? [];
+        const binds = statements.flatMap(statement => statement?.binds ?? []);
+        const index = tools.length, file = encodeURIComponent(name);
+        if (kind === "views")
+            imports.push(`import { validate as validate${index} } from "./validation/${kind}/${file}.js";`);
+        if (kind === "views") {
+            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.");
+        if (names.has(surface + ":" + tool))
+            refuse(`${kind}/${name}`, `MCP tool name ${tool} collides on ${surface}.`);
+        names.add(surface + ":" + tool);
+        const convert = conversions(operation.input?.properties, binds, target), scopes = (operation.requires?.auth?.all ?? []).flatMap(p => typeof p === "object" && "ctx.auth.scope" in p ? [p["ctx.auth.scope"]] : []);
+        const procedure = kind === "procedures" ? plan.procedures[name] : undefined;
+        const output = kind === "procedures" ? ref ? (procedure?.output.type === "object" ? procedure.output : undefined) : { type: "object", properties: { results: { type: "array", items: { type: "array", items: { type: "object" } } } }, required: ["results"] } : undefined;
+        const annotations = kind === "views" ? 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}`] : []),
+            ...(kind === "views" ? [`path: ${q(`views/${name}`)}`, `page: ${boundaryPage(`run${index}`, wire)}`] : [`run: ${ref ? `(db, caller, input, handlers) => store(db, caller, { handlers }).procedures[${q(name)}](input)` : `async (db, caller, input) => (await import("./procedures/${file}.js")).default(db, caller, input)`}`])];
+        tools.push({ fields: [...fields, `version: ${q(listed.version)}`], schema });
+    };
+    for (const [name, view] of Object.entries(plan.views))
+        if (view.surface !== "internal")
+            add(name, "views", view.surface);
+    const exposed = new Set();
+    for (const trigger of Object.values(plan.triggers))
+        if (trigger.source.kind === "mcp") {
+            const key = trigger.source.surface + ":" + trigger.procedure;
+            if (!exposed.has(key)) {
+                exposed.add(key);
+                add(trigger.procedure, "procedures", trigger.source.surface);
+            }
+        }
+    for (const schema of Object.values(plan.schemas))
+        if (schema.publishing)
+            for (const verb of ["publish", "unpublish", "archive"]) {
+                const name = `${schema.name}.${verb}`, input = publishingInput;
+                Object.assign(files, emitValidation({ views: {}, procedures: { [name]: { input } } }, refuse));
+                add(name, "procedures", "admin", { input, title: toolTitle(`${verb}_${schema.name}`), requires: { auth: { all: ["ctx.admin"] } }, mcp: publishingAnnotations(verb) }, mcpToolNameSegment(`${verb}_${schema.name}`));
+            }
+    if (hasWire)
+        imports.push('import { wireRows } from "@aotter/mantle/contracts";');
+    // 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);
+    for (const [schema, count] of uses)
+        if (count > 1 && schema)
+            shared.set(schema, `schema${shared.size}`);
+    return { ...files, "mcp.ts": `${[`import { mcp as serve, type Options as McpOptions, type Tool } from "@aotter/mantle/mcp";`, databaseImport(target),
+            ...(media ? ['import type { MediaStorage } from "@aotter/mantle/site";'] : []),
+            'import type { Handlers } from "./generated.js";', ...(hasRef ? ['import { store } from "./generated.js";'] : []), ...imports,
+            ...[...shared].map(([schema, name]) => `const ${name} = ${schema};`)].join("\n")}
+export type Options<Env = unknown> = McpOptions<Env, Database> & { handlers${refs ? "" : "?"}: Handlers }${media ? " & { media?: (env: Env) => MediaStorage }" : ""};
+/** The generated tools, exported so an app can compose them with its own tools and MCP Apps. */
+export const tools: readonly Tool<Database, Handlers>[] = [
+${tools.map(({ fields, schema }) => `  { ${fields.map(field => field === "inputSchema" ? `inputSchema: ${shared.get(schema) ?? schema}` : field).join(", ")} },`).join("\n")}
+];
+export function mcp<Env = unknown>(options: Options<Env>): (request: Request, env: Env, ctx?: import("@aotter/mantle/contracts").RequestContext) => Promise<Response | undefined> {
+  return serve<Env, Database, Handlers>(${media ? `async (request, env) => [...tools, ...(options.media && new URL(request.url).pathname.replace(/\\/+$/, "") === "/mcp/admin" ? (await import("./mcp-media.js")).mediaTools<Handlers>(() => options.media!(env)) : [])]` : "tools"}, ${plan.access ? `{...options, fields: ${q(plan.access.userFields)}, accessTargets: () => import("./access-targets.js").then(m => m.targets)}` : '{...options, accessTargets: () => import("./access-targets.js").then(m => m.targets)}'}, ${media ? `[...${q(reads)}, ...(options.media ? ${q(mediaTools.filter(tool => tool.annotations.readOnlyHint).map(tool => ({ name: tool.name, surface: "admin" })))} : [])]` : q(reads)});
+}
+` };
+}

package/dist/usecase/paging.js

@@ -0,0 +1,71 @@
+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";
+import { driverFor, databaseImport, isSqlite, q } from "../domain/entry.js";
+import { recipesOf } from "../domain/recipes.js";
+export function emitPaging(plan, lowered, target, refuse, proofs, boundary = false) {
+    const files = {}, base = "@aotter/mantle/";
+    const sqlite = isSqlite(target);
+    const user = userReferences(plan, sqlite);
+    const driver = driverFor(target);
+    for (const [name, view] of Object.entries(plan.views)) {
+        if (boundary && (view.surface === "internal" || !outputConversions(plan, name, target).some(([, type]) => type === "int")))
+            continue;
+        const path = `views/${name}`, sel = view.stmts[0]?.SelectStmt;
+        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`).");
+            continue;
+        }
+        const mode = view.surface === "public" ? "public" : "caller";
+        const c = lowered.views[name]?.[mode], trusted = mode === "caller" ? lowered.views[name]?.trusted : undefined;
+        if (!c)
+            continue;
+        const hidden = new Set(Array.from({ length: c.nkeys }, (_, i) => `_k${i}`));
+        if (Object.values(c.paged).some(p => p.names.some(name => hidden.has(sqlite ? name.toLowerCase() : name)))) {
+            if (view.surface !== "internal")
+                refuse(path, "Paged output names must not collide with the compiler's hidden cursor keys.");
+            continue;
+        }
+        const cap = sel.limitCount?.A_Const?.ival?.ival ?? 500;
+        if (sel.limitCount && (!sel.limitCount.A_Const?.ival || !Number.isInteger(cap) || cap < 1)) {
+            refuse(path, "A paged View LIMIT must be a positive integer literal.");
+            continue;
+        }
+        const values = new Set();
+        const kinds = proof.types.map(type => {
+            if (type === "date" || type === "timestamptz")
+                values.add(type === "date" ? "date" : "timestamp");
+            return type === "bool" ? "bool" : type === "int4" ? "int4" : ["integer", "int8"].includes(type) ? "int" : parseNumeric(type) ? "numeric" : ["real", "float8"].includes(type) ? "float" : type === "date" ? "date" : type === "timestamptz" ? "timestamp" : "text";
+        });
+        const variants = [c, ...(trusted ? [trusted] : [])].map(v => {
+            const pages = Object.values(v.paged);
+            const first = pages.find(p => !p.sources.some(s => "cursor" in s)), next = pages.find(p => p.sources.some(s => "cursor" in s));
+            if (!first || v.nkeys !== proof.types.length || v.nkeys > 0 && !next) {
+                refuse(path, "Core could not lower this View's keyset pages.");
+                return "";
+            }
+            const recipes = recipesOf(v, Object.keys(view.input?.properties ?? {}), message => refuse(path, message), values);
+            const page = (p) => `{ sql: ${q(p.sql)}, extra: ${q(p.sources.map(s => "cursor" in s ? s.cursor : -1))} }`;
+            return `{ binds: ${q(recipes)}, first: ${page(first)}, next: ${page(next ?? first)} }`;
+        });
+        const auth = authLines(view.requires, path);
+        const spec = [`path: ${q(path)}`, `cap: ${cap}`, `sqlite: ${sqlite}`, `cursor: ${q(kinds)}`, `keys: ${c.nkeys}`, `values: {${user.used ? [...values].sort().concat(user.values).join(", ") : values.size ? ` ${[...values].sort().join(", ")} ` : ""}}`, "read", `caller: ${variants[0]}`, ...(trusted ? [`trusted: ${variants[1]}`] : []), ...(auth.length ? [`auth: (caller: Caller) => {\n${auth.join("\n")}\n  }`] : [])];
+        files[`paged/${boundary ? "wire/" : ""}views/${encodeURIComponent(name)}.ts`] = `${user.code ? user.code + "\n" : ""}import { page, type Paged } from "${base}paging";
+import { ${auth.length ? "deny, isAdmin, isUser, " : ""}type Caller${sqlite ? "" : ", type Unsafe as Database"} } from "${base}contracts";
+${sqlite ? databaseImport(target) + "\n" : ""}import { read } from "${base}driver/${driver}";
+${values.size ? `import { ${[...values].sort().join(", ")} } from "${base}dialect/${sqlite ? "sqlite" : "postgres"}";\n` : ""}import type { Input, Row } from "${boundary ? "../../../" : "../../"}views/${encodeURIComponent(name)}.js";
+const spec: Paged<Database> = {
+  ${spec.join(",\n  ")},
+};
+export default (db: Database, caller: Caller, input: Input, options?: { limit?: number; cursor?: string }) => page<Database, Row>(${user.used ? "{ ...spec, caller: USER.scopedAll(spec.caller, caller) }" : "spec"}, db, caller, input, options);
+`;
+    }
+    return files;
+}

package/dist/usecase/publishing.js

@@ -0,0 +1,63 @@
+/** 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";
+import { renderTerm } from "../kernel/store.js";
+import { publishedParent } from "./translations.js";
+import { entry, exportName, q } from "../domain/entry.js";
+import { publishingAnnotations, publishingInput, publishingTransitions } from "../domain/generated-tools.js";
+export { publishingAnnotations, publishingInput, publishingTransitions };
+export function emitPublishing(plan, isSqlite, declarations, procedures, entries, values, refuse) {
+    const d = isSqlite ? sqlite : postgres;
+    const translations = Object.values(plan.schemas).some(s => s.translates);
+    if (translations)
+        declarations.push('import {translationWrite} from "@aotter/mantle/driver/transaction-context";');
+    if (Object.values(plan.schemas).some(s => s.publishing))
+        declarations.push('import { transition } from "@aotter/mantle/publishing";');
+    for (const s of Object.values(plan.schemas).filter(s => s.publishing).sort((a, b) => a.name.localeCompare(b.name))) {
+        if (Object.hasOwn(s.fields, "published_at")) {
+            refuse(`schemas/${s.name}`, "published_at is a publishing system column; remove the declared field.");
+            continue;
+        }
+        if (s.ttl)
+            values.add("cutoff");
+        for (const [verb, from, to] of publishingTransitions) {
+            const name = `${s.name}.${verb}`, fn = exportName("procedure", name), path = `procedures/${name}`;
+            const failure = `${verb}: row is missing or excluded, expectedVersion differs, status is not ${from.join(" or ")}${verb === "publish" ? `, or required data is missing${s.translates ? ", or no visible published parent shares the join key" : ""}` : ""}.`;
+            if (plan.procedures[name]) {
+                refuse(path, "This name is reserved for the generated publishing transition.");
+                continue;
+            }
+            const statement = (trusted) => {
+                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))));
+                if (verb === "publish")
+                    for (const field of s.schema.required ?? []) {
+                        const column = Object.keys(s.fields).find(c => (s.names?.[c] ?? c) === field);
+                        if (column)
+                            conditions.push(`${d.ident(column)} IS NOT NULL`);
+                    }
+                if (verb === "publish" && s.translates)
+                    conditions.push(publishedParent(plan, schema, d, recipes, trusted));
+                const clock = d.param(1);
+                return { sql: `UPDATE ${d.ident(s.name)} SET status = '${to}', published_at = ${verb === "publish" ? clock : "NULL"}, version = version + 1, updated_at = ${clock} WHERE ${conditions.join(" AND ")} RETURNING id, version, status, ${d.wireTimestamp(d.ident("published_at")).join("")} AS published_at`, binds: recipes, row: true };
+            };
+            values.add("now");
+            const caller = q([statement(false)]), trusted = q([statement(true)]);
+            declarations.push(`export type ${fn}Input = { readonly id: string; readonly expectedVersion: number };`, `const ${fn}Caller = ${caller} as const;`, ...(trusted === caller ? [] : [`const ${fn}Trusted = ${trusted} as const;`]), `async function ${fn}(db: Database, caller: Caller, raw: ${fn}Input): Promise<Output> { ${plan.access ? 'USER.modeOf(caller); ' : ''}return transition(db, caller, raw, ${q(path)}, ${plan.access ? "USER.scopedAll(" : ""}${trusted === caller ? "" : `${plan.access ? 'USER.modeOf(caller) === "trusted"' : 'caller.kind === "system"'} ? ${fn}Trusted : `}${fn}Caller${plan.access ? ", caller)" : ""}, ${q(failure)}, D, DRIVER.procedure${translations ? `, () => translationWrite(db, ${q(s.name)}, ${verb === "publish" && s.translates ? q(s.translates.parent) : "undefined"})` : ""}); }`, `export { ${fn} };`);
+            procedures.push(`[${q(name)}]: ${fn}`);
+            entries[`procedures/${encodeURIComponent(name)}.ts`] = entry("procedure", name, `${fn}Input as Input`, 'export type { Output } from "@aotter/mantle/contracts";\n');
+        }
+    }
+}
+/** 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(", ")})`);
+}

package/dist/usecase/refusals.js

@@ -0,0 +1,27 @@
+import { viewOutputs } from "../build/compiler.js";
+export function refuseDeclarations({ plan }, diagnostics) {
+    const refuse = (path, message) => diagnostics.push({ code: "GENERATE_UNSUPPORTED", path, message });
+    for (const [name, trigger] of Object.entries(plan.triggers)) {
+        const kind = trigger.source.kind;
+        if (kind === "http" || kind === "mcp")
+            continue;
+        refuse(`triggers/${name}`, kind === "schedule" ? "Schedule Triggers are unsupported. Wire scheduled() yourself." : "Before/after lifecycle hooks are unsupported. Write a custom handler.");
+    }
+    for (const [name, schema] of Object.entries(plan.schemas)) {
+        const parent = schema.translates && plan.schemas[schema.translates.parent.toLowerCase()];
+        if (parent?.scope && schema.scope !== parent.scope)
+            refuse(`schemas/${name}/translates`, `Scoped translation parent '${schema.translates.parent}' requires the same child scope column '${parent.scope}'. Different or missing child scope columns cannot be correlated safely.`);
+    }
+    for (const [kind, declarations] of [["views", plan.views], ["procedures", plan.procedures]]) {
+        for (const [name, declaration] of Object.entries(declarations)) {
+            if (declaration.requires?.guard)
+                refuse(`${kind}/${name}/requires/guard`, "Dynamic authorization guards are unsupported. Write a custom handler that checks authorization before executing queries.");
+        }
+    }
+    for (const [name, view] of Object.entries(plan.views)) {
+        for (const [key, column] of Object.entries(viewOutputs(view, plan.schemas, new Map(), true).columns))
+            if (plan.schemas[column.schema]?.fields[column.field] === "geo") {
+                refuse(`views/${name}/columns/${key}`, "Native geo projection is unsupported. Select the latitude and longitude columns explicitly.");
+            }
+    }
+}

package/dist/usecase/rest.js

@@ -0,0 +1,54 @@
+import { databaseImport, q, viewImports } from "../domain/entry.js";
+import { authLines, conversions } from "../domain/input.js";
+import { boundaryPage, outputConversions } from "../domain/columns.js";
+export function emitRest(plan, lowered, target, description) {
+    const guard = (requires, path, binds = [], trustedOnly = false) => {
+        const lines = authLines(requires, path, binds, !target.endsWith("postgres"), trustedOnly);
+        return lines.length ? `, check: (caller) => {${lines.join("")}}` : "";
+    };
+    const userImport = plan.access ? ['import { userBinds } from "@aotter/mantle/user-fields";'] : [];
+    const refs = Object.values(plan.procedures).some(p => "ref" in p.handler);
+    const imports = [...userImport, 'import { rest as serve, type Options } from "@aotter/mantle/rest";', databaseImport(target), ...(refs ? ['import { store, type Handlers } from "./generated.js";'] : [])];
+    if (Object.values(plan.procedures).some(p => p.trustedOnly) || [...Object.values(plan.views), ...Object.values(plan.procedures)].some(p => p.requires?.auth?.all.length))
+        imports.push('import { deny, isAdmin, isUser } from "@aotter/mantle/contracts";');
+    const views = [], procedures = [];
+    let hasWire = false;
+    const convert = (code) => code ? `, convert: ${code}` : "";
+    // Each segment matches in its encoded form; `{name}` segments capture.
+    const route = (method, path) => {
+        const keys = [];
+        const source = path.split("/").map(segment => segment.startsWith("{") && segment.endsWith("}") ? (keys.push(segment.slice(1, -1)), "([^/]+)") : encodeURIComponent(segment).replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("/");
+        return `method: ${q(method)}, pattern: new RegExp(${q("^" + source + "/?$")})${keys.length ? `, keys: ${q(keys)}` : ""}`;
+    };
+    for (const [name, view] of Object.entries(plan.views)) {
+        if (view.surface !== "public")
+            continue;
+        const id = views.length, encoded = encodeURIComponent(name);
+        const wire = outputConversions(plan, name, target);
+        imports.push(...viewImports(name, id).map(line => wire.some(([, type]) => type === "int") ? line.replaceAll("./paged/views/", "./paged/wire/views/") : line));
+        hasWire ||= wire.length > 0;
+        views.push(`{ ${route("GET", `/api/views/${name}`)}, target: ${q({ kind: "view", name })}${guard(view.requires, `views/${name}`, (lowered.views[name]?.public ?? lowered.views[name]?.caller)?.binds)}, query: query${id}, page: ${boundaryPage(`page${id}`, wire)}${convert(conversions(view.input?.properties, (lowered.views[name]?.public ?? lowered.views[name]?.caller)?.binds ?? [], target))} }`);
+    }
+    const triggers = Object.values(plan.triggers).filter(t => t.source.kind === "http").sort((a, b) => a.source.kind === "http" && b.source.kind === "http" ? (a.source.path.match(/\{/g)?.length ?? 0) - (b.source.path.match(/\{/g)?.length ?? 0) : 0);
+    for (const trigger of triggers) {
+        if (trigger.source.kind !== "http")
+            continue;
+        const { method, path } = trigger.source, name = trigger.procedure, procedure = plan.procedures[name], id = procedures.length, ref = "ref" in procedure.handler;
+        if (!ref)
+            imports.push(`import procedure${id} from "./procedures/${encodeURIComponent(name)}.js";`);
+        imports.push(`import { validate as validate${id} } from "./validation/procedures/${encodeURIComponent(name)}.js";`);
+        const params = Object.fromEntries([...path.matchAll(/\{([^}]+)\}/g)].flatMap(([, key]) => {
+            const type = [procedure.input?.properties?.[key]?.type].flat().find(t => t && t !== "null");
+            return type === "integer" || type === "number" ? [[key, "number"]] : type === "boolean" ? [[key, "boolean"]] : [];
+        }));
+        procedures.push(`{ ${route(method, path)}, id: ${q(`rest:${method} ${path.replace(/\{([^}]+)\}/g, ":$1")}`)}, target: ${q({ kind: "procedure", name })}${description.targets.find(t => t._meta.id === `procedure:${name}`)?._meta.readOnly ? ", readOnly: true" : ""}${guard(procedure.requires, `procedures/${name}`, lowered.procedures[name]?.caller?.flatMap(s => s.binds), procedure.trustedOnly)}${Object.keys(params).length ? `, params: ${q(params)}` : ""}, validate: validate${id}${convert(conversions(procedure.input?.properties, lowered.procedures[name]?.caller?.flatMap(s => s.binds) ?? [], target))}, run: ${ref ? `(db, caller, input, handlers) => store(db, caller, { handlers }).procedures[${q(name)}](input)` : `procedure${id}`} }`);
+    }
+    if (hasWire)
+        imports.push('import { wireRows } from "@aotter/mantle/contracts";');
+    const list = (items) => items.length ? `[\n${items.map(item => "    " + item + ",\n").join("")}  ]` : "[]";
+    return { "rest.ts": `${imports.join("\n")}
+export function rest<Env>(options: Options<Env, Database>${refs ? " & { handlers: Handlers }" : ""}): (request: Request, env: Env, ctx?: import("@aotter/mantle/contracts").RequestContext) => Promise<Response | undefined> {
+  return serve<Env, Database${refs ? ", Handlers" : ""}>(${list([...views, ...procedures])}, ${plan.access ? `{...options, fields: ${q(plan.access.userFields)}, accessTargets: () => import("./access-targets.js").then(m => m.targets)}` : '{...options, accessTargets: () => import("./access-targets.js").then(m => m.targets)}'});
+}
+` };
+}

package/dist/usecase/search.js

@@ -0,0 +1,7 @@
+export function searchDiagnostics(warnings) {
+    return [...new Set(warnings.filter(message => /mantle\.search|search fields/.test(message)).map(message => message.replace(/^(plan#\/[^ ]+) \([^)]*\): /, "$1: ")))].map(message => ({
+        code: "GENERATE_UNSUPPORTED",
+        path: /^plan#\/([^: ]+)/.exec(message)?.[1] ?? "views",
+        message: `${message}. Declare searchableFields on the source Schema; search_rank needs mantle.search on the same alias in the same query.`,
+    }));
+}

package/dist/usecase/site.js

@@ -0,0 +1,39 @@
+/** Generate the optional site/media module and deployment DDL, never runtime preparation. */
+import { assertSiteDefaultsCanonical, canonicalizeLocaleList, expandPolicyRequired } from "../build/compiler.js";
+import { driverFor, isSqlite, q } from "../domain/entry.js";
+export function emitSite(target, defaults, refuse, schemaNames) {
+    if (!defaults)
+        return {};
+    try {
+        assertSiteDefaultsCanonical(defaults);
+    }
+    catch (error) {
+        refuse("site", String(error.message));
+        return {};
+    }
+    for (const name of schemaNames)
+        if (["site_config", "media_assets", "pending_media_uploads"].includes(name.toLowerCase()))
+            refuse(`schemas/${name}`, "This table name is reserved by the selected site/media module.");
+    if (new Set(defaults.media?.purposes?.map(p => p.name)).size !== (defaults.media?.purposes?.length ?? 0))
+        refuse("site/media/purposes", "Media purpose names must be unique.");
+    defaults = { ...defaults, ...(defaults.locales ? { locales: canonicalizeLocaleList(defaults.locales).valid } : {}) };
+    const pg = !isSqlite(target), driver = driverFor(target);
+    const policies = defaults.media?.purposes?.map(p => ({ ...p, required: expandPolicyRequired(p.required).map(slot => slot.join(",")) })) ?? [];
+    const seed = ["brand", "title", "description"].filter(key => defaults[key]).map(key => `INSERT INTO site_config (key,value) VALUES ('${key}','${defaults[key].replaceAll("'", "''")}') ON CONFLICT(key) DO NOTHING;`).join("\n");
+    const root = "@aotter/mantle";
+    return { "site.ts": `import { createSite } from "${root}/site";
+import type { Caller } from "${root}/contracts";
+import type { ${pg ? "Postgres" : "Handle"} as Database } from "${root}/${pg ? "contracts" : `driver/${driver}`}";
+import * as DRIVER from "${root}/driver/${driver}";
+import { param, escapeLike, likeEscape, like } from "${root}/dialect/${pg ? "postgres" : "sqlite"}";
+export const siteDefaults = ${q(defaults)} as const;
+const policies = ${q(policies)} as const;
+export function site(db: Database, caller: Caller) { return createSite({read:(sql,values)=>DRIVER.read(db,sql,values),write:steps=>DRIVER.procedure(db,steps,"site"),definitive:DRIVER.definitive},{param,escapeLike,likeEscape,like},caller,siteDefaults,policies); }
+`, "site-seed.sql": seed + "\n", "site-schema.sql": `CREATE TABLE site_config (key TEXT PRIMARY KEY, value TEXT NOT NULL);
+CREATE TABLE media_assets (id TEXT PRIMARY KEY, created_at ${pg ? "BIGINT" : "INTEGER"} NOT NULL, owner_id TEXT, alt TEXT, caption TEXT, variants TEXT NOT NULL, metadata TEXT);
+CREATE INDEX media_assets_by_created_id ON media_assets (created_at DESC, id DESC);
+CREATE TABLE pending_media_uploads (id TEXT PRIMARY KEY, record TEXT NOT NULL, expires_at ${pg ? "BIGINT" : "INTEGER"} NOT NULL);
+CREATE INDEX pending_media_uploads_expires_at ON pending_media_uploads (expires_at);
+${seed}
+` };
+}

package/dist/usecase/stores.js

@@ -0,0 +1,64 @@
+/**
+ * One typed collection per Schema, over the generic `createStore`. Core's row rules (`rowPolicy`, `writePolicy`) are evaluated
+ * here, at build time, ONCE for a placeholder scope and TTL into the shared `Rules`; a Schema adds only a `Fact` (scope, TTL,
+ * publishing, its date-time and date columns). Generation is refused if a Schema's expanded rules differ from Core's own for it
+ * (caller and trusted rows, insert fills, update sets and lock, delete lock).
+ * Column names, value types, writable columns and `orderBy` are TypeScript types only: nothing at runtime knows them.
+ */
+import { NATIVE_NOT_NULL, notNullColumns, rowPolicy, writePolicy } from "../build/compiler.js";
+import { declaredType, inputType, nativeType } from "../domain/columns.js";
+import { q } from "../domain/entry.js";
+import { expand, SCOPE, TTL } from "../kernel/store.js";
+import { refChecks, userScopeTerm } from '../build/compiler.js';
+// Types the typed Store compares and writes as plain bind values. Fixed numerics are scaled integers on SQLite; geo is two columns.
+const SCALAR = new Set(["text", "real", "float8", "integer", "int4", "int8", "bool", "timestamptz", "date"]);
+/** Core's own rules for a Schema, in the shape of `Rules` without the id expression (a delete's lock is compared separately). */
+const core = (s, schemas) => {
+    const update = writePolicy(s, "update", { lock: true });
+    return { caller: rowPolicy(s, "caller", schemas), trusted: rowPolicy(s, "trusted", schemas), fills: writePolicy(s, "insert").fills, sets: update.sets, lock: update.lock };
+};
+const probe = { scope: SCOPE, ttl: TTL, ttlSeconds: 0, publishing: true };
+/** @internal */
+export function emitStores(schemas, isSqlite, newId, refuse, required = false) {
+    const all = Object.values(schemas).sort((a, b) => a.name < b.name ? -1 : 1);
+    if (!all.length && !required)
+        return undefined;
+    const rules = { ...core(probe), newId };
+    const tables = [], facts = [];
+    for (const s of all) {
+        const type = (column) => declaredType(s.fields, column) ?? (column === "version" ? "integer" : column === "published_at" ? "timestamptz" : "text");
+        const declared = Object.keys(s.fields).filter(f => f !== s.scope && s.fields[f] !== "geo");
+        const geo = Object.keys(s.fields).filter(f => s.fields[f] === "geo").flatMap(f => [`${f}_lat`, `${f}_lng`]); // `*` returns a geo field's two columns
+        const names = [...["id", "version", "created_at", "updated_at", "author_id", ...(s.publishing ? ["status", "published_at"] : [])], ...declared];
+        const required = new Set(s.schema.required ?? []), notNull = notNullColumns(s);
+        const nonNull = (column) => NATIVE_NOT_NULL.has(column) || notNull.has(column);
+        const ts = [...(s.publishing ? ["published_at"] : []), ...declared.filter(c => s.fields[c] === "timestamptz")], dates = declared.filter(c => s.fields[c] === "date");
+        const parent = s.translates && schemas[s.translates.parent.toLowerCase()];
+        const inherited = parent ? Object.keys(parent.fields).filter(c => c !== parent.scope && !Object.hasOwn(s.fields, c)).flatMap(c => parent.fields[c] === "geo" ? [`${c}_lat`, `${c}_lng`] : [c]) : [];
+        const inheritedType = (c) => parent?.fields[c] ?? "real";
+        const ref = refChecks(s, schemas);
+        const fact = {
+            ...(s.userScopes?.length ? { u: s.userScopes.map(u => userScopeTerm(u, true)) } : {}),
+            ...(s.scope ? { s: s.scope } : {}), ...(s.ttl ? { ttl: [s.ttl, s.ttlSeconds ?? 0] } : {}), ...(s.publishing ? { pub: 1 } : {}),
+            ...(ts.length ? { ts } : {}), ...(dates.length ? { d: dates } : {}),
+            ...(s.search?.length ? { search: s.search } : {}),
+            ...(ref.length ? { ref } : {}),
+            ...(parent ? { parent: { on: s.translates.on.toLowerCase(), ...(parent.scope ? { scope: [parent.scope, s.scope] } : {}), table: s.translates.parent.toLowerCase(), visible: rowPolicy(s, "caller", schemas).find(t => t[1] === "parent"), caller: rowPolicy(parent, "caller", schemas), trusted: rowPolicy(parent, "trusted", schemas), fields: inherited, ts: inherited.filter(c => parent.fields[c] === "timestamptz"), d: inherited.filter(c => parent.fields[c] === "date") } } : {}),
+        };
+        // the shared rules, with this Schema's scope and TTL put in, are Core's rules for it: or the runtime would enforce something else
+        const expected = q([core(s, schemas), writePolicy(s, "delete", { lock: true }).lock]), got = q([expand(rules, fact), rules.lock]);
+        if (expected !== got)
+            refuse(`schemas/${s.name}`, `Core's row rules for this Schema differ from the shared rules (${expected} vs ${got}); the generic Store cannot serve it.`);
+        // ORDER BY is allowed where the caller's scoped read can walk an index (its first column, or the one after the scope column) and the column is NOT NULL.
+        const indexed = new Set([...(s.publishing ? [[...(s.scope ? [s.scope] : []), "published_at", "id"]] : []), ...(s.indexes ?? []), ...(s.unique ?? [])].map(i => i[0] === s.scope ? i[1] : i[0]).filter((c) => !!c));
+        const key = (c) => /^[A-Za-z_]\w*$/.test(c) ? c : q(c);
+        const of = (columns, value) => `{ ${columns.map(c => `${key(c)}: ${value(c)};`).join(" ")} }`;
+        const union = (columns) => columns.map(c => q(c)).join(" | ") || "never";
+        const scalar = (c) => SCALAR.has(type(c));
+        const writable = declared.filter(c => !(s.userScopes ?? []).some(u => u.column === c) && (scalar(c) || type(c) === "json"));
+        const input = (c) => `${inputType(type(c))}${nonNull(c) ? "" : " | null"}`;
+        tables.push(`${key(s.name)}: { row: ${of([...names, ...geo], c => c === "id" ? "string" : nativeType(geo.includes(c) ? "real" : type(c), isSqlite, nonNull(c)))}${inherited.length ? ` & { ${inherited.map(c => `${key(c)}?: ${nativeType(inheritedType(c), isSqlite)};`).join(" ")} }` : ""}; fields: ${of(names.filter(scalar), c => inputType(type(c)))}; set: ${of(writable, input)}${s.userScopes?.length ? `; insert: ${of([...writable, ...s.userScopes.map(u => u.column)], input)}` : ""}; required: ${union(s.publishing ? [] : writable.filter(c => required.has(s.names?.[c] ?? c)))}; order: ${union(["id", ...names.filter(c => c !== "id" && scalar(c) && indexed.has(c) && (nonNull(c) || s.publishing && c === "published_at"))])} }`);
+        facts.push(`${q(s.name)}: ${q(fact)}`);
+    }
+    return { tables: `{ ${tables.join("; ")} }`, rules: q(rules), facts: `{ ${facts.join(", ")} }` };
+}

package/dist/usecase/tool-version.js

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

package/dist/usecase/translations.js

@@ -0,0 +1,78 @@
+import { userReferences } from "../domain/userReferences.js";
+/** Translation helpers use generated SQL policy, never a request-time manifest. */
+import { rowPolicy } from "../build/compiler.js";
+import { renderTerm } from "../kernel/store.js";
+import { dialect as SQLITE } from "../kernel/dialect/sqlite.js";
+import { dialect as POSTGRES } from "../kernel/dialect/postgres.js";
+import { declaredType } from "../domain/columns.js";
+import { driverFor, isSqlite, q } from "../domain/entry.js";
+/** The parent is checked by the same atomic UPDATE that publishes the child. */
+export function publishedParent(plan, child, d, recipes, trusted) {
+    const tr = child.translates, parent = plan.schemas[tr.parent.toLowerCase()], on = tr.on.toLowerCase();
+    const conditions = [`p.${d.ident(on)} = ${d.ident(child.name)}.${d.ident(on)}`];
+    if (parent.scope)
+        conditions.push(`p.${d.ident(parent.scope)} = ${d.ident(child.name)}.${d.ident(child.scope ?? parent.scope)}`);
+    if (parent.publishing)
+        conditions.push("p.status = 'published'");
+    for (const term of rowPolicy(parent, trusted ? "trusted" : "caller", plan.schemas))
+        conditions.push(renderTerm(d, term, "p.", recipe => (recipes.push(recipe), d.param(recipes.length))));
+    return `EXISTS (SELECT 1 FROM ${d.ident(parent.name)} p WHERE ${conditions.join(" AND ")})`;
+}
+export function emitTranslations(plan, target) {
+    const d = isSqlite(target) ? SQLITE : POSTGRES;
+    const user = userReferences(plan, isSqlite(target));
+    const children = Object.values(plan.schemas).filter(s => s.translates);
+    if (!Object.values(plan.schemas).some(s => s.localized))
+        return {};
+    if (!children.length)
+        return { "translations.ts": 'export {toCanonicalLocale} from "@aotter/mantle/translations";\n' };
+    const parents = [...new Set(children.map(s => s.translates.parent.toLowerCase()))], declarations = [], descriptors = [];
+    const driver = driverFor(target);
+    for (const parent of parents) {
+        const schema = plan.schemas[parent], types = children.filter(s => s.translates.parent.toLowerCase() === parent);
+        const entries = types.map(child => {
+            const on = child.translates.on.toLowerCase(), type = declaredType(child.fields, on);
+            const key = "t." + d.ident(on), projection = type === "timestamptz" ? d.wireTimestamp(key).join("") : type === "date" ? d.wireDate(key).join("") : key;
+            const lower = (mode) => {
+                const terms = rowPolicy(plan.schemas[child.name], mode, plan.schemas), recipes = [];
+                const where = terms.map(term => renderTerm(d, term, "t.", recipe => (recipes.push(recipe), d.param(recipes.length)))).join(" AND ");
+                return `{where:${q(where)},binds:${q(recipes)}}`;
+            };
+            return `{on:${q(on)},type:${q(type ?? "text")},sql:${q(`SELECT t.id AS _id, ${projection} AS _key, t.locale FROM ${d.ident(child.name)} t`)},caller:${lower('caller')},trusted:${lower('trusted')}}`;
+        });
+        const columns = [...new Set(types.map(s => s.translates.on.toLowerCase()))];
+        declarations.push(`${q(schema.name)}: Pick<Tables[${q(schema.name)}]["row"],${["id", ...columns.filter(c => c !== schema.scope)].map(value => q(value)).join("|")}>${schema.scope && columns.includes(schema.scope) ? ` & {readonly ${q(schema.scope)}?:string|null}` : ""};`);
+        descriptors.push(`${q(schema.name)}:[${entries.join(",")}]`);
+    }
+    return { "translations.ts": `${user.code ? user.code + "\n" : ""}import {ContractError,type Caller${driver === "postgres" ? ",type Unsafe as Database" : ""}} from "@aotter/mantle/contracts";
+${driver !== "postgres" ? `import type {Handle as Database} from "@aotter/mantle/driver/${driver}";` : ""}
+import {read} from "@aotter/mantle/driver/${driver}";
+import {binds,encode} from "@aotter/mantle/binds";
+import {param,ident${driver === "postgres" ? ",cast" : ""},timestamp,date} from "@aotter/mantle/dialect/${driver === "postgres" ? "postgres" : "sqlite"}";
+import type {Tables} from "./generated.js";
+export {toCanonicalLocale} from "@aotter/mantle/translations";
+export interface TranslationParents {${declarations.join("\n")}}
+const descriptors={${descriptors.join(",")}} as const;
+/** Only pass the current parent page (up to 500); reads are bounded to its keys. */
+export async function translationLocales<P extends keyof TranslationParents>(db:Database,caller:Caller,parent:P,parents:readonly TranslationParents[P][]):Promise<Record<string,string[]>> {
+${user.used ? ' USER.modeOf(caller);\n' : ''} if(parents.length>500)throw new ContractError("INPUT_VALIDATION_FAILED","Pass one parent page, at most 500 rows.","translations");
+ const out:Record<string,string[]>=Object.fromEntries(parents.map(row=>[row.id,[]]));
+ for(const child of descriptors[parent]) {
+  const rows=parents as readonly Record<string,unknown>[],keys=[...new Set(rows.map(row=>row[child.on]).filter(value=>value!==null&&value!==undefined&&value!==""))];
+  const byKey=new Map<unknown,Set<string>>(),mode=${user.used ? 'USER.modeOf(caller)==="trusted"' : 'caller.kind==="system"'}?child.trusted:child.caller;
+  for(let i=0;i<keys.length;i+=50) {
+   const base=binds(${user.used ? "USER_VALUES" : "{}"},mode.binds,caller),batch=keys.slice(i,i+50);let after:string|undefined;
+   do {
+    const values=[...base,...batch.map(value=>encode({timestamp,date},child.type,value))],where=[...(mode.where?[${user.used ? "USER.scoped(mode.where,caller)" : "mode.where"}]:[]),"t."+ident(child.on)+" IN ("+batch.map((_,index)=>${driver === "postgres" ? "cast(param(base.length+index+1),child.type)" : "param(base.length+index+1)"}).join(",")+")"];
+    if(after!==undefined){values.push(after);where.push("t.id > "+param(values.length));}
+    const translations:Record<string,unknown>[]=await read(db,child.sql+" WHERE "+where.join(" AND ")+" ORDER BY t.id LIMIT 500",values);
+    for(const row of translations)if(typeof row.locale==="string")byKey.set(row._key,(byKey.get(row._key)??new Set()).add(row.locale));
+    after=translations.length===500?String(translations.at(-1)!._id):undefined;
+   }while(after!==undefined);
+  }
+  for(const row of rows)for(const locale of byKey.get(row[child.on])??[])if(!out[String(row.id)]!.includes(locale))out[String(row.id)]!.push(locale);
+ }
+ return out;
+}
+` };
+}

package/dist/usecase/ttl.js

@@ -0,0 +1,20 @@
+import { dialect as sqlite } from "../kernel/dialect/sqlite.js";
+import { dialect as postgres } from "../kernel/dialect/postgres.js";
+import { entry, exportName, q } from "../domain/entry.js";
+export function emitTtl(plan, isSqlite, declarations, procedures, entries, refuse) {
+    const d = isSqlite ? sqlite : postgres;
+    const schemas = Object.values(plan.schemas).filter(s => s.ttl).sort((a, b) => a.name.localeCompare(b.name));
+    if (schemas.length)
+        declarations.push(`import { sweep as sweepTtl } from "@aotter/mantle/sweep";`, `import { cutoff as ttlCutoff } from "@aotter/mantle/dialect/${isSqlite ? "sqlite" : "postgres"}";`);
+    for (const s of schemas) {
+        const name = `${s.name}.sweepExpired`, fn = exportName("procedure", name), path = `procedures/${name}`;
+        if (plan.procedures[name]) {
+            refuse(path, "This name is reserved for generated TTL maintenance.");
+            continue;
+        }
+        const pick = `SELECT _rid FROM ${d.ident(s.name)} WHERE ${d.ident(s.ttl)} IS NOT NULL AND ${d.ident(s.ttl)} <= ${d.param(1)} AND _rid > ${d.param(2)} ORDER BY _rid LIMIT ${d.param(3)}`;
+        declarations.push(`export type ${fn}Input = import("@aotter/mantle/sweep").SweepInput;`, `export type ${fn}Result = import("@aotter/mantle/sweep").SweepResult;`, `async function ${fn}(db: Database, caller: Caller, input: ${fn}Input = {}): Promise<${fn}Result> { return sweepTtl(db, caller, input, ${q(path)}, ${s.ttlSeconds}, ${q([pick, `DELETE FROM ${d.ident(s.name)} WHERE _rid IN (${pick}) RETURNING _rid`])}, {cutoff: ttlCutoff}, DRIVER.procedure); }`, `export { ${fn} };`);
+        procedures.push(`[${q(name)}]: ${fn}`);
+        entries[`procedures/${encodeURIComponent(name)}.ts`] = entry("procedure", name, `${fn}Input as Input, ${fn}Result as Output`);
+    }
+}