@aotter/mantle 0.1.0-alpha.9 → 0.1.2-alpha.2

package/docs/direct-authoring.md

@@ -0,0 +1,5 @@
+# Direct authoring
+
+This guide moved into the handbook: [`docs/handbook/start/project-and-cli.md`](handbook/start/project-and-cli.md).
+
+The handbook ships inside the `@aotter/mantle` package under `node_modules/@aotter/mantle/docs/handbook/` and describes the installed release.

package/docs/examples/minimal-worker/README.md

@@ -0,0 +1,37 @@
+# Minimal Worker reference
+
+This is a directly authored, API-only application and executable consumer test.
+It is not a Starter, template catalog or CLI generator. The notes Schema/View
+is example business data; `mantle generate` never invents it.
+
+For your own project, author package.json, manifests, Worker/provider config
+and TypeScript settings for your requirements. Pin all selected `@aotter/mantle*`
+dependencies to the same intended release. This reference records alpha.17 as
+its last published baseline; Core's test runner substitutes its exact candidate
+in a disposable copy, including during a future release.
+
+Outside the SDK workspace, with Node 22+ and pnpm 9+:
+
+```sh
+pnpm install
+pnpm check
+pnpm dev
+```
+
+Commit the resolved lockfile in a real application and use frozen installs
+subsequently. `generate` writes `.mantle/generated/mantle.ts`; `skills` separately
+projects version-matched instructions. Public GET `/api/views/published-notes`
+returns an empty result against fresh local D1. `/` is 404: no visitor frontend
+is installed or rendered. Auth routes fail closed until auth is configured.
+No provider resources or secrets are needed for this local reference.
+The View declares a one-hour shared-cache hint and the Worker supplies the
+stable `minimal-worker-local` cache scope; authenticated requests remain private.
+
+`mantle-web` is optional runtime document composition; it does not generate a
+home page. Add application-owned routes/templates/frontend only when needed.
+Configure real D1 identity and the chosen auth mode before any remote deploy;
+never copy test names over an existing project's bindings or commit secrets.
+
+Maintainers run `pnpm check:worker-consumer` from the SDK root for exact packed
+packages. The release controller also runs the same check against public npm
+artifacts before promoting any public channel.

package/docs/examples/minimal-worker/manifests/site.yaml

@@ -0,0 +1,25 @@
+apiVersion: cms.mantle.aotter.net/v1
+kind: Schema
+metadata:
+  name: notes
+spec:
+  title: Notes
+  schema:
+    type: object
+    required: [title]
+    properties:
+      title: { type: string }
+  lifecycle: publishing
+---
+apiVersion: cms.mantle.aotter.net/v1
+kind: View
+metadata:
+  name: published-notes
+spec:
+  surface: public
+  from: notes
+  cache: { sharedMaxAge: 3600 }
+  fields: [id, title]
+  filter:
+    eq: { field: status, value: published }
+  limit: 20

package/docs/examples/minimal-worker/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "mantle-minimal-consumer",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "generate": "mantle generate",
+    "validate": "mantle validate",
+    "typecheck": "tsc --noEmit",
+    "dev": "wrangler dev --local",
+    "check": "mantle generate && mantle generate --check && mantle validate && mantle skills && mantle skills --check && tsc --noEmit && node smoke.mjs"
+  },
+  "dependencies": {
+    "@aotter/mantle": "0.1.0-alpha.17",
+    "@aotter/mantle-cloudflare": "0.1.0-alpha.17",
+    "better-auth": "1.7.2",
+    "hono": "^4.13.3",
+    "zod": "^4.5.4",
+    "aws4fetch": "^1.0.20"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^5.20260907.1",
+    "typescript": "^6.0.3",
+    "wrangler": "^4.125.0"
+  },
+  "packageManager": "pnpm@9.15.0"
+}

package/docs/examples/minimal-worker/smoke.mjs

@@ -0,0 +1,23 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { unstable_dev } from "wrangler";
+
+const worker = await unstable_dev("src/index.ts", {
+  config: "wrangler.jsonc", local: true, ip: "127.0.0.1", port: 0,
+  inspectorPort: 0, persist: false,
+  experimental: { disableExperimentalWarning: true },
+});
+try {
+  const response = await worker.fetch("/api/views/published-notes");
+  assert.equal(response.status, 200);
+  const body = await response.json();
+  assert.equal(body.ok, true);
+  assert.deepEqual(body.data.rows, []);
+  assert.equal((await worker.fetch("/")).status, 404, "No implicit visitor homepage");
+  const auth = await worker.fetch("/mcp/staff");
+  assert.equal(auth.status, 503, "Auth must fail closed until configured");
+  const pkg = JSON.parse(readFileSync("node_modules/@aotter/mantle/package.json", "utf8"));
+  console.log(`Mantle ${pkg.version}: public View 200, home 404, unconfigured auth 503`);
+} finally {
+  await worker.stop();
+}

