feat(handlers): expose sync_catalogs through sales-catalog-driven specialism

[bokelley]

Closes #786

Re-cut of #790 from current main (19fde5e). PR #790 was conflicting (dirty) with maintainer edits disabled; this branch is a clean re-apply of the same logic on top of 6.1.0-beta.1.

Summary

• Wire sync_catalogs into SPECIALISM_TO_ADVERTISED_TOOLS so sales-catalog-driven platforms expose the tool via tools/list
• Add PlatformHandler.sync_catalogs dispatcher — full SyncCatalogsRequest passed through (no arg_projector) so adopters can inspect req.delete_missing, req.dry_run, req.validation_mode, and req.catalog_ids
• Add sync_catalogs to SalesPlatform Protocol body (required section, sales-catalog-driven only)
• Add _require_platform_method("sync_catalogs") guard — non-catalog-driven platforms that somehow receive the call surface UNSUPPORTED_FEATURE instead of INTERNAL_ERROR
• Add sync_catalogs to _OPTIONAL_PLATFORM_METHODS (specialism-gated variant — absent on all non-sales-catalog-driven platforms)
• Add examples/hello_seller_catalog.py — runnable minimal adopter with discovery mode, delete_missing guard, and ergonomic list return
• Add MIGRATION_v5_to_v6.md 6.1.0-beta.1 entry documenting SalesPlatform @runtime_checkable isinstance behavior change
• Fix _SyncSalesPlatform test fixture to remain structurally conformant with SalesPlatform

Protocol note: sync_catalogs on the shared SalesPlatform Protocol

Adding sync_catalogs to the shared SalesPlatform Protocol (rather than a separate CatalogDrivenPlatform mixin) is intentional and consistent with how sync_audiences is handled on AudiencePlatform. The consequence is that isinstance(platform, SalesPlatform) now requires sync_catalogs for structural conformance — non-catalog-driven platforms that use this check need a stub. This is documented in MIGRATION_v5_to_v6.md. A separate CatalogDrivenPlatform mixin would be cleaner but is a larger structural change; see code-reviewer sign-off below.

What was tested

• pytest tests/test_decisioning_advertised_per_specialism.py tests/test_decisioning_dispatch.py tests/test_decisioning_handler_shims.py tests/test_decisioning_specialisms.py tests/test_lazy_platform_router.py — 235 passed
• ruff check src/ — clean
• python -m mypy src/adcp/decisioning/handler.py src/adcp/decisioning/specialisms/sales.py — clean

Nits (not fixing in this PR):

• _require_platform_method message says "optional method" — technically imprecise for sync_catalogs on sales-catalog-driven, but validate_platform (called from serve()) hard-fails at boot before any buyer reaches this gate; the backstop is only reachable via programmatic PlatformHandler construction without serve(). Pre-existing pattern used by 8 other methods.
• _maybe_auto_emit_sync_completion fires on dry_run=True requests — pre-existing pattern shared with sync_audiences; sync_catalogs in webhook_emit._SYNC_COMPLETION_METHODS is already present on main.
• MaybeAsync[SyncCatalogsSuccessResponse] Protocol return type doesn't formally include the ergonomic list[SyncCatalogResult] arm — pre-existing mismatch shared with sync_audiences.

Pre-PR review

code-reviewer: No blockers. Design concern noted (shared Protocol body vs. separate mixin) — explained above as intentional pattern. 1 nit (inline fixture duplication across 3 shim tests). Approved.

dx-expert: Approved (2nd pass). Previous blockers resolved: example added, _SyncSalesPlatform fixture fixed, migration note added. No new blockers.

---

Triage-managed PR. This bot does not currently iterate on
review comments or PR conversation threads (only on the source
issue). To unblock:

• Push fixup commits directly: gh pr checkout <num> →
  fix → push.
• Or re-trigger: comment /triage execute on the source
  issue.

See adcp#3121
for context.

Session: https://claude.ai/code/session_01NYBCVdwct1Hhz7GD1eaEHr

---

Generated by Claude Code