docs: fix the improvement tail (P1–P18) (#80)

Close out the convenience/readability/gap tail from the 2026-06-13 docs
audit; signatures and defaults verified against source.

- P1/P2/P3 subscriber.md: document propagate_inbound_headers, the
  standard passthrough kwargs, and a retry-strategy params/defaults table.
- P4/P5 publisher.md: show the broker.publisher() signature; add a
  FastAPI-specific callout to the OutboxResponse chained-publish example
  (the session must outlive the handler return — vanilla apps call
  broker.publish directly).
- P6 index.md: signpost the three observability entries (concept /
  reference / step-by-step).
- P7 instrumentation-seams.md: state the recorder "must not block"
  constraint; make the event count self-documenting.
- P8 observability.md: add a bundled-adapter wiring snippet.
- P9/P10/P11 comparison.md: bullet the feature wall, add a decision
  matrix, give the CDC verdict a falsifiable detail.
- P12/P13 how-it-works.md: flesh out the relay stub; dedupe the
  idempotency note.
- P14/P15 testing.md: runnable loop-mode example; drop the inconsistent
  pytest.mark.asyncio marker.
- P16 troubleshooting.md: name the missing-timer_id DLQ migration cause.
- P17 basic.md: drop the unexplained max_workers=4.
- P18 relay.md: setup note + OutboxResponse import in the anti-pattern.

All findings (B1–B5, C1–C3, I1–I15, P1–P18) now resolved.
mkdocs build --strict clean.

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: lesnik512

docs/concepts/comparison.md

@@ -5,28 +5,42 @@ trade-offs. This page names the alternatives, says when each is the better
 choice, and ends each comparison with a one-line verdict so a scanning
 reader can lift the answer without reading the discussion.
 
+| Alternative | Pick *it* when… | Pick `faststream-outbox` when… |
+|---|---|---|
+| [Writing your own](#vs-writing-your-own-outbox-table-and-worker) | You only ever need the MVP shape | You expect the system to live for years |
+| [CDC / Debezium](#vs-cdc-debezium-logical-replication) | You already need WAL capture, or producers are outside your control | You own the producer and want retry / DLQ / timers in-process |
+| [Kafka txns / Rabbit confirms](#vs-kafka-transactions-or-rabbitmq-publisher-confirms) | The bus is already running and you need bus-scale throughput | Postgres is your only durable store |
+| [Plain `LISTEN/NOTIFY`](#vs-plain-listennotify) | You only need a wake-up, not a delivery guarantee | You need durability, replay, and retry |
+| [Celery / RQ / Dramatiq](#vs-celery-or-rq-dramatiq-with-a-db-backend) | You're modelling ad-hoc background jobs | You're modelling events that must commit with a DB write |
+| [FastStream foreign broker](#vs-faststream-kafkabroker-rabbitbroker-directly) | You have no DB write to commit alongside the publish | You need atomicity with a DB write (use *both*, via [Relay](../usage/relay.md)) |
+
 ## vs. writing your own outbox table and worker
 
 A bespoke outbox is the most common starting point — the pattern itself is
 straightforward, and an MVP can ship in an afternoon. What `faststream-outbox`
 buys you, in concrete terms, is the pile of pieces that turn that MVP into a
-production system: per-row **lease tokens** with a load-bearing invariant
-that any new fetch / terminal path must preserve; the **partial-index
-design** the fetch CTE depends on (without those, the disjunctive WHERE
-clause falls back to seq-scan as the table grows); the **fetch-and-claim
-CTE shape** with `FOR UPDATE SKIP LOCKED` that reclaims both unleased rows
-and expired leases without a separate reaper; the
-retry-strategy hierarchy (`ExponentialRetry`, `NoRetry`, …) enforcing
-`max_attempts` and `max_total_delay_seconds` uniformly; `validate_schema()` via
-Alembic's `autogenerate.compare_metadata`; **drain semantics** on stop with
-the `running` / `_stopping` two-flag dance and parallel-gathered subscriber
-shutdown; **`LISTEN/NOTIFY`** short-circuit on top of polling, with NOTIFY
-suppression on future-dated rows and `timer_id` conflict no-ops;
-**`timer_id` dedup** via a partial unique index plus
-`on_conflict_do_nothing`; the **DLQ atomicity CTE** that rolls back the
-DELETE when the DLQ insert fails. None of these is hard individually; in
-aggregate they decide whether the outbox survives the second year of
-production load.
+production system:
+
+- per-row **lease tokens** with a load-bearing invariant that any new
+  fetch / terminal path must preserve;
+- the **partial-index design** the fetch CTE depends on (without those, the
+  disjunctive WHERE clause falls back to seq-scan as the table grows);
+- the **fetch-and-claim CTE shape** with `FOR UPDATE SKIP LOCKED` that
+  reclaims both unleased rows and expired leases without a separate reaper;
+- the **retry-strategy hierarchy** (`ExponentialRetry`, `NoRetry`, …)
+  enforcing `max_attempts` and `max_total_delay_seconds` uniformly;
+- **`validate_schema()`** via Alembic's `autogenerate.compare_metadata`;
+- **drain semantics** on stop, with the `running` / `_stopping` two-flag
+  dance and parallel-gathered subscriber shutdown;
+- **`LISTEN/NOTIFY`** short-circuit on top of polling, with NOTIFY
+  suppression on future-dated rows and `timer_id` conflict no-ops;
+- **`timer_id` dedup** via a partial unique index plus
+  `on_conflict_do_nothing`;
+- the **DLQ atomicity CTE** that rolls back the DELETE when the DLQ insert
+  fails.
+
+None of these is hard individually; in aggregate they decide whether the
+outbox survives the second year of production load.
 
 You also pick up the [Subscriber](../usage/subscriber.md),
 [Publisher](../usage/publisher.md), [Dead-letter queue](../usage/dlq.md), and
@@ -57,9 +71,12 @@ outbox row is cheap to write inline with the domain write), when you
 need **handler-level retry, DLQ, and scheduled-delivery semantics
 inline** (CDC pushes those concerns to a separate consumer layer), and
 when the **async-Python logical-replication tooling gap** is too thin
-to lean on. The last point is the load-bearing one for this project — a
-2026-05-07 reassessment confirmed the gap had not closed sufficiently to
-make CDC the recommended path here.
+to lean on: there is no async-native logical-decoding client comparable
+to Debezium's JVM connectors, so a Python CDC path means either running
+the JVM stack alongside your app or driving `pg_recvlogical` / a thin
+`psycopg` replication-protocol wrapper yourself. That is the load-bearing
+point for this project — a 2026-05-07 reassessment confirmed the gap had
+not closed sufficiently to make CDC the recommended path here.
 
 **TL;DR.** Pick CDC when you already need WAL capture or have producers
 outside your control. Pick this when you own the producer and want

docs/concepts/instrumentation-seams.md

@@ -61,16 +61,22 @@ Three events fire **outside** the handler invocation, with no
 ## What the recorder seam observes naturally
 
 The recorder is a `Callable[[str, Mapping[str, Any]], None]` invoked at
-six subscriber events and one producer event. Plus `dlq_written` when
-the DLQ is configured. It fires whether or not a handler is in scope:
+six core subscriber events (`fetched`, `dispatched`, `acked`,
+`nacked_retried`, `nacked_terminal`, `lease_lost`), a conditional
+`dlq_written` when the DLQ is configured, and one producer event
+(`published`). It fires whether or not a handler is in scope:
 
 - All three bus-invisible events above.
 - Plus `acked` / `nacked_retried` / `nacked_terminal` / `dispatched` /
   `published` from inside the handler-execution paths, with explicit
   `subscriber` and `queue` tags.
 
 The recorder cannot bracket span lifecycles (it's a callable, not a
-context manager), so tracing belongs to the middleware seam.
+context manager), so tracing belongs to the middleware seam. It also
+runs **on the dispatch event loop and must not block** — a synchronous
+`Counter.inc()` is fine; an HTTP / StatsD push is not. See
+[Observability § Recorder must not block](../usage/observability.md#recorder-must-not-block)
+for the full contract.
 
 ## Layering: middleware seam vs. recorder seam
 

docs/index.md

@@ -65,8 +65,9 @@ process, no Kafka.
 - [Comparison](concepts/comparison.md) — vs writing your own, vs CDC,
   vs Kafka transactions, vs `LISTEN/NOTIFY`, vs Celery, vs FastStream
   foreign-broker direct.
-- [Instrumentation seams](concepts/instrumentation-seams.md) — the
-  recorder seam vs native middleware, and why both exist.
+- [Instrumentation seams](concepts/instrumentation-seams.md) — *concept:*
+  the recorder seam vs native middleware, and why both exist. **Read this
+  first** if you're deciding what to wire.
 
 ### Guides
 
@@ -81,7 +82,8 @@ process, no Kafka.
 - [Schema validation](usage/schema-validation.md) — opt-in
   Alembic-driven check for `/health` and CI.
 - [Setup Prometheus and OpenTelemetry](usage/setup-prometheus-opentelemetry.md)
-  — wire the native middleware and recorder adapters end-to-end.
+  — *step-by-step:* wire the native middleware and recorder adapters
+  end-to-end.
 
 ### Reference
 
@@ -93,8 +95,8 @@ process, no Kafka.
   walking every subscriber via `broker.subscribers`.
 - [Dead-letter queue](usage/dlq.md) — opt-in audit table, atomicity
   via a single CTE, `dlq_written` metric, retention patterns.
-- [Observability](usage/observability.md) — recorder seam plus
-  native Prometheus / OpenTelemetry middleware.
+- [Observability](usage/observability.md) — *reference:* the recorder-seam
+  API, the full event/tag catalog, and the operator PromQL playbook.
 
 ### Operations
 

docs/introduction/how-it-works.md

@@ -178,13 +178,22 @@ you add).
 
 ## Failure modes
 
-- **Handlers must be idempotent.** Crash between commit-of-handler-side-effects and the broker's `DELETE` re-delivers the message.
+- **Handlers must be idempotent.** A crash between the handler's side effect and the broker's `DELETE` re-delivers the message — see [At-least-once delivery](#at-least-once-delivery) above.
 - **Best-effort ordering only.** `FOR UPDATE SKIP LOCKED` does not preserve strict order under concurrent workers. If you need strict per-aggregate ordering, route to a single subscriber and run a single worker.
 - **DLQ is opt-in.** Without `dlq_table=`, terminal failures `DELETE` the row.
 
 ## Relay to Kafka / RabbitMQ / NATS / Redis
 
-> **Relay outbox rows to Kafka / RabbitMQ / NATS / Redis with a single decorator → [Relay tutorial](../tutorials/add-kafka-relay.md).**
+An `OutboxSubscriber` can source a FastStream-native cross-broker chain:
+stack a foreign-broker publisher decorator on the subscriber
+(`@kafka_pub @broker_outbox.subscriber("q")`) and the handler's return
+value is forwarded to the real bus. The outbox row stays the durability
+boundary — the row commits with the domain write, and the relay carries
+at-least-once end to end. If the foreign publish fails, the row is **not**
+nacked through the `retry_strategy`; its lease simply expires and a later
+fetch retries the relay, so a transient bus outage never loses the row.
+
+> **Worked end-to-end example → [Relay tutorial](../tutorials/add-kafka-relay.md).**
 
 ## Acknowledgements
 

docs/operations/troubleshooting.md

@@ -54,7 +54,11 @@ pattern compounds.
 
 **Diagnose.** Run `await broker.validate_schema()` against the live
 DB (the `[validate]` extra is required). It will surface missing
-columns / indexes on the DLQ table.
+columns / indexes on the DLQ table. A frequent cause on older
+deployments is a hand-written DLQ migration missing the `timer_id`
+column — `validate_schema()` reports it as a missing column on the DLQ
+table. (The [Alembic guide](../operations/alembic.md#adding-the-dlq-after-the-fact)
+now includes it; pre-fix migrations may not.)
 
 **Fix.** Bring the DLQ schema up to spec (apply the missing migration,
 or rename / drop the drifted column / index). After the schema is

docs/usage/basic.md

@@ -39,13 +39,13 @@ Subscribers work like any FastStream subscriber. Decorate a handler with
 `@broker.subscriber(queue, ...)`:
 
 ```python
-@broker.subscriber("orders", max_workers=4)
+@broker.subscriber("orders")
 async def handle(order_id: int) -> None:
     print(f"order {order_id}")
 ```
 
-See [Subscriber](./subscriber.md) for the full options list, tuning guide,
-and retry strategies.
+See [Subscriber](./subscriber.md) for the full options list (concurrency
+via `max_workers`, tuning, retry strategies).
 
 ## 4. Publish a message
 
@@ -87,7 +87,7 @@ broker = OutboxBroker(engine, outbox_table=outbox_table)
 app = FastStream(broker)
 
 
-@broker.subscriber("orders", max_workers=4)
+@broker.subscriber("orders")
 async def handle(order_id: int) -> None:
     print(f"order {order_id}")
 

docs/usage/observability.md

@@ -36,6 +36,29 @@ def recorder(event: str, tags: dict) -> None:
 broker = OutboxBroker(engine, outbox_table=outbox_table, metrics_recorder=recorder)
 ```
 
+### Bundled adapters
+
+You rarely need to hand-write the callable. Two ready-made recorders ship
+as optional extras and emit the `faststream_outbox_*` series the PromQL
+playbook below keys off:
+
+```python
+from prometheus_client import CollectorRegistry
+from faststream_outbox.metrics.prometheus import PrometheusRecorder
+
+registry = CollectorRegistry()
+broker = OutboxBroker(
+    engine,
+    outbox_table=outbox_table,
+    metrics_recorder=PrometheusRecorder(app_name="checkout", registry=registry),
+)
+```
+
+`OpenTelemetryRecorder` (`faststream_outbox.metrics.opentelemetry`) is the
+OTel equivalent. Full wiring — including running the recorder seam and the
+native middleware together — is in
+[Setup Prometheus and OpenTelemetry](./setup-prometheus-opentelemetry.md).
+
 ### Recorder must not block
 
 The recorder is called from the event loop. **Do not block in it.**

docs/usage/publisher.md

@@ -102,8 +102,23 @@ async def checkout(order: Order, session: AsyncSession) -> None:
 Per-call `headers` are merged with the publisher's static headers
 (per-call wins).
 
+Constructor signature:
+
+```python
+broker.publisher(
+    queue: str,
+    *,
+    headers: dict[str, str] | None = None,
+    title: str | None = None,            # AsyncAPI operation title
+    description: str | None = None,      # AsyncAPI operation description
+    schema: Any | None = None,           # AsyncAPI payload schema override
+    include_in_schema: bool = True,      # exclude from the AsyncAPI spec when False
+) -> OutboxPublisher
+```
+
 The publisher exists primarily for AsyncAPI spec coverage and to
-encapsulate per-queue config (static headers, etc.).
+encapsulate per-queue config — hence the `title` / `description` / `schema`
+/ `include_in_schema` knobs above, alongside the static `headers`.
 
 ### Not a relay decorator
 
@@ -129,6 +144,16 @@ flow routes the returned value through the producer; the same
 transactional contract applies (you provide the session, the row commits
 with your domain writes):
 
+!!! note "This pattern is FastAPI-specific"
+    The returned `OutboxResponse` is published **after** the handler
+    returns, so its `session` must outlive the handler call. FastAPI's
+    `Depends(get_session)` provides exactly that — a session torn down by
+    the dependency after the response flow. Opening your own `async with
+    session_factory() as session:` inside the handler does **not** work
+    here: the session closes on `return`, before the row is inserted.
+    Outside FastAPI, call `broker.publish(..., session=session)` directly
+    inside your handler instead (see [§ `broker.publisher`](#not-a-relay-decorator)).
+
 ```python
 from fastapi import Depends
 from sqlalchemy.ext.asyncio import AsyncSession

docs/usage/relay.md

@@ -24,6 +24,10 @@ boundary, and the relay carries an at-least-once guarantee end to end.
 
 ## Minimal relay
 
+The snippets below assume `engine` and `outbox_table` from the
+[Basic usage](./basic.md) setup (`make_outbox_table(metadata)` +
+`create_async_engine(...)`).
+
 ```python
 from faststream.kafka import KafkaBroker
 from faststream_outbox import OutboxBroker
@@ -167,6 +171,9 @@ broker_outbox.include_router(outbox_router)
 **Do not** combine `OutboxResponse(...)` and a foreign-publisher decorator.
 
 ```python
+from faststream_outbox import OutboxResponse
+
+
 @publisher_kafka
 @broker_outbox.subscriber("outbox_queue")
 async def relay(body: dict) -> OutboxResponse:

docs/usage/subscriber.md

@@ -89,6 +89,7 @@ Per-subscriber knobs, passed to `@broker.subscriber("…", …)`:
 | `max_deliveries` | `None` (unbounded) | Total claims (including lease-expiry re-claims) after which the row is dropped without invoking the handler. Defends against handlers that consistently wedge. |
 | `ack_policy` | `AckPolicy.NACK_ON_ERROR` | See [Ack policy](#ack-policy) |
 | `retry_strategy` | `ExponentialRetry(...)` | See [Retry strategies](#retry-strategies) |
+| `propagate_inbound_headers` | `False` | Relay-only. When `True`, fills `Response.headers` from the inbound message *if* the handler returned a `Response` with empty headers (user-set headers always win). See [Relay](./relay.md). |
 
 ```python
 @broker.subscriber(
@@ -106,6 +107,10 @@ The factory in `subscriber/factory.py` warns or raises on likely-wrong
 combinations (`lease_ttl_seconds <= max_fetch_interval`, `max_deliveries`
 without retry, `min_fetch_interval > max_fetch_interval`, etc.).
 
+The table above lists the outbox-specific knobs. The standard FastStream
+subscriber kwargs pass through unchanged too: `dependencies`, `parser`,
+`decoder`, and the AsyncAPI `title_` / `description_` / `include_in_schema`.
+
 ## Slow handlers — dedicated queue
 
 When a handler's tail latency exceeds the subscriber's `lease_ttl_seconds`,
@@ -206,6 +211,19 @@ when non-zero, the computed delay is multiplied by `1 +
 U(-jitter_factor/2, +jitter_factor/2)` to spread out retries, matching
 `ExponentialRetry`'s shape.
 
+### Strategy parameters
+
+| Strategy | Required | Optional (default) |
+|---|---|---|
+| `NoRetry` | — | — |
+| `ConstantRetry` | `delay_seconds` | `jitter_factor` (`0.0`) |
+| `LinearRetry` | `initial_delay_seconds`, `step_seconds` | `jitter_factor` (`0.0`) |
+| `ExponentialRetry` | `initial_delay_seconds` | `multiplier` (`2.0`), `max_delay_seconds` (`None`), `jitter_factor` (`0.0`) |
+
+Every strategy except `NoRetry` also accepts the shared caps `max_attempts`
+(default `None`) and `max_total_delay_seconds` (default `None`); reaching
+either returns `None`, which is terminal (the row is deleted, or DLQ'd).
+
 ### Retry only on transient errors
 
 Strategies receive the raised `exception` so users may subclass for