@aotter/mantle 0.1.0-alpha.1 → 0.1.0-alpha.10

package/docs/adapter-guide.md

@@ -2,20 +2,24 @@
 
 This guide is the fresh-developer entry point for implementing a new mantle platform adapter.
 
-Read this with [ADR-0011](adr/0011-adapter-port-spec.md). The source of truth for TypeScript shapes is `packages/mantle-runtime/src/domain/port/`.
+Read this with [ADR-0019](adr/0019-sealed-manifest-runtime-pipeline.md). The source of truth for TypeScript shapes is `packages/mantle-runtime/src/domain/port/`.
 
 Adapter packages live under `packages/adapters/<platform>/` using a plural `adapters` bucket. The npm package names stay unchanged, for example `@aotter/mantle-cloudflare`. Keep adapters in this monorepo until the runtime/spec API is stable enough that coordinated releases across separate repositories would not create version skew for starters.
 
-## Required runtime ports
+## Required storage boundary
 
-A first-run adapter must implement exactly these two runtime ports:
+A storage adapter prepares one `RuntimePlan` into semantic ports:
 
 | Contract | Source | Cloudflare example |
 |---|---|---|
-| `DatabaseDriver` plus `PreparedStatement` and `MigrationRunner` | `packages/mantle-runtime/src/domain/port/DatabaseDriver.ts` | `packages/adapters/cloudflare/src/bindings/D1DatabaseDriver.ts` |
-| `AssetServer` | `packages/mantle-runtime/src/domain/port/AssetServer.ts` | `packages/adapters/cloudflare/src/bindings/AssetsAssetServer.ts` |
+| `MantleStorageAdapter` / `PreparedMantleStorage` | `packages/mantle-runtime/src/domain/port/MantleStorageAdapter.ts` | `SqliteMantleStorageAdapter` over `D1DatabaseDriver` |
+| `EntryRepository & EntryReader` | Existing semantic content ports | `DatabaseEntryRepository` supplied by the SQLite adapter |
+| `ViewQueryExecutor` | `packages/mantle-runtime/src/domain/port/ViewQueryExecutor.ts` | `SqliteViewQueryExecutor` |
 
-The runtime must not import platform types such as `D1Database`, `KVNamespace`, Cloudflare `Fetcher`, Netlify request objects, Postgres pools, or adapter SDK types. Those live in adapter packages.
+`DatabaseDriver` is only the reusable SQLite/D1 implementation seam. A
+PostgreSQL, MongoDB, or application-owned-table adapter implements the semantic
+ports directly; it does not emulate D1 and needs no mapping DSL. Platform types
+such as `D1Database`, Postgres pools, and Mongo clients remain in adapter code.
 
 ## Optional capabilities
 
@@ -26,7 +30,7 @@ Optional ports are enabled only when a feature needs them:
 | `MediaStorage` | `packages/mantle-runtime/src/domain/port/MediaStorage.ts` | The adapter exposes admin/MCP media upload flows. |
 | `DeferredHookDispatcher` | `packages/mantle-runtime/src/domain/port/DeferredHookDispatcher.ts` | The adapter wants at-least-once queue delivery for `after_*` lifecycle hooks. |
 
-Test seams such as `Clock` and `IdGenerator` are injectable through `createCmsRuntime`, but normal adapters do not need custom implementations.
+Test seams such as `Clock` and `IdGenerator` are injectable through `createMantleRuntime`, but normal adapters do not need custom implementations.
 
 Deferred delivery is an optional, versioned wire contract. Queue acceptance is
 not atomic with the entry write; adapters must preserve the supplied event id,
@@ -35,37 +39,72 @@ to their retry mechanism, and document poison-message/DLQ behavior. See
 [Deferred lifecycle hooks on Cloudflare Queues](deferred-lifecycle-queues.md)
 for the reference implementation and exact guarantees.
 
-## Runtime boot
+## Storage preparation
 
