feat(alerts): build escalation chains in the dashboard and see them on incidents

apps/api/src/routes/v2/alert-incidents.http.ts

@@ -1,7 +1,13 @@
 import { HttpApiBuilder } from "effect/http-api"
-import type { AlertIncidentDocument, AlertIncidentEventDocument } from "@maple/domain/http"
+import type {
+	AlertIncidentDocument,
+	AlertIncidentEscalationDocument,
+	AlertIncidentEventDocument,
+	AlertIncidentId,
+	OrgId,
+} from "@maple/domain/http"
 import { CurrentTenant, isAlertNotificationEventType } from "@maple/domain/http"
-import type { V2AlertIncident, V2AlertIncidentEvent } from "@maple/domain/http/v2"
+import type { V2AlertIncident, V2AlertIncidentEscalation, V2AlertIncidentEvent } from "@maple/domain/http/v2"
 import { MapleApiV2, paginateOffsetQuery, timestampOrNull } from "@maple/domain/http/v2"
 import { Duration, Effect, Option, Array as Arr } from "effect"
 import { AlertReadModelsService } from "@maple/backend/services/alerts/AlertReadModelsService"
@@ -16,7 +22,33 @@ import {
 import { OrgMembersService } from "@maple/backend/services/org/OrgMembersService"
 import { CurrentAuditActor } from "@maple/backend/services/auth/audit-actor"
 
-const toV2Incident = (doc: AlertIncidentDocument): V2AlertIncident => ({
+/**
+ * An ack pauses the run on the scheduler's next tick; until then the wire already reads it paused,
+ * so a caller never sees a page coming that will not.
+ */
+const toV2Escalation = (
+	doc: AlertIncidentEscalationDocument,
+	isAcknowledged: boolean,
+): V2AlertIncidentEscalation => {
+	const isPausing = isAcknowledged && doc.status === "active"
+	return {
+		chain_id: doc.chainId,
+		chain_name: doc.chainName,
+		status: isPausing ? "acknowledged" : doc.status,
+		// The scheduler leaves an exhausted run past its last step; the wire never reads past the end.
+		step: Math.min(doc.stepIndex + 1, doc.stepCount),
+		step_count: doc.stepCount,
+		pass: Math.min(doc.passIndex + 1, doc.repeatCount + 1),
+		pass_count: doc.repeatCount + 1,
+		steps_sent: doc.stepsSent,
+		next_step_at: isPausing ? null : doc.nextStepAt,
+	}
+}
+
+const toV2Incident = (
+	doc: AlertIncidentDocument,
+	escalation: AlertIncidentEscalationDocument | undefined,
+): V2AlertIncident => ({
 	id: doc.id,
 	object: "alert_incident",
 	rule_id: doc.ruleId,
@@ -50,6 +82,7 @@ const toV2Incident = (doc: AlertIncidentDocument): V2AlertIncident => ({
 			: { user_id: doc.acknowledgedByUserId, name: doc.acknowledgedByName },
 	acknowledged_via: doc.acknowledgedVia,
 	error_issue_id: doc.errorIssueId,
+	escalation: escalation === undefined ? null : toV2Escalation(escalation, doc.acknowledgedAt !== null),
 	...(doc.anomalyIncidentId === undefined ? undefined : { anomaly_incident_id: doc.anomalyIncidentId }),
 	...(doc.groupLabel === undefined ? undefined : { group_label: doc.groupLabel }),
 	...(doc.labels === undefined ? undefined : { labels: doc.labels }),
@@ -88,6 +121,24 @@ export const HttpV2AlertIncidentsLive = HttpApiBuilder.group(MapleApiV2, "alertI
 		const pagesService = yield* AlertIncidentPagesService
 		const members = yield* OrgMembersService
 
+		// One escalation read for a whole page of incidents, never one per incident.
+		const withEscalations = (orgId: OrgId, docs: ReadonlyArray<AlertIncidentDocument>) =>
+			readModels
+				.listIncidentEscalations(
+					orgId,
+					Arr.map(docs, (doc): AlertIncidentId => doc.id),
+				)
+				.pipe(
+					Effect.map((escalations) => {
+						const byIncident = new Map(Arr.map(escalations, (row) => [row.incidentId, row]))
+						return Arr.map(docs, (doc) => toV2Incident(doc, byIncident.get(doc.id)))
+					}),
+				)
+		const withEscalation = (orgId: OrgId, doc: AlertIncidentDocument) =>
+			Effect.map(readModels.listIncidentEscalations(orgId, [doc.id]), (rows) =>
+				toV2Incident(doc, rows[0]),
+			)
+
 		// Who is acknowledging, with a name recorded alongside so every surface can show it without a
 		// directory lookup. An API key is not a person: it is named by its label and has no user. A
 		// session is named by the member directory, best effort: a slow one records no name.
@@ -128,7 +179,11 @@ export const HttpV2AlertIncidentsLive = HttpApiBuilder.group(MapleApiV2, "alertI
 								limit,
 								offset,
 							})
-							.pipe(Effect.map((response) => Arr.map(response.incidents, toV2Incident))),
+							.pipe(
+								Effect.flatMap((response) =>
+									withEscalations(tenant.orgId, response.incidents),
+								),
+							),
 					)
 					return { object: "list" as const, ...page }
 				}),
@@ -137,22 +192,21 @@ export const HttpV2AlertIncidentsLive = HttpApiBuilder.group(MapleApiV2, "alertI
 				Effect.gen(function* () {
 					const tenant = yield* CurrentTenant.Context
 					const incident = yield* readModels.getIncident(tenant.orgId, params.id)
-
-					return toV2Incident(incident)
+					return yield* withEscalation(tenant.orgId, incident)
 				}),
 			)
 			.handle("acknowledge", ({ params }) =>
 				Effect.gen(function* () {
 					const { orgId, actor } = yield* callerActor
 					const result = yield* acks.acknowledge(orgId, params.id, actor)
-					return toV2Incident(result.incident)
+					return yield* withEscalation(orgId, result.incident)
 				}).pipe(Effect.withSpan("HttpV2AlertIncidents.acknowledge")),
 			)
 			.handle("unacknowledge", ({ params }) =>
 				Effect.gen(function* () {
 					const { orgId, actor } = yield* callerActor
 					const result = yield* acks.unacknowledge(orgId, params.id, actor)
-					return toV2Incident(result.incident)
+					return yield* withEscalation(orgId, result.incident)
 				}).pipe(Effect.withSpan("HttpV2AlertIncidents.unacknowledge")),
 			)
 			.handle("listEvents", ({ params }) =>

apps/api/src/routes/v2/alerts.http.test.ts

@@ -1363,6 +1363,102 @@ describe("v2 alerts over HTTP", () => {
 		await harness.dispose()
 	})
 
+	it("reads an incident's latest escalation run on retrieve and list, and null without one", async () => {
+		const harness = makeHarness()
+		const key = await harness.bootstrapKey(["alerts:write"])
+		await createWebhookAndRule(harness, key.secret)
+		await executeSql(
+			harness.testDb,
+			`insert into alert_incidents (
+				id, org_id, rule_id, incident_key, rule_name, group_key, signal_type, severity, status,
+				comparator, threshold, first_triggered_at, last_triggered_at, resolved_at, dedupe_key,
+				created_at, updated_at
+			)
+			select v.id, rules.org_id, rules.id, v.id, 'Checkout error rate', v.group_key, 'error_rate',
+				'critical', 'open', 'gt', 0.05, now(), now(), null, v.id, now(), now()
+			from (values
+				('00000000-0000-4000-8000-0000000000b1', 'checkout'),
+				('00000000-0000-4000-8000-0000000000b2', 'payments')
+			) as v(id, group_key)
+			cross join lateral (
+				select id, org_id from alert_rules where org_id = 'org_alerts_e2e' limit 1
+			) as rules`,
+		)
+		const steps = JSON.stringify([
+			{
+				targets: [{ type: "destination", destinationId: "00000000-0000-4000-8000-0000000000d1" }],
+				waitMinutes: 10,
+			},
+			{
+				targets: [{ type: "destination", destinationId: "00000000-0000-4000-8000-0000000000d2" }],
+				waitMinutes: 15,
+			},
+			{
+				targets: [{ type: "destination", destinationId: "00000000-0000-4000-8000-0000000000d3" }],
+				waitMinutes: 5,
+			},
+		])
+		// An older superseded run and the live one: the read shows the newer.
+		await executeSql(
+			harness.testDb,
+			`insert into alert_escalation_runs (
+				id, org_id, incident_id, chain_id, chain_name, severity, steps_json, repeat_count,
+				step_index, pass_index, next_step_at, status, payload_json, steps_sent, created_at, updated_at
+			) values
+				('00000000-0000-4000-8000-0000000000c1', 'org_alerts_e2e', '00000000-0000-4000-8000-0000000000b1',
+					'00000000-0000-4000-8000-0000000000e1', 'Old chain', 'warning', '${steps}'::jsonb, 0,
+					1, 0, '2026-11-06T14:00:00.000Z', 'superseded', '{}'::jsonb, 1,
+					'2026-11-06T13:00:00.000Z', '2026-11-06T13:00:00.000Z'),
+				('00000000-0000-4000-8000-0000000000c2', 'org_alerts_e2e', '00000000-0000-4000-8000-0000000000b1',
+					'00000000-0000-4000-8000-0000000000e2', 'Checkout on-call', 'critical', '${steps}'::jsonb, 1,
+					1, 0, '2026-11-06T14:25:00.000Z', 'active', '{}'::jsonb, 1,
+					'2026-11-06T14:10:00.000Z', '2026-11-06T14:10:00.000Z')`,
+		)
+		const list = await harness.request("GET", "/v2/alerts/incidents?status=open", key.secret)
+		expect(list.status).toBe(200)
+		const isEscalating = (incident: { escalation: unknown }) => incident.escalation !== null
+		const without = Arr.filter(list.body.data, (incident) => !isEscalating(incident))
+		const withRuns = Arr.filter(list.body.data, isEscalating)
+		expect(without).toHaveLength(1)
+		expect(without[0].escalation).toBeNull()
+		expect(withRuns).toHaveLength(1)
+		const withRun = withRuns[0]
+		const expected = {
+			chain_id: expect.stringMatching(/^esc_/),
+			chain_name: "Checkout on-call",
+			status: "active",
+			step: 2,
+			step_count: 3,
+			pass: 1,
+			pass_count: 2,
+			steps_sent: 1,
+			next_step_at: "2026-11-06T14:25:00.000Z",
+		}
+		expect(withRun.escalation).toEqual(expected)
+
+		const retrieved = await harness.request("GET", `/v2/alerts/incidents/${withRun.id}`, key.secret)
+		expect(retrieved.status).toBe(200)
+		expect(retrieved.body.escalation).toEqual(expected)
+
+		// Acked before the scheduler pauses the run: it already reads paused, with no next page.
+		await executeSql(
+			harness.testDb,
+			`update alert_incidents set acknowledged_at = now() where id = '00000000-0000-4000-8000-0000000000b1'`,
+		)
+		const pausing = await harness.request("GET", `/v2/alerts/incidents/${withRun.id}`, key.secret)
+		expect(pausing.body.escalation).toMatchObject({ status: "acknowledged", next_step_at: null })
+
+		// Paused while acknowledged: no next page time.
+		await executeSql(
+			harness.testDb,
+			`update alert_escalation_runs set status = 'acknowledged' where id = '00000000-0000-4000-8000-0000000000c2'`,
+		)
+		const paused = await harness.request("GET", `/v2/alerts/incidents/${withRun.id}`, key.secret)
+		expect(paused.body.escalation).toMatchObject({ status: "acknowledged", next_step_at: null })
+
+		await harness.dispose()
+	})
+
 	it("enforces the alerts scope family and rejects malformed ids", async () => {
 		const harness = makeHarness()
 		const readOnly = await harness.bootstrapKey(["alerts:read"])

apps/api/src/routes/v2/v2-test-support.ts

@@ -628,6 +628,7 @@ export const AlertDestinationsServiceStubLayer = Layer.succeed(
 const alertReadModelStubs = {
 	listIncidents: die,
 	getIncident: die,
+	listIncidentEscalations: die,
 	listRuleChecks: die,
 	summarizeRuleChecks: die,
 	listDeliveryEvents: die,

apps/ios/Packages/MapleAPI/Sources/MapleAPI/openapi.json

@@ -313,6 +313,17 @@
             "comparator": "gt",
             "dedupe_key": "alrt_gU26thvJECdQvu54Ad9jiz:__total__",
             "error_issue_id": null,
+            "escalation": {
+              "chain_id": "esc_gQtGH2s65G6a7sJmuayXL6",
+              "chain_name": "Checkout on-call",
+              "next_step_at": null,
+              "pass": 1,
+              "pass_count": 2,
+              "status": "acknowledged",
+              "step": 2,
+              "step_count": 3,
+              "steps_sent": 1
+            },
             "first_triggered_at": "2026-07-15T09:10:00.000Z",
             "group_key": null,
             "held_since": null,
@@ -368,6 +379,10 @@
             "$ref": "#/components/schemas/_maple_ErrorIssueId",
             "description": "The linked error issue (`iss_…`) when the incident was correlated to one, or `null`."
           },
+          "escalation": {
+            "$ref": "#/components/schemas/AlertIncidentEscalation",
+            "description": "The incident's latest escalation chain run, or `null` when its severity tier names no chain."
+          },
           "first_triggered_at": {
             "type": "string"
           },
@@ -523,6 +538,86 @@
         "title": "Alert incident actor",
         "type": "object"
       },
+      "AlertIncidentEscalation": {
+        "additionalProperties": false,
+        "description": "How far the incident's latest escalation chain run has got.",
+        "properties": {
+          "chain_id": {
+            "$ref": "#/components/schemas/_maple_EscalationChainId"
+          },
+          "chain_name": {
+            "description": "The chain's name when the run started.",
+            "examples": [
+              "Checkout on-call"
+            ],
+            "type": "string"
+          },
+          "next_step_at": {
+            "description": "When the next step pages, or `null` while paused or once the run has ended.",
+            "type": "string"
+          },
+          "pass": {
+            "description": "The pass the next step belongs to, from 1.",
+            "examples": [
+              1
+            ],
+            "maximum": 9007199254740991,
+            "minimum": 0,
+            "type": "integer"
+          },
+          "pass_count": {
+            "description": "Passes over the chain in all: its repeat count plus one.",
+            "examples": [
+              2
+            ],
+            "maximum": 9007199254740991,
+            "minimum": 0,
+            "type": "integer"
+          },
+          "status": {
+            "$ref": "#/components/schemas/_maple_AlertEscalationRunStatus"
+          },
+          "step": {
+            "description": "The next step to page, from 1.",
+            "examples": [
+              2
+            ],
+            "maximum": 9007199254740991,
+            "minimum": 0,
+            "type": "integer"
+          },
+          "step_count": {
+            "description": "Steps in the chain the run started with.",
+            "examples": [
+              3
+            ],
+            "maximum": 9007199254740991,
+            "minimum": 0,
+            "type": "integer"
+          },
+          "steps_sent": {
+            "description": "Steps paged so far, across passes.",
+            "examples": [
+              1
+            ],
+            "maximum": 9007199254740991,
+            "minimum": 0,
+            "type": "integer"
+          }
+        },
+        "required": [
+          "chain_id",
+          "chain_name",
+          "status",
+          "step",
+          "step_count",
+          "pass",
+          "pass_count",
+          "steps_sent"
+        ],
+        "title": "Alert incident escalation",
+        "type": "object"
+      },
       "AlertIncidentList": {
         "additionalProperties": false,
         "description": "A cursor-paginated page of alert incidents.",
@@ -6951,6 +7046,21 @@
         "title": "Alert Destination Type",
         "type": "string"
       },
+      "_maple_AlertEscalationRunStatus": {
+        "description": "`active` waits on `next_step_at`; `acknowledged` is paused until the incident is unacknowledged; `resolved`, `exhausted` (every step and repeat sent) and `superseded` (a higher tier started its own chain) have ended.",
+        "enum": [
+          "active",
+          "acknowledged",
+          "resolved",
+          "exhausted",
+          "superseded"
+        ],
+        "examples": [
+          "active"
+        ],
+        "title": "Alert Escalation Run Status",
+        "type": "string"
+      },
       "_maple_AlertEvaluationStatus": {
         "description": "The evaluation verdict: `breached`, `healthy`, or `skipped` (not enough samples / no data).",
         "enum": [