# Notifications Severity Transition Events (Web V)

## Status
- Draft v0.1 (2025-12-01); to be confirmed at 2025-12-06 checkpoint with Notifications Guild.

## 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).

## 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)
- `occurred_at`: string (UTC ISO-8601)
- `trace_id`: string (ULID/UUID)
- `correlation_id`: string (UUID/ULID)
- `actor`: { `subject`: string, `type`: `user`|`service` }
- `source`: `gateway`
- `version`: `v1`

## Delivery & QoS
- Bus topic: `notifications.severity.transition.v1`.
- At-least-once delivery; consumers must dedupe on `correlation_id + finding_id + to_severity`.
- Ordering: best-effort per `tenant_id`; no cross-tenant ordering guarantee.
- Retention: 7 days (proposed); DLQ on permanent failures with same schema plus `error`.

## 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" },
  "source": "gateway",
  "version": "v1"
}
```

## Open Questions
- Confirm retention period and DLQ topic naming.
- Confirm whether VEX statement link/reference is required in payload.
- Confirm if per-tenant rate limits apply to this topic.