-Adapters compose the runtime through `createCmsRuntime`:
+Compile before deployment preparation, then pass only the sealed plan:
 
 ```ts
-import { createCmsRuntime } from "@aotter/mantle-runtime";
-
-const runtime = createCmsRuntime({
-  manifests,
+import {
+  bootMantleRuntime,
+  SqliteMantleStorageAdapter,
+} from "@aotter/mantle-runtime";
+
+const storage = new SqliteMantleStorageAdapter(db, siteDefaults);
+const runtime = await bootMantleRuntime({
+  plan,
+  storage,
   handlers,
-  templates,
-  siteDefaults,
-  db,
-  assets,
-  publicPathResolver,
-  mediaStorage,
-  deferredHookDispatcher,
+  ports,
+  deployment: {
+    reservedHttpPathPrefixes: selectedCapabilities.flatMap(
+      (capability) => capability.reservedHttpPathPrefixes,
+    ),
+  },
 });
+```
+
+`bootMantleRuntime` performs one attempt and derives Procedure readiness from
+the supplied handlers. The platform adapter remains responsible for lazy boot,
+promise caching, retry policy, and teardown.
 
-await runtime.bootInit();
+Hosts that need work between preparation and binding may keep the same stages
+public and explicit:
+
+```ts
+const prepared = await prepareDeployment(plan, storage, {
+  handlerNames: Object.keys(handlers ?? {}),
+});
+const runtime = createMantleRuntime({ prepared, handlers, ports });
 ```
 
-`bootInit()` runs canonical migrations, seeds `siteDefaults`, and validates the manifest set. Call it once before serving CMS traffic. The Cloudflare adapter's reference pattern is `packages/adapters/cloudflare/src/mount/bootRuntimeOnce.ts`.
+The prepared revision carries its exact plan, but exposes both `plan` and
+`storage`; it seals the pairing invariant rather than hiding low-level host
+capabilities. Omit `handlerNames` only for a read-only embedding that never
+dispatches Procedures.
 
-Use purpose-shaped runtime surfaces for canonical data: `runtime.entryReader`
-applies Schema index declarations, locale semantics, and the public `Entry`
-projection; `runtime.siteConfig` owns site settings. `runtime.db` remains only
-for source compatibility and is deprecated. An adapter that owns additional
-tables should retain the `DatabaseDriver` it injected instead of reaching back
-through the assembled runtime. Authoring continues through the pre-wired
-content use cases.
+The official SQLite adapter runs canonical migrations, defaults, indexes, and
+schema-View reconciliation, and skips mutation for an unchanged revision. A
+custom adapter owns its own preparation and returns application-owned semantic
+ports. Unsupported native View dialects fail before the adapter mutates state.
+
+### Bun embedding
+
+`@aotter/mantle-bun` is the minimal SQLite reference: pass an application-owned
+`bun:sqlite` `Database` and a compiled `RuntimePlan` to `createBunMantle()`.
+Its `handle()` returns `null` for sibling routes and a Web-standard `Response`
+for manifest-declared public Views and HTTP Triggers. The host owns
+`Bun.serve`, database shutdown, authentication, and CSRF policy; the adapter
+prepares the semantic revision once and retries only after failed preparation.
+
+### Vercel Functions embedding
+
+`@aotter/mantle-vercel` accepts a compiled plan plus any application-owned
+`MantleStorageAdapter` and reuses the same public View/HTTP Trigger transport as
+Bun. It maps deferred work to Vercel Functions `waitUntil` and otherwise leaves
+the Web Handler, auth/CSRF, and route composition to the application. The
+optional `/libsql` subpath adapts a caller-owned remote Turso/libSQL client to
+the canonical SQLite chain; the default entry has no database-vendor policy.
+Vercel's read-only filesystem and writable `/tmp` are never durable state.
 
 ## HTTP and MCP surfaces
 
@@ -73,9 +112,10 @@ The runtime is a library, not an HTTP server. A new adapter must mount equivalen
 
 | Surface | Adapter responsibility | Cloudflare reference |
 |---|---|---|
