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

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,40 @@
+/** 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 INDEX media_assets_by_owner_created ON media_assets (owner_id, created_at DESC);
+CREATE TABLE pending_media_uploads (id TEXT PRIMARY KEY, record TEXT NOT NULL, expires_at ${pg ? "BIGINT" : "INTEGER"} NOT NULL);
+CREATE INDEX pending_media_uploads_expires_at ON pending_media_uploads (expires_at);
+${seed}
+` };
+}

package/dist/usecase/stores.js

@@ -0,0 +1,62 @@
+/**
+ * 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 { 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 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 } : {}),
+            ...(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/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 Postgres 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`);
+    }
+}

package/dist/usecase/validation.js

@@ -0,0 +1,132 @@
+import { q } from "../domain/entry.js";
+import { publishingInput } from "./publishing.js";
+const pointer = (key) => key.replace(/~/g, "~0").replace(/\//g, "~1");
+const supported = new Set("$defs $ref $schema $id type nullable properties required additionalProperties items enum format pattern minLength maxLength minimum maximum exclusiveMinimum exclusiveMaximum multipleOf minItems maxItems title description default readOnly writeOnly examples deprecated x-mantle-ref x-mcp-hint".split(" "));
+const bounds = [
+    ["string", "[...value].length", { minLength: "<", maxLength: ">" }],
+    ["number", "value", { minimum: "<", maximum: ">", exclusiveMinimum: "<=", exclusiveMaximum: ">=" }],
+    ["array", "value.length", { minItems: "<", maxItems: ">" }],
+];
+const condition = (type) => ({ null: "value === null", array: "Array.isArray(value)", object: 'typeof value === "object" && value !== null && !Array.isArray(value)', integer: 'typeof value === "number" && Number.isSafeInteger(value)', number: 'typeof value === "number" && Number.isFinite(value)' })[type] ?? `typeof value === ${q(type)}`;
+const typeCheck = (types) => `if (!(${types.map(type => `(${condition(type)})`).join(" || ")})) fail(path, ${q(`Expected ${types.join(" or ")}.`)});`;
+export function emitValidation(plan, refuse = (path, message) => { throw Error(`${path}: ${message}`); }) {
+    const files = {};
+    for (const [kind, operations] of [["views", plan.views], ["procedures", plan.procedures]])
+        for (const [name, operation] of Object.entries(operations)) {
+            const root = operation.input ?? { type: "object", additionalProperties: false };
+            const base = `${kind}/${name}/input`, file = `validation/${kind}/${encodeURIComponent(name)}.ts`;
+            const json = q(root);
+            if (kind === "procedures" && json === q(publishingInput)) {
+                files[file] = `import { transition } from "@aotter/mantle/validation";\nexport const validate = (raw: unknown) => transition(${q(base)}, raw);\n`;
+                continue;
+            }
+            // Only a local `$ref`, or more than 100 nested objects and arrays, can reach the nesting limit: only then is `depth` passed.
+            const recursive = json.includes('"$ref"') || json.split(/[[{]/).length > 101, depth = recursive ? ",depth+1" : "";
+            // Identical bodies share one function.
+            const nodes = new Map(), bodies = new Map(), functions = [], formats = new Set();
+            let equality = false;
+            const resolve = (ref) => {
+                let value = root;
+                try {
+                    if (typeof ref !== "string" || !ref.startsWith("#/"))
+                        throw Error();
+                    for (const key of decodeURIComponent(ref.slice(2)).split("/").map(key => key.replace(/~1/g, "/").replace(/~0/g, "~")))
+                        value = value && typeof value === "object" && Object.hasOwn(value, key) ? value[key] : undefined;
+                    if (value && typeof value === "object")
+                        return value;
+                }
+                catch { }
+                refuse(base, "Input ref must be a valid local JSON pointer.");
+                return {};
+            };
+            const emit = (schema) => {
+                if (nodes.has(schema))
+                    return nodes.get(schema);
+                const named = `check${nodes.size}`;
+                nodes.set(schema, named);
+                for (const key of Object.keys(schema))
+                    if (!supported.has(key))
+                        refuse(base, `Generated input validation does not support '${key}'.`);
+                const lines = recursive ? ['if (depth > 100) fail(path, "Input nesting exceeds 100 levels.");'] : [];
+                const check = (invalid, message) => lines.push(`if (${invalid}) fail(path, ${q(message)});`);
+                if (schema.nullable)
+                    lines.push("if (value === null) return;");
+                if (schema.$ref !== undefined)
+                    lines.push(`${emit(resolve(schema.$ref))}(value,path${depth});`);
+                const types = [schema.type].flat().filter((type) => !!type);
+                for (const type of types)
+                    if (!"null array object integer number string boolean".split(" ").includes(type))
+                        refuse(base, `Unsupported input type '${type}'.`);
+                if (types.length)
+                    lines.push(typeCheck(types));
+                // After a single type check `fail` (never) has narrowed `value`: that type's guard is implied.
+                const only = types.length === 1 ? types[0] : undefined;
+                const guard = (type, test = `(${condition(type)})`) => only === type || type === "number" && only === "integer" ? "" : test + " && ";
+                if (schema.enum) {
+                    equality = true;
+                    check(`!${q(schema.enum)}.some(option=>equal(value,option))`, "Value is not in enum.");
+                }
+                for (const [type, measure, keywords] of bounds)
+                    for (const [key, operator] of Object.entries(keywords))
+                        if (schema[key] !== undefined)
+                            check(`${guard(type)}${measure} ${operator} ${schema[key]}`, `Value violates ${key}.`);
+                if (schema.multipleOf !== undefined)
+                    check(`${guard("number", 'typeof value === "number"')}!(Math.abs(value / ${schema.multipleOf} - Math.round(value / ${schema.multipleOf})) < 1e-9)`, "Number violates multipleOf.");
+                if (schema.pattern !== undefined) {
+                    try {
+                        new RegExp(schema.pattern);
+                    }
+                    catch {
+                        refuse(base, "Input pattern is not a valid regular expression.");
+                    }
+                    check(`${guard("string", 'typeof value === "string"')}!new RegExp(${q(schema.pattern)}).test(value)`, "String does not match pattern.");
+                }
+                if (schema.format) {
+                    if (schema.format === "email")
+                        check(`${guard("string", 'typeof value === "string"')}!/^[^\\s@]+@[^\\s@]+$/u.test(value)`, "Expected an email with one @, non-empty local and domain parts, and no whitespace.");
+                    else if (!["date", "date-time"].includes(schema.format))
+                        refuse(base, `Generated input validation does not support format '${schema.format}'.`);
+                    else {
+                        const scalar = schema.format === "date" ? "encodeDate" : "encodeTimestamptz";
+                        formats.add(scalar);
+                        lines.push(`${only === "string" ? "" : 'if (typeof value === "string") '}try { ${scalar}(value); } catch { fail(path, ${q(`Expected a valid ${schema.format}.`)}); }`);
+                    }
+                }
+                if (schema.items)
+                    lines.push(`${only === "array" ? "" : "if (Array.isArray(value)) "}for (let i=0;i<value.length;i++) ${emit(schema.items)}(value[i],path+"/"+i${depth});`);
+                // Several keys that need no JSON-pointer escaping are checked by one loop, in the same order.
+                const required = schema.required ?? [], checks = Object.entries(schema.properties ?? {}).map(([key, child]) => [key, emit(child)]);
+                const loop = (keys) => keys.length > 1 && keys.every(key => pointer(key) === key);
+                const object = loop(required) ? [`for (const key of ${q(required)}) if (!Object.hasOwn(object,key)) fail(path+"/"+key,"Required field is missing.");`] : required.map(key => `if (!Object.hasOwn(object,${q(key)})) fail(path+${q("/" + pointer(key))},"Required field is missing.");`);
+                if (loop(checks.map(([key]) => key)))
+                    object.push(`for (const [key,check] of [${checks.map(([key, fn]) => `[${q(key)},${fn}]`)}] as const) if (Object.hasOwn(object,key)) check(object[key],path+"/"+key${depth});`);
+                else
+                    for (const [key, fn] of checks)
+                        object.push(`if (Object.hasOwn(object,${q(key)})) ${fn}(object[${q(key)}],path+${q("/" + pointer(key))}${depth});`);
+                if (schema.additionalProperties === false || typeof schema.additionalProperties === "object")
+                    object.push(`for (const key of Object.keys(object)) if (!(${q(Object.keys(schema.properties ?? {}))} as readonly string[]).includes(key)) { const childPath = path+"/"+key.replace(/~/g,"~0").replace(/\\//g,"~1"); ${schema.additionalProperties === false ? 'fail(childPath,"Unknown field.");' : `${emit(schema.additionalProperties)}(object[key],childPath${depth});`} }`);
+                if (object.length)
+                    lines.push(`${only === "object" ? "" : `if (${condition("object")}) `}{ const object = value as Record<string,unknown>;\n${object.join("\n")}\n}`);
+                const body = lines.join("\n");
+                // Without recursion nothing calls a check before its body is complete, so an identical body's function serves it.
+                const fn = recursive ? named : bodies.get(body) ?? named;
+                if (fn === named) {
+                    bodies.set(body, fn);
+                    functions.push(`function ${fn}(value:unknown,path:string${recursive ? ",depth:number" : ""}):void {\n${body}\n}`);
+                }
+                nodes.set(schema, fn);
+                return fn;
+            };
+            const validate = emit(root);
+            const fields = kind === "views" ? Object.entries(root.properties ?? {}).map(([key, schema]) => {
+                const type = [schema.type].flat().find(type => type && type !== "null");
+                return type === "boolean" || type === "integer" || type === "number" ? [key, type] : [key];
+            }) : undefined;
+            const helpers = [...(functions.length ? ["fail"] : []), ...(equality ? ["equal"] : []), ...(fields ? ["query as read"] : [])];
+            const code = `${helpers.length ? `import { ${helpers.join(", ")} } from "@aotter/mantle/validation";\n` : ""}${formats.size ? `import { ${[...formats].join(", ")} } from "@aotter/mantle/scalars";\n` : ""}${functions.join("\n")}
+export function validate(raw:unknown):Record<string,unknown> { ${validate}(raw,${q(base)}${recursive ? ",0" : ""}); return raw as Record<string,unknown>; }
+${fields ? `export const query = (params:URLSearchParams) => read(params, validate, ${q(`${kind}/${name}`)}, ${q(fields)});\n` : ""}`;
+            files[file] = code;
+        }
+    return files;
+}

package/dist/usecase/web.js

@@ -0,0 +1,22 @@
+import { databaseImport, q } from "../domain/entry.js";
+import { authLines, conversions } from "../domain/input.js";
+export function emitWeb(plan, lowered, target) {
+    const views = Object.entries(plan.views).filter(([, v]) => v.surface === "public");
+    const table = views.map(([name, v], i) => {
+        const binds = lowered.views[name]?.public?.binds ?? [], convert = conversions(v.input?.properties, binds, target);
+        const booleans = Object.keys(v.input?.properties ?? {}).filter(field => binds.some(b => b.k === "input" && String(b.name).toLowerCase() === field.toLowerCase() && String(b.type) === "bool"));
+        const check = authLines(v.requires, `views/${name}`, binds, !target.endsWith("postgres"));
+        return `[${q(name)}, { ${check.length ? `check: (caller) => {${check.join("")}}, ` : ""}query: input${i}, page: async (db, caller, input, paging) => (await import("./paged/views/${encodeURIComponent(name)}.js")).default(db, caller, input, paging)${convert ? `, convert: ${convert}` : ""}${booleans.length ? `, booleans: ${q(booleans)}` : ""} }]`;
+    });
+    return { "web.ts": [
+            ...(plan.access ? ['import { userBinds } from "@aotter/mantle/user-fields";'] : []),
+            ...([...Object.values(plan.views)].some(v => v.requires?.auth?.all.length) ? ['import { deny, isAdmin, isUser } from "@aotter/mantle/contracts";'] : []),
+            ...views.flatMap(([n], i) => [`import { query as input${i} } from "./validation/views/${encodeURIComponent(n)}.js";`, `import type { Row as Row${i} } from "./views/${encodeURIComponent(n)}.js";`]),
+            'import { web as site, type Options, type Page } from "@aotter/mantle/web";',
+            databaseImport(target),
+            `type App = { Rows: {${views.map(([n], i) => `${q(n)}:Row${i}`).join(";")}}; Inputs: {${views.map(([n, v]) => `${q(n)}:${Object.keys(v.input?.properties ?? {}).map(k => q(k)).join(" | ") || "never"}`).join(";")}}; List: ${views.filter(([, v]) => !v.input?.required?.length).map(([n]) => q(n)).join(" | ") || "never"} };`,
+            "export function web<const P extends Record<string, Page<App>>, E = unknown>(options: Options<App, Database, P, E>) {",
+            `  return site<Database, E>(${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)}'}, [${table.join(", ")}]);`,
+            "}"
+        ].join("\n") + "\n" };
+}

package/docs/examples/README.md

@@ -1,20 +1,35 @@
-# Examples hub
+# Examples
 
-Every page is a whole service in the 0.2.0 grammar: its manifests compile with
-`mantle generate` (the SDK repository compiles each one in its checks). Copy the shape you need into
-your project's `manifests/`; none is a template to copy wholesale.
+Start from the **app shell**, then copy the example closest to your app on top of it. Each example shows a few
+capabilities the others do not; combine them for anything else.
 
-| Example | What it shows | Handler code |
-|---|---|---|
-| [`reference-service/`](./reference-service/README.md) | A runnable service with its smoke test: scoped orders, SQL Views and Procedures, hooks, a cron, REST, both MCP surfaces, Admin's API and console email-OTP sign-in. The release gate runs it. | yes |
-| [Intake form](./intake.md) | An anonymous form: one SQL `INSERT` and a staff View. | none |
-| [Intake with bot check and notification](./intake-hooks.md) | A Turnstile check as the Procedure's guard, an email from an after hook. | 2 handlers |
-| [Reservation requests](./reservation.md) | A request queue with a Schema `check`. | none |
-| [Publication](./publication.md) | Localized posts with a parent identity, per-locale lists and `mantle.search`. | none |
-| [Legal documents and consent](./legal-documents.md) | Immutable revisions, and an acceptance written only for a published revision. | none |
-| [Procurement approvals](./procurement.md) | Members see their own rows through `auth.uid()`; staff review with an optimistic lock. | none |
-| [Commerce catalog and orders](./commerce.md) | A published catalog, guest orders and a locked staff review. | none |
-| [Commerce inventory](./commerce-inventory.md) | Server-side pricing, atomic stock reservation with `checks` and locks, a scheduled expiry and a verified payment callback. | 3 handlers |
-| [Guarded API access](./guarded-api.md) | API keys through a custom `CallerResolver`, scopes and a live entitlement guard. | 2 handlers |
+| Example | Shows |
+|---|---|
+| [App shell](./app-shell/README.md) | Better Auth (email OTP, `admin` + `user`), one Worker fetch, Admin, MCP, REST, local acceptance kit. No business manifests. |
+| [Recipes](./recipes/README.md) | Publishing (draft → publish), translations, visitor pages with SEO, JSON-LD, `llms.txt`, Markdown and hreflang alternates, R2 media. |
+| [Club events](./club-events/README.md) | Members who see and change only their own rows, no duplicates, capacity that never oversells, a handler that checks before writing, a member MCP tool, members-only sign-up. |
+| [Purchasing](./purchasing/README.md) | An internal workflow: guarded status transitions, admin-only approval (Admin and admin MCP), optimistic concurrency, several writes in one transaction, an external API with a signed callback, email and cron. |
+| [Generated website](./generated-web/README.md) | The smallest public site: list and detail pages, REST, `llms.txt`, sitemap, Markdown alternates. |
 
+## Combining
+
+| You need | Take |
+|---|---|
+| Stock that never oversells (orders, tickets, bookings) | club-events' capacity: a Schema `checks` constraint plus the decrement in the same program |
+| Employees or customers who see only their own records | club-events' `restrict: { <schema>: "author_id = auth.uid()" }` |
+| An approval step, or any state machine | purchasing's guarded `UPDATE ... WHERE requestStatus = ...` Procedures |
+| A third-party API that answers later (webhooks, callbacks) | purchasing's `src/routes.ts`: verify the raw request, then call a Procedure |
+| Public, multilingual, search- and AI-friendly pages | recipes' `src/routes.ts` |
+| Invite-only or members-only sign-up | club-events' `members` allowlist + `src/signup.ts` |
+| Notifications and reminders | purchasing's `EmailSender` call and `src/schedule.ts` |
+
+When you copy an example only for one of its patterns, delete what your app does not need. Copying club-events, for
+example, also brings its `members` allowlist and `src/signup.ts` (members-only sign-up); remove both, or restore the
+shell's allow-all `src/signup.ts`, unless sign-up should be invite-only. Purchasing brings its supplier callback
+(`src/routes.ts`, `src/supplier.ts`), email (`src/notify.ts`), cron (`src/schedule.ts` and `triggers.crons`) and its
+`wrangler.jsonc` secrets. `pnpm generate` and `tsc` point at leftovers that reference removed Schemas.
+
+Every example uses two roles: `admin` (the admin layer) and `user`.
+
+[Reference service](./reference-service/README.md) is the release smoke test for packed packages, not a starting point.
 Projects on 0.1.x move with [the upgrade guide](../upgrade-0.1-to-0.2.md).

package/docs/examples/app-shell/README.md

@@ -0,0 +1,48 @@
+# App shell
+
+The wiring every Mantle Cloudflare app needs, ready to copy: Better Auth (email OTP, admin + user roles),
+one Worker fetch (auth routes → your routes → Admin → MCP → generated REST), the Admin console assets, and a
+local acceptance kit. It has no business manifests: add your own, or copy one of the examples on top of it.
+
+## Start an app
+
+```sh
+cp -R node_modules/@aotter/mantle/docs/examples/app-shell/. my-app/   # or from this repository
+cp -R node_modules/@aotter/mantle/docs/examples/club-events/. my-app/ # optional: an example on top
+cd my-app
+# package.json: pin the exact installed Mantle version for @aotter/mantle, -admin and -ui
+pnpm install
+pnpm generate          # writes generated/ and lists any `handler: { ref }` to implement in src/handlers.ts
+pnpm types && pnpm check
+cp .dev.vars.example .dev.vars
+pnpm db:init && pnpm db:seed   # db:seed only when the example has seed.sql
+pnpm dev                       # one-time codes print to this log
+pnpm smoke                     # when the copied example has smoke.mjs
+```
+
+## Files you edit
+
+| File | What it is for |
+|---|---|
+| `manifests/*.yaml` | Your Schemas, Views, Procedures and Triggers. `pnpm generate` compiles every file here. |
+| `src/handlers.ts` | Code for each `handler: { ref }` Procedure. The Store it receives is bound to the same caller. |
+| `src/routes.ts` | App-owned routes: visitor pages, SEO files, webhooks and callbacks. |
+| `src/admin.ts` | Admin presentation for `--admin-extensions`: `navGroups` (sidebar groups) and `adminExtensions`. Empty by default. |
+| `src/sign-in.ts` | Member sign-in page at `/sign-in` (email code, then back to `?return=`) and `signInRedirect(request)` for pages that need a signed-in visitor. Unstyled; delete it if the app has no member pages. |
+| `src/schedule.ts` | Cron work. Add the cron to `wrangler.jsonc` `triggers.crons`. |
+| `src/signup.ts` | `allowSignUp(env, email)`: who may create an account (allow-all by default). `auth.ts` calls it before Better Auth creates a user; `ADMIN_EMAIL` is always allowed. |
+| `src/auth.ts` | Better Auth options. Two roles only: `admin` (the admin layer) and `user`. Replace the console OTP sender before deploying. |
+| `smoke.mjs` | Your acceptance steps on `smoke-kit.mjs` (fresh local D1, OTP sign-in per user, REST/MCP/Admin calls). |
+
+`src/service.ts` and `src/index.ts` rarely change. Delete the blocks marked `MCP / OAuth (optional)` in `auth.ts`
+and `service.ts` if the app has no MCP.
+
+Search for `AGENT:` to find what an app must fill in.
+
+## Local testing notes
+
+- Better Auth allows 3 OTP requests per minute per client IP. `smoke-kit.mjs` gives each user its own
+  `cf-connecting-ip`; when testing by hand, wait a minute or vary that header.
+- `ADMIN_EMAIL`'s first verified sign-in becomes `admin` while no admin exists. The sign-in response may still show
+  the previous role; `/admin/api/me` shows the current one.
+- Admin HTTP routes are listed in `docs/handbook/guides/native-admin.md`.

package/docs/examples/app-shell/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "mantle-app",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "generate": "mantle generate cloudflare-d1 generated manifests/*.yaml --auth src/auth.ts --entry src/index.ts --admin --admin-extensions src/admin.ts",
+    "types": "wrangler types --include-runtime=false",
+    "db:init": "wrangler d1 execute mantle-app --local --file generated/schema.sql",
+    "db:seed": "wrangler d1 execute mantle-app --local --file seed.sql",
+    "dev": "wrangler dev --local --ip 127.0.0.1 --port 8787",
+    "check": "mantle generate cloudflare-d1 generated manifests/*.yaml --auth src/auth.ts --entry src/index.ts --admin --admin-extensions src/admin.ts --check && wrangler types --include-runtime=false --check && tsc --noEmit",
+    "smoke": "node smoke.mjs"
+  },
+  "dependencies": {
+    "@aotter/mantle": "0.2.0-alpha.7",
+    "@aotter/mantle-ui": "0.2.0-alpha.7",
+    "@better-auth/cimd": "1.7.7",
+    "@better-auth/mcp": "1.7.7",
+    "@better-auth/oauth-provider": "1.7.7",
+    "@modelcontextprotocol/ext-apps": "2.0.0",
+    "@modelcontextprotocol/server": "2.1.0",
+    "better-auth": "1.7.7",
+    "@aotter/mantle-admin": "0.2.0-alpha.7"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "5.20260904.1",
+    "@types/node": "^26",
+    "typescript": "^6.0.3",
+    "wrangler": "4.129.0"
+  },
+  "engines": {
+    "node": ">=22.22"
+  }
+}