@fungi.computer/carrier 0.2.0 → 0.2.2

package/docs/api/post.md

@@ -12,12 +12,13 @@
 
 ### PostError
 
-Post rejected an unknown route, conflicting key, or unsupported policy.
+Post rejected an unknown route, conflicting key, unsupported policy or store.
 
 #### Extends
 
 - `YieldableError`\<`this`\> & `object` & `Readonly`\<\{ `message`: `string`;
-  `reason?`: `"relational-deadline-unsupported"`; \}\>
+  `reason?`: `"relational-deadline-unsupported"` \| `"pre-scheduler-store"`;
+  \}\>
 
 #### Constructors
 
@@ -29,10 +30,10 @@ new PostError(message, reason?): PostError;
 
 ###### Parameters
 
-| Parameter | Type                                |
-| --------- | ----------------------------------- |
-| `message` | `string`                            |
-| `reason?` | `"relational-deadline-unsupported"` |
+| Parameter | Type                                                           |
+| --------- | -------------------------------------------------------------- |
+| `message` | `string`                                                       |
+| `reason?` | `"relational-deadline-unsupported"` \| `"pre-scheduler-store"` |
 
 ###### Returns
 
@@ -43,7 +44,7 @@ new PostError(message, reason?): PostError;
 ```ts
 Data.TaggedError("PostError")<{
   readonly message: string;
-  readonly reason?: "relational-deadline-unsupported";
+  readonly reason?: "relational-deadline-unsupported" | "pre-scheduler-store";
 }>.constructor
 ```
 
