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

package/dist/usecase/mcp.js

@@ -1,4 +1,3 @@
-/** Emit the selected MCP boundary; the official transport loads on its first request. */
 import { mcpToolNameSegment, procedureAnnotations, toolTitle, viewAnnotations } from "../build/compiler.js";
 import { emitMcpMedia, mediaDefinitions } from "./mcp-media.js";
 import { advertised, emitValidation } from "./validation.js";
@@ -37,7 +36,6 @@ export function emitMcp(plan, lowered, target, description, refuse, media = fals
             const module = `./${outputConversions(plan, name, target).some(([, type]) => type === "int") ? "paged/wire/views" : "paged/views"}/${file}.js`;
             imports.push(`const run${index}: typeof import(${q(module)}).default = async (...args) => (await import(${q(module)})).default(...args);`);
         }
-        // The kernel adds a View tool's `limit` and `cursor` paging properties.
         const { inputSchema, description: about } = advertised(kind === "views" ? operation.input ?? { type: "object", additionalProperties: false } : operation.input, operation.description ?? operation.title ?? name), schema = literal(inputSchema);
         if (kind === "views" && ("limit" in (operation.input?.properties ?? {}) || "cursor" in (operation.input?.properties ?? {})))
             refuse(`views/${name}`, "MCP View input reserves limit and cursor for paging.");
