# V2 Game Event Taxonomy

`GameEventTaxonomy_V2_Contract.json` defines the standard event vocabulary for
Phase 72 telemetry SDK and ingestion work. The taxonomy is intentionally small:
it gives every gameplay, commerce, UI, and reliability pipeline the same session
and event names before SDK buffering, schema-versioning, replay, export, and
warehouse tasks are implemented.

## Naming Rules

- Canonical topics are published through `@oshun/event-bus`.
- V2 gameplay topics use `v2.player.*`, `v2.match.*`, or `v2.cosmetic.*`.
- Topics are past-tense facts and payload fields use `snake_case`.
- Account identity in standard taxonomy events uses `account_id_hash`; raw
  account IDs, platform user IDs, emails, IP addresses, and raw log lines are
  forbidden standard fields.
- Standard taxonomy events default to schema version `1`.

## Standard Event Types

| Standard type  | Canonical topic                  | Category      | Reliability | Required fields                                                                |
| -------------- | -------------------------------- | ------------- | ----------- | ------------------------------------------------------------------------------ |
| Session Start  | `v2.player.session.started`      | Online        | Reliable    | `account_id_hash`, `session_id`, `platform`, `build_id`                        |
| Session End    | `v2.player.session.ended`        | Online        | Reliable    | `account_id_hash`, `session_id`, `duration_seconds`, `end_reason`              |
| Level Load     | `v2.match.level.loaded`          | Performance   | Reliable    | `session_id`, `level_id`, `level_load_id`, `load_time_ms`                      |
| Death          | `v2.match.player.death`          | Match         | Reliable    | `match_id`, `account_id_hash`, `fighter_id`, `cause`                           |
| Achievement    | `v2.player.achievement.unlocked` | Progression   | Reliable    | `account_id_hash`, `achievement_id`, `unlock_source`, `unlocked_at`            |
| Purchase       | `v2.cosmetic.purchased`          | Economy       | Reliable    | `account_id_hash`, `item_id`, `currency`, `price_minor`                        |
| UI Interaction | `v2.player.ui.interacted`        | Accessibility | BestEffort  | `account_id_hash`, `session_id`, `screen_id`, `element_id`, `interaction_type` |
| Error          | `v2.player.error.reported`       | Performance   | ReleaseGate | `error_id`, `session_id`, `severity`, `category`, `build_id`                   |

The SDK-facing companion catalog lives in `telemetry-sdk-event-catalog.md`. It
maps each standard event to the `maya-telemetry-sdk` Rust topic constant,
required payload fields, reliability mode, and example payload.

## Pipeline Contract

Session start and session end bracket reconstruction. Level load, UI
interaction, and error events may happen before a match ID exists, so they carry
`session_id`. Match death events carry both `match_id` and `account_id_hash`.
Purchase events are emitted after platform receipt validation and entitlement
grant. Achievement events are emitted after progression state is committed.

Crash telemetry remains `v2.match.crash.reported`; `v2.player.error.reported`
covers recoverable client or service errors that do not produce a crash report.