website refactor

plans/website-architecture-violations.md

@@ -321,7 +321,45 @@ Rule violated:
 
 Action:
 
-- Refactor `DriverService.getDriverProfile()` (and any similar methods) to return Page DTO only when used from server paths.
+- Refactor any service method used by a PageQuery that currently returns a ViewModel to return a Page DTO instead.
+
+---
+
+## 12) Generic integrity rules for untrusted transport data (no case studies)
+
+This is the durable architectural rule behind the “`as` looks vulnerable” concern.
+
+### 12.1 Rule: treat API Transport DTO values as untrusted input
+
+Even with OpenAPI generation, runtime values can drift (backend bug, contract mismatch, migrations, older clients).
+
+Therefore:
+
+- Never use `as SomeClosedUnion` on fields coming from an API response.
+- Never assume string enums are safe.
+
+### 12.2 Where validation/coercion belongs
+
+- **API Transport DTO** remains raw (what the API sent).
+- **Page DTO** can remain raw but should be structurally stable.
+- **Presenter/ViewModel** is the correct place to normalize/coerce *for UI resilience*.
+
+This keeps the website as a delivery layer: we’re not enforcing business rules; we’re preventing UI crashes.
+
+### 12.3 Required pattern: parsers for string unions
+
+Define small pure parsers (in a Presenter-adjacent module) for every “closed set” field:
+
+- `parseSocialPlatform(value: unknown): SocialPlatform | 'unknown'`
+- `parseAchievementIcon(value: unknown): AchievementIcon | 'unknown'`
+- `parseAchievementRarity(value: unknown): AchievementRarity | 'unknown'`
+
+Policy (agreed):
+
+- ViewModel keeps `'unknown'` for debugging/telemetry.
+- ViewData omits unknown items (UI stays clean).
+
+This keeps code safe without turning the website into a second source of truth (the API still owns validation).
 
 ---