Implement sponsor tier model (Gold/Silver/Bronze) with database constraints

[federicopfund]

Summary

This PR implements the definitive sponsor business model with three tiers (Gold/Silver/Bronze), each with distinct content scope, exclusivity rules, and concurrency limits. The changes enforce these rules at the database level through constraints and indexes, eliminating reliance on application-layer validation alone.

Key Changes

• Evolution 32 (conf/evolutions/default/32.sql): Core schema updates

  • Added publication_id FK to sponsor_agreements to support publication-level sponsorships
  • Introduced unit_type = 'platform' for Gold tier agreements (single agreement covering entire site)
  • Added sponsor_id, sponsor_label, sponsor_show_public columns to publications table (matching existing pattern in seasons/collections/events)
  • Implemented chk_agreement_tier_scope constraint to enforce tier-specific content scope:
    • Gold: only platform (all content)
    • Silver: event, newsletter, publication
    • Bronze: event, publication
  • Created unique partial indexes for exclusivity enforcement:
    • idx_sponsor_gold_exclusive: ensures max 1 active Gold agreement platform-wide
    • idx_sponsor_silver_event_exclusive, idx_sponsor_silver_publication_exclusive, idx_sponsor_silver_newsletter_exclusive: ensures max 1 active Silver per unit
  • Extended sponsor_deliverables types with Gold-exclusive surfaces: homepage_banner, site_header_badge

• Trigger (sql/trigger_sponsor_bronze_limit.sql): Bronce concurrency enforcement

  • Implements enforce_bronze_sponsor_limit() function to enforce max 2 active Bronze agreements per unit
  • Cannot be expressed as a unique index (limit > 1), so implemented as a trigger
  • Kept outside Play evolutions due to PL/pgSQL dollar-quoting incompatibility (same pattern as evolution 16)

• Documentation (docs/SPONSOR_TIER_MODEL.md): Comprehensive business model specification

  • Evaluates evolution 31 limitations and explains corrections
  • Details tier definitions, scope rules, and concurrency models
  • Explains database-level enforcement mechanisms
  • Documents visibility across content interfaces
  • Outlines scalability patterns and future application-layer work

Notable Implementation Details

• Gold exclusivity: Implemented via unique partial index on tier column where tier='gold' AND status='active', preventing database-level violations even if application logic fails
• Unit coherence: Constraint ensures exactly one FK is set per agreement based on unit_type, preventing data inconsistency
• Platform agreements: Gold tier uses unit_type='platform' with no FK to specific content, allowing single agreement to cover all content surfaces
• Backward compatibility: Evolution 32 includes proper !Downs section to safely rollback all changes
• Denormalization strategy: Sponsor fields replicated across content tables (seasons, collections, events, publications) to avoid join overhead on every render

https://claude.ai/code/session_011GvPuvd3UBUf1hPFRHNEza