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

package/docs/handbook/concepts/runtime-and-adapters.md

@@ -103,13 +103,28 @@ dialect, and boot refuses a plan compiled for another one.
 PostgreSQL (13 or later). On Cloudflare, `mantle generate --dialect postgres`
 writes the preset over Hyperdrive; on any other platform, add `"host": "none"`
 and compose `createMantle` with `postgresStorage` yourself (ADR-0036). PostgreSQL
-is Mantle SQL's reference dialect (ADR-0037): it accepts D1's subset without
-SQLite's own `typeof`, `hex`, `json_extract`, `json_set`, `json_insert` and
-`json_remove` (write `x ->> '$.path'`), plus `WITH`, set operations, `LATERAL`,
-window frames, `FILTER`, jsonb operators and the rest of the
-[View reference](../reference/view.md)'s PostgreSQL table. A manifest that uses
-them no longer compiles for D1; one that does not moves between engines with a
-recompile.
+is Mantle SQL's reference dialect (ADR-0037), and its SQL is PostgreSQL's own
+(ADR-0039): Mantle lowers nothing to imitate SQLite. It accepts D1's subset except
+SQLite's own vocabulary (below), plus `WITH`, set operations, `LATERAL`, window
+frames, `FILTER`, jsonb operators and the rest of the
+[View reference](../reference/view.md)'s PostgreSQL table. A manifest targets one
+dialect: it need not compile for D1 or return the same values there. D1 to
+PostgreSQL is a migration (export, rewrite the SQL, import), not a switch.
+
+A SQLite spelling fails validation with its position and the PostgreSQL one:
+
+| SQLite (D1) | PostgreSQL |
+|---|---|
+| `FROM t, json_each(t.col) j`, `j.value` | `FROM t, jsonb_array_elements_text(t.col) WITH ORDINALITY AS j(value, n)` (`jsonb_array_elements` for jsonb values, `jsonb_each_text(t.col) WITH ORDINALITY AS j(key, value, n)` for an object) |
+| `ORDER BY …, j.id` of `json_each` | `WITH ORDINALITY AS j(value, n)`, then `ORDER BY …, j.n` (a sorted View over a row source needs `WITH ORDINALITY`; Mantle pages by it) |
+| `x ->> '$.a.b'`, `x ->> '$[0]'` | `x #>> '{a,b}'`, `x ->> 'a'`, `x ->> 0` (a `$…` string is refused: PostgreSQL would read it as a key) |
+| `json_extract(x, '$.a')` | `x ->> 'a'` (text) or `x -> 'a'` (jsonb) |
+| `json_remove(x, '$.a')` | `x - 'a'` |
+| `json_set`, `json_insert` | build the value with `jsonb_build_object` or `jsonb_build_array` |
+| `CAST(n AS bool)` of an integer | `n <> 0` (PostgreSQL has no bigint to boolean cast; `CAST('true' AS bool)` is unchanged) |
+| `2 * 3 \|\| 4` (text by any type) | `2 * 3 \|\| '4'`, or `CAST(n AS text) \|\| …`: `\|\|` needs a text operand |
+| `hex(x)`, `typeof(x)` | no equivalent on the allowlist; refused |
+| `NULL` first when ascending | `NULL` last when ascending (PostgreSQL's; say `NULLS FIRST` to override) |
 
 - Columns have native types: `timestamptz`, `date`, `numeric(p, s)`, `boolean`,
   `jsonb`, `bigint` and `double precision`. Values are decoded by the type
@@ -120,26 +135,39 @@ recompile.
   concurrent writers as it does on SQLite's single writer.
 - `checks` are `CHECK` constraints added `NOT VALID`: they bind every later
   write and leave older rows alone, like D1's triggers.
-- `json_each`, `->>` and `CAST(x AS bool)` read as they do on D1 through small
-  SQL functions Mantle creates (`_mantle_json_each`, `_mantle_jget`,
-  `_mantle_bool`). `json_group_array` and `json_group_object` order by value.
-- Results match D1 where Mantle decides them. Text columns use `COLLATE "C"`,
-  so they compare by code point. An `ORDER BY` key without `NULLS FIRST/LAST`
-  puts NULL first ascending, as Core pages every View. Values never depend on
+- `->>`, `||`, `CAST` and the jsonb row sources mean what PostgreSQL says; the
+  only SQL function Mantle creates is `_mantle_expect`. A database booted by an
+  earlier release keeps its `_mantle_jget`, `_mantle_bool` and `_mantle_json_each`
+  unused. `json_group_array` and `json_group_object` order by value.
+- Text columns use `COLLATE "C"`, so they compare by code point. An `ORDER BY` key without `NULLS FIRST/LAST`
+  sorts NULL as PostgreSQL does: last ascending, first descending (D1 puts it
+  first ascending). The `id` tiebreak follows the last key's direction, so an
+  index on the sort keys (and the `updated_at` index Mantle creates) serves a
+  paged sort. This is PostgreSQL's default for every `ORDER BY`, window and
+  aggregate (`json_group_array`) ones included. Values never depend on
   the server's `DateStyle`, `IntervalStyle` or `TimeZone`. Elsewhere the meaning
   is PostgreSQL's, where D1 differs:
   - `LIKE` is case-sensitive.
   - Division by zero is an error.
   - `->>` returns text.
-  - `||` prints booleans and floats as PostgreSQL does.
 - `searchableFields` and `mantle.near()` scan without an index in 0.2.0, and
   `mantle.search_rank()` counts occurrences rather than computing bm25.
   Site settings and media are SQLite-only (D1, bun:sqlite).
 - `date_trunc` and `extract` compute in the site time zone
   (`postgresStorage({ connect, timeZone })`, default UTC).
-- Every statement has a `statement_timeout` of 10 seconds, pinned in each
-  transaction (`statementTimeoutMs`; 0 is none). Storage convergence has none.
-  A statement past it fails with `RESOURCE_UNAVAILABLE` and writes nothing.
+- Every statement has a `statement_timeout` of at most 10 seconds
+  (`statementTimeoutMs`; 0 is none). A write batch sets it on its transaction.
+  A read is one statement outside a transaction, under the role's own
+  `statement_timeout`, so boot requires the role to have one no larger
+  (`ALTER ROLE app SET statement_timeout = '10s'`). Storage convergence has
+  none. A statement past it fails with `RESOURCE_UNAVAILABLE` and writes nothing.
+- Boot reads the role's settings once and refuses to start, naming the
+  `ALTER ROLE … SET` to run, unless `DateStyle` is ISO, `IntervalStyle` is
+  `postgres`, `extra_float_digits` is at least 1, `standard_conforming_strings`
+  is on and `TimeZone` is UTC (date and instant casts in your SQL use the
+  session's zone). These are PostgreSQL's defaults, except a server initialized
+  in another time zone. Mantle sets nothing per session, because
+  Hyperdrive resets every pooled session to the role's configuration.
 - Connect as a role that owns the service's tables but is not a superuser and
   holds no file or server privilege (`pg_read_server_files`,
   `pg_execute_server_program`). Mantle's allowlist refuses such functions; the
@@ -151,40 +179,53 @@ recompile.
 |---|---|---|
 | `d1Storage(env.DB, { timeZone?, site? })` | `@aotter/mantle/cloudflare` | Cloudflare D1, the one the preset uses |
 | `sqliteStorage(driver, { timeZone?, maxBindings?, site?, restrict? })` | `@aotter/mantle/d1` | any `DatabaseDriver`: `{ batch(statements) }`, all or nothing |
-| `postgresStorage({ connect, timeZone?, statementTimeoutMs?, restrict? })` | `@aotter/mantle/postgres` | `connect` opens one node-postgres (`pg`) client; Hyperdrive on Workers |
-| `bunPostgresStorage(sql, { timeZone?, statementTimeoutMs?, restrict? })` | `@aotter/mantle/bun` | a Bun.SQL pool with `prepare: false`; its role needs TEMPORARY (ADR-0038) |
+| `postgresStorage({ connect, timeZone?, statementTimeoutMs?, restrict? })` | `@aotter/mantle/postgres` | `connect` opens one node-postgres (`pg`) client: Hyperdrive on Workers, a `pg.Pool` on Bun (ADR-0039) |
 | `bunSqliteStorage(db, { timeZone?, site?, restrict? })` | `@aotter/mantle/bun` | a bun:sqlite `Database`; foreign keys are turned on |
 
 `restrict(plan, context)` returns refusals of its own, run after the dialect's
 on every program at runtime. It only narrows what runs, for an operator that
 runs other people's plans; a self-hosted service leaves it out (ADR-0037).
 
-On Workers, PostgreSQL goes through Hyperdrive, which pools the connections, so
-`connect` opens a client per operation (a socket must not outlive its request):
+On Workers, PostgreSQL goes through Hyperdrive, which pools the connections.
+`connect` opens one client, and `requestScoped` makes it one per request: every
+query of a request (Store, Better Auth, auth SQL) reuses it, and it is ended
+when the request ends, as a Worker's socket must be. Outside `run` (boot,
+schedules) each operation opens its own:
 
 ```ts
 import pg from "pg";
-import { pgDatabaseDriver, pgPool, postgresStorage } from "@aotter/mantle/postgres";
+import { pgDatabaseDriver, pgPool, postgresStorage, requestScoped, type PgSession } from "@aotter/mantle/postgres";
 
-const connect = (env: Env) => async () => {
+// one per isolate: every consumer must share it
+let session: PgSession | undefined;
+const database = (env: Env) => (session ??= requestScoped(async () => {
   const client = new pg.Client({ connectionString: env.HYPERDRIVE.connectionString });
   await client.connect();
   return client;
-};
-// storage: (env) => postgresStorage({ connect: connect(env) })
-// identity: createMantleAuth({ database: pgPool(connect(env)), driver: pgDatabaseDriver(connect(env)), ... })
+}));
+// storage: (env) => postgresStorage({ connect: database(env).connect })
+// identity: createMantleAuth({ database: pgPool(database(env).connect), driver: pgDatabaseDriver(database(env).connect), ... })
+// fetch: (request, env, ctx) => database(env).run(() => routes(request))
 ```
 
-The Worker needs `compatibility_flags: ["nodejs_compat"]` for `pg`. Mantle runs
-every read in a transaction, which Hyperdrive never answers from its cache.
-Better Auth's reads (sessions, roles) do not, so create the Hyperdrive config
-with caching disabled (`wrangler hyperdrive create … --caching-disabled`), or a
-revoked session can be accepted until the cache expires. `timeZone` must be an
+One operation holds the shared client from `connect()` to `end()`; another that
+arrives meanwhile opens its own, so nothing runs inside another's transaction.
+With `new pg.Client({ …, pipeline: true })` (pg 8.23 or later) a write batch is
+one round trip instead of N + 2; the generated Workers preset leaves it off
+until Hyperdrive is verified to forward a pipelined transaction.
+
+The Worker needs `compatibility_flags: ["nodejs_compat"]` for `pg`. Mantle's
+and Better Auth's reads run outside a transaction, which Hyperdrive would answer
+from its cache, so create the Hyperdrive config with caching disabled
+(`wrangler hyperdrive create … --caching-disabled`), or a read can miss the
+write before it and a revoked session can be accepted until the cache expires. The same holds for a role
+re-read and for a revoked grant: Auth's reads are single statements outside a transaction, so their freshness
+depends on `--caching-disabled` too. `timeZone` must be an
 IANA name: PostgreSQL reads an offset such as `+08:00` with the opposite sign.
 
 Bun has a generated preset for both engines (`mantle generate --host bun`,
-ADR-0038); `bunDatabaseDriver` / `bunAuthDatabase` and `bunSqliteDriver` give
-Better Auth the same store. A `DatabaseDriver` is one method, so another engine
+ADR-0038, ADR-0039): over PostgreSQL it is the Workers composition on a `pg.Pool`;
+over SQLite `bunSqliteDriver` gives Better Auth the same store. A `DatabaseDriver` is one method, so another engine
 (libSQL, for example) is a few lines of application code on `host: none`: the
 entry calls `createMantle` and its own server.
 

