@aotter/mantle 0.1.4 → 0.2.0-alpha.1

package/dist/web/createRestSurface.js

@@ -0,0 +1,39 @@
+import { coerce, failure, json, match, readJsonObject, viewQuery, wireError } from "../core/wire.js";
+export function createRestSurface(runtime, options) {
+    const base = options.basePath.replace(/\/+$/, "");
+    const { plan } = runtime;
+    const params = (path) => path.split("/").filter((s) => s.startsWith("{")).length;
+    // a route with fewer path params is more specific, so `/items/search` is never shadowed by `/items/{id}`
+    const routes = Object.entries(plan.triggers)
+        .flatMap(([name, t]) => (t.source.kind === "http" ? [{ name, method: t.source.method, path: t.source.path, procedure: t.procedure }] : []))
+        .sort((a, b) => params(a.path) - params(b.path));
+    return async (request, caller) => {
+        try {
+            const url = new URL(request.url);
+            const path = url.pathname;
+            const view = request.method === "GET" ? match(`${base}/views/{name}`, path)?.name : undefined;
+            if (view !== undefined) {
+                const v = plan.views[view];
+                if (!v || v.surface !== "public")
+                    throw wireError("NOT_FOUND", `no public View '${view}'`, "rest");
+                return json(await runtime.store.as(caller).view(view, viewQuery(view, v, url.searchParams, "rest")));
+            }
+            for (const route of routes) {
+                if (route.method !== request.method)
+                    continue;
+                const params = match(route.path, path);
+                if (!params)
+                    continue;
+                const props = plan.procedures[route.procedure]?.input.properties ?? {};
+                const body = await readJsonObject(request, "rest");
+                const input = { ...body, ...Object.fromEntries(Object.entries(params).map(([k, v]) => [k, coerce(v, props[k], k, "rest")])) };
+                return json(await runtime.invokeProcedure({ procedure: route.procedure, input, caller, cause: { kind: "http", id: crypto.randomUUID() } }));
+            }
+            throw wireError("NOT_FOUND", "no such route", "rest");
+        }
+        catch (e) {
+            return failure(e, "rest");
+        }
+    };
+}
+//# sourceMappingURL=createRestSurface.js.map

package/dist/web/createRestSurface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createRestSurface.js","sourceRoot":"","sources":["../../src/web/createRestSurface.ts"],"names":[],"mappings":"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"}

package/dist/web/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./createRestSurface.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/web/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/web/index.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC"}

package/dist/web/index.js

@@ -0,0 +1,2 @@
+export * from "./createRestSurface.js";
+//# sourceMappingURL=index.js.map

package/dist/web/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/web/index.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC"}

package/docs/adr/0008-structured-diagnostic-shape.md

@@ -7,7 +7,7 @@ diagnostic emitters and measured harnesses.
 
 **Deciders**: phsu
 
