@aotter/mantle 0.2.0 → 0.2.1-alpha.1

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.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

@@ -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.1",
+    "@aotter/mantle-ui": "0.2.1-alpha.1",
     "@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.1",
     "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.1/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.1`). 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.1
 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.1 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.1@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.1 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.1
 ```
 
-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.1` and `@aotter/mantle-admin@0.2.1-alpha.1` 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.

package/docs/handbook/guides/agent-workflow-acceptance.md

@@ -8,10 +8,13 @@ author's replay remain useful; they do not establish independent acceptance. A
 fresh context is not enough if the author still chooses a workflow that mirrors
 the implementation. Every acceptance round gives the evaluator only a
 role and the entry points that role uses; it derives realistic tasks itself
-and the author scores them against a private rubric.
+and the author scores them against a private rubric. The first delivery gets
+full acceptance; after a repair, the change decides what
+[re-runs](#re-verify-what-a-repair-touches).
 If independent acceptance is not run, report `UNVERIFIED`; if a fresh evaluator
 or authorized test transport is unavailable, report `BLOCKED`; neither outcome
-is done.
+is done. Either way, report the evidence you do have in the
+[layered handoff](#report-done-ness-in-layers).
 
 Use the surface the intended user actually uses: a real browser session for
 Admin and application pages; for REST, an HTTP client plus the public API
@@ -110,7 +113,9 @@ the evidence.
    (at least once after a first look, again after its first attempts), executes
    it, and reports PASS/FAIL/BLOCKED per goal with readbacks, rejected writes,
    recovery attempts and interaction counts. Zero findings is a valid result.
-4. **One fresh agent per role, every surface.** For the default two roles, run
+4. **One fresh agent per role, every surface.** In the first round, and in any
+   round the [re-verification rule](#re-verify-what-a-repair-touches) widens
+   to all of them, cover every role and surface. For the default two roles, run
    an `admin` evaluator and a `user` evaluator in the same round on shared live
    data, in the brief's natural order. Between them they cover every surface
    the app exposes to each role: Admin for `admin`, pages for visitors and
@@ -124,24 +129,80 @@ the evidence.
    discoverable), P2 (friction) or P3 (suggestion), with evidence and the
    smallest repair. Separate a violated explicit requirement, a demonstrated
    defect and a newly inferred product wish; a wish is not permission to grow
-   the product.
-6. **Repair outside the evaluator's context, then start over.** The author keeps
-   the findings ledger, makes the smallest in-scope repair, adds focused
-   regressions (authorization, OCC, atomicity), and freezes a new revision.
-   The next round uses new agents and new fixtures and passes them nothing
-   from earlier rounds.
-7. **Converge or stop.** A round converges when it has no P0 or P1 and the
-   evaluators' observed results cover every rubric item visible to their roles;
-   items outside any role's view (another caller's isolation, hidden state)
-   need author regressions, reported under that label. Run at most three
+   the product. A goal the evaluator's own environment stopped (its tool
+   approval, sandbox or network, not an app refusal) is not a finding: record
+   it as an [environment block](#report-done-ness-in-layers) and rerun that
+   role once it is lifted.
+6. **Repair outside the evaluator's context, then re-verify what it touches.**
+   The author keeps the findings ledger, makes the smallest in-scope repair,
+   adds focused regressions (authorization, OCC, atomicity), and freezes a new
+   revision. The next round re-runs the roles and surfaces the
+   [re-verification rule](#re-verify-what-a-repair-touches) names, with new
+   agents and new fixtures, and passes them nothing from earlier rounds.
+7. **Converge or stop.** A round converges when it has no P0 or P1 and
+   evaluator-observed results cover every rubric item visible to their roles:
+   from this round, or reused from an earlier round under the
+   re-verification rule. Items outside any role's view (another caller's
+   isolation, hidden state) need author regressions, reported under that
+   label. Run at most three
    rounds. If the third still has a P0 or P1 or an uncovered rubric item, report
    BLOCKED with the remaining ledger, not acceptance. Setup cleans fixtures in
    `finally` after every round, including aborted ones.
 
 If a fresh agent or authorized test transport is unavailable, record independent
-acceptance as BLOCKED and report the scripted checks separately. Do not invent
+acceptance as BLOCKED and report the scripted checks on their own
+[layers](#report-done-ness-in-layers). Do not invent
 an independent result. Do not deploy or publish merely to obtain acceptance.
 
+Acceptance proves the behavior, not its speed. Once a round converges, the
+[performance skill](../../skills/performance/SKILL.md) decides which performance
+checks apply and holds them to their targets; a performance repair that changes
+what a role sees or can do returns here, scoped by the
+[re-verification rule](#re-verify-what-a-repair-touches).
+
+## Re-verify what a repair touches
+
+The first delivery always gets full acceptance: every role, every surface.
+After a repair, the change itself decides what runs again, not the finding
+that prompted it. Rounds before convergence are not accepted, so diff against
+evidence, not rounds: for each item you want to reuse, diff the current
+revision against the revision it was observed at, and pick the widest row that
+diff matches. A chain of repairs adds up; a page-only repair followed by a
+handler repair has to re-run what the handler repair reaches.
+
+| The repair changes | Re-run with fresh evaluators | May reuse |
+| --- | --- | --- |
+| Only presentation: page or Admin layout, CSS, copy, client-side display | Blind acceptance of the affected UI, for each role that uses it. A shared component or layout affects every page that renders it. | REST and MCP evidence from the same business-rule version |
+| A public contract: a tool or route description, input, output or error shape; the generated client or other `generated/` output it changes | That surface for each role that uses it, plus every UI that consumes it | Other surfaces at the same business-rule version |
+| Authentication, sessions, roles, `requires`, row or tenant scope | Every surface that the changed rule guards, for every affected role | Nothing those surfaces depend on |
+| A SQL Procedure or View, a `uniqueIndexes` entry, a check or lock, a migration that changes results, a handler's business rule | Every surface that reads or writes that data | Nothing those surfaces depend on |
+| A shared transport: the service entry, routing, the HTTP or MCP mount, a shared error envelope | Every surface on that transport | Nothing on that transport |
+
+The business-rule version is the revision of the manifests, SQL, migrations,
+handlers, authorization and service entry. A repair that changes none of
+them keeps that version, so evidence collected at it still stands for
+surfaces the repair did not reach. A repair that changes any of them
+starts a new business-rule version, and looking at the UI alone is not
+enough. One exception: a repair that only adds or drops a non-unique Schema
+`indexes` entry and its migration keeps the version. It changes speed, not
+which rows a read returns or which writes are refused. A `uniqueIndexes`
+entry, a check or a lock does change which writes succeed, so it falls in the
+SQL row. When the diff is unclear, widen.
+
+Every row still runs the author's regressions on the new revision (layers 1
+and 2 of the [layered report](#report-done-ness-in-layers)): `pnpm check`,
+`pnpm smoke`, `pnpm test` and the focused regressions for the repair.
+
+A re-run evaluator is as fresh as the first: a new agent, new fixtures, only
+its role and the entry points under re-test. Do not tell it what was
+repaired, what to check or what an earlier evaluator did. No previous
+answers, rubric or precomputed steps.
+
+For every rubric item that was not re-run, record the round and revision its
+evidence comes from and why the changes since that revision could not affect
+it. Never report a
+reused item as observed in a later round.
+
 ## Hand each role to its evaluator
 
 Setup signs each role in; the evaluator receives the role's access, never a credential it could reuse or widen.
@@ -185,7 +246,8 @@ Fill this in per role. It names the role and the doors, never the jobs:
 > first look at the interface and again after your first attempts. Then do the
 > work and report each goal as PASS/FAIL/BLOCKED with what you read back,
 > what was refused, what it cost you, and the smallest change that would have
-> helped. Report what you covered and what you could not reach; finding nothing
+> helped. For BLOCKED, say whether the service refused you or your own tools
+> or permissions stopped you. Report what you covered and what you could not reach; finding nothing
 > wrong is acceptable.
 
 The author separately verifies isolation between callers, stale-version
@@ -194,6 +256,50 @@ through authorized test fixtures. Do not grant the evaluator extra authority
 just to observe hidden state. Keep author regressions distinct from what the
 fresh agent actually observed.
 
+## Report done-ness in layers
+
+Report a handoff in four layers, in this order, each for the exact commit. Each
+layer proves something the others do not; a passing layer neither replaces nor
+is invalidated by another layer's result.
+
+| Layer | What it proves | Evidence |
+| --- | --- | --- |
+| 1. Generation and types | Manifests compile, `generated/` is current, the app typechecks and builds. No handler runs. | `pnpm check` (includes `generate --check`), `pnpm build` |
+| 2. Business rules and permissions | Handlers on a fresh local D1 over HTTP: each operation at its edges, refusals, caller isolation, visitor pages, MCP discovery, the Admin MCP App loading. Author's evidence. | `pnpm smoke`, `pnpm test`; [Local HTTP checks](local-testing.md) |
+| 3. Independent acceptance, per role | A fresh agent given only its role and entry points finds and finishes that role's work on each surface it uses. | Per role: the [rounds](#run-role-only-acceptance-rounds-until-they-converge) verdict and surfaces covered, naming the round and revision of any [reused](#re-verify-what-a-repair-touches) evidence |
+| 4. External platform | A real MCP host connects over OAuth; the production origin serves the deployed app. Local cookie sessions prove neither. | Host and version, identity, origin, observed result |
+
+Give each layer, and each role on layer 3, one status:
+
+- **verified**: the evidence above, with its command or host and result.
+- **failed**: the product is wrong. Name the failing check or finding.
+- **BLOCKED**: the layer could not run. Give the reason, what refused or is
+  missing, and what would unblock it.
+- **not applicable**: with the reason. Layer 4 is not applicable unless the
+  requested work includes an external host connection or a deployment.
+
+A layer nobody attempted is UNVERIFIED, as above. A block from the execution
+environment (an agent's approval policy refusing fictional writes, no browser,
+no network, a sandbox) is BLOCKED on that layer only. It is never a failed
+layer or a product finding, and it does not invalidate the evidence on other
+layers. Do not work around it by widening the evaluator's authority, faking a
+result or deploying; ask whoever controls the environment and rerun only that
+layer on the same revision.
+
+The work is done only when layers 1 to 3 are verified for every role and
+surface, and layer 4 is verified or not applicable. Partial evidence is still
+reported, layer by layer; it is not done:
+
+```markdown
+| Layer | Status | Evidence |
+| --- | --- | --- |
+| 1. Generation and types | verified | `pnpm check`, `pnpm build` at <commit> |
+| 2. Business rules and permissions | verified | `pnpm smoke` (<n> checks), `pnpm test` |
+| 3. Acceptance: admin | BLOCKED: evaluator's approval policy refused to create fictional records; needs <permission> | round 1 stopped at goal <n> |
+| 3. Acceptance: user | verified: CONVERGED in round <n> | member pages in round <n>; MCP reused from round <m> at <revision> (page-only repair) |
+| 4. External platform | not applicable: no deployment or external host requested | |
+```
+
 ## Record evidence in the existing issue or handoff
 
 Use ordinary Markdown; no new receipt schema or framework is required:
@@ -201,16 +307,20 @@ Use ordinary Markdown; no new receipt schema or framework is required:
 - Original brief, the private rubric, roles, environment, per-round budgets
   and round cap.
 - Setup assistance and what each agent could access; identify distinct rounds.
-- Per round: revision, each evaluator's derived goals (first list and
+- Per round: revision, business-rule version, the roles and surfaces re-run
+  and why (the [re-verification rule](#re-verify-what-a-repair-touches) row),
+  each evaluator's derived goals (first list and
   refinements) and criteria, the gaps between them and the rubric, per-goal
   PASS/FAIL/BLOCKED, actual readbacks and interaction references,
   request/page/tool counts
   and negative/recovery attempts, with their differing scope stated.
 - Findings ledger with P0–P3, owner, disposition, minimal repair and
   regression commands/results.
-- Coverage of each rubric item (evaluator-observed, author regression only, or
-  UNVERIFIED); the final CONVERGED / BLOCKED / UNVERIFIED verdict and rounds
-  used. Retain every failed report.
+- Coverage of each rubric item (evaluator-observed in this round,
+  evaluator-observed and reused from round <n> at <revision> with the reason,
+  author regression only, or UNVERIFIED); the final CONVERGED / BLOCKED / UNVERIFIED verdict and rounds
+  used, which is layer 3 of the [layered report](#report-done-ness-in-layers).
+  Retain every failed report.
 - Fixture cleanup result and every remaining limitation.
 
 Keep credentials, raw auth logs, full resource HTML and private operational