@fungi.computer/carrier 0.0.1 → 0.1.0

package/README.md

@@ -97,7 +97,8 @@ In a Durable Object, `ctx.storage` is already the SQLite owner.
 `createMemoryOutbox()` stores encoded string rows in process memory for tests
 and quick starts. It provides `put`, `read`, key-ordered `list(limit, afterKey)`
 and `delete`. Each instance is independent; it is not durable storage. BirdDog’s
-[quick start](../bird-dog/README.md#quick-start) uses this helper.
+[quick start](https://docs.fungi.computer/bird-dog/quickstart/) uses this
+helper.
 
 ```ts
 import { createMemoryOutbox } from "@fungi.computer/carrier/testing";
@@ -214,6 +215,12 @@ ambiguous first dispatch has zero. Post `attempts` counts receiver invocations.
 
 ## Post
 
+Post uses Almanac's shared pure backoff calculation with its retained policy: 2
+seconds initially, doubling to a 5-minute cap, with at most 20 receiver
+attempts. The synchronous and SQL adapters share that default policy; explicit
+SQL retry policies retain their own delays. Almanac supplies arithmetic only,
+not a second scheduler or retry owner.
+
 `@fungi.computer/carrier/post` delivers typed, point-to-point envelopes between
 named Durable Objects. `definePostRoute` pairs each address schema and event
 schema with its Durable Object namespace, name function and fixed `addressKind`
@@ -264,7 +271,11 @@ its reason and its attempt count. `deadLetters` returns `letters` and
 
 The same retry and receipt machinery is exported as `makePostOutbox` for a
 string-backed outbox. [BirdDog](../bird-dog/README.md) uses it for agent reply
-delivery.
+delivery. `postOutboxPending` reports whether such an outbox still owes any
+message a delivery attempt; receipts and exhausted dead letters owe nothing. Its
+`nextWakeAt()` reads the earliest owed delivery across the retained rows,
+including future retries. Delivered receipts, exhausted dead letters and
+malformed rows do not request a wake.
 
 ## Post transactions on D1 and PostgreSQL
 

package/dist/internal/post-sql.js

@@ -1,8 +1,9 @@
 import * as Schema from "effect/Schema";
+import { backoffDelay } from "@fungi.computer/almanac";
 import { defineIdFamily } from "@fungi.computer/cairn";
 import { PostEnvelopeSchema, PostError, } from "../post.js";
 import { deliverPost, postDisposition, deliveryReceipt, } from "./post-execution.js";
-import { maxDeliveryAttempts, retryDelay } from "../post-outbox.js";
+import { maxDeliveryAttempts, postRetryPolicy } from "../post-outbox.js";
 const ids = defineIdFamily({
     family: "post",
     version: 1,
@@ -133,10 +134,13 @@ export function openSqlPost(database, options) {
         maxDelayMs: Schema.Int.check(Schema.isGreaterThan(0)),
     }))(options.retry ?? {
         maxAttempts: maxDeliveryAttempts,
-        baseDelayMs: retryDelay(1),
-        maxDelayMs: retryDelay(maxDeliveryAttempts),
+        baseDelayMs: backoffDelay(1, postRetryPolicy),
+        maxDelayMs: backoffDelay(maxDeliveryAttempts, postRetryPolicy),
+    });
+    const delay = (attempt) => backoffDelay(attempt, {
+        baseMs: policy.baseDelayMs,
+        maxMs: policy.maxDelayMs,
     });
-    const delay = (attempt) => Math.min(policy.baseDelayMs * 2 ** Math.max(0, attempt - 1), policy.maxDelayMs);
     const retrySql = Array.from({ length: policy.maxAttempts }, (_, index) => `WHEN ${String(index)} THEN ${String(delay(index + 1))}`).join(" ");
     for (const route of Object.values(options.routes)) {
         // Synchronous owner hooks cannot participate in an asynchronous transaction.

package/dist/post-outbox.d.ts

@@ -1,9 +1,10 @@
 import * as Effect from "effect/Effect";
 import * as Schema from "effect/Schema";
+import { type RetryPolicy } from "@fungi.computer/almanac";
 /** Maximum receiver attempts retained from BirdDog. */
 export declare const maxDeliveryAttempts = 20;
-/** BirdDog's retained bounded retry schedule. */
-export declare const retryDelay: (attempts: number) => number;
+/** BirdDog's retained receiver retry policy, shared by every Post adapter. */
+export declare const postRetryPolicy: RetryPolicy;
 /** Durable, string-backed rows. A delivered receipt must outlive source replay. */
 export type PostOutboxStore<E> = Readonly<{
     /** Commit one pending row or completion receipt. */
@@ -24,6 +25,8 @@ export type PostOutbox<M, E> = Readonly<{
     enqueue: (message: M, at?: number) => Effect.Effect<number | undefined, E>;
     /** Attempt one bounded page and arrange the next wake. */
     drain: () => Effect.Effect<void, E>;
+    /** Earliest owed delivery, including a future retry; absent when none remain. */
+    nextWakeAt: () => Effect.Effect<number | undefined, E>;
     /** Inspect exhausted messages in an ordered page. */
     deadLetters: (limit: number, afterKey?: string) => Effect.Effect<M[], E>;
 }>;
@@ -38,3 +41,12 @@ export declare function makePostOutbox<M, E>(options: Readonly<{
     invalidRow: () => E;
     encodingFailed: () => E;
 }>): PostOutbox<M, E>;
+/**
+ * Whether any message in an outbox still awaits a delivery attempt. Delivered
+ * receipts and exhausted dead letters are retained but owe nothing more, so a
+ * host may let their owner rest.
+ */
+export declare function postOutboxPending<M, E>(options: Readonly<{
+    message: Schema.Codec<M>;
+    outbox: Pick<PostOutboxStore<E>, "list">;
+}>): Effect.Effect<boolean, E>;

package/dist/post-outbox.js

@@ -1,28 +1,34 @@
 import * as Effect from "effect/Effect";
 import * as Schema from "effect/Schema";
+import { backoffDelay } from "@fungi.computer/almanac";
 const PageSize = 64;
 /** Maximum receiver attempts retained from BirdDog. */
 export const maxDeliveryAttempts = 20;
-/** BirdDog's retained bounded retry schedule. */
-export const retryDelay = (attempts) => Math.min(2_000 * 2 ** Math.max(0, attempts - 1), 300_000);
+/** BirdDog's retained receiver retry policy, shared by every Post adapter. */
+export const postRetryPolicy = {
+    baseMs: 2_000,
+    maxMs: 300_000,
+};
 const earlier = (a, b) => b === undefined ? a : a === undefined ? b : Math.min(a, b);
 const logDeliveryFailure = (cause) => {
     console.error("Carrier Post outbox delivery failed", {
         failureKind: cause instanceof Error ? "Error" : "NonErrorThrown",
     });
 };
+/** One durable row: a message still owed delivery, or its delivered receipt. */
+function postRowText(message) {
+    return Schema.fromJsonString(Schema.Union([
+        Schema.Struct({
+            mail: message,
+            attempts: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),
+            nextAttemptAt: Schema.optional(Schema.Number.check(Schema.isGreaterThanOrEqualTo(0))),
+        }),
+        Schema.Struct({ state: Schema.Literal("delivered") }),
+    ]));
+}
 /** The same bounded delivery and receipt machinery serves Post and BirdDog. */
 export function makePostOutbox(options) {
-    const Pending = Schema.Struct({
-        mail: options.message,
-        attempts: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),
-        nextAttemptAt: Schema.optional(Schema.Number.check(Schema.isGreaterThanOrEqualTo(0))),
-    });
-    const Row = Schema.Union([
-        Pending,
-        Schema.Struct({ state: Schema.Literal("delivered") }),
-    ]);
-    const Text = Schema.fromJsonString(Row);
+    const Text = postRowText(options.message);
     const decode = (value) => Schema.decodeUnknownEffect(Text)(value).pipe(Effect.mapError(options.invalidRow));
     const encode = (row) => Effect.try({
         try: () => Schema.encodeSync(Text)(row),
@@ -60,7 +66,7 @@ export function makePostOutbox(options) {
             return undefined;
         }
         const attempts = row.attempts + 1;
-        const nextAttemptAt = now + retryDelay(attempts);
+        const nextAttemptAt = now + backoffDelay(attempts, postRetryPolicy);
         yield* options.outbox.put(stored.key, yield* encode({ mail: row.mail, attempts, nextAttemptAt }));
         return attempts < maxDeliveryAttempts ? nextAttemptAt : undefined;
     });
@@ -95,5 +101,52 @@ export function makePostOutbox(options) {
         }
         return dead;
     });
-    return { enqueue, drain, deadLetters };
+    const nextWakeAt = () => Effect.gen(function* () {
+        let afterKey;
+        let due;
+        for (;;) {
+            const rows = yield* options.outbox.list(PageSize, afterKey);
+            for (const stored of rows) {
+                // Malformed rows are discarded by drain, not deliverable work.
+                const decoded = yield* Effect.result(decode(stored.value));
+                if (decoded._tag === "Failure")
+                    continue;
+                const row = decoded.success;
+                if (!("state" in row) && row.attempts < maxDeliveryAttempts)
+                    due = earlier(due, row.nextAttemptAt ?? options.now());
+            }
+            const lastKey = rows.at(-1)?.key;
+            if (rows.length < PageSize || lastKey === undefined)
+                return due;
+            afterKey = lastKey;
+        }
+    });
+    return { enqueue, drain, deadLetters, nextWakeAt };
+}
+/**
+ * Whether any message in an outbox still awaits a delivery attempt. Delivered
+ * receipts and exhausted dead letters are retained but owe nothing more, so a
+ * host may let their owner rest.
+ */
+export function postOutboxPending(options) {
+    const Text = postRowText(options.message);
+    return Effect.gen(function* () {
+        let afterKey;
+        for (;;) {
+            const rows = yield* options.outbox.list(PageSize, afterKey);
+            for (const stored of rows) {
+                // A malformed row is not deliverable; the next drain discards it.
+                const decoded = yield* Effect.result(Schema.decodeUnknownEffect(Text)(stored.value));
+                if (decoded._tag === "Failure")
+                    continue;
+                const row = decoded.success;
+                if (!("state" in row) && row.attempts < maxDeliveryAttempts)
+                    return true;
+            }
+            const lastKey = rows.at(-1)?.key;
+            if (rows.length < PageSize || lastKey === undefined)
+                return false;
+            afterKey = lastKey;
+        }
+    });
 }

package/dist/post.d.ts

@@ -3,7 +3,7 @@ import { type PostDeliveryResult } from "./internal/post-contract.js";
 export { PostError, PostDeliveryResultSchema, } from "./internal/post-contract.js";
 export type { PostDeliveryResult } from "./internal/post-contract.js";
 import type { WatchdogRunningJob, WatchdogSqliteOwner, WatchdogRuntime, WatchdogTransactionalProjection } from "@fungi.computer/watchdog";
-export { makePostOutbox, retryDelay } from "./post-outbox.js";
+export { makePostOutbox, postOutboxPending } from "./post-outbox.js";
 export type { PostOutbox, PostOutboxStore } from "./post-outbox.js";
 /** Wire envelope parsed at the durable row and receiver boundaries. */
 export declare const PostEnvelopeSchema: Schema.Struct<{

package/dist/post.js

@@ -3,8 +3,9 @@ import { PostError, } from "./internal/post-contract.js";
 export { PostError, PostDeliveryResultSchema, } from "./internal/post-contract.js";
 import { deliverPost, postDisposition, deliveryReceipt, } from "./internal/post-execution.js";
 import { defineIdFamily } from "@fungi.computer/cairn";
-import { maxDeliveryAttempts, retryDelay } from "./post-outbox.js";
-export { makePostOutbox, retryDelay } from "./post-outbox.js";
+import { backoffDelay } from "@fungi.computer/almanac";
+import { maxDeliveryAttempts, postRetryPolicy } from "./post-outbox.js";
+export { makePostOutbox, postOutboxPending } from "./post-outbox.js";
 const Key = Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(256));
 const JobPayload = Schema.Struct({ postKey: Key });
 const PageLimit = Schema.Int.check(Schema.isGreaterThanOrEqualTo(1), Schema.isLessThanOrEqualTo(64));
@@ -252,7 +253,7 @@ export function createPost(options) {
                 return undefined;
             }
             const attempts = row.attempts + 1;
-            const nextAttemptAt = options.now() + retryDelay(attempts);
+            const nextAttemptAt = options.now() + backoffDelay(attempts, postRetryPolicy);
             const started = { ...row, attempts, nextAttemptAt };
             // Preserve recovery evidence before invoking the receiver. A failed receipt
             // write leaves this row available for retry after Watchdog settles the job.
@@ -298,7 +299,7 @@ export function createPost(options) {
                 finish(postKey, current, disposition, deliveryReceipt(evidence));
             }
             else {
-                const due = options.now() + retryDelay(current.attempts);
+                const due = options.now() + backoffDelay(current.attempts, postRetryPolicy);
                 if (due !== current.nextAttemptAt) {
                     putRow(postKey, { ...current, nextAttemptAt: due });
                     retryAt = due;

package/docs/api/post.md

@@ -118,6 +118,7 @@ Durable, string-backed rows. A delivered receipt must outlive source replay.
 type PostOutbox<M, E> = Readonly<{
   enqueue: (message, at?) => Effect.Effect<number | undefined, E>;
   drain: () => Effect.Effect<void, E>;
+  nextWakeAt: () => Effect.Effect<number | undefined, E>;
   deadLetters: (limit, afterKey?) => Effect.Effect<M[], E>;
 }>;
 ```
@@ -368,33 +369,42 @@ Persisted Post row parser.
 
 ## Functions
 
-### retryDelay()
+### makePostOutbox()
 
 ```ts
-function retryDelay(attempts): number;
+function makePostOutbox<M, E>(options): PostOutbox<M, E>;
 ```
 
-BirdDog's retained bounded retry schedule.
+The same bounded delivery and receipt machinery serves Post and BirdDog.
+
+#### Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `M`            |
+| `E`            |
 
 #### Parameters
 
-| Parameter  | Type     |
-| ---------- | -------- |
-| `attempts` | `number` |
+| Parameter | Type                                                                                                                                                                                                                                                                                                                                              |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `options` | `Readonly`\<\{ `message`: `Schema.Codec`\<`M`\>; `key`: (`message`) => `string`; `outbox`: [`PostOutboxStore`](#postoutboxstore)\<`E`\>; `deliver`: (`message`) => `Effect.Effect`\<`boolean`, `E`\>; `scheduleWake`: (`at`) => `Effect.Effect`\<`void`, `E`\>; `now`: () => `number`; `invalidRow`: () => `E`; `encodingFailed`: () => `E`; \}\> |
 
 #### Returns
 
-`number`
+[`PostOutbox`](#postoutbox)\<`M`, `E`\>
 
 ---
 
-### makePostOutbox()
+### postOutboxPending()
 
 ```ts
-function makePostOutbox<M, E>(options): PostOutbox<M, E>;
+function postOutboxPending<M, E>(options): Effect<boolean, E>;
 ```
 
-The same bounded delivery and receipt machinery serves Post and BirdDog.
+Whether any message in an outbox still awaits a delivery attempt. Delivered
+receipts and exhausted dead letters are retained but owe nothing more, so a host
+may let their owner rest.
 
 #### Type Parameters
 
@@ -405,13 +415,13 @@ The same bounded delivery and receipt machinery serves Post and BirdDog.
 
 #### Parameters
 
-| Parameter | Type                                                                                                                                                                                                                                                                                                                                              |
-| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `options` | `Readonly`\<\{ `message`: `Schema.Codec`\<`M`\>; `key`: (`message`) => `string`; `outbox`: [`PostOutboxStore`](#postoutboxstore)\<`E`\>; `deliver`: (`message`) => `Effect.Effect`\<`boolean`, `E`\>; `scheduleWake`: (`at`) => `Effect.Effect`\<`void`, `E`\>; `now`: () => `number`; `invalidRow`: () => `E`; `encodingFailed`: () => `E`; \}\> |
+| Parameter | Type                                                                                                                              |
+| --------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `options` | `Readonly`\<\{ `message`: `Schema.Codec`\<`M`\>; `outbox`: `Pick`\<[`PostOutboxStore`](#postoutboxstore)\<`E`\>, `"list"`\>; \}\> |
 
 #### Returns
 
-[`PostOutbox`](#postoutbox)\<`M`, `E`\>
+`Effect`\<`boolean`, `E`\>
 
 ---
 
@@ -537,37 +547,6 @@ Preserve each route's inferred address and event types in a registry.
 
 ---
 
-### migratePostEvents()
-
-```ts
-function migratePostEvents<A, AI, B, BI>(options): void;
-```
-
-Migrate persisted ordinary events once, before opening their producer. Carrier
-preserves delivery evidence, ordering and Watchdog job identities. A failed
-decoder or transform rolls back both rows and the migration receipt.
-
-#### Type Parameters
-
-| Type Parameter |
-| -------------- |
-| `A`            |
-| `AI`           |
-| `B`            |
-| `BI`           |
-
-#### Parameters
-
-| Parameter | Type                                                                                                                                                                                                            |
-| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `options` | `Readonly`\<\{ `owner`: `WatchdogSqliteOwner`; `id`: `string`; `kind`: `string`; `toKind?`: `string`; `from`: `Schema.Codec`\<`A`, `AI`\>; `to`: `Schema.Codec`\<`B`, `BI`\>; `migrate`: (`event`) => `B`; \}\> |
-
-#### Returns
-
-`void`
-
----
-
 ### createPost()
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fungi.computer/carrier",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "author": "Levi <levi@technomancy.dev>",
   "description": "Durable email submission and recipient delivery tracking",
   "type": "module",
@@ -48,8 +48,9 @@
   ],
   "dependencies": {
     "@cloudflare/workers-types": "5.20260828.1",
-    "@fungi.computer/cairn": "0.0.1",
-    "@fungi.computer/watchdog": "0.0.1",
+    "@fungi.computer/almanac": "0.2.0",
+    "@fungi.computer/cairn": "0.1.0",
+    "@fungi.computer/watchdog": "0.1.0",
     "effect": "4.0.2",
     "pg": "8.23.0",
     "@types/pg": "8.23.1"