@fungi.computer/carrier 0.0.1 → 0.2.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,14 +215,26 @@ ambiguous first dispatch has zero. Post `attempts` counts receiver invocations.
 
 ## Post
 
+Post's ordinary retry policy uses Almanac's shared pure backoff calculation: 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. A SQLite route with `deadlineMs`
+uses its finite lifetime instead of the attempt ceiling. 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`
-label. Every event route to the same namespace shares that label, so different
-event kinds for one recipient keep producer order. The receiver implements
-`deliver(envelope)` and calls `admitPost` inside its own SQLite transaction, so
-the event mutation and admission receipt commit together. Keys must identify the
-producing event across all senders to that receiver.
+label. A SQLite-backed route may opt into a retry lifetime of at most seven days
+with `deadlineMs`; Post stores its absolute deadline at admission and settles an
+undelivered row as an `expired` dead letter when the deadline is reached.
+Deadline routes retry until expiry rather than using the ordinary attempt
+ceiling. Omitted deadlines preserve the existing retry budget. Every event route
+to the same namespace shares that label, so different event kinds for one
+recipient keep producer order. The receiver implements `deliver(envelope)` and
+calls `admitPost` inside its own SQLite transaction, so the event mutation and
+admission receipt commit together. Keys must identify the producing event across
+all senders to that receiver.
 
 Construct `createPost` with the producer's structural SQLite `owner`, typed
 `routes`, Watchdog's `transactional` projection and `readJob` operation, a
@@ -258,20 +271,29 @@ acknowledge a domain ledger in the same producer transaction as the Post
 receipt. An acknowledgment failure leaves both pending for retry. Prepared facts
 should carry sealed grants, never raw credentials.
 
-A definite refusal or an exhausted retry budget keeps a dead-letter envelope,
-its reason and its attempt count. `deadLetters` returns `letters` and
-`nextCursor`, including a continuation through pages that contain only receipts.
+A definite refusal, an exhausted retry budget or a route deadline keeps a
+dead-letter envelope, its reason and its attempt count. `deadLetters` returns
+`letters` and `nextCursor`, including a continuation through pages that contain
+only receipts.
 
 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
 
 `@fungi.computer/carrier/post-d1` and `/post-postgres` bind the ordinary Post
-address and event registry to Watchdog's database adapters. Apply `postD1Schema`
-or `postPostgresSchema` alongside the matching Watchdog schema through your
-migration tool.
+address and event registry to Watchdog's database adapters. These relational
+adapters preserve their existing schema and retry contract and do not support
+route deadlines. Constructing either adapter with a route that sets `deadlineMs`
+throws `PostError` with `reason: "relational-deadline-unsupported"` before
+database access. Use SQLite-backed Post for deadline routes. Apply
+`postD1Schema` or `postPostgresSchema` alongside the matching Watchdog schema
+through your migration tool.
 
 On D1, `post.send(envelope)` returns the envelope and job statements. Include
 both in the same `database.batch` as the producer fact. `sendFromSelect` accepts

package/dist/inspection.d.ts

@@ -30,7 +30,7 @@ export declare const PostReceiptSummarySchema: Schema.Union<readonly [Schema.Str
     readonly state: Schema.Literal<"dead">;
     readonly kind: Schema.String;
     readonly attempts: Schema.Int;
-    readonly reason: Schema.Literals<readonly ["refused", "exhausted"]>;
+    readonly reason: Schema.Literals<readonly ["refused", "exhausted", "expired"]>;
 }>]>;
 /** Metadata for one retained Post row. */
 export type PostReceiptSummary = Schema.Schema.Type<typeof PostReceiptSummarySchema>;
@@ -53,7 +53,7 @@ export declare const PostInspectionPageSchema: Schema.Union<readonly [Schema.Str
         readonly state: Schema.Literal<"dead">;
         readonly kind: Schema.String;
         readonly attempts: Schema.Int;
-        readonly reason: Schema.Literals<readonly ["refused", "exhausted"]>;
+        readonly reason: Schema.Literals<readonly ["refused", "exhausted", "expired"]>;
     }>]>>;
     readonly nextCursor: Schema.NullOr<Schema.String>;
 }>]>;

package/dist/inspection.js

@@ -29,7 +29,7 @@ export const PostReceiptSummarySchema = Schema.Union([
         state: Schema.Literal("dead"),
         kind: Key,
         attempts: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),
-        reason: Schema.Literals(["refused", "exhausted"]),
+        reason: Schema.Literals(["refused", "exhausted", "expired"]),
     }),
 ]);
 /** Bounded evidence with an explicit distinction between empty and uninitialized storage. */

package/dist/internal/post-contract.d.ts

@@ -18,10 +18,11 @@ export declare const PostDeliveryResultSchema: Schema.Union<readonly [Schema.Lit
 declare const PostError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
     readonly _tag: "PostError";
 } & Readonly<A>;
-/** Post rejected an unknown route or conflicting key. */
+/** Post rejected an unknown route, conflicting key, or unsupported policy. */
 export declare class PostError extends PostError_base<{
     readonly message: string;
+    readonly reason?: "relational-deadline-unsupported";
 }> {
-    constructor(message: string);
+    constructor(message: string, reason?: "relational-deadline-unsupported");
 }
 export {};

package/dist/internal/post-contract.js

@@ -14,9 +14,9 @@ export const PostDeliveryResultSchema = Schema.Union([
         receipt: Schema.Json,
     }),
 ]);
-/** Post rejected an unknown route or conflicting key. */
+/** Post rejected an unknown route, conflicting key, or unsupported policy. */
 export class PostError extends Data.TaggedError("PostError") {
-    constructor(message) {
-        super({ message });
+    constructor(message, reason) {
+        super(reason === undefined ? { message } : { message, reason });
     }
 }

package/dist/internal/post-execution.d.ts

@@ -6,6 +6,18 @@ export type DeliveryEvidence = Readonly<{
     envelope: PostEnvelope | undefined;
     failure?: unknown;
 }>;
+/** The settlement a delivery attempt resolves to; internal to the Post backends. */
+export type PostDisposition = Readonly<{
+    state: "dead";
+    reason: "refused" | "exhausted" | "expired";
+}> | Readonly<{
+    state: "pending";
+}> | Readonly<{
+    state: "delivered";
+    cursor?: number;
+}> | Readonly<{
+    state: "keep";
+}>;
 /** Shared preparation, bounded receiver I/O and response decoding for every Post backend. */
 export declare function deliverPost(input: Readonly<{
     attempt: Extract<PostRow, {
@@ -16,30 +28,9 @@ export declare function deliverPost(input: Readonly<{
     savePrepared: (envelope: PostEnvelope) => void | Promise<void>;
 }>): Promise<DeliveryEvidence>;
 /** One settlement decision, shared by native storage adapters. */
-export declare function postDisposition(evidence: DeliveryEvidence, route: PostRegistryRoute, attempts: number, maxAttempts: number): {
-    readonly state: "dead";
-    readonly reason: "exhausted";
-    readonly cursor?: never;
-} | {
-    readonly state: "pending";
-    readonly reason?: never;
-    readonly cursor?: never;
-} | {
-    readonly state: "dead";
-    readonly reason: "refused";
-    readonly cursor?: never;
-} | {
-    readonly state: "keep";
-    readonly reason?: never;
-    readonly cursor?: never;
-} | {
-    readonly state: "delivered";
-    readonly reason?: never;
-    readonly cursor?: never;
-} | {
-    readonly state: "delivered";
-    readonly cursor: number;
-    readonly reason?: never;
-};
+export declare function postDisposition(evidence: DeliveryEvidence, route: PostRegistryRoute, attempts: number, maxAttempts: number, options?: Readonly<{
+    deadlineExpired?: boolean;
+    retryUntilDeadline?: boolean;
+}>): PostDisposition;
 /** Durable provider/domain receipt data, separate from the staged event. */
 export declare function deliveryReceipt(evidence: DeliveryEvidence): Schema.Json | undefined;

package/dist/internal/post-execution.js

@@ -38,10 +38,12 @@ export async function deliverPost(input) {
     return { result: decoded.success, envelope };
 }
 /** One settlement decision, shared by native storage adapters. */
-export function postDisposition(evidence, route, attempts, maxAttempts) {
+export function postDisposition(evidence, route, attempts, maxAttempts, options = {}) {
     const { result, envelope } = evidence;
+    if (result === "unavailable" && options.deadlineExpired === true)
+        return { state: "dead", reason: "expired" };
     if (result === "unavailable")
-        return attempts >= maxAttempts
+        return !options.retryUntilDeadline && attempts >= maxAttempts
             ? { state: "dead", reason: "exhausted" }
             : { state: "pending" };
     if (envelope === undefined)

package/dist/internal/post-sql.d.ts

@@ -12,7 +12,7 @@ export type PostSql = Readonly<{
 }>;
 /** SQL native Carrier runtime configuration; route decisions remain in Post. */
 export type SqlPostOptions<R extends Record<string, PostRegistryRoute>> = Readonly<{
-    /** The same address/event registry used by SQLite Post. */
+    /** The same registry used by SQLite Post; routes with deadlines are rejected. */
     routes: R;
     /** Optional bounded, redacted family diagnostic; never persist raw provider errors. */
     failureDetail?: (cause: unknown) => string;

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,
@@ -127,16 +128,21 @@ function publicRow(stored) {
     };
 }
 export function openSqlPost(database, options) {
+    if (Object.values(options.routes).some((route) => route.deadlineMs !== undefined))
+        throw new PostError("relational Post adapters do not support route deadlines", "relational-deadline-unsupported");
     const policy = Schema.decodeUnknownSync(Schema.Struct({
         maxAttempts: Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: maxDeliveryAttempts })),
         baseDelayMs: Schema.Int.check(Schema.isGreaterThan(0)),
         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-d1.d.ts

@@ -19,7 +19,7 @@ export type D1Post = SqlPostRuntime & Readonly<{
 }>;
 /** Carrier-owned D1 schema, applied by the deployment migration owner. */
 export declare const postD1Schema: readonly string[];
-/** Bind the Post registry to native D1 batch admission and the shared delivery engine. */
+/** Bind the Post registry to D1; route deadlines are rejected with PostError. */
 export declare function createD1Post<R extends Record<string, PostRegistryRoute>>(options: SqlPostOptions<R> & Readonly<{
     database: D1Database;
     watchdog: D1Watchdog;

package/dist/post-d1.js

@@ -2,7 +2,7 @@ import { purgeD1Queues, prepareD1Admission, } from "@fungi.computer/watchdog/d1"
 import { admitPostSelect, jobSelect, openSqlPost, postSchema, preparePost, } from "./internal/post-sql.js";
 /** Carrier-owned D1 schema, applied by the deployment migration owner. */
 export const postD1Schema = postSchema(false);
-/** Bind the Post registry to native D1 batch admission and the shared delivery engine. */
+/** Bind the Post registry to D1; route deadlines are rejected with PostError. */
 export function createD1Post(options) {
     // Only package-owned templates use $N; caller SELECTs remain native SQL.
     const prepare = (statement) => options.database

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-postgres.d.ts

@@ -10,7 +10,7 @@ export type PostgresPost = SqlPostRuntime & Readonly<{
 }>;
 /** Carrier-owned PostgreSQL schema, applied by the deployment migration owner. */
 export declare const postPostgresSchema: readonly string[];
-/** Bind the Post registry to a PostgreSQL owner and the shared delivery engine. */
+/** Bind the Post registry to PostgreSQL; route deadlines are rejected with PostError. */
 export declare function createPostgresPost<R extends Record<string, PostRegistryRoute>>(options: SqlPostOptions<R> & Readonly<{
     database: Pick<Pool, "query" | "connect">;
     watchdog: PostgresWatchdog;

package/dist/post-postgres.js

@@ -10,7 +10,7 @@ const Job = Schema.Struct({
     priority: Schema.Number,
     payload_json: Schema.fromJsonString(Schema.Unknown),
 });
-/** Bind the Post registry to a PostgreSQL owner and the shared delivery engine. */
+/** Bind the Post registry to PostgreSQL; route deadlines are rejected with PostError. */
 export function createPostgresPost(options) {
     const enqueue = async (client, source) => {
         const native = source;

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<{
@@ -23,6 +23,7 @@ export declare const PostRowSchema: Schema.fromJsonString<Schema.Union<readonly
     }>;
     readonly attempts: Schema.Int;
     readonly nextAttemptAt: Schema.Number;
+    readonly deadlineAt: Schema.optional<Schema.Number>;
     readonly jobId: Schema.optional<Schema.String>;
     readonly delivery: Schema.optional<Schema.Struct<{
         readonly key: Schema.String;
@@ -44,7 +45,8 @@ export declare const PostRowSchema: Schema.fromJsonString<Schema.Union<readonly
         readonly event: Schema.Unknown;
     }>;
     readonly attempts: Schema.Int;
-    readonly reason: Schema.Literals<readonly ["refused", "exhausted"]>;
+    readonly reason: Schema.Literals<readonly ["refused", "exhausted", "expired"]>;
+    readonly deadlineAt: Schema.optional<Schema.Number>;
     readonly receipt: Schema.optional<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
     readonly delivery: Schema.optional<Schema.Struct<{
         readonly key: Schema.String;
@@ -62,6 +64,8 @@ export type PostRow = Schema.Schema.Type<typeof PostRowSchema>;
 export type PostRoute<A, E, D = E, AI = A, EI = E, DI = EI> = Readonly<{
     /** Fixed registry label shared by routes to one recipient namespace. */
     addressKind: string;
+    /** Optional SQLite Post lifetime of 1 ms to 7 days from admission; relational adapters reject it. */
+    deadlineMs?: number | undefined;
     /** Address parser for this kind. */
     address: Schema.Codec<A, AI>;
     /** Staged event parser for this kind. */
@@ -104,6 +108,8 @@ export type PostRoute<A, E, D = E, AI = A, EI = E, DI = EI> = Readonly<{
 export type PostRegistryRoute = Readonly<{
     /** Recipient namespace identity used for per-address ordering. */
     addressKind: string;
+    /** Optional SQLite Post lifetime of 1 ms to 7 days from admission; relational adapters reject it. */
+    deadlineMs?: number | undefined;
     /** Parser for this address kind. */
     address: Schema.Codec<unknown, unknown>;
     /** Parser for this event kind. */
@@ -147,11 +153,13 @@ export type PostRuntime<R extends Record<string, PostRegistryRoute>> = Readonly<
     }>>;
     /** Recover settled delivery jobs and enqueue due retries after a wake. */
     enqueueDue: (limit?: number, afterKey?: string) => Promise<string | undefined>;
-    /** Read an ordered page of refused or exhausted keys for operators. */
+    /** Release settled pending retries from backoff without resetting attempts. */
+    releaseNow: (limit?: number, afterKey?: string) => Promise<string | undefined>;
+    /** Read an ordered page of refused, exhausted or expired keys for operators. */
     deadLetters: (limit?: number, afterKey?: string) => Readonly<{
         letters: readonly Readonly<{
             key: string;
-            reason: "refused" | "exhausted";
+            reason: "refused" | "exhausted" | "expired";
             envelope: PostEnvelope;
             attempts: number;
         }>[];

package/dist/post.js

@@ -3,11 +3,13 @@ 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));
+const maxRouteDeadlineMs = 7 * 24 * 60 * 60 * 1_000;
 const ids = defineIdFamily({
     family: "post",
     version: 1,
@@ -27,6 +29,7 @@ export const PostRowSchema = Schema.fromJsonString(Schema.Union([
         envelope: PostEnvelopeSchema,
         attempts: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),
         nextAttemptAt: Schema.Number.check(Schema.isGreaterThanOrEqualTo(0)),
+        deadlineAt: Schema.optional(Schema.Number.check(Schema.isGreaterThanOrEqualTo(0))),
         jobId: Schema.optional(Key),
         delivery: Schema.optional(PostEnvelopeSchema),
         nextKey: Schema.optional(Key),
@@ -40,7 +43,8 @@ export const PostRowSchema = Schema.fromJsonString(Schema.Union([
         state: Schema.Literal("dead"),
         envelope: PostEnvelopeSchema,
         attempts: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),
-        reason: Schema.Literals(["refused", "exhausted"]),
+        reason: Schema.Literals(["refused", "exhausted", "expired"]),
+        deadlineAt: Schema.optional(Schema.Number.check(Schema.isGreaterThanOrEqualTo(0))),
         receipt: Schema.optional(Schema.Json),
         delivery: Schema.optional(PostEnvelopeSchema),
         nextKey: Schema.optional(Key),
@@ -78,6 +82,8 @@ export function definePostRoute(route) {
         ? receiptOperations(route.address, route.event, route)
         : receiptOperations(route.address, route.prepare.event, route);
     const prepare = route.prepare;
+    if (route.deadlineMs !== undefined)
+        Schema.decodeUnknownSync(Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: maxRouteDeadlineMs })))(route.deadlineMs);
     return {
         ...route,
         ...delivery,
@@ -178,12 +184,16 @@ export function createPost(options) {
         const queue = queueOf(envelope);
         const previousKey = store.read(tailKey(queue));
         const previous = previousKey === undefined ? undefined : readRow(previousKey);
-        const row = {
+        const admittedAt = options.now();
+        const baseRow = {
             state: "pending",
             envelope,
             attempts: 0,
-            nextAttemptAt: options.now(),
+            nextAttemptAt: admittedAt,
         };
+        const row = route.deadlineMs === undefined
+            ? baseRow
+            : { ...baseRow, deadlineAt: admittedAt + route.deadlineMs };
         putRow(envelope.key, row);
         if (previousKey !== undefined && previous?.state === "pending") {
             putRow(previousKey, { ...previous, nextKey: envelope.key });
@@ -227,8 +237,13 @@ export function createPost(options) {
                 envelope: row.envelope,
                 attempts: row.attempts,
             };
+            const settled = row.deadlineAt === undefined
+                ? dead
+                : { ...dead, deadlineAt: row.deadlineAt };
             receipt =
-                row.delivery === undefined ? dead : { ...dead, delivery: row.delivery };
+                row.delivery === undefined
+                    ? settled
+                    : { ...settled, delivery: row.delivery };
         }
         else
             receipt = terminal;
@@ -247,12 +262,16 @@ export function createPost(options) {
                 throw new PostError("delivery row is missing");
             if (row.state !== "pending" || row.jobId !== job.jobId)
                 return undefined;
-            if (row.attempts >= maxDeliveryAttempts) {
+            if (row.deadlineAt !== undefined && options.now() >= row.deadlineAt) {
+                finish(postKey, row, { state: "dead", reason: "expired" });
+                return undefined;
+            }
+            if (row.deadlineAt === undefined && row.attempts >= maxDeliveryAttempts) {
                 finish(postKey, row, { state: "dead", reason: "exhausted" });
                 return undefined;
             }
             const attempts = row.attempts + 1;
-            const nextAttemptAt = options.now() + retryDelay(attempts);
+            const nextAttemptAt = Math.min(options.now() + backoffDelay(attempts, postRetryPolicy), row.deadlineAt ?? Number.POSITIVE_INFINITY);
             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.
@@ -281,7 +300,11 @@ export function createPost(options) {
             const current = readRow(postKey);
             if (current?.state !== "pending" || current.jobId !== job.jobId)
                 return;
-            const disposition = postDisposition(evidence, route, current.attempts, maxDeliveryAttempts);
+            const disposition = postDisposition(evidence, route, current.attempts, maxDeliveryAttempts, {
+                deadlineExpired: current.deadlineAt !== undefined &&
+                    options.now() >= current.deadlineAt,
+                retryUntilDeadline: current.deadlineAt !== undefined,
+            });
             if (disposition.state === "keep")
                 return;
             if (disposition.state === "delivered") {
@@ -298,10 +321,16 @@ export function createPost(options) {
                 finish(postKey, current, disposition, deliveryReceipt(evidence));
             }
             else {
-                const due = options.now() + retryDelay(current.attempts);
-                if (due !== current.nextAttemptAt) {
-                    putRow(postKey, { ...current, nextAttemptAt: due });
-                    retryAt = due;
+                const now = options.now();
+                if (current.deadlineAt !== undefined && now >= current.deadlineAt) {
+                    finish(postKey, current, { state: "dead", reason: "expired" });
+                }
+                else {
+                    const due = Math.min(now + backoffDelay(current.attempts, postRetryPolicy), current.deadlineAt ?? Number.POSITIVE_INFINITY);
+                    if (due !== current.nextAttemptAt) {
+                        putRow(postKey, { ...current, nextAttemptAt: due });
+                        retryAt = due;
+                    }
                 }
             }
         });
@@ -329,7 +358,14 @@ export function createPost(options) {
                 const current = readRow(row.envelope.key);
                 if (current?.state !== "pending" || current.jobId !== row.jobId)
                     return;
-                if (current.attempts >= maxDeliveryAttempts)
+                if (current.deadlineAt !== undefined &&
+                    options.now() >= current.deadlineAt)
+                    finish(current.envelope.key, current, {
+                        state: "dead",
+                        reason: "expired",
+                    });
+                else if (current.deadlineAt === undefined &&
+                    current.attempts >= maxDeliveryAttempts)
                     finish(current.envelope.key, current, {
                         state: "dead",
                         reason: "exhausted",
@@ -369,13 +405,16 @@ export function createPost(options) {
                     enqueueJob(pending);
             }
             else {
-                const pending = {
+                const retry = {
                     state: "pending",
                     envelope: current.envelope,
                     attempts: 0,
                     nextAttemptAt: options.now(),
                     delivery: current.delivery,
                 };
+                const pending = current.deadlineAt === undefined
+                    ? retry
+                    : { ...retry, deadlineAt: current.deadlineAt };
                 putRow(key, pending);
                 const queue = queueOf(pending.envelope);
                 const previousKey = store.read(tailKey(queue));
@@ -391,6 +430,41 @@ export function createPost(options) {
         });
         await options.scheduleWake(options.now());
     };
+    const releasePendingRow = async (row, now) => {
+        if (row.state !== "pending" ||
+            row.jobId === undefined ||
+            row.nextAttemptAt <= now)
+            return false;
+        const work = await options.readJob(row.jobId);
+        if (work.status === "missing")
+            throw new PostError("delivery job is missing");
+        if (work.job.state !== "settled")
+            return false;
+        return store.commit(() => {
+            const current = readRow(row.envelope.key);
+            if (current?.state !== "pending" ||
+                current.jobId !== row.jobId ||
+                current.nextAttemptAt <= now)
+                return false;
+            const pending = { ...current, nextAttemptAt: now };
+            putRow(row.envelope.key, pending);
+            enqueueJob(pending);
+            return true;
+        });
+    };
+    const releaseNow = async (limit = 64, afterKey) => {
+        const pageSize = Schema.decodeUnknownSync(PageLimit)(limit);
+        const rows = store.list(pageSize, afterKey);
+        const now = options.now();
+        let released = false;
+        for (const stored of rows) {
+            const row = Schema.decodeUnknownSync(PostRowSchema)(stored.value);
+            released = (await releasePendingRow(row, now)) || released;
+        }
+        if (released)
+            await options.scheduleWake(now);
+        return rows.length === pageSize ? rows.at(-1)?.key : undefined;
+    };
     const deadLetters = (limit = 64, afterKey) => {
         const pageSize = Schema.decodeUnknownSync(PageLimit)(limit);
         const rows = store.list(pageSize, afterKey);
@@ -418,6 +492,7 @@ export function createPost(options) {
         retry,
         execute,
         enqueueDue,
+        releaseNow,
         deadLetters,
         read: readRow,
         nextWake,

package/docs/api/inspection.md

@@ -157,7 +157,7 @@ const PostReceiptSummarySchema: Union<
       state: Literal<"dead">;
       kind: String;
       attempts: Int;
-      reason: Literals<readonly ["refused", "exhausted"]>;
+      reason: Literals<readonly ["refused", "exhausted", "expired"]>;
     }>,
   ]
 >;
@@ -188,7 +188,7 @@ const PostInspectionPageSchema: Union<readonly [Struct<{
      state: Literal<"dead">;
      kind: String;
      attempts: Int;
-     reason: Literals<readonly [..., ...]>;
+     reason: Literals<readonly [..., ..., ...]>;
   }>]>>;
   nextCursor: NullOr<String>;
 }>]>;
@@ -275,7 +275,7 @@ jobs or arming a wake. The trusted host must admit an operator before calling.
 
 #### Returns
 
-| Name      | Type                                                                                                                                                                                                                                                                                                                                                                                                                                               | Description                                                                        |
-| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
-| `email()` | (`input`) => \| \{ `status`: `"uninitialized"`; \} \| \{ `status`: `"available"`; `records`: readonly `object`[]; `nextCursor`: `string` \| `null`; \}                                                                                                                                                                                                                                                                                             | Read aggregate dispatch evidence without email cargo or recipient addresses.       |
-| `post()`  | (`input`) => \| \{ `status`: `"uninitialized"`; \} \| \{ `status`: `"available"`; `records`: readonly ( \| \{ `key`: `string`; `state`: `"delivered"`; \} \| \{ `key`: `string`; `state`: `"pending"`; `kind`: `string`; `attempts`: `number`; `nextAttemptAt`: `number`; \} \| \{ `key`: `string`; `state`: `"dead"`; `kind`: `string`; `attempts`: `number`; `reason`: `"refused"` \| `"exhausted"`; \})[]; `nextCursor`: `string` \| `null`; \} | Read Post metadata; filtered pages retain their continuation through other states. |
+| Name      | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Description                                                                        |
+| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| `email()` | (`input`) => \| \{ `status`: `"uninitialized"`; \} \| \{ `status`: `"available"`; `records`: readonly `object`[]; `nextCursor`: `string` \| `null`; \}                                                                                                                                                                                                                                                                                                            | Read aggregate dispatch evidence without email cargo or recipient addresses.       |
+| `post()`  | (`input`) => \| \{ `status`: `"uninitialized"`; \} \| \{ `status`: `"available"`; `records`: readonly ( \| \{ `key`: `string`; `state`: `"delivered"`; \} \| \{ `key`: `string`; `state`: `"pending"`; `kind`: `string`; `attempts`: `number`; `nextAttemptAt`: `number`; \} \| \{ `key`: `string`; `state`: `"dead"`; `kind`: `string`; `attempts`: `number`; `reason`: `"expired"` \| `"refused"` \| `"exhausted"`; \})[]; `nextCursor`: `string` \| `null`; \} | Read Post metadata; filtered pages retain their continuation through other states. |

package/docs/api/post-d1.md

@@ -114,14 +114,13 @@ Carrier-owned D1 schema, applied by the deployment migration owner.
 function createD1Post<R>(options): D1Post;
 ```
 
