feat(legacypurchase): Postgres-backed Backend + reverse compact-seller facade (follow-up to #466)

[sujanchalla0510]

Context

Follow-up to #466 ("feat: implement durable legacy purchase continuation
coordinator for AdCP 3.2"). The core coordinator API, durable-store
interface, and a well-tested in-memory reference backend
(adcp/v3/legacypurchase) are implemented in a companion PR against #466 —
see that PR for the coordinator itself (Store.RegisterContinuation,
Store.ContinueLegacyPurchase, atomic single-use claim proven under
-race, deterministic replay, fail-closed crash reconciliation via
AmbiguousClaimError, and the products-only-brief-compatibility vectors
from the AdCP 3.2 schema bundle run end to end).

Two pieces of #466's scope were deliberately deferred out of that PR rather
than forced into one oversized change, and are tracked here:

1. Persistent (e.g. Postgres) legacypurchase.Backend implementation

adcp/v3/legacypurchase ships the pluggable Backend interface and
MemoryBackend (in-process) only. MemoryBackend is process-local — a
restart loses in-flight and recently-completed continuation state, which is
unacceptable for a production coordinator meant to prevent double-purchase
across a real deployment (potentially multiple instances behind a load
balancer, matching the same durability motivation as #105 /
adcp/v3/signing/pgreplay's PostgresReplayStore).

Scope for this half:

• A PostgresBackend implementing legacypurchase.Backend's three-state
  claim/commit/fail FSM atomically (unique constraint on token +
  conditional UPDATE ... WHERE token = $1 AND state = 'offered' for
  ClaimPending, mirroring adcp/v3/idempotency's PgBackend and
  adcp/v3/signing/pgreplay's atomic-insert pattern).
• A real concurrency proof against a live Postgres instance (e.g.
  testcontainers-go, matching this repo's existing
  registry/redisstore / registry/glidestore /
  adcp/v3/signing/pgreplay integration-test convention): many concurrent
  distinct-key claims against one continuation token, exactly one winner,
  under -race.
• A migration/schema file and SweepExpiredReplays-equivalent retention
  sweep for terminal and expired-offered records (never sweeping
  StatePending — see the core PR's MemoryBackend for why).

2. Reverse compact-seller → legacy-buyer server-side facade

The spec's "Established buyers against a compact-backed seller" section
(specs/legacy-compact-lifecycle-compatibility.md) and
static/compliance/source/test-vectors/products-only-brief-compatibility/vectors.json's
reverse_compatibility_cases describe the opposite direction from the
coordinator in the core PR: a 3.2 seller that implements refine_proposals
etc. natively but must still preserve its deprecated get_products /
create_media_buy facades for established buyers — using "a private atomic
coordinator" internally rather than a buy-then-sync compensating saga.

This is seller-side adapter work — a materially different scope from the
buyer-side coordinator in #466 / the core PR (different failure surface: the
seller owns both the compact and legacy code paths and must keep them
transactionally consistent, rather than redeeming an opaque token issued by
someone else). It needs its own design pass (at minimum: how a seller
built with this SDK's adcp/v3 package would wire a legacy facade through
its native compact handlers) before implementation.

Acceptance criteria

• legacypurchase.PostgresBackend (or similarly named) implements
  Backend with atomic claim/commit/fail transitions.
• Concurrency proof against a live Postgres instance under -race.
• Reverse-facade design doc or PR covering at least the
  reverse_compatibility_cases vector.
• Both pieces may ship as separate PRs / separate follow-up issues if
  that turns out cleaner once scoped in detail — this issue exists to
  track that they are real, disclosed, not-yet-done work rather than to
  mandate exactly one combined PR.

[bokelley]

Triage

Classification: Feature request — durable persistence backend + seller-side protocol facade
Bucket(s): SDK (adcp/v3/legacypurchase sub-module; no tmpclient/tmproto label exists in this repo — gap noted in run summary)
Status: deferred

Blocked-on: #466 — resurfaces on merge.

Both work items are explicitly gated on #466's companion PR landing and the AdCP 3.2 coordinator contract stabilizing from beta. The legacypurchase.Backend interface, MemoryBackend, and the pgreplay.PostgresReplayStore cited as prior art are not yet in the repo. There is nothing to build against until the parent issue closes.

What the experts said:

• code-reviewer: PostgresBackend FSM approach (conditional UPDATE … WHERE state = 'offered') and testcontainers-go test strategy follow existing repo patterns; facade deferral is correct — blocked on feat: implement durable legacy purchase continuation coordinator for AdCP 3.2 #466 and under-specified as written.
• ad-tech-protocol-expert: FSM structure is directionally sound and the StatePending-exclusion sweep invariant is correct; however, both work items depend on prerequisites not yet in the repo, and AdCP 3.2's coordinator contract is still schema-beta — defer until feat: implement durable legacy purchase continuation coordinator for AdCP 3.2 #466 lands and the wire version stabilizes; require a standalone design doc for the reverse-facade translation layer before implementation.
• security-reviewer: No TEE-path widening from the PostgresBackend sub-module; the "never sweep StatePending" policy introduces a Medium risk — an unbounded-growing pending table is a DoS vector and produces phantom conflicts (a crashed claim permanently blocks future claims on the same key with no operator recovery path); the compact-seller facade must not land without an explicit field-level design review confirming no catalog-data over-sharing to legacy buyers; testcontainers-go follows existing repo precedent.

My take: Both items are correctly scoped but have a hard ordering dependency on #466. When #466 merges, Part 1 (PostgresBackend) will be ready-to-implement with one pre-ship gate: the "never sweep StatePending" invariant needs a bounded pending lifetime or an operator sweep tool before the backend can be used safely in production. Part 2 (reverse compact-seller facade) needs its own design doc covering the reverse_compatibility_cases vectors before entering the implementation queue.

---

Triaged by Claude Code. Session: https://claude.ai/code/session_019mmBenmafVZkZ2KFkrgwvx

---

Generated by Claude Code