@checkstack/incident-backend 1.10.0 → 1.12.0

package/drizzle/meta/_journal.json

@@ -36,6 +36,20 @@
       "when": 1783287429703,
       "tag": "0004_flaky_malcolm_colcord",
       "breakpoints": true
+    },
+    {
+      "idx": 5,
+      "version": "7",
+      "when": 1783498751737,
+      "tag": "0005_real_leper_queen",
+      "breakpoints": true
+    },
+    {
+      "idx": 6,
+      "version": "7",
+      "when": 1783535507970,
+      "tag": "0006_last_princess_powerful",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/incident-backend",
-  "version": "1.10.0",
+  "version": "1.12.0",
   "license": "Elastic-2.0",
   "type": "module",
   "main": "src/index.ts",
@@ -14,25 +14,25 @@
     "lint:code": "eslint . --max-warnings 0"
   },
   "dependencies": {
-    "@checkstack/ai-backend": "0.10.8",
-    "@checkstack/ai-common": "0.6.5",
-    "@checkstack/backend-api": "0.30.0",
-    "@checkstack/cache-api": "0.3.18",
-    "@checkstack/cache-utils": "0.2.23",
-    "@checkstack/incident-common": "1.8.0",
-    "@checkstack/catalog-common": "2.6.2",
-    "@checkstack/catalog-backend": "1.6.8",
-    "@checkstack/notification-common": "1.5.2",
-    "@checkstack/auth-common": "0.12.2",
-    "@checkstack/command-backend": "0.2.20",
-    "@checkstack/signal-common": "0.2.16",
-    "@checkstack/status-page-backend": "0.4.7",
-    "@checkstack/status-page-common": "0.5.2",
-    "@checkstack/integration-backend": "0.7.2",
-    "@checkstack/integration-common": "0.9.7",
-    "@checkstack/automation-backend": "0.10.10",
-    "@checkstack/automation-common": "0.9.2",
-    "@checkstack/common": "0.21.0",
+    "@checkstack/ai-backend": "0.10.10",
+    "@checkstack/ai-common": "0.6.6",
+    "@checkstack/backend-api": "0.31.1",
+    "@checkstack/cache-api": "0.3.19",
+    "@checkstack/cache-utils": "0.2.24",
+    "@checkstack/incident-common": "1.10.0",
+    "@checkstack/catalog-common": "2.7.0",
+    "@checkstack/catalog-backend": "1.7.0",
+    "@checkstack/notification-common": "1.6.0",
+    "@checkstack/auth-common": "0.13.0",
+    "@checkstack/command-backend": "0.2.22",
+    "@checkstack/signal-common": "0.2.17",
+    "@checkstack/status-page-backend": "0.5.0",
+    "@checkstack/status-page-common": "0.6.0",
+    "@checkstack/integration-backend": "0.7.4",
+    "@checkstack/integration-common": "0.9.8",
+    "@checkstack/automation-backend": "0.11.1",
+    "@checkstack/automation-common": "0.10.0",
+    "@checkstack/common": "0.22.0",
     "drizzle-orm": "^0.45.0",
     "zod": "^4.2.1",
     "@orpc/contract": "^1.14.4",
@@ -40,11 +40,13 @@
   },
   "devDependencies": {
     "@checkstack/drizzle-helper": "0.0.6",
-    "@checkstack/scripts": "0.7.2",
-    "@checkstack/test-utils-backend": "0.1.54",
+    "@checkstack/scripts": "0.7.3",
+    "@checkstack/test-utils-backend": "0.1.56",
     "@checkstack/tsconfig": "0.0.7",
     "@types/bun": "^1.0.0",
+    "@types/pg": "^8.20.0",
     "drizzle-kit": "^0.31.10",
+    "pg": "^8.21.0",
     "typescript": "^5.0.0"
   }
 }

package/src/ai/incident-add-link.test.ts