package/docs/examples/minimal-worker/src/index.ts

@@ -0,0 +1,4 @@
+import { createMantleWorker } from "@aotter/mantle/cloudflare";
+import { plan } from "../.mantle/generated/mantle.js";
+
+export default createMantleWorker({ plan, cacheScope: "minimal-worker-local" });

package/docs/examples/minimal-worker/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "types": [
+      "@cloudflare/workers-types"
+    ]
+  },
+  "include": [
+    "src/**/*.ts",
+    ".mantle/generated/**/*.ts"
+  ]
+}

package/docs/examples/minimal-worker/wrangler.jsonc

@@ -0,0 +1,22 @@
+{
+  "$schema": "node_modules/wrangler/config-schema.json",
+  "name": "mantle-reference",
+  "main": "src/index.ts",
+  "compatibility_date": "2026-09-08",
+  "compatibility_flags": [
+    "nodejs_compat",
+    "global_fetch_strictly_public"
+  ],
+  "observability": {
+    "enabled": true
+  },
+  "vars": {
+    "MANTLE_AUTH_MODE": "self-managed"
+  },
+  "d1_databases": [
+    {
+      "binding": "DB",
+      "database_name": "mantle-reference-local"
+    }
+  ]
+}

package/docs/handbook/cloudflare/authentication.md

