@aotter/mantle 0.1.4 → 0.2.0-alpha.1

package/docs/handbook/cloudflare/bindings.md

@@ -1,298 +0,0 @@
----
-description: Each Cloudflare primitive a Mantle Worker can bind, what Mantle uses it for, the wrangler snippet, and the Env type.
----
-# Bindings and primitives
-
-This page lists every Cloudflare binding a Mantle Worker commonly declares: which are required, what Mantle does with each, the `wrangler.jsonc` snippet, and the matching `Env` field. Read it when you write or review a Worker's configuration.
-
-## Compatibility flags
-
-Every Mantle Worker keeps both flags:
-
-```jsonc
-"compatibility_flags": ["nodejs_compat", "global_fetch_strictly_public"]
-```
-
-`nodejs_compat` is required by the adapter and its Auth dependencies. `global_fetch_strictly_public` is required because MCP client metadata (CIMD) is fetched through the public Internet boundary.
-
-## The composition-root rule
-
-Bindings appear in two places only: the Worker entry (`createMantleWorker` options and the `bindings` hook) and `wrangler.jsonc`. Procedure handlers receive them through `ctx.env`. An application may own additional tables behind its own repository, but it never queries Mantle-owned native Schema tables, site settings, media or Auth tables outside the runtime. Use `runtime.entries`, generated `bindMantle(runtime)` and Views instead.
-
-## The Env interface
-
-```ts
-import type { DeferredHookEnvelope } from "@aotter/mantle/runtime";
-import type { MantleCloudflareEnv } from "@aotter/mantle/cloudflare";
-
-interface EmailBinding {
-  send(message: { to: string; from: string; subject: string; text?: string; replyTo?: string }): Promise<unknown>;
-}
-
-export interface Env extends MantleCloudflareEnv {
-  // MantleCloudflareEnv already declares DB, ASSETS?, MANTLE_KV? and the auth vars.
-  readonly DB: D1Database;                                   // required
-  readonly ASSETS: Fetcher;                                  // Admin bundle + your frontend
-  readonly PUBLIC_ORIGIN: string;
-  readonly MANTLE_KV?: KVNamespace;                          // optional MCP catalog cache
-  readonly MEDIA_BUCKET?: R2Bucket;                          // optional media
-  readonly R2_ACCOUNT_ID?: string;
-  readonly R2_ACCESS_KEY_ID?: string;
-  readonly R2_SECRET_ACCESS_KEY?: string;
-  readonly MEDIA_PUBLIC_URL_BASE?: string;
-  readonly AUDIT?: AnalyticsEngineDataset;                 // optional MCP tools/call audit trail
-  readonly MANTLE_INTERNAL_QUEUE?: Queue<DeferredHookEnvelope>;  // optional deferred hooks
-  readonly ORDER_EXPIRY_QUEUE?: Queue<{ type: "expire-order"; orderToken: string }>;  // application queue
-  readonly INVENTORY_COORDINATOR?: DurableObjectNamespace;  // application-owned
-  readonly EMAIL?: EmailBinding;                             // Email Service
-  readonly TURNSTILE_SECRET_KEY?: string;                    // secret
-}
-```
-
-## D1: `DB` (required)
-
-D1 is canonical storage. It holds one native table per Manifest Schema, Mantle's
-`_mantle_*` envelope and migration metadata, site settings, media metadata and
-pending uploads, and the Better Auth tables. `createConventionalBindings`
-throws without `DB`.
-
-```jsonc
-"d1_databases": [
-  { "binding": "DB", "database_name": "my-site", "database_id": "<production-id>" }
-]
-```
-
-Omit `database_id` only for local development. Set the production id before any remote deploy.
-
-## Static Assets: `ASSETS`
-
-```jsonc
-"assets": { "directory": "./public", "binding": "ASSETS" }
-```
-
-`ASSETS` is a hard requirement for Admin. `mantle generate` syncs the **prebuilt** Admin SPA into `public/_mantle/admin/` when `@aotter/mantle-admin-ui` is installed — there is no Vite step unless you are developing `admin-ui` itself. The facade wraps `ASSETS` as the Admin asset server and falls back to `/_mantle/admin/index.html` for client-side Admin routes. The same binding serves your own CSS, JS and icons.
-
-Without this binding, `/admin` can still return SPA HTML (`200`) while `/_mantle/admin/assets/*` is `404`. That white-screens the Dev UI.
-
-When Worker routes and static paths overlap, list Worker-owned paths in `run_worker_first` and keep `not_found_handling` at `"none"` so unmatched requests fall through to the Worker. **Leave `/_mantle` out of `run_worker_first`** so hashed Admin JS/CSS stay on the assets layer. A production configuration lists `/admin`, `/admin/*`, `/mcp`, `/mcp/*`, `/oauth`, `/oauth/*`, `/.well-known/*`, `/api/*`, `/llms.txt`, `/robots.txt`, `/sitemap.xml`, `/*/llms.txt` and every public content prefix there, so a static file can never shadow a Mantle route.
-
-## Workers Cache
-
-```jsonc
-"cache": { "enabled": true }
-```
-
-With a valid `cacheScope`, Mantle marks anonymous `200` `GET`/`HEAD` responses from the public mount (HTML, `.md`, `llms.txt`, sitemap) and eligible Views with a shared lifetime and a deployment-scoped `Cache-Tag`; everything else is `private, no-store`. Supplying a custom `credentialResolver` disables shared responses because Core cannot infer which request headers carry identity. Publishing-content and site-setting writes purge the tag after the canonical write. Purge failure is logged and does not turn a committed write into an error. The local emulator does not simulate the entrypoint cache or its purge API. See [Public web](./public-web.md#cache-contract).
-
-## KV: `MANTLE_KV` (optional)
-
-```jsonc
-"kv_namespaces": [
-  { "binding": "MANTLE_KV", "id": "<production-id>", "preview_id": "<development-id>" }
-]
-```
-
-A deployment-owned namespace that caches the caller-independent MCP catalog projection (brand, description, origin, icons, media-purpose policy) so an authenticated MCP catalog does not read D1 site settings. D1 stays canonical; missing or expired snapshots are repaired from D1 within one hour, and a KV failure never fails a committed write. Never store tokens, sessions or content here. `createMantleWorker` uses this binding only when `cacheScope` is valid, producing keys such as `mantle:my-site-production:site-config:v1:mcp`. KV is eventually consistent across regions, so invalidation is not a global read-after-write guarantee.
-
-## R2: `MEDIA_BUCKET` (optional)
-
-```jsonc
-"r2_buckets": [{ "binding": "MEDIA_BUCKET", "bucket_name": "<project>-media" }]
-```
-
-Staff media uploads through Staff MCP presigned PUT. The binding alone cannot sign URLs; you also need `R2_ACCOUNT_ID`, `MEDIA_PUBLIC_URL_BASE` and the two S3 credential secrets. See [Media uploads with R2](./media-r2.md).
-
-## Analytics Engine: `AUDIT` (optional)
-
-```jsonc
-"analytics_engine_datasets": [{ "binding": "AUDIT", "dataset": "mantle_mcp_audit" }]
-```
-
-An MCP `tools/call` audit trail: who called which tool on which surface, with
-what outcome and how long it took. The runtime's `McpJsonRpcDispatcher` is the
-single write point; it records nothing unless the composition root passes an
-`AuditSink`, and the write happens through `waitUntil`, off the response path.
-Request and response payloads are never recorded.
-
-```ts
-import { analyticsEngineAuditSink, createMantleWorker } from "@aotter/mantle/cloudflare";
-
-export default createMantleWorker<Env>({
-  plan,
-  audit: (env) => env.AUDIT
-    ? analyticsEngineAuditSink(env.AUDIT, { index: env.PUBLIC_ORIGIN })
-    : undefined,
-});
-```
-
-One dataset may hold many deployments: `index` is the deployment's public
-origin, the only column Analytics Engine filters cheaply. Columns, in order:
-
-| Column | Field |
-|---|---|
-| `index1` | the configured `index` |
-| `blob1` … `blob7` | `surface`, `callerId`, `clientId`, `credential`, `tool`, `outcome`, `operationId` |
-| `double1`, `double2` | `at` (epoch ms), `durationMs` |
-
-`outcome` is `ok`, a runtime Diagnostic code such as `UNAUTHENTICATED` or
-`AUTH_DENIED`, `UNKNOWN_TOOL`, `INVALID_PARAMS`, `INTERNAL`, or a transport gate denial
-(`INVALID_TOKEN`, `INSUFFICIENT_SCOPE`, `INSUFFICIENT_ROLE`, `CROSS_ORIGIN`): a
-`tools/call` refused before it reaches the dispatcher is recorded too, with
-whatever identity the gate established. Its body goes through the same 1 MiB
-bounded reader as an admitted call; a denied request whose body is oversized
-or not JSON is still recorded, with `tool` set to `(unreadable)`, so padding a
-body cannot hide a credential probe. `operationId` is the string argument whose
-schema declares `x-mcp-hint: idempotency-key`, falling back to the conventional
-`operationId` argument when the tool declares no hint. It is empty when that
-argument is absent and is resolved the same way on admitted and denied calls.
-Read it with the
-[SQL API](https://developers.cloudflare.com/analytics/analytics-engine/sql-api/):
-
-```sql
-SELECT timestamp, blob2 AS caller, blob5 AS tool, blob6 AS outcome, double2 AS ms
-FROM mantle_mcp_audit
-WHERE index1 IN ('https://site-a.example', 'https://site-b.example')
-  AND timestamp > NOW() - INTERVAL '7' DAY
-ORDER BY timestamp DESC
-```
-
-Analytics Engine keeps data for a bounded window and samples under very high
-write rates. Longer retention or a tamper-evident trail is an export job on top
-of this dataset. Self-hosted runtimes may implement `AuditSink` over any store;
-the interface is one `record(event)` method.
-
-## Queues
-
-```jsonc
-"queues": {
-  "producers": [
-    { "binding": "MANTLE_INTERNAL_QUEUE", "queue": "mantle-internal" },
-    { "binding": "ORDER_EXPIRY_QUEUE", "queue": "my-site-order-expiry" }
-  ],
-  "consumers": [
-    { "queue": "mantle-internal", "max_batch_size": 10, "max_batch_timeout": 5,
-      "max_retries": 5, "retry_delay": 60, "dead_letter_queue": "mantle-internal-dlq" },
-    { "queue": "my-site-order-expiry", "max_concurrency": 1, "max_batch_size": 10,
-      "max_retries": 5, "retry_delay": 30, "dead_letter_queue": "my-site-order-expiry-dlq" }
-  ]
-}
-```
-
-`MANTLE_INTERNAL_QUEUE` carries deferred `after_*` lifecycle hooks. Application queues share the same Worker; the `queue()` export switches on `batch.queue`. See [Deferred hooks with Queues](./deferred-hooks-queues.md).
-
-## Cron Triggers
-
-```jsonc
-"triggers": { "crons": ["*/5 * * * *"] }
-```
-
-A `scheduled()` handler reuses the fetch path's runtime and invokes a Procedure that has no Trigger of its own:
-
-```ts
-import { bindMantle } from "../.mantle/generated/mantle.js";
-
-const worker = createMantleWorker<Env>({ plan, handlers });
-
-export default {
-  fetch: worker.fetch,
-  async scheduled(_controller, env, ctx) {
-    const mantle = bindMantle(await worker.getRuntime(env));
-    const result = await mantle.procedures.sweepExpiredOrders(
-      { now: Date.now() },
-      { user: null, staff: null, env, waitUntil: (p) => ctx.waitUntil(p) },
-    );
-    if (!result.ok) throw new Error(`sweep failed: ${result.diagnostic.code}`);
-  },
-} satisfies ExportedHandler<Env>;
-```
-
-## Durable Objects (application-owned)
-
-Durable Objects are not a Core primitive. Use one as an application-owned coordinator when a decision must be serialized, for example reserving inventory exactly once. Export the class from the Worker entry, then bind and migrate it:
-
-```jsonc
-"durable_objects": { "bindings": [{ "name": "INVENTORY_COORDINATOR", "class_name": "InventoryCoordinator" }] },
-"migrations": [{ "tag": "inventory-v1", "new_sqlite_classes": ["InventoryCoordinator"] }]
-```
-
-```ts
-export { InventoryCoordinator } from "./commerce/InventoryCoordinator.js";
-```
-
-The coordinator keeps its own state; Mantle entries mirror the result. See [Commerce inventory](../../examples/cf-primitives-commerce-inventory.md).
-
-## Email Service: `[[send_email]]`
-
-```jsonc
-"send_email": [{ "name": "EMAIL" }]
-```
-
-Send from an `after_create` handler with `errorPolicy: continue`, and fail soft when the binding or addresses are absent so submissions still save on a fresh deployment:
-
-```ts
-export async function notifyIntake(input: { name?: string; email?: string }, ctx: HandlerContext) {
-  const env = ctx.env as Env & { INTAKE_NOTIFY_TO?: string; INTAKE_NOTIFY_FROM?: string };
-  if (!env.EMAIL || !env.INTAKE_NOTIFY_TO || !env.INTAKE_NOTIFY_FROM) {
-    console.info("[intake] notification not configured");
-    return { ok: true };
-  }
-  await env.EMAIL.send({
-    to: env.INTAKE_NOTIFY_TO,
-    from: env.INTAKE_NOTIFY_FROM,
-    subject: `New intake response from ${input.name ?? "website"}`,
-    text: `Email: ${input.email ?? ""}`,
-    ...(input.email ? { replyTo: input.email } : {}),
-  });
-  return { ok: true };
-}
-```
-
-## Turnstile
-
-Store the secret with `wrangler secret put TURNSTILE_SECRET_KEY`. Declare the token in the Procedure input, then verify it in a `before_create` lifecycle Trigger that aborts on failure:
-
-```yaml
-apiVersion: cms.mantle.aotter.net/v1
-kind: Trigger
-metadata:
-  name: intake-before-create-verify-turnstile
-spec:
-  source:
-    kind: lifecycle
-    schema: intake-submissions
-    on: [before_create]
-    errorPolicy: abort
-  target:
-    procedure: verify-intake-turnstile
-```
-
-The adapter exports a handler factory for the `siteverify` call:
-
-```ts
-import { cloudflareTurnstileCheck } from "@aotter/mantle/cloudflare";
-
-extend: ({ env }) => ({
-  handlers: {
-    "verify-intake-turnstile": cloudflareTurnstileCheck({
-      secret: env.TURNSTILE_SECRET_KEY ?? "dev-stub",
-      tokenField: "turnstileToken",
-    }),
-  },
-}),
-```
-
-Authenticated callers (`ctx.user` set) bypass the check. The literal secret `"dev-stub"` skips the network and rejects only the token `"fail"`. Rejection throws `AUTH_DENIED`, which maps to HTTP `403`. See [Intake Turnstile and email hooks](../../examples/cf-primitives-intake-hooks.md).
-
-## Source
-- [`packages/adapters/cloudflare/README.md`](../../../packages/adapters/cloudflare/README.md)
-- [`packages/adapters/cloudflare/src/bindings/conventionalBindings.ts`](../../../packages/adapters/cloudflare/src/bindings/conventionalBindings.ts)
-- [`packages/adapters/cloudflare/src/mount/cmsConfig.ts`](../../../packages/adapters/cloudflare/src/mount/cmsConfig.ts)
-- [`packages/adapters/cloudflare/src/worker/createMantleWorker.ts`](../../../packages/adapters/cloudflare/src/worker/createMantleWorker.ts)
-- [`packages/adapters/cloudflare/src/handlers/turnstile.ts`](../../../packages/adapters/cloudflare/src/handlers/turnstile.ts)
-- [`packages/mantle/src/cli/generate.ts`](../../../packages/mantle/src/cli/generate.ts)
-- [`docs/deferred-lifecycle-queues.md`](../../../docs/deferred-lifecycle-queues.md)
-- [`docs/media-uploads.md`](../../../docs/media-uploads.md)
-- [`docs/performance-harness.md`](../../../docs/performance-harness.md)
-- [`docs/cloudflare-low-level-composition.md`](../../../docs/cloudflare-low-level-composition.md)
-- [`docs/examples/host-local-admin-otp/wrangler.jsonc`](../../../docs/examples/host-local-admin-otp/wrangler.jsonc)
-- [`docs/examples/host-minimal-worker/wrangler.jsonc`](../../../docs/examples/host-minimal-worker/wrangler.jsonc)

package/docs/handbook/cloudflare/conventional-worker.md

@@ -1,162 +0,0 @@
----
-description: Assemble a Mantle Worker with createMantleWorker, add handlers and routes through extend, and respect Core-owned paths.
----
-# The conventional Worker
-
-`createMantleWorker` is the normal Cloudflare entry for a Mantle application. This page covers its options, what the facade owns, how to add application handlers and routes, and the readiness and reserved-path rules that keep those extensions safe.
-
-## Minimal entry
-
-```ts
-import { createMantleWorker } from "@aotter/mantle/cloudflare";
-import { plan } from "../.mantle/generated/mantle.js";
-
-export default createMantleWorker({ plan, cacheScope: "my-site-production" });
-```
-
-`plan` is the sealed plan that `mantle generate` writes to `.mantle/generated/mantle.ts`. With only `plan`, the Worker serves public View REST, HTTP Triggers, Admin, Auth, OAuth and MCP. It renders no public pages and `/` is a 404; see [Public web](./public-web.md). Local Admin with email OTP replaces Auth construction; see [Quickstart: local Admin](../start/quickstart-admin.md). Admin still requires the `ASSETS` binding.
-
-## Options
-
-| Option | Type | Purpose |
-|---|---|---|
-| `plan` | `RuntimePlan` | Required. Generated plan; a fingerprint or version mismatch fails immediately and asks you to regenerate. |
-| `handlers` | `Record<string, AnyHandler>` | Implementations for `handler.kind: ref` Procedures. Merged with `extend().handlers`; a name registered twice throws. |
-| `siteDefaults` | `SiteDefaults \| (env) => SiteDefaults` | Brand, title, description, origin, locales, icons, media purposes. Use the function form to read `env.PUBLIC_ORIGIN`. See [Site config](../reference/site-config.md). |
-| `cacheScope` | `string \| (env) => string` | Stable deployment/site identifier for public cache tags and optional `MANTLE_KV` keys. Lowercase letters, digits, `_` and `-`, up to 64 characters. Shared caching is disabled when absent or invalid. |
-| `templates` | `TemplateRegistry` | Entry and list templates for public HTML. |
-| `publicPathResolver` | `PublicPathResolver` | Collection-to-URL mapping used for canonical URLs, sitemap and hreflang. |
-| `mediaAllowSvg` | `boolean \| (env) => boolean` | Accept SVG uploads. Default `false`. |
-| `auth` | `(env) => Auth` | Replace Auth construction only. Core still owns the Auth routes. |
-| `bindings` | `(env, conventional) => MantleWorkerBindings` | Augment the conventional adapters, for example `mediaStorage` or `deferredHookDispatcher`. |
-| `extend` | `(ctx) => MantleWorkerExtension \| void` | The one seam for handlers, credential resolution, JWT bearer verification and new Hono routes. |
-
-`extend` receives `{ env, auth, bindings, getRuntime }` and may return:
-
-```ts
-{
-  handlers?: Record<string, AnyHandler>;
-  credentialResolver?: ConsumerCredentialResolver;   // site-owned API keys and personal tokens
-  jwtBearer?: { audience: string; scopes?: readonly string[] };
-  mount?: ({ app, ref, env, auth, bindings, getRuntime }) => void;
-}
-```
-
-`extend` may run again after a failed initialization. Keep external side effects out of it.
-
-## What the facade owns
-
-Once per isolate, `createMantleWorker` assembles and memoizes:
-
-- Conventional bindings: `DB` becomes the D1 driver, `ASSETS` serves the Admin bundle, `MANTLE_KV` (when bound) becomes the MCP catalog projection. See [Bindings](./bindings.md).
-- Conventional Auth chosen by `MANTLE_AUTH_MODE`, or your `auth` factory. See [Authentication](./authentication.md).
-- Runtime endpoints: manifest HTTP Triggers, `GET /api/views` and `GET /api/views/<name>` for public Views.
-- Admin at `/admin` when Admin assets are present, OAuth consent and discovery, and MCP at `/mcp` and `/mcp/staff`. The MCP transport is Streamable HTTP, POST-only: no session header, no server-initiated stream (`GET` answers `405`), and `tools/call` answers `401` with an OAuth challenge so a client can authenticate mid-session and retry. Verified against the official TypeScript client SDK `@modelcontextprotocol/client` 2.0.0 in the adapter's conformance test; that pin is the gate when the SDK is upgraded.
-- A `/favicon.ico` route derived from `siteDefaults.icons`. This is a convention, not a reserved path; an existing host route wins.
-- The final cache policy on every response, and best-effort purge of the deployment-scoped public tag after publishing-content and site-setting writes.
-- A redacted error boundary: an unexpected failure returns `500` with `{ "ok": false, "error": "internal_error" }` and `private, no-store`.
-
-If `auth.ready` rejects, the memoized assembly is evicted so the next request rebuilds instead of reusing a poisoned isolate.
-
-## The returned handler
-
-```ts
-const worker = createMantleWorker<Env>({ plan });
-worker.fetch(request, env, ctx);   // HTTP entry
-worker.getRuntime(env);            // the runtime fetch uses, resolved after auth.ready
-```
-
-Queue and scheduled handlers call `worker.getRuntime(env)` and then generated `bindMantle(runtime)` so they reuse the assembled runtime and never write Mantle tables directly. See [Bindings](./bindings.md#cron-triggers) and [Deferred hooks](./deferred-hooks-queues.md).
-
-## Readiness rule
-
-Standard protected routes establish readiness themselves: the facade awaits `getRuntime()` before Auth, `/oauth`, `/mcp`, `/admin/api` and `/.well-known/oauth*` requests. Extension routes do not. Before an extension route reads or writes Mantle data, or relies on database-backed Auth, it must `await ref.get()` (inside `mount`) or `await getRuntime()`.
-
-`getRuntime` rejects when called synchronously inside `extend` before it returns. Retain the function and call it later, for example inside a request handler.
-
-## Reserved paths
-
-Extensions add routes; they never replace Core surfaces. These registrations are rejected:
-
-- `/admin`, `/_mantle`, `/api/auth`, `/api/views`, `/oauth`, `/mcp`, and anything beneath them
-- `/.well-known/oauth*`
-- the custom Auth factory's `basePath`
-- global `*` and `/*` handlers
-- any exact method and path pair that a manifest HTTP Trigger already owns
-
-Static literals fail TypeScript during your build (`MantleExtensionPath`). Computed paths cannot be proven statically, so after `mount` returns the facade inspects Hono's assembled route table and throws before serving any request. There is no override option. The `app` passed to `mount` exposes `get`, `post`, `put`, `patch`, `delete`, `options`, `all`, `on`, `use` and `route`; it omits global error and not-found hooks.
-
-## Handlers and routes
-
-```ts
-import { createMantleWorker, type MantleCloudflareEnv } from "@aotter/mantle/cloudflare";
-import { plan } from "../.mantle/generated/mantle.js";
-import { notifyIntake } from "./handlers/notifyIntake.js";
-
-interface Env extends MantleCloudflareEnv {
-  readonly PUBLIC_ORIGIN: string;
-}
-
-export default createMantleWorker<Env>({
-  plan,
-  siteDefaults: (env) => ({
-    brand: "Example",
-    title: "Example",
-    description: "Example site.",
-    origin: env.PUBLIC_ORIGIN,
-    locales: ["en"],
-    icons: [
-      { src: "/site-icon.png", mimeType: "image/png", sizes: ["64x64"] },
-      { src: "/site-icon.svg", mimeType: "image/svg+xml", sizes: ["any"] },
-    ],
-  }),
-  extend: () => ({
-    handlers: { "notify-intake": notifyIntake },
-    mount({ app, ref }) {
-      app.get("/api/health", (c) => c.json({ ok: true }));
-      app.get("/api/locales", async (c) => {
-        const runtime = await ref.get();            // readiness before data
-        const site = await runtime.siteConfig.load();
-        return c.json({ locales: site.locales });
-      });
-    },
-  }),
-});
-```
-
-Handler keys match `spec.handler.ref` in Procedure manifests; see [Procedures and Triggers](../concepts/procedures-and-triggers.md).
-
-## A `bindings` hook
-
-`bindings` receives the conventional set and returns the set the runtime uses. Spread the conventional bindings, then add capability adapters:
-
-```ts
-import {
-  createMantleWorker,
-  WorkersQueueHookDispatcher,
-} from "@aotter/mantle/cloudflare";
-
-export default createMantleWorker<Env>({
-  plan,
-  bindings: (env, conventional) => ({
-    ...conventional,
-    mediaStorage: buildMediaStorage(env),          // see media-r2.md
-    deferredHookDispatcher: new WorkersQueueHookDispatcher(env.MANTLE_INTERNAL_QUEUE),
-  }),
-});
-```
-
-The conventional set is `{ db, adminAssets, mcpCatalogKv? }`. Never drop `db`.
-
-## Site identity
-
-`siteDefaults.icons` is one identity reused by browser favicons, Admin chrome and MCP `serverInfo.icons`. Keep the SVG as the editable source and add a PNG rendition for MCP clients that need raster formats. Both files live in `public/`.
-
-## Source
-- [`packages/mantle/README.md`](../../../packages/mantle/README.md)
-- [`packages/adapters/cloudflare/README.md`](../../../packages/adapters/cloudflare/README.md)
-- [`packages/adapters/cloudflare/src/worker/createMantleWorker.ts`](../../../packages/adapters/cloudflare/src/worker/createMantleWorker.ts)
-- [`packages/adapters/cloudflare/src/bindings/conventionalBindings.ts`](../../../packages/adapters/cloudflare/src/bindings/conventionalBindings.ts)
-- [`packages/adapters/cloudflare/src/mount/cmsConfig.ts`](../../../packages/adapters/cloudflare/src/mount/cmsConfig.ts)
-- [`docs/examples/host-local-admin-otp/src/index.ts`](../../../docs/examples/host-local-admin-otp/src/index.ts)
-- [`docs/examples/host-minimal-worker/src/index.ts`](../../../docs/examples/host-minimal-worker/src/index.ts)

package/docs/handbook/cloudflare/deferred-hooks-queues.md

@@ -1,170 +0,0 @@
----
-description: Move after_* lifecycle Triggers onto Cloudflare Queues with at-least-once delivery, idempotent handlers and a DLQ.
----
-# Deferred hooks with Queues
-
-`after_create`, `after_update`, `after_delete` and `after_publish` lifecycle Triggers run inline by default. Binding a Cloudflare Queue moves them off the request path. This page covers the guarantees, the setup, the Worker wiring and how to write handlers that survive replay.
-
-## When to defer
-
-Defer hooks that must not add request latency and that tolerate a short delay: notifications, projections, upstream API calls. Keep synchronous `before_*` hooks for validation and abuse prevention; they may read request-only input such as a CAPTCHA token, which deferred envelopes never retain.
-
-## Guarantees
-
-- The entry write commits first. D1 and the Queue do not share a transaction, so a Worker failure between them can lose the enqueue.
-- Delivery is at-least-once. A message can run more than once.
-- A rejected or ambiguous `Queue.send()` falls back to `ctx.waitUntil` (or inline when unavailable) with the same event identity. That fallback is best-effort.
-- A consumer runs every captured Trigger before acknowledging; a later failure can replay an earlier success.
-- Malformed, oversized, removed-Trigger and persistently failing messages are retried and then land in the dead-letter queue. Without a DLQ, Cloudflare discards them after `max_retries`.
-
-Handlers must therefore be idempotent. Mantle does not promise exactly-once execution.
-
-## The v1 envelope
-
-```ts
-interface DeferredHookEnvelope {
-  version: 1;
-  eventId: string;
-  triggerNames: readonly string[];
-  hook: "after_create" | "after_update" | "after_delete" | "after_publish";
-  schema: string;
-  entry: EntryRow;
-  ctxSnapshot: CtxSnapshot | null;
-}
-```
-
-Each handler receives the persisted `entry.data` as input and `ctx.event = { id, trigger, hook, schema, entry }`. Use `${ctx.event.id}:${ctx.event.trigger}` as the idempotency key; it is stable across fallback, retries and replay. `ctxSnapshot` holds normalized actor and credential metadata, never cookies, tokens or API keys.
-
-Cloudflare's 128 KB message limit is decimal and includes platform metadata. The dispatcher rejects non-JSON-safe envelopes and any encoded envelope of 127,000 bytes or more before calling `Queue.send`. Keep entry payloads well below that.
-
-## Setup
-
-```sh
-pnpm wrangler queues create mantle-internal
-pnpm wrangler queues create mantle-internal-dlq
-```
-
-```jsonc
-"queues": {
-  "producers": [{ "binding": "MANTLE_INTERNAL_QUEUE", "queue": "mantle-internal" }],
-  "consumers": [{
-    "queue": "mantle-internal",
-    "max_batch_size": 10,
-    "max_batch_timeout": 5,
-    "max_retries": 5,
-    "retry_delay": 60,
-    "dead_letter_queue": "mantle-internal-dlq"
-  }]
-}
-```
-
-These are adapter settings, not manifest grammar. See [Trigger](../reference/trigger.md) for the `lifecycle` source shape.
-
-## Worker wiring
-
-```ts
-import type { DeferredHookEnvelope } from "@aotter/mantle/runtime";
-import {
-  WorkersQueueHookDispatcher,
-  createMantleWorker,
-  createQueueHandler,
-  type MantleCloudflareEnv,
-} from "@aotter/mantle/cloudflare";
-import { plan } from "../.mantle/generated/mantle.js";
-
-interface Env extends MantleCloudflareEnv {
-  readonly MANTLE_INTERNAL_QUEUE: Queue<DeferredHookEnvelope>;
-}
-
-const worker = createMantleWorker<Env>({
-  plan,
-  handlers,
-  bindings: (env, conventional) => ({
-    ...conventional,
-    deferredHookDispatcher: new WorkersQueueHookDispatcher(env.MANTLE_INTERNAL_QUEUE),
-  }),
-});
-
-export default {
-  fetch: worker.fetch,
-  queue(batch, env) {
-    return createQueueHandler<Env>({ get: () => worker.getRuntime(env) })(batch, env);
-  },
-} satisfies ExportedHandler<Env>;
-```
-
-The same Worker is producer and consumer. Opt-in adds only the dispatcher binding and the `queue` export; Auth, MCP, cache and runtime assembly stay on the standard path.
-
-## Multiplexing application queues
-
-Route on `batch.queue` when the Worker also consumes its own queues:
-
-```ts
-queue(batch, env, ctx) {
-  const mantleQueue = createQueueHandler<Env>({ get: () => worker.getRuntime(env) });
-  switch (batch.queue) {
-    case "mantle-internal": return mantleQueue(batch, env);
-    case "billing-jobs": return consumeBilling(batch, env, ctx);
-    default:
-      batch.retryAll();
-      console.error(`No consumer for queue '${batch.queue}'`);
-  }
-}
-```
-
-Application consumers own their own acknowledgement. A common pattern is to `bindMantle(await worker.getRuntime(env))` and call a Procedure, then `ack()` on success, `retry()` on `INTERNAL_ERROR` or `CONFLICT`, and `ack()` on other diagnostics so a poison message does not loop. See [Bindings](./bindings.md#queues).
-
-## Consumer semantics
-
-- At most five messages run concurrently within a delivered batch, even if `max_batch_size` is higher.
-- Runtime boot failure calls `batch.retryAll()` so per-message attempt counters advance and `max_retries` and the DLQ apply.
-- Each message is acknowledged exactly once after every captured Trigger succeeds; any failure calls `retry()` on that message only.
-
-## An idempotent D1 handler
-
-Make the event key a unique database key:
-
-```sql
-CREATE TABLE notification_jobs (
-  idempotency_key TEXT PRIMARY KEY,
-  entry_id TEXT NOT NULL,
-  payload TEXT NOT NULL,
-  created_at INTEGER NOT NULL
-);
-```
-
-```ts
-import type { HandlerContext } from "@aotter/mantle/runtime";
-
-export async function enqueueNotification(input: Record<string, unknown>, ctx: HandlerContext) {
-  if (!ctx.event?.entry) throw new Error("lifecycle entry event required");
-  const key = `${ctx.event.id}:${ctx.event.trigger}`;
-  await (ctx.env as Env).DB.prepare(
-    `INSERT OR IGNORE INTO notification_jobs (idempotency_key, entry_id, payload, created_at)
-     VALUES (?, ?, ?, ?)`,
-  ).bind(key, ctx.event.entry.id, JSON.stringify(input), Date.now()).run();
-  return { ok: true };
-}
-```
-
-For an upstream API, send the same key as `Idempotency-Key` and throw on a non-OK response so the Queue retries. Core adds no outbox, job registry or provider retry wrapper; those remain application-owned.
-
-## The removed-Trigger footgun
-
-`triggerNames` is captured when the mutation runs. Renaming or removing a captured Trigger makes every older message fail validation at dispatch and eventually reach the DLQ; it never silently changes meaning. Drain the queue before removing a deferred Trigger, and inspect the DLQ before raising `max_retries`.
-
-## Verify
-
-In the SDK checkout the contract test is:
-
-```sh
-pnpm --filter @aotter/mantle-cloudflare test -- mantle-internal-queue.test.ts
-```
-
-For a site, run `wrangler dev`, submit a mutation that has an `after_*` Trigger, and read the consumer log. Make one handler fail once and confirm the replay carries the same `ctx.event.id` and `ctx.event.trigger`.
-
-## Source
-- [`docs/deferred-lifecycle-queues.md`](../../../docs/deferred-lifecycle-queues.md)
-- [`packages/adapters/cloudflare/src/bindings/WorkersQueueHookDispatcher.ts`](../../../packages/adapters/cloudflare/src/bindings/WorkersQueueHookDispatcher.ts)
-- [`packages/adapters/cloudflare/src/mount/cmsConfig.ts`](../../../packages/adapters/cloudflare/src/mount/cmsConfig.ts)
-- [`packages/adapters/cloudflare/README.md`](../../../packages/adapters/cloudflare/README.md)