@checkstack/incident-backend 1.2.0 → 1.4.0

package/src/incident-entity.test.ts

@@ -0,0 +1,266 @@
+import { describe, it, expect } from "bun:test";
+import type {
+  EntityChanged,
+  EntityHandle,
+} from "@checkstack/automation-backend";
+import { SYSTEM_ACTOR } from "@checkstack/common";
+
+import {
+  INCIDENT_ENTITY_KIND,
+  INCIDENT_TRIGGER_EVENTS,
+  IncidentEntityStateSchema,
+  createIncidentEntityRead,
+  deriveIncidentTriggerEvents,
+  incidentChangeToPayload,
+  removeIncidentEntity,
+  toIncidentEntityState,
+  writeIncidentEntity,
+  type IncidentEntityState,
+} from "./incident-entity";
+import {
+  incidentCreatedTrigger,
+  incidentResolvedTrigger,
+  incidentUpdatedTrigger,
+} from "./automations";
+import type { IncidentService } from "./service";
+
+function change(overrides: Partial<EntityChanged> = {}): EntityChanged {
+  return {
+    kind: INCIDENT_ENTITY_KIND,
+    id: "inc-1",
+    prev: { status: "investigating", severity: "major", systemIds: ["a"] },
+    next: { status: "monitoring", severity: "major", systemIds: ["a"] },
+    delta: { status: "monitoring" },
+    changedFields: ["status"],
+    actor: SYSTEM_ACTOR,
+    occurredAt: new Date().toISOString(),
+    ...overrides,
+  };
+}
+
+describe("deriveIncidentTriggerEvents", () => {
+  it("create → incident.created", () => {
+    expect(
+      deriveIncidentTriggerEvents(
+        change({
+          prev: null,
+          next: { status: "investigating", severity: "minor", systemIds: ["a"] },
+        }),
+      ),
+    ).toEqual([INCIDENT_TRIGGER_EVENTS.created]);
+  });
+
+  it("transition to resolved → incident.resolved", () => {
+    expect(
+      deriveIncidentTriggerEvents(
+        change({
+          prev: { status: "monitoring", severity: "major", systemIds: ["a"] },
+          next: { status: "resolved", severity: "major", systemIds: ["a"] },
+        }),
+      ),
+    ).toEqual([INCIDENT_TRIGGER_EVENTS.resolved]);
+  });
+
+  it("non-resolve field change → incident.updated", () => {
+    expect(deriveIncidentTriggerEvents(change())).toEqual([
+      INCIDENT_TRIGGER_EVENTS.updated,
+    ]);
+  });
+
+  it("reopen (resolved → investigating) → incident.updated", () => {
+    expect(
+      deriveIncidentTriggerEvents(
+        change({
+          prev: { status: "resolved", severity: "major", systemIds: ["a"] },
+          next: { status: "investigating", severity: "major", systemIds: ["a"] },
+        }),
+      ),
+    ).toEqual([INCIDENT_TRIGGER_EVENTS.updated]);
+  });
+
+  it("tombstone → no event (no incident.deleted)", () => {
+    expect(deriveIncidentTriggerEvents(change({ next: null }))).toEqual([]);
+  });
+});
+
+describe("incidentChangeToPayload — payloadSchema parity", () => {
+  it("a create payload validates against the created trigger's payloadSchema", () => {
+    const payload = incidentChangeToPayload(
+      change({
+        prev: null,
+        next: { status: "investigating", severity: "minor", systemIds: ["a", "b"] },
+        delta: { status: "investigating" },
+        changedFields: ["status", "severity", "systemIds"],
+      }),
+    );
+    const parsed = incidentCreatedTrigger.payloadSchema.parse(payload);
+    expect(parsed.incidentId).toBe("inc-1");
+    expect(parsed.status).toBe("investigating");
+    expect(parsed.severity).toBe("minor");
+    expect(parsed.systemIds).toEqual(["a", "b"]);
+  });
+
+  it("a status-flip payload validates against the updated trigger's payloadSchema and carries statusChange", () => {
+    const payload = incidentChangeToPayload(change());
+    const parsed = incidentUpdatedTrigger.payloadSchema.parse(payload);
+    expect(parsed.incidentId).toBe("inc-1");
+    expect(parsed.status).toBe("monitoring");
+    // status was in changedFields → statusChange mirrors the new status.
+    expect(parsed.statusChange).toBe("monitoring");
+  });
+
+  it("a resolve payload validates against the resolved trigger's payloadSchema", () => {
+    const payload = incidentChangeToPayload(
+      change({
+        prev: { status: "monitoring", severity: "major", systemIds: ["a"] },
+        next: { status: "resolved", severity: "major", systemIds: ["a"] },
+      }),
+    );
+    const parsed = incidentResolvedTrigger.payloadSchema.parse(payload);
+    expect(parsed.incidentId).toBe("inc-1");
+    expect(parsed.severity).toBe("major");
+    expect(parsed.systemIds).toEqual(["a"]);
+  });
+
+  it("omits statusChange when status did not change", () => {
+    const payload = incidentChangeToPayload(
+      change({
+        delta: { severity: "critical" },
+        changedFields: ["severity"],
+        next: { status: "monitoring", severity: "critical", systemIds: ["a"] },
+      }),
+    );
+    expect("statusChange" in payload).toBe(false);
+  });
+});
+
+describe("IncidentEntityStateSchema", () => {
+  it("parses the reactive subset", () => {
+    const parsed = IncidentEntityStateSchema.parse({
+      status: "investigating",
+      severity: "critical",
+      systemIds: ["a", "b"],
+    });
+    expect(parsed.systemIds).toEqual(["a", "b"]);
+  });
+});
+
+describe("toIncidentEntityState", () => {
+  it("projects the reactive subset off a full incident", () => {
+    expect(
+      toIncidentEntityState({
+        status: "monitoring",
+        severity: "major",
+        systemIds: ["a", "b"],
+      }),
+    ).toEqual({ status: "monitoring", severity: "major", systemIds: ["a", "b"] });
+  });
+});
+
+describe("createIncidentEntityRead", () => {
+  it("routes the batched read straight to the service (plugin-backed)", async () => {
+    const seen: ReadonlyArray<string>[] = [];
+    const service = {
+      async getManyEntityStates(ids: ReadonlyArray<string>) {
+        seen.push(ids);
+        return {
+          "inc-1": {
+            status: "investigating" as const,
+            severity: "minor" as const,
+            systemIds: ["a"],
+          },
+        };
+      },
+    } as unknown as IncidentService;
+    const read = createIncidentEntityRead(service);
+    const out = await read(["inc-1", "inc-2"]);
+    expect(seen).toEqual([["inc-1", "inc-2"]]);
+    expect(out["inc-1"]).toEqual({
+      status: "investigating",
+      severity: "minor",
+      systemIds: ["a"],
+    });
+  });
+});
+
+describe("writeIncidentEntity", () => {
+  it("drives the write through handle.mutate keyed by incident id", async () => {
+    const calls: Array<{ id: string; next: IncidentEntityState }> = [];
+    const handle = {
+      kind: INCIDENT_ENTITY_KIND,
+      async mutate(input: {
+        id: string;
+        apply: () => Promise<IncidentEntityState>;
+      }) {
+        const next = await input.apply();
+        calls.push({ id: input.id, next });
+        return next;
+      },
+    } as unknown as EntityHandle<IncidentEntityState>;
+
+    let applied = false;
+    await writeIncidentEntity({
+      handle,
+      incidentId: "inc-9",
+      apply: async () => {
+        applied = true;
+        return { status: "monitoring", severity: "critical", systemIds: ["a"] };
+      },
+    });
+    expect(applied).toBe(true);
+    expect(calls).toEqual([
+      {
+        id: "inc-9",
+        next: { status: "monitoring", severity: "critical", systemIds: ["a"] },
+      },
+    ]);
+  });
+
+  it("still runs the plugin write when no handle is wired", async () => {
+    let applied = false;
+    await writeIncidentEntity({
+      handle: undefined,
+      incidentId: "inc-9",
+      apply: async () => {
+        applied = true;
+        return { status: "investigating", severity: "minor", systemIds: [] };
+      },
+    });
+    expect(applied).toBe(true);
+  });
+});
+
+describe("removeIncidentEntity", () => {
+  it("tombstones via handle.remove({ apply })", async () => {
+    const removed: string[] = [];
+    let deleted = false;
+    const handle = {
+      kind: INCIDENT_ENTITY_KIND,
+      async remove(input: { id: string; apply: () => Promise<void> }) {
+        await input.apply();
+        removed.push(input.id);
+      },
+    } as unknown as EntityHandle<IncidentEntityState>;
+    await removeIncidentEntity({
+      handle,
+      incidentId: "inc-9",
+      apply: async () => {
+        deleted = true;
+      },
+    });
+    expect(deleted).toBe(true);
+    expect(removed).toEqual(["inc-9"]);
+  });
+
+  it("still runs the delete when no handle is wired", async () => {
+    let deleted = false;
+    await removeIncidentEntity({
+      handle: undefined,
+      incidentId: "inc-9",
+      apply: async () => {
+        deleted = true;
+      },
+    });
+    expect(deleted).toBe(true);
+  });
+});

