fix: harden staleness failover and OTLP production readiness

[Pavkazzz]

Summary

• Fix real staleness failures in asyncpg, asyncpgsa and SQLAlchemy/asyncpg by projecting PostgreSQL WAL LSNs as text.
• Fix psycopg3 promotion detection: health queries finish their own transactions and preserve caller-owned transactions through savepoints.
• Make OTLP callbacks consume detached snapshots sampled on the owner event loop; harden startup/cancellation/shutdown and runnable module imports in all five examples.
• Add six-adapter real PostgreSQL and actual OpenTelemetry SDK regression tests; fix test cleanup and synchronize docs.

Verification

• Scoped local suite: 200 passed.
• Fresh installed wheel in an isolated environment: 99 passed, all six adapters imported/executed, no source-tree import or adapter skips. Local-only SCM version 0.9.31+readiness.smoke, not a publication.
• Physical primary + two standbys: 12/12 adapter/checker combinations passed pause/replay lag, fresh/master/stale selection and recovery; final psycopg byte/time rerun passed after transaction fix.
• Actual primary stop + replica promotion, retaining original managers: 6/6 adapters wrote successfully; persisted rows verified on the promoted node.
• All five OTLP CLI modules exported positive acquire counters to a real local gRPC collector and shut down under SIGINT.
• Scoped Ruff, mypy and whitespace checks passed.
• Independent requirements and OTLP thread/lifecycle reviews: SAFE. Documentation setup finding fixed and re-reviewed.
• Exhaustive lint/mypy and Python 3.10–3.14 suites: 7/7 success on exact head d80f36be65e1121ec827333d30835f607a248732 (CI run).

All database fault injection used uniquely owned transient containers from the approved local Compose service. Shared PostgreSQL and production were untouched.

Compatibility and delivery

No library public API or runtime dependency additions; OpenTelemetry remains test/example-only. Existing metric names/types/units remain unchanged. Example integration now uses observe_hasql_metrics and python -m example.otlp.<adapter> from the checkout. Snapshot sampling and export intervals are distinct.

This PR is for review/CI only: no merge, package publication or consumer deployment is included. After separate approval, validate the target consumer in stage before production. Rollback: revert this commit or pin the consumer to its prior package version.

Residual security follow-up

GitHub reports existing Dependabot alerts against uv.lock, including development/test dependencies. The published library declares no runtime dependencies. Confirmed dependency paths for cryptography (Linux keyring), urllib3 and idna lead to twine in develop; these existing lockfile alerts were not remediated in this behavioral-readiness PR. This is not a claim of a clean dependency security audit or of a completed consumer rollout.

AI-assisted: true