package/docs/handbook/concepts/views.md

@@ -33,7 +33,7 @@ has the full table):
   integer literals: use `round(x)`), JSON `->>`;
 - `WHERE` with comparisons, `BETWEEN`, `IN (list | subquery)`, `EXISTS`,
   `LIKE` (case-insensitive, as in SQLite), `IS DISTINCT FROM`;
-- `INNER` and `LEFT JOIN`, subqueries, `json_each(…)`;
+- `INNER` and `LEFT JOIN`, subqueries, `json_each(…)` on D1 (PostgreSQL: `jsonb_array_elements_text(…) WITH ORDINALITY AS j(value, n)`);
 - `GROUP BY`, `HAVING`, `count`, `sum`, `min`, `max`, `avg`,
   `json_group_array`, `json_group_object`; `row_number()`, `rank()` and running
   aggregates;

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

@@ -0,0 +1,191 @@
+---
+description: Add your own pages, settings, actions, record panels and field widgets to Admin in 0.2.0, bind them from manifest uiSchema, and verify them.
+---
+# Extend Admin
+
+Manifests decide most of what Admin shows ([Customize Admin from
+manifests](admin-ui.md)). When a project needs UI of its own, it adds an
+**Admin extension**: a declaration that is plain data, server handlers, and
+optionally one ES module with renderers. The contract is
+[ADR-lite 1376](../../adr/adr-lite-1376-admin-extensions.md).
+
+For a new project with feature `admin`, the preset writes
+`src/admin-extensions.ts` (yours to edit) and passes its `adminExtensions` to
+`createAdminSurface`. The preset is written once: when `src/service.ts`
+already exists, `mantle generate` leaves it alone, so add the file and
+`extensions: adminExtensions` to your `createAdminSurface` call yourself.
+
+## What you can add
+
+| Contribution | Where it appears | Client code |
+|---|---|---|
+| `pages` | `/admin/x/{extension}/{page}`; in **More** when it declares `nav` | a renderer |
+| `settings` | `/admin/x/{extension}/{id}`, always in **More** | none: Admin renders a form from `schema`, which must be the form subset (a flat object whose properties are `string`, `number`, `integer` or `boolean`, with `title`, `description`, `default`, `enum`, `oneOf`, `minimum`, `maximum`, `minLength`, `maxLength`) |
+| `actions` | `record/v1` (a record's header), `list.selection/v1` (the bulk bar), `list.toolbar/v1` (a list's toolbar) | none for `run` and `confirm` (a server `run`); a renderer for `dialog` |
+| `panels` | `record.sidebar/v1` (a record's side column), `home/v1` (the home page) | a renderer |
+| `fields` | `field.input/v1` (a form control), `field.cell/v1` (a list cell) | a renderer |
+
+Pages, settings, actions and panels need a minimum staff `role`; a field
+widget's `role` is optional and defaults to `contributor` (below it, Admin's
+own control is used). The server sends each staff member only the
+contributions their role reaches, and checks the session and role again on
+every extension route: hiding a button is never the only guard.
+
+- A settings page and an action are checked against their own `role`.
+- The extension's `api` and its served `source` are shared by all its
+  contributions, so they need only the **lowest** role among them: an owner-only
+  page does not make the `api` owner-only.
+
+Finer rules belong in your handlers, which receive the caller.
+
+## A complete extension
+
+```ts
+// src/admin-extensions.ts
+import type { AdminExtension } from "@aotter/mantle/admin";
+
+const brand: AdminExtension = {
+  apiVersion: 1,
+  id: "brand",
+  title: { en: "Brand", "zh-TW": "品牌" },
+  // Admin serves this at /admin/extensions/brand.js, with its integrity computed
+  source: BRAND_MODULE,
+  contributes: {
+    pages: [{ id: "palette", title: "Palette", role: "editor", nav: { group: "more" } }],
+    settings: [{ id: "defaults", title: "Brand defaults", role: "owner", schema: {
+      type: "object", required: ["accent"],
+      properties: { accent: { type: "string", title: "Accent", enum: ["teal", "navy"] }, limit: { type: "integer", minimum: 1, maximum: 20 } },
+    } }],
+    actions: [{ id: "reindex", title: "Re-index colors", role: "editor", target: "record/v1", presentation: "confirm", when: { schema: ["products"] } }],
+    panels: [{ id: "usage", title: "Where it is used", role: "contributor", target: "record.sidebar/v1", when: { schema: ["products"] } }],
+    fields: [
+      { id: "color", target: "field.input/v1", optionsSchema: { type: "object", properties: { palette: { type: "string", enum: ["brand", "web"] } } } },
+      { id: "swatch", target: "field.cell/v1" },
+    ],
+  },
+  handlers: {
+    settings: { defaults: { load: async () => ({ accent: "teal" }), save: async (_caller, value) => value } },
+    actions: { reindex: { run: async (caller, { record }) => ({ message: `Re-indexed ${record!.id}` }) } },
+    // GET/POST /admin/api/x/brand/api/{path}; null answers 404
+    api: async (request, { caller, path }) => (path === "usage" ? Response.json({ count: 3 }) : null),
+  },
+};
+
+export const adminExtensions: readonly AdminExtension[] = [brand];
+```
+
+`source` is the module's code (or a function returning it). How you load the
+text is up to your host: a string constant, a Wrangler `Text` module rule, or
+Bun's `with { type: "text" }` import. A host that serves the file itself sets
+`module: "/path.js"` (same-origin) and optionally `integrity` instead.
+
+## The module
+
+The module needs no build step. Admin's import map provides `react`,
+`react/jsx-runtime`, `react-dom`, `react-dom/client`,
+`@aotter/mantle-ui/kit` and `@aotter/mantle-ui/extension`, so the module
+uses Admin's own React and kit and looks like the rest of Admin. If you do
+bundle it, mark those specifiers external.
+
+```js
+import { jsx } from "react/jsx-runtime";
+import { useEffect, useState } from "react";
+import { createRoot } from "react-dom/client";
+import { Badge, Input } from "@aotter/mantle-ui/kit";
+import { defineAdminExtension } from "@aotter/mantle-ui/extension";
+
+// a renderer gets an element and a context; it may return a cleanup or { update, unmount }
+const react = (Component) => (element, context) => {
+  const root = createRoot(element);
+  root.render(jsx(Component, { context }));
+  return { update: (next) => root.render(jsx(Component, { context: next })), unmount: () => root.unmount() };
+};
+
+function Usage({ context }) {
+  const [count, setCount] = useState(null);
+  useEffect(() => { fetch(`${context.apiBase}/usage`).then((r) => r.json()).then((b) => setCount(b.count)); }, [context.apiBase]);
+  return jsx(Badge, { children: count === null ? "…" : `${count} pages` });
+}
+function Color({ context }) {
+  return jsx(Input, { "aria-label": context.field.name, value: String(context.field.value ?? ""), onChange: (e) => context.onChange(e.target.value) });
+}
+
+export default defineAdminExtension({
+  pages: { palette: react(() => jsx("p", { children: "Palette" })) },
+  panels: { usage: react(Usage) },
+  fields: {
+    color: react(Color),
+    swatch: (element, context) => { element.textContent = `■ ${context.field.value ?? ""}`; },
+  },
+});
+```
+
+The context holds `extension`, `contribution`, `apiBase` (your `api`
+handler), `language`, `theme`, `caller.role`, and where it applies `record`
+(`{ schema, id, version }`), `selection`, `schema`, `field`, `options` and,
+for `field.input/v1`, `onChange`. `host.navigate(path)`, `host.notify(text)`
+and `host.close()` (a dialog action) are the supported console API. They are
+not a sandbox: a module is trusted same-origin code and can still reach the
+DOM, `fetch` and whatever the signed-in session may do (see Trust).
+
+## Bind contributions from manifests
+
+A manifest's `uiSchema` can name a project contribution as
+`<extension>/<contribution>`. The binding sits next to the field it changes,
+so one change (and one review) covers both:
+
+```yaml
+apiVersion: cms.mantle.aotter.net/v2
+kind: Schema
+metadata: { name: products }
+spec:
+  title: Products
+  lifecycle: operational
+  uiSchema:
+    fields:
+      color: { widget: brand/color, options: { palette: brand } }
+    list:
+      columns: [color]
+      cells: { color: brand/swatch }
+    panels: [brand/usage]
+  schema:
+    type: object
+    required: [name]
+    properties:
+      name: { type: string }
+      color: { type: string }
+```
+
+- `fields.<name>.widget` names a `field.input/v1` contribution (any field type);
+  `options` must satisfy its `optionsSchema`.
+- `list.cells.<field>` (Schemas, and staff Views by output name) names a
+  `field.cell/v1` contribution.
+- `panels` (Schemas) names `record.sidebar/v1` contributions.
+- Procedure `uiSchema.fields.<name>.widget` works like a Schema's.
+
+`mantle generate` checks the shape of the names. `createAdminSurface` checks
+that each named contribution exists, has the right target and accepts its
+`options`, and refuses to start otherwise (`UI_EXTENSION_UNKNOWN`,
+`UI_EXTENSION_TARGET`, `UI_EXTENSION_OPTIONS`). Name only your project's own
+extensions, so the project renders the same locally and deployed; a host that
+adds extensions attaches them with `when`. Core checks that a name exists, not
+whose extension it is. When a manifest names a widget for a field (even
+`textarea`), a matching `when` does not replace it. `uiSchema` stays presentation only: the field's JSON Schema
+still validates whatever a widget sends.
+
+## Trust
+
+An extension's module runs in Admin's origin with the viewer's session. It
+has no more power than the project already has: whoever deploys the project
+already controls its handlers and storage. Keep host routes that act beyond
+this project (an organization console, other projects) on another origin.
+
+## Verify
+
+- `createAdminSurface` validates every declaration at start
+  (`UI_EXTENSION_INVALID` names the first problem).
+- `ADMIN_EXTENSION_JSON_SCHEMA` (from `@aotter/mantle/admin`) describes a
+  declaration for tooling; `diffAdminExtensions(before, after)` lists added,
+  removed and changed contributions for review.
+- Sign in as each role and check what appears; call
+  `/admin/api/x/{extension}/...` as a lower role and expect 403.

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

