@checkstack/incident-backend 1.2.0 → 1.4.0

package/src/index.ts

@@ -1,6 +1,5 @@
 import * as schema from "./schema";
 import type { SafeDatabase } from "@checkstack/backend-api";
-import { z } from "zod";
 import {
   incidentAccessRules,
   incidentAccess,
@@ -11,7 +10,13 @@ import {
   incidentGroupSubscription,
 } from "@checkstack/incident-common";
 import { createBackendPlugin, coreServices } from "@checkstack/backend-api";
-import { integrationEventExtensionPoint } from "@checkstack/integration-backend";
+import {
+  automationActionExtensionPoint,
+  automationArtifactTypeExtensionPoint,
+  automationTriggerExtensionPoint,
+  entityExtensionPoint,
+  type EntityHandle,
+} from "@checkstack/automation-backend";
 import {
   NotificationApi,
   specToRegistration,
@@ -20,47 +25,38 @@ 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 { incidentHooks } from "./hooks";
 import { createIncidentCache } from "./cache";
+import {
+  createIncidentActions,
+  incidentArtifactType,
+  incidentTriggers,
+} from "./automations";
 
 // =============================================================================
-// Integration Event Payload Schemas
+// Plugin Definition
 // =============================================================================
 
-const incidentCreatedPayloadSchema = z.object({
-  incidentId: z.string(),
-  systemIds: z.array(z.string()),
-  title: z.string(),
-  description: z.string().optional(),
-  severity: z.string(),
-  status: z.string(),
-  createdAt: z.string(),
-});
-
-const incidentUpdatedPayloadSchema = z.object({
-  incidentId: z.string(),
-  systemIds: z.array(z.string()),
-  title: z.string(),
-  description: z.string().optional(),
-  severity: z.string(),
-  status: z.string(),
-  statusChange: z.string().optional(),
-});
-
-const incidentResolvedPayloadSchema = z.object({
-  incidentId: z.string(),
-  systemIds: z.array(z.string()),
-  title: z.string(),
-  severity: z.string(),
-  resolvedAt: z.string(),
-});
+// Reactive `incident` entity handle (§10.1). Defined in register(); mutated
+// from the router onward.
+let incidentEntity: EntityHandle<IncidentEntityState> | undefined;
 
-// =============================================================================
-// Plugin Definition
-// =============================================================================
+// 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,
@@ -71,42 +67,51 @@ export default createBackendPlugin({
       incidentGroupSubscription,
     ]);
 
-    // Register hooks as integration events
-    const integrationEvents = env.getExtensionPoint(
-      integrationEventExtensionPoint,
+    // 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,
     );
-
-    integrationEvents.registerEvent(
-      {
-        hook: incidentHooks.incidentCreated,
-        displayName: "Incident Created",
-        description: "Fired when a new incident is created",
-        category: "Incidents",
-        payloadSchema: incidentCreatedPayloadSchema,
+    for (const trigger of incidentTriggers) {
+      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);
       },
-      pluginMetadata,
-    );
+    });
+    entityPoint.registerChangeDeriver({
+      kind: INCIDENT_ENTITY_KIND,
+      derive: deriveIncidentTriggerEvents,
+      toPayload: incidentChangeToPayload,
+    });
+    const onEntityChanged = entityPoint.onEntityChanged;
 
-    integrationEvents.registerEvent(
-      {
-        hook: incidentHooks.incidentUpdated,
-        displayName: "Incident Updated",
-        description:
-          "Fired when an incident is updated (info or status change)",
-        category: "Incidents",
-        payloadSchema: incidentUpdatedPayloadSchema,
-      },
-      pluginMetadata,
+    // Register the `incident` artifact type so `incident.create` can
+    // `produces` it and the close/update actions can `consumes` it.
+    const automationArtifactTypes = env.getExtensionPoint(
+      automationArtifactTypeExtensionPoint,
     );
-
-    integrationEvents.registerEvent(
-      {
-        hook: incidentHooks.incidentResolved,
-        displayName: "Incident Resolved",
-        description: "Fired when an incident is marked as resolved",
-        category: "Incidents",
-        payloadSchema: incidentResolvedPayloadSchema,
-      },
+    automationArtifactTypes.registerArtifactType(
+      incidentArtifactType,
       pluginMetadata,
     );
 
@@ -140,6 +145,9 @@ export default createBackendPlugin({
         const service = new IncidentService(
           database as SafeDatabase<typeof schema>,
         );
+        // 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(
@@ -150,9 +158,25 @@ export default createBackendPlugin({
           authClient,
           logger,
           cache,
+          () => incidentEntity,
         );
         rpc.registerRouter(router, incidentContract);
 
+        // Register incident actions with the Automation platform. We
+        // capture the service in closure here (rather than via a
+        // service ref + ctx.getService at execute time) because the
+        // service has no per-request state — one instance for the life
+        // of the plugin is correct.
+        const automationActions = env.getExtensionPoint(
+          automationActionExtensionPoint,
+        );
+        for (const action of createIncidentActions({
+          service,
+          getIncidentEntity: () => incidentEntity,
+        })) {
+          automationActions.registerAction(action, pluginMetadata);
+        }
+
         // Register "Create Incident" command in the command palette
         registerSearchProvider({
           pluginMetadata,
@@ -184,7 +208,7 @@ 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 }) => {
         const typedDb = database as SafeDatabase<typeof schema>;
         const service = new IncidentService(typedDb);
         const notificationClient = rpcClient.forPlugin(NotificationApi);
@@ -198,17 +222,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.");
       },

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,