@checkstack/incident-backend 1.3.0 → 1.5.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 });
+}

package/src/index.ts

@@ -12,7 +12,10 @@ import {
 import { createBackendPlugin, coreServices } from "@checkstack/backend-api";
 import {
   automationActionExtensionPoint,
+  automationArtifactTypeExtensionPoint,
   automationTriggerExtensionPoint,
+  entityExtensionPoint,
+  type EntityHandle,
 } from "@checkstack/automation-backend";
 import {
   NotificationApi,
@@ -22,16 +25,39 @@ import { IncidentService } from "./service";
 import { createRouter } from "./router";
 import { CatalogApi } from "@checkstack/catalog-common";
 import { AuthApi } from "@checkstack/auth-common";
-import { catalogHooks } from "@checkstack/catalog-backend";
+import { CATALOG_SYSTEM_ENTITY_KIND } from "@checkstack/catalog-backend";
+import {
+  INCIDENT_ENTITY_KIND,
+  IncidentEntityStateSchema,
+  createIncidentEntityRead,
+  deriveIncidentTriggerEvents,
+  incidentChangeToPayload,
+  type IncidentEntityState,
+} from "./incident-entity";
 import { registerSearchProvider } from "@checkstack/command-backend";
 import { resolveRoute } from "@checkstack/common";
 import { createIncidentCache } from "./cache";
-import { createIncidentActions, incidentTriggers } from "./automations";
+import {
+  createIncidentActions,
+  incidentArtifactType,
+  incidentTriggers,
+} from "./automations";
 
 // =============================================================================
 // Plugin Definition
 // =============================================================================
 
+// Reactive `incident` entity handle (§10.1). Defined in register(); mutated
+// from the router onward.
+let incidentEntity: EntityHandle<IncidentEntityState> | undefined;
+
+// The incident service is created in init() (it needs the resolved database),
+// but the PLUGIN-BACKED entity `read` accessor must be supplied at
+// `defineEntity` time in register(). This holder bridges the two: the `read`
+// closure resolves the service lazily, and init() sets it before any mutation
+// runs (the registry only mutates from init() onward).
+let incidentServiceRef: IncidentService | undefined;
+
 export default createBackendPlugin({
   metadata: pluginMetadata,
   register(env) {
@@ -41,10 +67,10 @@ export default createBackendPlugin({
       incidentGroupSubscription,
     ]);
 
-    // Register hooks as automation triggers — buffered until the
-    // automation plugin's `register()` runs and the extension point
-    // resolves. Triggers expose `contextKey` so wait_for_trigger can
-    // match resume events back to the originating incident.
+    // Register triggers — buffered until the automation plugin's
+    // `register()` runs and the extension point resolves. Triggers expose
+    // `contextKey` so wait_for_trigger can match resume events back to the
+    // originating incident.
     const automationTriggers = env.getExtensionPoint(
       automationTriggerExtensionPoint,
     );
@@ -52,6 +78,43 @@ export default createBackendPlugin({
       automationTriggers.registerTrigger(trigger, pluginMetadata);
     }
 
+    // ─── Reactive `incident` entity (§10.1) ────────────────────────────
+    // PLUGIN-BACKED (Model B): the `incidents` + `incident_systems` tables ARE
+    // the current-state storage. `read` routes straight to the service's
+    // batched authoritative read — no framework `entity_state` row, so no
+    // `indexes` (those only apply to store-backed kinds). The `read` closure
+    // resolves the service set by init() (mutations only happen from init on).
+    const entityPoint = env.getExtensionPoint(entityExtensionPoint);
+    incidentEntity = entityPoint.defineEntity<IncidentEntityState>({
+      kind: INCIDENT_ENTITY_KIND,
+      state: IncidentEntityStateSchema,
+      read: (ids) => {
+        const svc = incidentServiceRef;
+        if (!svc) {
+          throw new Error(
+            "incident entity read before init: service not yet resolved",
+          );
+        }
+        return createIncidentEntityRead(svc)(ids);
+      },
+    });
+    entityPoint.registerChangeDeriver({
+      kind: INCIDENT_ENTITY_KIND,
+      derive: deriveIncidentTriggerEvents,
+      toPayload: incidentChangeToPayload,
+    });
+    const onEntityChanged = entityPoint.onEntityChanged;
+
+    // Register the `incident` artifact type so `incident.create` can
+    // `produces` it and the close/update actions can `consumes` it.
+    const automationArtifactTypes = env.getExtensionPoint(
+      automationArtifactTypeExtensionPoint,
+    );
+    automationArtifactTypes.registerArtifactType(
+      incidentArtifactType,
+      pluginMetadata,
+    );
+
     let incidentCache:
       | ReturnType<typeof createIncidentCache>
       | undefined;
@@ -64,6 +127,7 @@ export default createBackendPlugin({
         rpcClient: coreServices.rpcClient,
         signalService: coreServices.signalService,
         cacheManager: coreServices.cacheManager,
+        advisoryLock: coreServices.advisoryLock,
       },
       init: async ({
         logger,
@@ -72,6 +136,7 @@ export default createBackendPlugin({
         rpcClient,
         signalService,
         cacheManager,
+        advisoryLock,
       }) => {
         logger.debug("🔧 Initializing Incident Backend...");
 
@@ -81,7 +146,11 @@ export default createBackendPlugin({
 
         const service = new IncidentService(
           database as SafeDatabase<typeof schema>,
+          advisoryLock,
         );
+        // Publish the service for the PLUGIN-BACKED entity `read` accessor
+        // (defined in register()). Mutations only run from here onward.
+        incidentServiceRef = service;
         const cache = createIncidentCache({ cacheManager, logger });
         incidentCache = cache;
         const router = createRouter(
@@ -92,6 +161,7 @@ export default createBackendPlugin({
           authClient,
           logger,
           cache,
+          () => incidentEntity,
         );
         rpc.registerRouter(router, incidentContract);
 
@@ -103,7 +173,10 @@ export default createBackendPlugin({
         const automationActions = env.getExtensionPoint(
           automationActionExtensionPoint,
         );
-        for (const action of createIncidentActions({ service })) {
+        for (const action of createIncidentActions({
+          service,
+          getIncidentEntity: () => incidentEntity,
+        })) {
           automationActions.registerAction(action, pluginMetadata);
         }
 
@@ -138,9 +211,14 @@ export default createBackendPlugin({
       // associations) + register subscription specs. Per-system /
       // per-group notification group lifecycle is fully owned by
       // notification-backend now — incident never touches it.
-      afterPluginsReady: async ({ database, logger, onHook, rpcClient }) => {
+      afterPluginsReady: async ({
+        database,
+        logger,
+        rpcClient,
+        advisoryLock,
+      }) => {
         const typedDb = database as SafeDatabase<typeof schema>;
-        const service = new IncidentService(typedDb);
+        const service = new IncidentService(typedDb, advisoryLock);
         const notificationClient = rpcClient.forPlugin(NotificationApi);
 
         await Promise.all([
@@ -152,17 +230,27 @@ export default createBackendPlugin({
           ),
         ]);
 
-        onHook(
-          catalogHooks.systemDeleted,
-          async (payload) => {
+        // React to catalog system deletion (tombstone) via the reactive
+        // `catalog-system` entity instead of the (being-removed)
+        // `system.deleted` hook (§10.1). `work-queue` delivery preserved:
+        // association cleanup is a side-effecting write that must run once
+        // per cluster, not per-instance.
+        onEntityChanged({
+          kind: CATALOG_SYSTEM_ENTITY_KIND,
+          handler: async (change) => {
+            if (change.next !== null) return; // tombstone only
+            const systemId = change.id;
             logger.debug(
-              `Cleaning up incident associations for deleted system: ${payload.systemId}`,
+              `Cleaning up incident associations for deleted system: ${systemId}`,
             );
-            await service.removeSystemAssociations(payload.systemId);
-            await incidentCache?.invalidateSystem(payload.systemId);
+            await service.removeSystemAssociations(systemId);
+            await incidentCache?.invalidateSystem(systemId);
           },
-          { mode: "work-queue", workerGroup: "incident-system-cleanup" },
-        );
+          delivery: {
+            mode: "work-queue",
+            workerGroup: "incident-system-cleanup",
+          },
+        });
 
         logger.debug("✅ Incident Backend afterPluginsReady complete.");
       },