# Event Taxonomy (Canonical)

## Purpose
Define domain events for async workflows with stable names, payload contracts, ownership, and idempotency behavior.

## Naming Convention
`<domain>.<entity_or_process>.<action>`
Examples:
- `gpuaas.provisioning.requested`
- `platform.billing.balance_depleted`

## Envelope Contract
All events follow envelope:
- `event_id` (uuid)
- `event_type` (string)
- `occurred_at` (RFC3339 UTC)
- `version` (semver-like string)
- `correlation_id` (trace/correlation id)
- `payload` (typed object)

## Event Catalog
| Event | Producer | Consumers | Idempotency Key | Notes |
|---|---|---|---|---|
| gpuaas.provisioning.requested | Orchestrator | Provisioning Worker | allocation_id | starts provisioning workflow |
| gpuaas.provisioning.active | Provisioning Worker | Billing, Notification Relay | allocation_id + started_at | allocation usable |
| gpuaas.provisioning.failed | Provisioning Worker | API read model, Notification Relay | allocation_id + reason hash | terminal failure state |
| gpuaas.provisioning.force_release_requested | Billing Worker | Provisioning Worker | user_id + window | release due to policy (balance depleted) |
| gpuaas.provisioning.releasing.requested | Provisioning Orchestrator | Provisioning Worker | allocation_id | user/system-initiated release started |
| gpuaas.provisioning.releasing.completed | Provisioning Worker | Billing, Notification Relay | allocation_id + released_at | node unassigned, usage window closed |
| gpuaas.provisioning.release_failed | Provisioning Worker | Billing, Notification Relay | allocation_id + failed_at | all retries exhausted; billing stops, admin intervention required |
| platform.billing.low_balance_warning | Billing Worker | Notification Relay | user_id + threshold_window | one-time per low-state transition |
| platform.billing.auto_release_pending | Billing Worker | Notification Relay | user_id + projected_depletion_at | warning that forced release is approaching based on projected depletion |
| platform.billing.balance_depleted | Billing Worker | Notification Relay, Provisioning | user_id + depleted_at | triggers force release |
| platform.billing.usage.metered | GPUaaS / App Platform / future metered products | Billing Worker | usage_event_id or idempotency_key | product-neutral usage interval for usage_records, rated_usage_lines, and ledger posting |
| platform.payments.balance_credited | Payments Service | Billing Read Model | stripe_event_id | credit applied after idempotent webhook post |
| platform.payments.reconcile_failed | Payments Service | Notification Relay, Ops | stripe_event_id + payment_session_id | mismatch or provider failure requiring support follow-up |

## Versioning Rules
- Additive payload fields -> minor event version.
- Breaking payload changes -> new event version and dual-consume window.

## Retry/DLQ Rules
- Consumers must be idempotent.
- Retry with exponential backoff.
- Poison events routed to DLQ with replay tooling.