feat(server/idempotency): complete PgBackend for multi-worker durable replay

[bokelley]

Summary

Closes #548. Replaces the NotImplementedError scaffold with a real psycopg3-async-pool-backed PgBackend. Multi-worker AdCP sellers can now declare IdempotencySupported(supported=True) and actually dedupe across workers.

• PgBackend(pool=...) — async pool, per-call connection acquisition (matches PgWebhookDeliverySupervisor / PgReplayStore)
• await create_schema() — idempotent CREATE TABLE IF NOT EXISTS + INDEX. JSONB response, COLLATE "C" on PK text columns
• First-writer-wins under concurrent put: ON CONFLICT … DO UPDATE … WHERE existing.expires_at <= now() — concurrent writers racing the same fresh slot can't violate the cache invariant "same (scope, key) → same payload_hash"
• Naive datetime → ValueError with schema-drift hint (fail-fast over silent UTC coercion)
• ASCII identifier regex on table_name; adcp[pg] extra; ImportError when missing

Security hardening alongside the backend

• IdempotencyStore._extract_scope_key rejects tenant_id / caller_identity containing the U+001E scope separator. Without this, tenant="A\x1eB" + principal="X" collides with tenant="A" + principal="B\x1eX" — multi-tenant isolation defeated
• Log lines use _scope_log_id(scope_key) — sha256-truncated identifier instead of the raw principal id. PII no longer lands in centralized log sinks

Docstring caveats

• Atomicity (v1): cache write commits on a fresh pool connection (not handler's tx). Non-idempotent handler side effects need handler-level dedup on a unique constraint, or the co-tx follow-on
• Schema bootstrap: CREATE TABLE IF NOT EXISTS no-ops on a pre-existing wrong-shape table — Alembic-first deployments must copy the DDL verbatim
• JSON-safe contract: response dict must serialize via json.dumps; no datetime/Decimal/set/bytes
• DoS: no row cap, only TTL. Per-principal rate limiting at the auth tier is the AdCP spec's expectation; schedule delete_expired() as a sweep

Test plan

• 15 unit tests with mocked psycopg pool — tests/test_pg_idempotency_backend.py
• 9 conformance tests against real Postgres (skipped without ADCP_PG_TEST_URL): first-writer-wins concurrent put, expired-row overwrite, scope isolation, end-to-end IdempotencyStore replay through PgBackend
• 4 scope-separator-rejection unit tests in tests/test_server_idempotency.py
• CI workflow extended to run the new conformance suite in the Postgres-16 job
• Adjacent + full unit suite green (3511 passed, 0 failures)
• ruff check + mypy clean

Reviewed by

Pre-PR review by code-reviewer, security-reviewer, python-expert. Material concerns addressed:

• ON CONFLICT DO UPDATE race (python-expert) — added WHERE expires_at <= now() for first-writer-wins (was last-writer-wins)
• \x1e separator confusion (security-expert) — added validator in _extract_scope_key, fail-closed on either tenant or principal containing the separator
• PII in logs (security-expert) — sha256-truncated _scope_log_id replaces raw scope_key in WARNING/DEBUG lines
• Naive datetime (python-expert) — fail-fast with schema-drift hint instead of silent UTC coercion
• Docstring expansions for atomicity caveat, Alembic-first drift, JSON-safe contract, DoS expectations

🤖 Generated with Claude Code