docs: fix 22 inaccuracies from the 2026-06-12 docs audit (I1–I22)

[lesnik512]

Summary

Fixes all 22 inaccuracy-severity findings from planning/active/2026-06-12-docs-audit-findings.md — docs that are stale or misleading but not flatly broken. Each correction was verified against current source (post-#61/#63).

ID	Page(s)	Fix
I1	how-it-works	Illustrative fetch CTE: real ORDER BY (next_attempt_at, id), deliveries_count increment, "simplified" note on the partial-index OR shape
I2	how-it-works, timers	NOTIFY skipped only when genuinely future-dated; a past activate_at still notifies
I3	installation	Base install ships no async Postgres driver; the asyncpg DSNs need one
I4	add-kafka-relay	Listener rationale: the Step 5 console consumer uses the HOST listener from inside the broker container, not the DOCKER listener
I5	add-kafka-relay	Tutorial 1's cleanup destroys its --rm Postgres container — recovery note added
I6	subscriber	min_fetch_interval is the jittered idle-backoff base + queue-full wait, not a "floor when the queue has work"
I7	subscriber, troubleshooting	start() only schedules tasks; pool exhaustion = repeating reconnect ERRORs + starved dispatch, not a hang at start()
I8	dlq, observability	dlq_written always emits exception_type (None when absent)
I9	dlq	Add missing from sqlalchemy import MetaData
I10	schema-validation	Note the second validation pass over the DLQ table
I11	publisher	Terminal write runs on the worker's autocommit connection, not the user session
I13	fastapi	Broker middlewares go through OutboxRouter(middlewares=[...])
I14	setup-prometheus	Constructor kwarg is middlewares, not broker_middlewares
I15	observability	dispatched/acked/nacked_terminal/lease_lost event-catalog rows corrected to actual tags
I16	instrumentation-seams	"Four events" → three (the empty-fetch idle counter is fetched with count=0)
I17	comparison	Drop the unreachable "channel name too long" NOTIFY-loss mode (make_outbox_table raises first)
I18	subscriber, troubleshooting, checklist	Server-side budget is max_workers + 2 (pool +1 plus the raw LISTEN conn); pool formula +1 kept
I19	alembic	astext_type=sa.Text() (qualified)
I20	alembic	validate_schema() is opt-in — fails a /health probe or CI gate, never runs at broker.start()
I21	observability	Seven subscriber emission points (with dlq_written)
I22	setup-prometheus	OTel recorder also emits messaging.publish.messages + the three messaging.outbox.* instruments

Notes

• I12 (testing.md "_FakeRow dicts") was already resolved as collateral of the B3 fix in docs: fix 14 confirmed bugs from the 2026-06-12 docs audit (B1–B14) #63.
• Bugs B1–B14 shipped in docs: fix 14 confirmed bugs from the 2026-06-12 docs audit (B1–B14) #63; improvements P1–P25 remain open triage.
• Two fixes corrected an unflagged adjacent site for consistency: the dlq_written row in observability.md (I8) and the broker.start() troubleshooting heading/TOC (I7).

Test plan

• just docs-build (mkdocs build --strict) passes
• Each source-dependent claim (CTE ORDER BY / increment, _base_tags subscriber, lease_lost phases, OTel instrument set, dlq_written exception_type, max_workers + 2, middlewares kwarg) verified against current code
• Sweeps clean: no leftover broker_middlewares, "six emission points", or "four events" in docs

🤖 Generated with Claude Code