@aotter/mantle 0.0.11-alpha.63 → 0.0.11-alpha.64

package/docs/adr/0009-consumer-supplied-manifests.md

@@ -1,270 +1,143 @@
 # ADR-0009: Consumer-supplied manifests at SDK boot
 
-**Status:** Carried over from POC v0.0.x; refreshed for v0.1.0.
+**Status:** Carried over from POC v0.0.x; amended for the parser-free v0.1
+consumer boundary.
 
-**Date**: 2026-05-01 (POC); refreshed 2026-05-03 for v0.1.0 rebuild
+**Date:** 2026-05-01 (POC); last amended 2026-08-03
 
-**Deciders**: phsu
-
-**Related**: [ADR-0001](0001-four-atom-manifest-model.md) (the manifest model whose authoring path this ADR opens to consumers), [ADR-0007](0007-ai-as-primary-author.md) (the AI-author DX this unblocks at the per-project layer)
-
----
+**Related:** [ADR-0001](0001-four-atom-manifest-model.md),
+[ADR-0007](0007-ai-as-primary-author.md),
+[ADR-0018](0018-core-starters-repository-boundary.md)
 
 ## Context
 
-The 4-atom manifest model ([ADR-0001](0001-four-atom-manifest-model.md))
-promises that "anything more domain-shaped is composed in the
-consumer's project." For that promise to hold, the SDK has to accept
-manifest content from the consumer rather than baking any in itself.
-
-The natural failure mode — and the one this ADR forecloses — is the
-SDK shipping with a fixed manifest set hand-maintained inside the
-package (e.g. a TS string mirror of starter YAML files compiled into
-the SDK bundle). A consumer who wants a `comments` Schema, a
-`like-post` Procedure, or a cron Trigger then has two bad options:
-
-1. Edit the embedded set inside the SDK (forks the SDK; loses upgrades), or
-2. Wait for a future SDK release that ships the manifest they want.
-
-Either option is incompatible with the AI-as-primary-author contract
-([ADR-0007](0007-ai-as-primary-author.md)): the AI is
-working *inside the consumer's project*, not inside the SDK monorepo.
-It cannot extend the SDK without a fork-and-publish loop that has none
-of the three feedback loops the contract guarantees.
+The four-atom model promises that domain shape is authored in the consumer's
+project. Core therefore cannot ship a fixed manifest set: doing so would force
+every new Schema, View, Procedure, or Trigger through an SDK fork/release.
 
-Consumer-supplied manifests are the path that keeps the 4-atom model
-a property of *the SDK* rather than of *whatever starter the SDK
-ships*.
+The first v0.1 implementation imported YAML as Wrangler Text modules and parsed
+it during Worker startup. That kept ownership correct but leaked authoring-only
+YAML machinery into the runtime bundle and coupled consumers to Wrangler
+`[[rules]]`. The public CLI now provides one build-time compilation boundary.
 
 ## Decision
 
-The SDK's mount factory accepts manifest YAML text passed in by the
-consumer. The SDK ships **zero** embedded manifests; the registry is
-built exclusively from what the consumer passes. The resulting
-registry feeds `createCmsRuntime(...).bootInit()`, the HTTP Trigger
-mounts, the View executor, and the MCP tool catalog.
+Consumers own YAML under `manifests/`. The installed `mantle` CLI parses and
+validates that YAML, then writes the machine-owned runtime module and handler
+types:
 
-```ts
-export interface CmsConfig {
-  /** Procedure handlers keyed by `Procedure.spec.handler.ref`. */
-  readonly handlers?: Readonly<Record<string, AnyHandler>>;
-  /** Parsed consumer-authored manifests. Starters usually import YAML
-   *  as text via Wrangler rules and call `parseManifestsOrThrow()`
-   *  before passing them to the adapter. */
-  readonly manifests: readonly Manifest[];
-}
+```bash
+pnpm exec mantle generate
+pnpm exec mantle generate --check
 ```
 
-The consumer's config file remains `src/mantleConfig.ts` (unchanged
-from v0.0.x). YAML manifests are imported as **Text modules** via
-Wrangler's `[[rules]]` block — the standard CF Workers mechanism for
-bundling text assets into a Worker without a codegen step:
+The outputs are:
+
+- `.mantle/generated/site.ts` — a parser-free `readonly Manifest[]` export;
+- `.mantle/generated/types.d.ts` — handler declarations derived from the same
+  validated manifest set.
+
+The Worker imports the generated array rather than YAML text:
 
 ```ts