@@ -49,7 +47,6 @@ export function emitMcp(plan, lowered, target, description, refuse, media = fals
         const output = kind === "procedures" ? ref ? (procedure?.output.type === "object" ? procedure.output : undefined) : { type: "object", properties: { results: { type: "array", items: { type: "array", items: { type: "object" } } } }, required: ["results"] } : undefined;
         const annotations = kind === "views" ? viewAnnotations : procedure ? procedureAnnotations(procedure) : operation.mcp;
         const wire = kind === "views" ? outputConversions(plan, name, target) : [];
-        // Hashed as listed: the kernel adds a View tool's paging properties exactly so.
         const listed = versioned({ name: tool, title: operation.title ?? toolTitle(name), description: about, inputSchema: kind === "views" ? { ...inputSchema, properties: { ...inputSchema?.properties, limit: { type: "integer", minimum: 1, maximum: 500 }, cursor: { type: "string" } } } : inputSchema, outputSchema: output, annotations });
         hasWire ||= wire.length > 0;
         const fields = [...(description.targets.find(t => t._meta.id === `${kind === "views" ? "view" : "procedure"}:${name}`)?._meta.readOnly ? ["readOnly: true"] : []), `target: ${q({ kind: kind === "views" ? "view" : "procedure", name })}${guard(operation.requires, `${kind}/${name}`, binds, procedure?.trustedOnly)}`, `name: ${q(tool)}`, `surface: ${q(surface)}`, `title: ${q(listed.title)}`, `description: ${q(listed.description)}`, "inputSchema", ...(output ? [`outputSchema: ${literal(output)}`] : []), ...(annotations ? [`annotations: ${q(annotations)}`] : []), ...((operation.requires?.auth?.all.length ?? 0) > 0 ? ["closed: true"] : []), ...(scopes.length ? [`scopes: ${q(scopes)}`] : []), `validate: ${kind === "views" ? `validate${index}` : `async (raw) => (await import("./validation/procedures/${file}.js")).validate(raw)`}`, ...(convert ? [`convert: ${convert}`] : []),
@@ -77,7 +74,6 @@ export function emitMcp(plan, lowered, target, description, refuse, media = fals
             }
     if (hasWire)
         imports.push('import { wireRows } from "@aotter/mantle/contracts";');
-    // An input schema several tools share is one constant.
     const uses = new Map(), shared = new Map();
     for (const { schema } of tools)
         uses.set(schema, (uses.get(schema) ?? 0) + 1);

package/dist/usecase/paging.js

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

package/dist/usecase/publishing.js

@@ -1,4 +1,3 @@
-/** Opt-in lifecycle: one atomic, version-guarded statement per transition, with Core's row rules. */
 import { rowPolicy } from "../build/compiler.js";
 import { dialect as sqlite } from "../kernel/dialect/sqlite.js";
 import { dialect as postgres } from "../kernel/dialect/postgres.js";
@@ -7,7 +6,9 @@ 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) {
+export const publishRequired = (s) => (s.schema.required ?? []).flatMap(field => Object.keys(s.fields).filter(c => (s.names?.[c] ?? c) === field).slice(0, 1)
+    .flatMap(c => s.fields[c] === "geo" ? [[`${c}_lat`, field], [`${c}_lng`, field]] : [[c, field]]));
+export function emitPublishing(plan, isSqlite, declarations, procedures, entries, values, refuse, locks = {}) {
     const d = isSqlite ? sqlite : postgres;
     const translations = Object.values(plan.schemas).some(s => s.translates);
     if (translations)
@@ -32,21 +33,30 @@ export function emitPublishing(plan, isSqlite, declarations, procedures, entries
                 const schema = plan.schemas[s.name];
                 const recipes = [{ k: "now" }, { k: "input", name: "id" }, { k: "input", name: "expectedVersion" }];
                 const conditions = [`id = ${d.param(2)}`, `version = ${d.param(3)}`, `status IN (${from.map(v => `'${v}'`).join(", ")})`];
-                // Same visibility as Store and Admin writes, translation parent included (a child under an out-of-set parent is missing);
-                // the status term is replaced by the transition's own `status IN (...)`.
                 for (const term of rowPolicy(schema, trusted ? "trusted" : "caller", plan.schemas))
                     if (term[1] !== "admin")
                         conditions.push(renderTerm(d, term, term[1] === "parent" ? d.ident(s.name) + "." : "", recipe => (recipes.push(recipe), d.param(recipes.length))));
                 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`);
-                    }
+                    for (const [column] of publishRequired(s))
+                        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 };
+                const held = trusted ? [] : (locks[s.name.toLowerCase()] ?? []).filter(l => l.on.includes("update"));
+                const lock = held.length ? (() => {
+                    const probe = [], number = new Map(), renumber = (sql) => sql.replace(isSqlite ? /\?(\d+)/g : /\$(\d+)/g, (_, n) => {
+                        const i = Number(n);
+                        if (!number.has(i)) {
+                            probe.push(recipes[i - 1]);
+                            number.set(i, d.param(probe.length));
+                        }
+                        return number.get(i);
+                    });
+                    const where = renumber(conditions.filter(c => c !== `version = ${d.param(3)}`).join(" AND "));
+                    return { sql: `SELECT CASE ${held.map(l => `WHEN (${l.sql}) IS NOT FALSE THEN '${l.name}'`).join(" ")} END AS ${d.ident("lock")} FROM ${d.ident(s.name)} WHERE ${where}`, binds: probe, schema: s.name, verb: "update", locks: Object.fromEntries(held.map(l => [l.name, l.message])) };
+                })() : undefined;
+                conditions.push(...held.map(l => `NOT (${l.sql})`));
+                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, ...(lock ? { lock } : {}) };
             };
             values.add("now");
             const caller = q([statement(false)]), trusted = q([statement(true)]);
@@ -56,7 +66,6 @@ export function emitPublishing(plan, isSqlite, declarations, procedures, entries
         }
     }
 }
-/** Publishing lists get one index, prefixed by scope when present. */
 export function publishingSql(schemas, isSqlite) {
     const d = isSqlite ? sqlite : postgres;
     return Object.values(schemas).filter(s => s.publishing).map(s => `CREATE INDEX ${d.ident(`_mantle_ix_${s.name}_published`)} ON ${d.ident(s.name)} (${[...(s.scope ? [s.scope] : []), ...(s.userScopes ?? []).map(u => u.column), "published_at", "id"].map(d.ident).join(", ")})`);

package/dist/usecase/rest.js

@@ -1,6 +1,7 @@
 import { databaseImport, q, viewImports } from "../domain/entry.js";
 import { authLines, conversions } from "../domain/input.js";
 import { boundaryPage, outputConversions } from "../domain/columns.js";
+import { pathTemplate as template, routeOrder, routeSource } from "../kernel/route-pattern.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);
@@ -14,11 +15,9 @@ export function emitRest(plan, lowered, target, description) {
     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)}` : ""}`;
+        const { source, keys } = routeSource(path);
+        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")
@@ -29,7 +28,7 @@ export function emitRest(plan, lowered, target, description) {
         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);
+    const triggers = Object.values(plan.triggers).filter(t => t.source.kind === "http").sort((a, b) => a.source.kind === "http" && b.source.kind === "http" ? routeOrder(a.source.path, b.source.path) : 0);
     for (const trigger of triggers) {
         if (trigger.source.kind !== "http")
             continue;
@@ -41,7 +40,7 @@ export function emitRest(plan, lowered, target, description) {
             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}`} }`);
+        procedures.push(`{ ${route(method, path)}, id: ${q(`rest:${method} ${template(path)}`)}, 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";');

package/dist/usecase/site.js

@@ -1,4 +1,3 @@
-/** 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) {

package/dist/usecase/stores.js

@@ -1,25 +1,16 @@
-/**
- * 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.
+import { refChecks, userScopeTerm } from '../build/compiler.js';
+import { publishRequired } from "./publishing.js";
 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) {
+export function emitStores(schemas, isSqlite, newId, refuse, required = false, locks = {}) {
     const all = Object.values(schemas).sort((a, b) => a.name < b.name ? -1 : 1);
     if (!all.length && !required)
         return undefined;
@@ -28,7 +19,7 @@ export function emitStores(schemas, isSqlite, newId, refuse, required = false) {
     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 geo = Object.keys(s.fields).filter(f => s.fields[f] === "geo").flatMap(f => [`${f}_lat`, `${f}_lng`]);
         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);
@@ -36,18 +27,22 @@ export function emitStores(schemas, isSqlite, newId, refuse, required = false) {
         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 } : {}),
+            ...(s.scope ? { s: s.scope } : {}), ...(s.ttl ? { ttl: [s.ttl, s.ttlSeconds ?? 0] } : {}), ...(s.publishing ? { pub: 1, ...(publishRequired(s).length ? { req: Object.fromEntries(publishRequired(s)) } : {}) } : {}),
             ...(ts.length ? { ts } : {}), ...(dates.length ? { d: dates } : {}),
             ...(s.search?.length ? { search: s.search } : {}),
+            ...(ref.length ? { ref } : {}),
+            ...(locks[s.name.toLowerCase()]?.length ? { lock: locks[s.name.toLowerCase()] } : {}),
             ...(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]);
+        for (const verb of ["update", "delete"])
+            if (q(writePolicy(s, verb).locks.map(l => l[0])) !== q((fact.lock ?? []).filter(l => l.on.includes(verb)).map(l => l.name)))
+                refuse(`schemas/${s.name}`, `Core's ${verb} locks for this Schema differ from the Store's.`);
         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(" ")} }`;
@@ -55,7 +50,7 @@ export function emitStores(schemas, isSqlite, newId, refuse, required = false) {
         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"))])} }`);
+        tables.push(`${key(s.name)}: { row: ${of([...names, ...geo], c => c === "id" ? "string" : c === "version" ? "number" : 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

@@ -1,8 +1,5 @@
-/** 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

@@ -1,12 +1,10 @@
 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)}`];

package/dist/usecase/validation.js

@@ -1,4 +1,3 @@
-/** Compile boundary checks into each operation; no schema enters the request bundle. */
 import { INPUT_RULE_KEYWORDS, lookupLocalRef as lookup, rootRefChain } from "../build/compiler.js";
 import { literal, q } from "../domain/entry.js";
 import { publishingInput } from "./publishing.js";
@@ -6,14 +5,9 @@ import { equal } from "../kernel/validation.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 const 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(" "), ...INPUT_RULE_KEYWORDS]);
 const shapes = "see docs/handbook/reference/surface.md";
-// YAML .inf and .nan parse to numbers that JSON writes as null.
 const finite = (value) => typeof value === "number" ? Number.isFinite(value) : !!value && typeof value === "object" ? Object.values(value).every(finite) : true;
 const has = (key) => `Object.hasOwn(object,${q(key)})`;
 const exactly = (value, keys) => !!value && typeof value === "object" && !Array.isArray(value) && Object.keys(value).sort().join(" ") === keys;
-/**
- * An object schema's rules, each failing `when` (JavaScript on `object`) with its sentence at the missing field `key`, or the
- * reason a rule has an unsupported shape.
- */
 function rules(schema) {
     const declared = (names) => Array.isArray(names) && names.length > 0 && names.every(name => typeof name === "string" && Object.hasOwn(schema.properties ?? {}, name));
     const list = (names) => names.map(name => `'${name}'`).join(" and ");
@@ -34,7 +28,6 @@ function rules(schema) {
     if (condition !== undefined || then !== undefined || otherwise !== undefined) {
         const [key] = exactly(condition, "properties required") ? Object.keys(condition.properties) : [];
         const value = key === undefined ? undefined : condition.properties[key];
-        // Without required: [key], an absent key satisfies `if`.
         if (key === undefined || !exactly(condition.properties, key) || !exactly(value, "const") || !(["string", "boolean"].includes(typeof value.const) || Number.isFinite(value.const) || value.const === null) || q(condition.required) !== q([key]) || !declared([key]))
             return `if is supported only as exactly { properties: { <field>: { const: <string, finite number, boolean or null> } }, required: [<field>] }, so an absent field does not satisfy it; ${shapes}.`;
         if (then === undefined && otherwise === undefined || [then, otherwise].some(branch => branch !== undefined && !(exactly(branch, "required") && declared(branch.required))))
@@ -47,19 +40,12 @@ function rules(schema) {
     }
     return found;
 }
-/** Whether an input schema accepts `{}`: a list View is read with no input, so web indexes need this. */
 export function acceptsEmpty(input) {
     if (input === undefined)
         return true;
-    // Validation applies a root `$ref`'s target too, so each schema along the chain must accept `{}`; an unresolved or cyclic chain does not.
-    // dependentRequired needs a present key; an if needs its field, so `{}` meets only an else. An enum or const must admit `{}`.
     return rootRefChain(input)?.every(schema => !schema.required?.length && schema.anyOf === undefined && !schema.else?.required?.length
         && (schema.enum === undefined || schema.enum.some(option => equal({}, option))) && (schema.const === undefined || equal({}, schema.const)) && (schema.type === undefined || [schema.type].flat().includes("object"))) ?? false;
 }
-/**
- * An input schema as an AI tool catalogue advertises it: some model APIs refuse rules (a root `anyOf`, `if`), so each rule leaves
- * the schema and becomes a sentence of the description.
- */
 export function advertised(input, description) {
     if (!input)
         return { inputSchema: input, description };
@@ -68,7 +54,6 @@ export function advertised(input, description) {
         if (!node || typeof node !== "object")
             return;
         const schema = node;
-        // An MCP View tool keeps each rule set of its root `$ref` chain as an `allOf` branch over the merged properties.
         const branches = Array.isArray(schema.allOf) ? schema.allOf : [];
         for (const branch of [schema, ...branches.map(branch => ({ ...branch, properties: schema.properties }))]) {
             const found = rules(branch);
@@ -111,9 +96,7 @@ export function emitValidation(plan, refuse = (path, message) => { throw Error(`
                 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(), patterns = new Map();
             let equality = false;
             const resolve = (ref) => {
@@ -142,7 +125,6 @@ export function emitValidation(plan, refuse = (path, message) => { throw Error(`
                         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) {
@@ -197,7 +179,6 @@ export function emitValidation(plan, refuse = (path, message) => { throw Error(`
                 }
                 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.");`);
@@ -217,7 +198,6 @@ export function emitValidation(plan, refuse = (path, message) => { throw Error(`
                 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);

package/docs/examples/README.md

@@ -1,7 +1,8 @@
 # Examples
 
-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.
+Start an app with `mantle init`, which writes the **app shell** once. The examples are references: each shows a few
+capabilities the others do not. Find each need in **Combining** below, read that example's manifest and source, and
+take the pattern into your own manifests and `src/`. Do not copy an example directory over your app.
 
 | Example | Shows |
 |---|---|
@@ -16,20 +17,27 @@ capabilities the others do not; combine them for anything else.
 | You need | Take |
 |---|---|
 | Stock that never oversells (orders, tickets, bookings) | club-events' capacity: a Schema `checks` constraint plus the decrement in the same program |
+| An order, cart or import with several rows that must all commit or none | one SQL Procedure over `json_each(input.items)` with a counted check that refuses unknown lines (`mantle help typed-queries`, "Several rows that commit together") |
 | 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 |
+| Approve first, then reserve or spend | purchasing's `approve-request-write`: the guarded status change and the budget deduction in one program (`mantle help sql-patterns`, "Approve before reserving") |
+| A status chosen while writing (auto-approve small requests) | purchasing's `submit-request`: `CASE` in the INSERT ("Choose a status while writing: CASE") |
+| Edit only the fields given | `COALESCE(input.field, field)` ("Change only the fields given") |
+| Create or add (restock, counters) | `INSERT ... ON CONFLICT (...) DO UPDATE` ("Create or add") |
+| Refuse while something still refers to it | a `NOT EXISTS` guard in the UPDATE (purchasing's `submit-request` ledger row; "Refuse while something refers to it") |
+| A record with its children in one read | club-events' `event-roster`: a JSON array per row ("A row with its children in one read") |
+| The latest row per group, rankings | `row_number() OVER (PARTITION BY ...)` ("The latest row of each group") |
 | 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
+If you do copy an example's files, 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](https://github.com/aotter/mantle/tree/v0.2.0-alpha.9/docs/examples/reference-service) is the release smoke test for packed packages, not a starting point. Its source lives in the tagged repository; it is not included in the npm docs.
+[Reference service](https://github.com/aotter/mantle/tree/v0.2.1-alpha.1/docs/examples/reference-service) is the release smoke test for packed packages, not a starting point. Its source lives in the tagged repository; it is not included in the npm docs.
 Projects on 0.1.x move with [the upgrade guide](../upgrade-0.1-to-0.2.md).

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

@@ -2,24 +2,59 @@
 
 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.
+local acceptance kit. It has no business manifests: add your own, taking patterns from the examples (`mantle help examples`).
 
 ## 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
+npx @aotter/mantle@<exact version> init my-app   # writes this shell once, Mantle packages pinned to that version
 cd my-app
-# package.json: pin the exact installed Mantle version for @aotter/mantle, -admin and -ui
 pnpm install
+# add manifests/*.yaml (mantle help four-atoms; patterns: mantle help examples)
 pnpm generate          # writes generated/ and lists any `handler: { ref }` to implement in src/handlers.ts
-pnpm types && pnpm check
+pnpm types && pnpm check       # each builds once (see Which steps build)
 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
+pnpm db:init                   # optional seed.sql for static reference data, then pnpm db:seed (see Seed data)
+pnpm dev                       # builds, rebuilds on change; one-time codes print to this log
+pnpm smoke                     # builds; your smoke.mjs on smoke-kit.mjs (see Files you edit)
+pnpm accept                    # builds; hands each role to a fresh evaluator (see Independent acceptance)
+pnpm test                      # Admin MCP App check of the last build: needs Chrome (npx playwright-core install chromium, or MANTLE_TEST_CHROMIUM=<executable>)
 ```
 
+### Which steps build
+
+`wrangler.jsonc` sets `mantle bundle src/index.ts dist` as Wrangler's custom build. These steps run it (marked
+**builds**); the others do not:
+
+| Step | Builds? |
+|---|---|
+| `pnpm generate`, `pnpm db:init`, `pnpm db:seed` | no |
+| `pnpm test` | no; it tests the last build |
+| `pnpm types` (`wrangler types`) | **builds**: Wrangler reads the built entry's exports for Durable Object and service binding types |
+| `pnpm check` | **builds** once, in `wrangler types --check`; `generate --check` and `tsc` do not |
+| `pnpm build` | **builds** |
+| `pnpm dev` | **builds** at start, then again on every change under `src/` or `generated/` |
+| `pnpm smoke`, `pnpm accept` | **build** once each: both start `wrangler dev` |
+
+Wrangler has no option to skip the custom build for `wrangler types`. The Admin console is rebuilt only when the
+installed Admin packages change or the app has `src/admin.tsx`, so a repeated build mostly rebuilds the Worker.
+
+First run, after `pnpm install` and your manifests: `pnpm generate`, `pnpm types`, `pnpm check`,
+`cp .dev.vars.example .dev.vars` (`pnpm dev` needs the secrets `wrangler.jsonc` requires), `pnpm db:init`, then
+`pnpm dev` or `pnpm smoke`. Right after `pnpm types`, `pnpm check` repeats its build; run it anyway, because it is the
+same check CI and hand-off use.
+
+Routine edit, with `pnpm dev` running:
+
+1. Edit `manifests/*.yaml`, then `pnpm generate`. Wrangler does not watch `manifests/`, so the last build keeps
+   serving until something under `src/` or `generated/` changes. From the next change under `src/` until you
+   generate, each change prints one line, `Generated output in generated is stale (...)`, and the dev server holds
+   requests instead of running stale code. Writing `generated/` rebuilds. If you undo the manifest edit instead,
+   nothing rebuilds until the next change under `src/` or a restart of `pnpm dev`.
+2. `pnpm types` only when `generate` or you changed `wrangler.jsonc` (bindings, secrets, vars).
+3. Edits under `src/` rebuild by themselves.
+4. Before handing off: `pnpm check`, then `pnpm smoke`.
+
 npm works too (`npm install`, `npm run …`). `package.json` pins `@better-auth/core` and `@better-auth/utils` even though
 the shell does not import them: they are the exact versions the SDK's Better Auth peers require, and without them a fresh
 install resolves newer ones (npm ERESOLVE, or a second Better Auth type tree under pnpm). Keep every Better Auth package
@@ -38,6 +73,7 @@ on one version.
 | `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). |
+| `accept.mjs` | Independent acceptance setup: one URL per role that carries its session, plus a minimal MCP client. Add a fixtures module for realistic data. |
 
 `src/service.ts` and `src/index.ts` rarely change. The default shell mounts REST and MCP together. If the app deliberately
 chooses asymmetric exposure, delete the blocks marked `MCP / OAuth (deliberate exception)` in `auth.ts` and `service.ts`;
@@ -45,16 +81,59 @@ HTTP-only Procedures will keep generating with a warning.
 
 Search for `AGENT:` to find what an app must fill in.
 
+## Seed data
+
+Create test records through the app: your `smoke.mjs` or an `accept.mjs` fixtures module calls the app's own REST, MCP
+or Admin operations as a signed-in user, so Mantle fills `id`, `version`, `created_at`, `updated_at`, `author_id`
+and the publishing `status`/`published_at`. Keep `seed.sql` for static reference data no surface writes; native SQL
+must set those columns itself, timestamps as integer microseconds on D1. An omitted `updated_at` stores `0`, which
+Admin shows as 1970. `mantle help local-testing` (Seed data) has a complete seed:
+
+```sql
+INSERT INTO categories (id, version, created_at, updated_at, name) VALUES
+  ('books', 1, 1767225600000000, 1767225600000000, 'Books');
+```
+
 ## 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.
+- More administrators: in Admin, **More → Administrators** invites by email and **More → Members** grants Admin to an
+  existing member. `docs/handbook/cloudflare/authentication.md` (Identity helpers) has the same operations as an API.
 - Admin HTTP routes are listed in `docs/handbook/guides/native-admin.md`.
 
+`mantle help local-testing` lists what the smoke covers: every Procedure at its edges, each caller's isolation,
+visitor pages without JavaScript, MCP discovery and Admin's MCP App.
 Scripted smoke is not independent acceptance; before reporting a user-facing
-deliverable done, follow the [independent acceptance guide](../../handbook/guides/agent-workflow-acceptance.md).
+deliverable done, follow the independent acceptance guide: `mantle help agent-workflow-acceptance`. Hand off with
+its layered report ("Report done-ness in layers"): smoke and `pnpm test` are layer 2, `pnpm accept` rounds layer 3.
+
+### Independent acceptance
+
+`pnpm accept` (optionally `pnpm accept --fixtures fixtures.mjs --user member@example.test`; with npm, `npm run accept -- --fixtures …`) starts the app on a fresh local D1,
+signs the admin in, runs your fixtures module, signs the user in and prints one local URL per role:
+
+```text
+visitor (anonymous): http://127.0.0.1:18741
+admin (owner@example.test): http://127.0.0.1:46467  MCP http://127.0.0.1:46467/mcp/admin  Admin http://127.0.0.1:46467/admin
+user (member@example.test): http://127.0.0.1:42607  MCP http://127.0.0.1:42607/mcp
+```
+
+Each URL forwards to the app with that role's session; the evaluator never sees a cookie, and the URL refuses
+`/api/auth/*`, so it cannot sign out, sign in as someone else or mint credentials. Give an evaluator only its role's URL:
+
+- MCP: configure the URL as a streamable HTTP MCP server, or, without an MCP client,
+  `node accept.mjs mcp <url>/mcp` lists the tools and `node accept.mjs mcp <url>/mcp <tool> '<json>'` calls one.
+- Admin and member pages: open the URL in a browser (a person's, or Playwright for an agent); it is already
+  signed in.
+- REST: send requests to the URL with no credential.
+
+The fixtures module's default export receives `{ call, mcp, signIn, sql, sessions, user }` and runs between the two
+sign-ins, so an invite-only app can admit the user first. Create records through the app's own REST/MCP as real
+users (other members' records, several states, more than one page); `sql` is for what no surface may write, and returns storage column names (lower case unless aliased).
+Ctrl-C stops the app and deletes its data. To accept an external MCP host's OAuth connection instead, see the guide.
 
 ### MCP acceptance
 
@@ -84,7 +163,7 @@ and compares exact names without calling business tools. JSON/SSE protocol failu
 unexpected/missing tools and repeated/excessive pagination fail; it never obtains credentials or mounts routes.
 
 This local cookie test does not prove OAuth Bearer or an external client's connection. Test those separately
-with supplied credentials and record their results. For each declared interface, the existing handoff/README/test
-report must say verified (command, identity and result), intentionally not exposed, or deferred/unverified with a
-reason. WebMCP-only applications remain valid; an interrupted preview must retain the remote acceptance item
+with supplied credentials and record their results as layer 4 of the layered report. For each declared interface,
+the existing handoff/README/test report must say verified (command, identity and result), intentionally not exposed,
+or deferred/unverified with a reason. WebMCP-only applications remain valid; an interrupted preview must retain the remote acceptance item
 as deferred rather than silently claiming completion.