@@ -25,7 +25,8 @@ same files with `bunAdminAssets` from `@aotter/mantle/bun`. Sign in at
 | Rename a collection or explain a field | Schema `title` / `description`, property `title` / `description` (a string or a locale map) | Labels and help. Stored names do not change |
 | Required fields and option lists | JSON Schema `required`, `enum`, `type` | Data contracts, checked on every write, not styling |
 | Option labels | a string property's `oneOf: [{ const: open, title: { en: Open, zh-TW: 處理中 } }, …]` instead of `enum` | Selects, filter tabs and list cells show the `title` |
-| A multiline string | Schema or Procedure `uiSchema.fields.<name>.widget: textarea` | `textarea` is the only explicit widget |
+| A multiline string | Schema or Procedure `uiSchema.fields.<name>.widget: textarea` | `textarea` is the only built-in explicit widget |
+| Your own control, list cell or record panel | `uiSchema.fields.<name>.widget: <extension>/<contribution>`, `uiSchema.list.cells`, `uiSchema.panels` | Contributions of the project's Admin extensions; see [Extend Admin](admin-extensions.md) |
 | Markdown or HTML | property `x-mcp-hint: markdown` or `html` | A rich editor |
 | A timestamp, a date or money | `format: date-time`, `format: date`; `x-mcp-hint: money-minor` on an integer | Date controls; money in minor units, with a sibling `currency` when present |
 | Columns of an operational list | Schema `uiSchema.list.primaryField`, `.columns` | `primaryField` is a scalar data field; `columns` may name native columns (`createdAt`, `updatedAt`) |

