@fungi.computer/bird-dog 0.0.1 → 0.1.0

package/README.md

@@ -163,6 +163,13 @@ schedules an immediate wake and continues from the same place on the next drain.
 receipt under the same key. Replaying the same settlement after a restart finds
 the receipt and does not post the reply again. Keep those receipts as long as
 source settlements can replay. BirdDog does not expire them.
+`hasPendingDelivery(outbox)` reads only whether any reply still awaits a
+delivery attempt, so a host can tell retained receipts and dead letters from
+owed mail.
+
+The Effect mail room's `nextWakeAt()` reads Carrier's earliest owed delivery,
+including future retries. Runtime hosts include that hint in their pending-work
+answer rather than clearing a retry when other runtime work is idle.
 
 **Host ports.** `BirdDog.make` takes four things:
 
@@ -182,11 +189,12 @@ The generated reference is in [docs/api](docs/api/README.md).
   `BirdDogAgentJobPayload`, `BirdDogReply`, `BirdDogOutbox`, `BirdDogOptions`,
   `BirdDogSettlement` and `BirdDogRuntime` types.
 - `@fungi.computer/bird-dog/effect`: `make`, `agentJobFromInput`,
-  `decodeAgentJob`, `settlementReplies`, `boundedDiagnostic`,
-  `BIRD_DOG_DIAGNOSTIC_MAX_LENGTH`, `BirdDogError`, `EffectBirdDogOptions`,
-  `BirdDogEffect` and the schemas `BirdDogAgentReferenceSchema`,
-  `BirdDogReplySchema`, `BirdDogMailSchema`, `BirdDogAgentWorkSchema`,
-  `BirdDogAgentJobPayloadSchema` and `BirdDogAgentJobInputSchema`.
+  `decodeAgentJob`, `settlementReplies`, `hasPendingDelivery`,
+  `boundedDiagnostic`, `BIRD_DOG_DIAGNOSTIC_MAX_LENGTH`, `BirdDogError`,
+  `EffectBirdDogOptions`, `BirdDogEffect` and the schemas
+  `BirdDogAgentReferenceSchema`, `BirdDogReplySchema`, `BirdDogMailSchema`,
+  `BirdDogAgentWorkSchema`, `BirdDogAgentJobPayloadSchema` and
+  `BirdDogAgentJobInputSchema`.
 
 ## Examples and checks
 

package/dist/effect.d.ts

@@ -174,6 +174,8 @@ export type BirdDogEffect = Readonly<{
     fanOut: (settlement: BirdDogSettlement) => Effect.Effect<void, BirdDogError>;
     /** Deliver due replies and schedule any required retry wake. */
     drainOutbox: () => Effect.Effect<void, BirdDogError>;
+    /** Earliest owed reply delivery, including retries; absent after delivery. */
+    nextWakeAt: () => Effect.Effect<number | undefined, BirdDogError>;
 }>;
 /** Validate and translate agent work into Watchdog's opaque job grammar. */
 export declare const agentJobFromInput: (input: BirdDogAgentJobInput) => WatchdogQueuedJob;
@@ -187,5 +189,10 @@ export declare const decodeAgentJob: (job: WatchdogStoredJob) => BirdDogAgentJob
  * are presented. A reply never carries the settled work's host metadata.
  */
 export declare function settlementReplies(settlement: BirdDogSettlement, createdAt: number): readonly BirdDogMail[];
+/**
+ * Whether this mail room's outbox still owes any reply a delivery attempt.
+ * Delivered receipts and exhausted dead letters stay but owe nothing.
+ */
+export declare const hasPendingDelivery: (outbox: Pick<EffectBirdDogOptions["outbox"], "list">) => Effect.Effect<boolean, BirdDogError>;
 /** Construct BirdDog's Effect-native mail room over Post's shared outbox. */
 export declare const make: (options: EffectBirdDogOptions) => Effect.Effect<BirdDogEffect>;

package/dist/effect.js

@@ -1,6 +1,6 @@
 import * as Effect from "effect/Effect";
 import * as Schema from "effect/Schema";