@@ -0,0 +1,167 @@
+---
+description: Configure MANTLE_AUTH_MODE, secrets, the first owner and staff roles; understand which routes need a session.
+---
+# Authentication
+
+Conventional Auth is chosen by one variable, `MANTLE_AUTH_MODE`, and fails closed when its configuration is incomplete. This page covers the two modes, the secrets each needs, first-owner bootstrap, roles, the routes that require a session, and the curated Better Auth surface.
+
+## Mode matrix
+
+| Mode | Non-secret vars | Worker secrets | Must be absent |
+|---|---|---|---|
+| `self-managed` | `MANTLE_AUTH_MODE=self-managed`, `PUBLIC_ORIGIN`, `GITHUB_CLIENT_ID`, `ADMIN_GITHUB_LOGIN` | `GITHUB_CLIENT_SECRET`, `BETTER_AUTH_SECRET` | `MANTLE_HOSTED_AUTH_ISSUER`, `MANTLE_HOSTED_AUTH_CLIENT_ID` |
+| `hosted` | `MANTLE_AUTH_MODE=hosted`, `PUBLIC_ORIGIN`, `MANTLE_HOSTED_AUTH_ISSUER`, `MANTLE_HOSTED_AUTH_CLIENT_ID`, `ADMIN_GITHUB_LOGIN` | `BETTER_AUTH_SECRET` | `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET` |
+
+Validation rules:
+
+- `PUBLIC_ORIGIN` is the site's HTTPS origin without a trailing slash. When unset, the adapter falls back to `http://localhost:8787`.
+- Self-managed uses the site's own GitHub OAuth app. Register its callback URL as `<PUBLIC_ORIGIN>/api/auth/callback/github`.
+- Hosted is a public PKCE client with no client secret. `MANTLE_HOSTED_AUTH_ISSUER` must be an HTTPS root origin (no path, query or fragment; `http` only for loopback). `MANTLE_HOSTED_AUTH_CLIENT_ID` must be a URL on that same origin shaped `/clients/<id>`.
+- `ADMIN_GITHUB_LOGIN` must be a valid GitHub login.
+
+Any missing, invalid, partial or mixed-mode configuration produces a setup-incomplete Auth instance instead of a working one.
+
+## `503 setup_incomplete`
+
+With incomplete Auth, public routes keep working: public Views, public HTTP Triggers, public pages, `.md` mirrors, `llms.txt` and the sitemap. Auth-owned private routes return:
+
+```json
+{ "error": "setup_incomplete", "message": "Self-managed Auth configuration errors: BETTER_AUTH_SECRET is not set; ..." }
+```
+
+with status `503` and `private, no-store`. The affected paths are `/admin` and `/admin/*`, `/api/auth` and `/api/auth/*`, `/oauth` and `/oauth/*`, `/.well-known/oauth*`, `/mcp` and `/mcp/*`. The message lists every failing check.
+
+## Secrets and local values
+
+```sh
+wrangler secret put BETTER_AUTH_SECRET
+wrangler secret put GITHUB_CLIENT_SECRET   # self-managed only
+```
+
+Non-secret vars go in `wrangler.jsonc` under `vars`. For local development put the same names in `.dev.vars`, which the minimal reference ignores in git (`.dev.vars*`). Never commit a secret.
+
+## First owner
+
+Every new user receives the default role `user`, which has no staff access. The first sign-in whose GitHub login matches `ADMIN_GITHUB_LOGIN` is promoted to `owner`. Promotion is blocked once any staff user exists, so the variable only bootstraps an empty site.
+
+## Roles
+
+Staff roles are `owner`, `editor` and `contributor`, in descending order. Owners manage them in Admin; the underlying routes are:
+
+| Route | Minimum role |
+|---|---|
+| `GET /admin/api/staff`, `PATCH /admin/api/staff/:id/role` (a role or `null` to revoke) | `owner` |
+| `POST /admin/api/staff/invitations`, `DELETE /admin/api/staff/invitations/:id` | `owner` |
+| `GET /admin/api/site-settings`, `PATCH /admin/api/site-settings` | `owner` |
+| `GET /admin/api/members` | `editor` |
+| `POST /admin/api/entries/:id/publish`, `POST /admin/api/entries/:id/unpublish`, `DELETE /admin/api/entries/:id` | `editor` |
+
+The staff role is re-read from D1 on every protected REST and MCP call; a revoked role takes effect on the next request. Manifest-level rules such as `requires.auth` are covered in [Authorization](../concepts/authorization.md) and the [authorization reference](../reference/authorization.md).
+
+## What needs a session
+
+| Surface | Requirement |
+|---|---|
+| `/admin`, `/admin/api/*` | Staff session; role gates per route |
+| `/api/auth/*`, `/oauth/*`, `/.well-known/oauth*` | Auth-owned; public endpoints of the OAuth flow |
+| `/mcp` | Any authenticated OAuth caller; anonymous requests get `401` with a `WWW-Authenticate` challenge |
+| `/mcp/staff` | Authenticated caller with a staff role |
+| `/<locale>/<segment>/<slug>?preview=1` | Staff session (`401` without a session, `403` without a staff role) |
+| Public Views, public HTTP Triggers, public pages, `.md`, `llms.txt`, sitemap | None, unless the manifest declares `requires` |
+
+MCP tokens are session-bound: signing out of Admin ends MCP access. See [MCP and agents](../concepts/mcp-and-agents.md).
+
+## Curated Better Auth surface
+
+`createAuth()` exposes curated fields, not a Better Auth passthrough: `database`, `baseURL`, `secret`, `methods`, `bootstrapOwner`, `oauthProvider`, `rateLimit`, and for first-party SSO `trustedOrigins`, `cookiePrefix` and `crossSubDomainCookies`. There is no `betterAuthOptions` or `advanced` escape hatch; a new Better Auth knob appears only when a Mantle use case justifies a first-class field.
+
+When several first-party apps share one parent domain that the same party controls, configure shared cookies explicitly. `cookiePrefix` is required whenever more than one Better Auth app writes cookies under that domain; `trustedOrigins` is the auth-flow trust list, not a CORS policy.
+
+```ts
+const auth = createAuth({
+  database: env.DB,
+  baseURL: "https://platform.example.com",
+  secret: env.BETTER_AUTH_SECRET,
+  methods,
+  trustedOrigins: ["https://example.com", "https://www.example.com"],
+  cookiePrefix: "example-platform",
+  crossSubDomainCookies: { enabled: true, domain: "example.com" },
+});
+```
+
+Shared cookies do not cross registrable domains. A browser never sends an `example.com` cookie to `customer.com`. For a customer-owned domain, use an OAuth/OIDC broker flow: the customer site redirects to the identity provider's authorize endpoint, receives the callback, verifies the response and creates its own local session. The broker returns identity; the customer site remains the authority for its members and grants.
+
+## Self-hosted and hosted
+
+A free self-hosted site runs every method `createAuth()` exposes: Better Auth social providers, email OTP, magic link, and parent-domain SSO. The owner supplies provider credentials, email sending and cookie policy. Hosted auth is an operations convenience: the platform holds provider and email configuration and registers the site as a PKCE client, while the site still owns grants, members, content and `ctx.user`/`ctx.staff` mapping. Neither mode changes the runtime's authorization vocabulary.
+
+## Replacing Auth construction
+
+```ts
+createMantleWorker({
+  plan,
+  auth: (env) => createAuth({ /* curated, site-specific methods */ }),
+});
+```
+
+With `auth` set, `MANTLE_AUTH_MODE` and the mode variables are not read. Core still owns the Auth routes: the factory's `basePath` joins the reserved paths, the MCP resource defaults to `auth.mcpResource ?? <PUBLIC_ORIGIN>/mcp`, and a rejected `auth.ready` evicts the isolate's assembly. Keep the D1 `DB` binding; Better Auth tables live there.
+
+## OAuth resource primitives
+
+When one Mantle site is an OAuth client of another, request a stable RFC 8707
+resource and use standard `offline_access` when refresh is needed:
+
+```ts
+const clientAuth = createAuth({
+  // database, baseURL, secret, other methods...
+  methods: [{
+    kind: "oauth",
+    providerId: "mantle-platform",
+    clientId: env.PLATFORM_CLIENT_ID,
+    discoveryUrl: "https://platform.example.com/api/auth/.well-known/openid-configuration",
+    scopes: ["openid", "offline_access", "accounts:read"],
+    resource: "https://api.example.com",
+  }],
+});
+
+const { accessToken, accessTokenExpiresAt, scopes } =
+  await clientAuth.getProviderAccessToken(request, "mantle-platform");
+```
+
+The server-side getter is bound to the current local session request and never
+returns a refresh token or account row. On the provider:
+
+```ts
+const providerAuth = createAuth({
+  // database, baseURL, secret, methods...
+  oauthProvider: {
+    loginPage: "/sign-in",
+    consentPage: "/consent",
+    scopes: ["openid", "offline_access", "accounts:read"],
+    resources: ["https://api.example.com"],
+  },
+});
+
+const verification = await providerAuth.verifyOAuthAccessToken(request, {
+  audience: "https://api.example.com",
+  scopes: ["accounts:read"],
+});
+```
+
+The verifier accepts JWT access tokens only and checks the configured issuer,
+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.
+
+## Source
+- [`packages/adapters/cloudflare/README.md`](../../../packages/adapters/cloudflare/README.md)
+- [`packages/adapters/cloudflare/src/auth/conventionalAuth.ts`](../../../packages/adapters/cloudflare/src/auth/conventionalAuth.ts)
+- [`packages/adapters/cloudflare/src/auth/createAuth.ts`](../../../packages/adapters/cloudflare/src/auth/createAuth.ts)
+- [`packages/adapters/cloudflare/src/worker/createMantleWorker.ts`](../../../packages/adapters/cloudflare/src/worker/createMantleWorker.ts)
+- [`packages/adapters/cloudflare/src/mount/mountPublicRoutes.ts`](../../../packages/adapters/cloudflare/src/mount/mountPublicRoutes.ts)
+- [`packages/adapters/cloudflare/src/mount/mountMcp.ts`](../../../packages/adapters/cloudflare/src/mount/mountMcp.ts)
+- [`packages/mantle-admin/src/mountMantleAdmin.ts`](../../../packages/mantle-admin/src/mountMantleAdmin.ts)
+- [`docs/auth-hosting-model.md`](../../../docs/auth-hosting-model.md)
+- [`docs/adapter-guide.md`](../../../docs/adapter-guide.md)
+- [`docs/examples/minimal-worker/.gitignore`](../../../docs/examples/minimal-worker/.gitignore)

