Python DX: complete type stubs with a CI typing gate + error-message audit

[hardbyte]

Motivation

Python is a first-class runtime, and typing is how Python developers experience an API's quality. The .pyi stubs exist but have drifted before (the ADR-023 claim-ring kwargs were documented-but-not-plumbed until the 0.6 pre-flight caught it). Errors that surface from the PyO3 boundary should name the fix, not just the failure.

Scope

• Stub completeness: audit .pyi against the actual PyO3 surface; add a CI gate that fails when the compiled module exposes symbols/signatures the stubs don't match (and vice versa).
• Type-check the examples: mypy/pyright run over awa-python/examples/ and the README snippets' source files in CI, so the documented API is the typed API.
• Error-message audit: every error raised across the bridge names the likely fix or links a docs anchor (e.g., schema-mismatch → "run awa migrate"; non-finalized cluster in 0.7 → the finalize steps; NOTIFY failure → pooler docs).
• Confirm the awa-pg wheel matrix covers current CPython versions and platforms; document the support matrix.

Acceptance

• CI fails on stub/API drift (demonstrated with an intentional drift in a test).
• Examples type-check clean.
• Error audit checklist merged with before/after samples for the top ten operator-facing errors.

References

Roadmap: docs/0.7-roadmap.md (WS-6, NEW-14). Related: ADR-004 (PyO3 bridge), ADR-009 (sync parity), 0.5→0.6 pre-flight known-issue (claim-ring kwargs).