@aotter/mantle-cloudflare 0.0.11-alpha.59 → 0.0.11-alpha.61

package/README.md

@@ -72,3 +72,18 @@ of the Core SDK skill contract or Day 1 landing path. Use the Cloudflare recipe
 only when a site actually needs staff-managed images or files:
 
 <https://raw.githubusercontent.com/aotter/mantle/develop/docs/media-uploads.md>
+
+## Optional deferred lifecycle hooks
+
+`WorkersQueueHookDispatcher` and `createQueueHandler` opt `after_*` lifecycle
+Triggers into Cloudflare Queues. Delivery is at-least-once, not exactly-once;
+the D1 write and Queue send are not atomic, and fallback through `waitUntil` is
+best-effort. Handlers receive a stable `ctx.event.id` plus
+`ctx.event.trigger` for idempotency. The adapter validates strict v1 JSON
+envelopes, reserves metadata headroom under Cloudflare's 128 KB message limit,
+and maps failures to per-message retry/DLQ behavior.
+
+Producer/consumer bindings, Worker export, idempotent D1/upstream examples,
+site-queue multiplexing, verification, and the legacy-envelope drain step are
+in the shipped
+[deferred lifecycle Queue guide](../../../docs/deferred-lifecycle-queues.md).

package/dist/bindings/D1DatabaseDriver.js

@@ -106,7 +106,21 @@ class D1Migrations {
             ops.push(this.db
                 .prepare(`INSERT INTO _migrations (id, applied_at) VALUES (?, ?)`)
                 .bind(m.id, Date.now()));
-            await this.db.batch(ops);
+            try {
+                await this.db.batch(ops);
+            }
+            catch (error) {
+                // Two cold starts can read the same stale `seen` snapshot. The
+                // losing batch rolls back atomically; accept it only when the
+                // winner has recorded this exact migration in the meantime.
+                const winner = await this.db
+                    .prepare(`SELECT id FROM _migrations WHERE id = ?`)
+                    .bind(m.id)
+                    .first();
+                if (winner?.id !== m.id)
+                    throw error;
+            }
+            seen.add(m.id);
         }
     }
 }

package/dist/bindings/D1DatabaseDriver.js.map

@@ -1 +1 @@
-{"version":3,"file":"D1DatabaseDriver.js","sourceRoot":"","sources":["../../src/bindings/D1DatabaseDriver.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"D1DatabaseDriver.js","sourceRoot":"","sources":["../../src/bindings/D1DatabaseDriver.ts"],"names":[],"mappings":"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"}

package/dist/bindings/WorkersQueueHookDispatcher.d.ts

@@ -2,10 +2,9 @@ import type { CmsRuntime, DeferredHookDispatcher, DeferredHookEnvelope } from "@
 /**
  * `DeferredHookDispatcher` impl backed by a Cloudflare Workers Queue
  * binding. Producer side: serialises each `DeferredHookEnvelope` and
- * sends it via `queue.send`. The runtime decorator handles fallback
- * on rejection (its three-rung ladder downgrades to `ctx.waitUntil`
- * → inline-await), so this dispatcher does not retry — it lets the
- * caller decide.
+ * sends it explicitly as JSON. The runtime decorator handles a
+ * rejection with its best-effort fallback. Queue acceptance is not
+ * atomic with the preceding D1 mutation.
  *
  * Per ADR-0011 only this adapter package may import the CF binding
  * type. The runtime sees only the `DeferredHookDispatcher` port.
@@ -17,7 +16,7 @@ export declare class WorkersQueueHookDispatcher implements DeferredHookDispatche
 }
 /**
  * Build the `queue(batch, env, ctx)` Workers handler that consumes
- * `mantle_internal` messages and re-fires each `after_*` hook through
+ * `mantle-internal` messages and re-fires each `after_*` hook through
  * the runtime. Consumers wire this alongside `fetch` in their default
  * Worker export:
  *
@@ -28,11 +27,11 @@ export declare class WorkersQueueHookDispatcher implements DeferredHookDispatche
  * } satisfies ExportedHandler<Env>;
  * ```
  *
- * Per-message ack / retry: a thrown handler error retries the
- * message; success acks. CF Queues then handles backoff and the
- * dead-letter queue per the binding's wrangler config.
+ * Per-message ack / retry: any validation or handler failure retries
+ * the message; success acks. CF Queues then applies the consumer's
+ * retry delay, max_retries, and DLQ configuration.
  */
 export declare function createQueueHandler<Env>(cmsRef: {
     get(): Promise<CmsRuntime>;
-}): (batch: MessageBatch<DeferredHookEnvelope>, env: Env) => Promise<void>;
+}): (batch: MessageBatch<unknown>, env: Env) => Promise<void>;
 //# sourceMappingURL=WorkersQueueHookDispatcher.d.ts.map