@@ -52,7 +53,7 @@ Data.TaggedError("PostError")<{
 ##### reason?
 
 ```ts
-readonly optional reason?: "relational-deadline-unsupported";
+readonly optional reason?: "relational-deadline-unsupported" | "pre-scheduler-store";
 ```
 
 ###### Inherited from
@@ -96,58 +97,6 @@ Receiver's idempotent admission decision.
 
 ---
 
-### PostOutboxStore
-
-```ts
-type PostOutboxStore<E> = Readonly<{
-  put: (key, value) => Effect.Effect<void, E>;
-  read: (key) => Effect.Effect<string | undefined, E>;
-  list: (
-    limit,
-    afterKey?,
-  ) => Effect.Effect<
-    readonly Readonly<{
-      key: string;
-      value: string;
-    }>[],
-    E
-  >;
-  delete: (key) => Effect.Effect<void, E>;
-}>;
-```
-
-Durable, string-backed rows. A delivered receipt must outlive source replay.
-
-#### Type Parameters
-
-| Type Parameter |
-| -------------- |
-| `E`            |
-
----
-
-### PostOutbox
-
-```ts
-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>;
-}>;
-```
-
-Bounded generic delivery owned by Post.
-
-#### Type Parameters
-
-| Type Parameter |
-| -------------- |
-| `M`            |
-| `E`            |
-
----
-
 ### PostEnvelope
 
 ```ts
@@ -243,12 +192,8 @@ Runtime operations that preserve the route's schema evidence.
 ```ts
 type PostRuntime<R> = Readonly<{
   send: <K>(input) => void;
-  execute: (job) => Promise<
-    Readonly<{
-      kind: "completed";
-    }>
-  >;
-  enqueueDue: (limit?, afterKey?) => Promise<string | undefined>;
+  retryPolicy: (job) => Promise<WatchdogRetryPolicy>;
+  execute: (job, attempt, signal?) => Promise<WatchdogExecutionDecision>;
   releaseNow: (limit?, afterKey?) => Promise<string | undefined>;
   deadLetters: (
     limit?,
@@ -273,7 +218,6 @@ type PostRuntime<R> = Readonly<{
     | undefined;
   retry: (key) => Promise<void>;
   read: (key) => PostRow | undefined;
-  nextWake: () => number | null;
 }>;
 ```
 
@@ -338,10 +282,8 @@ const PostRowSchema: fromJsonString<
           address: Unknown;
           event: Unknown;
         }>;
-        attempts: Int;
-        nextAttemptAt: Number;
         deadlineAt: optional<Number>;
-        jobId: optional<String>;
+        jobId: String;
         delivery: optional<
           Struct<{
             key: String;
@@ -350,12 +292,10 @@ const PostRowSchema: fromJsonString<
             event: Unknown;
           }>
         >;
-        nextKey: optional<String>;
       }>,
       Struct<{
         state: Literal<"delivered">;
         receipt: optional<Codec<Json, Json, never, never>>;
-        nextKey: optional<String>;
       }>,
       Struct<{
         state: Literal<"dead">;
@@ -377,7 +317,6 @@ const PostRowSchema: fromJsonString<
             event: Unknown;
           }>
         >;
-        nextKey: optional<String>;
       }>,
     ]
   >
@@ -388,62 +327,6 @@ Persisted Post row parser.
 
 ## Functions
 
-### makePostOutbox()
-
-```ts
-function makePostOutbox<M, E>(options): PostOutbox<M, E>;
-```
-
-The same bounded delivery and receipt machinery serves Post and BirdDog.
-
-#### Type Parameters
-
-| Type Parameter |
-| -------------- |
-| `M`            |
-| `E`            |
-
-#### 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`; \}\> |
-
-#### Returns
-
-[`PostOutbox`](#postoutbox)\<`M`, `E`\>
-
----
-
-### postOutboxPending()
-
-```ts
-function postOutboxPending<M, E>(options): Effect<boolean, 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.
-
-#### Type Parameters
-
-| Type Parameter |
-| -------------- |
-| `M`            |
-| `E`            |
-
-#### Parameters
-
-| Parameter | Type                                                                                                                              |
-| --------- | --------------------------------------------------------------------------------------------------------------------------------- |
-| `options` | `Readonly`\<\{ `message`: `Schema.Codec`\<`M`\>; `outbox`: `Pick`\<[`PostOutboxStore`](#postoutboxstore)\<`E`\>, `"list"`\>; \}\> |
-
-#### Returns
-
-`Effect`\<`boolean`, `E`\>
-
----
-
 ### definePostRoute()
 
 #### Call Signature
@@ -584,9 +467,9 @@ Decode at both persisted and DO boundaries with the route's Effect Schema.
 
 #### Parameters
 
-| Parameter | Type                                                                                                                                                                                                                                   |
-| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `options` | `Readonly`\<\{ `routes`: `R`; `owner`: `WatchdogSqliteOwner`; `transactional`: `WatchdogTransactionalProjection`; `readJob`: `WatchdogRuntime`\[`"read"`\]; `now`: () => `number`; `scheduleWake`: (`at`) => `Promise`\<`void`\>; \}\> |
+| Parameter | Type                                                                                                                                                                                         |
+| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `options` | `Readonly`\<\{ `routes`: `R`; `owner`: `WatchdogSqliteOwner`; `transactional`: `WatchdogTransactionalProjection`; `now`: () => `number`; `scheduleWake`: (`at`) => `Promise`\<`void`\>; \}\> |
 
 #### Returns
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fungi.computer/carrier",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "author": "Levi <levi@technomancy.dev>",
   "description": "Durable email submission and recipient delivery tracking",
   "type": "module",
@@ -34,10 +34,6 @@
     "./post-postgres": {
       "types": "./dist/post-postgres.d.ts",
       "import": "./dist/post-postgres.js"
-    },
-    "./testing": {
-      "types": "./dist/testing.d.ts",
-      "import": "./dist/testing.js"
     }
   },
   "files": [
@@ -48,9 +44,9 @@
   ],
   "dependencies": {
     "@cloudflare/workers-types": "5.20260828.1",
-    "@fungi.computer/almanac": "0.2.0",
+    "@fungi.computer/almanac": "0.2.1",
     "@fungi.computer/cairn": "0.1.0",
-    "@fungi.computer/watchdog": "0.1.0",
+    "@fungi.computer/watchdog": "0.1.1",
     "effect": "4.0.2",
     "pg": "8.23.0",
     "@types/pg": "8.23.1"

package/dist/post-outbox.d.ts

@@ -1,52 +0,0 @@
-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 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. */
-    put: (key: string, value: string) => Effect.Effect<void, E>;
-    /** Inspect one durable row by key. */
-    read: (key: string) => Effect.Effect<string | undefined, E>;
-    /** Read an ordered bounded page. */
-    list: (limit: number, afterKey?: string) => Effect.Effect<readonly Readonly<{
-        key: string;
-        value: string;
-    }>[], E>;
-    /** Discard one malformed row. */
-    delete: (key: string) => Effect.Effect<void, E>;
-}>;
-/** Bounded generic delivery owned by Post. */
-export type PostOutbox<M, E> = Readonly<{
-    /** Queue a message and return its wake hint so a fan-out can schedule once. */
-    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>;
-}>;
-/** The same bounded delivery and receipt machinery serves Post and BirdDog. */
-export declare function makePostOutbox<M, E>(options: Readonly<{
-    message: Schema.Codec<M>;
-    key: (message: M) => string;
-    outbox: PostOutboxStore<E>;
-    deliver: (message: M) => Effect.Effect<boolean, E>;
-    scheduleWake: (at: number) => Effect.Effect<void, E>;
-    now: () => number;
-    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,152 +0,0 @@
-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 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 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),
-        catch: options.encodingFailed,
-    });
-    const enqueue = (message, at = options.now()) => Effect.gen(function* () {
-        const key = options.key(message);
-        const existing = yield* options.outbox.read(key);
-        if (existing !== undefined) {
-            const row = yield* decode(existing);
-            if ("state" in row || row.attempts >= maxDeliveryAttempts)
-                return;
-            return Math.max(at, row.nextAttemptAt ?? at);
-        }
-        const value = yield* encode({ mail: message, attempts: 0 });
-        yield* options.outbox.put(key, value);
-        return at;
-    });
-    const process = (stored, now) => Effect.gen(function* () {
-        const decoded = yield* Effect.result(decode(stored.value));
-        if (decoded._tag === "Failure") {
-            yield* options.outbox.delete(stored.key);
-            return undefined;
-        }
-        const row = decoded.success;
-        if ("state" in row || row.attempts >= maxDeliveryAttempts)
-            return undefined;
-        if (row.nextAttemptAt !== undefined && row.nextAttemptAt > now)
-            return row.nextAttemptAt;
-        const delivered = yield* options.deliver(row.mail).pipe(Effect.catch((cause) => Effect.sync(() => {
-            logDeliveryFailure(cause);
-        }).pipe(Effect.as(false))));
-        if (delivered) {
-            yield* options.outbox.put(stored.key, yield* encode({ state: "delivered" }));
-            return undefined;
-        }
-        const attempts = row.attempts + 1;
-        const nextAttemptAt = now + backoffDelay(attempts, postRetryPolicy);
-        yield* options.outbox.put(stored.key, yield* encode({ mail: row.mail, attempts, nextAttemptAt }));
-        return attempts < maxDeliveryAttempts ? nextAttemptAt : undefined;
-    });
-    let cursor;
-    let earliestFuture;
-    const drain = () => Effect.gen(function* () {
-        const now = options.now();
-        const rows = yield* options.outbox.list(PageSize, cursor);
-        for (const row of rows)
-            earliestFuture = earlier(earliestFuture, yield* process(row, now));
-        if (rows.length === PageSize) {
-            const lastKey = rows[rows.length - 1]?.key;
-            if (lastKey !== undefined &&
-                (yield* options.outbox.list(1, lastKey)).length > 0) {
-                cursor = lastKey;
-                yield* options.scheduleWake(now);
-                return;
-            }
-        }
-        cursor = undefined;
-        if (earliestFuture !== undefined)
-            yield* options.scheduleWake(Math.max(now, earliestFuture));
-        earliestFuture = undefined;
-    });
-    const deadLetters = (limit, afterKey) => Effect.gen(function* () {
-        const rows = yield* options.outbox.list(limit, afterKey);
-        const dead = [];
-        for (const stored of rows) {
-            const row = yield* decode(stored.value);
-            if (!("state" in row) && row.attempts >= maxDeliveryAttempts)
-                dead.push(row.mail);
-        }
-        return dead;
-    });
-    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/testing.d.ts

@@ -1,16 +0,0 @@
-/** String-row outbox for deterministic tests and quick starts; no persistence. */
-export type MemoryOutbox = Readonly<{
-    /** Store or replace one encoded row. */
-    put: (key: string, value: string) => Promise<void>;
-    /** Read a retained row, if present. */
-    read: (key: string) => Promise<string | undefined>;
-    /** Read a key-ordered page strictly after the supplied cursor. */
-    list: (limit: number, afterKey?: string) => Promise<readonly Readonly<{
-        key: string;
-        value: string;
-    }>[]>;
-    /** Remove one row. */
-    delete: (key: string) => Promise<void>;
-}>;
-/** Create an independent in-process outbox for trusted tests and examples. */
-export declare function createMemoryOutbox(): MemoryOutbox;

package/dist/testing.js

@@ -1,20 +0,0 @@
-/** Create an independent in-process outbox for trusted tests and examples. */
-export function createMemoryOutbox() {
-    const rows = new Map();
-    return {
-        put: (key, value) => {
-            rows.set(key, value);
-            return Promise.resolve();
-        },
-        read: (key) => Promise.resolve(rows.get(key)),
-        list: (limit, afterKey) => Promise.resolve([...rows]
-            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
-            .filter(([key]) => afterKey === undefined || key > afterKey)
-            .slice(0, limit)
-            .map(([key, value]) => ({ key, value }))),
-        delete: (key) => {
-            rows.delete(key);
-            return Promise.resolve();
-        },
-    };
-}

package/docs/api/testing.md

@@ -1,46 +0,0 @@
-<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
-
-[**@fungi.computer/carrier**](README.md)
-
----
-
-[@fungi.computer/carrier](README.md) / testing
-
-# testing
-
-## Type Aliases
-
-### MemoryOutbox
-
-```ts
-type MemoryOutbox = Readonly<{
-  put: (key, value) => Promise<void>;
-  read: (key) => Promise<string | undefined>;
-  list: (
-    limit,
-    afterKey?,
-  ) => Promise<
-    readonly Readonly<{
-      key: string;
-      value: string;
-    }>[]
-  >;
-  delete: (key) => Promise<void>;
-}>;
-```
-
-String-row outbox for deterministic tests and quick starts; no persistence.
-
-## Functions
-
-### createMemoryOutbox()
-
-```ts
-function createMemoryOutbox(): MemoryOutbox;
-```
-
-Create an independent in-process outbox for trusted tests and examples.
-
-#### Returns
-
-[`MemoryOutbox`](#memoryoutbox)