feat(legacypurchase): add durable legacy purchase continuation coordinator

[sujanchalla0510]

Summary

Implements the Go SDK-local durable coordinator for redeeming a deprecated
AdCP 3.2 products_available legacy_create purchase continuation — the
equivalent of the protocol's
continueLegacyPurchase(CompatibilityPurchaseCoordinatorInput), addressing
#466.

• New package: adcp/v3/legacypurchase
  (Store.RegisterContinuation, Store.ContinueLegacyPurchase,
  Backend interface, MemoryBackend reference implementation).
• Contract source: specs/legacy-compact-lifecycle-compatibility.md from
  adcp#6733 (merged
  2026-08-20, resolving
  adcp#6716) and
  the media-buy/legacy-purchase-continuation-input.json schema from the
  3.2.0-beta.9 bundle this SDK already pins at adcp/v3/schemas/VERSION
  — confirmed byte-identical (formatting aside) between the bundle I
  downloaded locally via adcp/v3/schemas/download.sh and the source repo.
• Test vectors: static/compliance/source/test-vectors/products-only-brief-compatibility/
  from the same bundle, vendored at
  adcp/v3/legacypurchase/testdata/products-only-brief-compatibility/
  (see its PROVENANCE.md) and run end to end in vectors_test.go.

Design

Modeled on the two existing "durable, pluggable, atomic-claim" packages in
this codebase — adcp/v3/idempotency (PutIfAbsent-based replay) and
adcp/v3/signing/pgreplay (atomic-insert replay-cap enforcement) — rather
than inventing a new shape. Widened from idempotency's single
PutIfAbsent into an explicit three-state FSM
(StateOffered -> StatePending -> StateCommitted/StateFailed) because
redeeming a continuation is a genuinely two-phase operation: claim the
token, then call an external legacy seller whose outcome isn't known at
claim time. A crash between those two phases must be observable as
StatePending, not silently lost (double-purchase) or silently fabricated —
this is exactly the security-reviewer concern noted in #466's own triage
thread ("the three-state FSM requirement ... is semantically distinct from
PutIfAbsent replay — conflating them would be a correctness footgun").

CompatibilityPurchaseCoordinatorInput is hand-written rather than
generated: the schema is x-adcp-sdk-local: true and is not reachable by
$ref from any AdCP tool's request/response schema, so
adcp/v3/schemas/generate.py's auto-discovery does not produce a Go type
for it. Verified by downloading the pinned 3.2.0-beta.9 bundle and
regenerating types_gen.go locally — no
CompatibilityPurchaseCoordinatorInput / PurchaseContinuation type is
emitted, confirming this is by design, not a generator gap.

Scope decision (disclosed)

#466's full scope — durable pluggable store + a persistent backend + the
complete reverse compact-seller→legacy-buyer facade + full per-legacy-
version request-schema validation — is more than one well-verified PR
should carry. This PR ships a solid, fully-tested core: the coordinator
API, the durable-store interface, and a well-tested in-memory reference
backend, covering every one of #466's acceptance-criteria bullets an
in-memory backend can genuinely satisfy:

• Coordinator API and durable-store interface are public and documented.
• Concurrent claims cannot purchase twice — store_race_test.go,
  64 goroutines with distinct idempotency keys racing one continuation
  token under -race, exactly one wins, Executor called exactly once.
• Retry after success returns the deterministic prior result —
  exercised both directly (TestContinueLegacyPurchase_RetryReturnsDeterministicPriorResult)
  and against every vector case.
• Ambiguous/crashed claims fail closed and expose recovery guidance —
  AmbiguousClaimError, distinct from the ordinary in-flight case
  (InFlightError), gated by Options.PendingLeaseTimeout.
• Principal/account/version/expiry/payload mismatches are rejected —
  every one has a typed error and a dedicated test.
• Shared beta.4+ compatibility vectors pass — vectors_test.go runs
  every cases[] entry (AdCP 2.5/3.0/3.1) end to end, plus the
  negative mutations (product substitution, package-selection drift,
  incomplete/stale loss consent, wrong account, expiry) the vector
  bundle's own README documents as SDK-suite-constructed (the upstream
  bundle does not ship separate negative JSON fixtures).
• Migration guidance explains what remains application-owned — see
  adcp/v3/legacypurchase/README.md.

This does not complete #466. Deferred and tracked in
#482:

1. A persistent (e.g. Postgres) Backend implementation — this PR ships
   the interface + MemoryBackend only, mirroring how
   adcp/v3/idempotency's Postgres adapter and adcp/v3/signing/pgreplay
   shipped as their own follow-on work in this same PR sequence.
2. Full per-source-version (2.5/3.0/3.1) create_media_buy request schema
   validation. This PR enforces the structural rules tied directly to
   atomicity/single-use-claim safety (explicit-package mode, exact
   package-product-ID match, the account cross-check) — not a complete
   replica of each legacy version's schema, which adcp/v3 (an AdCP
   3.x-only module) does not vendor. Disclosed in the README's migration
   guidance as application-owned.