-// consumer's src/mantleConfig.ts
-import postsYaml from "../manifests/posts.yaml";
-import contactYaml from "../manifests/contact.yaml";
-import { sendContactMessage } from "./handlers/send-contact-message.js";
-
-export const cmsConfig: CmsConfig = {
-  manifests: [postsYaml, contactYaml],
-  handlers: { "send-contact-message": sendContactMessage },
-};
-```
+import { createMantleWorker } from "@aotter/mantle/cloudflare";
+import { manifest } from "../.mantle/generated/site.js";
 
-```toml
-# wrangler.toml — bundle every manifests/*.yaml as text
-[[rules]]
-type = "Text"
-globs = ["**/*.yaml"]
-fallthrough = true
+export default createMantleWorker({ manifest });
 ```
 
-A small ambient `yaml.d.ts` declaration tells TypeScript that
-`*.yaml` imports resolve to a string. The contract the SDK consumes
-is just "an array of YAML strings"; how the consumer's bundler
-produces them is their choice.
+Low-level composition passes the same array as `CmsConfig.manifests`. Core and
+adapters ship zero application manifests. The registry, boot validator, View
+executor, HTTP/MCP mounts, and tool catalog are built only from the consumer's
+generated array.
 
-### Adapter scope for v0.1.0
+`mantle generate --check` must gate validation/deploy so authored YAML cannot
+drift from checked-in generated output. Generation never edits YAML, handlers,
+skills, package metadata, styles, or provider configuration.
 
-The Cloudflare adapter (`@aotter/mantle-cloudflare`) is the
-only shipping adapter in v0.1.0, so the Text-import-via-`[[rules]]`
-pattern is the canonical path. When other adapters (Netlify, etc.)
-ship, they will need their own equivalent text-import mechanism, but
-the SDK boundary remains unchanged: an array of YAML strings in,
-parsed registry out.
+### Adapter scope
 
-### Single-slice ship
+Compilation is adapter-independent and uses Node at author/build time. The
+Worker runtime receives plain typed objects, so Cloudflare needs no YAML Text
+module rule and a future adapter needs no equivalent bundler hook.
 
-The grammar lock applies to the spec shape, not to how the SDK ships
-internally. v0.1.0 lands consumer-supplied manifests as the only
-path from day one — no embedded fallback, no deprecation window, no
-override semantics. This is a fresh build with no existing v0.1.x
-deployments to migrate.
+### Single authority
 
-This means:
-- The mount factory requires `manifests` to be passed in for any
-  Schema / View / Trigger functionality. Calling it without manifests
-  yields an admin-only Worker (no Schema, no View, no Trigger), with
-  the boot validator surfacing the empty set as a warning.
-- No conflict policy is needed: the SDK ships no manifests, so there
-  is no merge surface where an override could disagree with a default.
+YAML remains the authored source of truth. Generated TypeScript is a
+deterministic transport artifact and must not be hand-edited. Parser
+diagnostics point to the consumer manifest document/pointer before generation;
+runtime boot validation covers cross-manifest and registered-handler facts.
 
 ## Worked example
 
-The v0.1.0 starter ships at `starters/blog/manifests/` and is the
-canonical example consumers copy from. It demonstrates the full
-pattern: a `posts` Schema, a `contact` multi-doc Procedure + Trigger,
-the `[[rules]] type = "Text"` block in `wrangler.toml`, the ambient
-`yaml.d.ts`, and the `src/mantleConfig.ts` file that wires manifests
-+ handlers into the SDK. The blog `SKILL.md` walks AI install agents
-through the sequence.
+The external [`aotter/mantle-starters`](https://github.com/aotter/mantle-starters)
+repository owns the blank project and typed overlays. Materialized projects
+carry their own `manifests/`, generated module, handlers, and package scripts;
+they consume the exact packed Core artifact rather than a workspace link.
 
 ## Consequences
 
-### Pros
-
-- Consumers can compose all four atoms in their own project per the
-  ADR-0001 promise. The 4-atom model is a property of the SDK, not
-  of the starters.
-- The static-validation feedback loop (`mantle validate`) reads
-  from a `manifests/` directory in the consumer's project; the
-  validate path is uniformly applicable to consumer-authored
-  manifests across all four feedback loops.
-- The SDK bundle ships no manifest content. Consumers who don't need
-  a given starter's atoms (e.g. a docs site that only uses
-  `posts`-shaped content) don't pay for unrelated atoms.
-- Text-imported YAML keeps manifests as the YAML source-of-truth on
-  disk — no codegen step in the build, no parser drift between
-  author-time YAML and runtime parse. Multi-doc YAML grouping
-  ([ADR-0001](0001-four-atom-manifest-model.md) §"Authoring shape: multi-doc YAML")
-  is preserved end-to-end.
-- The MCP tool catalog automatically picks up the consumer's atoms —
-  no separate registration call. The consumer adds a `comments` Schema
-  and the operator agent sees `create_draft_comments` /
-  `update_draft_comments` on the next deploy.
+### Benefits
+
+- Consumers can compose all four atoms without forking or publishing Core.
+- One CLI parse/validation path drives runtime objects and handler types.
+- Worker bundles do not include the YAML parser or consumer YAML text imports.
+- Every REST/MCP catalog automatically reflects the generated consumer set.
+- Other adapters consume the same `readonly Manifest[]` with no filesystem or
+  bundler-specific manifest loader.
 
 ### Costs
 
-- The consumer project carries a `manifests/` directory, a
-  `wrangler.toml` `[[rules]]` block, and a `src/yaml.d.ts` ambient
-  declaration. The install agent has these files to copy and one
-  more import to wire (the blog `SKILL.md` covers the sequence).
-- Text imports for YAML are a property of the consumer's build
-  system, not the SDK. Consumers using a non-standard build need to
-  ensure their bundler resolves `*.yaml` to a string. This is a
-  documentation issue, not a contract change — alternative paths
-  (codegen, embedded literal, fetch from KV) all work the same way
-  at the SDK boundary as long as they yield a string.
-- Boot validation needs to surface "the consumer wrote invalid YAML"
-  clearly. The diagnostic's `path` field references the consumer
-  file (e.g. `consumer-manifest:[2]#/spec/...`) so deploy logs point
-  at the right file.
-
-### Risks
-
-- **Build-step coupling.** Text imports depend on the consumer's
-  bundler. If a future Wrangler version changes the `[[rules]]`
-  surface the docs need updating. Mitigation: spec the import
-  contract loosely — "a string carrying the YAML text" — so any
-  other path (codegen, embedded literal, `fetch` from KV) works the
-  same way at the SDK boundary.
-- **Manifest drift between dev and prod.** The consumer edits a YAML
-  file; until they re-run `wrangler deploy`, the runtime keeps
-  serving the previous bundle. This is the existing Worker dev-loop;
-  the validate CLI catches the static checks pre-deploy and the
-  boot validator catches handler-ref mismatches at deploy. No new
-  risk; just call out in the docs that "rebuild required after
-  manifest edit."
-- **Multi-tenant deployments amplifying conflict.** A single Worker
-  running multiple tenants would want each tenant's manifests
-  isolated. The atom model has no `namespace` field
-  ([ADR-0001](0001-four-atom-manifest-model.md)) on purpose —
-  multi-tenancy lives in the consumer app layer with `tenant_id`
-  columns. Consumer-supplied manifests don't change this; the SDK
-  still sees one flat manifest set per Worker. Multi-tenant
-  SaaS-on-this-CMS is a separate design question.
-- **Manifest set growth.** A large consumer (50+ Procedures, 20+
-  Schemas) makes per-file imports verbose. Mitigation: a future
-  ergonomic helper (`loadManifestsFromGlob`) can be added without
-  changing the SDK contract — the contract is "pass an array of YAML
-  strings"; how the consumer assembles the array is their choice.
+- Projects keep deterministic generated files and must run `generate` after
+  editing YAML.
+- CI/deploy must run `generate --check`; otherwise an old generated module can
+  outlive its source YAML.
+- Merge conflicts in generated output are resolved by re-running the installed
+  command, never by editing the artifact.
+
+### Risks and controls
+
+- **Version skew:** always run the generator from the installed package and
+  read its embedded docs. Do not generate a versioned project from `develop`.
+- **Hidden stale output:** keep `mantle generate --check` in the normal project
+  validation gate.
+- **Runtime/parser divergence:** generated objects come from the same parser
+  used by `validate`; focused packed-package tests compare the consumer output.
+- **Multi-tenancy pressure:** Core still sees one flat manifest set per Worker.
+  Tenant isolation remains an application concern; this ADR adds no namespace.
 
 ## Alternatives considered
 
