API reference

effect

Import

import * as api from "@fungi.computer/bird-dog/effect";

Exports

Kind	Export	Description
class	BirdDogError	BirdDog could not complete one owned store or transport operation.
type alias	EffectBirdDogOptions	Effect host ports for the durable mail room.
type alias	BirdDogEffect	Effect-native durable reply delivery.
constant	BIRD_DOG_MAIL_CONTENT_MAX_BYTES	The maximum UTF-8 size of one mail body.
constant	BirdDogAgentReferenceSchema	Parser for an ordinary agent Session address.
constant	BirdDogAgentRecipientReferenceSchema	An addressed Agent may create its first Session when accepting this mail.
constant	BirdDogSystemIdentitySchema	The Hub’s stable system identity for a terminal offline disposition.
constant	BIRD_DOG_DIAGNOSTIC_MAX_LENGTH	The most characters a reply’s failure diagnostic may carry.
constant	BIRD_DOG_WAITING_MAX_ITEMS	The most open items one reply names as waiting on its recipient.
constant	BirdDogWaitingItemSchema	One open item of the replying Session that waits on this reply’s recipient. BirdDog carries the three bounded fields; the replying host owns their meaning and the recipient host owns every decision about them.
constant	SettledBirdDogReplySchema	Parser for the settlement facts a reply carries beside its content: the replying Session’s command, its exact Watchdog outcome, for work that did not complete the Session’s bounded terminal diagnostic and, when the replying host names any, the open items now waiting on the recipient.
constant	BirdDogUndeliverableReasonSchema	A terminal delivery failure, correlated by the original mail key only.
constant	UndeliverableBirdDogReplySchema	Parser for a terminal delivery failure reply.
constant	AcceptedBirdDogReplySchema	Recipient acceptance, before the command has settled.
constant	BirdDogReplySchema	Parser for any reply: settled, accepted or undeliverable.
constant	BirdDogMailSchema	Parser for addressed Agent mail, from an Agent or from the Hub system.
constant	BirdDogAgentWorkSchema	Parser for accepted Session work.
constant	BirdDogAgentJobPayloadSchema	Parser for the payload that Watchdog stores without interpretation.
constant	BirdDogAgentJobInputSchema	Parser for accepted work entering BirdDog’s transactional projection.
function	boundedDiagnostic()	One secret-safe line of at most `BIRD_DOG_DIAGNOSTIC_MAX_LENGTH` characters from a Session’s terminal diagnostic, or nothing when it is blank. Control characters and line breaks become single spaces, so the text cannot shape the reply around it, and credential-shaped values are masked before the line is cut, so a cut never exposes part of one.
function	agentJobFromInput()	Validate and translate agent work into Watchdog’s opaque job grammar.
function	decodeAgentJob()	Decode the opaque payload at BirdDog’s side of the Watchdog seam.
function	settlementReplies()	Build the replies owed by one settlement for a host-owned Post transport. Each reply carries the settled content verbatim (or, when there is none, one sentence naming the outcome and its diagnostic, so the reply is always admissible text) and its settlement facts as typed fields; the recipient’s host authenticates them and decides how they are presented. A reply never carries the settled work’s host metadata.
function	acceptedNotice()	Build the recipient’s one stable acceptance notice for one original mail.
function	hasPendingDelivery()	Whether this mail room’s outbox still owes any reply a delivery attempt. Delivered receipts and exhausted dead letters stay but owe nothing.
function	make()	Construct BirdDog’s Effect-native mail room over Post’s shared outbox.

BirdDogErrorclass

BirdDog could not complete one owned store or transport operation.

Extends

Error

Constructors

Constructor

new BirdDogError(message, options?): BirdDogError;

Parameters

Parameter	Type
`message`	`string`
`options?`	`ErrorOptions`

Returns

BirdDogError

Overrides

Error.constructor;

Properties

_tag

readonly _tag: "BirdDogError";

Stable discriminator for BirdDog-owned effect failures.

EffectBirdDogOptionstype alias

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>;
  now: () => number;
}>;

Effect host ports for the durable mail room.

BirdDogEffecttype alias

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.

BIRD_DOG_MAIL_CONTENT_MAX_BYTESconstant

const BIRD_DOG_MAIL_CONTENT_MAX_BYTES: number;

The maximum UTF-8 size of one mail body.

BirdDogAgentReferenceSchemaconstant

const BirdDogAgentReferenceSchema: Struct<{
  kind: Literal<"agent">;
  agentId: String;
  sessionId: String;
}>;

Parser for an ordinary agent Session address.

BirdDogAgentRecipientReferenceSchemaconstant

const BirdDogAgentRecipientReferenceSchema: Struct<{
  kind: Literal<"agent">;
  agentId: String;
  sessionId: optionalKey<String>;
}>;

