@checkstack/incident-backend 1.3.0 → 1.4.0

package/src/router.ts

@@ -14,10 +14,19 @@ import type { IncidentService } from "./service";
 import { CatalogApi } from "@checkstack/catalog-common";
 import { AuthApi } from "@checkstack/auth-common";
 import type { InferClient } from "@checkstack/common";
-import { incidentHooks } from "./hooks";
 import { notifyAffectedSystems } from "./notifications";
-import type { IncidentUpdate } from "@checkstack/incident-common";
+import type {
+  IncidentUpdate,
+  IncidentWithSystems,
+} from "@checkstack/incident-common";
 import type { IncidentCache } from "./cache";
+import type { EntityHandle } from "@checkstack/automation-backend";
+import {
+  writeIncidentEntity,
+  removeIncidentEntity,
+  toIncidentEntityState,
+  type IncidentEntityState,
+} from "./incident-entity";
 
 export function createRouter(
   service: IncidentService,
@@ -29,6 +38,8 @@ export function createRouter(
   authClient: InferClient<typeof AuthApi>,
   logger: Logger,
   cache: IncidentCache,
+  /** Resolver for the reactive `incident` entity (§10.1). Undefined in tests. */
+  getIncidentEntity?: () => EntityHandle<IncidentEntityState> | undefined,
 ) {
   /**
    * Resolve user IDs to profile names for a list of updates.
@@ -148,7 +159,23 @@ export function createRouter(
     createIncident: os.createIncident.handler(async ({ input, context }) => {
       const userId =
         context.user && "id" in context.user ? context.user.id : undefined;
-      const result = await service.createIncident(input, userId);
+
+      // Drive the create through the reactive `incident` entity (§10.1):
+      // `apply` performs the REAL `incidents`/junction write (the plugin's own
+      // db/tx) and returns the new reactive state; the deriver fires
+      // `incident.created` from the resulting change. The id is generated up
+      // front so the handle is keyed on it and the create's `prev` snapshot
+      // correctly reads the not-yet-existing row as absent.
+      const incidentId = crypto.randomUUID();
+      let result!: Awaited<ReturnType<typeof service.createIncident>>;
+      await writeIncidentEntity({
+        handle: getIncidentEntity?.(),
+        incidentId,
+        apply: async () => {
+          result = await service.createIncident(input, userId, incidentId);
+          return toIncidentEntityState(result);
+        },
+      });
 
       // Invalidate before signal so any frontend that refetches in response
       // sees fresh data. The mutation invariant for every handler in this
@@ -165,17 +192,6 @@ export function createRouter(
         action: "created",
       });
 
-      // Emit hook for cross-plugin coordination
-      await context.emitHook(incidentHooks.incidentCreated, {
-        incidentId: result.id,
-        systemIds: result.systemIds,
-        title: result.title,
-        description: result.description,
-        severity: result.severity,
-        status: result.status,
-        createdAt: result.createdAt.toISOString(),
-      });
-
       // Send notifications to system subscribers
       const systemNames = await resolveSystemNames(result.systemIds);
       await notifyAffectedSystems({
@@ -193,12 +209,32 @@ export function createRouter(
       return result;
     }),
 
-    updateIncident: os.updateIncident.handler(async ({ input, context }) => {
-      const result = await service.updateIncident(input);
-      if (!result) {
+    updateIncident: os.updateIncident.handler(async ({ input }) => {
+      // Probe existence first so a missing incident still surfaces as
+      // NOT_FOUND without driving an entity write.
+      const exists = await service.getIncident(input.id);
+      if (!exists) {
         throw new ORPCError("NOT_FOUND", { message: "Incident not found" });
       }
 
+      // Drive the update through the reactive `incident` entity (§10.1);
+      // `apply` performs the REAL update (the plugin's own db/tx) and returns
+      // the new reactive state. The deriver fires `incident.updated` (or
+      // `incident.resolved` on a resolution) from the resulting change.
+      let result!: NonNullable<Awaited<ReturnType<typeof service.updateIncident>>>;
+      await writeIncidentEntity({
+        handle: getIncidentEntity?.(),
+        incidentId: input.id,
+        apply: async () => {
+          const updated = await service.updateIncident(input);
+          if (!updated) {
+            throw new ORPCError("NOT_FOUND", { message: "Incident not found" });
+          }
+          result = updated;
+          return toIncidentEntityState(result);
+        },
+      });
+
       await cache.invalidateForMutation({
         incidentId: result.id,
         systemIds: result.systemIds,
@@ -211,16 +247,6 @@ export function createRouter(
         action: "updated",
       });
 
-      // Emit hook for cross-plugin coordination
-      await context.emitHook(incidentHooks.incidentUpdated, {
-        incidentId: result.id,
-        systemIds: result.systemIds,
-        title: result.title,
-        description: result.description,
-        severity: result.severity,
-        status: result.status,
-      });
-
       // Send notifications to system subscribers
       const systemNames = await resolveSystemNames(result.systemIds);
       await notifyAffectedSystems({
@@ -248,11 +274,30 @@ export function createRouter(
         : undefined;
       const previousStatus = previousIncident?.status;
 
-      const result = await service.addUpdate(input, userId);
+      // Drive the update through the reactive `incident` entity (§10.1).
+      // `apply` posts the update row + (optionally) flips status in the
+      // plugin's own db/tx, then re-reads the post-write reactive state. The
+      // deriver fires `incident.resolved` on a transition to resolved,
+      // otherwise `incident.updated` — purely from the entity diff (so the
+      // `statusChange` branch collapses into the single driven write). When
+      // the status is unchanged, the diff is empty and no event fires.
+      let result!: Awaited<ReturnType<typeof service.addUpdate>>;
+      let incident: Awaited<ReturnType<typeof service.getIncident>>;
+      await writeIncidentEntity({
+        handle: getIncidentEntity?.(),
+        incidentId: input.incidentId,
+        apply: async () => {
+          result = await service.addUpdate(input, userId);
+          incident = await service.getIncident(input.incidentId);
+          // The incident must exist (the update FK-references it); guard for
+          // the type and to fail loudly if it vanished mid-write.
+          if (!incident) {
+            throw new ORPCError("NOT_FOUND", { message: "Incident not found" });
+          }
+          return toIncidentEntityState(incident);
+        },
+      });
 
-      // Read post-write state directly from the service so the broadcast
-      // payload is fresh; the cache is invalidated below before the signal.
-      const incident = await service.getIncident(input.incidentId);
       if (incident) {
         await cache.invalidateForMutation({
           incidentId: input.incidentId,
@@ -265,28 +310,6 @@ export function createRouter(
           action: "updated",
         });
 
-        // Emit hook for cross-plugin coordination
-        await context.emitHook(incidentHooks.incidentUpdated, {
-          incidentId: input.incidentId,
-          systemIds: incident.systemIds,
-          title: incident.title,
-          description: incident.description,
-          severity: incident.severity,
-          status: incident.status,
-          statusChange: input.statusChange,
-        });
-
-        // If status changed to resolved, emit resolved hook
-        if (input.statusChange === "resolved") {
-          await context.emitHook(incidentHooks.incidentResolved, {
-            incidentId: input.incidentId,
-            systemIds: incident.systemIds,
-            title: incident.title,
-            severity: incident.severity,
-            resolvedAt: new Date().toISOString(),
-          });
-        }
-
         // Send notifications when status changes
         if (input.statusChange && previousStatus !== input.statusChange) {
           // Determine notification action based on status transition
@@ -321,15 +344,34 @@ export function createRouter(
     resolveIncident: os.resolveIncident.handler(async ({ input, context }) => {
       const userId =
         context.user && "id" in context.user ? context.user.id : undefined;
-      const result = await service.resolveIncident(
-        input.id,
-        input.message,
-        userId,
-      );
-      if (!result) {
+
+      const exists = await service.getIncident(input.id);
+      if (!exists) {
         throw new ORPCError("NOT_FOUND", { message: "Incident not found" });
       }
 
+      // Drive the resolve through the reactive `incident` entity (§10.1);
+      // `apply` performs the REAL resolve (the plugin's own db/tx) and returns
+      // the new reactive state. The deriver fires `incident.resolved` from the
+      // status → resolved transition.
+      let result!: NonNullable<Awaited<ReturnType<typeof service.resolveIncident>>>;
+      await writeIncidentEntity({
+        handle: getIncidentEntity?.(),
+        incidentId: input.id,
+        apply: async () => {
+          const resolved = await service.resolveIncident(
+            input.id,
+            input.message,
+            userId,
+          );
+          if (!resolved) {
+            throw new ORPCError("NOT_FOUND", { message: "Incident not found" });
+          }
+          result = resolved;
+          return toIncidentEntityState(result);
+        },
+      });
+
       await cache.invalidateForMutation({
         incidentId: result.id,
         systemIds: result.systemIds,
@@ -342,15 +384,6 @@ export function createRouter(
         action: "resolved",
       });
 
-      // Emit hook for cross-plugin coordination
-      await context.emitHook(incidentHooks.incidentResolved, {
-        incidentId: result.id,
-        systemIds: result.systemIds,
-        title: result.title,
-        severity: result.severity,
-        resolvedAt: new Date().toISOString(),
-      });
-
       // Send notifications to system subscribers
       const systemNames = await resolveSystemNames(result.systemIds);
       await notifyAffectedSystems({
@@ -369,10 +402,27 @@ export function createRouter(
     }),
 
     deleteIncident: os.deleteIncident.handler(async ({ input }) => {
-      // Get incident before deleting to get systemIds
+      // Get incident before deleting to get systemIds.
       const incident = await service.getIncident(input.id);
-      const success = await service.deleteIncident(input.id);
-      if (success && incident) {
+      if (!incident) {
+        return { success: false };
+      }
+
+      // Drive the delete through the reactive `incident` entity tombstone
+      // (§10.1). `apply` performs the REAL delete (the plugin's own db/tx);
+      // the framework records the tombstone transition and emits a tombstone
+      // change. No `incident.deleted` trigger event exists, so the deriver
+      // fires nothing. `success` tracks whether the row was actually deleted.
+      let success = false;
+      await removeIncidentEntity({
+        handle: getIncidentEntity?.(),
+        incidentId: input.id,
+        apply: async () => {
+          success = await service.deleteIncident(input.id);
+        },
+      });
+
+      if (success) {
         await cache.invalidateForMutation({
           incidentId: input.id,
           systemIds: incident.systemIds,
@@ -396,11 +446,22 @@ export function createRouter(
       }),
 
     createAutoIncident: os.createAutoIncident.handler(
-      async ({ input, context }) => {
-        // No user context for service-initiated incidents; createdBy
-        // stays null and the timeline shows the originating plugin via
-        // the hook payload.
-        const result = await service.createIncident(input);
+      async ({ input }) => {
+        // No user context for service-initiated incidents; createdBy stays
+        // null and the timeline shows the originating plugin via the entity
+        // state. Driven through the reactive `incident` entity (§10.1); the
+        // deriver fires `incident.created` from the resulting change. The id
+        // is generated up front so the create's `prev` snapshot is null.
+        const incidentId = crypto.randomUUID();
+        let result!: Awaited<ReturnType<typeof service.createIncident>>;
+        await writeIncidentEntity({
+          handle: getIncidentEntity?.(),
+          incidentId,
+          apply: async () => {
+            result = await service.createIncident(input, undefined, incidentId);
+            return toIncidentEntityState(result);
+          },
+        });
 
         await cache.invalidateForMutation({
           incidentId: result.id,
@@ -413,16 +474,6 @@ export function createRouter(
           action: "created",
         });
 
-        await context.emitHook(incidentHooks.incidentCreated, {
-          incidentId: result.id,
-          systemIds: result.systemIds,
-          title: result.title,
-          description: result.description,
-          severity: result.severity,
-          status: result.status,
-          createdAt: result.createdAt.toISOString(),
-        });
-
         const systemNames = await resolveSystemNames(result.systemIds);
         await notifyAffectedSystems({
           catalogClient,
@@ -441,10 +492,31 @@ export function createRouter(
     ),
 
     resolveAutoIncident: os.resolveAutoIncident.handler(
-      async ({ input, context }) => {
-        const result = await service.resolveIncident(input.id, input.message);
-        // Idempotent: a missing or already-resolved incident is treated
-        // as success so the auto-close worker can be re-run safely.
+      async ({ input }) => {
+        // Idempotent: a missing incident is treated as success so the
+        // auto-close worker can be re-run safely. Probe first so the no-op
+        // case never drives an entity write.
+        const exists = await service.getIncident(input.id);
+        if (!exists) {
+          return { success: true };
+        }
+
+        // Drive the resolve through the reactive `incident` entity (§10.1):
+        // the REAL resolve runs INSIDE `apply`, so `prev` is snapshotted
+        // before the status flips and the deriver fires `incident.resolved`
+        // from the status → resolved transition. An already-resolved incident
+        // yields an empty diff and no event — the idempotent re-run case.
+        let result: IncidentWithSystems | undefined;
+        await writeIncidentEntity({
+          handle: getIncidentEntity?.(),
+          incidentId: input.id,
+          apply: async () => {
+            result = await service.resolveIncident(input.id, input.message);
+            // The probe found it; a race could still delete it mid-write.
+            // Fall back to the pre-write state so the diff is a no-op.
+            return toIncidentEntityState(result ?? exists);
+          },
+        });
         if (!result) {
           return { success: true };
         }
@@ -460,14 +532,6 @@ export function createRouter(
           action: "resolved",
         });
 
-        await context.emitHook(incidentHooks.incidentResolved, {
-          incidentId: result.id,
-          systemIds: result.systemIds,
-          title: result.title,
-          severity: result.severity,
-          resolvedAt: new Date().toISOString(),
-        });
-
         const systemNames = await resolveSystemNames(result.systemIds);
         await notifyAffectedSystems({
           catalogClient,

package/src/service.test.ts

@@ -1,5 +1,11 @@
 import { describe, it, expect, mock, beforeEach } from "bun:test";
 import { IncidentService } from "./service";
+import {
+  incidents,
+  incidentSystems,
+  incidentUpdates,
+  incidentLinks,
+} from "./schema";
 
 /**
  * Programmable mock DB that records each `select(...).from(...).where(...)`
@@ -124,3 +130,196 @@ describe("IncidentService.hasActiveIncidentWithSuppression", () => {
     expect(dbHelper.getCallCount()).toBe(1);
   });
 });
+
+describe("IncidentService.getManyEntityStates (plugin-backed entity read)", () => {
+  it("returns {} for an empty id set without querying", async () => {
+    const dbHelper = createProgrammableSelectDb([]);
+    const service = new IncidentService(dbHelper.db as never);
+    expect(await service.getManyEntityStates([])).toEqual({});
+    expect(dbHelper.getCallCount()).toBe(0);
+  });
+
+  it("projects { status, severity, systemIds } from incidents + junction", async () => {
+    const dbHelper = createProgrammableSelectDb([
+      // 1st query: incidents rows for the requested ids.
+      [
+        { id: "inc-1", status: "investigating", severity: "major" },
+        { id: "inc-2", status: "resolved", severity: "minor" },
+      ],
+      // 2nd query: incident_systems junction rows for the present ids.
+      [
+        { incidentId: "inc-1", systemId: "sys-a" },
+        { incidentId: "inc-1", systemId: "sys-b" },
+        { incidentId: "inc-2", systemId: "sys-c" },
+      ],
+    ]);
+    const service = new IncidentService(dbHelper.db as never);
+    const out = await service.getManyEntityStates(["inc-1", "inc-2", "inc-x"]);
+    expect(out).toEqual({
+      "inc-1": {
+        status: "investigating",
+        severity: "major",
+        systemIds: ["sys-a", "sys-b"],
+      },
+      "inc-2": { status: "resolved", severity: "minor", systemIds: ["sys-c"] },
+    });
+    // Missing ids are omitted (never a null/undefined entry).
+    expect("inc-x" in out).toBe(false);
+  });
+
+  it("returns {} when none of the ids exist (no junction query)", async () => {
+    const dbHelper = createProgrammableSelectDb([
+      // incidents query returns nothing → no second query.
+      [],
+    ]);
+    const service = new IncidentService(dbHelper.db as never);
+    expect(await service.getManyEntityStates(["ghost"])).toEqual({});
+    expect(dbHelper.getCallCount()).toBe(1);
+  });
+
+  it("yields an empty systemIds array for an incident with no systems", async () => {
+    const dbHelper = createProgrammableSelectDb([
+      [{ id: "inc-1", status: "monitoring", severity: "critical" }],
+      [], // no junction rows
+    ]);
+    const service = new IncidentService(dbHelper.db as never);
+    const out = await service.getManyEntityStates(["inc-1"]);
+    expect(out["inc-1"]).toEqual({
+      status: "monitoring",
+      severity: "critical",
+      systemIds: [],
+    });
+  });
+});
+
+/**
+ * Table-backed fake `db` for the dedup-create path. Models just enough of
+ * the Drizzle surface the service touches (select/insert by TABLE IDENTITY,
+ * `.from`/`.where`/`.limit`, and a serializing `transaction`).
+ *
+ * Crucially `transaction(fn)` models `pg_advisory_xact_lock`: it serializes
+ * callers on the lock key seen in the `tx.execute(...)` SQL, so concurrent
+ * dedup-creates run their find-then-create one-at-a-time — exactly the
+ * guarantee M3 needs. Because the test confines data to a single system,
+ * the (ignored) WHERE clauses don't change which rows match.
+ */
+function createDedupFakeDb() {
+  const store = {
+    incidents: [] as Array<Record<string, unknown>>,
+    incidentSystems: [] as Array<Record<string, unknown>>,
+    incidentUpdates: [] as Array<Record<string, unknown>>,
+    incidentLinks: [] as Array<Record<string, unknown>>,
+  };
+
+  const tableKey = (
+    table: unknown,
+  ): keyof typeof store | undefined => {
+    if (table === incidents) return "incidents";
+    if (table === incidentSystems) return "incidentSystems";
+    if (table === incidentUpdates) return "incidentUpdates";
+    if (table === incidentLinks) return "incidentLinks";
+    return undefined;
+  };
+
+  // Per-key serialization (the xact-lock model).
+  const tails = new Map<string, Promise<unknown>>();
+
+  function buildSelect() {
+    return (projection?: Record<string, unknown>) => {
+      const project = (
+        list: Array<Record<string, unknown>>,
+      ): Array<Record<string, unknown>> => {
+        if (!projection) return list;
+        const keys = Object.keys(projection);
+        return list.map((r) => {
+          const out: Record<string, unknown> = {};
+          for (const k of keys) out[k] = r[k];
+          return out;
+        });
+      };
+      const from = (table: unknown) => {
+        const key = tableKey(table);
+        const rows = key ? project([...store[key]]) : [];
+        const limit = (n: number) => Promise.resolve(rows.slice(0, n));
+        const where = () =>
+          Object.assign(Promise.resolve(rows), { limit });
+        return Object.assign(Promise.resolve(rows), { where, limit });
+      };
+      return { from };
+    };
+  }
+
+  function buildInsert() {
+    return (table: unknown) => ({
+      values: (vals: Record<string, unknown>) => {
+        const key = tableKey(table);
+        if (key) store[key].push({ ...vals });
+        return Promise.resolve();
+      },
+    });
+  }
+
+  const db = {
+    select: buildSelect(),
+    insert: buildInsert(),
+    async transaction<T>(fn: (tx: unknown) => Promise<T>): Promise<T> {
+      // The lock key is embedded in the SQL the helper runs via tx.execute.
+      let lockKey = "default";
+      const tx = {
+        execute: async (sqlObj: unknown) => {
+          // Drizzle sql`` carries the interpolated key in its params; the
+          // helper interpolates exactly one param (the lock key).
+          const params = (sqlObj as { queryChunks?: unknown[] }).queryChunks;
+          const found = JSON.stringify(params ?? sqlObj).match(
+            /incident\.dedupe-open-for-system:[^"\\]+/,
+          );
+          if (found) lockKey = found[0];
+          return { rows: [] };
+        },
+      };
+      // Serialize on the lock key: chain after the current tail.
+      const prior = tails.get(lockKey) ?? Promise.resolve();
+      let resolveTail!: () => void;
+      const myTail = new Promise<void>((r) => (resolveTail = r));
+      tails.set(
+        lockKey,
+        prior.then(() => myTail),
+      );
+      await prior;
+      try {
+        return await fn(tx);
+      } finally {
+        resolveTail();
+      }
+    },
+  };
+
+  return { db: db as unknown, store };
+}
+
+describe("IncidentService.createIncidentDedupedForSystem (M3)", () => {
+  it("two concurrent dedupe creates for one system open exactly ONE incident", async () => {
+    const { db, store } = createDedupFakeDb();
+    const service = new IncidentService(db as never);
+
+    const input = {
+      title: "Down",
+      severity: "critical" as const,
+      systemIds: ["sys-1"],
+      suppressNotifications: false,
+    };
+
+    // Sustained + flapping fire concurrently for the same system. Without
+    // the per-system lock both would find no open incident and both create.
+    const [a, b] = await Promise.all([
+      service.createIncidentDedupedForSystem(input, "sys-1"),
+      service.createIncidentDedupedForSystem(input, "sys-1"),
+    ]);
+
+    // Exactly one incident row created.
+    expect(store.incidents).toHaveLength(1);
+    // One created, one reused — both return the same incident id.
+    expect(a.incident.id).toBe(b.incident.id);
+    expect([a.reused, b.reused].filter(Boolean)).toHaveLength(1);
+  });
+});