-| Public/admin HTTP endpoints | Route HTTP Triggers, View REST endpoints, admin SPA assets, and public render routes into runtime use cases. | `packages/adapters/cloudflare/src/mount/mountServerEndpoints.ts`, `mountPublicRoutes.ts` |
-| Auth endpoints | Own sign-in/session/OAuth metadata routes through the adapter's Better Auth integration. | `packages/adapters/cloudflare/src/auth/createAuth.ts`, `mountServerEndpoints.ts` |
-| MCP endpoints | Mount `/mcp/staff` and `/mcp` via `createOAuthProvider({ apiHandlers })`; the OAuth lib verifies bearer tokens against its KV grant store, then calls the matching apiHandler with `ctx.props` set. The adapter enforces the staff D1 role inside the apiHandler, then dispatches JSON-RPC. | `packages/adapters/cloudflare/src/mount/mountMcp.ts`, `oauth/oauthSingleton.ts`, `oauth/mountOAuth.ts` |
+| Runtime HTTP endpoints | Route HTTP Triggers and public View REST endpoints into runtime use cases. | `packages/adapters/cloudflare/src/mount/mountRuntimeEndpoints.ts` |
+| Optional Admin | Supply session/request context and assets to `mantle-admin`; mount only when selected. | `packages/adapters/cloudflare/src/mount/mountAdmin.ts` |
+| Auth endpoints | Own sign-in/session/OAuth metadata through the adapter's Better Auth implementation selected by Admin/OAuth surfaces. | `packages/adapters/cloudflare/src/auth/createAuth.ts` |
+| MCP endpoints | Mount `/mcp/staff` and `/mcp` behind one canonical protected resource. The adapter verifies Better Auth JWTs, normalizes the caller, re-reads the staff D1 role, then dispatches JSON-RPC. | `packages/adapters/cloudflare/src/mount/mountMcp.ts`, `auth/createAuth.ts` |
 
 Auth is not a runtime port. Per [ADR-0014](adr/0014-auth-better-auth-and-multi-tenant-mcp.md), the adapter owns Better Auth wiring and passes authenticated user/staff context into runtime dispatchers. Procedure handlers receive that data through `HandlerContext` in `packages/mantle-runtime/src/domain/model/HandlerContext.ts`.
 
@@ -93,7 +133,7 @@ Minimum HTTP behavior for a full adapter:
 - Route manifest HTTP Triggers to `runtime.invokeProcedure`.
 - Route `GET /api/views/<name>` to `runtime.executeView`.
 - Mount admin content APIs with session/role checks before calling runtime content use cases.
-- Serve admin SPA assets through `AssetServer`, with an SPA catchall for admin client-side routes.
+- Serve selected Admin SPA assets through `AdminAssetServer`, with an SPA catchall for client-side routes.
 - Mount public render routes and markdown mirrors when the starter exposes public pages.
 - Translate runtime diagnostics and validation failures into stable HTTP JSON responses instead of throwing raw errors.
 - Evaluate target auth and dynamic guards through the runtime use cases; do
@@ -101,22 +141,27 @@ Minimum HTTP behavior for a full adapter:
 
 For the Cloudflare adapter, public rendering requires three matching consumer
 inputs: `mountPublicRoutes(...)` route declarations, a `TemplateRegistry`
-passed through `CmsConfig.templates`, and a `publicPathResolver` passed through
-`CmsConfig.publicPathResolver`. Omitting public routes is valid for a headless
+passed through `MantleCloudflareConfig.templates`, and a `publicPathResolver`
+passed through `MantleCloudflareConfig.publicPathResolver`. Omitting public routes is valid for a headless
 consumer; mounting every Schema automatically is not, because some collections
 are private even when they contain a slug.
 
+`TemplateRegistry` and `createPublicPathResolver` come from
+`@aotter/mantle-web`. Other adapters can call `createMantleWeb(runtime)` and map
+its document operations into their own routing and cache conventions.
+
 ### HTTP cache contract
 
-The Cloudflare adapter is private by default. Consumers must export
-`createOAuthProvider(...)` as the Worker's top-level handler so its final
-response policy covers admin, auth, API, OAuth, MCP, redirects, and errors.
+The Cloudflare adapter is private by default. Consumers must apply its final
+cache policy after admin, auth, API, OAuth, MCP, application routes, redirects,
+and errors.
 Those responses receive `Cache-Control: private, no-store`; Cloudflare-specific
 CDN cache overrides are removed.
 
 `mountPublicRoutes(...)` renders canonical D1 state and opts only successful HTML, markdown,
 `llms.txt`, and sitemap responses into the shared cache with