-Bind the Post registry to native D1 batch admission and the shared delivery
-engine.
+Bind the Post registry to D1; route deadlines are rejected with PostError.
 
 #### Type Parameters
 
-| Type Parameter                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `R` _extends_ `Record`\<`string`, `Readonly`\<\{ `addressKind`: `string`; `address`: `Codec`\<`unknown`, `unknown`\>; `event`: `Codec`\<`unknown`, `unknown`\>; `encodeEnvelope`: (`envelope`) => `object`; `parseDelivery`: (`envelope`) => `object`; `prepareEnvelope?`: (`envelope`, `signal`) => `Promise`\<\{ `key`: `string`; `kind`: `string`; `address`: `unknown`; `event`: `unknown`; \}\>; `recordDelivered?`: (`envelope`) => `void`; `nameOf`: (`envelope`) => `string`; `namespace`: `Readonly`\<\{ `getByName`: (`name`) => `Readonly`\<\{ `deliver`: (`envelope`) => `Promise`\<[`PostDeliveryResult`](post.md#postdeliveryresult)\>; \}\>; \}\>; `recordCursor?`: (`envelope`, `cursor`) => `void`; `recordRefused?`: (`envelope`) => `void`; \}\>\> |
+| Type Parameter                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `R` _extends_ `Record`\<`string`, `Readonly`\<\{ `addressKind`: `string`; `deadlineMs?`: `number`; `address`: `Codec`\<`unknown`, `unknown`\>; `event`: `Codec`\<`unknown`, `unknown`\>; `encodeEnvelope`: (`envelope`) => `object`; `parseDelivery`: (`envelope`) => `object`; `prepareEnvelope?`: (`envelope`, `signal`) => `Promise`\<\{ `key`: `string`; `kind`: `string`; `address`: `unknown`; `event`: `unknown`; \}\>; `recordDelivered?`: (`envelope`) => `void`; `nameOf`: (`envelope`) => `string`; `namespace`: `Readonly`\<\{ `getByName`: (`name`) => `Readonly`\<\{ `deliver`: (`envelope`) => `Promise`\<[`PostDeliveryResult`](post.md#postdeliveryresult)\>; \}\>; \}\>; `recordCursor?`: (`envelope`, `cursor`) => `void`; `recordRefused?`: (`envelope`) => `void`; \}\>\> |
 
 #### Parameters
 

package/docs/api/post-postgres.md

@@ -52,13 +52,14 @@ Carrier-owned PostgreSQL schema, applied by the deployment migration owner.
 function createPostgresPost<R>(options): PostgresPost;
 ```
 
-Bind the Post registry to a PostgreSQL owner and the shared delivery engine.
+Bind the Post registry to PostgreSQL; route deadlines are rejected with
+PostError.
 
 #### Type Parameters
 
-| Type Parameter                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `R` _extends_ `Record`\<`string`, `Readonly`\<\{ `addressKind`: `string`; `address`: `Codec`\<`unknown`, `unknown`\>; `event`: `Codec`\<`unknown`, `unknown`\>; `encodeEnvelope`: (`envelope`) => `object`; `parseDelivery`: (`envelope`) => `object`; `prepareEnvelope?`: (`envelope`, `signal`) => `Promise`\<\{ `key`: `string`; `kind`: `string`; `address`: `unknown`; `event`: `unknown`; \}\>; `recordDelivered?`: (`envelope`) => `void`; `nameOf`: (`envelope`) => `string`; `namespace`: `Readonly`\<\{ `getByName`: (`name`) => `Readonly`\<\{ `deliver`: (`envelope`) => `Promise`\<[`PostDeliveryResult`](post.md#postdeliveryresult)\>; \}\>; \}\>; `recordCursor?`: (`envelope`, `cursor`) => `void`; `recordRefused?`: (`envelope`) => `void`; \}\>\> |
+| Type Parameter                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `R` _extends_ `Record`\<`string`, `Readonly`\<\{ `addressKind`: `string`; `deadlineMs?`: `number`; `address`: `Codec`\<`unknown`, `unknown`\>; `event`: `Codec`\<`unknown`, `unknown`\>; `encodeEnvelope`: (`envelope`) => `object`; `parseDelivery`: (`envelope`) => `object`; `prepareEnvelope?`: (`envelope`, `signal`) => `Promise`\<\{ `key`: `string`; `kind`: `string`; `address`: `unknown`; `event`: `unknown`; \}\>; `recordDelivered?`: (`envelope`) => `void`; `nameOf`: (`envelope`) => `string`; `namespace`: `Readonly`\<\{ `getByName`: (`name`) => `Readonly`\<\{ `deliver`: (`envelope`) => `Promise`\<[`PostDeliveryResult`](post.md#postdeliveryresult)\>; \}\>; \}\>; `recordCursor?`: (`envelope`, `cursor`) => `void`; `recordRefused?`: (`envelope`) => `void`; \}\>\> |
 
 #### Parameters
 

package/docs/api/post.md

@@ -12,26 +12,27 @@
 
 ### PostError
 
-Post rejected an unknown route or conflicting key.
+Post rejected an unknown route, conflicting key, or unsupported policy.
 
 #### Extends
 
 - `YieldableError`\<`this`\> & `object` & `Readonly`\<\{ `message`: `string`;
-  \}\>
+  `reason?`: `"relational-deadline-unsupported"`; \}\>
 
 #### Constructors
 
 ##### Constructor
 
 ```ts
-new PostError(message): PostError;
+new PostError(message, reason?): PostError;
 ```
 
 ###### Parameters
 
-| Parameter | Type     |
-| --------- | -------- |
-| `message` | `string` |
+| Parameter | Type                                |
+| --------- | ----------------------------------- |
+| `message` | `string`                            |
+| `reason?` | `"relational-deadline-unsupported"` |
 
 ###### Returns
 
@@ -42,11 +43,24 @@ new PostError(message): PostError;
 ```ts
 Data.TaggedError("PostError")<{
   readonly message: string;
+  readonly reason?: "relational-deadline-unsupported";
 }>.constructor
 ```
 
 #### Properties
 
+##### reason?
+
+```ts
+readonly optional reason?: "relational-deadline-unsupported";
+```
+
+###### Inherited from
+
+```ts
+Data.TaggedError("PostError").reason;
+```
+
 ##### message
 
 ```ts
@@ -118,6 +132,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>;
 }>;
 ```
@@ -158,6 +173,7 @@ Pending row, terminal receipt, or dead letter.
 ```ts
 type PostRoute<A, E, D, AI, EI, DI> = Readonly<{
   addressKind: string;
+  deadlineMs?: number;
   address: Schema.Codec<A, AI>;
   event: Schema.Codec<E, EI>;
   name: (address) => string;
@@ -204,6 +220,7 @@ Schema-correlated ordinary events or prepared delivery facts.
 ```ts
 type PostRegistryRoute = Readonly<{
   addressKind: string;
+  deadlineMs?: number;
   address: Schema.Codec<unknown, unknown>;
   event: Schema.Codec<unknown, unknown>;
   encodeEnvelope: (envelope) => PostEnvelope;
@@ -232,13 +249,14 @@ type PostRuntime<R> = Readonly<{
     }>
   >;
   enqueueDue: (limit?, afterKey?) => Promise<string | undefined>;
+  releaseNow: (limit?, afterKey?) => Promise<string | undefined>;
   deadLetters: (
     limit?,
     afterKey?,
   ) => Readonly<{
     letters: readonly Readonly<{
       key: string;
-      reason: "refused" | "exhausted";
+      reason: "refused" | "exhausted" | "expired";
       envelope: PostEnvelope;
       attempts: number;
     }>[];
@@ -322,6 +340,7 @@ const PostRowSchema: fromJsonString<
         }>;
         attempts: Int;
         nextAttemptAt: Number;
+        deadlineAt: optional<Number>;
         jobId: optional<String>;
         delivery: optional<
           Struct<{
@@ -347,7 +366,8 @@ const PostRowSchema: fromJsonString<
           event: Unknown;
         }>;
         attempts: Int;
-        reason: Literals<readonly ["refused", "exhausted"]>;
+        reason: Literals<readonly ["refused", "exhausted", "expired"]>;
+        deadlineAt: optional<Number>;
         receipt: optional<Codec<Json, Json, never, never>>;
         delivery: optional<
           Struct<{
@@ -368,33 +388,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 +434,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`\>
 
 ---
 
@@ -422,6 +451,7 @@ The same bounded delivery and receipt machinery serves Post and BirdDog.
 ```ts
 function definePostRoute<A, E, AI, EI>(route): PostRoute<A, E, E, AI, EI, EI> & Omit<Readonly<{
   addressKind: string;
+  deadlineMs?: number;
   address: Codec<unknown, unknown>;
   event: Codec<unknown, unknown>;
   encodeEnvelope: (envelope) => object;
@@ -457,29 +487,30 @@ Preserve each route's inferred address and event types in a registry.
 
 ##### Parameters
 
-| Parameter | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `route`   | `Readonly`\<\{ `addressKind`: `string`; `address`: `Codec`\<`A`, `AI`\>; `event`: `Codec`\<`E`, `EI`\>; `name`: (`address`) => `string`; `namespace`: `Readonly`\<\{ `getByName`: (`name`) => `Readonly`\<\{ `deliver`: (`envelope`) => `Promise`\<[`PostDeliveryResult`](#postdeliveryresult)\>; \}\>; \}\>; \}\> & `Readonly`\<\{ `prepare?`: `undefined`; `onDelivered?`: (`address`, `event`) => `void`; `onCursor?`: (`address`, `event`, `cursor`) => `void`; `onRefused?`: (`address`, `event`) => `void`; \}\> |
+| Parameter | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `route`   | `Readonly`\<\{ `addressKind`: `string`; `deadlineMs?`: `number`; `address`: `Codec`\<`A`, `AI`\>; `event`: `Codec`\<`E`, `EI`\>; `name`: (`address`) => `string`; `namespace`: `Readonly`\<\{ `getByName`: (`name`) => `Readonly`\<\{ `deliver`: (`envelope`) => `Promise`\<[`PostDeliveryResult`](#postdeliveryresult)\>; \}\>; \}\>; \}\> & `Readonly`\<\{ `prepare?`: `undefined`; `onDelivered?`: (`address`, `event`) => `void`; `onCursor?`: (`address`, `event`, `cursor`) => `void`; `onRefused?`: (`address`, `event`) => `void`; \}\> |
 
 ##### Returns
 
 [`PostRoute`](#postroute)\<`A`, `E`, `E`, `AI`, `EI`, `EI`\> &
-`Omit`\<`Readonly`\<\{ `addressKind`: `string`; `address`: `Codec`\<`unknown`,
-`unknown`\>; `event`: `Codec`\<`unknown`, `unknown`\>; `encodeEnvelope`:
-(`envelope`) => `object`; `parseDelivery`: (`envelope`) => `object`;
-`prepareEnvelope?`: (`envelope`, `signal`) => `Promise`\<\{ `key`: `string`;
-`kind`: `string`; `address`: `unknown`; `event`: `unknown`; \}\>;
-`recordDelivered?`: (`envelope`) => `void`; `nameOf`: (`envelope`) => `string`;
-`namespace`: `Readonly`\<\{ `getByName`: (`name`) => `Readonly`\<\{ `deliver`:
-(`envelope`) => `Promise`\<...\>; \}\>; \}\>; `recordCursor?`: (`envelope`,
-`cursor`) => `void`; `recordRefused?`: (`envelope`) => `void`; \}\>, `"address"`
-\| `"event"`\>
+`Omit`\<`Readonly`\<\{ `addressKind`: `string`; `deadlineMs?`: `number`;
+`address`: `Codec`\<`unknown`, `unknown`\>; `event`: `Codec`\<`unknown`,
+`unknown`\>; `encodeEnvelope`: (`envelope`) => `object`; `parseDelivery`:
+(`envelope`) => `object`; `prepareEnvelope?`: (`envelope`, `signal`) =>
+`Promise`\<\{ `key`: `string`; `kind`: `string`; `address`: `unknown`; `event`:
+`unknown`; \}\>; `recordDelivered?`: (`envelope`) => `void`; `nameOf`:
+(`envelope`) => `string`; `namespace`: `Readonly`\<\{ `getByName`: (`name`) =>
+`Readonly`\<\{ `deliver`: (`envelope`) => `Promise`\<...\>; \}\>; \}\>;
+`recordCursor?`: (`envelope`, `cursor`) => `void`; `recordRefused?`:
+(`envelope`) => `void`; \}\>, `"address"` \| `"event"`\>
 
 #### Call Signature
 
 ```ts
 function definePostRoute<A, E, D, AI, EI, DI>(route): PostRoute<A, E, D, AI, EI, DI> & Omit<Readonly<{
   addressKind: string;
+  deadlineMs?: number;
   address: Codec<unknown, unknown>;
   event: Codec<unknown, unknown>;
   encodeEnvelope: (envelope) => object;
@@ -517,54 +548,23 @@ Preserve each route's inferred address and event types in a registry.
 
 ##### Parameters
 
-| Parameter | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `route`   | `Readonly`\<\{ `addressKind`: `string`; `address`: `Codec`\<`A`, `AI`\>; `event`: `Codec`\<`E`, `EI`\>; `name`: (`address`) => `string`; `namespace`: `Readonly`\<\{ `getByName`: (`name`) => `Readonly`\<\{ `deliver`: (`envelope`) => `Promise`\<[`PostDeliveryResult`](#postdeliveryresult)\>; \}\>; \}\>; \}\> & `Readonly`\<\{ `prepare`: `Readonly`\<\{ `event`: `Schema.Codec`\<`D`, `DI`\>; `run`: (`address`, `intent`, `signal`) => `Promise`\<`D`\>; \}\>; `onDelivered?`: (`address`, `event`) => `void`; `onCursor?`: (`address`, `event`, `cursor`) => `void`; `onRefused?`: (`address`, `event`) => `void`; \}\> |
+| Parameter | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `route`   | `Readonly`\<\{ `addressKind`: `string`; `deadlineMs?`: `number`; `address`: `Codec`\<`A`, `AI`\>; `event`: `Codec`\<`E`, `EI`\>; `name`: (`address`) => `string`; `namespace`: `Readonly`\<\{ `getByName`: (`name`) => `Readonly`\<\{ `deliver`: (`envelope`) => `Promise`\<[`PostDeliveryResult`](#postdeliveryresult)\>; \}\>; \}\>; \}\> & `Readonly`\<\{ `prepare`: `Readonly`\<\{ `event`: `Schema.Codec`\<`D`, `DI`\>; `run`: (`address`, `intent`, `signal`) => `Promise`\<`D`\>; \}\>; `onDelivered?`: (`address`, `event`) => `void`; `onCursor?`: (`address`, `event`, `cursor`) => `void`; `onRefused?`: (`address`, `event`) => `void`; \}\> |
 
 ##### Returns
 
 [`PostRoute`](#postroute)\<`A`, `E`, `D`, `AI`, `EI`, `DI`\> &
-`Omit`\<`Readonly`\<\{ `addressKind`: `string`; `address`: `Codec`\<`unknown`,
-`unknown`\>; `event`: `Codec`\<`unknown`, `unknown`\>; `encodeEnvelope`:
-(`envelope`) => `object`; `parseDelivery`: (`envelope`) => `object`;
-`prepareEnvelope?`: (`envelope`, `signal`) => `Promise`\<\{ `key`: `string`;
-`kind`: `string`; `address`: `unknown`; `event`: `unknown`; \}\>;
-`recordDelivered?`: (`envelope`) => `void`; `nameOf`: (`envelope`) => `string`;
-`namespace`: `Readonly`\<\{ `getByName`: (`name`) => `Readonly`\<\{ `deliver`:
-(`envelope`) => `Promise`\<...\>; \}\>; \}\>; `recordCursor?`: (`envelope`,
-`cursor`) => `void`; `recordRefused?`: (`envelope`) => `void`; \}\>, `"address"`
-\| `"event"`\>
-
----
-
-### 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`
+`Omit`\<`Readonly`\<\{ `addressKind`: `string`; `deadlineMs?`: `number`;
+`address`: `Codec`\<`unknown`, `unknown`\>; `event`: `Codec`\<`unknown`,
+`unknown`\>; `encodeEnvelope`: (`envelope`) => `object`; `parseDelivery`:
+(`envelope`) => `object`; `prepareEnvelope?`: (`envelope`, `signal`) =>
+`Promise`\<\{ `key`: `string`; `kind`: `string`; `address`: `unknown`; `event`:
+`unknown`; \}\>; `recordDelivered?`: (`envelope`) => `void`; `nameOf`:
+(`envelope`) => `string`; `namespace`: `Readonly`\<\{ `getByName`: (`name`) =>
+`Readonly`\<\{ `deliver`: (`envelope`) => `Promise`\<...\>; \}\>; \}\>;
+`recordCursor?`: (`envelope`, `cursor`) => `void`; `recordRefused?`:
+(`envelope`) => `void`; \}\>, `"address"` \| `"event"`\>
 
 ---
 
@@ -578,9 +578,9 @@ Decode at both persisted and DO boundaries with the route's Effect Schema.
 
 #### Type Parameters
 
-| Type Parameter                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `R` _extends_ `Record`\<`string`, `Readonly`\<\{ `addressKind`: `string`; `address`: `Codec`\<`unknown`, `unknown`\>; `event`: `Codec`\<`unknown`, `unknown`\>; `encodeEnvelope`: (`envelope`) => `object`; `parseDelivery`: (`envelope`) => `object`; `prepareEnvelope?`: (`envelope`, `signal`) => `Promise`\<\{ `key`: `string`; `kind`: `string`; `address`: `unknown`; `event`: `unknown`; \}\>; `recordDelivered?`: (`envelope`) => `void`; `nameOf`: (`envelope`) => `string`; `namespace`: `Readonly`\<\{ `getByName`: (`name`) => `Readonly`\<\{ `deliver`: (`envelope`) => `Promise`\<[`PostDeliveryResult`](#postdeliveryresult)\>; \}\>; \}\>; `recordCursor?`: (`envelope`, `cursor`) => `void`; `recordRefused?`: (`envelope`) => `void`; \}\>\> |
+| Type Parameter                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `R` _extends_ `Record`\<`string`, `Readonly`\<\{ `addressKind`: `string`; `deadlineMs?`: `number`; `address`: `Codec`\<`unknown`, `unknown`\>; `event`: `Codec`\<`unknown`, `unknown`\>; `encodeEnvelope`: (`envelope`) => `object`; `parseDelivery`: (`envelope`) => `object`; `prepareEnvelope?`: (`envelope`, `signal`) => `Promise`\<\{ `key`: `string`; `kind`: `string`; `address`: `unknown`; `event`: `unknown`; \}\>; `recordDelivered?`: (`envelope`) => `void`; `nameOf`: (`envelope`) => `string`; `namespace`: `Readonly`\<\{ `getByName`: (`name`) => `Readonly`\<\{ `deliver`: (`envelope`) => `Promise`\<[`PostDeliveryResult`](#postdeliveryresult)\>; \}\>; \}\>; `recordCursor?`: (`envelope`, `cursor`) => `void`; `recordRefused?`: (`envelope`) => `void`; \}\>\> |
 
 #### Parameters
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fungi.computer/carrier",
-  "version": "0.0.1",
+  "version": "0.2.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"