docs: fix broken examples and wrong behaviour claims

[lesnik512]

Summary

A docs review found examples that fail when run and behaviour descriptions that disagree with the code. Each item below was checked against the source and, for examples, run in the repo venv.

Changes

Broken examples

• docs/usage/messaging-service.md: Resources.database_engine inside the class Resources body raised NameError; now database_engine (checked with modern-di installed).
• docs/usage/relay.md: the standalone router snippet included the FastAPI StreamRouters into a plain KafkaBroker, which raises SetupError: Router must be an instance of KafkaRegistrator. It now builds faststream.kafka.KafkaRouter + faststream_outbox.OutboxRouter. The OutboxResponse(..., session=...) example would fail with TypeError from the eager check (response.py:_validate_publish_args) before the documented dispatch error; now session=session.
• docs/usage/fastapi.md: app.add_event_handler does not exist on the installed FastAPI 0.141 / Starlette 1.6. Replaced with a lifespan example (checked with TestClient: broker starts, engine.dispose() awaited).

Wrong behaviour claims

• troubleshooting.md: OutboxResponse + foreign publisher is not nacked. subscriber/usecase.py:609-619 logs "Outbox configuration error (fix required; row left to lease-expiry retry)" and the row waits for lease expiry (reproduced with TestOutboxBroker(run_loops=True)). Heading/anchor renamed; no private class names.
• troubleshooting.md: real ImportError text (schema_validation.py:278); drains are gathered (broker.py:302-306), so shutdown is about one graceful_timeout; lease_lost is an extra, the message text is "lease expired before {phase} write" (usecase.py:839), both now documented.
• instrumentation-seams.md: "Three" -> "Four" events (adds drain_timeout); removed duplicate sentence.
• setup-prometheus-opentelemetry.md: OTel meters go to the global OTel meter provider; the duplicate-collector ValueError fires when the second collector set is created (reproduced at PrometheusRecorder(...)); consume spans use messaging.destination_publish.name, publish spans messaging.destination.name (opentelemetry/provider.py:51,66).
• dlq.md: no enum column exists (schema.py:207).
• schema-validation.md: documents the pg_index / pg_constraint probes (schema_validation.py:68-77) and check_autovacuum=True (broker.py:367).
• alembic.md: partitioned DLQ DDL used last_exception TEXT; validate_schema() against Postgres 17 fails with "type mismatch: expected String(), got TEXT()". VARCHAR passes.
• index.md / how-it-works.md: standalone and relay presented as two options; index lists concepts/performance.md.
• first-outbox-app.md: Python 3.11+ (matches requires-python); sample output uses 0.14.1 (latest tag).
• README.md: faststream_outbox.fastapi.OutboxRouter.
• schema_validation.py:278: quote 'faststream-outbox[validate]' for zsh; test updated first (red, then green).

Private internals and stale history

• Removed _fake_start, _fetch_loop, _sync_dispatch, _basic_publish, _noop_recorder, _emit_metric, _subscribers, _stopping, _LAST_EXCEPTION_MAX_CHARS, _flush_terminal, OutboxSubscriberConfig.__post_init__, unexported OutboxClient from the pages named in the review; described behaviour instead.
• Removed "Since 0.11.0", "pre-fix migrations", "F5-03", "fix: don't propagate envelope-managed headers onto a chained OutboxResponse (F5-01/F5-02) #85", "2026-05-07 reassessment", and the HTML maintainer note.

Doc code blocks: 92 python blocks extracted from docs/**/*.md + README; 88 compile (4 are signature sketches); 42 run cleanly with a shared per-page namespace. The rest are fragments that need earlier context, need Postgres, or need packages not installed (modern-di, OTLP exporter).

Checklist

• Lint and format pass (ruff)
• Type check passes (ty)
• Tests pass and new behavior is covered
• Build succeeds (uv build) if packaging or build config changed
• Repo metadata stays consistent across the three surfaces (GitHub description, pyproject description, profile blurb) if this touches packaging

Also ran mkdocs build --strict (passes) and the full pytest suite against Postgres 17 (624 passed).

[github-actions]

Benchmark gate

✅ gate passed

scenario	msg/s	delete/msg	WALrec/msg	WALB/msg	fpi	upd	del	dead_tup
consumer/w1/b10	965	1.000	6.78	914	242	5000	5000	10000
consumer/w1/b100	968	1.000	6.83	918	243	5000	5000	10000
consumer/w2/b10	1086	1.000	6.80	965	242	5000	5000	10000
consumer/w2/b100	1329	1.000	6.73	955	243	5000	5000	10000
consumer/w4/b10	966	1.000	6.82	992	261	5000	5000	10000
consumer/w4/b100	1514	1.000	6.87	1038	244	5000	5000	10000
consumer/w1/b100/tfbs100	5025	0.010	6.07	1116	243	5000	5000	10000
producer/w1/b100	2172	0.000	3.04	584	0	0	0	0

Gated (fails the build): delete_calls + tuple counters (upd/del/ins) + the producer's insert_calls, exact; select_calls within +2; wal_records within a 10% band. msg/s, WAL bytes and total calls are informational (timing/FPI noise).