@fungi.computer/bird-dog 0.3.3 → 0.3.4

package/README.md

@@ -1,24 +1,12 @@
 # BirdDog (`@fungi.computer/bird-dog`)
 
-BirdDog is a durable mail room for AI agents. One agent sends work to another
-agent's session, the work runs as a [Watchdog](../watchdog/README.md) job, and
-when that job settles BirdDog delivers the reply to everyone on the envelope's
-`replyTo` list. Replies sit in a durable outbox and retry on a bounded schedule
-until the recipient accepts them.
-
-It does two jobs:
-
-- It translates addressed agent work into an opaque Watchdog job, and decodes
-  that job's payload back after Watchdog claims it.
-- It fans out replies when the job settles, stores them in your outbox, and
-  delivers them with retries through Carrier's Post outbox
-  ([`@fungi.computer/carrier/post`](../carrier/README.md)).
-
-Every sender and recipient is an ordinary agent session. A parent and a child
-agent are both plain agents to BirdDog. Their relationship lives in your code,
-and all agent work uses Watchdog's `default` lane. You own storage, transport,
-the clock and wake scheduling. BirdDog owns the envelope format, the reply keys
-and the retry schedule.
+BirdDog translates addressed Agent work into Watchdog jobs and builds replies
+when that work settles. It owns envelope grammar, reply keys and settlement
+content. The host stages each reply batch through its existing Carrier Post
+owner; Watchdog owns delivery attempts and wakes.
+
+Every sender and recipient is an ordinary Agent Session. Parent and child
+relationships remain in the host's domain records.
 
 ## Install or set up
 
@@ -26,10 +14,10 @@ and the retry schedule.
 npm install @fungi.computer/bird-dog
 ```
 
-BirdDog is ESM-only. It depends on `@fungi.computer/watchdog`,
-`@fungi.computer/carrier` and `effect`, which npm installs for you. It does no
-I/O of its own, so it runs in Node, Cloudflare Workers or any runtime that can
-give it an outbox and a `post` function.
+BirdDog is ESM-only. It depends on `@fungi.computer/watchdog` and `effect`,
+which npm installs for you. It does no I/O of its own, so it runs in Node,
+Cloudflare Workers or any runtime that can stage a batch of mail in its existing
+delivery owner.
 
 Entrypoints:
 
@@ -41,13 +29,11 @@ Entrypoints:
 
 ## Quick start
 
-This sends work from a parent agent to a child agent, settles it, and delivers
-the reply. The outbox uses Carrier’s deterministic memory helper, and `post`
-prints the reply instead of sending it anywhere.
+This constructs a reply batch. The example prints it; a durable host stages the
+batch in its existing Carrier Post transaction.
 
 ```ts
 import { BirdDog, type BirdDogMail } from "@fungi.computer/bird-dog";
