@aotter/mantle 0.1.5-alpha.1 → 0.2.0-alpha.1

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

@@ -0,0 +1,63 @@
+# 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/README.md

@@ -2,7 +2,7 @@
 
 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.
 
-## v0.1.0 ADRs
+## ADRs
 
 | # | Title | Status |
 |---|---|---|
@@ -12,22 +12,33 @@ Records of *why* mantle ended up shaped this way. The numbering preserves POC AD
 | [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. | Accepted (new) |
+| [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 |
+| [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 |
+| [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 |
-| [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 |
+| [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 |
-| [0027](0027-scheduled-procedure-triggers.md) | Schedule Triggers in the sealed plan with Cloudflare-hosted invocation and system identity. | Accepted for 0.1.5 |
+| [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 same pin through grants and the frontend kit. | 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 |
 
 ## Reading order
 
@@ -79,3 +90,7 @@ These retain their issue-based filenames and original decision status.
 | [#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 |

package/docs/adr/adr-lite-861-admin-webmcp.md

@@ -2,6 +2,12 @@
 
 Status: Accepted for implementation following maintainer approval.
 
+> **Amendment (0.2.0):** Admin answers no MCP. `POST /admin/api/mcp` is
+> removed; the browser calls a staff tool with `POST /admin/api/webmcp/<tool>`
+> and its input as JSON, which Admin runs as the staff MCP surface does, with
+> the session. The catalog is still the staff MCP surface's; an MCP client
+> with a token uses `/mcp/staff`.
+
 Admin WebMCP uses the canonical staff MCP catalog and JSON-RPC dispatcher.
 `GET /admin/api/webmcp` supplies the same tool definitions plus UI route hints;
 `POST /admin/api/mcp` carries MCP requests using the current Admin session.

package/docs/adr/adr-lite-909-admin-ui-kit.md

@@ -1,6 +1,6 @@
 # ADR-lite 909: Mantle Admin UI kit export
 
-**Status:** Accepted
+**Status:** Accepted; amended by [ADR-0029](0029-mcp-apps-interaction-contracts.md) (the kit moves to `@aotter/mantle-ui`, with a one-minor re-export from `@aotter/mantle-admin-ui/kit`)
 
 ## Context
 

package/docs/examples/README.md

@@ -1,22 +1,20 @@
 # Examples hub
 
-This folder is the only official examples tree. Filenames carry the handler class. There is no second Manifest body under `docs/handbook/examples/` — those pages redirect here.
+Every page is a whole service in the 0.2.0 grammar: its manifests compile with
+`mantle generate` (the SDK repository compiles each one in its checks). Copy the shape you need into
+your project's `manifests/`; none is a template to copy wholesale.
 
-**Builder** may ingest a Manifest only when every Procedure is `handler.kind: builtin` (or the example has no Procedures). That is the `builtin-*` prefix. `cf-primitives-*` documents Durable Objects, Queues, cron, R2, and/or `handler.kind: ref`. `host-*` directories are runnable consumer projects, not business presets.
+| Example | What it shows | Handler code |
+|---|---|---|
+| [`reference-service/`](./reference-service/README.md) | A runnable service with its smoke test: scoped orders, SQL Views and Procedures, hooks, a cron, REST, both MCP surfaces, Admin's API and console email-OTP sign-in. The release gate runs it. | yes |
+| [Intake form](./intake.md) | An anonymous form: one SQL `INSERT` and a staff View. | none |
+| [Intake with bot check and notification](./intake-hooks.md) | A Turnstile check as the Procedure's guard, an email from an after hook. | 2 handlers |
+| [Reservation requests](./reservation.md) | A request queue with a Schema `check`. | none |
+| [Publication](./publication.md) | Localized posts with a parent identity, per-locale lists and `mantle.search`. | none |
+| [Legal documents and consent](./legal-documents.md) | Immutable revisions, and an acceptance written only for a published revision. | none |
+| [Procurement approvals](./procurement.md) | Members see their own rows through `auth.uid()`; staff review with an optimistic lock. | none |
+| [Commerce catalog and orders](./commerce.md) | A published catalog, guest orders and a locked staff review. | none |
+| [Commerce inventory](./commerce-inventory.md) | Server-side pricing, atomic stock reservation with `checks` and locks, a scheduled expiry and a verified payment callback. | 3 handlers |
+| [Guarded API access](./guarded-api.md) | API keys through a custom `CallerResolver`, scopes and a live entitlement guard. | 2 handlers |
 
-Drop a `builtin-*` YAML block into `host-local-admin-otp/manifests/` (or `host-minimal-worker/manifests/`) and run `mantle validate`.
-
-| Id / filename | Meaning | Class | Builder | Admin | Related host |
-|---|---|---|---|---|---|
-| [`builtin-intake.md`](./builtin-intake.md) | Public request form; builtin create; staff list | builtin | yes | optional (staff View / Staff MCP) | `host-minimal-worker` or `host-local-admin-otp` |
-| [`builtin-reservation.md`](./builtin-reservation.md) | Public reservation queue; builtin create; staff list | builtin | yes | optional | `host-minimal-worker` or `host-local-admin-otp` |
-| [`builtin-publication.md`](./builtin-publication.md) | Localized posts, public list, reader suggestions | builtin | yes | optional (Admin or Staff MCP to draft/publish) | `host-local-admin-otp` |
-| [`builtin-procurement.md`](./builtin-procurement.md) | Member requisitions and staff approve/reject with OCC | builtin | yes | optional (Admin or Staff MCP) | `host-local-admin-otp` |
-| [`builtin-legal-documents.md`](./builtin-legal-documents.md) | Localized Terms/Privacy revisions and signed-in acceptances | builtin | yes | optional (staff create via MCP; Admin for review) | `host-local-admin-otp` |
-| [`builtin-commerce.md`](./builtin-commerce.md) | Product catalog, guest orders, staff fulfill/cancel; builtin create/update only | builtin | yes | optional (Admin or Staff MCP to publish products) | `host-local-admin-otp` |
-| [`cf-primitives-intake-hooks.md`](./cf-primitives-intake-hooks.md) | Same intake Schema with Turnstile `before_create` and email `after_create` `ref` hooks | cf-primitives | no | optional | `host-minimal-worker` plus handlers |
-| [`cf-primitives-commerce-inventory.md`](./cf-primitives-commerce-inventory.md) | Catalog plus Durable Object stock authority, Queue expiry, payment callback, `ref` handlers | cf-primitives | no | optional | `host-minimal-worker` plus DO/Queue/cron |
-| [`cf-primitives-guarded-api.md`](./cf-primitives-guarded-api.md) | API keys, scopes, live entitlement `ref` guards over REST and MCP | cf-primitives | no | none | `host-minimal-worker` plus credential resolver |
-| [`host-minimal-worker/`](./host-minimal-worker/README.md) | Executable Spec + adapter without Admin | host | no | none | itself |
-| [`host-local-admin-otp/`](./host-local-admin-otp/README.md) | Executable opt-in Admin / Dev UI with email OTP | host | no | required | itself |
-| [Mantle on ChatGPT Sites](../handbook/chatgpt-sites/index.md) · [runnable reference](./host-chatgpt-sites/README.md) | Runnable Sites D1/R2, ChatGPT identity, Admin media, published web and public read-only MCP | host | no | required | itself |
+Projects on 0.1.x move with [the upgrade guide](../upgrade-0.1-to-0.2.md).