package/dist/bindings/WorkersQueueHookDispatcher.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"WorkersQueueHookDispatcher.d.ts","sourceRoot":"","sources":["../../src/bindings/WorkersQueueHookDispatcher.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,UAAU,EACV,sBAAsB,EACtB,oBAAoB,EACrB,MAAM,wBAAwB,CAAC;AAEhC;;;;;;;;;;GAUG;AACH,qBAAa,0BAA2B,YAAW,sBAAsB;IAC3D,OAAO,CAAC,QAAQ,CAAC,KAAK;gBAAL,KAAK,EAAE,KAAK,CAAC,oBAAoB,CAAC;IAEzD,OAAO,CAAC,QAAQ,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC;CAG7D;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EACpC,MAAM,EAAE;IAAE,GAAG,IAAI,OAAO,CAAC,UAAU,CAAC,CAAA;CAAE,GACrC,CAAC,KAAK,EAAE,YAAY,CAAC,oBAAoB,CAAC,EAAE,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,CAgCxE"}
+{"version":3,"file":"WorkersQueueHookDispatcher.d.ts","sourceRoot":"","sources":["../../src/bindings/WorkersQueueHookDispatcher.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,UAAU,EACV,sBAAsB,EACtB,oBAAoB,EACrB,MAAM,wBAAwB,CAAC;AAUhC;;;;;;;;;GASG;AACH,qBAAa,0BAA2B,YAAW,sBAAsB;IAC3D,OAAO,CAAC,QAAQ,CAAC,KAAK;gBAAL,KAAK,EAAE,KAAK,CAAC,oBAAoB,CAAC;IAEzD,OAAO,CAAC,QAAQ,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC;CAiC7D;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EACpC,MAAM,EAAE;IAAE,GAAG,IAAI,OAAO,CAAC,UAAU,CAAC,CAAA;CAAE,GACrC,CAAC,KAAK,EAAE,YAAY,CAAC,OAAO,CAAC,EAAE,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,CAkC3D"}

package/dist/bindings/WorkersQueueHookDispatcher.js

@@ -1,10 +1,16 @@
+import { z } from "zod";
+// Cloudflare's 128 KB limit is decimal and includes roughly 100 bytes
+// of platform metadata. Reserve a full 1 KB so accepted envelopes stay
+// below the provider limit rather than failing only at queue.send.
+const MAX_ENVELOPE_BYTES = 127_000;
+const MAX_CONCURRENCY = 5;
+const jsonValue = z.json();
 /**
  * `DeferredHookDispatcher` impl backed by a Cloudflare Workers Queue
  * binding. Producer side: serialises each `DeferredHookEnvelope` and
- * sends it via `queue.send`. The runtime decorator handles fallback
- * on rejection (its three-rung ladder downgrades to `ctx.waitUntil`
- * → inline-await), so this dispatcher does not retry — it lets the
- * caller decide.
+ * sends it explicitly as JSON. The runtime decorator handles a
+ * rejection with its best-effort fallback. Queue acceptance is not
+ * atomic with the preceding D1 mutation.
  *
  * Per ADR-0011 only this adapter package may import the CF binding
  * type. The runtime sees only the `DeferredHookDispatcher` port.
@@ -15,12 +21,36 @@ export class WorkersQueueHookDispatcher {
         this.queue = queue;
     }
     async enqueue(envelope) {
-        await this.queue.send(envelope);
+        // `EntryRow.locale?` may be present with value `undefined` in a
+        // repository object. JSON transport omits that optional field;
+        // normalize only this declared optional before the strict
+        // JSON-safe check so undefined values inside entry.data still
+        // fail instead of disappearing silently.
+        const { locale, ...entryWithoutLocale } = envelope.entry;
+        const wireEnvelope = locale === undefined
+            ? { ...envelope, entry: entryWithoutLocale }
+            : envelope;
+        let json;
+        try {
+            json = jsonValue.safeParse(wireEnvelope);
+        }
+        catch (cause) {
+            throw new Error(`Deferred lifecycle envelope '${envelope.eventId}' is not JSON-safe.`, { cause });
+        }
+        if (!json.success) {
+            const issue = json.error.issues[0];
+            throw new Error(`Deferred lifecycle envelope '${envelope.eventId}' is not JSON-safe at '${issue?.path.join("/") ?? "unknown"}'.`);
+        }
+        const bytes = new TextEncoder().encode(JSON.stringify(json.data)).byteLength;
+        if (bytes >= MAX_ENVELOPE_BYTES) {
+            throw new Error(`Deferred lifecycle envelope '${envelope.eventId}' is ${bytes} bytes; this adapter requires less than ${MAX_ENVELOPE_BYTES} to leave room under Cloudflare's 128 KB message limit.`);
+        }
+        await this.queue.send(wireEnvelope, { contentType: "json" });
     }
 }
 /**
  * Build the `queue(batch, env, ctx)` Workers handler that consumes
- * `mantle_internal` messages and re-fires each `after_*` hook through
+ * `mantle-internal` messages and re-fires each `after_*` hook through
  * the runtime. Consumers wire this alongside `fetch` in their default
  * Worker export:
  *
@@ -31,9 +61,9 @@ export class WorkersQueueHookDispatcher {
  * } satisfies ExportedHandler<Env>;
  * ```
  *
- * Per-message ack / retry: a thrown handler error retries the
- * message; success acks. CF Queues then handles backoff and the
- * dead-letter queue per the binding's wrangler config.
+ * Per-message ack / retry: any validation or handler failure retries
+ * the message; success acks. CF Queues then applies the consumer's
+ * retry delay, max_retries, and DLQ configuration.
  */
 export function createQueueHandler(cmsRef) {
     return async (batch, env) => {
@@ -46,23 +76,28 @@ export function createQueueHandler(cmsRef) {
             // batch.retryAll so each message's per-message attempt counter
             // increments — letting wrangler's max_retries / DLQ rules
             // engage instead of looping forever at the batch level.
-            console.error("[mantle-internal] runtime boot failed; retrying batch", err);
             batch.retryAll();
+            console.error("[mantle-internal] runtime boot failed; retrying batch", err);
             return;
         }
-        // Drain in parallel — after-hooks are independent and CF Queues
-        // ack/retry is per-message, so serial processing only burns the
-        // 30s consumer wall clock on larger batches.
-        await Promise.allSettled(batch.messages.map(async (message) => {
-            try {
-                await cms.runDeferredHook.execute({ envelope: message.body, env });
-                message.ack();
-            }
-            catch (err) {
-                console.error(`[mantle-internal] consume failed for ${message.body.hook} on ${message.body.schema}/${message.body.entry.id}`, err);
-                message.retry();
-            }
-        }));
+        // Bound fan-out even when a consumer raises max_batch_size.
+        for (let offset = 0; offset < batch.messages.length; offset += MAX_CONCURRENCY) {
+            const chunk = batch.messages.slice(offset, offset + MAX_CONCURRENCY);
+            await Promise.all(chunk.map(async (message) => {
+                try {
+                    await cms.runDeferredHook.execute({ envelope: message.body, env });
+                    message.ack();
+                }
+                catch (err) {
+                    message.retry();
+                    console.error("[mantle-internal] deferred lifecycle consume failed; retrying", {
+                        messageId: message.id,
+                        attempts: message.attempts,
+                        error: err,
+                    });
+                }
+            }));
+        }
     };
 }
 //# sourceMappingURL=WorkersQueueHookDispatcher.js.map

package/dist/bindings/WorkersQueueHookDispatcher.js.map

@@ -1 +1 @@
-{"version":3,"file":"WorkersQueueHookDispatcher.js","sourceRoot":"","sources":["../../src/bindings/WorkersQueueHookDispatcher.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;GAUG;AACH,MAAM,OAAO,0BAA0B;IACR;IAA7B,YAA6B,KAAkC;QAAlC,UAAK,GAAL,KAAK,CAA6B;IAAG,CAAC;IAEnE,KAAK,CAAC,OAAO,CAAC,QAA8B;QAC1C,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAClC,CAAC;CACF;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,kBAAkB,CAChC,MAAsC;IAEtC,OAAO,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;QAC1B,IAAI,GAAe,CAAC;QACpB,IAAI,CAAC;YACH,GAAG,GAAG,MAAM,MAAM,CAAC,GAAG,EAAE,CAAC;QAC3B,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,yDAAyD;YACzD,+DAA+D;YAC/D,0DAA0D;YAC1D,wDAAwD;YACxD,OAAO,CAAC,KAAK,CAAC,uDAAuD,EAAE,GAAG,CAAC,CAAC;YAC5E,KAAK,CAAC,QAAQ,EAAE,CAAC;YACjB,OAAO;QACT,CAAC;QACD,gEAAgE;QAChE,gEAAgE;QAChE,6CAA6C;QAC7C,MAAM,OAAO,CAAC,UAAU,CACtB,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE;YACnC,IAAI,CAAC;gBACH,MAAM,GAAG,CAAC,eAAe,CAAC,OAAO,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,IAAI,EAAE,GAAG,EAAE,CAAC,CAAC;gBACnE,OAAO,CAAC,GAAG,EAAE,CAAC;YAChB,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,OAAO,CAAC,KAAK,CACX,wCAAwC,OAAO,CAAC,IAAI,CAAC,IAAI,OAAO,OAAO,CAAC,IAAI,CAAC,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,EAC9G,GAAG,CACJ,CAAC;gBACF,OAAO,CAAC,KAAK,EAAE,CAAC;YAClB,CAAC;QACH,CAAC,CAAC,CACH,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"WorkersQueueHookDispatcher.js","sourceRoot":"","sources":["../../src/bindings/WorkersQueueHookDispatcher.ts"],"names":[],"mappings":"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"}

package/dist/mount/cmsConfig.d.ts

@@ -18,10 +18,11 @@ export interface CmsConfig {
          *  `/admin/api/media/*` endpoints are registered. Forwarded to the
          *  runtime as `mediaStorage`. */
         readonly mediaStorage?: CreateCmsRuntimeArgs["mediaStorage"];
-        /** Optional deferred-delivery dispatcher. When set, `after_*`
-         *  lifecycle hooks fire through this instead of riding
-         *  `ctx.waitUntil`. The Cloudflare adapter expects a
-         *  `WorkersQueueHookDispatcher` bound to the `mantle_internal` queue
+        /** Optional at-least-once dispatcher. When set, `after_*`
+         *  lifecycle hooks enqueue after the entry write; a rejected send
+         *  falls back to best-effort `ctx.waitUntil`/inline execution. The
+         *  Cloudflare adapter expects a
+         *  `WorkersQueueHookDispatcher` bound to the `mantle-internal` queue
          *  here. */
         readonly deferredHookDispatcher?: CreateCmsRuntimeArgs["deferredHookDispatcher"];
     };

package/dist/mount/cmsConfig.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cmsConfig.d.ts","sourceRoot":"","sources":["../../src/mount/cmsConfig.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,UAAU,EACV,oBAAoB,EACpB,kBAAkB,EAClB,gBAAgB,EACjB,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAClE,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAClD,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAC;AAErE;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,SAAS,EAAE,SAAS,QAAQ,EAAE,CAAC;IACxC,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC;IACzD,QAAQ,CAAC,SAAS,CAAC,EAAE,gBAAgB,CAAC;IACtC,QAAQ,CAAC,YAAY,CAAC,EAAE,YAAY,CAAC;IACrC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IACjD,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC,oBAAoB,EAAE,IAAI,GAAG,IAAI,GAAG,QAAQ,CAAC,GAAG;QACtE;;yCAEiC;QACjC,QAAQ,CAAC,YAAY,CAAC,EAAE,oBAAoB,CAAC,cAAc,CAAC,CAAC;QAC7D;;;;oBAIY;QACZ,QAAQ,CAAC,sBAAsB,CAAC,EAAE,oBAAoB,CAAC,wBAAwB,CAAC,CAAC;KAClF,CAAC;IACF,gEAAgE;IAChE,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB;;yBAEqB;IACrB,QAAQ,CAAC,kBAAkB,CAAC,EAAE,0BAA0B,CAAC;IACzD,sEAAsE;IACtE,QAAQ,CAAC,WAAW,CAAC,EAAE;QACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;KACrC,CAAC;CACH"}
+{"version":3,"file":"cmsConfig.d.ts","sourceRoot":"","sources":["../../src/mount/cmsConfig.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,UAAU,EACV,oBAAoB,EACpB,kBAAkB,EAClB,gBAAgB,EACjB,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAClE,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAClD,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAC;AAErE;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,SAAS,EAAE,SAAS,QAAQ,EAAE,CAAC;IACxC,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC;IACzD,QAAQ,CAAC,SAAS,CAAC,EAAE,gBAAgB,CAAC;IACtC,QAAQ,CAAC,YAAY,CAAC,EAAE,YAAY,CAAC;IACrC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IACjD,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC,oBAAoB,EAAE,IAAI,GAAG,IAAI,GAAG,QAAQ,CAAC,GAAG;QACtE;;yCAEiC;QACjC,QAAQ,CAAC,YAAY,CAAC,EAAE,oBAAoB,CAAC,cAAc,CAAC,CAAC;QAC7D;;;;;oBAKY;QACZ,QAAQ,CAAC,sBAAsB,CAAC,EAAE,oBAAoB,CAAC,wBAAwB,CAAC,CAAC;KAClF,CAAC;IACF,gEAAgE;IAChE,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB;;yBAEqB;IACrB,QAAQ,CAAC,kBAAkB,CAAC,EAAE,0BAA0B,CAAC;IACzD,sEAAsE;IACtE,QAAQ,CAAC,WAAW,CAAC,EAAE;QACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;KACrC,CAAC;CACH"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aotter/mantle-cloudflare",
-  "version": "0.0.11-alpha.59",
+  "version": "0.0.11-alpha.61",
   "description": "Cloudflare Workers adapter for mantle. Hono-based mountServerEndpoints / createMcpApiHandler / mountAuthorize / mountPublicRoutes. Better Auth for staff sign-in; @cloudflare/workers-oauth-provider for the MCP OAuth AS surface.",
   "license": "Apache-2.0",
   "homepage": "https://mantle.tools/",
@@ -30,9 +30,9 @@
   ],
   "dependencies": {
     "@better-auth/oauth-provider": "^1.6.23",
-    "@aotter/mantle-admin-ui": "0.0.11-alpha.59",
-    "@aotter/mantle-runtime": "0.0.11-alpha.59",
-    "@aotter/mantle-spec": "0.0.11-alpha.59"
+    "@aotter/mantle-admin-ui": "0.0.11-alpha.61",
+    "@aotter/mantle-runtime": "0.0.11-alpha.61",
+    "@aotter/mantle-spec": "0.0.11-alpha.61"
   },
   "peerDependencies": {
     "@cloudflare/workers-oauth-provider": "^0.8.0",