-**(A) `manifests: readonly Manifest[]`** — pre-parsed manifest
-objects instead of YAML strings. Rejected: pre-parsing means the
-consumer must call `parseManifests` themselves, losing multi-doc
-YAML grouping unless they call it once per file. The SDK already
-parses YAML inside its boot pipeline; pushing parse responsibility
-to the consumer is unforced complexity. Diagnostic paths also
-degrade: parse errors surface as JS exceptions in consumer code,
-not as Diagnostic JSON tied to a file path.
-
-**(B) Filesystem-based manifest discovery** — SDK reads manifests
-from `process.cwd()/manifests/*.yaml` at boot. Rejected: Workers do
-not have a runtime filesystem. Even at build time, Wrangler doesn't
-provide a hook for the SDK to read consumer files — that's the
-consumer's bundler's job, which is exactly what Text-imported YAML
-is for.
-
-**(C) Separate `@aotter/mantle-manifests-<consumer>` package** —
-each consumer ships their manifests as an npm package; the SDK
-imports from `mantle-manifests-blog` etc. Rejected: 1:N package
-overhead for what should be a directory of YAML files. Tooling pain
-(versioning, publishing) for a layer that is fundamentally
-consumer-internal. Useful if a community emerges around shared
-manifest sets ("here's a forum schema as a package"), but YAGNI for
-the v0.1 baseline — that ergonomic can be added later by a wrapper
-that calls the mount factory with `pkg.manifests`.
-
-**(D) Embed manifests in the SDK and ignore the question** — ship
-the SDK with a fixed manifest set baked in. Rejected: fails the
-ADR-0001 promise and the AI-author contract. The SDK is supposed to
-be content-agnostic; making it content-prescriptive permanently is
-a strategic mistake.
-
-**(E) Override semantics for conflicts** — last-write-wins, with the
-consumer's manifest beating the SDK's. Rejected: only relevant if
-the SDK ships embedded manifests alongside consumer ones. With the
-SDK shipping zero manifests there is no conflict surface.
+**Runtime YAML Text imports.** Replaced. They require Wrangler-specific rules,
+ambient YAML modules, and ship authoring-only parse machinery in the Worker.
+
+**Runtime filesystem discovery.** Rejected. Workers have no runtime filesystem,
+and hidden discovery would make inputs and diagnostics less deterministic.
+
+**Application-specific manifest packages.** Rejected for the baseline. It adds
+publish/version overhead to files that belong in one consumer repo.
+
+**SDK-embedded manifests or override precedence.** Rejected. Core is
+content-agnostic, so there is no default manifest set and no merge policy.
 
 ## How to apply
 