An addressed Agent may create its first Session when accepting this mail.

BirdDogSystemIdentitySchemaconstant

const BirdDogSystemIdentitySchema: Struct<{
  kind: Literal<"system">;
  systemId: Literal<"hub">;
}>;

The Hub’s stable system identity for a terminal offline disposition.

BIRD_DOG_DIAGNOSTIC_MAX_LENGTHconstant

const BIRD_DOG_DIAGNOSTIC_MAX_LENGTH: 200 = 200;

The most characters a reply’s failure diagnostic may carry.

BIRD_DOG_WAITING_MAX_ITEMSconstant

const BIRD_DOG_WAITING_MAX_ITEMS: 8 = 8;

The most open items one reply names as waiting on its recipient.

BirdDogWaitingItemSchemaconstant

const BirdDogWaitingItemSchema: Struct<{
  itemId: String;
  kind: String;
  summary: String;
}>;

One open item of the replying Session that waits on this reply’s recipient. BirdDog carries the three bounded fields; the replying host owns their meaning and the recipient host owns every decision about them.

SettledBirdDogReplySchemaconstant

const SettledBirdDogReplySchema: Struct<{
  commandId: String;
  outcome: Literals<
    readonly [
      "completed",
      "failed",
      "interrupted",
      "cancelled",
      "outcome_unknown",
    ]
  >;
  diagnostic: optionalKey<String>;
  waitingOnYou: optionalKey<
    $Array<
      Struct<{
        itemId: String;
        kind: String;
        summary: String;
      }>
    >
  >;
}>;

Parser for the settlement facts a reply carries beside its content: the replying Session’s command, its exact Watchdog outcome, for work that did not complete the Session’s bounded terminal diagnostic and, when the replying host names any, the open items now waiting on the recipient.

BirdDogUndeliverableReasonSchemaconstant

const BirdDogUndeliverableReasonSchema: Literals<
  readonly ["recipient_offline", "recipient_left"]
>;

A terminal delivery failure, correlated by the original mail key only.

UndeliverableBirdDogReplySchemaconstant

const UndeliverableBirdDogReplySchema: Struct<{
  outcome: Literal<"undeliverable">;
  reason: Literals<readonly ["recipient_offline", "recipient_left"]>;
}>;

Parser for a terminal delivery failure reply.

AcceptedBirdDogReplySchemaconstant

const AcceptedBirdDogReplySchema: Struct<{
  outcome: Literal<"accepted">;
  commandId: String;
}>;

Recipient acceptance, before the command has settled.

BirdDogReplySchemaconstant

const BirdDogReplySchema: Union<
  readonly [
    Struct<{
      commandId: String;
      outcome: Literals<
        readonly [
          "completed",
          "failed",
          "interrupted",
          "cancelled",
          "outcome_unknown",
        ]
      >;
      diagnostic: optionalKey<String>;
      waitingOnYou: optionalKey<
        $Array<
          Struct<{
            itemId: String;
            kind: String;
            summary: String;
          }>
        >
      >;
    }>,
    Struct<{
      outcome: Literal<"undeliverable">;
      reason: Literals<readonly ["recipient_offline", "recipient_left"]>;
    }>,
    Struct<{
      outcome: Literal<"accepted">;
      commandId: String;
    }>,
  ]
>;

Parser for any reply: settled, accepted or undeliverable.

BirdDogMailSchemaconstant

const BirdDogMailSchema: Union<readonly [Struct<{
  key: String;
  to: Struct<{
     kind: Literal<"agent">;
     agentId: String;
     sessionId: optionalKey<String>;
  }>;
  replyTo: $Array<Struct<{
     kind: Literal<"agent">;
     agentId: String;
     sessionId: String;
  }>>;
  content: String;
  createdAt: Number;
  meta: optionalKey<Codec<Json, Json, never, never>>;
  from: Struct<{
     kind: Literal<"agent">;
     agentId: String;
     sessionId: String;
  }>;
  reply: optionalKey<Union<readonly [Struct<{
     commandId: String;
     outcome: Literals<readonly [..., ..., ..., ..., ...]>;
     diagnostic: optionalKey<String>;
     waitingOnYou: optionalKey<$Array<...>>;
   }>, Struct<{
     outcome: Literal<"accepted">;
     commandId: String;
   }>, Struct<{
     outcome: Literal<"undeliverable">;
     reason: Literal<"recipient_left">;
  }>]>>;
}>, Struct<{
  key: String;
  to: Struct<{
     kind: Literal<"agent">;
     agentId: String;
     sessionId: optionalKey<String>;
  }>;
  replyTo: $Array<Struct<{
     kind: Literal<"agent">;
     agentId: String;
     sessionId: String;
  }>>;
  content: String;
  createdAt: Number;
  meta: optionalKey<Codec<Json, Json, never, never>>;
  from: Struct<{
     kind: Literal<"system">;
     systemId: Literal<"hub">;
  }>;
  reply: Struct<{
     outcome: Literal<"undeliverable">;
     reason: Literal<"recipient_offline">;
  }>;
}>]>;