-import { makePostOutbox } from "@fungi.computer/carrier/post";
+import { makePostOutbox, postOutboxPending, } from "@fungi.computer/carrier/post";
 const Identifier = Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(256));
 /** Parser for an ordinary agent Session address. */
 export const BirdDogAgentReferenceSchema = Schema.Struct({
@@ -150,6 +150,11 @@ export function settlementReplies(settlement, createdAt) {
         reply,
     }));
 }
+/**
+ * Whether this mail room's outbox still owes any reply a delivery attempt.
+ * Delivered receipts and exhausted dead letters stay but owe nothing.
+ */
+export const hasPendingDelivery = (outbox) => postOutboxPending({ message: BirdDogMailSchema, outbox });
 /** Construct BirdDog's Effect-native mail room over Post's shared outbox. */
 export const make = (options) => {
     const post = makePostOutbox({
@@ -177,5 +182,9 @@ export const make = (options) => {
         if (wake !== undefined)
             yield* options.scheduleWake(wake);
     });
-    return Effect.succeed({ fanOut, drainOutbox: post.drain });
+    return Effect.succeed({
+        fanOut,
+        drainOutbox: post.drain,
+        nextWakeAt: post.nextWakeAt,
+    });
 };

package/docs/api/effect.md

@@ -90,6 +90,7 @@ Effect host ports for the durable mail room.
 type BirdDogEffect = Readonly<{
   fanOut: (settlement) => Effect.Effect<void, BirdDogError>;
   drainOutbox: () => Effect.Effect<void, BirdDogError>;
+  nextWakeAt: () => Effect.Effect<number | undefined, BirdDogError>;
 }>;
 ```
 
@@ -455,6 +456,27 @@ readonly `Readonly`\<\{ `key`: `string`; `to`:
 
 ---
 
+### hasPendingDelivery()
+
+```ts
+function hasPendingDelivery(outbox): Effect<boolean, BirdDogError>;
+```
+
+Whether this mail room's outbox still owes any reply a delivery attempt.
+Delivered receipts and exhausted dead letters stay but owe nothing.
+
+#### Parameters
+
+| Parameter | Type                                                                              |
+| --------- | --------------------------------------------------------------------------------- |
+| `outbox`  | `Pick`\<[`EffectBirdDogOptions`](#effectbirddogoptions)\[`"outbox"`\], `"list"`\> |
+
+#### Returns
+
+`Effect`\<`boolean`, [`BirdDogError`](#birddogerror)\>
+
+---
+
 ### make()
 
 ```ts
@@ -462,6 +484,7 @@ function make(options): Effect<
   Readonly<{
     fanOut: (settlement) => Effect<void, BirdDogError>;
     drainOutbox: () => Effect<void, BirdDogError>;
+    nextWakeAt: () => Effect<number | undefined, BirdDogError>;
   }>
 >;
 ```
@@ -478,4 +501,5 @@ Construct BirdDog's Effect-native mail room over Post's shared outbox.
 
 `Effect`\<`Readonly`\<\{ `fanOut`: (`settlement`) => `Effect`\<`void`,
 [`BirdDogError`](#birddogerror)\>; `drainOutbox`: () => `Effect`\<`void`,
-[`BirdDogError`](#birddogerror)\>; \}\>\>
+[`BirdDogError`](#birddogerror)\>; `nextWakeAt`: () => `Effect`\<`number` \|
+`undefined`, [`BirdDogError`](#birddogerror)\>; \}\>\>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fungi.computer/bird-dog",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "author": "Levi <levi@technomancy.dev>",
   "description": "Durable addressed agent mail over generic Watchdog work",
   "type": "module",
@@ -23,8 +23,8 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@fungi.computer/carrier": "0.0.1",
-    "@fungi.computer/watchdog": "0.0.1",
+    "@fungi.computer/carrier": "0.1.0",
+    "@fungi.computer/watchdog": "0.1.0",
     "effect": "4.0.2"
   },
   "devDependencies": {