# Live Tournament Data Update Plan

This plan describes how Fan Passport content should be updated during FIFA World Cup 2026 live play. The goal is to keep fixtures, results, predictions, challenges, stickers, quizzes, and memories accurate without spoiling fans or corrupting progress.

## Objectives

- Keep match schedules, statuses, results, standings, and bracket paths current.
- Settle predictions reliably and idempotently.
- Update dynamic challenge targets such as “watch every England match” as teams advance.
- Unlock stickers, quizzes, memories, and achievements at the correct time.
- Preserve a complete audit trail for every live-data change.
- Allow safe rollback when a feed or operator publishes incorrect data.

## Data sources

Use an explicit source priority list:

1. Official tournament data feed or licensed sports data provider.
2. Manual operations console using official match reports.
3. Editorial override for non-result content such as quiz copy, memory prompts, and sticker drop windows.

Every live update should record:

- Source name
- Source event ID or URL when available
- Ingest timestamp
- Operator or job ID
- Base content version
- Patch ID
- Reason for update
- Whether the update is automatic, manual, or corrective

## Content states

### Static preseason content

Examples:

- Tournament structure
- Host countries
- Stadium pages
- Evergreen trivia
- Sticker album definitions
- Generic achievements
- Generic challenge templates

Update cadence:

- As needed before tournament
- Locked at tournament start except for corrections

### Draw-dependent content

Examples:

- Group assignments
- Group-stage match participants
- Group collection challenges
- Group winner prediction options

Update cadence:

- Immediately after official draw confirmation
- Revalidated after any schedule revision

### Matchday live content

Examples:

- Match status
- Lineups
- Goals
- cards
- halftime/full-time status
- Result finalization
- Matchday moments stickers
- Post-match quiz unlocks
- Match check-in windows

Update cadence:

- Scheduled pre-match sync
- Live polling or webhook handling during match
- Final reconciliation after official report

### Knockout-dependent content

Examples:

- Bracket slots
- Round of 32/16/quarter/semi/final participants
- Dynamic team journey targets
- Knockout prediction options
- Final foil sticker drops

Update cadence:

- After each feeder match is marked final
- Full bracket reconciliation at the end of every matchday

### Post-tournament content

Examples:

- Champion
- Golden Boot
- final standings
- tournament awards
- final memories
- long-term commemorative stickers
- migration into future passport products

Update cadence:

- After final official reports
- After award confirmation
- Archive snapshot once all predictions and achievements settle

## Recommended update pipeline

1. **Ingest**
   - Pull or receive official data.
   - Normalize team, stadium, match, and provider IDs into Fan Passport IDs.
   - Store raw payload for audit and replay.

2. **Validate**
   - Validate syntax and schema.
   - Validate status transition legality.
   - Validate referential integrity.
   - Validate spoiler gates.
   - Reject or quarantine impossible updates.

3. **Transform to patch**
   - Create a small content patch rather than rewriting full seed files.
   - Include old value, new value, source, timestamp, and reason.
   - Mark patch type: fixture, result, standings, bracket, content, settlement, correction.

4. **Dry-run**
   - Apply patch to a copy of current content state.
   - Recalculate standings, bracket slots, prediction settlement candidates, and challenge dynamic targets.
   - Produce a diff for monitoring.

5. **Publish**
   - Apply patch atomically.
   - Increment content state version.
   - Emit events for downstream systems.

6. **Recalculate**
   - Recalculate affected challenge progress.
   - Settle affected predictions.
   - Unlock affected quizzes, stickers, memories, and achievements.
   - Ensure jobs are idempotent.

7. **Monitor**
   - Track feed freshness, validation errors, patch lag, settlement lag, and rollback count.
   - Alert operators if official match status is stale near kickoff, halftime, full time, or bracket advancement.

8. **Archive**
   - Store patch, raw source payload, validation result, and downstream effects.
   - Keep enough history to rebuild any user’s progress.