package/docs/handbook/navigation.json

@@ -14,7 +14,8 @@
       "items": [
         { "text": "Agent installation and handoff", "link": "/guides/agent-setup" },
         { "text": "Query from TypeScript", "link": "/guides/typed-queries" },
-        { "text": "Customize Admin from manifests", "link": "/guides/admin-ui" }
+        { "text": "Customize Admin from manifests", "link": "/guides/admin-ui" },
+        { "text": "Extend Admin", "link": "/guides/admin-extensions" }
       ]
     },
     {

package/docs/handbook/reference/diagnostics.md

@@ -69,6 +69,7 @@ Admin's statistics route answers 501 with the wire code
 | `INVALID_MANIFEST_ENVELOPE`, `DUPLICATE_NAME`, `MANIFEST_ROOT_NOT_FOUND`, `MANIFEST_READ_FAILED` | files and the envelope; a `v1` apiVersion fails here and names the upgrade guide; `x-mantle-bind` fails and names its replacements (`spec.scope`, `auth.uid()`, `now()`) |
 | `REQUIRED_FIELD_UNKNOWN`, `INVALID_PATTERN`, `JSON_SCHEMA_UNSUPPORTED`, `JSON_SCHEMA_REF_INVALID`, `JSON_SCHEMA_LIMIT_EXCEEDED` | JSON Schemas |
 | `SCHEMA_INDEX_INVALID`, `SCHEMA_INDEX_FIELD_UNKNOWN`, `UNIQUE_INDEX_FIELD_UNKNOWN`, `SCHEMA_SEARCH_INVALID`, `SCHEMA_SEARCH_FIELD_UNKNOWN`, `SCHEMA_TTL_INVALID`, `SCHEMA_TTL_TRANSLATION_UNSUPPORTED`, `SCHEMA_UI_INVALID`, `SCHEMA_NAME_CASE_COLLISION`, `FIELD_NAME_CASE_COLLISION`, `MANTLE_REF_INVALID` | Schemas |
+| `UI_EXTENSION_INVALID`, `UI_EXTENSION_UNKNOWN`, `UI_EXTENSION_TARGET`, `UI_EXTENSION_OPTIONS` | Admin extensions, at `createAdminSurface`: a declaration it cannot honor, and a `uiSchema` contribution name that is missing, of the wrong target, or given options its `optionsSchema` refuses |
 | `TRANSLATES_PARENT_UNKNOWN`, `TRANSLATES_REQUIRES_LOCALIZED`, `TRANSLATES_REQUIRES_CONTENT_FIELD`, `TRANSLATES_FIELD_NOT_IN_PARENT`, `TRANSLATES_FIELD_NOT_IN_CHILD`, `TRANSLATES_PARENT_IS_LOCALIZED` | `translates` |
 | `VIEW_INPUT_INVALID_SHAPE`, `VIEW_INPUT_RESERVED_NAME`, `VIEW_CACHE_INVALID`, `VIEW_UI_INVALID` | Views |
 | `SQL_SYNTAX`, `SQL_UNSUPPORTED`, `SQL_FUNCTION`, `SQL_RELATION`, `SQL_COLUMN`, `SQL_WRITE`, `SQL_SHAPE`, `SQL_TYPE` | View and Procedure SQL, with a position |

package/docs/handbook/reference/procedure.md

@@ -44,7 +44,7 @@ References: `input.<name>`, `auth.uid()`, `auth.role()`, `now()`.
 `updated_at`, `author_id`, or `id` in an `UPDATE`, in a column list, `SET` or
 `DO UPDATE SET`; on a scoped Schema an `INSERT` names no `id`. Store fills
 them (`SQL_WRITE`). Multi-row `VALUES` is refused: insert from
-`json_each(input.items)` instead. `UPDATE … FROM`, `DELETE … USING`,
+`json_each(input.items)` on D1 instead (PostgreSQL: `jsonb_array_elements(input.items)`). `UPDATE … FROM`, `DELETE … USING`,
 `INSERT OR …` and `last_insert_rowid()` are refused.
 
 **RETURNING names** fold to lower case unless quoted:
@@ -109,6 +109,7 @@ handler, which always writes, may not claim `readOnlyHint: true`.
 | Key | Effect in Admin |
 |---|---|
 | `fields.<name>.widget: textarea` | a multiline input |
+| `fields.<name>.widget: <extension>/<contribution>` (with optional `options`) | an Admin extension's `field.input/v1` control ([Extend Admin](../guides/admin-extensions.md)) |
 | `collectionAction: <schema>` | offer the operation on that collection's list |
 
 Admin lists a Procedure as an operation only when a Trigger binds it to the

package/docs/handbook/reference/schema.md

@@ -43,7 +43,7 @@ insert and when a draft is published; a draft may be saved incomplete.
 | `type: integer` | `INTEGER` | `int8` | |
 | `type: number` | `REAL` | `float8` | |
 | `type: boolean` | integer 0/1 | `bool` | `true`/`false` on the wire |
-| `type: object`, `type: array` | JSON | `jsonb` | read with `->>` or `json_each` in SQL |
+| `type: object`, `type: array` | JSON | `jsonb` | read with `->>` in SQL, or `json_each` on D1 (PostgreSQL: `jsonb_array_elements_text(…) WITH ORDINALITY AS j(value, n)`) |
 | `format: geo` | two `REAL` columns and an R*Tree | two `float8` columns | `{ lat, lng }`; query with `mantle.near` and `mantle.distance` |
 
 ### Reserved entry columns
@@ -181,14 +181,17 @@ Admin presentation only; it never changes validation or MCP.
 
 | Key | Values |
 |---|---|
-| `fields.<name>.widget` | `textarea` |
+| `fields.<name>.widget` | `textarea` (a string field), or `<extension>/<contribution>`: an Admin extension's `field.input/v1` control, for any field type |
+| `fields.<name>.options` | with an extension widget only: an object checked against the contribution's `optionsSchema` |
 | `list.primaryField` | a scalar data field shown first (operational Schemas) |
 | `list.columns` | data fields and native columns, in order (operational Schemas) |
+| `list.cells` | data field or native column -> `<extension>/<contribution>`, an Admin extension's `field.cell/v1` renderer |
+| `panels` | up to 16 `<extension>/<contribution>` names: Admin extension `record.sidebar/v1` panels on the record page |
 | `list.filterField` | a string enum field that leads an index: tabs per value (operational Schemas) |
 | `nav.standalone` | `true`: also list a folded child in navigation |
 | `nav.parentField` | which `x-mantle-ref` field filters it, when several could |
 
-Other keys are refused (`SCHEMA_UI_INVALID`).
+Other keys are refused (`SCHEMA_UI_INVALID`). A contribution name is checked for shape here; whether it exists, fits the key and accepts the `options` is checked when Admin starts ([Extend Admin](../guides/admin-extensions.md)).
 
 ## Diagnostics
 

package/docs/handbook/reference/surface.md

@@ -56,13 +56,17 @@ Every route needs a staff caller; the column names the least role.
 | `POST …/entries/{id}/publish`, `…/unpublish`, `DELETE …/entries/{id}` | editor | |
 | `GET /admin/api/views-manifest`, `GET …/views/{name}`, `GET …/views/{name}/export` | contributor | staff Views (`{ name, title, description, input, list: { columns, searchFields, filterFields }, columns }`); rows by `limit`/`cursor` with `search` and `filter.<output>`; CSV |
 | `GET /admin/api/operations`, `POST …/operations/{name}` | contributor | Procedures bound to the staff MCP surface |
-| `GET /admin/api/site` | contributor | site metadata, `mcpEndpoints`, and `capabilities: { siteSettings, media, invitationEmail, statistics }` (what this deployment turned on; the console hides what is off) |
+| `GET /admin/api/site` | contributor | site metadata, `mcpEndpoints`, `capabilities: { siteSettings, media, invitationEmail, statistics }` (what this deployment turned on; the console hides what is off), and `extensions` (the Admin extension declarations the caller's role reaches, never handlers or integrity) |
 | `GET`, `PATCH /admin/api/site-settings` | owner | 501 `SITE_NOT_CONFIGURED` without `runtime.site` |
 | `POST /admin/api/media/uploads`, `POST …/media/uploads/{groupId}/commit`, `GET …/media`, `GET`, `PATCH`, `DELETE …/media/{id}` | editor | with `media` and `runtime.site` |
 | `GET /admin/api/webmcp`, `POST …/webmcp/{tool}` | contributor | the staff tools for a browser agent (`{ tools, routes }`); a call runs one as `/mcp/staff` does and answers `{ output }` |
 | `GET /admin/api/staff`, `PATCH …/staff/{id}/role`, `POST …/staff/invitations`, `DELETE …/staff/invitations/{id}` | owner | with an `AdminIdentity` that has `directory` / `roles` |
 | `GET /admin/api/members` | editor | with `directory` |
 | `GET /admin/api/developer-console` | owner | the plan's data model, logic and schedules |
+| `GET`, `PATCH /admin/api/x/{extension}/settings/{id}` | the settings' `role` | load and save an extension's settings; `PATCH { value }` is checked against its `schema` (400 with `error.fields`) |
+| `POST /admin/api/x/{extension}/actions/{id}` | the action's `role` | run a `run` or `confirm` action with `{ record }`, `{ selection }` or `{ schema }` for its target; `when.schema` is enforced |
+| `… /admin/api/x/{extension}/api/{path}` | the extension's lowest contribution role | the extension's own API (`handlers.api`); `null` answers 404; answers are `no-store` unless the handler sets `cache-control` |
+| `GET /admin/extensions/{id}.js` | the extension's lowest contribution role | a `source` extension's module; its integrity is in the shell's import map ([Extend Admin](../guides/admin-extensions.md)) |
 
 ## Packages
 
@@ -79,7 +83,7 @@ Two npm packages, always published together at one version.
 | `@aotter/mantle/admin` | `createAdminSurface`, `AdminIdentity` |
 | `@aotter/mantle/mcp` | `createMcpSurface`, `planApp` and `appCatalog` (the MCP App's catalog) |
 | `@aotter/mantle/web` | `createRestSurface` |
-| `@aotter/mantle/bun` | `bunPostgresStorage`, `bunSqliteStorage`, `bunPgConnect`, `bunDatabaseDriver`, `bunSqliteDriver`, `bunAuthDatabase`, `bunAdminAssets` |
+| `@aotter/mantle/bun` | `bunSqliteStorage`, `bunSqliteDriver`, `bunAdminAssets` |
 | `@aotter/mantle/testing` | `runStorageConformance`, the dialect compliance suite |
 | `@aotter/mantle-ui` | the root (React operation components and the controller), `/controller`, `/kit`, `/kit.css`, `/tokens.css`, `/mcp-app` (`mantleAppHtml`, the App `planApp` serves), and the prebuilt Admin console in `dist/admin` (exported as `./admin/index.html`), which the preset serves at `/admin` |
 

package/docs/handbook/reference/view.md

@@ -38,13 +38,13 @@ SQLite and on any `sqliteStorage` driver.
 
 | Area | Supported | Rule |
 |---|---|---|
-| Expressions | columns, aliases, literals, arithmetic, `\|\|`, `CASE`, `COALESCE`, `NULLIF`, `CAST` | `CAST(x AS int)` only for an integer literal: use `round(x)`. `CAST(x AS bool)` follows PostgreSQL. `*` expands to declared fields; a bare `*` over a subquery or `json_each` is refused: name the columns |
+| Expressions | columns, aliases, literals, arithmetic, `\|\|`, `CASE`, `COALESCE`, `NULLIF`, `CAST` | `CAST(x AS int)` only for an integer literal: use `round(x)`. `CAST(x AS bool)` follows PostgreSQL's text rules; an integer has no cast to boolean on PostgreSQL: write `x <> 0`. `*` expands to declared fields; a bare `*` over a subquery or `json_each` is refused: name the columns |
 | Conditions | comparisons, `AND`/`OR`/`NOT`, `BETWEEN`, `IS [NOT] NULL`, `IS DISTINCT FROM`, `IN (list \| subquery)`, `[NOT] EXISTS`, `LIKE … ESCAPE` | `LIKE` is case-insensitive (SQLite). An input array in `IN` binds once. A date-time, date or boolean column (and `created_at`, `updated_at`) is not compared with a bare string: write `CAST('…' AS timestamptz)`, `true`, or bind an input |
-| Relations | one Schema, `INNER`/`LEFT JOIN … ON` (self-joins too), a subquery in `FROM`, `json_each(<input or column>)` | the only comma join is `t, json_each(t.col)` |
+| Relations | one Schema, `INNER`/`LEFT JOIN … ON` (self-joins too), a subquery in `FROM`, `json_each(<input or column>)` on D1; on PostgreSQL `jsonb_array_elements_text(<input or column>) WITH ORDINALITY AS j(value, n)` | the only comma join is `t, json_each(t.col)` on D1 (PostgreSQL: `t, jsonb_array_elements_text(t.col) WITH ORDINALITY AS j(value, n)`, [SQLite to PostgreSQL rewrites](../concepts/runtime-and-adapters.md#the-postgresql-dialect)) |
 | Subqueries | scalar and correlated | |
 | Aggregation | `count`, `sum`, `min`, `max`, `avg`, `count(DISTINCT)`, `json_group_array([DISTINCT])`, `json_group_object`, `GROUP BY`, `HAVING` | a selected column is grouped or aggregated |
 | Windows | `row_number()`, `rank()`, `sum`/`count … OVER (PARTITION BY … ORDER BY …)` | no frame clause |
-| Order and paging | `ORDER BY … [NULLS FIRST \| LAST]`, `LIMIT`, `DISTINCT` | `id` is appended as the last sort key; `LIMIT` needs `ORDER BY` and bounds every page together; a sort key may be NULL (an unstated `NULLS` puts NULL first ascending and last descending, and the cursor follows the same rule); `ORDER BY 1` sorts by the first output; `DISTINCT` with `ORDER BY` is refused. A View without `ORDER BY` (a `DISTINCT`, an aggregate, a `GROUP BY`) is one page: it takes no cursor and is refused when it has more rows than the page |
+| Order and paging | `ORDER BY … [NULLS FIRST \| LAST]`, `LIMIT`, `DISTINCT` | `id` is appended as the last sort key (on PostgreSQL in the last key's direction); `LIMIT` needs `ORDER BY` and bounds every page together; a sort key may be NULL (an unstated `NULLS` follows the dialect: D1 puts NULL first ascending and last descending, PostgreSQL last ascending and first descending, and the cursor follows the same rule); `ORDER BY 1` sorts by the first output; `DISTINCT` with `ORDER BY` is refused. A View without `ORDER BY` (a `DISTINCT`, an aggregate, a `GROUP BY`) is one page: it takes no cursor and is refused when it has more rows than the page |
 | JSON | `->>`, `json_extract`, `json_set`, `json_insert`, `json_remove`, `json_array_length` | `->` is refused |
 | Time | `now()`, `date_trunc('hour'\|'day'\|'week'\|'month'\|'year', ts)`, `extract(year\|month\|day\|dow\|hour FROM ts)`, `ts ± interval '<n> seconds\|minutes\|hours'`, `ts - ts` | site time zone; `ts - ts` is microseconds. Calendar intervals (`day`, `month`) are refused: bind the boundary as an input |
 | Search and places | `mantle.search(t, q)`, `mantle.search_rank(t)`, `mantle.near(t.f, lat, lng, meters)`, `mantle.distance(t.f, lat, lng)` | `near` takes a literal radius of at most 50 km; ordering by `distance` needs `LIMIT` ≤ 100 and has no cursor |
@@ -78,8 +78,9 @@ On PostgreSQL a View may also use:
 | Time | `ts AT TIME ZONE 'Asia/Taipei'`; `date_trunc` adds `minute` and `quarter`; `extract` adds `minute`, `quarter`, `week`, `isoyear`, `isodow`, `doy`, `epoch` |
 | Casts | any expression to `int4`, `int8`, `numeric(p, s)`, `date`, `timestamptz`, `jsonb`; a text literal compared with a date-time column is cast, as PostgreSQL does |
 
-Every statement on PostgreSQL has a 10-second `statement_timeout`
-(`postgresStorage({ statementTimeoutMs })`).
+Every statement on PostgreSQL has a `statement_timeout` of at most 10 seconds
+(`postgresStorage({ statementTimeoutMs })`); a View runs under the role's own,
+which boot requires to be set and no larger.
 
 ### Reading another View
 
@@ -136,6 +137,7 @@ REST coerces each `input` query parameter to its declared type.
 | `list.columns` | the outputs the console shows, in order; CSV export uses them |
 | `list.searchFields` | outputs the console's search box matches: one case-insensitive `LIKE '%text%'` per output, ORed, with `%`, `_` and `\` in the text matched literally |
 | `list.filterFields` | outputs the console offers as filters: one `=` each, the value coerced to the output's field type |
+| `list.cells` | output -> `<extension>/<contribution>`: an Admin extension's `field.cell/v1` renderer for that column ([Extend Admin](../guides/admin-extensions.md)) |
 
 Each name must be one of the View's outputs (`VIEW_UI_INVALID` otherwise).
 The conditions wrap the View's own query, after its `WHERE` and the injected

package/docs/handbook/releases/index.md

@@ -28,9 +28,10 @@ by hand.
   Procedures are SQL statements or a `ref`, in PostgreSQL syntax. The builtin
   handlers, the Filter AST, `params`, `$ctx` references and `x-mantle-bind` are
   gone; Schemas gain `checks`, and `searchableFields` becomes full-text search.
-- **SQL in PostgreSQL syntax.** PostgreSQL is the reference dialect
+- **SQL in the dialect's syntax.** PostgreSQL is the reference dialect
   (`@aotter/mantle/postgres`); D1 and SQLite run a subset
-  (`@aotter/mantle/d1`). A plan records its dialect.
+  (`@aotter/mantle/d1`). Each dialect is its own target (ADR-0039), and a
+  plan records its dialect.
 - **One Store.** Every read and write goes through Store, which adds caller
   scope, TTL and published-only to every statement, and an optimistic lock
   where the caller passes one; a write
@@ -38,8 +39,8 @@ by hand.
 - **The service is the application's.** `createMantle(service, …)` replaces
   `createMantleWorker`, and the first `mantle generate` writes the host's
   preset (`src/service.ts`, `src/index.ts`, ...) once. `--host` is
-  `cloudflare` (D1, or PostgreSQL through Hyperdrive), `bun` (Bun.SQL or
-  bun:sqlite, `@aotter/mantle/bun`) or `none` (plan and types only), and
+  `cloudflare` (D1, or PostgreSQL through Hyperdrive), `bun` (node-postgres
+  or bun:sqlite, `@aotter/mantle/bun`) or `none` (plan and types only), and
   `--dialect` is `sqlite` or `postgres`; both are chosen once.
 - **Mantle never owns your users.** A `CallerResolver` turns a request into a
   `Caller`; identity is `mantle` (Better Auth), `custom` or `none`. Core creates
@@ -64,6 +65,79 @@ by hand.
 - **Not yet in 0.2.0:** Mantle-rendered public pages and the MCP interaction
   App tools.
 
+### Upgrading an existing PostgreSQL service (0.2.0-alpha.6)
+
+PostgreSQL is native from this alpha (ADR-0039): each dialect is its own target,
+PostgreSQL's SQL and ordering are PostgreSQL's, and node-postgres (`pg`) is the
+PostgreSQL driver on every host. D1 and SQLite output is unchanged except where
+noted. Work through these in order before deploying.
+
+1. **Role settings (from #1383, now also checked on Bun).** Boot refuses with
+   `STORAGE_CHANGE_BLOCKED` (path `storage:settings`) unless the role Mantle
+   connects as has a statement limit and UTC:
+   `ALTER ROLE app SET statement_timeout = '10s'; ALTER ROLE app SET TimeZone = 'UTC';`
+   (10s or less). Bun's `Bun.SQL` entry used to pin its own limit and skip this
+   check. A Hyperdrive config must keep `--caching-disabled`: reads, role
+   re-reads and grant revocations run outside a transaction.
+2. **Rewrite SQLite spellings, then run `mantle generate`.** A PostgreSQL
+   manifest that uses `json_each`, `-> '$.a'`, `->> '$.a'`, `json_extract`,
+   `json_set`, `json_insert`, `json_remove` or `hex` fails validation with its
+   position and the PostgreSQL spelling. The
+   [rewrite table](../concepts/runtime-and-adapters.md#the-postgresql-dialect)
+   lists them: `json_each(t.col) j` becomes
+   `jsonb_array_elements_text(t.col) WITH ORDINALITY AS j(value, n)` (a sorted
+   View over a row source needs the alias and `WITH ORDINALITY`, and `j.id`
+   becomes `j.n`), `CAST(n AS bool)` of an integer becomes `n <> 0`, and `||`
+   needs a text operand. The PostgreSQL dialect version is now 2, so a plan
+   compiled earlier fails at boot with `PLAN_FINGERPRINT_MISMATCH`: run
+   `mantle generate` and deploy the regenerated plan.
+3. **NULL order.** Unstated `NULLS` now follows PostgreSQL: NULL last ascending,
+   first descending, for every `ORDER BY` including windows and
+   `json_group_array`. Write `NULLS FIRST` or `NULLS LAST` to keep a specific
+   order. Rows tied on the last sort key are ordered by `id` in that key's
+   direction. A cursor live across the deploy may repeat or skip rows once.
+4. **Bun entry.** Install `pg` and `@types/pg`. Replace
+   `new SQL(url, { prepare: false, ... })` with
+   `new pg.Pool({ connectionString, pipeline: true })`; `Env.SQL` becomes
+   `Env.PG`. The simplest path is to delete `src/service.ts` and `src/index.ts`
+   and re-run `mantle generate --host bun`, or copy the new preset. Removed from
+   `@aotter/mantle/bun`: `bunPostgresStorage`, `bunPgConnect`,
+   `bunDatabaseDriver`, `bunAuthDatabase`, `BunSqlPool`, `BunAuthPool`. The role
+   no longer needs `TEMPORARY`. Custom transports lose `temporaryResultMetadata`,
+   `describeResult` and `readOnly` from `PgClient` / `PgStatement`.
+5. **Generated `src/service.ts` changed.** The `database(env).run` wrapper moved
+   to the exported `mantle`, and the Bun pooled wrapper ends each client once.
+   The preset is never rewritten: re-run `mantle generate` into a scratch
+   directory and copy the difference, or delete and regenerate if unedited.
+6. **First boot does one-time work.** It runs once under the advisory lock:
+   - one `_mantle_ix_<schema>_updated` index on `([scope,] updated_at, id)` per
+     Schema, built without `CONCURRENTLY` inside the convergence transaction, so
+     writes to a large table block while it builds. Pre-create it before
+     deploying, on the schema (`search_path`) Mantle uses, with both names quoted:
+     `CREATE INDEX CONCURRENTLY "_mantle_ix_<schema>_updated" ON "<schema>" (["<scope>",] updated_at, id)`.
+     A matching index is accepted. If a concurrent build fails, drop the invalid
+     index before deploying: boot accepts it by name and columns and never
+     rebuilds it. A Schema name longer than about 43 bytes gets a hashed index
+     name; read it from a fresh database's `pg_indexes` instead;
+   - each `_mantle_chk_*` check is rebuilt once (earlier releases left no
+     marker); later boots leave unchanged checks alone;
+   - the old `_mantle_jget`, `_mantle_bool` and `_mantle_json_each` functions
+     stay in place, unused: a previous release still running during a rolling
+     deploy calls them.
+7. **Boot under contention.** Concurrent boots converge once. A boot that cannot
+   get a lock within about five tries of one second fails with
+   `STORAGE_CHANGE_BLOCKED` naming the lock (another boot still converging, or a
+   long transaction on a table the plan changes), and is not retried for 10
+   seconds. A winner building a very large index can outlast its waiters, which
+   then report the blocked boot; boot again when it has finished (#1408).
+8. **Auth.** `get-session` no longer carries a `set-auth-jwt` response header
+   when the OAuth provider is configured; call the plugin's `/api/auth/token`
+   instead. `d1Driver`'s structural `D1PreparedStatement` now requires `first`
+   and `all`: a hand-rolled fake must add them.
+9. **D1.** A paged View with `json_each` in a `JOIN` arm, or with more than one
+   `json_each`, now pages by every element's `id`: its order among ties changes,
+   no row is skipped, and a cursor issued before the upgrade may need to restart.
+
 ## 0.1.4 — 2026-09-24
 
 0.1.4 repairs the published consumer path without changing the Manifest