-`Cache-Control: public, max-age=0, s-maxage=300`. The top-level policy preserves
+`Cache-Control: public, max-age=0, s-maxage=300` and the site-level
+`Cache-Tag: mantle-public`. The top-level policy preserves
 that opt-in only for anonymous `GET`/`HEAD` responses with status 200, explicit
 shared freshness, no request `Cookie` or `Authorization`, and no response
 `Set-Cookie`. It also varies public responses by `Cookie` and `Authorization`.
@@ -124,7 +169,10 @@ shared freshness, no request `Cookie` or `Authorization`, and no response
 A starter-level Workers Cache may therefore store only responses that still
 meet that exact public contract. It must bypass credentialed/cookie requests
 and must never infer cacheability from a URL prefix. Cache entries remain
-version-local; cross-version caching is outside this contract.
+version-local; cross-version caching is outside this contract. Successful
+publishing-content and site-setting mutations purge `mantle-public` through
+Cloudflare's native cache API. Operational records and immutable assets do not
+purge the public render cache.
 
 Minimum auth/MCP behavior:
 
@@ -142,20 +190,19 @@ Minimum auth/MCP behavior:
 
 ## Static assets
 
-`AssetServer` is required because every adapter must have a strategy for serving the prebuilt admin UI from `@aotter/mantle-admin-ui`. The adapter may serve those files from platform assets, a static publish directory, object storage plus CDN, or a filesystem bundle. Return `null` from `AssetServer.fetch()` when a specific asset is not found so the adapter can fall back to the admin SPA catchall.
+`AdminAssetServer` belongs to optional `@aotter/mantle-admin`. Headless Core
+storage preparation and binding do not accept or require a static asset port.
 
 ## Implementation checklist
 
-- [ ] Implement `DatabaseDriver`, including canonical migration tracking.
-- [ ] Implement `AssetServer` for the admin UI assets.
-- [ ] Compose `createCmsRuntime` with manifests, handlers, templates, site defaults, and required ports.
-- [ ] Call `bootInit()` before serving CMS traffic.
+- [ ] Implement `MantleStorageAdapter` returning existing semantic ports, or reuse `SqliteMantleStorageAdapter` with an already-owned handle.
+- [ ] Call `bootMantleRuntime()` once per semantic revision, or explicitly prepare before binding.
 - [ ] Mount HTTP Trigger and View REST surfaces.
 - [ ] Mount admin/public render routes and admin SPA assets.
 - [ ] Provide adapter-owned Better Auth wiring and session helpers.
 - [ ] Normalize session/OAuth and any consumer credential seam into
       `HandlerContext.auth`; never put raw credentials in runtime context.
-- [ ] Mount `/mcp/staff` and `/mcp` via the platform's OAuth provider lib (Cloudflare adapter uses `@cloudflare/workers-oauth-provider` at top level). Enforce staff D1 role inside the apiHandler.
+- [ ] Mount `/mcp/staff` and `/mcp` behind one resource-bound token verifier. Enforce the live staff role inside the apiHandler.
 - [ ] Preserve the HTTP cache contract: private by default; explicit anonymous 200 `GET`/`HEAD` public opt-in only.
 - [ ] Prove one guarded target has identical REST/MCP outcomes, including
       mutable revocation on the next call.
@@ -170,4 +217,4 @@ Minimum auth/MCP behavior:
 - Do not add API-key, personal-token, transaction, billing, or entitlement
   repositories to Core. They are consumer state behind the adapter resolver
   and guard Procedure.
-- Do not add a second canonical migration chain for a new adapter. The runtime owns canonical migrations; adapters execute them through `DatabaseDriver.migrations`.
+- Do not generalize `DatabaseDriver` for PostgreSQL/MongoDB or add a mapping DSL. Implement semantic ports; SQLite/D1 alone reuse the canonical SQL chain.