@aotter/mantle 0.2.0 → 0.2.1-alpha.2

package/docs/handbook/releases/index.md

@@ -1,5 +1,5 @@
 ---
-description: Every Mantle release line — what 0.2.0 changes, and what each stable 0.1.x release contained.
+description: Every Mantle release line — what 0.2.x changes, and what each stable 0.1.x release contained.
 ---
 # Releases
 
@@ -15,6 +15,80 @@ From 0.2.0-alpha.7, Mantle publishes three packages together at one version:
 and `@aotter/mantle-admin` (optional Admin server, SPA and MCP App).
 Pin every package you use to the same exact version and upgrade them together.
 
+## 0.2.1 — in preparation
+
+0.2.1 adds Schema locks: a manifest rule that refuses a row's update or delete
+for every caller path (REST, MCP, Admin and Procedures), with Admin showing the
+lock before an edit. `spec.publishing.liveEdits` lets an application edit a
+published row in place, and the [revisions guide](../guides/revisions.md) now
+freezes the live revision with a lock and switches it atomically. It also brings
+Admin form and refresh fixes, the media picker for custom inputs and pages
+(`@aotter/mantle-admin/media`), `matchTarget` in `@aotter/mantle/describe`, and
+dependency updates for current advisories.
+
+Procedures gain `handler.steps`: a program written one statement per step, where
+`onNoRows: conflict` makes a set-op write that writes nothing a `CONFLICT` and
+rolls the whole program back ("create only if the parent exists"). Ref handlers
+and interactive transactions can use `store.batch` for atomic multi-writes, and
+`mantle bundle` under `wrangler dev` reports stale generated output in one line
+instead of a failed build.
+
+### Upgrading to 0.2.1-alpha.2
+
+Pin the selected packages to `0.2.1-alpha.2` and regenerate. Breaking change:
+
+- **`@aotter/mantle/describe`** keeps only `matchTarget` and the
+  `AppDescription`, `DescribeTarget` and `TargetRequest` types. `describeApp`,
+  `diffApp` and the `@aotter/mantle/target-hash` subpath are removed.
+  **`mantle describe` output is the supported way to get a description outside
+  the CLI:** run `mantle describe <target> manifests/*.yaml > describe.json` in
+  Node.js or Bun (for example in a deploy step) and give the JSON to
+  `matchTarget`. Do not import compiler files from `dist`; a Worker cannot
+  compile manifests that contain SQL ([describe](../reference/describe.md)).
+  Use `mantle describe --diff` instead of `diffApp`, and `_meta.targetHash`
+  instead of `targetHash()`.
+
+Hand-built MCP tools gain three opt-in capabilities; without them the output
+is unchanged ([MCP Apps](../guides/mcp-apps.md), [surface](../reference/surface.md)):
+
+- `Tool.meta` merges into the tool's listed `_meta`. `ui.visibility: ["app"]`
+  can now hide a Procedure from clients without MCP Apps; it is a listing hint,
+  and calls are authorized as before.
+- `withResultMeta(data, meta)` returns `meta` only in the result `_meta`, so a
+  value such as a signed upload URL stays out of `content`. `callTool` returns
+  `{ data, _meta }`; drop `_meta` before forwarding a result to a model.
+- `toolsPageSize` pages `tools/list` with an opaque `nextCursor`.
+
+Also: generation reports a SQL parser that cannot load in the current runtime
+as such, instead of `SQL_SYNTAX`, and the handbook renders under Vue-based
+site generators (bare `<placeholder>` text is now quoted, and `pnpm check`
+fails on any that return).
+
+### Upgrading to 0.2.1-alpha.1
+
+Pin `@aotter/mantle`, and any selected `@aotter/mantle-ui` and
+`@aotter/mantle-admin`, to `0.2.1-alpha.1`, refresh the lockfile, regenerate and
+review owned output. No DDL changes are required. Breaking changes:
+
+- **PostgreSQL `version`:** Store results return `version` as a number, as on
+  SQLite and D1. Procedure results stay driver-native.
+- **Admin record form:** clearing an optional field sends `null`; generated
+  form types for optional fields are `T | null`.
+- **REST route precedence** is fixed and most-specific-first. Only overlapping
+  same-method http Triggers with the same parameter count can change winner.
+  `TRIGGER_PATH_INVALID` and `TRIGGER_PATH_COLLISION` refuse ambiguous paths
+  at generation; see [route precedence](../reference/trigger.md#route-precedence).
+- **Tooling:** the templates move to Wrangler 4.153.0 and
+  `@cloudflare/workers-types` 5.20261027.1.
+- **PostgreSQL serialization failures:** SQLSTATE `40001` and `40P01` from a
+  definitive server refusal are now `CONFLICT` with `kind: "serialization"`
+  (409), instead of an unclassified driver error. Nothing is retried
+  automatically; read again before deciding to retry.
+- **Revisions recipe:** an application that copied the guide's
+  `switch-revision` handler should adopt the new version. It requires
+  `expectedRevisionVersion` from the preview and seals and switches in one
+  `ctx.store.batch`.
+
 ## 0.2.0 (2026-10-19)
 
 The first stable native 0.2 release compiles closed v2 manifests to SQL and

package/docs/handbook/start/agents.md

@@ -1,5 +1,5 @@
 ---
-description: The entry point `mantle help` prints first: choose a complete app or generation only, use examples as references, accept before done.
+description: "The entry point `mantle help` prints first: choose a complete app or generation only, use examples as references, accept before done."
 ---
 # Build with an agent
 
@@ -38,7 +38,11 @@ the app entry (`--entry`) never imports, it warns and names the topic that shows
 4. `pnpm generate`, implement every handler it lists, `pnpm check`, then `pnpm smoke`.
 5. Before reporting the app or a feature done, run [role-only acceptance](../guides/agent-workflow-acceptance.md)
    (`mantle help agent-workflow-acceptance`). Scripted smoke is not acceptance. `pnpm accept` starts the app and hands
-   each role to a fresh evaluator as a URL that carries that role's session.
+   each role to a fresh evaluator as a URL that carries that role's session. After a repair, the guide's
+   [re-verification rule](../guides/agent-workflow-acceptance.md#re-verify-what-a-repair-touches) decides which roles
+   and surfaces run again.
+6. Once acceptance converges, follow the [performance skill](../../skills/performance/SKILL.md): it decides which of
+   front end (Lighthouse), cold start and backend load apply, and holds each to a target before you report done.
 
 The first verified sign-in with `ADMIN_EMAIL` becomes the admin. Further administrators are added in Admin:
 **More → Administrators** invites by email, and **More → Members** grants Admin to an existing member.

package/docs/handbook/start/project-and-cli.md

@@ -59,6 +59,10 @@ Other handles may adapt to the same [structural driver contracts](../guides/adap
 `--auth` and `--site` modules). `mantle bundle`, which Wrangler runs for `wrangler dev` and every
 deploy, refuses to build when an input changed since, so stale generated code cannot run; regenerate and rebuild.
 Commit it with the other generated files.
+Under `wrangler dev` (Wrangler sets `WRANGLER_COMMAND=dev`) the refusal is one line per change instead of a failed
+build: `mantle bundle` removes `<outdir>/worker` and exits 0, so Wrangler reports the entry missing and holds requests.
+Writing `generated/` rebuilds. Other commands, other errors and a build by hand still fail with a nonzero exit.
+To see that form while `wrangler dev` runs, run `pnpm build` (or `mantle bundle` by hand).
 The bundle also prints notes, never errors, for SQL in the app's own code against Better Auth's tables (read users
 through `userOf(caller)` or `readIdentity(auth)` instead) and for Better Auth roles beyond `admin` and `user`.
 

package/docs/handbook/start/quickstart-worker.md

@@ -3,7 +3,7 @@ description: Generate a small native D1 service and mount an application-owned W
 ---
 # Quickstart: a service on Workers
 
-Create an application outside the SDK checkout. Install stable `@aotter/mantle@0.2.0` exactly, TypeScript, Wrangler and Cloudflare Worker types; `node_modules/@aotter/mantle/docs/examples/app-shell/package.json` lists the versions this release is tested with. Read that installed version's handbook; this page describes the native 0.2.0 contract.
+Create an application outside the SDK checkout. Install `@aotter/mantle@0.2.1-alpha.2` exactly (a prerelease; stable 0.2.0 has its own tagged handbook), TypeScript, Wrangler and Cloudflare Worker types; `node_modules/@aotter/mantle/docs/examples/app-shell/package.json` lists the versions this release is tested with. Read that installed version's handbook; this page describes the native 0.2 contract.
 
 Save `manifests/tickets.yaml`:
 

package/docs/skills/develop/SKILL.md

@@ -25,14 +25,23 @@ visibility, OCC and restart persistence, not just a 200 response.
 Before reporting any new app or feature as done, follow the [independent
 acceptance guide](../../handbook/guides/agent-workflow-acceptance.md): write a
 private rubric, then give one fresh agent per role (`admin`, `user`) only its
-role and entry points, across every surface it uses. This is not limited to
+role and entry points, across every surface it uses. After a repair, re-run
+the scope its [re-verification
+rule](../../handbook/guides/agent-workflow-acceptance.md#re-verify-what-a-repair-touches)
+names and state which evidence you reused. This is not limited to
 MCP; if it was not run, say so explicitly and report the work as UNVERIFIED
-rather than done. For MCP workflows, also run the guide's design audit before implementing
-tools.
+rather than done. Hand off with the guide's [layered
+report](../../handbook/guides/agent-workflow-acceptance.md#report-done-ness-in-layers):
+an environment block is BLOCKED on its layer, never a product failure. For MCP workflows, also run the guide's design audit before implementing
+tools. Once acceptance converges, follow the [performance skill](../performance/SKILL.md) before reporting done.
 
 For native Admin, read the [current guide](../../handbook/guides/native-admin.md):
 the app builds Admin with `mantle bundle`. To customise pages, slots, hooks or
 MCP-host-safe components, follow [Customising Admin](../../handbook/guides/native-admin.md#customising-admin).
+Custom structured inputs and browser pages can use the optional
+`@aotter/mantle-admin/media` controlled `MediaPicker`: pass `readOnly` and an exact
+`uploadPurpose` (omit for selection only), apply `onSelect` to the local draft,
+and keep its import out of the MCP App entry. See the native Admin media example.
 Keep matching SDK, Admin and UI versions. Ref handlers retain caller-bound
 `ctx.store`; generic Admin reads use shared generated View templates and writes
 use native Procedure fragments.
@@ -80,6 +89,9 @@ Destructive changes and type changes need explicit data migration. Mantle drops
 
 Writes use Store `insert` / `update` / `delete`, `batch`, `transaction`, or declared Procedures. Never use raw SQL writes: they bypass scope, TTL, publishing and system-column rules. For reads beyond an id lookup or simple AND filter (joins, aggregates, OR, reuse), declare an internal View so the SQL is reviewable and typed. Store `findById`, `find` and `first` remain suitable for handler lookups and embedding in an existing app. Ref handlers receive `ctx.store` bound to the same Caller and transaction.
 
+For published-content replacement with preview and rollback, follow `mantle help revisions`: Core supplies OCC, Schema locks and atomic `store.batch`; the recipe binds the previewed revision ID/version and atomically seals it while switching the parent. Applications own retention and review policy; Core does not mandate a preparation step. Keep the previewed version on submit and require another preview after a revision conflict.
+Use its custom Native Admin preview/switch page: freeze the reviewed content and both row versions, then submit them through the authorized operation. Do not make editors copy version numbers or silently replace the reviewed snapshot after a refresh; conflicts require another explicit preview.
+
 For simple creates/partial updates, prefer Store-backed ref Procedures; keep
 Procedure `requires`/generated input checks, use only allowed patch fields and
 return safe business fields with the actual returned ID/version. Preserve

package/docs/skills/integrate/SKILL.md

@@ -22,7 +22,9 @@ data-preserving schema/auth/role migrations on a copy and retain rollback artifa
 Initial schema.sql is for an empty database, not an in-place upgrade. Requests run
 no DDL or storage checks; the only request-time write outside app operations is
 the configured OAuth resource row (see [OAuth](../../handbook/guides/oauth.md)).
-Verify cutover with actual app tests.
+Verify cutover with actual app tests. Before reporting user-facing work done, run
+[independent acceptance](../../handbook/guides/agent-workflow-acceptance.md), then the
+[performance skill](../performance/SKILL.md).
 
 Preserve the app router, verified identity and native resources. For selected
 Admin, follow the [native guide](../../handbook/guides/native-admin.md) for its

package/docs/skills/performance/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: performance
+description: Make an accepted Mantle 0.2 application fast — Lighthouse for app-authored pages, Worker cold start and first-load budgets, and backend reads and writes under realistic data volume with indexes and internal Views. Use right after independent acceptance converges, or when a user reports a slow page, first request or query.
+metadata:
+  source: "@aotter/mantle"
+  sourcePath: docs/skills/performance/SKILL.md
+  applies_to: mantle 0.2
+  projection: package
+---
+
+# Mantle Performance
+
+This skill sets direction: when to run, what to aim for, in what order and when
+to stop. It names no tools or commands. Choose the measurement and repair
+methods that fit the application, its host and the tools available to you; the
+targets and rules below are what stay fixed.
+
+## When to run
+
+- **After acceptance.** Once [independent acceptance](../../handbook/guides/agent-workflow-acceptance.md)
+  reports CONVERGED for a new application or a feature, continue here before
+  reporting done. Never optimize behavior that has not been accepted: after
+  BLOCKED or UNVERIFIED, report that and stop.
+- **On request.** When a user reports a slow page, slow first request or slow
+  query, run only the part that covers it, then check the others it could affect.
+
+## Choose what to run
+
+Decide from the manifests, the service entry and the changed files, not from
+guesses about future use. Run every part whose condition holds; record each
+skipped part with its reason.
+
+| Run | When the application or change has | Skip when |
+|---|---|---|
+| Front end | Pages a browser opens directly that the application authors: public pages, member pages, a custom frontend, Admin customisations | The only browser UI is SDK-built Admin, unchanged; MCP and REST alone have no page to measure |
+| Cold start | A deployed Worker or service entry: always for a new application; for a change, any added or moved import in the entry, its startup graph, a page's or an MCP App entry's first-load code | The change touched no import, entry, page or MCP App bundle |
+| Backend reads | Views, or Store reads in handlers, whose rows grow with data: lists, search, paging, joins, aggregates, totals, reports | Only id lookups and small, bounded configuration tables |
+| Backend writes | Procedures or Store writes that run often or concurrently: stock, counters, approvals, checkout, imports | Rare single-row administrative writes |
+
+A change in one part can move another: an added index slows writes, a shared
+stylesheet or entry import affects every page. Re-measure what a repair can reach.
+
+## Front end
+
+**Target:** the highest Lighthouse performance score the page allows, with a
+floor of 90 on mobile and 95 on desktop for every distinct page template, and
+no regression in accessibility, SEO or best practices.
+
+- Measure a production build, several runs on mobile and desktop, and report the
+  range. Separate what is real from what only the local environment causes
+  (no compression or HTTP/2, a cold cache) and say which is which.
+- Measure pages behind sign-in (member pages, Admin) through the role's session
+  URL that `pnpm accept` prints
+  ([hand each role](../../handbook/guides/agent-workflow-acceptance.md#hand-each-role-to-its-evaluator)),
+  never by weakening sign-in.
+- Find the actual bottleneck before changing anything; a trace beats a guess.
+- Repair in this order: what blocks the first paint (render-blocking styles and
+  font stylesheets, request chains, unused bytes), then main-thread work (heavy
+  scripts, animations, layout of off-screen content), then repeat visits
+  (content-hashed assets cached long, HTML revalidated).
+- When a bottleneck appears only because the measuring environment lacks
+  something (a GPU, a fast CPU), fix it only in a way that also helps real users
+  without it. Never detect the measuring tool to serve it a different page.
+- After every change, prove nothing else moved: the page looks the same, links,
+  forms and in-page anchors still work, and the
+  [public-page checks](../../handbook/guides/public-pages.md#check-before-you-report-done)
+  still pass without JavaScript.
+
+## Cold start
+
+**Target:** budgets that force code to load when it is needed, not before.
+
+- **Worker:** its startup graph imports only what every request needs; auth, MCP,
+  Admin and rarely used routes load on the request that uses them
+  ([size and startup](../../handbook/guides/size-and-startup.md)). On Workers the
+  startup graph is the entry chunk `mantle bundle` writes under `<outdir>/worker`
+  plus the chunks it imports statically ([outputs](../../handbook/start/project-and-cli.md#outputs));
+  anything behind a dynamic import is outside it. Report its size locally as the
+  *Worker entry static graph*; measure the host's startup time only on
+  a deployment the user has authorized, and keep it well under the host's limit
+  (aim below 50 ms on Cloudflare).
+- **Pages:** each page's *first-load JavaScript* is at most 100 KB, and only
+  what the first paint and first interaction need. Move the rest behind dynamic
+  imports, on use or when the browser is idle. An MCP App the application
+  authors holds its first-load JavaScript, the inline script text of its one
+  HTML file, to the same budget; it renders inside a host, so Lighthouse does
+  not measure it. Report the whole *MCP App HTML document* as its own number: it
+  also holds CSS and markup, so never compare it with this budget.
+- Use the one definition of each metric in
+  [size metrics](../../handbook/guides/size-and-startup.md#size-metrics), with
+  its measurement. Where the SDK's own checks measure differently, that page says how.
+- An overrun is a finding to repair by splitting, not a budget to raise. Raise a
+  budget only with the user's agreement and record why.
+
+## Backend
+
+**Target:** every read and write the application's surfaces actually make stays
+fast at a realistic volume, and no hot path scans a table that grows.
+
+- **Data:** seed an isolated local database, never a shared or production one,
+  with data shaped like real use: several owners and roles, every state, long
+  text where fields allow it, and more than one page of results everywhere. Size
+  the largest tables at 100,000 rows or 10 times the expected first-year volume,
+  whichever is larger. Seed with SQL straight into that database, setting the
+  native columns as [reserved entry columns](../../handbook/reference/schema.md#reserved-entry-columns)
+  describes: it is test data, not an application write.
+- **Load:** call every View and Procedure through the same callers and surfaces
+  the application uses, as each role. The app's local test harness already
+  starts it on a fresh database, signs each role in and calls routes and MCP
+  tools as that role ([local HTTP checks](../../handbook/guides/local-testing.md#what-smoke-covers)).
+  Record typical and slow-tail latency and
+  rows read, then run concurrent writers wherever contention matters. A business
+  rule that breaks under concurrency (oversell, double approval, lost update) is
+  a correctness defect, not a performance finding: fix it first.
+- **Aim:** hot reads stay in the tens of milliseconds locally at seeded volume,
+  and their cost does not grow with table size.
+- **Repair in this order:**
+  1. Read the native query plan of each hot path, using the SQL in its generated
+     query module under `generated/` against the seeded database; a full scan of a
+     growing table is a finding.
+  2. Add the index that serves it in the Schema's `indexes`
+     ([indexes](../../handbook/reference/schema.md#indexes-checks-and-search))
+     together with a native migration ([database changes](../develop/SKILL.md#database-changes)).
+     Index only what a measured query uses; every index costs writes. Paged Views
+     and [Schema locks](../../handbook/reference/schema.md#locks) are index-proven
+     already: generation refuses one no index serves.
+  3. Move complex reads (joins, aggregates, OR, reuse) into an
+     [internal View](../../handbook/guides/typed-queries.md#declare-an-internal-view),
+     page with keysets ([results and paging](../../handbook/reference/view.md#results-and-paging)),
+     and replace exact totals on hot paths ([search and totals](../../handbook/reference/view.md#search-and-totals)).
+  4. Re-measure reads and writes after each repair.
+
+## Rules
+
+- Speed never buys a lower standard: scope, authorization, OCC, atomicity,
+  accessibility, the public-page requirements and every explicit user
+  requirement stay intact. The application's writes still go through Store and
+  Procedures; only seed data for the isolated test database is inserted directly.
+- Do not lower a target, shrink the seeded data or drop a slow case to pass.
+  Report what is left instead.
+- Work locally. Deploying or measuring a deployment follows the
+  [provision skill](../provision/SKILL.md) and needs the user's authorization.
+- After any repair, rerun the [local HTTP checks](../../handbook/guides/local-testing.md).
+  A repair that changes what a user sees or can do is no longer only a
+  performance change: re-run acceptance for the scope the
+  [re-verification rule](../../handbook/guides/agent-workflow-acceptance.md#re-verify-what-a-repair-touches)
+  names. A changed View or Procedure widens it to every surface that reads or
+  writes that data, and so does a `uniqueIndexes` entry. A non-unique
+  `indexes` entry and its migration keep the business rules: run `pnpm check`,
+  the local HTTP checks and your focused regressions, not acceptance.
+- Report app-added cost and SDK-existing cost separately. Built-in Admin has a
+  recorded [baseline](../../handbook/guides/size-and-startup.md#native-admin-baselines)
+  per SDK version; while the installed version and Admin entry are unchanged,
+  reuse it instead of repeating that experiment each round. Built-in Admin's
+  page and MCP App both miss the first-load budget; that is SDK-existing cost,
+  not the application's. A target the SDK's cost misses is still PARTIAL, with
+  its owner named. Never relabel it PASS.
+- Do not patch vendor or SDK code, remove native Admin features or build a
+  general benchmark framework to meet a target.
+- Stop when every target is met, after three rounds, or when two rounds in a row
+  bring no measurable gain.
+
+## Report
+
+For each part: run or skipped (with the reason), the environment, before and
+after numbers as ranges, what changed and what is left. Close with one verdict
+beside the acceptance verdict: **PASS** (every target that applies is met),
+**PARTIAL** (improved, with the targets still missed and why) or **SKIPPED**
+(nothing applied).

package/docs/skills/update/SKILL.md

@@ -15,12 +15,16 @@ metadata:
 Read the installed SDK README, then follow the version-matched [project and CLI
 workflow](../../handbook/start/project-and-cli.md) before editing.
 
-For 0.1.x, follow [Upgrade 0.1 to 0.2](../../upgrade-0.1-to-0.2.md): give the
-0.2 service a new database and move data by export and import; never boot 0.2
-against a 0.1.x database. Between 0.2 versions, apply reviewed migrations
-rehearsed on a copy.
+For 0.1.x, follow [Upgrade 0.1 to 0.2](../../upgrade-0.1-to-0.2.md). Mantle
+ships no migration tool: plan the data move from
+[Moving data from 0.1.x](../../upgrade-0.1-to-0.2.md#moving-data-from-01x),
+verify each fact against the generated `schema.sql` and the 0.1.4 export, and
+have the plan reviewed. Give the 0.2 service a new database, rehearse the load
+on a copy, never boot 0.2 against a 0.1.x database, and keep exports out of the
+repository. The guide's appendix is historical; do not follow it. Between 0.2
+versions, apply reviewed migrations rehearsed on a copy.
 
-For the stable 0.2 line, pin every selected Mantle package to `0.2.0`; do not upgrade an existing application by following a moving dist-tag.
+For the stable 0.2 line, pin every selected Mantle package to `0.2.0`; to try the 0.2.1 prerelease, pin all of them to `0.2.1-alpha.2` and read its release notes. Do not upgrade an existing application by following a moving dist-tag.
 
 Pin exact target SDK/peer versions and read its release notes and Admin build
 instructions. Core-to-native replaces app imports/wiring; it is not