@shiit/bird-dog

A mail system backed by a dog that bites.

A bird dog is a hunting dog, bred to find birds. Pigeons were bred to carry letters. This dog brings home the mail. Even from the hands of a dead bird.

        ┌────────────────── @shiit/bird-dog ──────────────────┐
mail ──►│ pigeon: validate the envelope, carry it as payload  │
        │ watchdog: keeps the books: queue → claim → settle   │
        │ pigeon: on settle → turn record + alert to replyTo  │
        └─────────────────────────────────────────────────────┘

The dog and the bird

• @shiit/watchdog: the dog. Keeps the books (the durable job store) and bites when things need bitten: the sweep, the concurrency cap, the crash recovery. The payload is a bird it never pecks. Opaque, untouched, returned whole.
• the pigeon: the bird. Carries the mail. The envelope (Mail, Zod-validated at the door), the transport (the outbox), the turn record, the completion alert.

What the hunt looks like

• ingest(mail, opts?): validate the envelope, drop it in the yard. The envelope rides as the dog's opaque payload. opts.priority and opts.retry (opt-in, default never) are engine fields, passed at the door, never smuggled on the envelope.
• claim(queue) / complete(jobId, { outcome, result? }): the bracket around your work. outcome is completed | error | cancelled | interrupted. result is your cargo.
• readPriorityMessages(queue): mid-run steer. Priority birds get handed over at the turn boundary.
• tick(): the dog sweeps and claims; the pigeon drains the outbox.
• abort(queue): settles the executing job as cancelled. The yard is never purged. Cancel is scoped to the current run, always.

Why the dog finds the letters

The dog settles and calls onSettled. The pigeon flies the reply. The turn record goes on the books, and a completion alert goes to every parent named in the envelope's replyTo. Loud, not silent. A crash settles interrupted and the parent hears about it. Cancel is the one quiet outcome.

And when the pigeon dies mid-flight (isolate eviction, a crash, a deploy) the mail is still in the dog's yard. Durable, retrievable, never lost. That's the breed.

The bird is opinionated on purpose: the envelope carries agent vocabulary (to.sessionId, replyTo, alert) because that's what a mail carrier is for. The dog knows none of it.

Oban for DOs, with the mail layer the boring part everyone skipped.

Part of the shiit stack. MIT.