Add Samsung Wallet support

[Korbeil]

Summary

This PR adds comprehensive Samsung Wallet support to wallet-kit, extending the library's multi-platform abstraction to cover Apple, Google, and Samsung Wallet. Samsung Wallet uses a unified JSON envelope model (unlike Google's Class+Object split), with 8 card
types that map to the existing 7 cross-platform verticals plus 2 Samsung-only types.

Motivation

wallet-kit already abstracts Apple Wallet and Google Wallet with a fluent builder API and typed PHP models. Adding Samsung Wallet completes coverage of the three major mobile wallet platforms, allowing developers to build passes for all three from a single
source.

Changes

Models (src/Pass/Samsung/Model/)

• Card envelope: Card, CardData, Localization — unified JSON structure with single card type per envelope
• 8 card types: BoardingPass, EventTicket, Coupon, GiftCard, Loyalty, Generic, DigitalId (Samsung-only), PayAsYouGo (Samsung-only)
• Shared models: SamsungImage (dark/light variants), SamsungBarcode (serialType-based), Location (lat/lng)
• Enums: CardTypeEnum, CardSubTypeEnum (14 subtypes), SerialTypeEnum

Normalizers (src/Pass/Samsung/Normalizer/)

• Card envelope normalizers (Card, CardData, Localization)
• 8 vertical attribute normalizers handling Samsung-specific formats:
  • Y/N boolean serialization ("Y"/"N" instead of true/false)
  • 13-digit epoch millisecond timestamps
  • Hex color codes
  • Null field omission for compact JSON

Builder Integration

• SamsungWalletContext: refId, language, app link fields (required by Samsung)
• Mappers:
  • SamsungBarcodeMapper — Apple → Samsung barcode format conversion
  • SamsungBoardingPassSubTypeMapper — Transit type → Samsung subtype mapping
• WalletPlatformContext refactored to fluent builder pattern:
  • Removed static factories (::both(), ::all(), etc.)
  • Added instance methods: withApple(), withGoogle(), withSamsung()
  • Runtime validation: exceptions thrown when accessing unavailable platforms
• All 7 vertical builders updated to produce Samsung Card output
• CommonWalletBuilderTrait extended: mutateSamsung(), createSamsungCard(), primarySamsungBarcode(), resolvedSamsungHexColor()

Spec Verification (tools/spec/)

• samsung-wallet-keyset.php — extracts @phpstan-type keys from Samsung models (mirrors Apple approach)
• samsung-wallet-keyset.json — baseline for CI spec-check validation
• castor.php — added spec:check:samsung and spec:baseline:samsung tasks

Tests & Documentation

• DualWalletBuilderTest.php: 41 tests → 55 tests (added Samsung test cases, immutability checks)
• SamsungNormalizerTest.php: comprehensive test coverage for all 8 card types and edge cases
• BuilderTestSerializerFactory.php: registered all 21 Samsung normalizers
• README.md: Samsung Wallet section, updated builder overview
• docs/builder-examples.md: updated all 8 examples with new fluent API, added Samsung-only example

Key Architectural Decisions

1. Single Card model (not Class+Object like Google) — Samsung payload is simpler, single JSON envelope
2. Digital ID & PayAsYouGo — Samsung-only, no Apple/Google equivalent; built directly via models, not via WalletPass factory methods
3. Fluent builder context API — immutable instance methods instead of static factories, simplifies parameter naming and progressive composition
4. Runtime validation — constructor accepts any combination; runtime exceptions when accessing unavailable platforms
5. Keyset-based spec check — Samsung has no public API versioning, so baseline uses phpstan-type extraction (like Apple)

Verification

• ✅ PHPStan: 0 errors across 261 files
• ✅ PHPUnit: 55 tests, 967 assertions, all passing
• ✅ PHP-CS-Fixer: 0 files needing fixes
• ✅ Spec checks: apple, google, samsung all pass baseline validation

Notes for Reviewers

• Samsung timestamps use 13-digit epoch milliseconds (different from Unix seconds)
• Booleans serialize as "Y"/"N" strings per Samsung spec
• App link fields (appLinkLogo, appLinkName, appLinkData) are required on all Samsung card types
• WalletPlatformContext API change is breaking: users upgrade from WalletPlatformContext::both(...) to (new WalletPlatformContext())->withApple(...)->withGoogle(...)