3. The reverse compact-seller → legacy-buyer server-side facade (the
   spec's "Established buyers against a compact-backed seller" section,
   vectors.json's reverse_compatibility_cases) — materially separate,
   seller-side adapter scope.

listed_purchase is not a deferral: per the spec it passes seller-issued
feed/pricing values straight into ordinary buy_products, with no durable
continuation state to claim — nothing for this coordinator to do there.

Verification

cd adcp/v3
gofmt -l legacypurchase/            # clean
go build ./legacypurchase/...       # clean
go vet ./legacypurchase/...         # clean
golangci-lint run ./legacypurchase/... # 0 issues
go test -race -count=1 ./legacypurchase/...  # 26 tests, all pass
go test -race -count=1 ./...        # whole module, all pass (idempotency/signing/webhook untouched)

git status clean; the adcp/v3/schemas/*.json files I downloaded locally
to inspect and cross-check the schema are gitignored and not part of this
diff.

Test plan for reviewers

• cd adcp/v3 && go test -race -count=1 ./legacypurchase/...
• Skim store_race_test.go for the concurrency proof shape (mirrors
  adcp/v3/idempotency/store_race_test.go's existing convention).
• Skim testdata/products-only-brief-compatibility/PROVENANCE.md for
  exactly which vector sections are and aren't exercised, and why.

[garvitkaushik-123]

Could you take a look at four cases I reproduced locally? I saw the scope notes about the persistent backend and full legacy schema validation. These cases concern the identity checks, saved pricing, and replay behavior in the current coordinator.

1. Checking the buyer on a retry. After completing a purchase as one buyer, I repeated the same token, idempotency key, and request under a different authenticated buyer. It returned the first buyer's saved result. The replay path receives principal but never checks it. Could we verify the buyer before returning a saved result or operation state?

2. Checking the selected pricing option. Using the shared AdCP 3.0 test vector, I changed only pricing_option_id from fixed-cpm to an option absent from the saved product information. The execution callback still ran. ObservedPayload is stored, but the validation before claiming never checks against it. Could we check that the selected pricing belongs to the saved observation before proceeding? This is the comparison with the saved offer, separate from validating the request's JSON structure.

3. The additional AdCP 2.5 risk declaration. Registration accepted a 2.5 continuation without mutation_idempotency_not_guaranteed, and the execution callback ran after accepting only the other two declared risks. Could registration reject a 2.5 continuation missing that required declaration? The existing equality check does work when all required risks were registered correctly.

4. Keeping saved responses unchanged. With MemoryBackend, changing a byte in a returned replay response also changed the response returned by the next retry. The returned record is only a shallow copy, so it still shares the saved response bytes. Could we copy the mutable data when storing and returning records, and add a test confirming callers cannot change a saved response this way?

The pricing check and the additional 2.5 declaration are both covered by the compatibility contract. Happy to clarify any of the reproduction steps if useful.

[bokelley]

All four cases reproduced and fixed in 844af1a. Here's what each fix does:

1. Principal check on replay (resolveNonOffered).
Added a principal guard at the top of resolveNonOffered — before checking the idempotency key or revealing any claim metadata. A different authenticated buyer now gets PrincipalMismatchError rather than the first buyer's committed result. Deliberately placed before the ClaimantKey check so a mismatched principal cannot even learn whether their idempotency key matches the claimant's.

2. Pricing option validation (validateBinding).
Added a new validatePricingOptions helper called from validateBinding. It parses the packages from legacy_create_request, and for any package that carries a pricing_option_id, verifies that ID is present in rec.ObservedPayload (the compact_projection.products array bound at registration) for the named product. Returns a new PricingOptionError on mismatch. The check is skipped entirely when no package specifies a pricing_option_id, so existing requests that omit the optional field are unaffected.

3. AdCP 2.5 risk declaration (RegisterContinuation).
Added a check immediately after the existing two-loss baseline check: when SourceADCPVersion has prefix "2.5", mutation_idempotency_not_guaranteed is also required in Losses. The check is version-gated so 3.0/3.1 registrations (which don't declare that loss) are unaffected.

4. MemoryBackend deep copy.
Added a deepCopyRecord helper that clones ObservedPayload, Result, ProductIDs, and Losses on every copy. PutContinuation now stores a deep copy so caller mutations after registration don't reach the backend; GetContinuation returns a deep copy so caller mutations of the returned record (including Response bytes from a committed replay) don't corrupt the stored state. New test TestMemoryBackend_MutatingReturnedResponseDoesNotAffectReplay confirms the invariant.

All 35 tests pass with -race -count=1; full module (idempotency/signing/webhook) is clean.

---

Generated by Claude Code

[aao-secretariat]

Medium: resolveNonOffered never re-checks the principal — the principal parameter is threaded in (L219) and left unused. The confused-deputy guard fires only on the StateOffered claim path (validateBinding, L185). Every replay/pending/committed resolution keys off continuation_token alone.

Unlike adcp/v3/idempotency, which bakes the principal into the storage scope key so cross-principal collision is structurally impossible, this store keys records by a global continuation_token. A different authenticated principal presenting a StateCommitted token plus the original claimant's idempotency_key and matching payload hash reaches return &Result{Response: rec.Result, Replayed: true} (L244) and replays another principal's create_media_buy response — no principal check. The StatePending/AlreadyClaimedError branches likewise act on another principal's continuation without one.

Add if rec.Principal != principal { return nil, &PrincipalMismatchError{Token: rec.Token} } at the top of resolveNonOffered. The dead principal param is the tell the check was intended. Gated behind knowing the claimant's UUID today, but this is exactly the tenant-binding guard the package advertises.

[aao-secretariat]

Ladon verdict: Approve

Approve — new additive package adcp/v3/legacypurchase (a durable claim-once coordinator for legacy_create purchase continuations).

What I checked:

• Purely additive PR (2579 additions, 0 deletions); 13 new files, all under the new legacypurchase package.
• No touches to adcp/schemas/**, adcp/types_gen.go, tmproto/*, reference/identity-agent/**, or skills/** — none of the mandatory schema/TMP/TEE/protocol-skill gates apply.
• No exported-symbol removal/rename on the wire/public-API path, so no conventional-commit breaking marker is required.
• Atomic FSM (Offered→Pending→Committed/Failed), single-use claim, exec-at-most-once, and fail-closed crash reconciliation are proven under -race.
• gated_paths: false, high_risk: false, no no-auto-approve team match.

Medium findings:

• store.go:220 — resolveNonOffered drops the principal re-check on the replay/pending/committed path; a different principal with the claimant's idempotency_key + matching payload could replay another principal's result.

Decision-table application: no critical/high findings (row 1 no); gated_paths false (row 2 no); no deletions (row 3 no); the single medium is not data-loss/schema/infra category and high_risk is false (rows 4/5 no); no prior escalation (row 6 no); no team gate (row 7 no); only 1 medium finding, fewer than 3 (row 8 no) → falls through to row 9: approve. The lone medium does not block. Worth a follow-up look at the principal re-check, but not a gate blocker.

[bokelley]

Please address the inline principal-binding finding before merge. resolveNonOffered must re-check rec.Principal before exposing pending or terminal state or replaying a committed result; continuation tokens cannot become a cross-principal response pinhole.

[sujanchalla0510]

Fixed in dcb8a11, all four:

1. Principal check on replay — resolveNonOffered received principal but never checked it. Now checks rec.Principal != principal first, before ClaimantKey/RequestHash, so a claimed/committed/failed continuation can't replay its result or leak state to a different principal reusing the idempotency_key. New test: TestContinueLegacyPurchase_ReplayRejectedForDifferentPrincipal.
2. Pricing-option substitution — added validatePricingSelection, called from validateBinding: a package's pricing_option_id must be present among the continuation's observed pricing_options for that product (the spec's "complete observed product/pricing payload" binding). New PricingSelectionError, new test TestContinueLegacyPurchase_PricingSubstitutionRejected.
3. 2.5 risk declaration — RegisterContinuation now rejects a SourceADCPVersion == "2.5" continuation that doesn't also declare mutation_idempotency_not_guaranteed. New test TestRegisterContinuation_Rejects25WithoutMutationIdempotencyLoss.
4. Shallow-copy aliasing — every MemoryBackend accessor did cp := *rec, which still shares ObservedPayload/Result/etc. backing arrays with the stored record. Added cloneRecord (deep-copies the mutable slice fields), used everywhere. New test TestMemoryBackend_ReturnedRecordMutationDoesNotCorruptStore reproduces your exact repro (mutate a byte in a replay response, confirm the next retry is unaffected).

Also had to fix store_test.go's validFixture: its ObservedPayload was shaped as {"products": [...string]} rather than the real bare-array-of-product-objects contract vectors_test.go uses — harmless before since nothing parsed it, but #2 needed a real shape to validate against.

Generated by Claude Code

[aao-secretariat]

Ladon verdict: Approve

Approve — clean delta pass, no blocking findings.

This PR adds a new adcp/v3/legacypurchase package (all files additions, 0 deletions) with tests. The reviewer found no Critical/High/Medium findings. The changes since the prior review are pure hardening with tests: cloneRecord deep-copies all four mutable slice fields (no store aliasing), resolveNonOffered now checks principal before disclosing claim state (closes a confused-deputy replay leak), validatePricingSelection fails closed on unoffered pricing options, and AdCP 2.5 mutation-idempotency loss is enforced at registration.

Gate checks:

• No no-auto-approve team match (row 7 does not fire).
• gated_paths: false — row 2 does not apply. (review_decision is CHANGES_REQUESTED, but the deterministic gated-paths gate only bites when gated_paths is true; the standalone review status does not force escalate.)
• high_risk: false — rows 3/5 do not fire.
• No schema/generated-type, TMP signing, TEE, or protocol-skill surfaces touched; no exported-symbol wire changes requiring a conventional-commit marker.
• Prior decision was approve, so sticky escalation (row 6) does not apply.
• Zero medium findings — rows 1, 4, 8 do not fire.

None of rows 1–8 match; falls through to row 9 → approve.