-When proposing a new SDK feature that depends on knowing the
-manifest set (e.g. a new admin UI screen, a new MCP reflection
-method), assume the manifest set is consumer-owned. Don't hardcode
-collection names; iterate `getRegistry().schemas`. Don't assume the
-SDK knows about `posts`; it doesn't.
-
-When writing or reviewing the install agent's path, the agent must:
-1. Copy the relevant `starters/<name>/` contents into the consumer's
-   project. The starter is self-contained — `manifests/`,
-   `src/yaml.d.ts`, the `[[rules]] type = "Text"` block in
-   `wrangler.toml`, and `src/mantleConfig.ts` all come along.
-2. Wire `import postsYaml from "../manifests/posts.yaml"` (and
-   peers) in `src/mantleConfig.ts`. No `?raw` suffix needed —
-   Wrangler's text rule covers plain imports.
-3. Pass `manifests: [postsYaml, contactYaml, ...]` in the exported
-   `cmsConfig` object.
-
-The blog `SKILL.md` walks this sequence.
+When a Core feature needs the manifest set, accept the parsed consumer-owned
+array; never hardcode starter collection names or read consumer files at
+runtime.
+
+When authoring or reviewing a generated project:
+
+1. Edit YAML only under `manifests/`.
+2. Run the installed `pnpm exec mantle generate`.
+3. Import `manifest` from `.mantle/generated/site.js` into the conventional
+   Worker, or pass it as `CmsConfig.manifests` in low-level composition.
+4. Run `pnpm exec mantle generate --check` in validation and before deploy.
+5. Reject Wrangler YAML Text rules, runtime `parseManifests*` calls, or a second
+   manifest loader in a new generated project.
 
 ## Implementation status
 