-**Related**: [ADR-0007](0007-ai-as-primary-author.md) (the AI-as-primary-author contract this diagnostic format serves); the zod runtime is described in [`docs/design-atoms.md`](../design-atoms.md) § "Manifest validation — JSON Schema in, zod at runtime".
+**Related**: [ADR-0007](0007-ai-as-primary-author.md) (the AI-as-primary-author contract this diagnostic format serves); the zod runtime is described in [`docs/design-atoms.md`](https://github.com/aotter/mantle/blob/main/docs/design-atoms.md) § "Manifest validation — JSON Schema in, zod at runtime".
 
 ---
 
@@ -217,7 +217,7 @@ from day 1 — manifest authoring stays JSON Schema, but the
 runtime validator a manifest author's request body hits is a
 zod schema, produced by Zod's official `z.fromJSONSchema` importer behind the
 compatibility boundary in
-`@aotter/mantle-spec` (see [`docs/design-atoms.md`](../design-atoms.md) § "Manifest validation — JSON Schema in, zod at runtime").
+`@aotter/mantle-spec` (see [`docs/design-atoms.md`](https://github.com/aotter/mantle/blob/main/docs/design-atoms.md) § "Manifest validation — JSON Schema in, zod at runtime").
 Mantle validates its supported keyword/ref policy before import and emits
 `JSON_SCHEMA_UNSUPPORTED`, `JSON_SCHEMA_REF_INVALID`, or
 `JSON_SCHEMA_LIMIT_EXCEEDED`; Zod owns the accepted keywords' validation

package/docs/adr/0011-adapter-port-spec.md

@@ -63,7 +63,7 @@ execution. Deferred envelopes carry persisted entry data and normalized actor
 metadata, never arbitrary original request input. Adapter-specific retry,
 delay, batch, DLQ, and message-size settings remain outside manifest grammar.
 The operational reference is
-[`docs/deferred-lifecycle-queues.md`](../deferred-lifecycle-queues.md).
+[`docs/deferred-lifecycle-queues.md`](https://github.com/aotter/mantle/blob/main/docs/deferred-lifecycle-queues.md).
 
 Identity, session, OAuth, and role enforcement are adapter-owned per
 ADR-0014. The runtime does not define `SessionRepository`,
@@ -227,7 +227,7 @@ There's no module-global state holding adapter-specific bindings.
 - Removing a port is also possible (if a port is found to overlap or be unnecessary), again by amending this ADR.
 
 **Discoverability for adapter authors**:
-- A future adapter author reads this ADR + [`docs/adapter-guide.md`](../adapter-guide.md), implements the two required ports, then wires boot and HTTP/MCP surfaces. That's the contract. No hidden state, no implicit assumptions about the HTTP framework.
+- A future adapter author reads this ADR + [`docs/adapter-guide.md`](https://github.com/aotter/mantle/blob/main/docs/adapter-guide.md), implements the two required ports, then wires boot and HTTP/MCP surfaces. That's the contract. No hidden state, no implicit assumptions about the HTTP framework.
 
 **Test ergonomics**:
 - Each port is small and isolated. Tests can mock individual ports without spinning up D1 or an OAuth provider.

package/docs/adr/0014-auth-better-auth-and-multi-tenant-mcp.md

@@ -439,7 +439,7 @@ and `ADMIN_GITHUB_LOGIN`; it does not use Platform Account OIDC, a client
 secret, or an owner email handoff. The local provider id remains `github`.
 The wire contract remains in [Platform #35](https://github.com/aotter/mantle-platform/issues/35),
 and the product boundary is documented in
-[`docs/auth-hosting-model.md`](../auth-hosting-model.md).
+[`docs/auth-hosting-model.md`](https://github.com/aotter/mantle/blob/main/docs/auth-hosting-model.md).
 
 This does not change ADR-0014's core rule: Mantle does not expose an
 un-curated `betterAuthOptions` or `advanced` passthrough. Missing Better
@@ -521,7 +521,7 @@ every `tools/call`. MCP does not promise to accept a raw REST API key/PAT.
 Dynamic membership, billing, and entitlement state remains consumer-owned.
 `requires.guard.procedure` orchestrates a site handler on every invocation but
 does not introduce a Policy atom or an entitlement service. See
-[`API and MCP authorization`](../api-mcp-authorization.md) for the public API
+[Guarded API access](../examples/guarded-api.md) for the public API
 and end-to-end examples.
 
 ## Amendment — 2026-08-22: Better Auth 1.7 MCP and CIMD convergence
@@ -898,3 +898,22 @@ Boundaries that stay:
   `verifyOAuthAccessToken`, DPoP binding and the MCP challenge are unchanged.
 - No other Better Auth field gains a passthrough by this amendment. The
   2026-05-14 test still applies to the next proposal.
+
+## 2026-10-02 amendment — a surface with no anonymous tool challenges at connect
+
+The 2026-09-21 amendment kept anonymous `initialize` and `tools/list` open on the public surface and moved the `401` to
+the first `tools/call` that needs identity. MCP clients do not all follow that: several decide whether to run OAuth from
+the connect step alone (an anonymous `initialize` that succeeds means "no sign-in"), so a surface whose every tool needs
+identity never showed them a sign-in. Better Auth's `withMcpAuth` and the MCP SDK's `requireBearerAuth` both challenge
+every unauthenticated request for the same reason.
+
+- A surface is **closed** when none of its tools may be called anonymously: every tool's `requires.auth.all` names at least
+  one predicate (each of `ctx.user`, `ctx.auth`, `ctx.staff`, `ctx.auth.scope` needs an identity). The staff surface is
+  always closed; a public surface with no tools is open, since nothing on it needs a sign-in.
+- On a closed surface every anonymous request (`initialize`, `tools/list`, the SSE `GET`) answers `401` with the RFC 9728
+  `WWW-Authenticate` challenge, as the staff surface already did. The challenge names the surface's scope floor
+  (`scope="mcp"` by default), so the first authorization already asks for it.
+- A surface with at least one tool anonymous may call keeps the 2026-09-21 behaviour: discovery stays open and the first
+  `tools/call` that needs identity answers `401`.
+- Nothing is configured: the rule follows from the plan, so a project that adds a public tool reopens discovery by
+  declaring it.

package/docs/adr/0019-sealed-manifest-runtime-pipeline.md

@@ -74,7 +74,7 @@ semantic fingerprint.
 | Optional modules/adapters | Web/Admin composition and request/session/cache/platform translation | Re-parsing, re-linking, or a second authorization/runtime stack |
 
 The current-to-target rule ledger and evidence are maintained in
-[`docs/sealed-pipeline-ownership.md`](../sealed-pipeline-ownership.md).
+[`docs/sealed-pipeline-ownership.md`](https://github.com/aotter/mantle/blob/main/docs/sealed-pipeline-ownership.md).
 
 ### Core and optional products
 
@@ -149,6 +149,10 @@ second manifest/runtime path.
 
 ### Naming and code generation
 
+This section records the original codegen decision. The current generated API
+uses a sealed `plan` and wire-keyed `Schemas`, `Views`, and `Store` type maps;
+see the [typed queries guide](../handbook/guides/typed-queries.md).
+
 The Core execution unit is `MantleRuntime`, not a site. Optional TypeScript
 generation is a pure projection of linked/compiled semantics. It exposes
 `bindMantle(runtime)` plus an eager `createMantle()` convenience that delegates

package/docs/adr/0021-retire-starter-scaffolding.md

@@ -1,6 +1,6 @@
 # ADR-0021: Author applications directly; retire Starter scaffolding
 
-Status: Accepted by owner, 2026-09-08 (#786). Supersedes ADR-0018 for the 0.1.2 line.
+Status: Accepted by owner, 2026-09-08 (#786). Supersedes ADR-0018 for the 0.1.2 line. Its no-initialization clause is superseded by [ADR-0026](0026-progressive-generate.md) for 0.1.5.
 
 Core is an embeddable manifest engine. Applications own package manifests,
 Worker entries, provider configuration, business manifests and visitor UI.

package/docs/adr/0022-caller-observed-version-occ.md

@@ -1,6 +1,6 @@
 # ADR-0022: Caller-observed `expectedVersion` for Admin and builtin upsert
 
-**Status:** Accepted
+**Status:** Accepted; the Admin binding rules are superseded by [ADR-0029](0029-mcp-apps-interaction-contracts.md) (Admin binds `expectedVersion` only from a declared interaction and infers no OCC target). The caller-observed version contract itself stands.
 
 **Date:** 2026-09-14
 

package/docs/adr/0024-manifest-native-schema-tables.md

@@ -1,6 +1,6 @@
 # ADR-0024: Materialize each Schema as a native storage table
 
-**Status:** Accepted; the clauses allowing authored data to use `id`, `status` or `createdAt` are superseded by [ADR-0025](0025-reserved-native-columns-and-published-only-public-views.md) (2026-09-22)
+**Status:** Accepted; the clauses allowing authored data to use `id`, `status` or `createdAt` are superseded by [ADR-0025](0025-reserved-native-columns-and-published-only-public-views.md) (2026-09-22); the migration-artifact and destructive-change workflow is superseded by [ADR-0033](0033-storage-converges-to-the-plan.md) for 0.2.0
 
 **Date:** 2026-09-18
 
@@ -108,7 +108,7 @@ destructive in the pre-beta contract. Cloud rejects them; operators rebuild the
 database and move required data manually outside Mantle and Control. Production
 neither generates nor accepts arbitrary migration SQL.
 
-Preparation records applied migration ids in the existing `_migrations` ledger.
+Preparation records applied migration ids in the `_mantle_migrations` ledger (#1150).
 The enclosing immutable artifact checksum protects the ordered SQL,
 fingerprints, and target projections. Preparation rejects an unknown source
 fingerprint, changed artifact checksum, skipped revision, or target mismatch.

package/docs/adr/0026-progressive-generate.md

@@ -0,0 +1,36 @@
+# ADR-0026: Progressive application generation
+
+**Status:** Accepted by owner for the 0.1.5 line (#1081–#1086). Supersedes the no-initialization clause of ADR-0021; direct authorship and optional package boundaries remain.
+
+Mantle is progressive. A new application defaults to Spec, Runtime, API, MCP, Admin, and an editable blank Web home so an agent does not forget the optional Admin composition. `--features` is a positive replacement list over `spec,runtime,api,mcp,admin,web`; dependencies are closed automatically. `spec` alone is host-free. The first generated hosts are `cf` and `chatgpt-sites`. Only host-dependent selections require `--host`; a TTY may prompt, while headless use must pass it explicitly.
+
+| Feature | Required features | Direct package additions |
+| --- | --- | --- |
+| `spec` | — | `@aotter/mantle`, `zod` peer |
+| `runtime` | `spec` | Host adapter; current CF adapter also brings Admin/Auth/Web transitively |
+| `api` | `runtime` | Host route composition and `hono` peer |
+| `mcp` | `runtime` | Host MCP route composition |
+| `admin` | `runtime,api,mcp` | `@aotter/mantle-admin`, `@aotter/mantle-admin-ui`; CF owner auth also uses `@aotter/mantle-auth` |
+| `web` | `runtime` | `@aotter/mantle-web` and a user-owned blank home |
+
+The host adapter's declared peers (`better-auth`, `hono`, `zod`, `aws4fetch`) are installed for host-dependent selections until its package dependency graph is split. A reduced selection still omits unselected routes and assets; it does not claim smaller transitive installation today.
+
+An application with only Git, installed skills, package metadata, a lockfile, README, and installed dependencies is new. Existing manifests or application code remain in direct-authoring compile mode. A saved `mantle.config.json` decides subsequent runs before that heuristic. V1 refuses host changes and feature-list changes after selection; application owners can make an explicit migration rather than have generation delete routes or data. An explicitly named missing manifest path is an error. A new default manifest directory may be absent or empty, yielding a valid empty plan without a fake business Schema.
+
+Generation preflights selection, manifest validity, package/script conflicts, file ownership, and symlink escapes before writing. It saves the selection and adds only absent package declarations and scripts; it does not run a package manager. Selected Mantle packages use the running CLI's exact version. Missing selected packages produce an incomplete, nonzero result and an explicit install-and-rerun instruction. `--check` never writes, installs, prompts, or provisions. Generated code and assets remain CLI-owned; the editable frontend, host config, identity, secrets, handlers, and historical migrations are application-owned. A later SDK upgrade does not overwrite them. Clean builds remove only copied output.
+
+Cloudflare currently has a facade with transitive Admin/Auth/Web dependencies and mounts OAuth/MCP unconditionally. Host generation must use a lower-level composition for reduced selections or change that facade; omitting dependencies from a manifest does not prove route omission. Cloudflare D1 remains runtime-managed. ChatGPT Sites uses reviewed, append-only managed migrations with applied-state checks (owned by #1086). Neither host generator provisions resources or deploys.
+
+This decision restores a convenient default while keeping the sealed Manifest-to-RuntimePlan pipeline and user-owned application source. It does not reintroduce a remote Starter catalog or a `mantle create` command.
+
+## 2026-09-25 amendment — existing application integration
+
+The original implementation added `--adopt` to convert an existing authored
+application into the generated-project layout. This amendment removes that
+mode. Applications with their own host shape continue direct authoring;
+integrating Mantle is guided by the version-matched `integrate` consumer skill.
+The agent may embed selected capabilities, replace one part at a time, or
+build a fresh Mantle application and migrate frontend and data. The CLI owns
+only deterministic generation and its declared checks; it does not certify
+arbitrary user-owned host wiring. A saved generated project still reruns from
+its own configuration, with file ownership and migration safeguards intact.

package/docs/adr/0027-scheduled-procedure-triggers.md

@@ -0,0 +1,31 @@
+# ADR-0027: Scheduled Procedure Triggers
+
+**Status:** Accepted for 0.1.5 (#1087). Revises the closed Trigger-source grammar from ADR-0001 and the host-only cron guidance of #322.
+
+**Date:** 2026-09-25
+
+## Context
+
+The earlier contract kept cron outside the Manifest graph. That forced an application Worker to invoke a Procedure by name with its own caller context, leaving scheduling invisible to validation and the compiled plan. A portable declaration is needed without pretending that every host can register a cron event.
+
+## Decision
+
+`Trigger.spec.source` gains `kind: schedule`, a five-field Cloudflare UTC `cron` (weekday 1=Sunday), and optional `enabled` (default true). It targets one Procedure whose input accepts `{}` and requires no user or staff authorization. The compiled plan carries Trigger identity, expression, target, enabled state, and the required `cloudflare` host. No HTTP route or user identity is granted.
+
+Cloudflare's `scheduled` entry finds enabled plan entries with the exact incoming expression and invokes them in Trigger-name order through the existing Procedure pipeline, continuing after individual failures and reporting them together. The system context has null user and staff, no credential, and `ctx.schedule` with stable `${trigger}:${scheduledTime}` identity. The application registers exact expressions with Wrangler. Cloudflare Cron Triggers do not document automatic retries; handlers still use the identity for possible duplicate/manual replay. Other hosts reject enabled schedules rather than silently omit them.
+
+## Consequences
+
+The grammar and sealed plan version advance. Applications must rerun `mantle generate` after upgrading. A Procedure needing staff authorization cannot run from a schedule. Cron provisioning, retries, retention and exactly-once execution remain host/operator responsibilities; the runtime does not claim them.
+
+## Alternatives
+
+Keeping host-only calls would preserve the old grammar but fail static validation and omit the feature from introspection. A general background-job framework would add storage and scheduling responsibilities without a second host implementation.
+
+## How to apply
+
+Declare a schedule Trigger, export `worker.scheduled`, and register its expression in `wrangler.jsonc`. Use `ctx.schedule.id` to deduplicate writes. See [Trigger reference](../handbook/reference/trigger.md#schedule).
+
+## Implementation status
+
+Implemented in the 0.1.5 scheduled Procedure PR, with parser, linker, compiler, runtime and Cloudflare adapter tests.

package/docs/adr/0028-schema-ttl-expiry.md

@@ -0,0 +1,33 @@
+# ADR-0028: Logical Schema TTL before explicit physical cleanup
+
+**Status:** Accepted for 0.1.5 (#1088).
+
+**Date:** 2026-09-25
+
+## Context
+
+An application needs a portable expiry rule across D1 and Bun SQLite. A cron-only delete task cannot guarantee that readers stop seeing expired data if it runs late or fails. Applying a new policy to a populated table must not silently bulk-delete rows.
+
+## Decision
+
+`Schema.spec.ttl` names one top-level date-time field and a nonnegative `expireAfterSeconds`. At `timestamp + duration <= now`, semantic reads exclude the row. Missing, null and unparseable legacy dates never expire. Declarative Views include the same predicate. Native SQL Views that name a TTL Schema's table are rejected (SQL over other tables is unaffected), and shared caching of a TTL View is rejected. The compiled plan and introspection expose the policy. Public Cloudflare pages derived from TTL collections use `no-store` rather than shared caching.
+
+SQLite storage implements an optional bounded `ExpirySweeper`. A sweep previews by default; `delete: true` is required for physical removal. It returns counts and a cursor, selects at most 100 expired IDs in stable order, and rechecks expiry in one bounded delete statement. A failed page can be retried with the previous cursor. Ref Procedures can call the semantic capability, including from a scheduled Trigger. No host automatically invokes it.
+
+Physical TTL removal does not fire before/after entry lifecycle hooks. Expiry already changed logical visibility; cleanup reclaims storage rather than representing an editorial deletion. Consumers needing business actions at expiry must implement them in idempotent scheduled host code before calling the sweep.
+
+## Consequences
+
+Adding or shortening TTL changes read visibility immediately but never starts physical deletion. Owners preview counts and choose when to sweep; expired rows can still occupy unique indexes until removal. Other adapters must implement equivalent read filtering and a sweep or fail closed for TTL plans. The runtime does not promise an exact deletion time.
+
+## Alternatives
+
+Scheduler-driven deletion alone leaves a visibility gap. Implicit migration-time cleanup risks irreversible bulk deletion. Firing ordinary deletion hooks during storage reclamation would cause delayed, retry-sensitive business effects after the row was already logically gone.
+
+## How to apply
+
+Declare `ttl` on a Schema, use declarative Views, preview with `runtime.store.sweepExpired({ collection, delete: false })`, then explicitly request deletion page by page. See [Schema TTL](../handbook/reference/schema.md#ttl).
+
+## Implementation status
+
+Implemented in the 0.1.5 TTL PR for the SQLite family, with Bun and local D1 conformance checks.

package/docs/adr/0029-mcp-apps-interaction-contracts.md

@@ -0,0 +1,324 @@
+# ADR-0029: Official MCP SDK, interaction contracts and MCP Apps
+
+**Status:** Accepted
+
+**Date:** 2026-09-25
+
+**Related:** epic [#1110](https://github.com/aotter/mantle/issues/1110)
+(supersedes #1109); tracked as [#1114](https://github.com/aotter/mantle/issues/1114).
+Builds on [ADR-0012](0012-views-as-public-rest.md),
+[ADR-0014](0014-auth-better-auth-and-multi-tenant-mcp.md),
+[ADR-0019](0019-sealed-manifest-runtime-pipeline.md),
+[ADR-0020](0020-builtin-handler-contracts-and-matched-upsert.md),
+[ADR-0022](0022-caller-observed-version-occ.md),
+[ADR-lite 845](adr-lite-845-frontend-client.md),
+[ADR-lite 861](adr-lite-861-admin-webmcp.md).
+Amends [ADR-lite 909](adr-lite-909-admin-ui-kit.md) (the kit moves to
+`@aotter/mantle-ui`). External: MCP specification 2025-11-25 and 2026-07-28,
+the MCP Apps extension, and the official TypeScript SDK
+(`@modelcontextprotocol/server` 2.1.0, `client` 2.1.0, `ext-apps` 2.0.0).
+
+## Context
+
+Mantle projects callable capabilities from the sealed RuntimePlan
+(`CallableCapabilityProjector`) and serves them over a hand-written JSON-RPC
+dispatcher in `mantle-runtime/src/infrastructure/mcp`. The #1109 goal (agents
+discover capabilities, find the right record, and open an interaction UI in
+chat) exposed three gaps.
+
+**Protocol.** The hand-written dispatcher accepts only protocol `2025-11-25`,
+has no resource layer, and duplicates negotiation, batching and error framing
+that the official SDK already owns. MCP Apps would add `resources/*`,
+`ui://` resources and `_meta.ui` negotiation on top. The repository already
+tests against the official client (#1023), and the official
+`@modelcontextprotocol/ext-apps` 2.0 server helpers target SDK 2.x.
+
+**Semantics in the wrong layer.** Tool semantics live in the transport:
+generic-tool role floors, entry mutability checks, argument parsing, media
+tool descriptions and `expected_version` annotation are in `McpToolCatalog`
+and `McpJsonRpcDispatcher.dispatchToolByName`. They must survive a transport
+swap unchanged.
+
+**Interaction contracts.** Verified on `develop` @ `35d2c14`:
+
+1. Row binding is inferred, and only in Admin. `discoverRowBindings`
+   (`mantle-admin/src/mountMantleAdmin.ts`) picks a same-name property, then a
+   lone single-field unique index, then `id`. The procurement example omits
+   `x-mantle-ref` because the inference would bind `requestNumber` where
+   builtin `update` needs the entry id.
+2. Admin's View page has no row operations; bindings are keyed by collection.
+3. SQL Views declare no output (ADR-lite 845).
+4. `lockedCollection()` in `ManifestGraphValidator` infers the collection an
+   OCC write locks. It is a diagnostic heuristic, not an execution contract.
+5. Staff MCP has no single-entry read.
+6. Admin binds the version read when the dialog opens
+   (`row-operations.tsx`), not the version of the row the user saw.
+7. Business errors are JSON-RPC `-32000` errors with `error.data`.
+8. Website preview (`?preview=1`) is authorized by a staff session cookie,
+   which is a third-party cookie inside a host's sandboxed iframe.
+9. Canonical Admin refuses framing (`frame-ancestors 'none'`).
+10. An MCP App's `tools/call` is proxied by the host with the model's client
+    credential. The server cannot tell a UI call from a model call.
+
+## Decision
+
+### 1. Protocol belongs to the official SDK; semantics belong to Mantle
+
+All MCP wire handling uses the official TypeScript SDK: JSON-RPC framing,
+version negotiation, transports, `tools/*`, `resources/*` and MCP Apps
+metadata. Mantle keeps authorization, guards, OCC, audit, validation and the
+diagnostic vocabulary. Official packages are pinned to exact versions and
+never forked. No hand-written JSON-RPC handling remains in the repository.
+
+Both protocol eras are served: `2026-07-28` and `2025-*` in stateless mode
+(`createMcpHandler(..., { legacy: "stateless" })`).
+
+### 2. Runtime is transport-neutral
+
+Runtime stops knowing about MCP. It provides:
+
+- `CapabilityCatalog` (domain service): one transport-neutral description per
+  callable capability on a surface: Views, Procedures, generic authoring and
+  lifecycle operations, and media upload. Each carries name, surface, title,
+  description, `inputSchema`, declared `outputSchema`, annotations,
+  `requiresIdentity` and the argument that identifies the operation for audit.
+- `InvokeCapabilityUseCase` (use case): the single execution entry and the
+  single validation point. It returns
+  `{ ok: true, data } | { ok: false, diagnostic }`. Missing or ill-typed
+  arguments are `VALIDATION_FAILED` diagnostics.
+
+Nothing under `domain/` or `usecase/` imports an MCP concept.
+
+### 3. Validate once
+
+The SDK receives each `inputSchema` through `fromJsonSchema(schema, validator)`
+with a pass-through validator: the schema is advertised unchanged, and the
+SDK does not validate. Runtime validates once, so MCP, HTTP and Admin report
+the same Mantle diagnostic, and the Ajv instance the default validator would
+pull in is not bundled.
+
+`outputSchema` is the safe projection from #1127: an allowlist that only
+loosens the declared schema, so a standard client validator accepts every
+value Runtime accepts. Ineligible outputs advertise none. Views advertise none.
+
+### 4. Results and errors (D1)
+
+- **Success:** `content` is one JSON text block; `structuredContent` carries
+  the value when it is a plain object.
+- **Business failure:** `isError: true` with `{ diagnostics: [Diagnostic] }`
+  (the ADR-0008 shape) as a JSON text block, repeated as `structuredContent`
+  unless the tool advertises an `outputSchema`. Structured results must
+  conform to that schema, and 1.x clients validate them even on `isError`.
+  This replaces the JSON-RPC `-32000` business error and is a breaking wire
+  change, announced with the cutover.
+- **Protocol failure** (malformed request, unknown method, unsupported
+  version) stays a JSON-RPC error owned by the SDK.
+- **Authentication:** an anonymous call to a tool whose capability
+  `requiresIdentity` (including any member of a 2025-era batch) is answered
+  before the SDK with HTTP 401 and a `WWW-Authenticate` challenge built by the
+  SDK helper. The SDK's own
+  `scopeChallenge` covers scopes only; identity stays outside it.
+
+### 5. Identity stays outside the SDK
+
+The SDK never verifies tokens. Adapters verify the caller with `mantle-auth`
+(ADR-0014), build the `HandlerContext`, and pass it as `authInfo.extra`. The
+server factory reads it per request. Authorization extensions such as EMA are
+unaffected.
+
+### 6. Packages and dependency direction (D7)
+
+Two packages are added; no other package is split.
+
+| Package | Responsibility |
+|---|---|
+| `@aotter/mantle-mcp` | Optional. Registers the capability catalog on an official `McpServer` per surface (`createMantleMcpServer`), wraps `createMcpHandler` (`createMantleMcpHandler`), writes audit per call, and registers MCP Apps resources and app tools through `@modelcontextprotocol/ext-apps/server`. No UI dependency. |
+| `@aotter/mantle-ui` | Optional. `/controller`: framework-free interaction controller; must not import React. `/` (root): React interaction components. `/kit` (with `kit.css` and `tokens.css`): the ADR-lite 909 kit moved from `@aotter/mantle-admin-ui/kit`, whose libraries are optional peers so `/controller` installs none. `/mcp-app`: a single-file `ui://` HTML build (`vite-plugin-singlefile`) using the official `App` bridge. |
+
+```text
+mantle-spec ◄── mantle-runtime ◄── mantle-mcp ◄── adapters, mantle-admin
+                      ▲                 │
+                      │                 └──► @modelcontextprotocol/server, ext-apps/server
+                      │ (types only)
+              mantle-ui/controller ◄── mantle-ui ◄── mantle-ui/mcp-app ──► ext-apps (App)
+                                           ▲
+                                     mantle-admin-ui
+```
+
+- Arrows point from consumer to dependency. Server packages never depend on
+  UI packages; `mantle-mcp` receives MCP App HTML as injected bytes.
+
+> **Amendment (0.2.0):** results carry no `_meta` interaction description.
+> `planApp(plan, { surface, html })` (`@aotter/mantle/mcp`) embeds the plan's
+> catalog (each View tool's columns as the fields they read, and, for a View
+> that reads one table and outputs its `id`, the Procedure tools whose
+> `target` is that Schema) as a JSON script in the injected HTML, and renders
+> every View tool of the surface. A rendered result names its tool in
+> `_meta["net.aotter.mantle/tool"]`. The App (`mantleAppHtml` from
+> `@aotter/mantle-ui/mcp-app`) reviews a row as listed; a moved version is the
+> server's `CONFLICT`. The preset serves it on `/mcp/staff`; a member-facing
+> App is the application's own.
+- `@aotter/mantle-admin-ui/kit` re-exports from `@aotter/mantle-ui` for one
+  minor release, then is removed.
+- No exported UI module depends on Admin's router, global API client, query
+  singletons or cookie session.
+
+### 7. Interaction contract
+
+| Term | Meaning |
+|---|---|
+| **Capability** | A callable View or Procedure on one surface, with its Trigger identity. |
+| **Target** | The entity an interaction is about: collection plus a stable key, never a display label. |
+| **Reference** | A declared relation from a field to a target collection and key. A reference alone does not mean an operation mutates or locks that entity. |
+| **Operation target** | The entity an operation mutates and whose version it locks. |
+| **Snapshot read** | The authorized read that produces what the human sees, including its version. |
+| **Input binding** | An explicit mapping from snapshot fields to operation input. |
+| **Version binding** | The input field carrying the observed version, taken from the snapshot the human saw. |
+| **Renderer** | Presentation of a snapshot, form, review or outcome. Owns no semantics. |
+
+Rules:
+
+- An interaction is **entity-bound** only when target, snapshot read, input
+  binding and (when required) version binding are all established by the
+  contract. Otherwise no automatic binding is offered; the operation stays
+  usable as an ordinary form.
+- Nothing is guessed from names.
+- **Derivable today:** builtin `update`/`delete`/`archive` and id-based
+  `upsert` target `handler.schema` by input `id`, with `expectedVersion` when
+  declared; a non-SQL View's rows target its `from` collection when `fields`
+  includes `id`, and supply a version only when `fields` includes `version`.
+- **Declared (D4, grammar-revise #1116):**
+  - `x-mantle-ref: { schema, field }` on a Schema or View field names the
+    target collection and the key field. `field` must be `id` or a
+    single-field unique index of `schema`.
+  - `Procedure.spec.target: { schema, id, version? }` names a `ref`
+    handler's operation target: `id` and `version` are input property names.
+    It is rejected on builtin handlers, whose target is already derivable.
+  - Queries, notifications and multi-entity Procedures declare no target.
+- `lockedCollection()` stays a diagnostic heuristic.
+- SQL Views are not bound automatically until a validated output contract
+  admits them.
+- **View purpose (D5, #1115):** `View.spec.description` is added and projected
+  into the View tool description.
+
+### 8. Snapshot and version (D2)
+
+- Public and member snapshots are read only through declared, parameterized
+  Views.
+- Staff snapshots use a bounded single-entry read offered only for
+  collections that are the target of a declared interaction. Other staff
+  reads go through Views. This limits which records flow into a model
+  provider's context.
+- The version bound to an operation is the version the human saw. A newer
+  read is shown as "changed since the list" and requires a deliberate re-read
+  and review; it never rebinds silently. Background refresh never replaces
+  user edits.
+- Conflicts preserve user input. Uncertain writes (timeout, abort) are not
+  retried; the controller reconciles first.
+
+### 9. Projection ownership (D8)
+
+- Spec resolves D4 declarations during link. The RuntimePlan compiler emits
+  interaction descriptors (`plan.interactions`); this advances
+  `RUNTIME_PLAN_VERSION`.
+- The capability catalog, Admin operations and the web client all read
+  `plan.interactions`. HTTP-only staff Procedures never enter an MCP
+  projection.
+- Admin's inference is kept for one minor release. When an operation is bound
+  only by inference, Admin logs one deprecation warning pointing to
+  `Procedure.spec.target`. The next minor removes the inference.
+- Dynamic availability is advisory. No mutating handler runs to infer
+  availability.
+
+### 10. MCP Apps
+
+Implemented the way the official `add-app-to-server` and `create-mcp-app`
+skills describe:
+
+- `mantle-mcp` registers `ui://` resources with `registerAppResource` and
+  interaction tools with `registerAppTool` and `_meta.ui.resourceUri`.
+  App-only helpers use `_meta.ui.visibility: ["app"]` and are read-only.
+- Negotiation uses `getUiCapability`, per request. A 2026-07-28 request, or a
+  2025-era `initialize`, that declares no MCP Apps support gets no `_meta.ui`,
+  no resources and no app-only tools; everything else is unchanged.
+- A stateless 2025-era request after `initialize` carries no client
+  capabilities. It is treated as possibly supporting MCP Apps: it gets the App
+  metadata and the app-only tools, so hosts with MCP Apps can call them on
+  every request. Hosts without MCP Apps ignore the metadata but may list the
+  app-only tools to the model. This is why app-only tools must be declared
+  read-only.
+- Each surface is its own `McpServer`; staff resources never appear on public.
+- Resources hold reusable assets only: no caller data, no bearer. Per-call data
+  travels in `structuredContent`. Every app tool keeps its text `content`.
+- Opening an interaction is read-only; a mutation is always a separate
+  explicit `tools/call`. Canonical Admin keeps refusing framing.
+- **Preview (D10):** a staff-only, read-only, app-only `preview_entry` tool,
+  offered only when a Web renderer is mounted, returns the rendered HTML in
+  `structuredContent` under bearer authorization. The app shows it in a
+  sandboxed `srcdoc` iframe without `allow-same-origin`. The response is
+  `no-store` and the HTML never enters a shared resource.
+- **Hosts (D6):** CI runs the official `basic-host` and
+  `@modelcontextprotocol/client`; Claude and ChatGPT are verified manually per
+  release of this feature. No identical behavior across hosts is assumed.
+
+### 11. Human approval (D3)
+
+Deferred. UI confirmation and app-only visibility do not prove a human
+decision (Context 10). The handbook documents the pattern that works today: a
+`readOnly: true` Schema blocks generic writes, and an approval Procedure with
+only an HTTP Trigger and a `ctx.staff` requirement appears in Admin but in no
+MCP catalog. A test asserts an MCP-audience token cannot call an HTTP
+Trigger. Any future Core mechanism is enforced at the server boundary and
+binds target, input and version.
+
+### 12. Presentation boundary
+
+Renderer registries and `uiSchema` carry presentation only. Target, input
+mapping, authorization, side effects and version semantics are never declared
+there.
+
+## Consequences
+
+- One validated interaction definition drives Admin, application frontends
+  and chat hosts. Admin becomes a consumer of binding rules.
+- Applications that do not use MCP no longer carry any MCP code in Runtime.
+  Applications that do add `@aotter/mantle-mcp` and its SDK dependency;
+  measured on a minimal Worker, SDK plus zod is about 82 KiB gzip without Ajv.
+- MCP business errors change from JSON-RPC errors to `isError` results
+  (`breaking-change`), announced when adapters cut over.
+- Manifests that need entity-bound interactions for `ref` handlers or non-id
+  references adopt the D4 declarations. The sealed plan version advances, so
+  applications rerun `mantle generate`.
+- Hosts without MCP Apps support see only the additive `structuredContent`
+  and `outputSchema`.
+
+## Alternatives
+
+- **Keep the hand-written dispatcher and add MCP Apps to it.** Duplicates
+  the SDK, stays on one protocol version, and diverges from the official
+  ext-apps helpers.
+- **Validate in both the SDK and Runtime.** Two error shapes for one mistake,
+  and Ajv in every Worker.
+- **Put MCP Apps in Runtime with an injected provider.** Makes Runtime own a
+  protocol extension; the SDK already owns resources.
+- **More packages** (separate controller, kit, app packages). Three
+  versioning surfaces for one feature; subpaths give the same boundaries.
+- **Each surface derives relations itself.** Status quo; inconsistent.
+- **Bindings in `uiSchema` or an SDK-side registry.** A second, unvalidated
+  Manifest; rejected by #1109.
+- **Embed canonical Admin.** Requires weakening framing and cookie policy.
+- **Promote `lockedCollection()` to the execution contract.** A reference does
+  not prove mutation or locking.
+
+## How to apply
+
+Work follows epic #1110 as stacked PRs:
+
+1. #1126, #1127 — dispatcher factory; `structuredContent` and `outputSchema`.
+2. #1129 — `CapabilityCatalog` and `InvokeCapabilityUseCase`.
+3. #1130 — `@aotter/mantle-mcp`.
+4. #1131 — adapters, Admin and templates cut over; hand-written dispatcher
+   deleted.
+5. #1115, #1116 — grammar-revise; then #1120 interaction descriptors.
+6. #1121 — MCP Apps registration; #1122, #1123, #1124 — `@aotter/mantle-ui`;
+   #1125 — preview; #1119 — host matrix.