Data Dictionary

Status: Active | Version: 1.0.0 | Last Updated: 2026-05-23

This document defines every significant data entity, field, and enum used across the ML Incident Response Platform — in the PostgreSQL schema, the API payloads, and the Prometheus metrics surface. Engineers and analysts should treat this as the canonical source of truth for field names, types, allowed values, and business-level definitions.

---

Entity: incidents

The core table. Each row represents a discrete operational event affecting one or more ML models in production.

Column	Type	Nullable	Description
id	UUID	No	Primary key, generated by gen_random_uuid()
title	VARCHAR(500)	No	Human-readable summary. Populated by the engineer or automated alert.
severity	ENUM	No	See Severity Levels below.
status	ENUM	No	Current lifecycle state. See Incident Status.
model_id	UUID	No	Foreign key → models.id. The primary affected model.
description	TEXT	Yes	Free-form markdown body. Supports embedded links and code blocks.
trigger_source	ENUM	No	How the incident was created: manual, automated_drift, automated_performance, pagerduty.
labels	TEXT[]	No	Arbitrary string tags. Default: {}. Used for filtering and routing rules.
assigned_to	VARCHAR(255)	Yes	PagerDuty on-call schedule name or individual user slug.
runbook_url	TEXT	Yes	Link to the applicable runbook in runbooks/.
created_at	TIMESTAMPTZ	No	Set on insert, never updated.
updated_at	TIMESTAMPTZ	No	Updated on every write via trigger.
resolved_at	TIMESTAMPTZ	Yes	Populated when status transitions to resolved.
closed_at	TIMESTAMPTZ	Yes	Populated when status transitions to closed.
created_by	VARCHAR(255)	No	JWT sub claim of the user or service account that created the record.

Severity Levels

Value	Label	SLO — Time to Acknowledge	SLO — Time to Resolve	Typical Trigger
P1	Critical	5 minutes	1 hour	Production model completely unavailable or returning null predictions
P2	High	15 minutes	4 hours	PSI > 0.25 on a revenue-critical model; error rate > 5%
P3	Medium	1 hour	24 hours	PSI 0.15–0.25; performance degradation within acceptable range
P4	Low	4 hours	72 hours	Minor drift detected; scheduled maintenance window needed

Incident Status

Status values follow a strict state machine. See governance.md for the full transition diagram.

Value	Description
open	Created but not yet acknowledged
investigating	Acknowledged; root cause analysis in progress
mitigated	Immediate impact contained; root cause may still be unknown
resolved	Root cause identified and fix confirmed in production
closed	Post-mortem completed and action items assigned

---

Entity: incident_timeline

Append-only audit log of all events that occurred during an incident's lifecycle.

Column	Type	Nullable	Description
id	UUID	No	Primary key
incident_id	UUID	No	Foreign key → incidents.id
event_type	ENUM	No	note, status_change, escalation, runbook_step_completed, automated_alert
body	TEXT	No	Markdown content of the event
author	VARCHAR(255)	No	User slug or service account identifier
occurred_at	TIMESTAMPTZ	No	When the event occurred (may differ from created_at for retroactive entries)
created_at	TIMESTAMPTZ	No	When the record was inserted

---

Entity: models

Registry of ML models monitored by the platform.

Column	Type	Nullable	Description
id	UUID	No	Primary key
name	VARCHAR(255)	No	Human-readable model identifier, e.g. credit-risk-v3
version	VARCHAR(50)	No	Semantic version or git SHA of the model artifact
stage	ENUM	No	staging, production, deprecated
team	VARCHAR(255)	No	Owning team slug. Used for alert routing.
feature_store_ref	TEXT	Yes	Path or URI to the feature store view used at training time
model_card_url	TEXT	Yes	Link to the model card document
registered_at	TIMESTAMPTZ	No	When the model was added to the registry
promoted_at	TIMESTAMPTZ	Yes	When the model was promoted to production

---

Entity: drift_assessments

Stores point-in-time drift evaluation results for each model run by the drift detection pipeline.

Column	Type	Nullable	Description
id	UUID	No	Primary key
model_id	UUID	No	Foreign key → models.id
assessed_at	TIMESTAMPTZ	No	Window end time of the assessment
psi_composite	FLOAT	No	Weighted composite PSI across all features. Threshold: 0.15 (warn), 0.25 (critical).
ks_p_value	FLOAT	No	KS-test p-value across the prediction distribution. Values < 0.05 indicate significant drift.
drift_detected	BOOLEAN	No	true if any individual feature PSI > threshold or KS p-value < 0.05
feature_scores	JSONB	No	Map of feature_name → psi_score for per-feature drill-down
reference_window_start	TIMESTAMPTZ	No	Start of the training/baseline data window
reference_window_end	TIMESTAMPTZ	No	End of the training/baseline data window
evaluation_window_start	TIMESTAMPTZ	No	Start of the production data window compared against reference
evaluation_window_end	TIMESTAMPTZ	No	End of the production data window

---

Prometheus Metrics

The platform exposes a /metrics endpoint (Prometheus text format) scraped every 30 seconds.

Metric name	Type	Labels	Description
mlplatform_incidents_total	Counter	severity, trigger_source	Total incidents created since service start
mlplatform_incidents_open	Gauge	severity	Currently open incidents by severity
mlplatform_drift_psi_composite	Gauge	model_id, model_name	Latest composite PSI score per model
mlplatform_drift_detections_total	Counter	model_id, drift_detected	Total drift assessments run
mlplatform_api_request_duration_seconds	Histogram	method, endpoint, status_code	API latency distribution
mlplatform_redis_denylist_size	Gauge	—	Current number of denylisted JWT JTIs in Redis

---

Enum Reference

All enum values are stored as lowercase strings in PostgreSQL to avoid case-sensitivity bugs during ORM mapping.

Enum name	Values
incident_severity	p1, p2, p3, p4
incident_status	open, investigating, mitigated, resolved, closed
trigger_source	manual, automated_drift, automated_performance, pagerduty
model_stage	staging, production, deprecated
timeline_event_type	note, status_change, escalation, runbook_step_completed, automated_alert