## Patch model

A live patch should have this conceptual shape:

```json
{
  "patchId": "patch_2026_06_11_match_001_final",
  "contentVersionFrom": "2026.0.1",
  "contentVersionTo": "2026.0.2",
  "source": {
    "type": "official_feed",
    "name": "licensed-provider-or-official-feed",
    "sourceEventId": "provider-match-001",
    "ingestedAt": "2026-06-11T22:05:00Z"
  },
  "changes": [
    {
      "entity": "match",
      "entityId": "match-001",
      "field": "status",
      "oldValue": "live",
      "newValue": "final"
    }
  ],
  "reason": "Official full-time result confirmed",
  "operator": "live-data-job",
  "rollbackOf": null
}
```

Keep patches small. Prefer multiple specific patches over one large opaque update.

## Match status transitions

Allowed normal transitions:

1. `scheduled`
2. `lineups_available`
3. `live`
4. `halftime`
5. `live`
6. `full_time_pending`
7. `extra_time`
8. `penalties`
9. `final`

Special transitions:

- `scheduled` to `postponed`
- `live` to `abandoned`
- any state to a prior state only through a rollback patch

Rules:

- Prediction settlement starts only after `final`.
- Group standings update after `final`.
- Knockout advancement updates after `final`.
- Spoiler-sensitive quizzes and stickers unlock after `final` or after a configured delay.
- Memory prompts can unlock at kickoff, halftime, final, or custom match moments depending on prompt type.

## Prediction settlement

Prediction settlement must be deterministic and replayable.

For each settlement job:

1. Load all predictions whose lock time passed and whose source event is final.
2. Calculate result from official normalized data.
3. Write a settlement record with prediction ID, rule version, source patch ID, and outcome.
4. Grant rewards through an idempotent reward ledger.
5. Emit challenge progress events such as `prediction_settled`.
6. Do not mutate the original prediction answer.

Voiding rules:

- If a match is abandoned and not replayed, void match predictions.
- If a match is postponed, keep predictions locked unless the product policy explicitly reopens them.
- If a tournament award rule changes, settle by the official competition award only.
- If a feed correction changes a settled result, issue a corrective settlement patch and ledger reversal/adjustment.

## Challenge progress during live play

Challenge progress should be event-sourced where possible.

Examples:

- `match_check_in` contributes to watch challenges.
- `stadium_stamp_collected` contributes to stadium collection.
- `quiz_answered` and `quiz_completed` contribute to trivia challenges.
- `prediction_settled` contributes to prediction challenges.
- `sticker_collected` contributes to album challenges.
- `memory_created` contributes to memory challenges.

Dynamic targets must be recalculated after:

- Group draw confirmation
- Match schedule updates
- Team qualification or elimination
- Knockout bracket advancement
- Sticker set additions
- Stadium assignment corrections

For “watch every team match” challenges:

- Before a team is eliminated, target count grows as new fixtures are confirmed.
- If a team is eliminated, target count freezes at all matches the team played.
- Users who had checked in to all played matches before elimination can complete the challenge.
- If a match is postponed, target remains pending until final or voided by policy.

## Stickers and live moments

Sticker drops should have clear unlock rules:

- Pre-tournament: host cities, stadium postcards, team crests
- Group stage: matchday moments, group completion rewards
- Knockout: bracket moments, penalty shootout moments, upset moments
- Final week: final foils, champion stickers, award stickers
- Post-tournament: commemorative archive packs

Do not publish result-specific sticker copy before the match is final.

## Quizzes and spoiler gating

Daily trivia can be evergreen or live-result-aware.

Evergreen trivia:

- Can be scheduled in advance.
- Should not depend on current standings or results.

Live-result-aware trivia:

- Must reference the match or event it depends on.
- Must unlock only after the official result is final.
- Should include a fallback evergreen question if the match is postponed or the feed is delayed.

## Fan memories

