feat(outbox): transactional outbox helper — Node core (ADR-0029)

Ports the producer-side transactional outbox: Outbox.write encodes the frozen
envelope and persists it via a caller-bound OutboxStore inside the caller's own
DB transaction (no dual-write), and OutboxRelay.flush/drain forwards stored rows
verbatim through an OutboxTransport — mark-published only after publish resolves,
a rejecting publish -> markFailed + linear backoff (row stays pending), one poison
row never blocks the batch. At-least-once handoff; consumers dedupe on meta.id
(the Idempotent mirror). Frozen bytes ride verbatim (GR-1/4/5); store+transport
are interfaces so the core stays zero-dep (GR-7). v1.6.0.

Author: muhammetsafak

CHANGELOG.md

@@ -9,6 +9,36 @@ The envelope wire format is versioned separately by `meta.schema_version`
 
 ## [Unreleased]
 
+## [1.6.0] - 2026-06-21
+
+### Added
+- **Transactional outbox — an optional producer-side helper that removes the dual
+  write (ADR-0029).** A plain producer must commit its business row **and** publish to
+  the broker — two systems that disagree on a crash. The outbox persists the encoded
+  envelope into the **same DB transaction** as the business write, and a separate relay
+  publishes the durable rows afterwards: no distributed transaction, exactly-once
+  *handoff*, then at-least-once on the wire as always.
+  - New `Outbox` writer — `write(envelope)` encodes via the frozen `EnvelopeCodec` and
+    delegates to the store. **The caller owns the transaction boundary**; the helper
+    never begins/commits anything (GR-7).
+  - New `OutboxStore` interface (`save`, `fetchUnpublished` oldest-first, `markPublished`,
+    `markFailed`) — the persistence seam the caller binds to their own DB; the core ships
+    no DB driver. New `OutboxTransport` interface (`publish(body, queue)`) — the
+    publish-only seam the relay forwards through, bound to the caller's broker.
+  - New `OutboxRelay` — `flush()` publishes one batch (marking each row published only
+    **after** the transport resolves; a rejecting publish → `markFailed` + bounded linear
+    backoff, the row stays pending, the batch continues) and `drain(maxPasses?)` loops
+    until no progress, with a safety ceiling. The sleeper is injectable so tests are
+    instant.
+  - New `InMemoryOutboxStore` reference store (tests / single-process demos; no real
+    transaction). New types `OutboxRecord`, `OutboxRelayResult`, `OutboxRelayOptions`,
+    `Sleeper`.
+  - The relay publishes the **stored bytes verbatim** — never decoding, rebuilding or
+    re-encoding the envelope — so `trace_id` is preserved end-to-end (GR-4) and the body
+    is byte-identical before store and after relay (GR-1/GR-5). `schema_version` stays
+    **1**: the outbox's bookkeeping lives *around* the envelope, never *on* the wire.
+    Entirely opt-in and backward compatible.
+
 ## [1.5.0] - 2026-06-21
 
 ### Added

README.md

@@ -129,6 +129,42 @@ stays **1**, GR-1) — the same out-of-band `HeaderCarrier` seam as the `tracepa
 header. It takes effect only when the `RedriveIO` implements `publishWithHeaders`;
 otherwise `bypass` is a no-op (`bypassed: false`) and the message is still redriven.
 
+### Transactional outbox (optional)
+
+A plain producer does two things that must both happen or neither — commit the
+business row and publish the message — across two systems that can disagree on a
+crash (the **dual write**). The outbox removes it: `outbox.write(env)` persists the
+**encoded envelope into the same DB transaction** as your business write, and a
+separate `OutboxRelay` publishes the durable rows afterwards (ADR-0029).
+
+```ts
+import { Outbox, OutboxRelay, InMemoryOutboxStore, EnvelopeCodec } from "@babelqueue/core";
+
+// 1) WRITE — the caller owns the transaction boundary (this is the whole point).
+const outbox = new Outbox(store); // your OutboxStore, bound to your DB
+await db.transaction(async (tx) => {
+  await tx.insertOrder(order);                          // the business write
+  const env = EnvelopeCodec.make("urn:babel:orders:created", { order_id }, { queue: "orders" });
+  await outbox.write(env);                              // same connection, same tx
+});                                                     // both commit, or neither
+
+// 2) RELAY — drain the durable rows onto the broker (a worker loop / cron).
+const relay = new OutboxRelay(transport, store);       // your OutboxTransport
+await relay.drain();                                   // publishes verbatim, marks published
+```
+
+The store and the transport are **interfaces you bind** to your own DB and broker —
+the core ships no DB driver (GR-7) and only an `InMemoryOutboxStore` reference for
+tests/demos. The relay publishes the **stored bytes verbatim** — it never decodes,
+rebuilds or re-encodes the envelope — so `trace_id` is preserved end-to-end (GR-4)
+and the body is byte-identical before store and after relay (GR-1/GR-5). It is
+**at-least-once handoff**: a crash between publish and mark-published re-publishes the
+row, so consumers must stay idempotent (the `Wrap` helper is the consumer-side mirror).
+
+Implement `OutboxStore` over your DB (`save`, `fetchUnpublished` oldest-first — your
+adapter SHOULD claim/lock rows so two relays don't double-publish — `markPublished`,
+`markFailed`) and `OutboxTransport` (`publish(body, queue)`) over your broker.
+
 ## What this core is (and isn't)
 
 It enforces the **contract**: the envelope shape, URN identity, trace propagation,

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@babelqueue/core",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Polyglot Queues, Simplified — the Node/TypeScript core: the canonical BabelQueue wire-envelope codec, contracts and dead-letter helpers.",
   "keywords": [
     "queue",
@@ -59,7 +59,7 @@
     "build": "tsup",
     "typecheck": "tsc --noEmit",
     "lint": "eslint src test",
-    "test": "node --import tsx --test test/codec.test.ts test/dead-letter.test.ts test/conformance.test.ts test/overhead.test.ts test/idempotency.test.ts test/schema.test.ts test/otel.test.ts test/redrive.test.ts test/replay.test.ts",
+    "test": "node --import tsx --test test/codec.test.ts test/dead-letter.test.ts test/conformance.test.ts test/overhead.test.ts test/idempotency.test.ts test/schema.test.ts test/otel.test.ts test/redrive.test.ts test/replay.test.ts test/outbox.test.ts",
     "coverage": "c8 --check-coverage --lines 90 --functions 90 --branches 85 --reporter=text npm test",
     "prepublishOnly": "npm run build"
   },

package.json

@@ -49,3 +49,13 @@ export type {
 } from "./redrive.js";
 
 export { HEADER_REPLAY_BYPASS, isReplay, bypassExternalEffects } from "./replay.js";
+
+export { Outbox, OutboxRelay, InMemoryOutboxStore } from "./outbox.js";
+export type {
+  OutboxStore,
+  OutboxTransport,
+  OutboxRecord,
+  OutboxRelayResult,
+  OutboxRelayOptions,
+  Sleeper,
+} from "./outbox.js";