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

package/docs/adr/0039-postgresql-is-native.md

@@ -0,0 +1,130 @@
+# ADR-0039: PostgreSQL is native, and node-postgres is its only driver
+
+**Status:** Accepted (2026-10-08).
+
+**Date:** 2026-10-08.
+
+**Supersedes:**
+- ADR-0035: the cross-dialect parity clauses (one shared subset, identical results on every dialect).
+- ADR-0037: "moving from D1 to PostgreSQL still needs no rewrite", and the SQLite emulation it implies.
+- ADR-0038: the Bun.SQL PostgreSQL host and its temporary-table result description. Bun's SQLite preset is unchanged.
+
+## Context
+
+Mantle has run PostgreSQL as an emulation of D1/SQLite, so that one manifest returns identical results on both engines.
+
+### What the emulation costs
+
+The PostgreSQL audit on the procurement fixture (S, M and L tiers, Bun and Workers hosts) measured three costs.
+
+**1. No declared index can serve a paged sort.**
+- Paging forces SQLite's NULL order: `ASC NULLS FIRST`, `DESC NULLS LAST` (`core/sql/run.ts:257,297`). The tiebreak is `id COLLATE "C"`.
+- PostgreSQL btree indexes have the opposite default order (`postgres/storage.ts:88-93`).
+- As a result, every Admin list and every View with an ORDER BY does a full scan plus a sort, even with an index:
+
+  | Measurement | Today | With an order-matching index |
+  |---|---|---|
+  | Admin list, L tier, c=8 | 3 rps | 139 rps |
+  | procurement report | 47 ms | 0.26 ms |
+
+- Matching the indexes to the emulated order would mean a `NULLS FIRST` index migration, permanently.
+
+**2. Translation shims in SQL that authors never see.**
+- `_mantle_jget` reproduces SQLite's `->>` and `$` paths.
+- `_mantle_bool` reproduces SQLite's integer truthiness.
+- `_mantle_json_each` reproduces SQLite's json_each columns.
+- `||` is cast to text, and pinned `DateStyle`/`IntervalStyle`/`extra_float_digits` settings exist only so that text decodes the way D1's does.
+
+**3. A second driver on Bun that exists only to recover type metadata.**
+- Bun.SQL exposes no column OIDs or typmods: verified on Bun 1.4.2, and its docs list column type transforms as unfinished.
+- Mantle therefore describes every result through `CREATE TEMP TABLE … WITH NO DATA` plus `pg_attribute`.
+- A View read costs 12 statements and 10 round trips on Bun.SQL, against 4 and 4 on node-postgres.
+- Every Bun role also needs `TEMPORARY`.
+
+### Who actually needs D1/PostgreSQL parity
+
+No caller needs one manifest to switch engines without changes:
+- **Cloud tenants** are moving to PostgreSQL.
+- **On-premises single-organization deployments** run PostgreSQL on Bun.
+- **D1 services** stay on D1.
+
+What callers do need is that one PostgreSQL plan behaves the same on Bun and on Workers. The same app runs in Cloud and on-premises, and handler code and output schemas see the values directly.
+
+## Decision
+
+### 1. Each dialect is its own target
+
+- A manifest targets one dialect.
+- Mantle does not promise that a PostgreSQL manifest compiles for D1, or that a D1 manifest compiles for PostgreSQL.
+- Mantle does not promise that the two dialects return equal values.
+- The compliance suite checks each dialect against its own semantics, not against the other dialect.
+- The closed allowlist stays: base for D1, reference for PostgreSQL (ADR-0037 decision 1).
+
+### 2. PostgreSQL semantics are PostgreSQL's
+
+**Ordering.** Paging uses PostgreSQL's own NULL order (`ASC NULLS LAST`, `DESC NULLS FIRST`), and the cursor follows it. The tiebreak uses the column's own collation, so declared indexes serve ORDER BY … LIMIT. An index matches a sort only when every key in it runs in the same direction; that remains an authoring rule for indexes.
+
+**The SQLite shims go.** `_mantle_jget`, `_mantle_bool`, `_mantle_json_each`, the `||` text cast and the `$`-path lowering are removed. PostgreSQL manifests use PostgreSQL's jsonb operators, booleans and `jsonb_array_elements`. A manifest that relied on a SQLite-ism fails validation with a position and the PostgreSQL spelling.
+
+**What stays.** Mantle's own functions that are not emulation stay:
+- `_mantle_expect` (#1379);
+- the policy rewrite;
+- convergence;
+- the boot-time settings check, reduced to what the remaining decoding needs.
+
+### 3. node-postgres is the only PostgreSQL driver
+
+- **Every host uses node-postgres (`pg` 8.23 or later):** the Bun preset (a `pg.Pool`), the Workers/Hyperdrive preset (a client per request), and any host composed by hand.
+- **Request scoping and pipelining are the same everywhere:** `requestScoped` and the pipelined write path from #1379 run identically on every host.
+- **The Bun.SQL host is removed**, along with its result description and the `TEMPORARY` grant.
+- **Values come out of one decoder** (`decodeField` over RowDescription OIDs and typmods). Bun and Workers therefore return the same values for the same plan, with no separate value contract to maintain.
+
+## Consequences
+
+- **Indexes work on PostgreSQL**, with no `NULLS FIRST` migration. The keyset cursor (row comparison, #1391 follow-up) becomes the next step for deep pages.
+- **There is one PostgreSQL code path** to test, profile and secure, and no `TEMPORARY` privilege.
+- **This is breaking for existing PostgreSQL services:**
+  - NULL position in sorted results changes.
+  - Manifests that use SQLite JSON paths or integer truthiness on PostgreSQL must be rewritten.
+  - The Bun PostgreSQL preset's entry changes.
+  - Release notes give the rewrites.
+- **D1 → PostgreSQL is a migration, not a switch:**
+  - Export, rewrite the manifest's SQL, import.
+  - aotter/mantle#1298 (portable dump) is re-scoped to data only.
+  - aotter/mantle-home#251 (tenant upgrade from D1) becomes an explicit migration.
+- **Bun gives up Bun.SQL's native client.** The audit measured no gain from it where Mantle's wrapper was absent: the session check ran 390 rps on Bun.SQL and 388 rps on node-postgres. If Bun later exposes column metadata and a measured gain appears, a Bun.SQL driver can return as a second implementation of the same contract.
+
+## Alternatives
+
+- **Keep parity and build `NULLS FIRST` indexes.** Rejected. It keeps every shim, needs an index migration on every existing database, and buys a guarantee no caller uses.
+- **Keep Bun.SQL with a cached result description.** Rejected. It makes the wrapper cheaper but keeps it, keeps the `TEMPORARY` grant, and keeps two drivers to maintain.
+- **Keep Bun.SQL, with a value contract both drivers normalise to.** Rejected. Two drivers plus a normalisation layer cost more than one driver, and the contract would need maintaining.
+
+## How to apply
+
+Each step is its own PR. Each is breaking where noted.
+
+1. **Bun preset on node-postgres.**
+   - `cli/preset.ts`/`generate.ts` write a `pg.Pool` entry with `requestScoped`.
+   - Remove `bunPgConnect`, `bunPostgresStorage` and the result-description path from `src/bun`, and the `TEMPORARY` note from the handbook.
+   - `test/bun/native.ts` runs the PostgreSQL conformance on node-postgres under Bun.
+2. **Native ordering.**
+   - `run.ts` stops emitting NULLS clauses on PostgreSQL. The dialect supplies its default NULL order, and the cursor predicate follows it.
+   - The tiebreak drops `COLLATE "C"` on PostgreSQL.
+   - Add EXPLAIN-based tests showing a declared index serves each paged sort.
+3. **Remove the SQLite shims** from `postgres/lower.ts`, `print.ts` and `storage.ts` `FUNCTIONS`.
+   - Add validation diagnostics that name the PostgreSQL spelling.
+   - Rewrite the PostgreSQL compliance fixtures and the reference suite in PostgreSQL's own semantics.
+4. **Docs and skills.**
+   - The handbook's dialect pages and the consumer skills say that each dialect is its own target.
+   - Add release notes with the rewrites.
+5. **Follow-ups from the audit** (#1391 and the audit report), in this order:
+   - keyset cursor;
+   - auth: drop the discarded JWT header, plain reads;
+   - SQL compile cache;
+   - boot trim;
+   - convergence safety (CHECK diffing, re-reading the fingerprint under the lock).
+
+## Implementation status
+
+Accepted. Implementation follows in the stacked PRs listed under How to apply.

package/docs/adr/README.md

@@ -39,6 +39,7 @@ Records of *why* mantle ended up shaped this way. The numbering preserves POC AD
 | [0036](0036-host-and-dialect.md) | A project picks a host (`cloudflare`, `none`) and a dialect (`sqlite`, `postgres`, a package) once; `mantle generate` writes the pair's preset; the host never enters the plan. | Accepted for 0.2.0; reserved Bun host amended by 0038 |
 | [0037](0037-postgresql-is-the-reference-dialect.md) | PostgreSQL is the reference dialect: one closed allowlist in Core (base and reference profiles), D1 runs the base subset; a View reads an internal View; `restrict` narrows at runtime; a statement timeout on PostgreSQL; Cloud's PostgreSQL connection stays with the platform. | Accepted for 0.2.0 |
 | [0038](0038-bun-native-host.md) | Bun is a native host: `@aotter/mantle/bun` owns the native SQLite and PostgreSQL drivers and Admin files; `host: bun` defaults to `dialect: postgres`; the CLI writes a `Bun.serve` entry once. | Accepted for 0.2.0 |
+| [0039](0039-postgresql-is-native.md) | PostgreSQL is native, not a D1 emulation: each dialect is its own target, PostgreSQL ordering and SQL are PostgreSQL's, and node-postgres is the only PostgreSQL driver on every host. | Accepted; supersedes parts of 0035, 0037 and 0038 |
 
 ## Reading order
 
@@ -94,3 +95,4 @@ These retain their issue-based filenames and original decision status.
 | [#845 Frontend client](adr-lite-845-frontend-client.md) | Accepted |
 | [#861 Admin WebMCP](adr-lite-861-admin-webmcp.md) | Accepted |
 | [909 Admin UI kit](adr-lite-909-admin-ui-kit.md) | Accepted; amended by 0029 |
+| [#1376 Admin extensions](adr-lite-1376-admin-extensions.md) | Accepted |

package/docs/adr/adr-lite-1376-admin-extensions.md

@@ -0,0 +1,330 @@
+# ADR-lite 1376: Admin extensions
+
+**Status:** Accepted (revision 3: the full contract, for hosts and for
+projects; replaces the pages-only draft)
+
+## Context
+
+A project or the host that mounts Admin sometimes needs its own UI next to the generated
+collections, Views and operations. Examples are an operator's
+access-management screen, a record action that calls a host service, or a
+field widget for a host-specific format. Today the Admin SPA has no way to add
+any of these:
+
+- Its routes and navigation are fixed.
+- `createAdminSurface` has no host routes.
+- The UI kit (ADR-lite 909) deliberately does not export the application
+  shell.
+
+Hosts are left with forking the SPA or patching its private DOM.
+
+The first draft of this record added whole pages only. A survey of how other
+products open their admin turns up the same set of extension points in
+almost all of them. The CMS products were Strapi, Directus, Payload, Sanity,
+Contentful, Keystone, Decap, Tina and WordPress. The platforms were Shopify
+Admin UI extensions, VS Code, Grafana, Backstage, Atlassian Forge, Figma and
+the Keycloak admin console. The recurring points are:
+
+- pages with a navigation entry
+- record and list actions
+- record side panels
+- field widgets
+- dashboard widgets
+- settings pages
+- server endpoints
+
+The survey also turns up five lessons that bear on this design:
+
+1. **Only a narrow, typed surface survives major versions.** Every product
+   that exposed its internal context or helper packages broke all its plugins
+   at the next major: Strapi's helper-plugin, Sanity's Parts, Payload 2→3,
+   Decap's React pin. Contentful's location-scoped SDK and Backstage's typed
+   data refs aged well.
+2. **Declare in data, run in code.** The extension says *what* attaches
+   *where* as data. Code supplies only the behavior. Grafana had to retrofit a
+   static mirror of its imperative `addLink` calls before it could index,
+   validate or lazy-load extensions. Declarations can also be validated and
+   diffed before anything runs. That matters here because agents author and
+   deploy Mantle projects.
+3. **Typed contribution points beat free-form injection zones.** Strapi 5 and
+   Sanity steer integrators to typed actions with a position and a dialog
+   kind. Strapi now marks its free zones internal.
+4. **Navigation visibility is not authorization.** Strapi, Payload and
+   Directus all warn about this. Every extension route has to check the
+   caller on the server.
+5. **Same-origin code has no security boundary.** That is acceptable for code
+   the host installs and trusts. Untrusted third-party code needs an iframe
+   (Contentful, Forge Custom UI) or remote rendering (Shopify). The contract
+   should allow such an isolation tier later without changing.
+
+## Decision
+
+### 1. One declaration per extension, from the project or the host
+
+`createAdminSurface` accepts `extensions: AdminExtension[]`. Each extension
+pairs a declaration, which is plain data, with server handlers, which are
+code:
+
+```ts
+{
+  apiVersion: 1,
+  id: 'access',                        // kebab-case, unique, immutable once deployed
+  title: { en: 'Access', 'zh-TW': '存取權限' },
+  source: ACCESS_MODULE,               // the module's code; Admin serves it at {basePath}/extensions/access.js
+  // or, served by the host instead: module: '/assets/access/admin.js', integrity?: 'sha384-…'
+  contributes: {
+    pages:    [{ id, title, role, nav: { group: 'more' | 'settings', order? } }],
+    settings: [{ id, title, role, schema }],          // JSON Schema form, no client code
+    actions:  [{ id, title, role, target, presentation, destructive?, when? }],
+    panels:   [{ id, title, role, target, when? }],
+    fields:   [{ id, target, when?, optionsSchema? }],
+  },
+  handlers: {
+    api?(request, { caller, extension, path }): Promise<Response | null>,
+    settings?: { [id]: { load(caller), save(caller, value) } },
+    actions?:  { [id]: { run(caller, { record?, selection?, schema? }) } },
+  },
+}
+```
+
+### 1a. Projects author extensions; hosts may add their own
+
+Extensions are not a host-only feature. An agent customizing a project's Admin
+is the main author:
+
+- A project exports `adminExtensions: AdminExtension[]`. For a new project the
+  generated preset writes `src/admin-extensions.ts` and passes it to
+  `createAdminSurface`; the preset is written once, so an existing
+  `src/service.ts` wires it by hand. A host that builds Admin itself (for example a hosted
+  platform) reads the same export and appends its own extensions.
+- Extension ids are one namespace per Admin. A host extension whose id
+  collides with a project extension fails construction, so a project can
+  never shadow a host page, and the reverse.
+- A module needs no build step: Admin's import map provides React, the kit and
+  the extension helper (§4), so plain ESM works. `source` lets Admin serve the
+  module itself, so a project needs no static-file setup; Admin computes its
+  integrity. The same project shows the same extensions locally and when
+  deployed; a host only adds.
+
+**Trust.** A project extension's module runs in Admin's origin with the
+viewer's session. That gives it no more power than the project already has:
+whoever can deploy the project already controls its server code, its
+handlers and its storage. Two rules keep that equivalence true:
+
+- Host extension routes reachable from a project's Admin origin must act only
+  on that project. Anything wider (an organization console, other projects)
+  lives on a different origin, so a project module never holds its session.
+- A host that restricts what some staff may do inside a project (fine-grained
+  policies) must treat the right to deploy as full trust in that project, and
+  govern deployment separately.
+
+Contributions and their targets (§1b covers how manifests use them):
+
+| Contribution | Targets (`/v1`) | Client code |
+| --- | --- | --- |
+| page | its own route `/admin/x/{extension}/{page}`; in navigation when it declares `nav` | a renderer |
+| settings | its own route `/admin/x/{extension}/{id}`, always in navigation | none. Admin renders `schema` (the form subset) with its form; `load` and `save` run on the server |
+| action | `record/v1` (record header), `list.selection/v1` (bulk), `list.toolbar/v1` | `presentation: 'run' \| 'confirm'` needs none (the server `run` is called). `'dialog'` mounts client code in an Admin dialog |
+| panel | `record.sidebar/v1`, `home/v1` | a renderer |
+| field | `field.input/v1`, `field.cell/v1` | a renderer |
+
+`when` is a closed predicate over names only: `{ schema?: string[], field?:
+string[], format?: string[] }`. It contains no expressions and no record
+values, so the server can evaluate it.
+
+`role` is the minimum staff role, the same vocabulary as `requires.auth`. It is
+required except on `fields`, where it defaults to `contributor`.
+
+### 1b. Manifests pick contributions through `uiSchema`
+
+There are two ways to attach a contribution. Both stay:
+
+- **From the manifest.** `uiSchema` already chooses Admin presentation
+  (`fields.<name>.widget: textarea`, `list.columns`, `collectionAction`).
+  It may also name a contribution as `<extension>/<contribution>`:
+
+  ```yaml
+  # Schema products
+  uiSchema:
+    fields:
+      color: { widget: brand-kit/color, options: { palette: brand } }
+      notes: { widget: textarea }
+    list:
+      cells: { color: brand-kit/swatch }       # field.cell/v1
+    panels: [brand-kit/usage]                  # record.sidebar/v1
+  # Procedure reassign-order (uiSchema.fields.<name>.widget works the same)
+  # View sales-by-region
+  uiSchema:
+    list: { cells: { region: maps/region-badge } }
+  ```
+
+  - The binding sits next to the field it changes. An agent writes both in
+    one change, and a manifest review shows it.
+  - `options` is passed to the renderer as `ctx.options`. A contribution may
+    declare `optionsSchema` (the settings form subset). `options` is checked
+    against it, and a contribution without one refuses `options`.
+  - The target kind must match the key: `fields.*.widget` names a
+    `field.input/v1` contribution, `list.cells.*` a `field.cell/v1`
+    contribution, and `panels` a `record.sidebar/v1` contribution.
+- **From the extension.** `when: { schema, field, format }` attaches a
+  contribution everywhere it matches without touching manifests, for example
+  every field with `x-mcp-hint: money-minor`. This suits host extensions and
+  cross-cutting widgets.
+
+When both apply to one place, the manifest wins.
+
+**Validation.**
+- The manifest grammar checks the shape: `<extension>/<contribution>` with
+  kebab-case parts. `textarea` stays the one built-in widget.
+- Whether the named contribution exists, has the right target and accepts the
+  `options` is checked where the plan and the extensions meet:
+  - `createAdminSurface` fails construction with `UI_EXTENSION_UNKNOWN`,
+    `UI_EXTENSION_TARGET` or `UI_EXTENSION_OPTIONS`.
+  - `checkPlanUiExtensions(plan, extensions)` is exported, so a deploy step or
+    a test can run the same check before the service starts.
+
+**Who may be named.** A manifest should name only the project's own
+extensions, so the project renders the same locally and when deployed; a host
+attaches its contributions with `when` instead. Core cannot enforce this: the
+extensions reach `createAdminSurface` as one list with no provenance, so it
+checks existence, target and options, not ownership. A host that must keep
+manifests from naming its contributions checks the plan's names
+(`planUiExtensionRefs`) against its own ids before it starts Admin.
+
+**A named widget is a decision.** When `uiSchema.fields.<name>.widget` names
+any widget, `textarea` included, a matching `when` does not replace it; a
+contribution the viewer's role does not reach falls back to Admin's own
+control, not to `when`.
+
+**Effect.** `uiSchema` stays presentation only. It never changes validation,
+MCP schemas or authorization. The field's JSON Schema still validates what a
+widget sends.
+
+### 2. The server decides what a caller sees, and checks again on use
+
+- `GET /admin/api/site` (and bootstrap's `site`) returns the contributions
+  the caller's role reaches, with their declarations only. Handlers and
+  `integrity` are not sent.
+- Every extension route checks a signed-in staff session and the
+  contribution's role before it calls the host:
+  - `{basePath}/api/x/{extension}/settings/{id}`: `GET` → `load`, `PATCH { value }` → `save`
+  - `{basePath}/api/x/{extension}/actions/{id}`: `POST` → `run`, with `{ record }`, `{ selection }` or `{ schema }` for the action's target; `when.schema` is enforced here too
+  - `{basePath}/api/x/{extension}/api/{path}` → `api`, for the extension's lowest contribution role
+  - `GET {basePath}/extensions/{id}.js` → a `source` extension's module, for the same role
+- `save` input is validated against `schema` before the host sees it (400 with
+  `error.fields` otherwise).
+- `null` answers 404. Answers are `no-store` unless the host sets
+  `cache-control`. Cross-site mutation protection is the `withCaller`
+  wrapper's, as for every Admin route.
+- The checks above are the minimum. Finer authorization is the host's, inside
+  its handlers.
+
+### 3. Client modules supply renderers keyed by contribution id
+
+```ts
+import { defineAdminExtension } from '@aotter/mantle-ui/extension'
+
+export default defineAdminExtension({
+  pages:   { overview: (element, ctx) => cleanup },
+  actions: { 'reassign': (element, ctx) => cleanup },   // dialog presentation only
+  panels:  { 'history': (element, ctx) => cleanup },
+  fields:  { 'color': (element, ctx) => ({ update(next) {}, unmount() {} }) },
+})
+```
+
+A renderer returns nothing, a cleanup, or `{ update, unmount }`. With `update`,
+Admin passes later contexts (a new value, a new language) in place instead of
+mounting again; a field value the renderer reported itself never remounts it.
+
+- Admin imports `module` once, when a contribution that needs it is first
+  shown, and calls the renderer for that contribution.
+- A renderer for an undeclared contribution is ignored. A declared
+  contribution without a renderer shows an error in its place.
+- The context is serializable and typed per target. It holds `{ extension,
+  contribution, apiBase, language, theme, caller: { role } }` plus:
+  - `record: { schema, id, version }` for record targets
+  - `selection: { schema, ids }` for list targets
+  - `field: { schema, name, value, readOnly, property }` for field targets,
+    and `options` from `uiSchema`; `field.input/v1` also gets `onChange(value)`
+- A small `host` object offers `navigate(path)`, `notify(message)` and
+  `close()` for dialogs.
+- Admin offers no other SPA API. This is a supported surface, not a sandbox:
+  the module is trusted same-origin code (§5).
+- Each mount gets a fresh element. A renderer that resolves after its mount was
+  replaced writes into a detached node, never over the current one.
+
+### 4. Shared dependencies come from Admin
+
+- Admin's HTML declares an import map for `react`, `react/jsx-runtime`,
+  `react-dom`, `react-dom/client`, `@aotter/mantle-ui/kit` and
+  `@aotter/mantle-ui/extension`, served beside the shell. The React entries
+  re-export Admin's own instance; the kit and the helper are real modules
+  that import React through the same map, and the kit's stylesheet loads with
+  the first extension.
+- Extension modules use these specifiers directly (or mark them external when
+  bundling). They share Admin's single React and keep its look, theme and
+  accessibility.
+- The kit and the extension helper are the whole public UI surface. The shell
+  stays private (ADR-lite 909).
+
+### 5. Trust tier
+
+- Extensions are trusted host code. They run in Admin's origin with Admin's
+  privileges, and Core does not sandbox them.
+- `module` must be a same-origin path, so Admin keeps its existing CSP and
+  framing policy.
+- `integrity` (given for `module`, computed for `source`) goes into the
+  shell's import map, so the browser enforces it on import.
+- An isolated tier for untrusted extensions is reserved and is not part of
+  this decision. Because contexts are serializable and the UI surface is the
+  kit, an iframe or remote-rendering tier can reuse this declaration format
+  unchanged.
+
+### 6. Stability and tooling
+
+- `apiVersion` and the `/v1` target names version the contract. Within a
+  version, changes are additive only. A breaking change adds `/v2`, and both
+  run side by side through a deprecation window.
+- Construction validates every declaration and fails on:
+  - a bad or duplicate id
+  - an unknown target or `apiVersion`
+  - a non-same-origin `module`, or both `module` and `source`
+  - a contribution that needs code when there is neither
+  - a settings `schema` outside the form subset
+- Core exports the declaration's JSON Schema, so tooling and agents can check
+  a declaration without running it.
+- Core also exports `diffAdminExtensions(previous, next)`. It reports added
+  and removed contributions, role changes and module changes, for review
+  screens.
+
+## Non-goals
+
+- Replacing the shell, navigation component or layout.
+- Free-form injection into arbitrary DOM.
+- A marketplace or untrusted third-party extensions (reserved tier, above).
+- Server-side sandboxing of handlers. They are host code in the host's
+  process.
+- Declaring extensions in the YAML manifest. They live in the project's
+  service module (TypeScript), so the four-atom grammar does not change.
+
+## Consequences
+
+- Projects and hosts add pages, settings, actions, panels and field widgets
+  without forking the SPA, and the SPA stays one build. Without
+  `extensions`, nothing changes.
+- An agent can customize a project's Admin with a small module and a
+  declaration that tooling validates and diffs before deploy. A `uiSchema`
+  line in the manifest binds it to a field, a list cell or a record panel.
+- The `uiSchema` vocabulary widens: `fields.<name>.widget` accepts
+  `<extension>/<contribution>` beside `textarea`, with `options`; Schemas gain
+  `list.cells` and `panels`; staff Views gain `list.cells`. This record is the
+  grammar decision CONTRIBUTING requires for new keys: the name's shape is
+  closed and checked at generate time (`SCHEMA_UI_INVALID`,
+  `VIEW_UI_INVALID`), and its existence at construction
+  (`UI_EXTENSION_UNKNOWN`, `UI_EXTENSION_TARGET`, `UI_EXTENSION_OPTIONS`).
+- Settings pages need no client code at all. This covers most host
+  configuration screens and is the easiest kind for an agent to author and
+  review.
+- Admin takes on an import map and the `@aotter/mantle-ui/extension` entry.
+- The first draft's `extensions: { pages, api }` is replaced before any
+  release; it was never published.

package/docs/examples/commerce-inventory.md

@@ -321,7 +321,24 @@ Points worth noticing:
 - **`expired-orders` is `internal`:** callable only through
   `ctx.store.view` or `runtime.store`. SQL compares `expiresAt` with `now()`.
 - **`picking-list`** unnests order lines with `json_each`, the one comma join
-  the dialect allows.
+  the D1 dialect allows. This example's SQL is D1 (SQLite) SQL. On PostgreSQL
+  the same View reads:
+
+  ```sql
+  SELECT o.orderToken, o.customerName, o.shippingAddress,
+         item.value ->> 'productSlug' AS "productSlug",
+         item.value ->> 'title' AS "productTitle",
+         item.value ->> 'quantity' AS quantity
+  FROM orders o, jsonb_array_elements(o.items) WITH ORDINALITY AS item(value, n)
+  WHERE o.orderStatus = 'paid'
+  ORDER BY o.created_at, item.n LIMIT 200
+  ```
+
+  `jsonb_array_elements_text(o.items) WITH ORDINALITY AS j(value, n)` is the
+  form for text elements. A sorted View over a row source needs the alias and
+  `WITH ORDINALITY`; Mantle pages by `n`. The
+  [rewrite table](../handbook/concepts/runtime-and-adapters.md#the-postgresql-dialect)
+  lists the other SQLite spellings PostgreSQL refuses.
 
 ## Handlers
 

package/docs/examples/reference-service/package.json

@@ -8,8 +8,8 @@
     "check": "mantle generate && mantle generate --check && tsc --noEmit && node smoke.mjs"
   },
   "dependencies": {
-    "@aotter/mantle": "0.2.0-alpha.5",
-    "@aotter/mantle-ui": "0.2.0-alpha.5",
+    "@aotter/mantle": "0.2.0-alpha.6",
+    "@aotter/mantle-ui": "0.2.0-alpha.6",
     "@better-auth/cimd": "1.7.7",
     "@better-auth/mcp": "1.7.7",
     "@better-auth/oauth-provider": "1.7.7",

package/docs/handbook/cloudflare/authentication.md

@@ -35,9 +35,9 @@ preset does); without Admin it is `/oauth/consent`, the plain page
 then `createCallerResolver(auth, { jwtBearer: { audience: `${origin}/mcp`, scopes: ["mcp"] } })`,
 `createAuthRoutes(auth, { resolver })` and an `AdminIdentity` over the auth's
 own methods. With dialect `postgres` the preset passes `database:
-pgPool(connect), driver: pgDatabaseDriver(connect)` over Hyperdrive; host `bun`
-passes `bunAuthDatabase(sql)` and `bunDatabaseDriver(sql)` (or the bun:sqlite
-`Database` and `bunSqliteDriver(db)`), with `ipAddressHeaders:
+pgPool(connect), driver: pgDatabaseDriver(connect)` on both hosts (Hyperdrive on
+`cloudflare`, a `pg.Pool` on `bun`); host `bun` over SQLite passes the bun:sqlite
+`Database` and `bunSqliteDriver(db)`, with `ipAddressHeaders:
 ["x-mantle-client-ip"]`, which its entry sets from the socket.
 
 ### Local sign-in

package/docs/handbook/cloudflare/deploy-and-operate.md

@@ -16,7 +16,10 @@ pnpm exec wrangler deploy
 
 With dialect `postgres`, create the Hyperdrive config instead of the D1
 database (`pnpm exec wrangler hyperdrive create my-service --caching-disabled
---connection-string=…`) and copy its id into `hyperdrive[0].id`.
+--connection-string=…`) and copy its id into `hyperdrive[0].id`. Give the
+role a statement limit and UTC, which boot checks (`ALTER ROLE app SET
+statement_timeout = '10s'; ALTER ROLE app SET TimeZone = 'UTC'`); the boot
+error names any other setting to change.
 
 Set `PUBLIC_ORIGIN` in `wrangler.jsonc` `vars` to the deployed origin, and
 replace the console email sender first