feat: FeedMirror — client-side wholesale feed mirror for products/signals

[bokelley]

Closes #900

What

Adds FeedMirror, a client-side helper that maintains an in-memory mirror of an AdCP agent's wholesale product and signal feeds, implementing the AdCP 3.1 wholesale-feed sync pattern.

• bootstrap — initial full load via get_products(buying_mode="wholesale") and get_signals(discovery_mode="wholesale"), walking pagination cursors and recording wholesale_feed_version / pricing_version / cache_scope per feed.
• conditional refresh — re-reads each feed presenting the cached if_wholesale_feed_version (and if_pricing_version when known). unchanged: true short-circuits and leaves the replica untouched (build-then-swap; an unchanged probe never wipes the mirror).
• incremental webhook application — apply_webhook() applies denormalized product.* / signal.* events to the index in place (created/updated replace, priced re-prices, removed deletes) and updates the cached feed version.
• bulk-change re-bootstrap — a wholesale_feed.bulk_change webhook re-bootstraps only the feed named by affected_entity_type.
• Optional FeedStateStore persistence hook (survive restart without a cold re-bootstrap) and on_event callback.

Lives in src/adcp/feed_mirror.py, exported from the top-level adcp package — matching the established pattern for the RegistrySync sync helper. Built entirely on the generated wholesale_feed / product / signal types; no schema re-download, no ADCP_VERSION bump.

Context on the deferral gate

#900 was deferred pending JS adcp-client#2094 "stabilizing the TS shape". That issue does not exist, so the gate is stale. The JS SDK does ship a reference (src/lib/wholesale-feed-sync/, class WholesaleFeedSync). This port mirrors its core bootstrap / refresh / webhook / bulk-change semantics. The JS background-poll loop, capability auto-resolution, and EventEmitter surface are deliberately not ported — they are beyond #900's stated "Suggested scope" and add a large speculative API; deferred for a follow-up if demand appears.

Tests

tests/test_feed_mirror.py (14 tests, real types via .model_validate, in-memory seller stub — no HTTP mocking): bootstrap + pagination walk + wholesale-mode/account request assertions; incremental product & signal events; conditional-refresh no-op preserves the replica and re-presents cached version tokens; changed-feed refresh swaps the index; bulk_change re-bootstraps only the affected feed; state-store restore/persist; envelope-mismatch and failed-read error paths.

Verification

make lint, make typecheck, make typecheck-all, and the feed-mirror / import-layering / public-API tests all pass. The public-API snapshot was regenerated to register the 7 new intentional exports.

🤖 Generated with Claude Code

[aao-ipr-bot]

Clean port of the buyer side of the AdCP 3.1 wholesale-feed sync pattern. The build-then-swap discipline is the right shape — the replica is the load-bearing invariant, and an unchanged probe must never wipe it.

Things I checked

• Atomic swap holds. _commit (src/adcp/feed_mirror.py:442-453) only replaces the live index if not meta.unchanged. An unchanged: true short-circuit updates only the cached version tokens and leaves self._products / self._signals in place. Confirmed by test_conditional_refresh_unchanged_is_noop.
• Conditional-fetch token scoping is correct on the wire. _build_products_request / _build_signals_request (feed_mirror.py:396-399, 411-414) gate if_wholesale_feed_version on first_page only, and nest if_pricing_version inside the feed-version guard so pricing-version is never sent alone. Both match the normative descriptions in generated_poc/media_buy/get_products_request.py:236,242 ("pagination.cursor is NOT part of the scoping tuple", "MUST only be sent together with if_wholesale_feed_version"). ad-tech-protocol-expert: sound on points 1–6.
• Happy-path webhook apply does not spuriously raise. The notification_type != event.event_type integrity check at feed_mirror.py:492 compares a NotificationType StrEnum against a Literal value, both str-derived, so a valid envelope evaluates equal and never trips FeedMirrorError. code-reviewer verified against _str_enum.py.
• *.priced replaces, not merges. _apply_event (feed_mirror.py:535-537,547-549) does model_copy(update={"pricing_options": ...}) with the full post-change array — matches the schema's "NOT a delta — consumers replace" contract.
• Pagination terminates. _next_cursor returns a cursor only when has_more is true; has_more: true with cursor: null exits via the if cursor is None guard.
• Public surface is additive. 7 new exports, all new symbols, registered in tests/fixtures/public_api_snapshot.json. No removals, no signature changes, no required↔optional flips — feat: is the correct semver signal. No generated files touched; no ADCP_VERSION bump, as claimed.

Follow-ups (non-blocking — file as issues)

• State persistence is asymmetric. apply_webhook's incremental path persists via _persist_state (feed_mirror.py:506), but refresh, bootstrap, and the bulk_change re-bootstrap do not. After a refresh or bulk-change repair, the bumped wholesale_feed_version lives only in memory; a restart restores the stale persisted token. Self-healing (the stale token forces a full re-read on the next conditional fetch), so not corruption — but it silently defeats the restart optimization the state_store exists to provide. Persist on a successful swap, or document the asymmetry. (code-reviewer: Medium.)
• Webhook envelope check is incomplete. apply_webhook validates notification_type/notification_id against the embedded event, but not the third schema-mandated invariant: cache_scope MUST equal event.payload.applies_to.scope (schemas/cache/3.1.0-rc.9/core/wholesale-feed-webhook.json allOf). The generated Pydantic model doesn't encode that cross-field allOf, so model_validate won't catch a mismatched envelope either. Blast radius here is limited — a FeedMirror is single-account-scoped and doesn't multiplex scopes internally — but the cross-check is cheap and belongs next to the two it already does. (ad-tech-protocol-expert: caveat, not unsound.)
• New public exports aren't in the human-facing docs. Check README.md / AGENTS.md for FeedMirror drift, the same way RegistrySync is documented.
• No infinite-loop guard if a non-conformant seller returns a constant non-null cursor with has_more: true. A max_pages cap would harden the walk.

Minor nits (non-blocking)

1. _remember_webhook_version skips pricing_version by design (feed_mirror.py:553-557) — the webhook envelope carries no pricing token, so the retained-stale value correctly forces a full payload on the next refresh. One line of comment would save the next reader the trip to the schema.
2. Silent no-op on *.priced for an unmirrored id (feed_mirror.py:533,545). Defensible — a priced payload carries only pricing_options, nothing to insert — but the spec's reconciliation SHOULD means a missed created stays missing until the next bulk_change. A debug-log would make the gap observable.

Stale-deferral-gate note in the PR body is appreciated — citing a JS issue that doesn't exist is a notable way to defer a feature for two quarters.

LGTM. Follow-ups noted below. Ship it once CI is green.