package/src/incident-entity.ts

@@ -0,0 +1,192 @@
+/**
+ * The reactive `incident` entity (reactive automation engine §10.1).
+ *
+ * Model B PLUGIN-BACKED entity: the `incidents` + `incident_systems` tables
+ * are authoritative AND ARE the entity's current-state storage — there is NO
+ * framework `entity_state` row for an incident. `defineEntity({ read })` makes
+ * that plugin state reactive: every reactive-state write goes through
+ * `handle.mutate`, whose `apply()` performs the REAL `incidents`/junction write
+ * via the incident service (the plugin's own db/tx) and returns the resulting
+ * `{ status, severity, systemIds }`. The framework snapshots `prev` via `read`,
+ * appends the transition log (its own db), and emits `ENTITY_CHANGED`. The
+ * change → trigger-event deriver reproduces `incident.created` / `.updated` /
+ * `.resolved` so automations keep firing.
+ */
+import { z } from "zod";
+import {
+  IncidentSeverityEnum,
+  IncidentStatusEnum,
+} from "@checkstack/incident-common";
+import type {
+  EntityChangeDeriver,
+  EntityChangePayloadMapper,
+  EntityHandle,
+  EntityMutationOpts,
+  EntityRead,
+} from "@checkstack/automation-backend";
+import {
+  withEntityRemove,
+  withEntityWrite,
+} from "@checkstack/automation-backend";
+
+import type { IncidentService } from "./service";
+
+export const INCIDENT_ENTITY_KIND = "incident";
+
+export const IncidentEntityStateSchema = z.object({
+  status: IncidentStatusEnum,
+  severity: IncidentSeverityEnum,
+  systemIds: z.array(z.string()),
+});
+
+export type IncidentEntityState = z.infer<typeof IncidentEntityStateSchema>;
+
+export const INCIDENT_TRIGGER_EVENTS = {
+  created: "incident.created",
+  updated: "incident.updated",
+  resolved: "incident.resolved",
+} as const;
+
+function readStatus(state: Record<string, unknown> | null): string | null {
+  if (state === null) return null;
+  const status = state["status"];
+  return typeof status === "string" ? status : null;
+}
+
+/**
+ * `incident` change → trigger events.
+ *
+ * - create (`prev === null`) → `incident.created`
+ * - transition TO `resolved` (and not already resolved) → `incident.resolved`
+ * - any other field change → `incident.updated`
+ * - tombstone (`next === null`, from `deleteIncident`) → no event (there is
+ *   no `incident.deleted` trigger event)
+ *
+ * NOTE (deviation): the old `addUpdate`-with-status=resolved path emitted
+ * BOTH `incident.updated` and `incident.resolved`; the deriver fires only
+ * `incident.resolved` on a resolution (matching the dedicated
+ * `resolveIncident` / `resolveAutoIncident` paths, which only emitted
+ * `incident.resolved`). A resolution is no longer also surfaced as a generic
+ * `incident.updated` — automations meant to react to resolution should use
+ * the `incident.resolved` trigger.
+ */
+export const deriveIncidentTriggerEvents: EntityChangeDeriver = (changed) => {
+  if (changed.prev === null && changed.next !== null) {
+    return [INCIDENT_TRIGGER_EVENTS.created];
+  }
+  if (changed.next === null) {
+    return [];
+  }
+  const prevStatus = readStatus(changed.prev);
+  const nextStatus = readStatus(changed.next);
+  if (nextStatus === "resolved" && prevStatus !== "resolved") {
+    return [INCIDENT_TRIGGER_EVENTS.resolved];
+  }
+  return [INCIDENT_TRIGGER_EVENTS.updated];
+};
+
+function readField(
+  state: Record<string, unknown> | null,
+  field: string,
+): unknown {
+  return state === null ? undefined : state[field];
+}
+
+/**
+ * Map an `incident` entity change to the domain-named `trigger.payload` the
+ * incident triggers declare via `payloadSchema` (`incidentId`, `systemIds`,
+ * `severity`, `status`, `statusChange`). This restores the keys operators read
+ * (`trigger.payload.incidentId` etc.) that the generic change shape omits.
+ *
+ * The reactive `incident` entity state is only `{ status, severity, systemIds }`,
+ * so the schemas' descriptive fields (`title`, `description`, `createdAt`,
+ * `resolvedAt`) are NOT available from a change and are declared OPTIONAL on
+ * those schemas. `statusChange` is populated when the status field changed (the
+ * `updated` trigger's hint), so a status flip carries the new status both as
+ * `status` and `statusChange`.
+ */
+export const incidentChangeToPayload: EntityChangePayloadMapper = (changed) => {
+  const next = changed.next;
+  const statusChanged = changed.changedFields.includes("status");
+  const nextStatus = readField(next, "status");
+  return {
+    incidentId: changed.id,
+    systemIds: Array.isArray(readField(next, "systemIds"))
+      ? (readField(next, "systemIds") as unknown[])
+      : [],
+    severity: readField(next, "severity"),
+    status: nextStatus,
+    ...(statusChanged && typeof nextStatus === "string"
+      ? { statusChange: nextStatus }
+      : {}),
+  };
+};
+
+/**
+ * Build the PLUGIN-BACKED `read` accessor for the `incident` entity. Routes
+ * straight to the service's batched authoritative read — no framework storage.
+ */
+export function createIncidentEntityRead(
+  service: IncidentService,
+): EntityRead<IncidentEntityState> {
+  return (ids) => service.getManyEntityStates(ids);
+}
+
+/**
+ * Project a service incident shape onto the reactive `{ status, severity,
+ * systemIds }` subset. The router's service writes return the full incident;
+ * this is the `apply()` return for `handle.mutate`.
+ */
+export function toIncidentEntityState(incident: {
+  status: IncidentEntityState["status"];
+  severity: IncidentEntityState["severity"];
+  systemIds: string[];
+}): IncidentEntityState {
+  return {
+    status: incident.status,
+    severity: incident.severity,
+    systemIds: incident.systemIds,
+  };
+}
+
+/**
+ * Drive a reactive-state incident write through `handle.mutate` (§10.1).
+ * `apply` performs the REAL `incidents`/junction write via the service (the
+ * plugin's own db/tx) and returns the new reactive state. The framework
+ * snapshots `prev`, appends the transition log, and emits `ENTITY_CHANGED`
+ * (the deriver turns that into `incident.created/.updated/.resolved`).
+ *
+ * When no handle is available (tests construct the router without one), the
+ * write still runs — the entity reactivity is layered on top, never required
+ * for the underlying write to succeed.
+ */
+export async function writeIncidentEntity(args: {
+  handle: EntityHandle<IncidentEntityState> | undefined;
+  incidentId: string;
+  /**
+   * Mutation context (actor / runId). When the write originates inside a
+   * dispatch run, pass `opts: { runId }` so a run-resolved secret that lands
+   * in the reactive state is masked in the transition rows + `ENTITY_CHANGED`.
+   */
+  opts?: EntityMutationOpts;
+  apply: () => Promise<IncidentEntityState>;
+}): Promise<void> {
+  const { handle, incidentId, opts, apply } = args;
+  await withEntityWrite({ handle, id: incidentId, opts, apply });
+}
+
+/**
+ * Drive an incident tombstone through `handle.remove` (§10.1). `apply`
+ * performs the REAL delete via the service; the framework records the
+ * tombstone transition and emits a tombstone change (the deriver fires
+ * nothing — there is no `incident.deleted` trigger event). Without a handle,
+ * the delete still runs.
+ */
+export async function removeIncidentEntity(args: {
+  handle: EntityHandle<IncidentEntityState> | undefined;
+  incidentId: string;
+  apply: () => Promise<void>;
+}): Promise<void> {
+  const { handle, incidentId, apply } = args;
+  await withEntityRemove({ handle, id: incidentId, apply });
+}