feat(signing): PostgreSQL-backed PgReplayStore for multi-instance verifiers

[bokelley]

Summary

Ships a production ReplayStore backed by PostgreSQL so multi-instance AdCP verifiers share nonce-seen state. A replay accepted on worker A can no longer land on worker B within the signature's validity window — the in-memory default left that gap on any load-balanced deployment.

Closes #187.

Backend choice: Postgres (not Redis)

Issue #187 originally proposed Redis. Since then the idempotency work (PR #196) landed PgBackend scaffolding as the intended shared-state backend, signaling the library's direction. Starting with Postgres:

• aligns integrators who already adopted Postgres for idempotency
• avoids pulling a second infra dep (Redis) when Postgres handles the workload with simple TTL cleanup
• leaves Redis as a clean follow-up if a caller asks

Shape

from psycopg_pool import ConnectionPool
from adcp.signing import PgReplayStore, VerifyOptions

pool = ConnectionPool("postgresql://...", min_size=4, max_size=20)
replay = PgReplayStore(pool=pool)

options = VerifyOptions(..., replay_store=replay)

Design notes

• Caller owns the pool — integrators typically already have one; second pool would be wasteful
• Sync, not async — matches the current verifier; async follows whenever an async verifier lands
• Three single-statement queries (seen / remember / at_capacity) + optional sweep_expired()
• ON CONFLICT ... DO UPDATE handles legitimate nonce refresh without error paths
• Lazy-only sweep — seen self-filters; public sweep_expired() for cron
• Fail-closed — connection errors propagate; verifier rejects
• Table-name kwarg is identifier-validated — zero SQL injection surface
• COLLATE "C" on keyid / nonce — blocks locale-dependent case folding that could collapse distinct slots
• at_capacity uses COUNT(*) >= cap against a partial index — pays for accuracy exactly when a signer is misbehaving

Schema

Ships as plain SQL at src/adcp/signing/pg/replay_store.sql. Run it through whatever migration tool you already use — Alembic, Flyway, psql. Partial index for at_capacity is commented out in the DDL so integrators opt in per deployment.

Optional dep via [pg] extra

[project.optional-dependencies]
pg = [
    "psycopg[binary]>=3.1.0",
    "psycopg-pool>=3.2.0",
]

Core SDK stays installable without SQL deps; adcp.signing.PgReplayStore resolves to None when the extra isn't installed. Constructor raises ImportError with the install hint if called without the extra.

Testing

• test_pg_replay_store.py — 16 tests, skipped when ADCP_PG_TEST_URL is unset
• New CI job pg-replay-store runs against a Postgres 16 service container on every PR
• Covers: all Protocol methods, TTL semantics, at_capacity threshold + per-keyid isolation, sweep_expired, 10-thread concurrent remember on the same nonce (tests ON CONFLICT correctness), COLLATE "C" case-variant isolation, identifier validation
• Verified locally against a real Postgres 17 instance: all 16 pass

Not in scope (follow-ups)

• Async PgReplayStore — needs an async verifier first (tracked separately)
• Redis backend — follow up if a caller asks
• #182 Pg idempotency backend — separate issue; this PR paves the psycopg3 dep path they'll share

Test plan

• pytest tests/conformance/signing/ -q — 239 passed, 2 skipped (Pg tests skip without env var)
• ADCP_PG_TEST_URL=... pytest tests/conformance/signing/test_pg_replay_store.py -v — all 16 pass locally
• ruff check src/adcp/signing/ tests/conformance/signing/ — clean
• mypy src/adcp/signing/ — clean (18 source files)
• CI: pg-replay-store job runs full suite against Postgres 16 service

🤖 Generated with Claude Code

[gitguardian]

️✅ There are no secrets present in this pull request anymore.

If these secrets were true positive and are still valid, we highly recommend you to revoke them.
While these secrets were previously flagged, we no longer have a reference to the
specific commits where they were detected. Once a secret has been leaked into a git
repository, you should consider it compromised, even if it was deleted immediately.
Find here more information about risks.

---

^{_{🦉 GitGuardian detects secrets in your source code to help developers and security teams secure the modern development process. You are seeing this because you or someone else with access to this repository has authorized GitGuardian to scan your pull request.}}