package/docs/handbook/cloudflare/bindings.md

@@ -0,0 +1,236 @@
+---
+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 tables (`entries`, site settings, media, Auth) 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 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" }
+```
+
+`mantle generate` syncs the Admin SPA into `public/_mantle/admin/` when `@aotter/mantle-admin-ui` is installed. 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.
+
+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. 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).
+
+## 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 transaction](../examples/commerce-transaction.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 form](../examples/intake-form.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/minimal-worker/wrangler.jsonc`](../../../docs/examples/minimal-worker/wrangler.jsonc)
+- Retired-starter patterns: [`blank/wrangler.toml`](https://github.com/aotter/mantle-starters/blob/a66ec0ea3aaefc09a0229b7d8ca35af630f2b55d/blank/wrangler.toml), [`overlays/transaction/wrangler.append.toml`](https://github.com/aotter/mantle-starters/blob/a66ec0ea3aaefc09a0229b7d8ca35af630f2b55d/overlays/transaction/wrangler.append.toml), [`overlays/transaction/src/index.ts`](https://github.com/aotter/mantle-starters/blob/a66ec0ea3aaefc09a0229b7d8ca35af630f2b55d/overlays/transaction/src/index.ts), [`overlays/transaction/src/mantle/config.ts`](https://github.com/aotter/mantle-starters/blob/a66ec0ea3aaefc09a0229b7d8ca35af630f2b55d/overlays/transaction/src/mantle/config.ts), [`overlays/intake/src/worker/features/intake/notifyIntake.ts`](https://github.com/aotter/mantle-starters/blob/a66ec0ea3aaefc09a0229b7d8ca35af630f2b55d/overlays/intake/src/worker/features/intake/notifyIntake.ts), [`overlays/intake/manifests/site.yaml`](https://github.com/aotter/mantle-starters/blob/a66ec0ea3aaefc09a0229b7d8ca35af630f2b55d/overlays/intake/manifests/site.yaml)