@aotter/mantle 0.2.0 → 0.2.1-alpha.2

package/dist/usecase/adminClient.js

@@ -13,6 +13,7 @@ test("the Admin MCP App works in an MCP host", { timeout: 300_000 }, async () =>
   await checkMcpApp({ catalogue: mcpAppCatalogues.admin, html });
 });
 `;
+const nullable = (p) => p.nullable === true || [p.type].flat().includes("null") || (p.enum ?? []).includes(null);
 const closed = (typeOf, schema) => !schema ? "{}" : schema.properties || schema.type === "object" && !schema["$ref"] ? typeOf({ ...schema, additionalProperties: false }) : "{ readonly [key: string]: unknown }";
 export function emitAdminClient(plan, typeOf) {
     const tools = mcpTools(plan, "admin"), hasTool = (kind, source) => tools.some(t => t.kind === kind && t.source === source);
@@ -20,7 +21,9 @@ export function emitAdminClient(plan, typeOf) {
     const operations = Object.entries(plan.procedures).filter(([name]) => hasTool("procedure", name)).sort(([a], [b]) => a < b ? -1 : 1);
     const schemas = Object.values(plan.schemas).sort((a, b) => a.name < b.name ? -1 : 1);
     const dataOf = (s) => {
-        const scope = s.scope ? s.names[s.scope] ?? s.scope : undefined, { [scope ?? ""]: _scope, ...properties } = s.schema.properties ?? {};
+        const scope = s.scope ? s.names[s.scope] ?? s.scope : undefined, { [scope ?? ""]: _scope, ...declared } = s.schema.properties ?? {};
+        const certain = (name) => !s.publishing && s.schema.required?.includes(name);
+        const properties = Object.fromEntries(Object.entries(declared).map(([name, p]) => [name, certain(name) || nullable(p) ? p : { ...p, nullable: true }]));
         const required = s.publishing ? [] : s.schema.required?.filter(f => f !== scope);
         const schema = { ...s.schema, properties, ...(required ? { required } : {}) };
         return s.translates ? typeOf(schema) : closed(typeOf, schema);

package/dist/usecase/generate.js

@@ -77,14 +77,16 @@ export function generate(input) {
     };
     const values = new Set();
     const step = (s, path, fields, row = false) => {
-        const recipes = recipesOf(s, fields, message => refuse(path, message));
-        for (const r of recipes) {
+        const recipes = recipesOf(s, fields, message => refuse(path, message)), probe = row && s.probe ? recipesOf(s.probe, fields, message => refuse(path, message)) : [];
+        for (const r of [...recipes, ...probe]) {
             if (r.k === "now" || r.k === "cutoff")
                 values.add(r.k);
             else if (r.k === "input" && r.type)
                 values.add(r.type === "date" ? "date" : "timestamp");
         }
-        return `{ sql: ${q(s.sql)}, binds: ${q(recipes)}${row ? ", row: true" : ""} }`;
+        const locks = Object.fromEntries((plan.schemas[s.schema ?? ""]?.locks ?? []).filter(l => l.on.includes(s.verb)).map(l => [l.name, l.message]));
+        const lock = row && s.probe ? `, lock: ${q({ sql: s.probe.sql, binds: probe, schema: plan.schemas[s.schema].name, verb: s.verb, locks })}` : "";
+        return `{ sql: ${q(s.sql)}, binds: ${q(recipes)}${row ? ", row: true" : s.onNoRows ? ', row: "some"' : ""}${lock} }`;
     };
     const declarations = [], views = [], procedures = [], refProcedures = [];
     const entries = {};
@@ -137,8 +139,8 @@ export function generate(input) {
         entries[`procedures/${encodeURIComponent(name)}.ts`] = entry("procedure", name, `Procedure${index}Input as Input`, `export type { Output } from "${base}contracts";\n`);
     }
     emitTtl(plan, isSqlite, declarations, procedures, entries, refuse);
-    emitPublishing(plan, isSqlite, declarations, procedures, entries, values, refuse);
-    const stores = emitStores(plan.schemas, isSqlite, newId, refuse, hasHandlers);
+    emitPublishing(plan, isSqlite, declarations, procedures, entries, values, refuse, input.locks);
+    const stores = emitStores(plan.schemas, isSqlite, newId, refuse, hasHandlers, input.locks);
     const surfaces = { ...emitPaging(plan, lowered, target, refuse, paging), ...emitPaging(plan, input.wireLowered ?? lowered, target, refuse, paging, true), ...emitValidation(plan, refuse), ...emitRest(plan, lowered, target, input.description), ...emitWeb(plan, lowered, target), ...emitMcp(plan, lowered, target, input.description, refuse, !!site), ...emitAdminDescriptors({ plan, admin }, diagnostics), ...emitAdminBindings(input, refuse), ...(admin ? emitAdminClient(plan, typeOf) : {}), ...emitSite(target, site, refuse, Object.keys(plan.schemas)), ...emitTranslations(plan, target) };
     if (diagnostics.length)
         return { ok: false, diagnostics };

package/dist/usecase/handlers.js

@@ -6,7 +6,7 @@ export function emitHandlers(plan, interactive, typeOf, declarations, procedures
         declarations.push("export interface Handlers {}");
         return [];
     }
-    declarations.push('export type HandlerStore = Pick<ReturnType<typeof makeStore>, "collection" | "views" | "procedures">;', 
+    declarations.push('export type HandlerStore = Pick<ReturnType<typeof makeStore>, "collection" | "batch" | "views" | "procedures">;', 
     `export interface HandlerContext { readonly caller: Caller; readonly db: Database; readonly store: HandlerStore;${interactive ? " readonly transaction: <R>(fn: (ctx: { readonly store: HandlerStore; readonly db: Database }) => Promise<R>) => Promise<R>;" : ""} }`, "export interface Handlers {", ...refs.map(({ name, index }) => `  readonly [${q(name)}]: (ctx: HandlerContext, input: Procedure${index}Input) => Promise<Procedure${index}Output>;`), "}");
     for (const { name, procedure, index } of refs) {
         const path = `procedures/${name}`, fn = `procedure${index}`;

package/dist/usecase/publishing.js

@@ -6,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)
@@ -35,15 +37,26 @@ export function emitPublishing(plan, isSqlite, declarations, procedures, entries
                     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)]);

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);
@@ -15,9 +16,8 @@ export function emitRest(plan, lowered, target, description) {
     let hasWire = false;
     const convert = (code) => code ? `, convert: ${code}` : "";
     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")
@@ -28,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;
@@ -40,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/stores.js

@@ -3,13 +3,14 @@ import { declaredType, inputType, nativeType } from "../domain/columns.js";
 import { q } from "../domain/entry.js";
 import { expand, SCOPE, TTL } from "../kernel/store.js";
 import { refChecks, userScopeTerm } from '../build/compiler.js';
+import { publishRequired } from "./publishing.js";
 const SCALAR = new Set(["text", "real", "float8", "integer", "int4", "int8", "bool", "timestamptz", "date"]);
 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 };
-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;
@@ -29,13 +30,17 @@ export function emitStores(schemas, isSqlite, newId, refuse, required = false) {
         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") } } : {}),
         };
         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.`);
         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));