-Accepted for v0.1.0. The implementation slice:
-
-- `CmsConfig` carries `manifests?: readonly string[]`.
-- The mount factory builds the registry from the consumer-supplied
-  YAML; no SDK fallback.
-- The `@aotter/mantle-cloudflare` package ships zero embedded
-  manifests.
-- The starter at `starters/blog/` is self-contained: `manifests/`,
-  `src/yaml.d.ts`, `wrangler.toml` `[[rules]]` block, and
-  `src/mantleConfig.ts` wiring it together.
-- Boot validator's `path` field on `INVALID_MANIFEST_ENVELOPE`-class
-  errors uses the consumer-supplied YAML index
-  (e.g. `consumer-manifest:[2]#/spec/...`) so deploy logs point at
-  the right file.
-
-Tracking: aotter/mantle.
+Implemented by the umbrella `mantle generate` command and the conventional
+Cloudflare Worker facade. Exact commands and output paths are documented in the
+version-matched `@aotter/mantle` README and embedded Core skills.

package/docs/adr/0012-views-as-public-rest.md

@@ -1,20 +1,26 @@
-# ADR-0012: Views as the public REST surface
+# ADR-0012: Views as named REST and MCP read surfaces
 
-**Status:** Accepted for v0.1.0. New ADR.
+**Status:** Accepted for v0.1.0. Amended to match the shipped public/staff
+surface and authorization contract.
 
-**Date:** 2026-05-05
+**Date:** 2026-05-05; amended 2026-08-03
 
 ## Context
 
 mantle ships two read-side surfaces and one write-side surface:
 
 - **Templates** (rendered HTML / Markdown / `llms.txt`) — composed by the consumer's `TemplateRegistry` from runtime APIs. The starter blog uses these for `/{locale}/posts/{slug}` etc.
-- **MCP tools** — agent-facing CRUD over the entry chokepoint. Every Schema gets `create_draft_<n>` / `update_draft_<n>` per-collection authoring tools plus generic tools (`list_entries`, `get_entry`, `request_publish`, `unpublish_entry`, `archive_entry`).
+- **MCP tools** — the staff surface exposes entry authoring and lifecycle
+  tools; both public and staff surfaces expose `query_view_<name>` for Views
+  assigned to that surface.
 - **HTTP Triggers** — write-side endpoints declared by the consumer (`Trigger.source.kind: http`, methods `POST | PUT | PATCH | DELETE` only). Per ADR-0001 grammar, **`GET` is intentionally absent** because read endpoints belong to Views, not Procedures.
 
 What was missing: a stable, consumer-facing **public REST read surface**. The starter blog had no JSON API at all. The CMS needed an answer to "I'm a downstream service that wants `posts` filtered by locale — how do I read?" without forcing every consumer to hand-write a route handler that re-implements filtering.
 
