@aotter/mantle 0.0.11-alpha.73 → 0.1.0-alpha.10

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

@@ -0,0 +1,204 @@
+# ADR-0019: Seal the manifest-to-runtime pipeline
+
+**Status:** Accepted
+
+**Date:** 2026-08-16
+
+**Related:** [#656](https://github.com/aotter/mantle/issues/656),
+[#662](https://github.com/aotter/mantle/issues/662),
+[#546](https://github.com/aotter/mantle/issues/546), ADR-0008, ADR-0009,
+ADR-0011, ADR-0018
+
+## Context
+
+Mantle already has an adapter-neutral runtime package and structured
+diagnostics, but its real execution boundary is still the complete Cloudflare
+site product. Authored YAML is parsed into an ordinary `Manifest[]`; validation,
+defaulting, lookup construction, boot checks, SQL compilation, storage setup,
+public rendering, and Admin helpers then overlap across spec, runtime, and the
+Cloudflare adapter.
+
+That overlap creates two portability failures:
+
+1. A downstream caller can bypass an earlier stage and reinterpret raw
+   manifests, so a rule or default can have more than one owner.
+2. Embedding the runtime also selects SQL-shaped storage, public Web behavior,
+   Admin assets, and Cloudflare-oriented boot conventions.
+
+The product needs one embeddable Core that can be called directly by an
+existing application, with Web, Admin, and platform integrations selected
+downstream. The migration cannot introduce a permanent `v2` pipeline beside
+the current one: every compatibility path must delegate forward and be deleted
+within the same milestone.
+
+## Decision
+
+### One sealed pipeline
+
+Mantle has one supported semantic path:
+
+```text
+ManifestSourceSet
+  -> parse + normalize
+  -> ParsedManifestSet
+  -> link
+  -> LinkedManifestSet
+  -> compile
+  -> RuntimePlan
+  -> prepare deployment
+  -> PreparedRevision
+  -> bind runtime
+  -> MantleRuntime
+```
+
+Decode may remain an internal parser step. The public contract starts with
+caller-supplied sources and ends with a programmatic runtime. A failed stage
+does not produce a usable value for the next stage.
+
+Parse, link, and compile are pure and deterministic. Their sealed outputs may
+be constructed only by their owning package, apart from explicit test fixture
+helpers. Source locations remain authored metadata; they do not affect the
+semantic fingerprint.
+
+### One owner per invariant
+
+| Stage | Owns | Must not own |
+|---|---|---|
+| Parse + normalize | YAML syntax/alias limits, closed four-atom shape, primitive and atom-local rules, behavior-affecting defaults, source metadata | Cross-atom references, handlers, storage, optional routes |
+| Link | Duplicate symbols, cross-atom references, guard graphs, translations, manifest-owned route/tool collisions | I/O, selected modules, handler availability |
+| Compile | Immutable lookup records, authorization plans, Trigger indices, Procedure descriptors, logical View plans, semantic fingerprint | Connections, repositories, handlers, requests, templates, assets |
+| Prepare | Selected storage migrations/indexes/native Views, handler availability, selected capability/route checks, readiness revision | YAML interpretation or request execution |
+| Bind/invoke | Semantic ports, handler dispatch, parameter binding, centralized authorization, content/View/Procedure/Trigger/lifecycle operations | DDL, route mounting, assets, HTTP/session/cache policy |
+| 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).
+
+### Core and optional products
+
+`@aotter/mantle-spec` owns source, parse, normalize, link, introspection, and
+manifest-derived code generation. It has no runtime or platform dependency.
+
+`@aotter/mantle-runtime` owns `RuntimePlan`, preparation contracts, semantic
+storage ports, and `MantleRuntime`. The portable runtime input is prepared
+semantic storage, not `DatabaseDriver`. It has no Web, Admin, Cloudflare, Bun,
+or Vercel dependency.
+
+`@aotter/mantle-web` is optional and owns the official public HTML, Markdown,
+`llms.txt`, sitemap, SEO, preview, template, and public-path composition.
+Applications still own their router, URLs, navigation, and design. Platform
+adapters own HTTP mounting and cache behavior.
+
+`@aotter/mantle-admin` is optional and owns Admin API/application
+orchestration and its asset contract. `@aotter/mantle-admin-ui` remains the UI
+artifact. Core supplies content operations and authorization but does not
+serve the UI or reserve Admin paths when the module is absent.
+
+Cloudflare, Bun, and Vercel packages bind platform storage, lifecycle,
+request/session, cache, and asset concerns. They may expose convenience
+facades, but those facades compose the same Core and selected modules.
+
+### Storage and Views
+
+Preparation accepts a selected storage adapter and produces semantic ports,
+including existing content repositories/readers and a `ViewQueryExecutor`.
+Concrete D1/SQLite drivers and SQL repositories remain implementation details.
+An existing application may either pass its already-owned database/client to
+an official adapter or implement the semantic ports over its own tables.
+
+Declarative Views compile to logical plans once. Storage preparation lowers
+those plans to native queries. The v0.1 `View.spec.sql` form remains explicitly
+SQLite-only and is rejected by unsupported storage during preparation; Mantle
+does not guess a translation and does not add a universal query driver.
+
+### Naming and code generation
+
+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
+one preparation attempt to Runtime. Generated code never caches, retries,
+mounts routes, or owns host lifecycle. The bound API retains its raw `runtime`
+so typed projection does not hide lower-level Core capabilities. It emits
+deterministic lower-camel identifiers while preserving manifest wire names
+internally. Identifier collisions are errors.
+
+Code generation is never required by the runtime and never copies Web or Admin
+assets. Dynamic/string-based calls remain the escape hatch for JavaScript and
+runtime-defined consumers.
+
+### Migration rule
+
+Issues #663 through #673 move ownership in pipeline order. At every step:
+
+- existing callers may use a temporary wrapper only if it delegates to the new
+  owner;
+- no rule, default, query compiler, authorization evaluator, or router is
+  implemented twice;
+- the old owner and its obsolete tests are deleted when its last caller moves;
+- exact packed consumers, not workspace links, are the final compatibility
+  gate.
+
+Breaking API changes from the `v0.1.0-alpha.7` contract are allowed in the
+0.1.2 milestone. Migration notes should keep old projects mechanically
+adaptable, but downward compatibility is not a reason to retain a second stack.
+
+## Consequences
+
+### Positive
+
+- Human and agent authors get one deterministic path and one diagnostic owner.
+- Existing applications can embed Core without surrendering process, router,
+  database, or transaction ownership.
+- Web, Admin, and each platform can evolve without entering Core.
+- Performance work happens once per semantic revision instead of per request.
+- Compatibility code has a defined deletion point.
+
+### Negative
+
+- 0.1.2 intentionally breaks parts of the alpha.7 API.
+- Cloudflare's current convenience facade must be decomposed and then
+  reassembled from optional modules.
+- Downstream projects must update generated imports and runtime construction.
+- Exact consumer tests are required across more than one platform.
+
+## Alternatives
+
+### Keep `Manifest[]` as the shared contract
+
+Rejected. It cannot prove that defaults, references, and plans were evaluated
+once, and it lets every downstream package rebuild semantic state.
+
+### Generalize `DatabaseDriver` for every database
+
+Rejected. Its SQL/D1 shape is not a useful MongoDB or application-domain
+contract. Existing semantic repository ports are the smaller portable seam.
+
+### Add a plugin/provider framework
+
+Rejected. Ordinary package dependencies, exported mount functions, and narrow
+ports cover the known compositions. A registry would add a second architecture
+before a use case requires it.
+
+### Build a parallel Core v2 and migrate later
+
+Rejected. It duplicates rules and makes deletion optional. The migration is
+ordered specifically so each new owner replaces the old owner in place.
+
+## How to apply
+
+- Start a pipeline change at the current owner listed in the rule ledger.
+- Add one check at the new owner, route every caller through it, then delete the
+  old implementation and obsolete tests.
+- Reject runtime imports of raw manifests, Web/Admin packages, or platform
+  primitives once their migration issue closes.
+- Prefer current ports and native platform APIs; add a package only for a real
+  dependency/runtime boundary.
+- PR descriptions for #656 must state old owner, new owner, evidence, deleted
+  code, and any diagnostic timing change.
+
+## Implementation status
+
+Issue #662 records the current behavior, ownership ledger, consumer corpus, and
+performance baseline. Issues #663 through #674 execute the migration and final
+repository cleanup. The ADR is complete only when #673 removes every temporary
+compatibility path; #674 then updates contributor guidance to the final tree.

package/docs/adr/README.md

@@ -6,31 +6,33 @@ Records of *why* mantle ended up shaped this way. The numbering preserves POC AD
 
 | # | 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 (refreshed) |
+| [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) | Consumers own manifest YAML; the installed CLI emits the parser-free runtime module and handler types. Core ships no application manifests. | 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. CF impl + Netlify stub. | Accepted (new) |
+| [0011](0011-adapter-port-spec.md) | Adapter port spec. Required runtime ports plus optional feature ports. | Accepted (new) |
 | [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 for first launch by landing provision bundles. | Superseded |
-| [0014](0014-auth-better-auth-and-multi-tenant-mcp.md) | The Cloudflare adapter owns the curated Better Auth identity/session facade and top-level `@cloudflare/workers-oauth-provider` MCP transport. Both normalize verified callers 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 curated Better Auth 1.7 identity/OAuth/MCP authority with CIMD discovery. Verified callers are normalized into runtime context; mutable staff role and target authorization are re-evaluated per call. | Accepted + amended |
 | [0016](0016-site-semantic-layer.md) | Site semantic layer: `AGENTS.md` (cross-tool entry) + `.mantle/launch-state.json` (deterministic install context). The older `mantle/site.md` letter surface is suspended from first-run scaffolds. | Accepted (slimmed) |
 | [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. | Accepted for now |
+| [0019](0019-sealed-manifest-runtime-pipeline.md) | One sealed source-to-runtime pipeline, semantic storage seam, and optional Web/Admin/platform dependency direction. | Accepted |
 
 ## Reading order
 
 If you're new to the codebase:
 
 1. **0001** — what the 4 atoms are.
-2. **0009** — how consumers wire them in.
-3. **0007** — what running the SDK feels like as an AI author (and as the operator agent).
-4. **0011** — the boundary between the runtime and the adapter (most load-bearing for the rebuild).
-5. **0010** — how locale flows through the system.
-6. **0013** — historical install-session context; current first launch is landing provision bundles plus repo-local handoff.
-7. **0002, 0008** — the two ADRs that touch every diagnostic and every binding.
+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. **0013** — historical install-session context; current first launch is landing provision bundles plus repo-local handoff.
+8. **0002, 0008** — the two ADRs that touch every diagnostic and every binding.
 
 ## What's NOT here (and why)
 
@@ -39,12 +41,12 @@ 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 vs DRAFT discipline → folded into ADR-0001 §"Future grammar discipline."
+- **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 `simple` only; `editorial` is a v0.1.x feature.
+- **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`. Editorial lifecycle remains v0.1.x-gated. Full shape spec lives in `docs/design-atoms.md`.
+- **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.
 
@@ -52,7 +54,7 @@ The rebuild's ADR-0011 (new) is the most load-bearing addition — the POC accum
 
 ## Contributing a new ADR
 
-1. Pick the next number (currently 0019).
+1. Pick the next number (currently 0020).
 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.

package/docs/api-mcp-authorization.md

@@ -78,9 +78,66 @@ Missing/invalid credentials return `401`; a verified caller missing a required
 role or scope returns `403`; a site guard may return
 `ENTITLEMENT_REQUIRED`/`402`. Guards run on every call and are not cached.
 
+### Identity-bound Views
+
+Use the closed `{ "$ctx.user": "id" }` filter sentinel for rows owned by the
+current site-local Better Auth user. The caller never supplies this value, so
+the same View is safe on both REST and public MCP:
+
+```yaml
+apiVersion: cms.mantle.aotter.net/v1
+kind: Schema
+metadata: { name: orders }
+spec:
+  schema:
+    type: object
+    properties:
+      userId: { type: string, x-mantle-bind: ctx.user }
+      orderNumber: { type: string }
+      orderStatus: { type: string }
+      totalMinor: { type: integer }
+      placedAt: { type: integer }
+  indexes: [[userId, placedAt]]
+---
+apiVersion: cms.mantle.aotter.net/v1
+kind: View
+metadata: { name: my-orders }
+spec:
+  surface: public
+  from: orders
+  requires:
+    auth:
+      all: [ctx.user]
+  filter:
+    and:
+      - { eq: { field: status, value: published } }
+      - { eq: { field: userId, value: { "$ctx.user": id } } }
+  fields: [orderNumber, orderStatus, totalMinor, placedAt]
+  orderBy: [{ field: placedAt, direction: desc }]
+  limit: 50
+```
+
+Core rejects this sentinel unless the View requires `ctx.user` and the bound
+field is the leftmost field of a declared Schema index. Missing identity fails
+with `401`; it never drops the filter or falls back to all rows. REST exposes
+`GET /api/views/my-orders`; public MCP exposes `query_view_my_orders`. Both
+call `ExecuteViewUseCase` and bind the same `ctx.user.id`.
+
+The id belongs to the customer site's Better Auth user row. It is not a
+Mantle Platform user id, Hosted Auth upstream subject, email, or provider id.
+Hosted Auth may establish the site session, but Platform is not part of the
+View query path.
+
+## Site OAuth symmetry
+
+A site-issued OAuth access token represents the same caller on public MCP and
+manifest HTTP routes. Both surfaces populate `ctx.user` and `ctx.auth` from the
+same token grant; expiry, revocation, scope, client, and resource audience are
+enforced before the Procedure or View runs.
+
 ## Cloudflare consumer wiring
 
-Pass one site-owned resolver to `createCmsRef`. Return `not-handled` when the
+Pass one site-owned resolver to `createMantleRuntimeRef`. Return `not-handled` when the
 request is not one of the site's credential formats, `invalid` when it is a
 recognized but bad/revoked credential, and `verified` only after checking the
 authoritative site record.
@@ -163,55 +220,31 @@ function parseScopes(json: string): string[] | null {
 }
 ```
 
-Wire it alongside the existing Auth facade. `oauthBearer` is optional and
+Wire it alongside the existing Auth facade. `jwtBearer` is optional and
 enables JWT bearer verification for manifest REST routes:
 
 ```ts
 import {
-  AssetsAssetServer,
-  createCmsRef,
-  createMcpApiHandler,
-  createOAuthProvider,
-  D1DatabaseDriver,
-  KvCacheBinding,
-  mountServerEndpoints,
+  createMantleWorker,
 } from "@aotter/mantle/cloudflare";
 
-const runtimeRef = createCmsRef({
-  manifests,
+export default createMantleWorker({
+  plan,
   handlers,
-  bindings: {
-    db: new D1DatabaseDriver(env.DB),
-    kv: new KvCacheBinding(env.KV),
-    assets: env.ASSETS
-      ? new AssetsAssetServer(env.ASSETS)
-      : { fetch: async () => null },
-  },
-  auth,
-  credentialResolver: siteCredentialResolver(env.DB),
-  oauthBearer: {
-    audience: "https://api.example.com",
-    // Optional server-wide floor. Manifest scopes still run per target.
-    scopes: ["api"],
-  },
-});
-
-mountServerEndpoints(app, runtimeRef);
-
-const oauthProvider = createOAuthProvider({
-  defaultHandler: {
-    fetch: (request, workerEnv, ctx) => app.fetch(request, workerEnv, ctx),
-  },
-  apiHandlers: {
-    "/mcp/staff": createMcpApiHandler({ ref: runtimeRef, surface: "staff" }),
-    "/mcp": createMcpApiHandler({ ref: runtimeRef, surface: "public" }),
-  },
-  scopesSupported: ["mcp"],
+  extend: ({ env }) => ({
+    credentialResolver: siteCredentialResolver(env.DB),
+    jwtBearer: {
+      audience: "https://api.example.com",
+      // Optional server-wide floor. Manifest scopes still run per target.
+      scopes: ["api"],
+    },
+  }),
 });
 ```
 
-Export or delegate to `oauthProvider` as the Worker's top-level handler so the
-OAuth provider can verify MCP bearers before dispatching to either MCP surface.
+The facade mounts both MCP surfaces behind the same Better Auth 1.7 resource.
+Low-level composition must pass that canonical resource to each
+`createMcpApiHandler` explicitly.
 
 Resolution precedence is site resolver, configured OAuth bearer, then cookie
 session. A recognized invalid credential never falls back to a valid cookie.
@@ -563,7 +596,7 @@ const providerAuth = createAuth({
     loginPage: "/sign-in",
     consentPage: "/consent",
     scopes: ["openid", "offline_access", "accounts:read"],
-    validAudiences: ["https://api.example.com"],
+    resources: ["https://api.example.com"],
   },
 });
 
@@ -574,9 +607,10 @@ const verification = await providerAuth.verifyOAuthAccessToken(request, {
 ```
 
 The verifier accepts JWT access tokens only and checks the configured issuer,
-JWKS/signature, audience, time claims, and required scopes. It returns only
-`userId`, `clientId`, `credentialId`, and scopes. Opaque tokens are rejected;
-there is no introspection fallback.
+JWKS/signature, audience, time claims, required scopes, and—when passed the
+request—DPoP proof binding with database-backed replay protection. It returns
+only `userId`, `clientId`, `credentialId`, and scopes. Opaque tokens are
+rejected; there is no introspection fallback.
 
 ## OpenAPI reflection
 

package/docs/auth-hosting-model.md

@@ -5,8 +5,10 @@ basic login. The split is:
 
 - **Mantle SDK** gives every generated site the primitives needed to
   run its own auth.
-- **Mantle starters** decide whether a generated site is wired for
-  self-hosted auth or as a client of Mantle Platform hosted auth.
+- **Mantle's conventional Cloudflare adapter** runs the generated site's
+  selected self-hosted or Mantle Platform hosted client configuration.
+- **Mantle starters** declare the mode and provider placeholders that landing
+  or the site owner completes.
 - **Mantle Platform** can sell hosted identity, provider setup, email,
   and billing convenience for site owners who do not want to operate
   those pieces.
@@ -92,7 +94,7 @@ customer-owned domain, hosted auth must use OAuth/OIDC:
 
 ```text
 customer.com/login
-  -> platform.mantle.tools/oauth/authorize
+  -> platform.mantle.tools/api/auth/oauth2/authorize
   -> user signs in with Platform-supported methods
   -> customer.com/api/auth/callback/mantle
   -> customer.com verifies the authorization response
@@ -117,10 +119,12 @@ Landing can probe Platform staff/session state, but provisioning's
 GitHub OAuth token is still Landing-owned unless a separate token
 handoff design is introduced.
 
-The generated site's hosted-auth client code belongs in the starter or
-a starter overlay. Core owns only the auth contract, normalized
-manifest/runtime credential vocabulary (`ctx.user`, `ctx.staff`, `ctx.auth`),
-guard orchestration, and curated Better Auth server primitives.
+The conventional hosted-auth client wiring belongs in Core's Cloudflare
+adapter. Starters declare its environment bindings; landing supplies an
+allocated client. A site can still replace Auth construction through
+`createMantleWorker({ auth })` when it needs a different curated identity
+design. Core continues to own the normalized manifest/runtime credential
+vocabulary (`ctx.user`, `ctx.staff`, `ctx.auth`) and guard orchestration.
 
 ## API and MCP Authorization
 
@@ -154,10 +158,10 @@ The cross-site API use case additionally justifies these curated fields and
 facades:
 
 - generic OAuth method `resource`
-- OAuth provider `validAudiences`
+- OAuth provider `resources` and the curated `mcpResource`
 - `Auth.getProviderAccessToken(request, providerId)`
 - `Auth.verifyOAuthAccessToken(tokenOrRequest, { audience, scopes })`
 
-All are additive. Existing generated sites that do not pass them keep their
-previous cookie, session, and REST behavior. These are not a raw Better Auth
-options passthrough.
+Generic OAuth providers use Better Auth 1.7's standard social sign-in and
+`/api/auth/callback/:id` path. These are not a raw Better Auth options
+passthrough.

package/docs/cloudflare-low-level-composition.md

@@ -8,18 +8,20 @@ while adding one application-owned post-response Queue audit across every route.
 ```ts
 import { Hono } from "hono";
 import {
-  createCmsRef,
+  applyCachePolicy,
+  conventionalMcpResource,
+  createMantleRuntimeRef,
   createConventionalAuth,
   createConventionalBindings,
   createMcpApiHandler,
-  createOAuthProvider,
   mountAuthorize,
-  mountServerEndpoints,
+  mountAdmin,
+  mountRuntimeEndpoints,
   runMantleWorkerRequest,
   setupIncompleteAuthResponse,
   type MantleCloudflareEnv,
 } from "@aotter/mantle/cloudflare";
-import { manifest } from "../.mantle/generated/site.js";
+import { plan } from "../.mantle/generated/mantle.js";
 
 interface Env extends MantleCloudflareEnv {
   readonly AUDIT_QUEUE: Queue<{
@@ -50,30 +52,40 @@ export default {
 function assemble(env: Env) {
   const bindings = createConventionalBindings(env);
   const auth = createConventionalAuth(env);
-  const ref = createCmsRef({ manifests: manifest, bindings, auth });
+  const ref = createMantleRuntimeRef({ plan, bindings, auth });
   const app = new Hono<{ Bindings: Env }>();
 
-  mountServerEndpoints(app, ref);
-  mountAuthorize(app, { auth, loginPath: "/admin/sign-in" });
+  mountRuntimeEndpoints(app, ref);
+  if (bindings.adminAssets) mountAdmin(app, ref, bindings.adminAssets);
+  mountAuthorize(app, { auth });
   app.get("/cache-probe", () => new Response("public", {
     headers: { "cache-control": "public, s-maxage=60" },
   }));
 
-  const provider = createOAuthProvider<Env>({
-    defaultHandler: {
-      fetch: (request, workerEnv, ctx) => app.fetch(request, workerEnv, ctx),
+  const resource = conventionalMcpResource(env);
+  const mcp = new Map([
+    ["/mcp/staff", createMcpApiHandler<Env>({ ref, surface: "staff", resource })],
+    ["/mcp", createMcpApiHandler<Env>({ ref, surface: "public", resource })],
+  ]);
+  return {
+    auth,
+    async fetch(request: Request, workerEnv: Env, ctx: ExecutionContext) {
+      // Low-level owners must prepare the canonical D1 schema before Better
+      // Auth handles a token, client, consent, or CIMD request.
+      await ref.get();
+      const handler = mcp.get(new URL(request.url).pathname);
+      const response = handler?.fetch
+        ? await handler.fetch(request, workerEnv, ctx)
+        : await app.fetch(request, workerEnv, ctx);
+      return applyCachePolicy(request, response);
     },
-    apiHandlers: {
-      "/mcp/staff": createMcpApiHandler<Env>({ ref, surface: "staff" }),
-      "/mcp": createMcpApiHandler<Env>({ ref, surface: "public" }),
-    },
-  });
-  return { auth, fetch: provider.fetch.bind(provider) };
+  };
 }
 ```
 
-Keep the conventional `DB`, `KV` and `OAUTH_KV` bindings and
-`nodejs_compat`; add the Queue producer in `wrangler.jsonc`:
+Keep the conventional `DB` binding and `nodejs_compat`. CIMD metadata fetches
+also require `global_fetch_strictly_public`; add the Queue producer in
+`wrangler.jsonc`:
 
 ```jsonc
 {