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

Ports the producer-side transactional outbox as babelqueue.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 the transport — mark_published only after
publish returns, a raising publish -> mark_failed + 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);
OutboxStore is a Protocol so the core stays stdlib-only (GR-7). v1.12.0.

Author: muhammetsafak

CHANGELOG.md

@@ -9,6 +9,31 @@ The envelope wire format is versioned separately by `meta.schema_version`
 
 ## [Unreleased]
 
+## [1.12.0] - 2026-06-21
+
+### Added
+- **Transactional outbox helper** (ADR-0029) — the optional `babelqueue.outbox` module ports the
+  PHP `BabelQueue\Outbox` helper to Python, removing the producer **dual write**: the message is
+  persisted **into your database, in the same transaction** as the business data (so it commits or
+  rolls back atomically with it), and a separate **relay** publishes the durable rows afterwards.
+  No distributed transaction; exactly-once *handoff* into the broker, then at-least-once on the wire
+  (the consumer dedupes on `meta.id` via the idempotency helper, the consumer-side mirror, ADR-0022).
+  The core stays **stdlib-only** (GR-7): `OutboxStore` is an abstract `typing.Protocol` the caller
+  binds to their own DB — the module ships only the in-memory `InMemoryOutboxStore` reference and
+  pulls in **no** DB driver. `Outbox.write(envelope)` encodes via the frozen `EnvelopeCodec` and
+  delegates to `OutboxStore.save` **inside the transaction the caller already opened** — it does not
+  begin/commit anything (the caller owns the transaction boundary). `OutboxRelay.flush()` publishes
+  one batch through the existing publish-only `Transport`, marking each row published **only after**
+  the transport accepts it, or failed (caught → `mark_failed`, row left pending, with a bounded
+  linear backoff via an injectable sleeper) so one poison row never blocks the batch;
+  `OutboxRelay.drain()` loops while a pass makes progress, with a safety ceiling. The relay
+  publishes the **stored bytes verbatim** — it never decodes, rebuilds or re-encodes the envelope —
+  so `trace_id` is preserved end-to-end and the body is byte-compatible across SDKs (GR-1/GR-4/GR-5).
+  Unit-tested without a broker (write stores the encoded envelope byte-identical; relay publishes via
+  a fake `Transport` + marks published; a raising publish → `mark_failed`, row still pending, batch
+  continues; `drain` loops to empty and stops on no-progress; backoff grows linearly and caps via the
+  injected sleeper). The envelope is unchanged (`schema_version: 1`); this is purely additive.
+
 ## [1.11.0] - 2026-06-21
 
 ### Added

README.md

@@ -182,6 +182,47 @@ def on_created(data, meta): ...
 python manage.py babelqueue_worker --queue orders          # run the consumer
 ```
 
+## Transactional outbox (optional)
+
+The `babelqueue.outbox` helper (ADR-0029) removes the producer **dual write**: "commit the
+business row" and "publish to the broker" are two systems that can disagree on a crash. Instead the
+message is persisted **into your database, in the same transaction** as the business data — so it
+commits or rolls back atomically with it — and a separate **relay** publishes the durable rows
+afterwards. No distributed transaction; exactly-once *handoff* into the broker, then at-least-once
+on the wire (the consumer dedupes on `meta.id` — see the idempotency helper, the mirror of this).
+
+The core stays **stdlib-only**: `OutboxStore` is an abstract `Protocol` you bind to **your own DB**
+(the core ships no driver). The stored value is the `EnvelopeCodec`-encoded envelope **byte-for-byte
+unchanged** (frozen, `schema_version: 1`); the relay publishes those exact bytes — it never decodes,
+rebuilds or re-encodes — so `trace_id` is preserved end-to-end.
+
+```python
+from babelqueue import BabelQueue, EnvelopeCodec
+from babelqueue.outbox import Outbox, OutboxRelay, InMemoryOutboxStore
+
+store = InMemoryOutboxStore()          # production: your own OutboxStore adapter, DB-backed
+outbox = Outbox(store)
+
+# write side — YOU own the transaction boundary (this is the whole point):
+with db.transaction():                 # your own open transaction
+    db.insert_order(order)             # the business write
+    envelope = EnvelopeCodec.make("urn:babel:orders:created", {"order_id": 1042}, queue="orders")
+    outbox.write(envelope)             # same connection, same tx — both, or neither
+
+# read/publish side — run on a short interval, after the business tx commits:
+app = BabelQueue("redis://localhost:6379/0", queue="orders")
+relay = OutboxRelay(app.transport, store)
+relay.drain()                          # publish all pending rows; flush() does one batch
+```
+
+`Outbox.write` only encodes and calls `OutboxStore.save` — it does **not** begin or commit anything.
+A `save` runs inside the transaction you already opened; you commit both together. `OutboxRelay`
+marks a row published only **after** the transport accepts it; a publish that raises is recorded via
+`mark_failed` (with a bounded, injectable-sleeper backoff) and left pending for a later pass, so one
+poison row never blocks the batch. Implement `OutboxStore` over your DB (claim rows oldest-first,
+ideally with `SELECT … FOR UPDATE SKIP LOCKED` so two relays don't double-publish); `InMemoryOutboxStore`
+is the reference for tests and single-process demos (no real transaction).
+
 ## OpenTelemetry tracing (optional)
 
 `pip install "babelqueue[otel]"` adds the optional `babelqueue.otel` module — the core never

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "babelqueue"
-version = "1.11.0"
+version = "1.12.0"
 description = "Polyglot Queues, Simplified — the Python core: the canonical BabelQueue wire-envelope codec, contracts and dead-letter helpers."
 readme = "README.md"
 requires-python = ">=3.9"

src/babelqueue/__init__.py

@@ -11,18 +11,26 @@
 
 from __future__ import annotations
 
-from . import dead_letter, headers, idempotency, redrive, replay
+from . import dead_letter, headers, idempotency, outbox, redrive, replay
 from .app import BabelQueue
 from .codec import SCHEMA_VERSION, SOURCE_LANG, EnvelopeCodec
 from .contracts import HasTraceId, PolyglotMessage
 from .headers import headers_from_context
 from .idempotency import IdempotencyStore, InMemoryStore
+from .outbox import (
+    InMemoryOutboxStore,
+    Outbox,
+    OutboxRecord,
+    OutboxRelay,
+    OutboxRelayResult,
+    OutboxStore,
+)
 from .exceptions import BabelQueueError, UnknownUrnError
 from .replay import HEADER_REPLAY_BYPASS, bypass_external_effects, is_replay
 from .routing import UnknownUrnStrategy
 from .transport import HeaderPublisher, InMemoryTransport, ReceivedMessage, Transport
 
-__version__ = "1.11.0"
+__version__ = "1.12.0"
 
 __all__ = [
     "BabelQueue",
@@ -41,6 +49,13 @@
     "dead_letter",
     "headers",
     "idempotency",
+    "outbox",
+    "Outbox",
+    "OutboxStore",
+    "OutboxRecord",
+    "OutboxRelay",
+    "OutboxRelayResult",
+    "InMemoryOutboxStore",
     "redrive",
     "replay",
     "is_replay",