-This ADR answers that question: **every parsed View auto-exposes `GET /api/views/<view-name>`**, and Schemas do not get a public REST surface at all. Public reads always go through a named query.
+This ADR answers that question: **every parsed View is a named read surface**.
+Views default to public and auto-expose `GET /api/views/<view-name>` plus a
+matching public MCP tool. `surface: staff` moves both transports to the guarded
+staff surfaces. Schemas do not get a public REST surface at all.
 
 (Schemas remain available on the **admin** REST surface — `/admin/api/*` — which lands with the admin UI commit and is auth-gated to staff. That's a separate cut and out of scope here.)
 
@@ -34,13 +40,30 @@ No version prefix. `apiVersion: cms.mantle.aotter.net/v1` is the manifest-gramma
 
 `<view-name>` is `View.metadata.name` verbatim. Authors are free to pick kebab-case (`recent-posts`) or any URL-safe identifier; the runtime mounts the route as-is.
 
-### 3. Views auto-expose; opt-out is "don't write a View"
+### 3. Views auto-expose on one declared surface
 
-We considered adding `View.spec.expose: { rest: false }`. Rejected — the shape `View` already has IS "public read API". Authors who want a private named query write a TypeScript helper and call `runtime` directly from their template.
+`View.spec.surface` uses the closed `public | staff` vocabulary and defaults to
+`public`:
+
+- public Views mount at `GET /api/views/<name>` and appear as
+  `query_view_<name>` on `/mcp`;
+- staff Views mount at `GET /admin/api/views/<name>` behind the live staff-role
+  gate and appear only on `/mcp/staff`.
+
+The adapter filters the View set before constructing each MCP dispatcher, so a
+guessed public tool call cannot reach a staff View. `View.spec.requires` then
+applies the same static predicates and optional guard Procedure on REST and MCP
+calls. Surface selects transport visibility; authorization decides whether the
+verified caller may execute the View.
+
+We still reject a second `expose.rest` switch. A View is externally queryable
+on exactly one surface; internal-only helpers remain TypeScript code.
 
 ### 4. Pagination knobs are reserved query-string names
 
-Public callers pass `?page=<1-indexed>&show=<page-size>`. Internally the runtime emits `LIMIT show OFFSET (page-1)*show`.
+REST callers pass `?page=<1-indexed>&show=<page-size>`. MCP callers pass the
+same reserved names as tool arguments. Internally the runtime emits
+`LIMIT show OFFSET (page-1)*show`.
 
 `page` / `show` / `cursor` are reserved names. The parser rejects any `View.spec.params.properties.<name>` colliding with these (`VIEW_PARAMS_RESERVED_NAME`). The author owns the rest of the query-string namespace.
 
@@ -93,7 +116,7 @@ The required-only rule is a v0.1.0 simplification. v0.1.x will promote optional-
 
 `hasMore = (rows.length === effectiveShow)` — the lazy semantics. We do **not** issue a separate `COUNT(*)` query, and we do not pull `LIMIT n+1` to probe. If the server returns exactly `show` rows, the caller may or may not have more; if fewer, we know definitively. The trade is one false-positive on the boundary case (caller asks for next page, gets empty) in exchange for no extra round-trip per request.
 
-### 7. Param coercion happens at the adapter boundary
+### 7. Param coercion happens at the transport boundary
 
 Query strings arrive as strings; `View.spec.params` declares the JSON Schema type. The Cloudflare adapter (`coerceViewParams` in `mountServerEndpoints.ts`) coerces per-property:
 
@@ -109,29 +132,34 @@ Required params not present → `400 INPUT_VALIDATION_FAILED`. Coercion failure
 
 ## Out of scope (deferred)
 
-- **MCP tools for Views.** MCP is for agents doing ops; readers don't need a separate MCP tool when they have a stable REST endpoint. Reconsider in v0.2 if downstream agent tooling demands it.
 - **`Trigger.target.view`** (lifecycle/projection triggers fired by Views). Tracked separately as a v0.2 grammar move.
 - **`spec.output.kind`** (declaring scalar / tree / tabular result shape per View). Lands with join + group-by support in v0.1.x.
 - **Optional param-ref drop semantics in the parser.** Runtime is already implemented; parser promotes when v0.1.x lands.
 - **DRAFT filter operators** (`contains` / `in` / `like` / `not`). v0.1 keeps comparison operators closed to `eq` / `gt` / `gte` / `lt` / `lte`; field-to-field comparisons remain out of scope.
-- **Auth on the public View REST surface.** v0.1.0 Views are public-read by definition. Member-gated reads land with the member system in v0.2.
+- **Row-level policy rewriting.** `requires` authorizes the whole View; it does
+  not inject per-row visibility predicates. Consumer-specific membership,
+  payment, or entitlement checks belong in the optional guard Procedure.
 
 ## Consequences
 
 **Authors gain:**
-- Public REST surface for free — declare a View, get an endpoint.
-- Single mental model for "how do consumers read?": always Views.
+- REST and MCP read surfaces for free — declare a View and choose public or
+  staff visibility once.
+- Single mental model for "how do consumers and agents read?": always Views.
 - Cheap pagination + dynamic filters without hand-writing handlers.
 
 **Authors lose:**
 - A View per filter combination (until DRAFT operators land). `posts-by-locale` plus `posts-by-tag` plus `posts-by-locale-and-tag` would be three Views in v0.1.0.
-- No way to write a "private" named query — moves to a TS helper.
+- No internal-only View surface; choose public/staff or keep the query in a TS
+  helper.
 
 **Runtime gains:**
-- One auto-mount path covers every public-read use case for v0.1.0.
+- One executor and response shape cover public/staff REST and MCP reads.
 - Forward-compat for join / group-by / aggregation: envelope generalises by Views declaring `output.kind` later.
 
 **Reviewers / future contributors should:**
 - Reject any PR adding `Schema.spec.expose.rest` or a similar Schema-level public-read flag.
 - Reject any PR introducing a second public read surface (e.g. `/api/<collection>` shortcut).
+- Require REST and MCP mounts to filter by the same `View.spec.surface` value,
+  and keep authorization in the shared `ExecuteViewUseCase` path.
 - Reject any PR that lets `filter` reference state outside the declared `params` (e.g. `{ $env: ... }`, `{ $cookie: ... }`) without a matching ADR amendment.

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

@@ -1,12 +1,18 @@
-# ADR-0014: Better Auth as the auth + MCP authorization server, scope-derived multi-tenant MCP
+# ADR-0014: Adapter-owned identity and MCP authorization
 
 ## Status
 
-Accepted (new). Amended 2026-05-14 — formalize "Better Auth as default implementation, `Auth` interface as the SDK contract" (see § "Auth as contract, Better Auth as default").
+Accepted. Amended 2026-05-14, 2026-05-15, 2026-06-30, 2026-07-15, and
+2026-08-03.
 
 ## Date
 
-2026-05-09 (amended 2026-05-14)
+2026-05-09 (last amended 2026-08-03)
+
+> **Current authority:** the original decision below records the rejected
+> Better-Auth-for-MCP design. The 2026-05-15 carve-out and 2026-07-15 unified
+> authorization amendment are authoritative where they conflict. Operational
+> guidance in "How to apply" is maintained against the current adapter/runtime.
 
 ## Context
 
@@ -40,7 +46,7 @@ A 2026 Workers-friendly auth library — [Better Auth](https://better-auth.com)
 
 Better Auth depends on a Kysely / Drizzle / Prisma adapter for the database, not on any Cloudflare-specific service. The auth machinery becomes platform-agnostic — porting to Netlify / Bun / Deno is config-only.
 
-## Decision
+## Decision (historical baseline; amended below)
 
 ### 1. Better Auth replaces both layers
 
@@ -310,7 +316,7 @@ Keep our `staff` overlay and `D1StaffRepository`. Use Better Auth only for ident
 
 **Rejected** — duplicate role data (Better Auth `admin` plugin + our staff overlay) is worse than picking one. Audit trail is the only thing the standalone overlay buys, and v0.1.0 doesn't need it.
 
-## Implementation status
+## Implementation status (historical snapshot)
 
 Phase 0 (spike, 0.5–1d) — pending:
 
@@ -351,13 +357,31 @@ Phase 3 (v0.2+, with community / fan-club):
 
 When reviewing or implementing a change that touches auth, MCP routing, or roles:
 
-1. **Identity / session / account state** — Better Auth API. Don't hand-write D1 reads against `user` / `session` / `account`. Use `auth.api.*`.
-2. **Role check** — read `session.user.role` (from `auth.api.getSession()` or `auth.api.getMcpSession()`). Don't query a `staff` table; it doesn't exist.
-3. **MCP tool routing** — let the dispatcher derive surface from `Procedure.requires.auth.all`. Don't add a per-tool `surface: 'staff' | 'public'` field; the predicate is the source of truth.
-4. **DCR consent gating** — scope-based via Better Auth `oauthProvider` config. `mcp:staff` requires admin role; `mcp:read` accepts any signed-in user. Don't add a separate consent path or config flag.
-5. **Token props** — minimal. If you need role in the token payload for caller convenience, add via `customAccessTokenClaims`, but always re-validate fresh on the server side.
-6. **Email** — call `EmailSender` port. CF adapter binds Resend; consumer can swap.
-7. **Adapter portability** — the auth surface is platform-agnostic. A new adapter (Netlify / Bun / Deno) constructs Better Auth with its preferred DB adapter and passes the instance to the runtime. No port re-implementation needed.
+1. **Identity and local sessions** — depend on the adapter's public `Auth`
+   interface. `createAuth()` is the curated Better Auth-backed Cloudflare
+   default; do not import Better Auth internals outside that implementation or
+   add an un-curated passthrough.
+2. **Mutable staff privilege** — call `auth.getUserRole(userId)` on every
+   protected REST/MCP invocation. Do not trust a role captured in an OAuth
+   grant or long-lived token.
+3. **MCP transport** — export `createOAuthProvider(...)` at the Worker top
+   level. It owns DCR/PKCE/token verification and dispatches `/mcp` and
+   `/mcp/staff`; the consent handler uses the current local `Auth` session.
+4. **MCP surface** — use explicit `View.spec.surface` and
+   `Trigger.source.surface`. The adapter pre-filters each catalog; the shared
+   runtime evaluator then enforces the target's `requires.auth.all` and
+   optional guard on every call.
+5. **Scopes and props** — advertise the compatibility scope `mcp`. Store only
+   immutable grant identity (`userId`, `clientId`, scopes); never store mutable
+   staff role or raw/refresh tokens in runtime context.
+6. **REST credentials** — normalize sessions, OAuth JWTs, and an optional
+   consumer `credentialResolver` into `HandlerContext`. A recognized invalid
+   API key/PAT fails closed and never falls back to a cookie. Standard remote
+   MCP does not promise raw REST key/PAT support.
+7. **Adapter portability** — auth remains adapter-owned. A future adapter
+   verifies its platform's credentials and supplies the same normalized
+   runtime context; `mantle-runtime` does not gain a Better Auth dependency or
+   an auth storage port.
 
 ## Sources
 
@@ -408,17 +432,19 @@ The original ADR-0014 §"Auth as contract, Better Auth as default" framing stays
 
 ### What didn't change
 
-- The auth port is still removed (the runtime takes the Better Auth instance directly).
+- The auth storage port remains removed; the adapter owns `Auth` and passes
+  verified, normalized caller context into runtime dispatchers.
 - Apple's `trustedOrigins` auto-append (`https://appleid.apple.com`) and `sameSite=none` cookie injection for cross-site `form_post` callback stay.
 - `appleClientSecret()` helper (from PR #173) stays.
 - All non-OAuth admin endpoints (`/api/auth/*`, `/api/auth/methods`, admin SPA mount) stay on Better Auth.
 - The `bootstrapOwner` + email-OTP + magic-link + `methods[]` carve-out stay.
 
-### Future work
+### Compatibility constraints to re-test before changing
 
-- A `@cloudflare/vitest-pool-workers`-based integration test covering the full OAuth flow (DCR → consent → token → MCP RPC). Node-vitest can't load `@cloudflare/workers-oauth-provider` because it imports from `cloudflare:workers`.
-- Starters (`aotter/mantle-starters`) migration to the same top-level OAuthProvider shape. All 8 archetypes currently use the pre-carve-out `mountMcp` API and need updating before the next starter tag.
-- Track whether Anthropic relaxes (1) the `/mcp` resource-path-prefix requirement and (2) the no-colon-in-scope requirement. Both are de-facto MCP client behaviors, not RFC requirements; if upstream relaxes them, the SDK can re-introduce `mcp:read` / `mcp:staff` scopes for finer-grained delegation.
+- Anthropic clients required the `/mcp` resource-path prefix during the
+  carve-out verification.
+- Colon-shaped advertised scopes broke the same clients; Mantle therefore
+  advertises one `mcp` scope and re-evaluates target authorization server-side.
 
 ## Amendment — 2026-06-30: Hosted-auth boundary and first-party cookie fields