Parser for addressed Agent mail, from an Agent or from the Hub system.

BirdDogAgentWorkSchemaconstant

const BirdDogAgentWorkSchema: Struct<{
  jobId: String;
  sessionId: String;
  commandFactId: String;
  recovery: optional<
    Struct<{
      maxRecoveries: Int;
    }>
  >;
}>;

Parser for accepted Session work.

BirdDogAgentJobPayloadSchemaconstant

const BirdDogAgentJobPayloadSchema: Struct<{
  work: Struct<{
     sessionId: String;
     commandFactId: String;
  }>;
  mail: optional<Union<readonly [Struct<{
     key: String;
     to: Struct<{
        kind: Literal<"agent">;
        agentId: String;
        sessionId: optionalKey<String>;
     }>;
     replyTo: $Array<Struct<{
        kind: Literal<...>;
        agentId: String;
        sessionId: String;
     }>>;
     content: String;
     createdAt: Number;
     meta: optionalKey<Codec<Json, Json, never, never>>;
     from: Struct<{
        kind: Literal<"agent">;
        agentId: String;
        sessionId: String;
     }>;
     reply: optionalKey<Union<readonly [Struct<...>, Struct<...>, Struct<...>]>>;
   }>, Struct<{
     key: String;
     to: Struct<{
        kind: Literal<"agent">;
        agentId: String;
        sessionId: optionalKey<String>;
     }>;
     replyTo: $Array<Struct<{
        kind: Literal<...>;
        agentId: String;
        sessionId: String;
     }>>;
     content: String;
     createdAt: Number;
     meta: optionalKey<Codec<Json, Json, never, never>>;
     from: Struct<{
        kind: Literal<"system">;
        systemId: Literal<"hub">;
     }>;
     reply: Struct<{
        outcome: Literal<"undeliverable">;
        reason: Literal<"recipient_offline">;
     }>;
  }>]>>;
}>;

Parser for the payload that Watchdog stores without interpretation.

BirdDogAgentJobInputSchemaconstant

const BirdDogAgentJobInputSchema: Struct<{
  work: Struct<{
     jobId: String;
     sessionId: String;
     commandFactId: String;
     recovery: optional<Struct<{
        maxRecoveries: Int;
     }>>;
  }>;
  mail: optional<Union<readonly [Struct<{
     key: String;
     to: Struct<{
        kind: Literal<"agent">;
        agentId: String;
        sessionId: optionalKey<String>;
     }>;
     replyTo: $Array<Struct<{
        kind: Literal<...>;
        agentId: String;
        sessionId: String;
     }>>;
     content: String;
     createdAt: Number;
     meta: optionalKey<Codec<Json, Json, never, never>>;
     from: Struct<{
        kind: Literal<"agent">;
        agentId: String;
        sessionId: String;
     }>;
     reply: optionalKey<Union<readonly [Struct<...>, Struct<...>, Struct<...>]>>;
   }>, Struct<{
     key: String;
     to: Struct<{
        kind: Literal<"agent">;
        agentId: String;
        sessionId: optionalKey<String>;
     }>;
     replyTo: $Array<Struct<{
        kind: Literal<...>;
        agentId: String;
        sessionId: String;
     }>>;
     content: String;
     createdAt: Number;
     meta: optionalKey<Codec<Json, Json, never, never>>;
     from: Struct<{
        kind: Literal<"system">;
        systemId: Literal<"hub">;
     }>;
     reply: Struct<{
        outcome: Literal<"undeliverable">;
        reason: Literal<"recipient_offline">;
     }>;
  }>]>>;
}>;

Parser for accepted work entering BirdDog’s transactional projection.

boundedDiagnostic()function

function boundedDiagnostic(text): string | undefined;

One secret-safe line of at most BIRD_DOG_DIAGNOSTIC_MAX_LENGTH characters from a Session’s terminal diagnostic, or nothing when it is blank. Control characters and line breaks become single spaces, so the text cannot shape the reply around it, and credential-shaped values are masked before the line is cut, so a cut never exposes part of one.

Parameters

Parameter	Type
`text`	`string`

Returns

string | undefined

agentJobFromInput()function

function agentJobFromInput(input): object;

Validate and translate agent work into Watchdog’s opaque job grammar.

Parameters

Parameter	Type
`input`	`BirdDogAgentJobInput`

Returns

object

