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

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

@@ -1,106 +1,5 @@
-# Low-level Cloudflare Worker composition
+# Cloudflare low-level composition
 
-Use `createMantleWorker` unless the application must own the top-level Worker
-assembly. This copyable fixture keeps Mantle's standard bindings, Auth,
-Admin/API routes, OAuth/MCP dispatch, cache policy and redacted error boundary,
-while adding one application-owned post-response Queue audit across every route.
+This guide moved into the handbook: [`docs/handbook/cloudflare/low-level-composition.md`](handbook/cloudflare/low-level-composition.md).
 
-```ts
-import { Hono } from "hono";
-import {
-  applyCachePolicy,
-  conventionalMcpResource,
-  createMantleRuntimeRef,
-  createConventionalAuth,
-  createConventionalBindings,
-  createMcpApiHandler,
-  mountAuthorize,
-  mountAdmin,
-  mountRuntimeEndpoints,
-  runMantleWorkerRequest,
-  setupIncompleteAuthResponse,
-  type MantleCloudflareEnv,
-} from "@aotter/mantle/cloudflare";
-import { plan } from "../.mantle/generated/mantle.js";
-
-interface Env extends MantleCloudflareEnv {
-  readonly AUDIT_QUEUE: Queue<{
-    readonly kind: "request-complete";
-    readonly path: string;
-    readonly status: number;
-  }>;
-}
-
-let assembled: ReturnType<typeof assemble> | undefined;
-
-export default {
-  fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
-    return runMantleWorkerRequest(async () => {
-      assembled ??= assemble(env);
-      const incomplete = await setupIncompleteAuthResponse(request, assembled.auth);
-      const response = incomplete ?? await assembled.fetch(request, env, ctx);
-      ctx.waitUntil(env.AUDIT_QUEUE.send({
-        kind: "request-complete",
-        path: new URL(request.url).pathname,
-        status: response.status,
-      }));
-      return response;
-    });
-  },
-} satisfies ExportedHandler<Env>;
-
-function assemble(env: Env) {
-  const bindings = createConventionalBindings(env);
-  const auth = createConventionalAuth(env);
-  const ref = createMantleRuntimeRef({ plan, bindings, auth });
-  const app = new Hono<{ Bindings: Env }>();
-
-  mountRuntimeEndpoints(app, ref);
-  if (bindings.adminAssets) mountAdmin(app, ref, bindings.adminAssets);
-  mountAuthorize(app, { auth });
-  app.get("/cache-probe", () => new Response("public", {
-    headers: { "cache-control": "public, s-maxage=60" },
-  }));
-
-  const resource = conventionalMcpResource(env);
-  const mcp = new Map([
-    ["/mcp/staff", createMcpApiHandler<Env>({ ref, surface: "staff", resource })],
-    ["/mcp", createMcpApiHandler<Env>({ ref, surface: "public", resource })],
-  ]);
-  return {
-    auth,
-    async fetch(request: Request, workerEnv: Env, ctx: ExecutionContext) {
-      // Low-level owners must prepare the canonical D1 schema before Better
-      // Auth handles a token, client, consent, or CIMD request.
-      await ref.get();
-      const handler = mcp.get(new URL(request.url).pathname);
-      const response = handler?.fetch
-        ? await handler.fetch(request, workerEnv, ctx)
-        : await app.fetch(request, workerEnv, ctx);
-      return applyCachePolicy(request, response);
-    },
-  };
-}
-```
-
-Keep the conventional `DB` binding and `nodejs_compat`. CIMD metadata fetches
-also require `global_fetch_strictly_public`; add the Queue producer in
-`wrangler.jsonc`:
-
-```jsonc
-{
-  "compatibility_flags": ["nodejs_compat", "global_fetch_strictly_public"],
-  "queues": {
-    "producers": [
-      { "binding": "AUDIT_QUEUE", "queue": "my-site-audit" }
-    ]
-  }
-}
-```
-
-After copying, the Worker entry, request audit, custom route and Queue contract
-belong to the application. Mantle still owns the imported adapters and
-standard route behavior; update them through the package version. Do not copy
-their source or replace Auth, MCP or cache handling locally. A copied
-composition has no automatic merge path back to `createMantleWorker`; keep it
-only while the custom top-level lifecycle remains necessary.
+The handbook ships inside the `@aotter/mantle` package under `node_modules/@aotter/mantle/docs/handbook/` and describes the installed release.

package/docs/deferred-lifecycle-queues.md

@@ -1,246 +1,5 @@
 # Deferred lifecycle hooks on Cloudflare Queues
 
-Mantle can opt `after_*` lifecycle Triggers into a Cloudflare Queue. This is
-useful for notifications and projections that should not add request latency,
-but it is not an exactly-once transaction boundary.
+This guide moved into the handbook: [`docs/handbook/cloudflare/deferred-hooks-queues.md`](handbook/cloudflare/deferred-hooks-queues.md).
 