Memory prompts can unlock around moments without revealing results.

Safe live prompts:

- “Where are you watching today?”
- “Save your halftime feeling.”
- “Capture your final whistle reaction.”

Spoiler-sensitive prompts:

- “React to the upset.”
- “Remember the penalty shootout.”
- “Save your champion celebration.”

Spoiler-sensitive prompts require official match tags such as `upset`, `penalty_shootout`, or `champion_confirmed`.

## Rollback and correction policy

Use rollback when:

- A provider sent incorrect score or status.
- A match was mistakenly marked final.
- A bracket slot was populated incorrectly.
- A standings calculation used incorrect tiebreakers.
- A reward job granted based on incorrect settlement.

Rollback requirements:

- Create a new patch; do not delete the old patch.
- Reference `rollbackOf`.
- Reverse or adjust reward ledger entries idempotently.
- Re-run affected settlement and challenge progress jobs.
- Notify users only if their visible reward/progress changed materially.

## Operations roles

### Live data operator

- Monitors feed health.
- Approves manual corrections.
- Reviews high-risk patches.
- Coordinates rollback.

### Content editor

- Publishes quizzes, memory prompts, and sticker drops.
- Reviews spoiler gates.
- Updates copy and localization.

### Economy owner

- Reviews reward changes.
- Monitors sticker pack issuance and coin inflation.
- Approves high-value challenge changes.

### Engineer on call

- Maintains ingestion jobs.
- Responds to validation failures.
- Ensures idempotent replay and rollback.

## Monitoring

Track:

- Feed freshness by match
- Patch processing latency
- Validation failure count
- Match status lag
- Prediction settlement lag
- Challenge progress recalculation lag
- Reward ledger duplicate prevention
- Spoiler gate violations
- Manual override count
- Rollback count

Recommended alert thresholds:

- Kickoff within 30 minutes and match status still missing.
- Match marked `live` more than 3 hours after kickoff without final/postponed/abandoned state.
- Prediction settlement queue older than 15 minutes after final.
- Challenge recalculation queue older than 30 minutes during live play.
- Any spoiler-gated content published before unlock condition.

## Tournament phase checklist

### Before tournament

- [ ] Validate all seed files.
- [ ] Confirm stadium and schedule data.
- [ ] Confirm host-country flags and time zones.
- [ ] Load evergreen quizzes.
- [ ] Load preseason predictions.
- [ ] Load sticker albums and initial drop tables.
- [ ] Smoke-test challenge progress with simulated events.

### After draw

- [ ] Update group assignments.
- [ ] Update group-stage match participants.
- [ ] Enable group completion challenges.
- [ ] Enable group winner predictions.
- [ ] Validate no duplicate team assignments.

### Every matchday

- [ ] Sync fixtures and kickoff changes.
- [ ] Open and close check-in windows.
- [ ] Monitor match status transitions.
- [ ] Publish safe live memory prompts.
- [ ] Settle final results.
- [ ] Recalculate predictions, standings, challenges, and sticker unlocks.
- [ ] Review alerts and validation warnings.

### End of group stage

- [ ] Finalize group standings.
- [ ] Populate Round of 32 bracket.
- [ ] Freeze group-stage predictions.
- [ ] Settle group winner predictions.
- [ ] Recalculate group completion challenges.
- [ ] Publish knockout bracket content.

### Knockout rounds

- [ ] Populate next-round slots after every final result.
- [ ] Keep team journey targets current.
- [ ] Publish knockout memory prompts.
- [ ] Publish penalty/upset stickers only after official tags are final.
- [ ] Settle bracket predictions after each round.

### After final

- [ ] Mark champion and runner-up.
- [ ] Settle champion, finalist, Golden Boot, and award predictions.
- [ ] Unlock final time capsule prompts.
- [ ] Publish final foil and champion stickers.
- [ ] Recalculate all completionist challenges.
- [ ] Archive final tournament content snapshot.