feat(server): createMediaBuyStore — opt-in targeting_overlay echo (#1415)

[bokelley]

Summary

Closes #1415.

createAdcpServerFromPlatform gains a mediaBuyStore opt-in. When wired, the framework satisfies the seller spec contract for targeting_overlay echo on get_media_buys without each adapter persisting + merging by hand.

import { createAdcpServerFromPlatform, createMediaBuyStore, InMemoryStateStore } from '@adcp/sdk/server';

createAdcpServerFromPlatform(myPlatform, {
  mediaBuyStore: createMediaBuyStore({ store: new InMemoryStateStore() }),
});

The framework then:

• Persists packages[].targeting_overlay from create_media_buy requests, joined with seller-assigned package_id (or buyer_ref when supplied). Runs in the createMediaBuy projection so it covers both the sync arm AND the HITL completion arm.
• On get_media_buys, backfills missing packages[].targeting_overlay from the store. Packages the seller already echoed are left untouched.
• On update_media_buy, deep-merges the patched overlay against prior persisted: omitted keys keep prior, non-null values replace, explicit null clears. new_packages[] are persisted as fresh entries.

Backed by any AdcpStateStore (InMemoryStateStore for dev, PostgresStateStore for production). Account-scoped per-tenant via scopedStore. Failures logged + swallowed — auto-echo never breaks a successful seller response.

hello_seller_adapter_guaranteed.ts now wires mediaBuyStore by default — every fork inherits the contract for free.

Triage resolution: drops four stale suppressors

Triage flagged that test/lib/storyboard-drift.test.js:291–299 suppressed the four media_buy_seller/inventory_list_targeting/get_after_* assertions as UPSTREAM_SCHEMA_DRIFT per adcontextprotocol/adcp#2488. Verified directly: schemas/cache/3.0.5/media-buy/get-media-buys-response.json includes targeting_overlay on PackageStatus with prose mandating echo for sellers claiming property-lists/collection-lists. adcp#2488 is resolved by the 3.0 GA schema update; the suppressors are stale and dropped in this PR.

Test plan

• npx vitest run src/lib/server/media-buy-store.test.ts — 9/9 pass
• node --test test/lib/storyboard-drift.test.js — 498/499 pass (1 unrelated skip), 0 fail
• npx tsc --noEmit -p tsconfig.lib.json clean
• npm run format:check clean
• Storyboard media_buy_seller/inventory_list_targeting/get_after_create passes against the worked example (manual repro)

Companion follow-ups

• SDK: export MEDIA_BUY_TRANSITIONS + assertMediaBuyTransition for runtime use #1416 — export MEDIA_BUY_TRANSITIONS + assertMediaBuyTransition (still triaging at PR open).
• Storyboard runner: can't capture context_outputs.path from HITL task completion artifact #1417 — runner HITL context_outputs.path capture from task completion artifact (deferred; triage suggests Option 1 explicit-prefix or Option 4 storyboard YAML redesign).

🤖 Generated with Claude Code

[bokelley]

Fold candidate — issue #1430 (filed from the protocol-expert review on this PR).

persistFromCreate in media-buy-store.ts always sources targeting_overlay from the request package. The spec requires echoing what the seller actually persisted — for normalizing sellers (those that resolve agent_url, strip unknown fields, or canonicalize list_id before persisting), the echoed value diverges from what was stored.

The fix is small: in persistFromCreate, replace:

targeting_overlay: reqPkg.targeting_overlay,

with:

targeting_overlay: respPkg?.targeting_overlay ?? reqPkg.targeting_overlay,

media-buy-store.ts is new in this PR, so the fix fits naturally before merge — no separate PR or changeset needed beyond what's already here. The CreateMediaBuyResultForStore interface would also need targeting_overlay?: TargetingOverlay added to its package shape to type-check.

Blocked-on: #1424 posted on #1430.

---

Generated by Claude Code

[bokelley]

Applied the fold from #1430 in commit 3b7e6ab:

• CreateMediaBuyResultForStore.packages now includes targeting_overlay?: TargetingOverlay so the response shape is typeable.
• persistFromCreate now stores respPkg?.targeting_overlay ?? reqPkg.targeting_overlay — normalizing sellers that mutate the overlay before echoing will have their canonical form persisted, not the raw request value.

All 9 media-buy-store.test.ts tests pass on the updated diff.

---

Generated by Claude Code

[bokelley]

Acknowledged — the fold from #1430 looks clean. The respPkg?.targeting_overlay ?? reqPkg.targeting_overlay normalization is the right call: sellers that canonicalize the overlay before echoing now have their version persisted rather than the raw request value, which is what the spec intends. All 9 tests green is a good signal. No further action needed from triage.

---

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

---

Generated by Claude Code