-## Contract
-
-- The entry write commits before Queue delivery. D1 and Queue do not share a
-  transaction, so a Worker failure can still occur in that gap.
-- A resolved `Queue.send()` means Cloudflare accepted the message. Consumption
-  is at-least-once; a message can run more than once.
-- A rejected or ambiguous send falls back with the same event identity through
-  `ctx.waitUntil`, or inline when `waitUntil` is unavailable. `waitUntil` is
-  best-effort and does not close the D1-to-Queue gap.
-- A consumer acknowledges a message only after every captured Trigger
-  succeeds. It runs all captured Triggers before surfacing failures, so a later
-  failure can replay an earlier success.
-- Malformed, unsupported, removed-Trigger, and persistently failing messages
-  are retried and then sent to the configured dead-letter queue (DLQ). Without
-  a DLQ, Cloudflare discards them after `max_retries`.
-
-Deferred handlers must therefore be idempotent. Mantle does not promise
-exactly-once execution.
-
-## Version 1 event
-
-The strict v1 envelope contains:
-
-```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;
-}
-```
-
-`triggerNames` is captured when the entry mutation runs. A later deployment
-does not add a new Trigger to an old event. Removing or renaming a captured
-Trigger makes that old message fail validation at dispatch and eventually
-reach the DLQ instead of silently changing its meaning.
-
-Each handler receives persisted `entry.data` as its input and:
-
-```ts
-ctx.event = {
-  id: envelope.eventId,
-  trigger: currentTriggerName,
-  hook: envelope.hook,
-  schema: envelope.schema,
-  entry: envelope.entry,
-};
-```
-
-Use `${ctx.event.id}:${ctx.event.trigger}` as the handler's idempotency key.
-The same key survives enqueue fallback, Queue retries, and replay. Synchronous
-`before_*` hooks may still receive pre-projection request input such as a
-CAPTCHA token; deferred `after_*` envelopes never retain that input. The
-identity snapshot contains normalized actor and credential metadata, never raw
-cookies, tokens, or API keys.
-
-Cloudflare's 128 KB limit is decimal and includes platform metadata. The
-adapter therefore rejects non-JSON envelopes and encoded envelopes at or above
-127,000 bytes before calling `Queue.send`, leaving at least 1 KB of headroom.
-Keep entry payloads smaller than that supported limit.
-
-## Cloudflare opt-in
-
-Create the internal queue and its DLQ:
-
-```sh
-pnpm wrangler queues create mantle-internal
-pnpm wrangler queues create mantle-internal-dlq
-```
-
-Add both producer and consumer bindings. These are adapter settings, not Mantle
-manifest grammar:
-
-```toml
-[[queues.producers]]
-binding = "MANTLE_INTERNAL_QUEUE"
-queue = "mantle-internal"
-
-[[queues.consumers]]
-queue = "mantle-internal"
-max_batch_size = 10
-max_batch_timeout = 5
-max_retries = 5
-retry_delay = 60
-dead_letter_queue = "mantle-internal-dlq"
-```
-
-Wire the producer into `MantleCloudflareConfig.bindings` and export the consumer alongside
-the existing HTTP/OAuth handler. The same Worker may be both producer and
-consumer:
-
-```ts
-import type { DeferredHookEnvelope } from "@aotter/mantle/runtime";
-import {
-  WorkersQueueHookDispatcher,
-  createMantleWorker,
-  createQueueHandler,
-  type MantleCloudflareEnv,
-} from "@aotter/mantle/cloudflare";
-
-interface Env extends MantleCloudflareEnv {
-  DB: D1Database;
-  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>;
-```
-
-Queue opt-in adds only the dispatcher binding and `queue` export; the facade
-keeps Auth, MCP, cache, and runtime assembly on the standard path.
-
-## Idempotent handlers
-
-For a D1-owned effect, make the event/Trigger key a unique database key. This
-example records a site-owned notification job exactly once even when the
-lifecycle handler is replayed:
-
-```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";
-
-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 that supports idempotency, send the same stable key and
-throw on failure so Queue retries it:
-
-```ts
-const key = `${ctx.event!.id}:${ctx.event!.trigger}`;
-const response = await fetch("https://api.example.com/messages", {
-  method: "POST",
-  headers: {
-    "Content-Type": "application/json",
-    "Idempotency-Key": key,
-  },
-  body: JSON.stringify(input),
-});
-if (!response.ok) throw new Error(`message provider returned ${response.status}`);
-```
-
-Core intentionally does not add a business outbox, payment state machine,
-provider retry wrapper, or generic job registry. Those remain site-owned.
-
-## Multiplexing site queues
-
-One Worker can consume the Mantle queue and site-owned queues without a Core
-registry. Route on `batch.queue` in the Worker entry:
-
-```ts
-const mantleQueue = createQueueHandler<Env>(cms);
-
-export default {
-  fetch: http.fetch.bind(http),
-  queue(batch, env, ctx) {
-    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}'`);
-        return;
-    }
-  },
-} satisfies ExportedHandler<Env>;
-```
-
-The Mantle consumer processes at most five messages concurrently within each
-delivered batch even if `max_batch_size` is raised. It calls `retryAll()` when
-runtime boot fails, `retry()` for one failed event, and `ack()` exactly once
-after success.
-
-## Verification and operations
-
-Run the integrated contract test:
-
-```sh
-pnpm --filter @aotter/mantle-cloudflare test -- mantle-internal-queue.test.ts
-```
-
-It covers real runtime failure propagation, all-Trigger execution, stable
-replay identity, per-message ack/retry, malformed bodies, size/JSON rejection,
-runtime boot failure, and the five-message concurrency bound.
-
-For a site integration, run `wrangler dev`, submit a mutation with an
-`after_*` Trigger, and verify the consumer log. Make one handler fail once and
-confirm its first delivery is retried and the replay sees the same
-`ctx.event.id` and `ctx.event.trigger`. Inspect the DLQ before increasing
-`max_retries`; poison messages otherwise hide as repeated retries.
-
-### Upgrading from the unversioned envelope
-
-Version 1 intentionally rejects the old unversioned envelope and the old
-`originalInput` field. Before deploying this release to a Worker that already
-uses `mantle-internal`, stop old producers and drain the queue (including any
-in-flight retries), or explicitly move the remaining messages to an operator
-workflow. Deploying v1 with legacy messages still queued will retry those
-messages and eventually place them in the DLQ.
+The handbook ships inside the `@aotter/mantle` package under `node_modules/@aotter/mantle/docs/handbook/` and describes the installed release.