-import { createMemoryOutbox } from "@fungi.computer/carrier/testing";
 
 const parent = {
   kind: "agent",
@@ -61,13 +47,8 @@ const child = {
 } as const;
 
 const room = await BirdDog.make({
-  outbox: createMemoryOutbox(),
-  post: async (mail: BirdDogMail) => {
-    console.log(`to ${mail.to.agentId}:\n${mail.content}`);
-    return true; // the recipient accepted it
-  },
-  scheduleWake: async (at) => {
-    console.log(`wake me at ${at}`);
+  stage: async (mail: readonly BirdDogMail[]) => {
+    for (const reply of mail) console.log(reply.content);
   },
   now: () => Date.now(),
 });
@@ -94,16 +75,16 @@ const job = BirdDog.agentJob({
 const payload = BirdDog.decodeAgentJob(job);
 console.log(payload.work.commandFactId); // "command-1"
 
-// 3. When Watchdog settles the job, queue the replies, then deliver them.
+// 3. When Watchdog settles the job, stage the replies.
 await room.fanOut({
   job: { ...job, state: "settled", outcome: "completed" },
   content: "A test fixture was missing. Fixed it.",
 });
-await room.drainOutbox();
 ```
 
-In a real host, the settled job comes from Watchdog's `tick()` result and
-`drainOutbox()` runs from the wake you scheduled.
+In a real host, the settled job comes from Watchdog and `stage` commits the
+whole batch before the settlement cursor advances. Replaying a stable reply key
+retains the first staged letter, including its original timestamp.
 
 ## Core concepts
 
@@ -125,9 +106,8 @@ Watchdog's `transactional.enqueueAcceptedJob`. `BirdDog.decodeAgentJob(job)`
 parses the payload back on the executor side. Watchdog never reads it.
 
 **Fan-out.** `fanOut({ job, content, diagnostic? })` takes a settled job, the
-content owed to correspondents and the Session's terminal diagnostic. It writes
-one reply per `replyTo` address into the outbox, keyed
-`outbox:<mail key>:reply:<index>`, then schedules one wake for the earliest.
+content owed to correspondents and the Session's terminal diagnostic. It passes
+one reply per `replyTo` address to `stage`, keyed `<mail key>:reply:<index>`.
 Each reply's `from` is the mail's recipient, its `content` is your content
 verbatim (or, when it is empty,
 `The delegated work ended <outcome> without reply text.`, so a reply is always
@@ -155,31 +135,10 @@ The recipient's host owns authentication and presentation. It trusts the `reply`
 facts only after checking the reply against the mail it sent, then decides who
 authors the line and how its model sees it.
 
-**Draining.** `drainOutbox()` reads one page of up to 64 outbox rows and calls
-`post` for each due reply. `post` returns `true` when the recipient accepts the
-mail. A `false` or a throw schedules a retry. If more rows remain, BirdDog
-schedules an immediate wake and continues from the same place on the next drain.
-
-**Receipts.** A delivered reply's row is replaced by a compact completion
-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:
-
-- `outbox`: string rows with `put`, `read`, ordered `list(limit, afterKey?)` and
-  `delete`. Use the same key ordering for sorting and the exclusive `afterKey`
-  filter so paging cannot skip or repeat rows.
-- `post(mail)`: delivers one reply and reports acceptance.
-- `scheduleWake(at)`: arms a durable timer for `drainOutbox`.
-- `now()`: the current time in milliseconds.
+**Host ports.** `BirdDog.make` takes `stage(mail)` and `now()`. Staging is one
+batch operation so the host can commit all replies atomically. The host retains
+stable keys, prepared delivery facts and receipts through Carrier Post. Watchdog
+reserves attempts, resumes retries after reopen and reports the next wake.
 
 ## API reference
 
@@ -187,19 +146,19 @@ The generated reference is in [docs/api](docs/api/README.md).
 
 - `@fungi.computer/bird-dog`: `BirdDog` with `agentJob`, `decodeAgentJob` and
   `make`, plus the `BirdDogMail`, `BirdDogAgentReference`, `BirdDogAgentWork`,
-  `BirdDogAgentJobPayload`, `BirdDogReply`, `BirdDogOutbox`, `BirdDogOptions`,
+  `BirdDogAgentJobPayload`, `BirdDogReply`, `BirdDogOptions`,
   `BirdDogSettlement` and `BirdDogRuntime` types.
 - `@fungi.computer/bird-dog/effect`: `make`, `agentJobFromInput`,
-  `decodeAgentJob`, `settlementReplies`, `hasPendingDelivery`,
-  `boundedDiagnostic`, `BIRD_DOG_DIAGNOSTIC_MAX_LENGTH`, `BirdDogError`,
-  `EffectBirdDogOptions`, `BirdDogEffect` and the schemas
-  `BirdDogAgentReferenceSchema`, `BirdDogReplySchema`, `BirdDogMailSchema`,
-  `BirdDogAgentWorkSchema`, `BirdDogAgentJobPayloadSchema` and
-  `BirdDogAgentJobInputSchema`.
+  `decodeAgentJob`, `settlementReplies`, `boundedDiagnostic`,
+  `BIRD_DOG_DIAGNOSTIC_MAX_LENGTH`, `BirdDogError`, `EffectBirdDogOptions`,
+  `BirdDogEffect` and the schemas `BirdDogAgentReferenceSchema`,
+  `BirdDogReplySchema`, `BirdDogMailSchema`, `BirdDogAgentWorkSchema`,
+  `BirdDogAgentJobPayloadSchema` and `BirdDogAgentJobInputSchema`.
 
 ## Examples and checks
 
-The Effect entrypoint takes the same ports as Effect values:
+The Effect entrypoint takes the same ports as Effect values. Using `job` from
+the quick start, this prints the settlement reply batch:
 
 ```ts
 import * as Effect from "effect/Effect";
@@ -207,18 +166,19 @@ import { make } from "@fungi.computer/bird-dog/effect";
 
 const room = await Effect.runPromise(
   make({
-    outbox: {
-      put: () => Effect.void,
-      read: () => Effect.succeed(undefined),
-      list: () => Effect.succeed([]),
-      delete: () => Effect.void,
-    },
-    post: () => Effect.succeed(true),
-    scheduleWake: () => Effect.void,
+    stage: (mail) =>
+      Effect.sync(() => {
+        for (const reply of mail) console.log(reply.content);
+      }),
     now: () => Date.now(),
   }),
 );
-await Effect.runPromise(room.drainOutbox());
+await Effect.runPromise(
+  room.fanOut({
+    job: { ...job, state: "settled", outcome: "completed" },
+    content: "A test fixture was missing. Fixed it.",
+  }),
+);
 ```
 
 Use the schemas to parse mail that arrives from outside your process:
@@ -230,11 +190,9 @@ import { BirdDogMailSchema } from "@fungi.computer/bird-dog/effect";
 const mail = Schema.decodeUnknownSync(BirdDogMailSchema)(JSON.parse(body));
 ```
 
-The package tests cover job translation, payload decoding, replayed settlement
-after a restart, explicit cancellation replies, exact failure outcomes with
-bounded and redacted diagnostics, retry re-arming after reopen, bounded paging
-past full pages, retry exhaustion, receipt walks, wake failure after fan-out,
-and parity between the Promise and Effect schemas. From the package directory:
+The package tests cover job translation, typed settlement replies, bounded and
+redacted diagnostics, and batch staging failures. Carrier and Local consumer
+tests cover durable retries, receipt loss and physical reopen.
 
 ```sh
 pnpm test
@@ -242,26 +200,11 @@ pnpm test
 
 ## Limits and errors
 
-- **Retry schedule.** A failed delivery retries after 2 seconds, doubling each
-  time, capped at 5 minutes. After 20 attempts the reply is exhausted. Its row
-  stays in the outbox, and BirdDog stops posting it and stops waking for it.
-- **At-least-once.** If the recipient accepts a reply but recording the receipt
-  fails, the retry uses the same mail key. Recipients must admit a repeated key
-  idempotently.
-- **Malformed rows.** A row that does not parse is deleted during a drain. A
-  malformed row met during fan-out fails that fan-out.
-- **Fan-out writes first.** Every reply is persisted before the wake is
-  scheduled. If `scheduleWake` fails, `fanOut` rejects but the replies are
-  already in the outbox, so replaying the settlement is safe.
-- **Invalid input.** `agentJob` and `decodeAgentJob` throw a schema error on
-  input that does not match. `fanOut` rejects with
-  `BirdDogError("invalid agent job payload")` for a job whose payload is not
-  BirdDog's.
-- **Host failures.** The Promise mail room wraps a failing port in a
-  `BirdDogError` and keeps your original error as its `cause`. The messages are
-  `outbox read failed`, `outbox write failed`, `outbox delete failed`,
-  `mail transport failed` and `wake scheduling failed`. A `post` that throws
-  during a drain is logged and retried, not rethrown.
+`agentJob` and `decodeAgentJob` reject invalid input using the maintained
+schema. A failing Promise staging port becomes
+`BirdDogError("mail staging failed")` with the original error as its `cause`.
+The caller must retain the settlement cursor until staging succeeds. Delivery
+remains at least once: receivers must admit a repeated mail key idempotently.
 
 ## Contribute and license
 

package/dist/effect.d.ts

@@ -158,6 +158,7 @@ export declare const BirdDogAgentWorkSchema: Schema.Struct<{
     readonly commandFactId: Schema.String;
     readonly recovery: Schema.optional<Schema.Struct<{
         readonly maxRecoveries: Schema.Int;
+        readonly windowMs: Schema.optionalKey<Schema.Int>;
     }>>;
 }>;
 /** Parser for the payload that Watchdog stores without interpretation. */
@@ -237,6 +238,7 @@ export declare const BirdDogAgentJobInputSchema: Schema.Struct<{
         readonly commandFactId: Schema.String;
         readonly recovery: Schema.optional<Schema.Struct<{
             readonly maxRecoveries: Schema.Int;
+            readonly windowMs: Schema.optionalKey<Schema.Int>;
         }>>;
     }>;
     readonly delivery: Schema.Literals<readonly ["steer", "followUp"]>;
@@ -309,38 +311,19 @@ export declare class BirdDogError extends Error {
     readonly _tag: "BirdDogError";
     constructor(message: string, options?: ErrorOptions);
 }
-/** Effect host ports for the durable mail room. */
+/** Durable staging belongs to the host's existing Carrier Post transaction. */
 export type EffectBirdDogOptions = Readonly<{
-    outbox: Readonly<{
-        /** Store one encoded mail row under its durable key. */
-        put: (key: string, value: string) => Effect.Effect<void, BirdDogError>;
-        /** Read one encoded mail row, if it exists. */
-        read: (key: string) => Effect.Effect<string | undefined, BirdDogError>;
-        /** Read an ordered page of encoded mail rows. */
-        list: (limit: number, afterKey?: string) => Effect.Effect<readonly Readonly<{
-            key: string;
-            value: string;
-        }>[], BirdDogError>;
-        /** Remove an invalid encoded row; completed deliveries retain receipts. */
-        delete: (key: string) => Effect.Effect<void, BirdDogError>;
-    }>;
-    /** Deliver one reply mail and report whether it was accepted. */
-    post: (mail: BirdDogMail) => Effect.Effect<boolean, BirdDogError>;
-    /** Arrange a future wake for pending delivery work. */
-    scheduleWake: (at: number) => Effect.Effect<void, BirdDogError>;
-    /** Return the host's current wall-clock time in milliseconds. */
+    /** Commit the complete reply batch through the host delivery owner. */
+    stage: (mail: readonly BirdDogMail[]) => Effect.Effect<void, BirdDogError>;
+    /** Current time used when constructing a new reply. */
     now: () => number;
 }>;
-/** Effect-native durable reply delivery. */
+/** Agent reply construction and durable staging; Watchdog owns delivery progress. */
 export type BirdDogEffect = Readonly<{
-    /** Queue replies owed by a settled agent job. */
+    /** Stage all reply letters for one settled command as one batch. */
     fanOut: (settlement: BirdDogSettlement) => Effect.Effect<void, BirdDogError>;
-    /** Durably queue one authored mail item in this Agent's existing outbox. */
+    /** Stage a host-authored letter through the same durable delivery owner. */
     postMail?: ((mail: BirdDogMail) => Effect.Effect<void, BirdDogError>) | undefined;
-    /** 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;
@@ -362,10 +345,5 @@ export declare const decodeAgentJob: (job: WatchdogStoredJob) => BirdDogAgentJob
 export declare function settlementReplies(settlement: BirdDogSettlement, createdAt: number): readonly BirdDogMail[];
 /** Build the recipient's one stable acceptance notice for one original mail. */
 export declare function acceptedNotice(mail: BirdDogMail, sessionId: string, commandId: string, createdAt: number): 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. */
+/** Construct BirdDog's reply semantics over the existing durable staging owner. */
 export declare const make: (options: EffectBirdDogOptions) => Effect.Effect<BirdDogEffect>;

package/dist/effect.js

@@ -1,6 +1,5 @@
 import * as Effect from "effect/Effect";
 import * as Schema from "effect/Schema";
-import { makePostOutbox, postOutboxPending, } from "@fungi.computer/carrier/post";
 const Identifier = Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(256));
 /** The maximum UTF-8 size of one mail body. */
 export const BIRD_DOG_MAIL_CONTENT_MAX_BYTES = 256 * 1024;
@@ -147,6 +146,7 @@ export const BirdDogAgentWorkSchema = Schema.Struct({
     commandFactId: Identifier,
     recovery: Schema.optional(Schema.Struct({
         maxRecoveries: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),
+        windowMs: Schema.optionalKey(Schema.Int.check(Schema.isGreaterThan(0))),
     })),
 });
 /** Parser for the payload that Watchdog stores without interpretation. */
@@ -266,49 +266,13 @@ export function acceptedNotice(mail, sessionId, commandId, 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({
-        message: BirdDogMailSchema,
-        key: (mail) => `outbox:${mail.key}`,
-        outbox: options.outbox,
-        deliver: options.post,
-        scheduleWake: options.scheduleWake,
-        now: options.now,
-        invalidRow: () => new BirdDogError("invalid outbox row"),
-        encodingFailed: () => new BirdDogError("could not encode outbox row"),
-    });
-    const fanOut = (settlement) => Effect.gen(function* () {
-        const createdAt = options.now();
-        const replies = yield* Effect.try({
-            try: () => settlementReplies(settlement, createdAt),
-            catch: () => new BirdDogError("invalid agent job payload"),
-        });
-        let wake;
-        for (const reply of replies) {
-            const hint = yield* post.enqueue(reply, createdAt);
-            if (hint !== undefined)
-                wake = wake === undefined ? hint : Math.min(wake, hint);
-        }
-        if (wake !== undefined)
-            yield* options.scheduleWake(wake);
-    });
-    const postMail = (mail) => Effect.gen(function* () {
-        const createdAt = options.now();
-        const hint = yield* post.enqueue(mail, createdAt);
-        if (hint !== undefined)
-            yield* options.scheduleWake(hint);
-        return;
-    });
-    return Effect.succeed({
-        fanOut,
-        postMail,
-        drainOutbox: post.drain,
-        nextWakeAt: post.nextWakeAt,
-    });
-};
+/** Construct BirdDog's reply semantics over the existing durable staging owner. */
+export const make = (options) => Effect.succeed({
+    /** Stage the complete settlement reply batch. */
+    fanOut: (settlement) => Effect.try({
+        try: () => settlementReplies(settlement, options.now()),
+        catch: (cause) => new BirdDogError("invalid agent job payload", { cause }),
+    }).pipe(Effect.flatMap(options.stage)),
+    /** Stage one host-authored letter. */
+    postMail: (mail) => options.stage([mail]),
+});

package/dist/index.d.ts

@@ -87,6 +87,7 @@ export type BirdDogAgentWork = Readonly<{
     commandFactId: string;
     recovery?: Readonly<{
         maxRecoveries: number;
+        windowMs?: number;
     }> | undefined;
 }>;
 /** Typed payload whose meaning belongs to BirdDog, never Watchdog. */
@@ -103,29 +104,11 @@ export type BirdDogAgentJobInput = Readonly<{
     delivery: "steer" | "followUp";
     mail?: BirdDogMail | undefined;
 }>;
-/** String-backed durable outbox owned by the BirdDog host. */
-export type BirdDogOutbox = Readonly<{
-    /** Store one encoded mail row under its durable key. */
-    put: (key: string, value: string) => Promise<void>;
-    /** Read one encoded mail row, if it exists. */
-    read: (key: string) => Promise<string | undefined>;
-    /** Read an ordered page of encoded mail rows. */
-    list: (limit: number, afterKey?: string) => Promise<readonly Readonly<{
-        key: string;
-        value: string;
-    }>[]>;
-    /** Remove an invalid encoded row; completed deliveries retain receipts. */
-    delete: (key: string) => Promise<void>;
-}>;
-/** Host ports for BirdDog's durable mail delivery. */
+/** Host ports for reply staging in its existing Carrier Post owner. */
 export type BirdDogOptions = Readonly<{
-    /** Durable store for pending reply mail. */
-    outbox: BirdDogOutbox;
-    /** Deliver one reply mail and report whether it was accepted. */
-    post: (mail: BirdDogMail) => Promise<boolean>;
-    /** Arrange a future wake for pending delivery work. */
-    scheduleWake: (at: number) => Promise<void>;
-    /** Return the host's current wall-clock time in milliseconds. */
+    /** Commit the complete reply batch through the host delivery owner. */
+    stage: (mail: readonly BirdDogMail[]) => Promise<void>;
+    /** Current time used when constructing a new reply. */
     now: () => number;
 }>;
 /**
@@ -172,8 +155,6 @@ export type BirdDogWaitingItem = Readonly<{
 export type BirdDogRuntime = Readonly<{
     /** Queue replies owed by a settled agent job. */
     fanOut: (settlement: BirdDogSettlement) => Promise<void>;
-    /** Deliver due replies and schedule any required retry wake. */
-    drainOutbox: () => Promise<void>;
 }>;
 /** BirdDog's small synchronous translation interface for owner transactions. */
 export type BirdDogApi = Readonly<{

package/dist/internal/promise-mail-room.js

@@ -11,41 +11,14 @@ const runPromise = (effect) => Effect.runPromiseExit(effect).then((exit) => {
 });
 /** Lift Promise host ports once into BirdDog's Effect-owned mail room. */
 export const createPromiseBirdDog = async (options) => {
-    const readOutbox = options.outbox.read;
-    const readPort = {
-        read: (key) => Effect.tryPromise({
-            try: () => readOutbox(key),
-            catch: (cause) => new BirdDogError("outbox read failed", { cause }),
-        }),
-    };
     const runtime = await Effect.runPromise(make({
-        outbox: {
-            ...readPort,
-            put: (key, value) => Effect.tryPromise({
-                try: () => options.outbox.put(key, value),
-                catch: (cause) => new BirdDogError("outbox write failed", { cause }),
-            }),
-            list: (limit, afterKey) => Effect.tryPromise({
-                try: () => options.outbox.list(limit, afterKey),
-                catch: (cause) => new BirdDogError("outbox read failed", { cause }),
-            }),
-            delete: (key) => Effect.tryPromise({
-                try: () => options.outbox.delete(key),
-                catch: (cause) => new BirdDogError("outbox delete failed", { cause }),
-            }),
-        },
-        post: (mail) => Effect.tryPromise({
-            try: () => options.post(mail),
-            catch: (cause) => new BirdDogError("mail transport failed", { cause }),
-        }),
-        scheduleWake: (at) => Effect.tryPromise({
-            try: () => options.scheduleWake(at),
-            catch: (cause) => new BirdDogError("wake scheduling failed", { cause }),
+        stage: (mail) => Effect.tryPromise({
+            try: () => options.stage(mail),
+            catch: (cause) => new BirdDogError("mail staging failed", { cause }),
         }),
         now: options.now,
     }));
     return Object.freeze({
         fanOut: (settlement) => runPromise(runtime.fanOut(settlement)),
-        drainOutbox: () => runPromise(runtime.drainOutbox()),
     });
 };

package/docs/api/effect.md

@@ -59,28 +59,12 @@ Stable discriminator for BirdDog-owned effect failures.
 
 ```ts
 type EffectBirdDogOptions = Readonly<{
-  outbox: Readonly<{
-    put: (key, value) => Effect.Effect<void, BirdDogError>;
-    read: (key) => Effect.Effect<string | undefined, BirdDogError>;
-    list: (
-      limit,
-      afterKey?,
-    ) => Effect.Effect<
-      readonly Readonly<{
-        key: string;
-        value: string;
-      }>[],
-      BirdDogError
-    >;
-    delete: (key) => Effect.Effect<void, BirdDogError>;
-  }>;
-  post: (mail) => Effect.Effect<boolean, BirdDogError>;
-  scheduleWake: (at) => Effect.Effect<void, BirdDogError>;
+  stage: (mail) => Effect.Effect<void, BirdDogError>;
   now: () => number;
 }>;
 ```
 
-Effect host ports for the durable mail room.
+Durable staging belongs to the host's existing Carrier Post transaction.
 
 ---
 
@@ -90,12 +74,10 @@ Effect host ports for the durable mail room.
 type BirdDogEffect = Readonly<{
   fanOut: (settlement) => Effect.Effect<void, BirdDogError>;
   postMail?: (mail) => Effect.Effect<void, BirdDogError>;
-  drainOutbox: () => Effect.Effect<void, BirdDogError>;
-  nextWakeAt: () => Effect.Effect<number | undefined, BirdDogError>;
 }>;
 ```
 
-Effect-native durable reply delivery.
+Agent reply construction and durable staging; Watchdog owns delivery progress.
 
 ## Variables
 
@@ -376,6 +358,7 @@ const BirdDogAgentWorkSchema: Struct<{
   recovery: optional<
     Struct<{
       maxRecoveries: Int;
+      windowMs: optionalKey<Int>;
     }>
   >;
 }>;
@@ -455,6 +438,7 @@ const BirdDogAgentJobInputSchema: Struct<{
      commandFactId: String;
      recovery: optional<Struct<{
         maxRecoveries: Int;
+        windowMs: optionalKey<Int>;
      }>>;
   }>;
   delivery: Literals<readonly ["steer", "followUp"]>;
@@ -560,8 +544,10 @@ Validate and translate agent work into Watchdog's opaque job grammar.
 | `lane`                   | `string`   |
 | `priority`               | `number`   |
 | `payload`                | `unknown`  |
+| `notBefore?`             | `number`   |
 | `recovery?`              | `object`   |
 | `recovery.maxRecoveries` | `number`   |
+| `recovery.windowMs?`     | `number`   |
 
 ---
 
@@ -575,9 +561,9 @@ Decode the opaque payload at BirdDog's side of the Watchdog seam.
 
 #### Parameters
 
-| Parameter | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `job`     | \| \{ `state`: `"queued"`; `jobId`: `string`; `queue`: `string`; `lane`: `string`; `priority`: `number`; `payload`: `unknown`; `recovery?`: \{ `maxRecoveries`: `number`; \}; \} \| \{ `state`: `"running"`; `jobId`: `string`; `queue`: `string`; `lane`: `string`; `priority`: `number`; `payload`: `unknown`; `recovery?`: \{ `maxRecoveries`: `number`; \}; \} \| \{ `state`: `"settled"`; `outcome`: `"failed"` \| `"completed"` \| `"interrupted"` \| `"cancelled"` \| `"outcome_unknown"`; `failureReason?`: `string`; `jobId`: `string`; `queue`: `string`; `lane`: `string`; `priority`: `number`; `payload`: `unknown`; `recovery?`: \{ `maxRecoveries`: `number`; \}; \} |
+| Parameter | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `job`     | \| \{ `state`: `"queued"`; `jobId`: `string`; `queue`: `string`; `lane`: `string`; `priority`: `number`; `payload`: `unknown`; `notBefore?`: `number`; `recovery?`: \{ `maxRecoveries`: `number`; `windowMs?`: `number`; \}; \} \| \{ `state`: `"running"`; `jobId`: `string`; `queue`: `string`; `lane`: `string`; `priority`: `number`; `payload`: `unknown`; `notBefore?`: `number`; `recovery?`: \{ `maxRecoveries`: `number`; `windowMs?`: `number`; \}; \} \| \{ `state`: `"completing"`; `outcome`: `"failed"` \| `"completed"` \| `"interrupted"` \| `"cancelled"` \| `"outcome_unknown"`; `failureReason?`: `string`; `jobId`: `string`; `queue`: `string`; `lane`: `string`; `priority`: `number`; `payload`: `unknown`; `notBefore?`: `number`; `recovery?`: \{ `maxRecoveries`: `number`; `windowMs?`: `number`; \}; \} \| \{ `state`: `"settled"`; `outcome`: `"failed"` \| `"completed"` \| `"interrupted"` \| `"cancelled"` \| `"outcome_unknown"`; `failureReason?`: `string`; `jobId`: `string`; `queue`: `string`; `lane`: `string`; `priority`: `number`; `payload`: `unknown`; `notBefore?`: `number`; `recovery?`: \{ `maxRecoveries`: `number`; `windowMs?`: `number`; \}; \} |
 
 #### Returns
 
@@ -639,27 +625,6 @@ Build the recipient's one stable acceptance notice for one original mail.
 
 ---
 
-### 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
@@ -667,13 +632,11 @@ function make(options): Effect<
   Readonly<{
     fanOut: (settlement) => Effect<void, BirdDogError>;
     postMail?: (mail) => Effect<void, BirdDogError>;
-    drainOutbox: () => Effect<void, BirdDogError>;
-    nextWakeAt: () => Effect<number | undefined, BirdDogError>;
   }>
 >;
 ```
 
-Construct BirdDog's Effect-native mail room over Post's shared outbox.
+Construct BirdDog's reply semantics over the existing durable staging owner.
 
 #### Parameters
 
@@ -685,6 +648,4 @@ Construct BirdDog's Effect-native mail room over Post's shared outbox.
 
 `Effect`\<`Readonly`\<\{ `fanOut`: (`settlement`) => `Effect`\<`void`,
 [`BirdDogError`](#birddogerror)\>; `postMail?`: (`mail`) => `Effect`\<`void`,
-[`BirdDogError`](#birddogerror)\>; `drainOutbox`: () => `Effect`\<`void`,
-[`BirdDogError`](#birddogerror)\>; `nextWakeAt`: () => `Effect`\<`number` \|
-`undefined`, [`BirdDogError`](#birddogerror)\>; \}\>\>
+[`BirdDogError`](#birddogerror)\>; \}\>\>

package/docs/api/index.md

@@ -155,6 +155,7 @@ type BirdDogAgentWork = Readonly<{
   commandFactId: string;
   recovery?: Readonly<{
     maxRecoveries: number;
+    windowMs?: number;
   }>;
 }>;
 ```
@@ -193,41 +194,16 @@ Input for projecting accepted agent work into Watchdog's generic grammar.
 
 ---
 
-### BirdDogOutbox
-
-```ts
-type BirdDogOutbox = 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-backed durable outbox owned by the BirdDog host.
-
----
-
 ### BirdDogOptions
 
 ```ts
 type BirdDogOptions = Readonly<{
-  outbox: BirdDogOutbox;
-  post: (mail) => Promise<boolean>;
-  scheduleWake: (at) => Promise<void>;
+  stage: (mail) => Promise<void>;
   now: () => number;
 }>;
 ```
 
-Host ports for BirdDog's durable mail delivery.
+Host ports for reply staging in its existing Carrier Post owner.
 
 ---
 
@@ -282,7 +258,6 @@ One open item named by a reply as waiting on its recipient.
 ```ts
 type BirdDogRuntime = Readonly<{
   fanOut: (settlement) => Promise<void>;
-  drainOutbox: () => Promise<void>;
 }>;
 ```
 

package/package.json

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