@@ -45,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/docs/examples/README.md

@@ -39,5 +39,5 @@ shell's allow-all `src/signup.ts`, unless sign-up should be invite-only. Purchas
 
 Every example uses two roles: `admin` (the admin layer) and `user`.
 
-[Reference service](https://github.com/aotter/mantle/tree/v0.2.0/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.2/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

@@ -12,15 +12,49 @@ cd my-app
 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                   # add seed.sql and run pnpm db:seed for fixtures
-pnpm dev                       # one-time codes print to this log
-pnpm smoke                     # your smoke.mjs on smoke-kit.mjs (see Files you edit)
-pnpm accept                    # hand each role to a fresh evaluator (see Independent acceptance)
-pnpm test                      # Admin MCP App check: needs Chrome (npx playwright-core install chromium, or MANTLE_TEST_CHROMIUM=<executable>)
+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
@@ -47,6 +81,19 @@ 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
@@ -60,7 +107,8 @@ Search for `AGENT:` to find what an app must fill in.
 `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: `mantle help agent-workflow-acceptance`.
+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
 
@@ -115,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.

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

@@ -15,27 +15,27 @@
     "accept": "node accept.mjs"
   },
   "dependencies": {
-    "@aotter/mantle": "0.2.0",
-    "@aotter/mantle-ui": "0.2.0",
+    "@aotter/mantle": "0.2.1-alpha.2",
+    "@aotter/mantle-ui": "0.2.1-alpha.2",
     "@better-auth/cimd": "1.7.7",
     "@better-auth/core": "1.7.7",
     "@better-auth/mcp": "1.7.7",
     "@better-auth/oauth-provider": "1.7.7",
     "@better-auth/utils": "0.4.2",
     "@modelcontextprotocol/ext-apps": "2.0.0",
-    "@modelcontextprotocol/server": "2.2.0",
+    "@modelcontextprotocol/server": "2.3.1",
     "better-auth": "1.7.7",
-    "@aotter/mantle-admin": "0.2.0",
+    "@aotter/mantle-admin": "0.2.1-alpha.2",
     "react": "19.3.0",
     "react-dom": "19.3.0"
   },
   "devDependencies": {
-    "@cloudflare/workers-types": "5.20260904.1",
+    "@cloudflare/workers-types": "5.20261027.1",
     "@types/node": "^26",
     "@types/react": "^19.3.0",
     "playwright-core": "1.62.1",
     "typescript": "^6.0.3",
-    "wrangler": "4.129.0"
+    "wrangler": "4.153.0"
   },
   "engines": {
     "node": ">=22.22"

package/docs/examples/club-events/manifests/club-events.yaml

@@ -9,6 +9,7 @@ spec:
   # It also refuses an officer lowering capacity below the seats already taken.
   checks: ["seats_taken <= capacity"]
   indexes: [[startsAt, id]]
+  searchableFields: [title]
   uiSchema: { list: { primaryField: title, columns: [startsAt, capacity, seats_taken, closed] } }
   schema:
     type: object
@@ -54,6 +55,7 @@ spec:
   uniqueIndexes: [[email]]
   # Better Auth lowercases emails; the check refuses a mixed-case entry that would never match.
   checks: ["email = lower(email)"]
+  searchableFields: [email, name]
   uiSchema: { list: { primaryField: email, columns: [name] } }
   schema:
     type: object

package/docs/examples/generated-web/seed.sql

@@ -1,6 +1,7 @@
 -- Local fixture only. Production publishing goes through the generated Procedures.
+-- Every system column is set: timestamps are microseconds since the Unix epoch (2026-01-01T00:00:00Z); 0 would show as 1970.
 INSERT INTO posts (id, version, created_at, updated_at, title, body, status, published_at) VALUES
-('home', 1, 0, 0, 'Posts', '# Posts — browse the HTML index for articles.', 'published', 0),
-('hello', 1, 0, 0, 'Hello <world>', '# Hello world', 'published', 0),
-('second', 1, 0, 0, 'Second post', '# Second post', 'published', 0),
-('draft', 1, 0, 0, 'Hidden draft', '# Draft', 'draft', NULL);
+('home', 1, 1767225600000000, 1767225600000000, 'Posts', '# Posts — browse the HTML index for articles.', 'published', 1767225600000000),
+('hello', 1, 1767225600000000, 1767225600000000, 'Hello <world>', '# Hello world', 'published', 1767225600000000),
+('second', 1, 1767225600000000, 1767225600000000, 'Second post', '# Second post', 'published', 1767225600000000),
+('draft', 1, 1767225600000000, 1767225600000000, 'Hidden draft', '# Draft', 'draft', NULL);

package/docs/examples/purchasing/manifests/purchasing.yaml

@@ -9,6 +9,7 @@ spec:
   uniqueIndexes: [[department]]
   # An approval that would overspend fails this check and the whole approval rolls back.
   checks: ["remaining >= 0"]
+  searchableFields: [department]
   uiSchema: { list: { primaryField: department, columns: [remaining] } }
   schema:
     type: object
@@ -25,6 +26,7 @@ spec:
   title: Purchase requests
   lifecycle: operational
   indexes: [[authorId, createdAt, id], [requestStatus, createdAt, id]]
+  searchableFields: [title, department]
   # Sidebar: in the Approvals group (src/admin.tsx), after the queue of requests waiting for a decision.
   uiSchema: { list: { primaryField: title, columns: [department, amount, requestStatus], filterField: requestStatus }, nav: { group: approvals, order: 2 } }
   schema:
@@ -50,6 +52,7 @@ spec:
   indexes: [[createdAt, id]]
   # One row per spending request.
   uniqueIndexes: [[requestId]]
+  searchableFields: [department]
   uiSchema: { list: { primaryField: department, columns: [amount, remainingAfter, requestId] } }
   schema:
     type: object

package/docs/handbook/cloudflare/media-r2.md

@@ -44,8 +44,11 @@ An existing S3 signer (for example an application already using aws4fetch) fits
 this port. This package adds no AWS SDK. The signer must return a SigV4
 query-signed PUT URL and preserve `X-Amz-Expires`; never give its credentials to
 the client. Configure bucket CORS to allow PUT from the application's origins
-and the returned Content-Type header. Serve the `committed/` prefix on the public domain; these keys differ from 0.2's `{purpose}/{group}/{role}` keys. Keep `uploads/` private/unserved on the
-public domain and add a bucket lifecycle rule for abandoned upload keys.
+and the returned Content-Type header. Uploads go to `uploads/<purpose>/<group>/<role>.<ext>` and each commit copies them
+to `committed/<group>/<attempt>/<role>.<ext>`. Serve the `committed/` prefix on the public domain. Keep `uploads/`
+private/unserved on the public domain and add a bucket lifecycle rule for abandoned upload keys. Mantle 0.1.x wrote
+`<purpose>/<group>/<role>.<ext>` keys (`<group>/<role>.<ext>` when the purpose was not a plain slug); an asset reads its keys from the stored `storageKey` and `publicUrl` of each
+variant, so 0.1.x assets keep working while their prefixes stay served.
 
 Commit checks every object's MIME and size, then rechecks the exact GET
 response used for the copy. Public keys cannot be reached by an upload URL. Each commit attempt has a separate
@@ -54,7 +57,7 @@ loser can neither overwrite nor remove the winner's objects. After SQL selects
 the durable asset, the losing attempt removes only its own unselected copies.
 Upload sources remain until the database commit succeeds, so an uncertain DB
 write can be reconciled/retried with the same UUID. Failed object deletion keeps
-the media row; retry the same id. An upload group expires after 15 minutes. Asset `createdAt` is the upload-group creation time (epoch milliseconds), not the later commit time.
+the media row; retry the same id. An upload group expires after 15 minutes. Asset `createdAt` (`media_assets.created_at`) is the upload-group creation time in epoch milliseconds, not the later commit time; entry timestamps on D1 are microseconds ([reserved entry columns](../reference/schema.md#reserved-entry-columns)).
 No R2 upload or deployment is performed by generation.
 
 A positively identified native rollback deletes only that attempt's copied

package/docs/handbook/cloudflare/service-entry.md

@@ -22,6 +22,8 @@ under `secrets.required`, run `pnpm exec wrangler types --include-runtime=false`
 add `worker-configuration.d.ts` to `tsconfig.json` and commit it.
 `@cloudflare/workers-types` still supplies runtime types. Rerun after every binding
 change; `wrangler types --include-runtime=false --check` fails on drift.
+Both run the custom build (`mantle bundle`), because Wrangler reads the built entry's exports
+for Durable Object and service binding types; Wrangler has no option to skip it.
 Once `secrets.required` is set, `wrangler dev` loads only those keys from
 `.dev.vars`/`.env`, so declare every secret the app reads.
 

package/docs/handbook/concepts/lifecycle-and-locales.md

@@ -2,7 +2,27 @@
 
 Schemas default to `operational`: rows are live immediately and edit in place. Opt-in `publishing` adds `status` (draft/published/archived), nullable `published_at` and a scope-aware `(published_at, id)` index.
 
-Generated `<table>.publish`, `.unpublish` and `.archive` Procedures take `{ id, expectedVersion }`, require admin/system and perform one atomic UPDATE. Publish checks required fields, visibility, TTL, source state and OCC. A failed guard is `CONFLICT`. Store cannot write status/published_at directly. Admin permits generic publishing edits only on drafts; Store does not add that separate Admin editing rule.
+Generated `<table>.publish`, `.unpublish` and `.archive` Procedures take `{ id, expectedVersion }`, require admin/system and perform one atomic UPDATE. Publish checks required fields, visibility, TTL, source state and OCC. A failed guard is `CONFLICT`. Store cannot write status/published_at directly. By default Admin's generic patch edits drafts only (published and archived entries are unpublished first), and a published entry is unpublished before it is deleted; both are an implicit lock named `publishing` that Admin shows before the edit, and neither applies to the transitions. A Store update may edit a published row in place but cannot clear a field `publish` requires: setting one to null is `INPUT_VALIDATION_FAILED` for every caller. Fields it leaves alone are not re-checked, so adding a field to `required` later does not block updates of posts published before it.
+
+To let admins correct a published entry in place, opt in with `publishing: { liveEdits: true }`. A personal blog needs nothing more than one Schema:
+
+```yaml
+apiVersion: cms.mantle.aotter.net/v2
+kind: Schema
+metadata: { name: posts }
+spec:
+  title: Posts
+  lifecycle: publishing
+  publishing: { liveEdits: true }
+  schema:
+    type: object
+    required: [title, body]
+    properties:
+      title: { type: string }
+      body: { type: string }
+```
+
+Admin then edits a published post with a "changes go live on save" notice. The save goes live on commit, `published_at` is kept and `updated_at` moves. The merged post must still pass `publish`'s checks, so emptying its title is refused with `INPUT_VALIDATION_FAILED`. An archived post stays draft-only: restore it to edit it. Deleting a published post still requires unpublishing, and [declared locks](../reference/schema.md#locks) still apply. `publishing` is refused on an operational Schema, which already edits in place. To prepare changes to published content without exposing them, split it into a publishing parent and operational revisions instead ([edit published content without downtime](../guides/revisions.md)).
 
 Public Views see published rows only. Other reads expose drafts only to admin/system. This policy applies to joins and nested queries too.
 

package/docs/handbook/examples/hub.md

@@ -2,4 +2,4 @@
 
 Use the [Worker quickstart](../start/quickstart-worker.md) for a complete native manifest and entry, [typed queries](../guides/typed-queries.md) for embedding, and [service composition](../cloudflare/service-entry.md) for optional surfaces.
 
-The runnable [reference service](https://github.com/aotter/mantle/tree/v0.2.0/docs/examples/reference-service) exercises the native package integration. See the [generated public website](../../examples/generated-web/README.md) for a native Worker example.
+The runnable [reference service](https://github.com/aotter/mantle/tree/v0.2.1-alpha.2/docs/examples/reference-service) exercises the native package integration. See the [generated public website](../../examples/generated-web/README.md) for a native Worker example.

package/docs/handbook/guides/admin-ui.md

@@ -6,7 +6,7 @@ Schema `uiSchema` selects fields, widgets, list columns, enum tabs and child nav
 
 Admin Views provide custom read lists; their SELECT outputs, column lineage and `uiSchema.list` define display/search/filter metadata. Procedures and MCP admin Triggers define operations with declared authorization, input checks and optional row targets. A hidden button never authorizes an operation.
 
-Generic publishing edits apply to drafts; publishing transitions retain their atomic guards and OCC. Read-only collections refuse generic edits while declared Procedures can still run. Ref operations receive the caller/transaction-bound Store.
+Generic publishing edits apply to drafts unless the Schema sets `publishing: { liveEdits: true }` ([lifecycle](../concepts/lifecycle-and-locales.md)); publishing transitions retain their atomic guards and OCC. Read-only collections refuse generic edits while declared Procedures can still run. Ref operations receive the caller/transaction-bound Store.
 
 Use [`defineAdmin` components](native-admin.md#customising-admin) for app-owned cells, inputs, record asides and actions; server work is a Procedure, a View or an application route. Keep exact conflict/uncertain-outcome handling in the shared UI controller.
 

package/docs/handbook/guides/agent-setup.md

@@ -13,20 +13,20 @@ carries.
 The Mantle plugin carries one OSS authoring skill, `mantle`, and local
 acceptance references. It does not configure a hosted-service connection.
 Install from the Git tag matching the exact SDK version you selected (currently
-`v0.2.0`). Pin the tag to keep instructions aligned with the application's
+`v0.2.1-alpha.2`). Pin the tag to keep instructions aligned with the application's
 SDK. A skill install does not upgrade the application's SDK.
 
 For Codex, pin the marketplace checkout:
 
 ```sh
-codex plugin marketplace add aotter/mantle --ref v0.2.0
+codex plugin marketplace add aotter/mantle --ref v0.2.1-alpha.2
 codex plugin add mantle@mantle
 ```
 
 For Claude Code, first clone the release into a directory you will keep:
 
 ```sh
-git clone --depth 1 --branch v0.2.0 https://github.com/aotter/mantle.git mantle-plugin
+git clone --depth 1 --branch v0.2.1-alpha.2 https://github.com/aotter/mantle.git mantle-plugin
 ```
 
 Then, in Claude Code, use that checkout's absolute path:
@@ -40,9 +40,12 @@ Cursor and GitHub Copilot use their plugin manifests from the same tagged
 checkout. Without a plugin host, install only the consumer skill by name:
 
 ```sh
-npx skills add https://github.com/aotter/mantle/tree/v0.2.0 --skill mantle
+npx skills add aotter/mantle@mantle
 ```
 
+Without a version it follows `main`, the latest stable release. To match the
+application's SDK exactly, add its release tag: `npx skills add aotter/mantle#v0.2.1-alpha.2@mantle`.
+
 When upgrading the SDK, update the marketplace ref or local tagged checkout and
 refresh/reinstall the plugin using the host's native workflow. Verify the loaded
 manifest version and skill source. Do not reset a checkout containing local edits.
@@ -53,14 +56,15 @@ project and copies no handbook.
 
 ## 2. Install the SDK, then read its own docs
 
-Use the version the project already pins. For a new project, install stable
-0.2.0 exactly:
+Use the version the project already pins. For a new project, install this
+handbook's version exactly. 0.2.1-alpha.2 is a prerelease; stable 0.2.0 remains the
+production line, and its own tagged handbook describes it.
 
 ```sh
-pnpm add --save-exact @aotter/mantle@0.2.0
+pnpm add --save-exact @aotter/mantle@0.2.1-alpha.2
 ```
 
-Add optional `@aotter/mantle-ui@0.2.0` and `@aotter/mantle-admin@0.2.0` only
+Add optional `@aotter/mantle-ui@0.2.1-alpha.2` and `@aotter/mantle-admin@0.2.1-alpha.2` only
 when the selected surfaces need them. Every selected `@aotter/mantle*` package
 stays at the same exact version. Read, from the application:
 
@@ -81,6 +85,7 @@ the skill's GitHub copy and over any online handbook.
 | `docs/skills/update/SKILL.md` | upgrading `@aotter/mantle`, including from 0.1.x |
 | `docs/skills/provision/SKILL.md` | deploying, with production sign-in |
 | `docs/skills/media-gc/SKILL.md` | auditing or removing stale R2 uploads |
+| `docs/skills/performance/SKILL.md` | after acceptance converges, or when a page, first request or query is slow |
 
 0.2.0 has no `mantle skills` command: nothing is copied into the project.
 An agent reads these files from `node_modules` when the task calls for them.