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

package/docs/adr/0038-bun-native-host.md

@@ -1,63 +0,0 @@
-# ADR-0038: Bun is a native host
-
-**Status:** Accepted for 0.2.0. Amends ADR-0036's reserved Bun host.
-
-## Decision
-
-`@aotter/mantle/bun` owns native drivers and Admin files. Core remains host-neutral;
-PostgreSQL retains policy, convergence, SQL printing, SERIALIZABLE retries, timeout
-and error mapping. `host: bun` defaults to `dialect: postgres` on first selection.
-The CLI writes an application-owned Bun.serve entry and service once. Both native
-PostgreSQL and bun:sqlite presets exist; neither imports Cloudflare or pg.
-
-The PostgreSQL host takes a Bun.SQL pool configured with `prepare: false`.
-Bun's prepared JSON parameter encoding serializes an already encoded JSON string
-again. Refuse another configuration rather than silently changing stored values.
-Pool reserve/release binds every operation to one connection. The host closes
-its pool after the server and retained background work stop.
-
-Bun exposes raw results without OIDs/typmods. Obtain exact result metadata from
-`CREATE TEMP TABLE ... AS <query> WITH NO DATA`, read pg_attribute and drop the
-temporary table, then execute the original statement once with raw text results.
-A DML description is a data-modifying CTE under WITH NO DATA, which does not
-execute its body. PostgreSQL owns all type inference, including numeric scale,
-CASE, COALESCE and CTEs. Each descriptor runs in the statement's existing pinned
-transaction. Views use a regular transaction because temporary DDL is forbidden
-in READ ONLY: a read describes first, then runs `SET TRANSACTION READ ONLY` before
-the statement, so the engine still refuses a write as it does on every other
-PostgreSQL host. Creating the temporary table needs the TEMPORARY privilege on the
-database (`GRANT TEMPORARY ON DATABASE ... TO <role>`); without it every read fails
-with 42501 naming this requirement, and a read replica cannot serve this host.
-Every transaction appends `pg_temp` to its search_path, on every PostgreSQL host,
-so a temporary table on a pooled session never stands in for a Schema table (unless
-the role's own search_path already names pg_temp earlier, which it should not).
-A connection whose ROLLBACK failed is closed, never released to the pool.
-This costs three metadata round trips per result. Replace it only when Bun
-provides public RowDescription metadata; do not approximate money or time values.
-
-The entry overwrites the trusted IP header from the socket; behind a reverse proxy
-listed in TRUSTED_PROXIES, the client is the address that proxy appended last to
-X-Forwarded-For (one trusted hop; an IPv4-mapped socket address is matched as
-IPv4), so each client keeps its own sign-in rate limit. Bun.serve runs
-with `development: false` and an error handler that answers Core's 500 envelope: Bun's
-development page would show the exception, stack and paths. Admin assets reject
-traversal, control characters and symlinks outside the installed bundle.
-bun:sqlite runs with foreign keys on, as D1 does, and a Mantle batch waits for a
-Better Auth transaction open on the same handle instead of becoming its savepoint.
-Local OTP requires an explicit loopback PUBLIC_ORIGIN, a secret and bootstrap
-email, as Cloudflare does.
-
-Bun has no built-in cron scheduler in this preset. Enabled schedule Triggers are
-refused before files are written; an application that supplies a scheduler uses
-host none and invokes Mantle's schedule ingress explicitly. No polling scheduler,
-workflow engine or new manifest grammar is introduced.
-
-## Verification
-
-Native PostgreSQL and SQLite run the same storage conformance suite. Native
-regressions cover result names, JSON scalar/array values, exact numeric typmods,
-microsecond timestamps, CTE/comment queries, star targets, connection
-reservation, read-only reads, statement_timeout, pg_temp ordering, foreign keys,
-transactions on a shared bun:sqlite handle and actual Better Auth
-OTP/bootstrap-owner login on both engines. Both generated presets typecheck
-against bun-types. CI installs pinned Bun and runs these on every PR.

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

@@ -1,130 +0,0 @@
-# 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

@@ -1,98 +0,0 @@
-# Architecture Decision Records
-
-Records of *why* mantle ended up shaped this way. The numbering preserves POC ADR numbers where carried over (so cross-references in code comments and external docs stay valid); new ADRs continue from the highest used number.
-
-## ADRs
-
-| # | Title | Status |
-|---|---|---|
-| [0001](0001-four-atom-manifest-model.md) | Four-atom manifest model (Schema / View / Procedure / Trigger). Folds POC ADR-0005 (grammar discipline) and POC ADR-0006 (multi-doc YAML). | Accepted; fixed-file contract superseded |
-| [0002](0002-closed-enums-for-bindings.md) | Closed enums for `x-mantle-bind` and `ctx.*` predicates. | Accepted (refreshed) |
-| [0007](0007-ai-as-primary-author.md) | AI is the primary author of consumer projects; SDK contract is three pre-serve feedback loops, runtime diagnostics, and coder/operator role surfaces. | Accepted + amended |
-| [0008](0008-structured-diagnostic-shape.md) | Diagnostic shape for validate/boot/runtime failures, with a reserved consumer-test phase; measured harnesses keep purpose-shaped reports. | Accepted + amended |
-| [0009](0009-consumer-supplied-manifests.md) | Historical generated-array workflow; consumer source ownership continues in ADR-0019. | Superseded by 0019 |
-| [0010](0010-locale-and-translates.md) | Locale 3-layer (manifest / D1 site_config / data field) + translates pattern. Boot decoupled from `site_config` (issue #60 fix). | Accepted (refreshed) |
-| [0011](0011-adapter-port-spec.md) | Adapter port spec. Required runtime ports plus optional feature ports. | Superseded by 0019 (Core storage, Admin composition) and 0024 (SQLite/D1 storage); retained as the alpha.7 Cloudflare adapter record |
-| [0012](0012-views-as-public-rest.md) | Views auto-expose matching REST and `query_view_*` MCP reads on their declared `public` or `staff` surface. Schemas never get a public REST endpoint. | Accepted + amended |
-| [0013](0013-agent-provisioned-consumer-projects.md) | Historical agent-provisioned consumer projects path. | Superseded by 0021 |
-| [0014](0014-auth-better-auth-and-multi-tenant-mcp.md) | The Cloudflare adapter owns one Better Auth 1.7 identity/OAuth/MCP authority with native method options and CIMD discovery. Verified callers are normalized into runtime context; mutable staff role and target authorization are re-evaluated per call. | Accepted + amended; auth ownership amended by 0032 |
-| [0016](0016-site-semantic-layer.md) | Historical Starter/Landing `AGENTS.md` and launch-state contract. | Superseded by 0021 |
-| [0017](0017-media-multi-variant-agent-side-optimization.md) | Multi-variant media assets with agent-side optimization and asset-id entry references. | Accepted |
-| [0018](0018-core-starters-repository-boundary.md) | Core produces published SDK artifacts; the separate starters repository validates them as an external consumer. Revisit after release-contract simplification. | Superseded by 0021 |
-| [0019](0019-sealed-manifest-runtime-pipeline.md) | One sealed source-to-runtime pipeline, semantic storage seam, and optional Web/Admin/platform dependency direction. | Accepted; optional boundaries become subpaths of two packages per 0032 |
-| [0020](0020-builtin-handler-contracts-and-matched-upsert.md) | Static builtin handler contracts and natural-key matched upsert (`handler.match`). | Accepted + amended by 0022 |
-| [0021](0021-retire-starter-scaffolding.md) | Direct authoring; retire Starter scaffolding. | Accepted; no-initialization clause superseded by 0026 |
-| [0022](0022-caller-observed-version-occ.md) | Caller-observed `expectedVersion` for Admin bind and builtin upsert OCC. | Accepted; Admin binding rules superseded by 0029 |
-| [0023](0023-port-failure-contract.md) | Storage and service failure contracts: resource, rate, outcome-unknown, partial-failure and precondition diagnostics with safe `failure` facts. | Accepted for alpha.17 (#857); amends 0008 |
-| [0024](0024-manifest-native-schema-tables.md) | Materialize each Schema as a native storage table and deploy reviewed migration artifacts. | Accepted; authored-native-name clauses superseded by 0025; migration workflow superseded by 0033 |
-| [0025](0025-reserved-native-columns-and-published-only-public-views.md) | Reserve the six native column names, let `indexes` reference them, and compile public publishing Views published-only. | Accepted |
-| [0026](0026-progressive-generate.md) | Progressive `mantle generate` with a full default, positive features, saved host selection, and user-owned source. | Accepted; supersedes part of 0021; dependency closure, identity and `--host` amended by 0032 |
-| [0027](0027-scheduled-procedure-triggers.md) | Schedule Triggers in the sealed plan with Cloudflare-hosted invocation and system identity. | Accepted for 0.1.5; cron dialect and host requirement amended by 0032 |
-| [0028](0028-schema-ttl-expiry.md) | Logical TTL on Schema reads with preview-first, explicit bounded cleanup. | Accepted for 0.1.5 |
-| [0029](0029-mcp-apps-interaction-contracts.md) | Official MCP SDK for all MCP wire handling; transport-neutral capability catalog with validate-once invocation; `@aotter/mantle-mcp` and `@aotter/mantle-ui`; Manifest-declared interaction contracts and MCP Apps (#1110). | Accepted; amends ADR-lite 909 |
-| [0030](0030-store.md) | Store: one persistence object (`ctx.store` / `runtime.store`) over one relational JSON query AST compiled by each adapter; first slice `select`, `view`, `id`, then `write`, then manifest grammar (#1151). | Accepted; completed for 0.2.0 by 0032; authoring amended by 0034 |
-| [0031](0031-host-cloud-core-contract.md) | Cloud supplies the Core pin before host artifact hashing; protocol 2 checks the pin through grants/kit; protocol 4 requires a verified source receipt before save. | Accepted |
-| [0032](0032-store-centric-core-and-service-contract.md) | 0.2.0: Store is the only entry persistence path; an application-owned service behind one host-neutral `createMantle`; one `Caller` identity and no Core-owned user or auth; `_mantle_` marks system tables only; two npm packages and one plugin. | Accepted for 0.2.0; decisions 1–5, 10 and 13 amended by 0034; decisions 6 and 12 by 0035 |
-| [0033](0033-storage-converges-to-the-plan.md) | Schema storage converges to the plan by introspection: Mantle applies safe additions, blocks the rest, and verifies author-made changes; no Mantle-written migration files. | Accepted for 0.2.0; amended by 0034 and 0035 |
-| [0034](0034-store-is-authored-as-sql.md) | Store is authored as SQL in the D1 dialect and compiled to IR by the CLI with `libpg-query`; no Worker parses SQL. The IR is the parser's AST under an exact allowlist, printed by `pgsql-deparser`; a chosen SQL subset with policy wrapped around every Schema reference; FTS5 search and R*Tree places; after hooks take row arrays; one SQLite executor; exact encodings for time and decimals. | Accepted for 0.2.0 (spike #1203); amended by 0035 and 0037 |
-| [0035](0035-sql-dialects.md) | Mantle SQL is PostgreSQL syntax and meaning; a dialect module runs it on one engine. D1 and PostgreSQL ship built in, and both pass the compliance suite. | Accepted for 0.2.0; amended by the PostgreSQL dialect (#1293), 0036 and 0037 |
-| [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
-
-If you're new to the codebase:
-
-1. **0001** — what the 4 atoms are.
-2. **0019** — the sealed source-to-runtime pipeline and optional product boundaries.
-3. **0009** — historical context for consumer-owned manifests.
-4. **0007** — what running the SDK feels like as an AI author (and as the operator agent).
-5. **0011** — the boundary between the runtime and the adapter.
-6. **0010** — how locale flows through the system.
-7. **0026** — current progressive generation boundary; **0021** retains the direct-authoring history and **0013** is historical install-session context.
-8. **0002, 0008** — the two ADRs that touch every diagnostic and every binding.
-
-## What's NOT here (and why)
-
-POC had 16 ADRs. The rebuild ports the durable ones, writes fresh ADRs
-for new v0.1.0 boundaries, and folds / drops the rest:
-
-- **POC ADR-0003** OpenAPI emission → folded into `mantle-spec` README (the *what* is implementation; the *why* was already captured by ADR-0001's grammar lock).
-- **POC ADR-0004** D1 today, Hyperdrive PG tomorrow → folded into `mantle-cloudflare` README (now a v0.2 roadmap item, not an architectural decision).
-- **POC ADR-0005** v0.1 minimum grammar → folded into ADR-0001's fail-closed grammar policy.
-- **POC ADR-0006** multi-doc YAML → folded into ADR-0001 §"Authoring shape: multi-doc YAML."
-- **POC ADR-0011** lifecycle binary opt-in → distilled to a §"Lifecycle" subsection in `docs/design-atoms.md`. v0.1.0 ships `publishing` and `operational`.
-- **POC ADR-0012** strategic posture vs adjacent CMS designs → strategic / marketing material, lives in `README.md` if anywhere.
-- **POC ADR-0013** role-split surfaces (coder agent vs operator agent) → folded into ADR-0007 (Part B).
-- **POC ADR-0014** builtin handlers and lifecycle Triggers → promoted to v0.1.0 and implemented in the rebuild via `LifecycleHookingEntryRepository` and `InvokeBuiltinUseCase`. Full shape spec lives in `docs/design-atoms.md`.
-- **POC ADR-0015** cms-astro internal seam discipline → POC-specific to a package that no longer exists; replaced by ADR-0011 (adapter port spec).
-- **POC ADR-0029** drop Astro from cms-cloudflare → POC-specific historical record; the rebuild starts post-Astro.
-
-The rebuild's ADR-0011 (new) is the most load-bearing addition — the POC accumulated multiple *aspirational* boundaries (POC ADR-0015 was one; references in CLAUDE.md were another) without a single normative spec. ADR-0011 makes the boundary explicit and reviewable. ADR-0012 and ADR-0013 capture newer v0.1.0 product/runtime seams that were not present in the POC.
-
-## Contributing a new ADR
-
-1. Pick the next unused number after the highest existing ADR.
-2. File: `docs/adr/<NNNN>-<kebab-title>.md`.
-3. Sections: Status, Date, Context, Decision, Consequences, Alternatives, How to apply, Implementation status.
-4. Link from this README's table.
-5. Land it in a PR alongside (or before) the implementation it documents — ADR-as-design-artifact, not ADR-as-archaeology.
-
-## ADR-lite records
-
-These retain their issue-based filenames and original decision status.
-
-| Record | Status |
-|---|---|
-| [#803 Request diagnostics](adr-lite-803-request-diagnostics.md) | Implemented |
-| [#808 Route readiness](adr-lite-808-route-readiness.md) | Accepted |
-| [#809 Bounded public content](adr-lite-809-bounded-public-content.md) | Implemented |
-| [#812 Native parity](adr-lite-812-native-parity.md) | Implemented; deployment evidence linked in record |
-| [#823 Home statistics](adr-lite-823-home-statistics.md) | Proposed; unmerged demo |
-| [#842 MCP authoring](adr-lite-842-mcp-authoring.md) | Accepted |
-| [#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

@@ -1,330 +0,0 @@
-# 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.