@worker-protocol/cloudflare 0.7.0 → 0.8.1

package/README.md

@@ -34,6 +34,7 @@ to watch in a first deployment.
 | `withSubscriptions` | SUB-7's subscriptions, found and ensured in one step | **one** object, never one per shard |
 | `withOutbox` | an outbox, drained when a call ends and retried by the alarm | every object whose changes raise events |
 | `withLogs` | LOG-2's window, filtered and paged in SQL | the object `/logs` reads, and a Tail Worker writes |
+| `withLifecycle` | EVT-15's births and endings of Tasks and Alerts, found by comparing snapshots | over `withOutbox`, in the object whose Facts the Tasks and Alerts derive from |
 
 Mixins rather than one base class, because a Worker in production keeps one object per vehicle and
 one for the fleet: the subscriptions belong in the one, an outbox in every other, and a class that
@@ -155,12 +156,17 @@ export default {
 };
 ```
 
-The consumer of the events Queue publishes each batch through the hub — the subscriptions are read
-once per type for the whole batch — and leaves one delivery per matching subscription on the
-deliveries Queue, then hands each event to the broker. An event of a type the Worker does not
-declare is set aside rather than retried, since no retry would mend it, and a failure to reach the
-store retries the batch whole, once. The consumer of the deliveries Queue runs `deliver()` and hands
-its decision back: `retry({ delaySeconds })`, or `ack()`.
+The consumer of the events Queue routes each batch through the hub — the subscriptions are read once
+per type for the whole batch — and **makes the first attempt at every delivery itself**, reading
+each subscription once, then hands each event to the broker. Only what the hub asks to retry goes to
+the deliveries Queue, with the delay it asked for: each Queue costs a batch wait, and an event that
+crossed both before its first attempt arrived seconds after the Fact that caused it. A sink slower
+than the hub's `attemptTimeoutMs` (ten seconds by default) holds the batch that long and is retried
+like any failure. An event the Worker's own declaration refuses — an undeclared type (EVT-12) or
+an undeclared extension (EVT-18) — is set aside rather than retried, since no retry would mend it,
+and a failure to reach the store retries the batch whole, once. The consumer of the deliveries
+Queue runs the later attempts and hands each decision back: `retry({ delaySeconds })`, or `ack()`,
+backing off from the larger of the attempt the delivery carries and the one the Queue counted.
 
 What is given up goes to the dead-letter queue as a `GivenUp`, tagged by its `kind` — a delivery
 refused for good, outside EVT-8's window or abandoned with its subscription, with the reason; or an
@@ -169,6 +175,42 @@ through `/logs`. Name the same queue as each consumer's `dead_letter_queue` in
 `wrangler.jsonc`, so it also receives what the platform drops after `max_retries`, and set
 `max_retries` well above what the hub asks for: its default of 3 cuts a delivery short.
 
+## The lifecycle of Tasks and Alerts
+
+```ts
+export class Intake extends withLifecycle(withOutbox(DurableObject<Env>, { events: (env) => env.EVENTS })) {
+  snapshot(at: number) {
+    return { tasks: openTasks(at, this.facts()), alerts: alerts(at, this.facts()) };
+  }
+  nextChange(after: number) {
+    return nextMinute(after); // or the next deadline, the end of an incident
+  }
+  async pause(source: string, now: number) {
+    this.changing(now, () => this.write(source, now)); // owes what the write changed
+    await this.flush();
+  }
+}
+```
+
+A Worker that derives its Tasks and Alerts from Facts supplies the two methods above, and
+`withLifecycle` owes their births and endings (EVT-15). It compares at every instant `nextChange`
+names since the last one compared — the mark survives the object, so a missed run leaves no gap, and
+one further behind than `catchUpMs` gives the rest up and calls `lifecycleSkipped` — and an Action's
+`changing(now, write)` compares the instant before its write and after it, in the same transaction.
+Every id is derived from the transition, the resource and its `since`, and the ids owed are kept for
+`keepAnnouncedMs`, so a change seen twice is owed once; an ending whose birth was never announced
+brings its birth with it. `heartbeat()` compares up to now and points the shared alarm at the next
+instant; a cron that calls it starts the chain and restarts it if an alarm is lost.
+
+**What a mixin does internally is a function of its module, never a method.** `private` is
+TypeScript's alone: at run time it is a method on the prototype, and a Worker whose class declares
+one of the same name replaces it silently. Only the methods each mixin's interface lists are on the
+object.
+
+`withSubscriptions` also answers `wantedHere(source, events)`: which events a live subscription it
+holds would receive, synchronously, so an object that keeps an outbox and the subscriptions leaves
+the rest out inside the transaction of the write that raised them.
+
 ## Also exported
 
 `durableOutcomes`, `durableSubscriptions` and `durableLogs` turn a stub into the store `mount()`

package/dist/index.d.ts

@@ -9,9 +9,12 @@
  *
  * **One mixin per piece**, because a Worker in production keeps one object per vehicle and one for
  * the fleet, and each object should carry only what it holds: the subscriptions in the one, an
- * outbox in every other. A Worker with a single object composes all four in it.
+ * outbox in every other. A Worker with a single object composes all of them in it; one that
+ * publishes the lifecycle of its Tasks and Alerts from snapshots adds `withLifecycle` over its
+ * outbox.
  */
 export type { DurableObjectClass, EnvOf, Mixed } from "./durable.ts";
+export { type Advanced, type LifecycleMethods, type LifecycleSnapshot, lifecycleEventsBetween, withLifecycle, } from "./lifecycle.ts";
 export { durableLogs, type LogMethods, type LogRow, type LogRows, type LogsQuery, type LogsRpc, tailRecords, withLogs, } from "./logs.ts";
 export { type Flushed, type OutboxEvent, type OutboxMethods, withOutbox } from "./outbox.ts";
 export { durableOutcomes, type OutcomeMethods, type OutcomesRpc, withOutcomes, } from "./outcomes.ts";

package/dist/index.js

@@ -9,8 +9,11 @@
  *
  * **One mixin per piece**, because a Worker in production keeps one object per vehicle and one for
  * the fleet, and each object should carry only what it holds: the subscriptions in the one, an
- * outbox in every other. A Worker with a single object composes all four in it.
+ * outbox in every other. A Worker with a single object composes all of them in it; one that
+ * publishes the lifecycle of its Tasks and Alerts from snapshots adds `withLifecycle` over its
+ * outbox.
  */
+export { lifecycleEventsBetween, withLifecycle, } from "./lifecycle.js";
 export { durableLogs, tailRecords, withLogs, } from "./logs.js";
 export { withOutbox } from "./outbox.js";
 export { durableOutcomes, withOutcomes, } from "./outcomes.js";

package/dist/lifecycle.d.ts

@@ -0,0 +1,77 @@
+import { type Alert, type OpenTask } from "@worker-protocol/hono";
+import { type DurableObjectClass, type Mixed } from "./durable.ts";
+import type { OutboxEvent, OutboxMethods } from "./outbox.ts";
+/**
+ * When a Task or an Alert is born and when it ends (EVT-15), owed from a Durable Object that derives
+ * both from its own Facts.
+ *
+ * **There is one way of finding out, and the Worker supplies two things to it.** `snapshot(at)` is
+ * the Tasks and Alerts whose conditions hold at an instant, and `nextChange(after)` is the next
+ * instant at which one can begin or end without anybody acting — a minute boundary, the end of an
+ * incident, a deadline. Everything else is here, because every Worker that publishes its lifecycle
+ * from snapshots wrote it again:
+ *
+ * - **Time, which nobody witnesses,** is compared at every instant `nextChange` names between the
+ *   last one compared and now. The mark of the last instant survives the object, so a run that was
+ *   missed leaves no gap; one that fell further behind than `catchUpMs` gives the rest up and says
+ *   so, and one run compares at most `mostPerRunMs`, so a catch-up is spread over several.
+ * - **An Action** compares the instant it acts at before its write and after it, in the same
+ *   transaction (`changing`), and owes what changed in the same call — the moment only it knows.
+ * - **Every id is derived, never drawn:** the transition, the resource's id and its `since`. So an
+ *   instant compared twice, an Action and the heartbeat seeing the same change, or an alarm
+ *   delivered again all name the same event, and the ids already owed are remembered for
+ *   `keepAnnouncedMs` so that none is owed twice.
+ * - **Nothing announces an end without its beginning.** A Task an Action ended before the heartbeat
+ *   compared the instant it was born at was never announced, so its birth is owed with its end.
+ * - **The heartbeat keeps itself going** on the one alarm `withOutbox` shares, at the next instant
+ *   `nextChange` names. A cron that calls `heartbeat()` every so often is what starts the chain and
+ *   restarts it if an alarm is ever lost.
+ *
+ * It composes over `withOutbox`, whose `enqueue` it owes into and whose alarm it shares.
+ */
+/** The Tasks and Alerts whose conditions hold at one instant. */
+export type LifecycleSnapshot = {
+    tasks: OpenTask[];
+    alerts: Alert[];
+};
+/** What one comparison run did: the instants it covered, what it owed, and what it gave up. */
+export type Advanced = {
+    from: number;
+    to: number;
+    owed: number;
+    /** The instants it did not compare because it had fallen further behind than `catchUpMs`. */
+    skipped?: {
+        from: number;
+        to: number;
+    };
+};
+/** What `withLifecycle` adds to a Durable Object, and the two methods it asks of it. */
+export interface LifecycleMethods {
+    /** The Tasks and Alerts whose conditions hold at `at`, read synchronously from this object. */
+    snapshot(at: number): LifecycleSnapshot;
+    /** The first instant after `after` at which one can begin or end without anybody acting. */
+    nextChange(after: number): number;
+    changing<T>(now: number, write: () => T): T;
+    advance(now: number): Promise<Advanced>;
+    heartbeat(): Promise<Advanced & {
+        next: number;
+    }>;
+    lifecycleSkipped(range: {
+        from: number;
+        to: number;
+    }): void;
+}
+/** What was born and what ended between two snapshots; an ending is dated `at`, after its birth. */
+export declare function lifecycleEventsBetween(given: {
+    previous: LifecycleSnapshot;
+    current: LifecycleSnapshot;
+    at: number;
+}): OutboxEvent[];
+export declare function withLifecycle<B extends Mixed<DurableObjectClass, OutboxMethods>>(Base: B, options?: {
+    /** How far behind the comparison may fall before the instants in between are given up. */
+    catchUpMs?: number;
+    /** How much one run compares at most, so a catch-up is spread over several. */
+    mostPerRunMs?: number;
+    /** How long an owed id is remembered: well past any instant that could be compared again. */
+    keepAnnouncedMs?: number;
+}): Mixed<B, LifecycleMethods>;

package/dist/lifecycle.js

@@ -0,0 +1,158 @@
+import { alertEnded, alertRaised, lifecycleChanges, taskEnded, taskRaised, } from "@worker-protocol/hono";
+import { first } from "./durable.js";
+import { migrate } from "./schema.js";
+const MINUTE = 60_000;
+/** `migrate` applies these; a new step goes at the end, and a published one is never edited. */
+const SCHEMA = {
+    piece: "worker-protocol.lifecycle",
+    steps: [
+        [
+            // Every lifecycle event ever owed, by id, so none is owed twice.
+            `CREATE TABLE IF NOT EXISTS wp_lifecycle_owed (
+        id TEXT PRIMARY KEY,
+        at INTEGER NOT NULL
+      )`,
+            "CREATE INDEX IF NOT EXISTS wp_lifecycle_owed_at ON wp_lifecycle_owed (at)",
+            // The last instant compared, one row.
+            `CREATE TABLE IF NOT EXISTS wp_lifecycle_mark (
+        one INTEGER PRIMARY KEY CHECK (one = 1),
+        at INTEGER NOT NULL
+      )`,
+        ],
+    ],
+};
+const idOf = (transition, resource) => `${transition}:${resource.id}:${resource.since.getTime()}`;
+/** A birth carries the `since` the resource declares (TASK-28, ALRT-3) as its `time`. */
+const bornTask = (task) => ({
+    ...taskRaised(task),
+    id: idOf("task-raised", task),
+    time: task.since.getTime(),
+});
+const bornAlert = (alert) => ({
+    ...alertRaised(alert),
+    id: idOf("alert-raised", alert),
+    time: alert.since.getTime(),
+});
+/** What was born and what ended between two snapshots; an ending is dated `at`, after its birth. */
+export function lifecycleEventsBetween(given) {
+    const { previous, current, at } = given;
+    const tasks = lifecycleChanges({ previous: previous.tasks, current: current.tasks });
+    const alerts = lifecycleChanges({ previous: previous.alerts, current: current.alerts });
+    return [
+        ...tasks.raised.map(bornTask),
+        ...tasks.ended.flatMap((task) => [
+            bornTask(task),
+            { ...taskEnded(task), id: idOf("task-ended", task), time: at },
+        ]),
+        ...alerts.raised.map(bornAlert),
+        ...alerts.ended.flatMap((alert) => [
+            bornAlert(alert),
+            { ...alertEnded(alert), id: idOf("alert-ended", alert), time: at },
+        ]),
+    ];
+}
+/**
+ * Owes each event not owed before, in the transaction the caller is in, and answers how many were
+ * new. The outbox holds an id back only while it waits; this remembers it after.
+ *
+ * **A function of the module and not a method of the mixin, and that is the rule for every mixin
+ * here.** `private` is TypeScript's alone: at run time it is a method on the prototype like any
+ * other, and `Mixed` does not carry it, so a Worker whose class declares a method of the same name
+ * replaces it without a word from the compiler or the runtime. Only what a mixin publishes as its
+ * interface is a method; what it does internally is reached by no subclass.
+ */
+function owe(given) {
+    const { storage, enqueue, now, events } = given;
+    const sql = migrate(storage, SCHEMA);
+    // `RETURNING` answers a row only for an id this inserted, and nothing for one already there.
+    const fresh = events.filter((event) => sql
+        .exec("INSERT INTO wp_lifecycle_owed (id, at) VALUES (?, ?) ON CONFLICT DO NOTHING RETURNING id", event.id, now)
+        .toArray().length > 0);
+    enqueue(now, fresh);
+    return fresh.length;
+}
+export function withLifecycle(Base, options = {}) {
+    const catchUpMs = options.catchUpMs ?? 120 * MINUTE;
+    const mostPerRunMs = options.mostPerRunMs ?? 60 * MINUTE;
+    const keepAnnouncedMs = options.keepAnnouncedMs ?? 2 * 24 * 60 * MINUTE;
+    class WithLifecycle extends Base {
+        /**
+         * Performs `write` and owes what it changed: the Tasks and Alerts at `now` before it and after
+         * it, compared in the same transaction as the write. `write` is synchronous, because the
+         * comparison is only true of the write if nothing interleaves between the three.
+         */
+        changing(now, write) {
+            const before = this.snapshot(now);
+            const done = write();
+            owe({
+                storage: this.ctx.storage,
+                enqueue: (at, events) => this.enqueue(at, events),
+                now,
+                events: lifecycleEventsBetween({ previous: before, current: this.snapshot(now), at: now }),
+            });
+            return done;
+        }
+        /**
+         * Compares from the last instant compared up to `now`, at every instant `nextChange` names,
+         * owes what was born and what ended, and sends it. The first run only sets the mark, because
+         * what was born before anybody watched was not seen being born.
+         */
+        async advance(now) {
+            const sql = migrate(this.ctx.storage, SCHEMA);
+            const mark = first(sql.exec("SELECT at FROM wp_lifecycle_mark WHERE one = 1"))?.at;
+            let from = mark ?? now;
+            let skipped;
+            if (now - from > catchUpMs) {
+                skipped = { from, to: now - catchUpMs };
+                from = now - catchUpMs;
+                this.lifecycleSkipped(skipped);
+            }
+            const to = Math.min(now, from + mostPerRunMs);
+            const owed = [];
+            if (to > from) {
+                let previous = this.snapshot(from);
+                let at = from;
+                while (at < to) {
+                    const asked = this.nextChange(at);
+                    // An answer that does not move forward is read as nothing before `to`.
+                    const next = asked > at ? Math.min(asked, to) : to;
+                    const current = this.snapshot(next);
+                    owed.push(...lifecycleEventsBetween({ previous, current, at: next }));
+                    previous = current;
+                    at = next;
+                }
+            }
+            const fresh = owe({
+                storage: this.ctx.storage,
+                enqueue: (at, events) => this.enqueue(at, events),
+                now,
+                events: owed,
+            });
+            sql.exec("INSERT OR REPLACE INTO wp_lifecycle_mark (one, at) VALUES (1, ?)", Math.max(to, from));
+            sql.exec("DELETE FROM wp_lifecycle_owed WHERE at < ?", now - keepAnnouncedMs);
+            await this.flush();
+            return { from, to, owed: fresh, ...(skipped === undefined ? {} : { skipped }) };
+        }
+        /**
+         * Compares up to now, then asks the one alarm to come back at the next instant anything can
+         * change at. A cron calls it to start the chain and to restart it if an alarm was ever lost;
+         * after that the alarm keeps it going on its own (`wake`).
+         */
+        async heartbeat() {
+            const advanced = await this.advance(Date.now());
+            const next = this.nextChange(Date.now());
+            await this.wakeAt(next);
+            return { ...advanced, next };
+        }
+        /**
+         * Told when a run gave instants up, for a Worker that keeps records to write one. Nothing,
+         * unless overridden.
+         */
+        lifecycleSkipped(_range) { }
+        /** The alarm `heartbeat` asked for. A Worker that needs the alarm too calls `super.wake()`. */
+        async wake() {
+            await this.heartbeat();
+        }
+    }
+    return WithLifecycle;
+}

package/dist/queues.d.ts

@@ -4,12 +4,20 @@ import type { OutboxEvent } from "./outbox.ts";
 /**
  * The two Queues between an outbox and a sink, and the one handler that consumes both.
  *
- * **Events, then deliveries.** Every object's `flush()` sends its events to the events Queue. Its
- * consumer publishes each batch through the hub — the subscriptions are read once per type for the
- * whole batch, from the one object that holds them — and leaves one delivery per matching
- * subscription on the deliveries Queue, whose consumer makes the attempt. Fanning out from each
- * object instead would make a run that touches thousands of them thousands of calls to that one
- * object, and an outage of it would leave every outbox retrying; here the events wait in a Queue.
+ * **Events, then the first attempt, then deliveries.** Every object's `flush()` sends its events to
+ * the events Queue. Its consumer routes each batch through the hub — the subscriptions are read once
+ * per type for the whole batch, from the one object that holds them — and makes the first attempt
+ * at every delivery itself, reading each subscription once. Only what the hub asks to retry goes to
+ * the deliveries Queue, with the delay it asked for, and that Queue's consumer makes the later
+ * attempts. Fanning out from each object instead would make a run that touches thousands of them
+ * thousands of calls to that one object, and an outage of it would leave every outbox retrying.
+ *
+ * **The first attempt is made here because each Queue costs a batch wait.** An event that crossed
+ * both Queues before its first attempt paid the wait twice, which put it seconds behind the Fact
+ * that caused it. A sink slower than the hub's `attemptTimeoutMs` holds the batch that long and no
+ * longer, and is retried from the deliveries Queue like any other failure. If the first attempts
+ * cannot be made at all — the subscriptions object is unreachable — the deliveries are queued as
+ * they were and nothing is lost.
  *
  * **What is given up stays visible.** A delivery `deliver()` gives up on, and an event of a type the
  * Worker does not declare, go to the dead-letter queue with the reason, to be inspected and never
@@ -26,8 +34,9 @@ type Hub = ReturnType<typeof eventHub>;
 export declare const deliveryQueue: (queue: Queue<Delivery>) => DeliveryQueue;
 /**
  * What the consumer sets aside in the dead-letter queue, tagged by what it is: a delivery given up,
- * with why, or an event of a type the Worker does not declare (EVT-12) — a mistake in the Worker's
- * own code, which no retry would mend.
+ * with why, or an event the Worker's own declaration refuses — a type it does not declare (EVT-12),
+ * or an extension its type does not (EVT-18). Both are mistakes in the Worker's own code, which no
+ * retry would mend; `detail` says which.
  */
 export type GivenUp = {
     kind: "delivery";
@@ -37,6 +46,7 @@ export type GivenUp = {
     kind: "event";
     event: OutboxEvent;
     reason: "undeclared";
+    detail: string;
 };
 export type QueuesConfig<E> = {
     /** The Queue names, as `wrangler.jsonc` gives them: how the handler tells the two batches apart. */

package/dist/queues.js

@@ -6,8 +6,11 @@ const backoff = (attempts) => Math.min(10 * 2 ** Math.max(attempts - 1, 0), 3600
  * hub has several. The chunks are independent — the Queue promises no order — so they go together.
  */
 export const deliveryQueue = (queue) => ({
-    send: async (delivery) => {
-        await queue.send(delivery, { contentType: "json" });
+    send: async (delivery, options) => {
+        await queue.send(delivery, {
+            contentType: "json",
+            ...(options?.delaySeconds === undefined ? {} : { delaySeconds: options.delaySeconds }),
+        });
     },
     sendBatch: async (deliveries) => {
         const chunks = [];
@@ -41,35 +44,64 @@ export function consumeQueues(config) {
             // The record is the courtesy copy; the dead-letter queue is the one that is kept.
         }
     };
+    /** A delivery given up, set aside with why, and a record of it where the Worker keeps logs. */
+    const giveUp = (given) => {
+        const { delivery, gaveUp } = given;
+        return setAside({
+            message: given.message,
+            kept: { kind: "delivery", delivery, gaveUp },
+            deadLetter: given.deadLetter,
+            rows: given.rows,
+            row: {
+                at: Date.now(),
+                level: "warn",
+                message: "a delivery was given up",
+                fields: {
+                    subscription: delivery.subscription,
+                    event: delivery.event.id,
+                    type: delivery.event.type,
+                    reason: gaveUp.reason,
+                    ...(gaveUp.status === null ? {} : { status: gaveUp.status }),
+                },
+            },
+        });
+    };
     async function events(batch, env) {
         const hub = config.hub(env);
         const deadLetter = config.deadLetter(env);
         const rows = [];
-        // EVT-12, asked first: an event the Worker does not declare can never be published, so it is
-        // set aside at once rather than failing the batch beside it a hundred times over.
-        const declared = batch.messages.filter((message) => hub.declares(message.body.type));
-        const undeclared = batch.messages.filter((message) => !hub.declares(message.body.type));
-        await Promise.all(undeclared.map((message) => setAside({
-            message,
-            kept: { kind: "event", event: message.body, reason: "undeclared" },
-            deadLetter,
-            rows,
-            row: {
-                at: Date.now(),
-                level: "error",
-                message: "an event of a type this Worker does not declare was set aside",
-                fields: { event: message.body.id, type: message.body.type },
-            },
-        })));
+        // EVT-12, EVT-18, asked first: an event the Worker's own declaration refuses can never be
+        // published, so it is set aside at once rather than failing the batch beside it a hundred
+        // times over.
+        const declared = batch.messages.filter((message) => hub.fault(message.body) === undefined);
+        const refused = batch.messages.filter((message) => hub.fault(message.body) !== undefined);
+        await Promise.all(refused.map((message) => {
+            const detail = hub.fault(message.body);
+            return setAside({
+                message,
+                kept: { kind: "event", event: message.body, reason: "undeclared", detail },
+                deadLetter,
+                rows,
+                row: {
+                    at: Date.now(),
+                    level: "error",
+                    message: "an event this Worker's declaration refuses was set aside",
+                    fields: { event: message.body.id, type: message.body.type, detail },
+                },
+            });
+        }));
         let published;
         try {
-            published =
-                declared.length === 0 ? [] : await hub.publishAll(declared.map((message) => message.body));
+            const routed = declared.length === 0
+                ? { events: [], deliveries: [] }
+                : await hub.route(declared.map((message) => message.body));
+            await attemptFirst({ hub, deliveries: routed.deliveries, deadLetter, rows });
+            published = routed.events;
         }
         catch {
             // The store or the deliveries Queue could not be reached. The batch is retried whole, once,
             // rather than event by event against the object that is already struggling; a delivery the
-            // first attempt did queue is queued again under the same id, which a sink discards.
+            // first attempt did make is made again under the same id, which a sink discards.
             for (const message of declared)
                 message.retry({ delaySeconds: backoff(message.attempts) });
         }
@@ -89,47 +121,82 @@ export function consumeQueues(config) {
         }
         await record(rows, env);
     }
+    /**
+     * The first attempt at every delivery, made here rather than after a second Queue. What the hub
+     * asks to retry goes to the deliveries Queue with the delay it asked for and the attempt counted;
+     * what it gives up is set aside. Where the attempts cannot be made at all, every delivery is
+     * queued as it is, so the later path makes the first attempt instead.
+     */
+    async function attemptFirst(given) {
+        const { hub, deliveries, deadLetter, rows } = given;
+        if (deliveries.length === 0)
+            return;
+        let outcomes;
+        try {
+            outcomes = await hub.deliverAll(deliveries);
+        }
+        catch {
+            await Promise.all(deliveries.map((delivery) => hub.later(delivery)));
+            return;
+        }
+        await Promise.all(deliveries.map(async (delivery, at) => {
+            const outcome = outcomes[at];
+            if ("retryAfterSeconds" in outcome) {
+                await hub.later({ ...delivery, attempt: delivery.attempt + 1 }, outcome.retryAfterSeconds);
+                return;
+            }
+            if (outcome.gaveUp === undefined)
+                return;
+            // No message of its own to settle: the event it belongs to is acked by the caller.
+            const kept = { kind: "delivery", delivery, gaveUp: outcome.gaveUp };
+            await deadLetter.send(kept, { contentType: "json" });
+            rows.push({
+                at: Date.now(),
+                level: "warn",
+                message: "a delivery was given up",
+                fields: {
+                    subscription: delivery.subscription,
+                    event: delivery.event.id,
+                    type: delivery.event.type,
+                    reason: outcome.gaveUp.reason,
+                    ...(outcome.gaveUp.status === null ? {} : { status: outcome.gaveUp.status }),
+                },
+            });
+        }));
+    }
     async function deliveries(batch, env) {
         const hub = config.hub(env);
         const deadLetter = config.deadLetter(env);
         const rows = [];
-        await Promise.all(batch.messages.map(async (message) => {
-            const delivery = message.body;
-            try {
-                // `attempts` is the Queue's own count, and the one `deliver` backs off by.
-                const outcome = await hub.deliver({ ...delivery, attempt: message.attempts });
-                if ("retryAfterSeconds" in outcome) {
-                    message.retry({ delaySeconds: outcome.retryAfterSeconds });
-                    return;
-                }
-                if (outcome.gaveUp === undefined) {
-                    message.ack();
-                    return;
-                }
-                const { reason, status } = outcome.gaveUp;
-                await setAside({
-                    message,
-                    kept: { kind: "delivery", delivery, gaveUp: outcome.gaveUp },
-                    deadLetter,
-                    rows,
-                    row: {
-                        at: Date.now(),
-                        level: "warn",
-                        message: "a delivery was given up",
-                        fields: {
-                            subscription: delivery.subscription,
-                            event: delivery.event.id,
-                            type: delivery.event.type,
-                            reason,
-                            ...(status === null ? {} : { status }),
-                        },
-                    },
-                });
-            }
-            catch {
-                // The store could not be reached: nothing was settled.
+        // `attempt` is the larger of what the body carries and what the Queue counted: a delivery queued
+        // after a first attempt made elsewhere already carries 2, and the Queue starts its own count at
+        // 1. Either alone would restart the backoff.
+        const attempted = batch.messages.map((message) => ({
+            message,
+            delivery: { ...message.body, attempt: Math.max(message.body.attempt, message.attempts) },
+        }));
+        let outcomes;
+        try {
+            outcomes = await hub.deliverAll(attempted.map((one) => one.delivery));
+        }
+        catch {
+            // The store could not be reached: nothing was settled.
+            for (const { message } of attempted) {
                 message.retry({ delaySeconds: backoff(message.attempts) });
             }
+            return;
+        }
+        await Promise.all(attempted.map(async ({ message, delivery }, at) => {
+            const outcome = outcomes[at];
+            if ("retryAfterSeconds" in outcome) {
+                message.retry({ delaySeconds: outcome.retryAfterSeconds });
+            }
+            else if (outcome.gaveUp === undefined) {
+                message.ack();
+            }
+            else {
+                await giveUp({ message, delivery, gaveUp: outcome.gaveUp, deadLetter, rows });
+            }
         }));
         await record(rows, env);
     }

package/dist/subscriptions.d.ts

@@ -1,4 +1,4 @@
-import type { SubscriptionStore } from "@worker-protocol/hono";
+import { type Publishable, type SubscriptionStore } from "@worker-protocol/hono";
 import { type DurableObjectClass, type Mixed, type Rpc } from "./durable.ts";
 /** What `withSubscriptions` adds to a Durable Object. Every subscription crosses as JSON. */
 export interface SubscriptionMethods {
@@ -8,6 +8,7 @@ export interface SubscriptionMethods {
         created: boolean;
     };
     getSubscription(id: string): string | null;
+    subscriptionsById(ids: string[]): string[];
     subscriptionsOf(caller: string | null): string[];
     subscriptionsFor(type: string): string[];
     updateSubscription(id: string, change: {
@@ -15,6 +16,7 @@ export interface SubscriptionMethods {
         clear: string[];
     }): void;
     removeSubscription(id: string): void;
+    wantedHere(source: string, events: Publishable[]): boolean[];
 }
 export declare function withSubscriptions<B extends DurableObjectClass>(Base: B): Mixed<B, SubscriptionMethods>;
 /** What `durableSubscriptions` needs of a stub: the methods `withSubscriptions` adds, over RPC. */

package/dist/subscriptions.js

@@ -1,3 +1,4 @@
+import { wantedBy, } from "@worker-protocol/hono";
 import { first } from "./durable.js";
 import { migrate } from "./schema.js";
 /**
@@ -57,6 +58,16 @@ export function withSubscriptions(Base) {
             const row = first(sql.exec("SELECT record FROM wp_subscription WHERE id = ?", id));
             return row?.record ?? null;
         }
+        /** Several by id in one call, so a batch of deliveries crosses the RPC boundary once. */
+        subscriptionsById(ids) {
+            if (ids.length === 0)
+                return [];
+            const sql = migrate(this.ctx.storage, SCHEMA);
+            return sql
+                .exec("SELECT record FROM wp_subscription WHERE id IN (SELECT value FROM json_each(?))", JSON.stringify(ids))
+                .toArray()
+                .map((row) => row.record);
+        }
         /** SUB-8: one caller's, ended ones included. `IS` because a caller may be `null`. */
         subscriptionsOf(caller) {
             const sql = migrate(this.ctx.storage, SCHEMA);
@@ -93,6 +104,19 @@ export function withSubscriptions(Base) {
             const sql = migrate(this.ctx.storage, SCHEMA);
             sql.exec("DELETE FROM wp_subscription WHERE id = ?", id);
         }
+        /**
+         * Which of these events a live subscription held here would receive (SUB-13), answered
+         * synchronously — so a Worker can leave the rest out of its outbox inside the very transaction
+         * of the write that raised them, as `changing()` needs. `source` is the Worker's id, which every
+         * event carries (EVT-1); the envelope is the hub's own, so the filters read the same attributes.
+         */
+        wantedHere(source, events) {
+            return wantedBy({
+                source,
+                subscribed: (type) => this.subscriptionsFor(type).map(parse),
+                events,
+            });
+        }
     }
     return WithSubscriptions;
 }
@@ -107,6 +131,7 @@ export const durableSubscriptions = (stub) => {
             return { subscription: parse(record), created };
         },
         get: async (id) => read(await stub.getSubscription(id)),
+        getMany: async (ids) => (await stub.subscriptionsById(ids)).map(parse),
         list: async (caller) => (await stub.subscriptionsOf(caller)).map(parse),
         forType: async (type) => (await stub.subscriptionsFor(type)).map(parse),
         // `undefined` names a member to clear, and JSON drops it — so the cleared ones go by name.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@worker-protocol/cloudflare",
-  "version": "0.7.0",
-  "workerProtocolEdition": "0.5",
+  "version": "0.8.1",
+  "workerProtocolEdition": "0.6",
   "description": "The protocol's stores in Durable Objects, and the Queues between an outbox and a sink: mixins for ENDP-16, SUB-7, LOG-2 and an outbox, for Workers on Cloudflare",
   "keywords": [
     "worker-protocol",
@@ -39,7 +39,7 @@
     "NOTICE"
   ],
   "dependencies": {
-    "@worker-protocol/hono": "0.7.0"
+    "@worker-protocol/hono": "0.8.1"
   },
   "peerDependencies": {
     "hono": "^4.13.7",