Name	Type
`state`	`"queued"`
`jobId`	`string`
`queue`	`string`
`lane`	`string`
`priority`	`number`
`payload`	`unknown`
`recovery?`	`object`
`recovery.maxRecoveries`	`number`

decodeAgentJob()function

function decodeAgentJob(job): BirdDogAgentJobPayload;

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; 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; }; }

Returns

BirdDogAgentJobPayload

settlementReplies()function

function settlementReplies(settlement, createdAt): readonly BirdDogMail[];

Build the replies owed by one settlement for a host-owned Post transport. Each reply carries the settled content verbatim (or, when there is none, one sentence naming the outcome and its diagnostic, so the reply is always admissible text) and its settlement facts as typed fields; the recipient’s host authenticates them and decides how they are presented. A reply never carries the settled work’s host metadata.

Work a delegator’s mail admitted replies to that mail under its :reply: key. Any other settled work, whatever started its turn, is a report to the Session’s delegator of record, when the host names one (it does so once the Session is idle), under the delegator mail’s :report: key.

Parameters

Parameter	Type
`settlement`	`BirdDogSettlement`
`createdAt`	`number`

Returns

readonly BirdDogMail[]

acceptedNotice()function

function acceptedNotice(mail, sessionId, commandId, createdAt): BirdDogMail;

Build the recipient’s one stable acceptance notice for one original mail.

Parameters

Parameter	Type
`mail`	`BirdDogMail`
`sessionId`	`string`
`commandId`	`string`
`createdAt`	`number`

Returns

BirdDogMail

hasPendingDelivery()function

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["outbox"], "list">`

Returns

Effect<boolean, BirdDogError>

make()function

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.

Parameters

Parameter	Type
`options`	`EffectBirdDogOptions`

Returns

Effect<Readonly<{ fanOut: (settlement) => Effect<void, BirdDogError>; postMail?: (mail) => Effect<void, BirdDogError>; drainOutbox: () => Effect<void, BirdDogError>; nextWakeAt: () => Effect<number | undefined, BirdDogError>; }>>

effect

Import

Exports

BirdDogErrorCclass

Extends

Constructors

Constructor

Parameters

Returns

Overrides

Properties

_tag

EffectBirdDogOptionsTtype alias

BirdDogEffectTtype alias

BIRD_DOG_MAIL_CONTENT_MAX_BYTESconstconstant

BirdDogAgentReferenceSchemaconstconstant

BirdDogAgentRecipientReferenceSchemaconstconstant

BirdDogSystemIdentitySchemaconstconstant

BIRD_DOG_DIAGNOSTIC_MAX_LENGTHconstconstant

BIRD_DOG_WAITING_MAX_ITEMSconstconstant

BirdDogWaitingItemSchemaconstconstant

SettledBirdDogReplySchemaconstconstant

BirdDogUndeliverableReasonSchemaconstconstant

UndeliverableBirdDogReplySchemaconstconstant

AcceptedBirdDogReplySchemaconstconstant

BirdDogReplySchemaconstconstant

BirdDogMailSchemaconstconstant

BirdDogAgentWorkSchemaconstconstant

BirdDogAgentJobPayloadSchemaconstconstant

BirdDogAgentJobInputSchemaconstconstant

boundedDiagnostic()fnfunction

Parameters

Returns

agentJobFromInput()fnfunction

Parameters

Returns

decodeAgentJob()fnfunction

Parameters

Returns

settlementReplies()fnfunction

Parameters

Returns

acceptedNotice()fnfunction

Parameters

Returns

hasPendingDelivery()fnfunction

Parameters

Returns

make()fnfunction

Parameters

Returns

BirdDogErrorclass

EffectBirdDogOptionstype alias

BirdDogEffecttype alias

BIRD_DOG_MAIL_CONTENT_MAX_BYTESconstant

BirdDogAgentReferenceSchemaconstant

BirdDogAgentRecipientReferenceSchemaconstant

BirdDogSystemIdentitySchemaconstant

BIRD_DOG_DIAGNOSTIC_MAX_LENGTHconstant

BIRD_DOG_WAITING_MAX_ITEMSconstant

BirdDogWaitingItemSchemaconstant

SettledBirdDogReplySchemaconstant

BirdDogUndeliverableReasonSchemaconstant

UndeliverableBirdDogReplySchemaconstant

AcceptedBirdDogReplySchemaconstant

BirdDogReplySchemaconstant

BirdDogMailSchemaconstant

BirdDogAgentWorkSchemaconstant

BirdDogAgentJobPayloadSchemaconstant

BirdDogAgentJobInputSchemaconstant

boundedDiagnostic()function

agentJobFromInput()function

decodeAgentJob()function

settlementReplies()function

acceptedNotice()function

hasPendingDelivery()function

make()function