# Notifications Severity Transition Events (Web V)

## Status
- Final v1.0 (2025-12-01); aligns with Notifications Guild checkpoint for Sprint 0216.

## Scope
- Event schema for severity transitions emitted by Web gateway to notifier bus (WEB-RISK-68-001).
- Traceability and audit linking for downstream consumers (Console, Observability, Export Center).

## Event Shape
- `event_type`: `severity.transition.v1`
- `tenant_id`: string (slug/UUID)
- `project_id`: string | null
- `finding_id`: string (hash/UUID)
- `risk_id`: string | null
- `from_severity`: enum [`none`, `info`, `low`, `medium`, `high`, `critical`]
- `to_severity`: enum (same as above)
- `transition_reason`: string (machine-friendly code, e.g., `exploit_seen`, `policy_change`, `scanner_reclass`)
- `occurred_at`: string (UTC ISO-8601)
- `trace_id`: string (ULID/UUID)
- `correlation_id`: string (UUID/ULID)
- `actor`: { `subject`: string, `type`: `user`|`service` }
- `vex_statement_id`: string | null — optional link to VEX statement that drove the change
- `evidence_bundle_id`: string | null — optional link to export bundle for the decision
- `source`: `gateway`
- `version`: `v1`

## Delivery & QoS
- Topic: `notifications.severity.transition.v1`; DLQ: `notifications.severity.transition.dlq.v1` (same schema + `error`).
- Delivery: at-least-once; consumers dedupe on `correlation_id + finding_id + to_severity`.
- Ordering: best-effort per `tenant_id`; no cross-tenant ordering guarantee.
- Retention: 7 days; DLQ retention 14 days.
- Rate limit: default 50 events/sec/tenant; above limit gateway returns 429 and drops publish with `ERR_NOTIFY_RATE_LIMIT` envelope.
- Ack: messages must be acked within 5 s or will be redelivered with increasing backoff.

## Sample Payload
```json
{
  "event_type": "severity.transition.v1",
  "tenant_id": "acme-tenant",
  "project_id": "proj-ops",
  "finding_id": "f-7e12d9",
  "risk_id": "r-4421",
  "from_severity": "medium",
  "to_severity": "high",
  "transition_reason": "exploit_seen",
  "occurred_at": "2025-12-01T10:15:20Z",
  "trace_id": "01HXYZABCD1234567890",
  "correlation_id": "01HXYZABCD1234567890",
  "actor": { "subject": "policy-svc", "type": "service" },
   "vex_statement_id": "vex-123",
   "evidence_bundle_id": "bundle-01HF7T4X6E4S7A6PK8",
  "source": "gateway",
  "version": "v1"
}
```