@@ -50,6 +50,7 @@ describe("incident.addLink tool", () => {
       incidentId: input.incidentId,
       label: input.label ?? null,
       url: input.url,
+      visibility: "public" as const,
       createdAt: new Date(),
     };
     const addLink = mock(() => Promise.resolve(created));

package/src/ai/incident-add-update.test.ts

@@ -45,7 +45,12 @@ describe("incident.addUpdate tool", () => {
   });
 
   test("execute (apply) posts via addUpdate", async () => {
-    const created = { id: "upd1", ...input, createdAt: new Date() };
+    const created = {
+      id: "upd1",
+      ...input,
+      visibility: "public" as const,
+      createdAt: new Date(),
+    };
     const addUpdate = mock(() => Promise.resolve(created));
     const rpcClient = fakeRpcClient({ addUpdate });
     const tool = createIncidentAddUpdateTool();

package/src/ai/incident-delete-update.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, test, mock } from "bun:test";
+import type { AuthUser, RpcClient } from "@checkstack/backend-api";
+import { createIncidentDeleteUpdateTool } from "./incident-delete-update";
+
+const principal: AuthUser = {
+  type: "user",
+  id: "u1",
+  accessRules: ["incident.incident.manage"],
+};
+
+function fakeRpcClient({
+  deleteUpdate,
+}: {
+  deleteUpdate: ReturnType<typeof mock>;
+}): RpcClient {
+  return {
+    forPlugin: () => ({ deleteUpdate }),
+  } as unknown as RpcClient;
+}
+
+describe("incident.deleteUpdate tool", () => {
+  test("declares destructive effect + the manage rule", () => {
+    const tool = createIncidentDeleteUpdateTool();
+    expect(tool.name).toBe("incident.deleteUpdate");
+    expect(tool.effect).toBe("destructive");
+    expect(tool.requiredAccessRules).toEqual(["incident.incident.manage"]);
+    expect(typeof tool.dryRun).toBe("function");
+  });
+
+  test("dryRun returns a payload and NEVER deletes the update", async () => {
+    const deleteUpdate = mock(() => Promise.resolve({ success: true }));
+    const rpcClient = fakeRpcClient({ deleteUpdate });
+    const tool = createIncidentDeleteUpdateTool();
+    const preview = await tool.dryRun!({
+      input: { id: "upd1", incidentId: "inc1" },
+      principal,
+      rpcClient,
+    });
+    expect(deleteUpdate).not.toHaveBeenCalled();
+    expect(preview.summary).toContain("permanent");
+    expect(preview.payload).toEqual({ id: "upd1", incidentId: "inc1" });
+  });
+
+  test("execute (apply) deletes via deleteUpdate with {id, incidentId}", async () => {
+    const deleteUpdate = mock(() => Promise.resolve({ success: true }));
+    const rpcClient = fakeRpcClient({ deleteUpdate });
+    const tool = createIncidentDeleteUpdateTool();
+    const result = await tool.execute({
+      input: { id: "upd1", incidentId: "inc1" },
+      principal,
+      rpcClient,
+    });
+    expect(deleteUpdate).toHaveBeenCalledWith({
+      id: "upd1",
+      incidentId: "inc1",
+    });
+    expect(result).toEqual({ id: "upd1", removed: true });
+  });
+});

package/src/ai/incident-delete-update.ts

@@ -0,0 +1,73 @@
+import { z } from "zod";
+import { qualifyAccessRuleId } from "@checkstack/common";
+import type { RpcClient, AuthUser } from "@checkstack/backend-api";
+import {
+  IncidentApi,
+  incidentAccess,
+  pluginMetadata,
+} from "@checkstack/incident-common";
+import type { AiProposalPreview } from "@checkstack/ai-common";
+import type { RegisteredAiTool } from "@checkstack/ai-backend";
+
+/** Input for `incident.deleteUpdate`: the update id + its owning incident. */
+export const IncidentDeleteUpdateInputSchema = z.object({
+  id: z.string(),
+  incidentId: z.string(),
+});
+export type IncidentDeleteUpdateInput = z.infer<
+  typeof IncidentDeleteUpdateInputSchema
+>;
+
+/** Output returned once a human applies the update removal. */
+export interface IncidentDeleteUpdateApplyResult {
+  id: string;
+  removed: true;
+}
+
+/**
+ * `incident.deleteUpdate` - delete a published status update by id.
+ *
+ * `effect: "destructive"` - deleting an update is irreversible, so it ALWAYS
+ * routes through the propose/apply confirm card in BOTH permission modes (it can
+ * never auto-apply). `dryRun` returns the captured payload for human review
+ * WITHOUT mutating; `execute` (reached only via `apply`) deletes the update. The
+ * underlying RPC uses the USER-SCOPED client passed at call time, so
+ * handler-side authorization is enforced exactly as a direct UI/RPC call.
+ */
+export function createIncidentDeleteUpdateTool(): RegisteredAiTool<
+  IncidentDeleteUpdateInput,
+  IncidentDeleteUpdateApplyResult
+> {
+  const dryRun = async ({
+    input,
+  }: {
+    input: IncidentDeleteUpdateInput;
+    principal: AuthUser;
+    rpcClient: RpcClient;
+  }): Promise<AiProposalPreview<IncidentDeleteUpdateInput>> => {
+    return {
+      summary: `Delete update ${input.id} from incident ${input.incidentId}. This is permanent.`,
+      payload: { id: input.id, incidentId: input.incidentId },
+    };
+  };
+
+  return {
+    name: "incident.deleteUpdate",
+    description:
+      "Delete a published status update from an incident by update id and its owning incidentId. DESTRUCTIVE and irreversible. Never deletes directly; a person must approve the confirmation. Find the update id and incidentId by reading the incident's details first.",
+    effect: "destructive",
+    input: IncidentDeleteUpdateInputSchema,
+    requiredAccessRules: [
+      qualifyAccessRuleId(pluginMetadata, incidentAccess.incident.manage),
+    ],
+    dryRun,
+    async execute({ input, rpcClient }) {
+      const incidentClient = rpcClient.forPlugin(IncidentApi);
+      await incidentClient.deleteUpdate({
+        id: input.id,
+        incidentId: input.incidentId,
+      });
+      return { id: input.id, removed: true };
+    },
+  };
+}

package/src/ai/incident-remove-link.test.ts

@@ -32,25 +32,25 @@ describe("incident.removeLink tool", () => {
     const rpcClient = fakeRpcClient({ removeLink });
     const tool = createIncidentRemoveLinkTool();
     const preview = await tool.dryRun!({
-      input: { id: "lnk1" },
+      input: { id: "lnk1", incidentId: "inc1" },
       principal,
       rpcClient,
     });
     expect(removeLink).not.toHaveBeenCalled();
     expect(preview.summary).toContain("permanent");
-    expect(preview.payload).toEqual({ id: "lnk1" });
+    expect(preview.payload).toEqual({ id: "lnk1", incidentId: "inc1" });
   });
 
-  test("execute (apply) removes via removeLink with {id}", async () => {
+  test("execute (apply) removes via removeLink with {id, incidentId}", async () => {
     const removeLink = mock(() => Promise.resolve({ success: true }));
     const rpcClient = fakeRpcClient({ removeLink });
     const tool = createIncidentRemoveLinkTool();
     const result = await tool.execute({
-      input: { id: "lnk1" },
+      input: { id: "lnk1", incidentId: "inc1" },
       principal,
       rpcClient,
     });
-    expect(removeLink).toHaveBeenCalledWith({ id: "lnk1" });
+    expect(removeLink).toHaveBeenCalledWith({ id: "lnk1", incidentId: "inc1" });
     expect(result).toEqual({ id: "lnk1", removed: true });
   });
 });

package/src/ai/incident-remove-link.ts

@@ -9,9 +9,10 @@ import {
 import type { AiProposalPreview } from "@checkstack/ai-common";
 import type { RegisteredAiTool } from "@checkstack/ai-backend";
 
-/** Input for `incident.removeLink`: the link id to remove. */
+/** Input for `incident.removeLink`: the link id to remove + its owning incident. */
 export const IncidentRemoveLinkInputSchema = z.object({
   id: z.string(),
+  incidentId: z.string(),
 });
 export type IncidentRemoveLinkInput = z.infer<
   typeof IncidentRemoveLinkInputSchema
@@ -45,15 +46,15 @@ export function createIncidentRemoveLinkTool(): RegisteredAiTool<
     rpcClient: RpcClient;
   }): Promise<AiProposalPreview<IncidentRemoveLinkInput>> => {
     return {
-      summary: `Remove link ${input.id} from its incident. This is permanent.`,
-      payload: { id: input.id },
+      summary: `Remove link ${input.id} from incident ${input.incidentId}. This is permanent.`,
+      payload: { id: input.id, incidentId: input.incidentId },
     };
   };
 
   return {
     name: "incident.removeLink",
     description:
-      "Remove a hotlink from an incident by link id. DESTRUCTIVE and irreversible. Never removes directly; a person must approve the confirmation. Find the link id by reading the incident's details first.",
+      "Remove a hotlink from an incident by link id and its owning incidentId. DESTRUCTIVE and irreversible. Never removes directly; a person must approve the confirmation. Find the link id and incidentId by reading the incident's details first.",
     effect: "destructive",
     input: IncidentRemoveLinkInputSchema,
     requiredAccessRules: [
@@ -62,7 +63,10 @@ export function createIncidentRemoveLinkTool(): RegisteredAiTool<
     dryRun,
     async execute({ input, rpcClient }) {
       const incidentClient = rpcClient.forPlugin(IncidentApi);
-      await incidentClient.removeLink({ id: input.id });
+      await incidentClient.removeLink({
+        id: input.id,
+        incidentId: input.incidentId,
+      });
       return { id: input.id, removed: true };
     },
   };

package/src/ai/register-ai-tools.ts

@@ -6,6 +6,7 @@ import { createIncidentAddUpdateTool } from "./incident-add-update";
 import { createIncidentResolveTool } from "./incident-resolve";
 import { createIncidentAddLinkTool } from "./incident-add-link";
 import { createIncidentRemoveLinkTool } from "./incident-remove-link";
+import { createIncidentDeleteUpdateTool } from "./incident-delete-update";
 
 /**
  * The incident plugin's AI tools, registered into the AI registry via
@@ -29,5 +30,6 @@ export function buildIncidentAiTools(): RegisteredAiTool[] {
     createIncidentResolveTool(),
     createIncidentAddLinkTool(),
     createIncidentRemoveLinkTool(),
+    createIncidentDeleteUpdateTool(),
   ];
 }

package/src/automations.test.ts

@@ -324,6 +324,76 @@ describe("incident automation actions", () => {
       expect(service.resolveIncident).toHaveBeenCalledWith("INC-1", "Fixed");
     });
 
+    // SLO-1 regression: an automation-driven resolve mutates the incident WITHOUT
+    // going through the RPC router, so it must emit `incident.lifecycle.changed`
+    // itself — otherwise an override-bearing incident resolved by an automation
+    // never triggers SLO downtime reconciliation and its incident-sourced event
+    // leaks open.
+    it("emits incident.lifecycle.changed on an automation resolve (SLO downtime reconcile)", async () => {
+      const resolved = {
+        id: "INC-1",
+        status: "resolved",
+        severity: "critical",
+        systemIds: ["sys-1", "sys-2"],
+      };
+      const service = makeServiceStub({
+        resolveIncident: mock(
+          async () => resolved,
+        ) as unknown as IncidentService["resolveIncident"],
+      });
+      const emit = mock(async () => {});
+      const eventBus = { emit } as unknown as Parameters<
+        typeof createIncidentActions
+      >[0]["eventBus"];
+      const resolveAction = createIncidentActions({ service, eventBus })[1];
+
+      await resolveAction.execute({
+        ...actionContext,
+        config: { incidentId: "INC-1", message: "Fixed" } as never,
+      });
+
+      expect(emit).toHaveBeenCalledTimes(1);
+      const emitArgs = emit.mock.calls[0] as unknown[] | undefined;
+      const hook = emitArgs?.[0] as { id?: string } | undefined;
+      const payload = emitArgs?.[1] as
+        | { systemIds?: string[]; action?: string }
+        | undefined;
+      expect(hook?.id).toBe("incident.lifecycle.changed");
+      expect(payload?.action).toBe("resolved");
+      expect(payload?.systemIds).toEqual(["sys-1", "sys-2"]);
+    });
+
+    it("emits incident.lifecycle.changed on an automation update_status → resolved", async () => {
+      const update = {
+        id: "upd-3",
+        incidentId: "INC-1",
+        message: "Status changed to resolved",
+        createdAt: new Date(),
+      };
+      const service = makeServiceStub({
+        addUpdate: mock(
+          async () => update,
+        ) as unknown as IncidentService["addUpdate"],
+      });
+      const emit = mock(async () => {});
+      const eventBus = { emit } as unknown as Parameters<
+        typeof createIncidentActions
+      >[0]["eventBus"];
+      const updateStatusAction = createIncidentActions({ service, eventBus })[3];
+
+      await updateStatusAction.execute({
+        ...actionContext,
+        config: { incidentId: "INC-1", status: "resolved" } as never,
+      });
+
+      expect(emit).toHaveBeenCalledTimes(1);
+      const payload = (emit.mock.calls[0] as unknown[] | undefined)?.[1] as
+        | { systemIds?: string[]; action?: string }
+        | undefined;
+      expect(payload?.action).toBe("resolved");
+      expect(payload?.systemIds).toEqual(["sys-1"]);
+    });
+
     // 6(b) regression: an action-driven resolve must route through the reactive
     // entity (like the RPC router) so it appends an `entity_transitions` row,
     // emits `ENTITY_CHANGED` (waking `wait_until`), and fires the

package/src/automations.ts

@@ -11,7 +11,7 @@
  * and to match `wait_for_trigger` waits against the same incident.
  */
 import { z } from "zod";
-import { Versioned } from "@checkstack/backend-api";
+import { Versioned, type EventBus } from "@checkstack/backend-api";
 import type {
   ActionDefinition,
   ArtifactTypeDefinition,
@@ -22,9 +22,11 @@ import { makeEntityDrivenTriggerSetup } from "@checkstack/automation-backend";
 import {
   IncidentSeverityEnum,
   IncidentStatusEnum,
+  type IncidentLifecycleAction,
 } from "@checkstack/incident-common";
 
 import type { IncidentService } from "./service";
+import { emitIncidentLifecycleChanged } from "./hooks";
 import {
   toIncidentEntityState,
   writeIncidentEntity,
@@ -259,12 +261,20 @@ export interface IncidentActionDeps {
    * non-reactively.
    */
   getIncidentEntity?: () => EntityHandle<IncidentEntityState> | undefined;
+  /**
+   * Distributed event bus used to emit `incident.lifecycle.changed` after an
+   * automation-driven lifecycle mutation. Automations mutate incidents WITHOUT
+   * going through the RPC router, so without this an automation resolving an
+   * override-bearing incident would never notify SLO downtime reconciliation and
+   * the incident-sourced downtime event would leak open. Undefined in tests.
+   */
+  eventBus?: EventBus;
 }
 
 export function createIncidentActions(
   deps: IncidentActionDeps,
 ): ActionDefinition<unknown, unknown>[] {
-  const { service, getIncidentEntity } = deps;
+  const { service, getIncidentEntity, eventBus } = deps;
 
   const createAction: ActionDefinition<
     z.infer<typeof incidentCreateConfigSchema>,
@@ -339,6 +349,17 @@ export function createIncidentActions(
           );
         } else {
           logger.info(`Automation created incident ${incident.id}`);
+          // Only a real create is a lifecycle mutation; a REUSE changed nothing,
+          // so SLO already reconciled it at its original creation.
+          await emitIncidentLifecycleChanged({
+            eventBus,
+            logger,
+            payload: {
+              incidentId: incident.id,
+              systemIds: incident.systemIds,
+              action: "created",
+            },
+          });
         }
         return {
           success: true,
@@ -364,6 +385,15 @@ export function createIncidentActions(
         },
       });
       logger.info(`Automation created incident ${incident.id}`);
+      await emitIncidentLifecycleChanged({
+        eventBus,
+        logger,
+        payload: {
+          incidentId: incident.id,
+          systemIds: incident.systemIds,
+          action: "created",
+        },
+      });
       return {
         success: true,
         externalId: incident.id,
@@ -442,6 +472,17 @@ export function createIncidentActions(
         };
       }
       logger.info(`Automation resolved incident ${incident.id}`);
+      // A resolve clears any active health override, so SLO must close the
+      // incident-forced downtime — the defect this notifier fixes.
+      await emitIncidentLifecycleChanged({
+        eventBus,
+        logger,
+        payload: {
+          incidentId: incident.id,
+          systemIds: incident.systemIds,
+          action: "resolved",
+        },
+      });
       return {
         success: true,
         externalId: incident.id,
@@ -485,7 +526,8 @@ export function createIncidentActions(
       // is a no-op diff (no event). `opts.runId` masks run-resolved secrets.
       const captured: {
         update: Awaited<ReturnType<typeof service.addUpdate>> | null;
-      } = { update: null };
+        systemIds: string[];
+      } = { update: null, systemIds: [] };
       await writeIncidentEntity({
         handle: getIncidentEntity?.(),
         incidentId,
@@ -500,6 +542,7 @@ export function createIncidentActions(
           if (!incident) {
             throw new Error(`Incident ${incidentId} not found`);
           }
+          captured.systemIds = incident.systemIds;
           return toIncidentEntityState(incident);
         },
       });
@@ -513,6 +556,21 @@ export function createIncidentActions(
       logger.info(
         `Automation added update ${update.id} to incident ${incidentId}`,
       );
+      // Only a status-changing update is a lifecycle mutation SLO cares about; a
+      // comment-only update changes no health-relevant state. A change to
+      // resolved clears any override, so SLO must reconcile.
+      if (config.statusChange) {
+        await emitIncidentLifecycleChanged({
+          eventBus,
+          logger,
+          payload: {
+            incidentId,
+            systemIds: captured.systemIds,
+            action:
+              config.statusChange === "resolved" ? "resolved" : "updated",
+          },
+        });
+      }
       return {
         success: true,
         externalId: update.id,
@@ -553,7 +611,8 @@ export function createIncidentActions(
       // re-reads post-write state. `opts.runId` masks run-resolved secrets.
       const captured: {
         update: Awaited<ReturnType<typeof service.addUpdate>> | null;
-      } = { update: null };
+        systemIds: string[];
+      } = { update: null, systemIds: [] };
       await writeIncidentEntity({
         handle: getIncidentEntity?.(),
         incidentId,
@@ -568,6 +627,7 @@ export function createIncidentActions(
           if (!incident) {
             throw new Error(`Incident ${incidentId} not found`);
           }
+          captured.systemIds = incident.systemIds;
           return toIncidentEntityState(incident);
         },
       });
@@ -581,6 +641,19 @@ export function createIncidentActions(
       logger.info(
         `Automation set incident ${incidentId} status → ${config.status}`,
       );
+      // A status flip is a lifecycle mutation; a flip to resolved clears any
+      // override, so SLO must reconcile the affected systems' downtime.
+      const action: IncidentLifecycleAction =
+        config.status === "resolved" ? "resolved" : "updated";
+      await emitIncidentLifecycleChanged({
+        eventBus,
+        logger,
+        payload: {
+          incidentId,
+          systemIds: captured.systemIds,
+          action,
+        },
+      });
       return {
         success: true,
         externalId: update.id,

package/src/hooks.ts

@@ -1,11 +1,61 @@
+import { createHook, type EventBus, type Logger } from "@checkstack/backend-api";
+import {
+  INCIDENT_LIFECYCLE_CHANGED_HOOK_ID,
+  type IncidentLifecycleChangedPayload,
+} from "@checkstack/incident-common";
+
 /**
  * Incident cross-plugin hooks.
  *
  * The `incident.created` / `.updated` / `.resolved` hooks were removed in
  * Phase 4 (§10.1): incidents are now the reactive `incident` entity, whose
  * change deriver fires the matching `incident.created` / `.updated` /
- * `.resolved` trigger events through Stage-1 routing. No cross-plugin hook
- * remains, so this object is intentionally empty (kept for the stable
- * `export { incidentHooks }` surface).
+ * `.resolved` trigger events through Stage-1 routing.
+ *
+ * `lifecycleChanged` is a distinct, lower-level cross-plugin hook: it fires on
+ * EVERY incident lifecycle mutation (create, update — including a health
+ * override added / changed / cleared —, resolve, delete, and the auto-incident
+ * paths), carrying `{ incidentId, systemIds, action }`. Unlike the reactive
+ * `incident` entity change (state `{ status, severity, systemIds }`, so an
+ * override-only edit emits nothing), this catches override changes, which
+ * `@checkstack/slo-backend` needs to open/close incident-forced SLO downtime.
+ * The id + payload contract live in `@checkstack/incident-common` so consumers
+ * subscribe without depending on this backend.
+ */
+export const incidentLifecycleChangedHook =
+  createHook<IncidentLifecycleChangedPayload>(
+    INCIDENT_LIFECYCLE_CHANGED_HOOK_ID,
+  );
+
+export const incidentHooks = {
+  lifecycleChanged: incidentLifecycleChangedHook,
+} as const;
+
+/**
+ * Emit `incident.lifecycle.changed` on the distributed event bus. THE single
+ * place the hook is fired, so every incident lifecycle path - the RPC router,
+ * the bulk paths, AND the automation actions - shares identical guard/failure
+ * semantics and can never drift. Best-effort by contract: the incident write is
+ * already committed by the time this runs, so a delivery failure must never turn
+ * a successful mutation into a client/run error - consumers reconcile on the
+ * next lifecycle event. A no-op when no event bus is wired (tests).
  */
-export const incidentHooks = {} as const;
+export async function emitIncidentLifecycleChanged({
+  eventBus,
+  logger,
+  payload,
+}: {
+  eventBus: EventBus | undefined;
+  logger: Logger;
+  payload: IncidentLifecycleChangedPayload;
+}): Promise<void> {
+  if (!eventBus) return;
+  try {
+    await eventBus.emit(incidentLifecycleChangedHook, payload);
+  } catch (error) {
+    logger.warn(
+      `Failed to emit incident.lifecycle.changed hook for incident ${payload.incidentId}; consumers will reconcile on the next lifecycle event.`,
+      { error },
+    );
+  }
+}