Notifications Severity Transition Events (Web V)

This document defines the severity.transition.v1 event that the Stella Ops Web gateway emits to the notifier bus whenever a finding’s severity changes. It is the contract for downstream consumers (Console, Observability, Export Center) that react to severity escalations and de-escalations, with traceability and audit linking built in.

Status

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

Scope

• Event schema for severity transitions emitted by the Web gateway to the 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

{
  "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"
}