@checkstack/dependency-backend 1.1.6 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,98 @@
 # @checkstack/dependency-backend
 
+## 1.2.0
+
+### Minor Changes
+
+- 41c77f4: feat(automation): type enum-able trigger/artifact fields as enums for editor value autocompletion
+
+  The automation editor's staged completion offers concrete values after a
+  comparator (`{{ trigger.payload.severity == "high" }}`) only when the
+  field's JSON Schema carries an `enum`. Several trigger payload + artifact
+  schemas declared closed-set fields as loose `z.string()`, so no values
+  were suggested. Tightened them to the canonical enums that already
+  existed in each plugin's `-common` package (and matched the hook payload
+  types in lockstep so the trigger's `payloadSchema` and `hook` keep the
+  same `TPayload`):
+
+  - **incident** — trigger payloads: `severity` → `IncidentSeverityEnum`,
+    `status` / `statusChange` → `IncidentStatusEnum`.
+  - **healthcheck** — trigger payloads: `previousStatus` / `newStatus` /
+    `status` → `HealthCheckStatusSchema` (across systemDegraded,
+    systemHealthy, systemHealthChanged, checkFailed; plus checkCompleted's
+    hook type).
+  - **dependency** — trigger + artifact: `impactType` → `ImpactTypeSchema`;
+    impactPropagated `previousState` / `newState` → `DerivedStateSchema`.
+    Also deduped the inline `impactTypeSchema` action-config enum to reuse
+    the canonical `ImpactTypeSchema`.
+  - **maintenance** — trigger + artifact: `status` →
+    `MaintenanceStatusEnum`; deduped the inline `maintenanceStatusEnum`
+    (used by `add_update.statusChange`) to the canonical one.
+  - **slo** — `achievement.unlocked` trigger + hook: `achievement` →
+    `AchievementTypeSchema`.
+
+  Runtime behaviour is unchanged — these fields always carried valid enum
+  values (the underlying records are enum-constrained); only the schema
+  types were loose. The hook payload generics are now precise too, which
+  caught one stale test fixture asserting an invalid `impactType: "soft"`.
+
+  Fields that look enum-ish but are genuinely free-form were intentionally
+  left as `z.string()`: satellite `region` (user-entered), Jira issue
+  `status` (per-instance workflow name), notification `strategyQualifiedId`
+  / `errorMessage`, healthcheck collector `result`, and script
+  `stdout` / `stderr`.
+
+- 41c77f4: feat(dependency): Phase 9 — triggers + create/remove actions for the Automation Platform
+
+  - Triggers `dependency.created`, `dependency.updated`, `dependency.deleted`,
+    each carrying `contextKey: (p) => p.dependencyId` so `wait_for_trigger`
+    resumes on the same edge.
+  - New hook `dependencyHooks.impactPropagated` + matching trigger
+    `dependency.impact_propagated` — fires once per upstream event from
+    `evaluateAndNotifyDownstream` with the list of downstream systems
+    whose derived state actually moved. Carries previous/new state for
+    each affected system so subscribers don't have to re-query the
+    graph. Fires regardless of notification suppression, so an
+    automation can react even when the user-facing notification is
+    skipped. `contextKey: (p) => p.sourceSystemId`.
+  - Actions `dependency.create` (with cycle + duplicate-edge detection
+    surfaced via the action's `error`) and `dependency.remove`. Both emit
+    the matching `dependencyHooks.*` so downstream automations and caches
+    react identically to RPC-driven changes.
+  - Artifact type `dependency.edge` for source/target/impact pass-through
+    between steps.
+
+### Patch Changes
+
+- Updated dependencies [e2d6f25]
+- Updated dependencies [41c77f4]
+- Updated dependencies [41c77f4]
+- Updated dependencies [e1a2077]
+- Updated dependencies [41c77f4]
+- Updated dependencies [41c77f4]
+- Updated dependencies [41c77f4]
+- Updated dependencies [41c77f4]
+- Updated dependencies [41c77f4]
+- Updated dependencies [41c77f4]
+- Updated dependencies [41c77f4]
+- Updated dependencies [6d52276]
+- Updated dependencies [6d52276]
+- Updated dependencies [35bc682]
+  - @checkstack/automation-backend@0.2.0
+  - @checkstack/healthcheck-backend@1.3.0
+  - @checkstack/catalog-backend@1.2.0
+  - @checkstack/common@0.12.0
+  - @checkstack/backend-api@0.18.0
+  - @checkstack/healthcheck-common@1.3.0
+  - @checkstack/catalog-common@2.2.3
+  - @checkstack/dependency-common@1.1.3
+  - @checkstack/incident-common@1.3.1
+  - @checkstack/maintenance-common@1.2.3
+  - @checkstack/gitops-backend@0.3.7
+  - @checkstack/gitops-common@0.4.2
+  - @checkstack/notification-common@1.2.1
+  - @checkstack/signal-common@0.2.5
+
 ## 1.1.6
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/dependency-backend",
-  "version": "1.1.6",
+  "version": "1.2.0",
   "license": "Elastic-2.0",
   "type": "module",
   "main": "src/index.ts",
@@ -11,20 +11,22 @@
     "typecheck": "tsgo -b",
     "generate": "drizzle-kit generate",
     "lint": "bun run lint:code",
-    "lint:code": "eslint . --max-warnings 0"
+    "lint:code": "eslint . --max-warnings 0",
+    "test": "bun test"
   },
   "dependencies": {
-    "@checkstack/backend-api": "0.17.0",
+    "@checkstack/backend-api": "0.17.1",
+    "@checkstack/automation-backend": "0.1.0",
     "@checkstack/dependency-common": "1.1.2",
     "@checkstack/catalog-common": "2.2.2",
-    "@checkstack/catalog-backend": "1.1.5",
-    "@checkstack/healthcheck-common": "1.1.2",
-    "@checkstack/healthcheck-backend": "1.1.4",
+    "@checkstack/catalog-backend": "1.1.6",
+    "@checkstack/healthcheck-common": "1.2.0",
+    "@checkstack/healthcheck-backend": "1.2.0",
     "@checkstack/maintenance-common": "1.2.2",
-    "@checkstack/incident-common": "1.2.2",
+    "@checkstack/incident-common": "1.3.0",
     "@checkstack/notification-common": "1.2.0",
     "@checkstack/signal-common": "0.2.4",
-    "@checkstack/gitops-backend": "0.3.5",
+    "@checkstack/gitops-backend": "0.3.6",
     "@checkstack/gitops-common": "0.4.1",
     "@checkstack/common": "0.11.0",
     "drizzle-orm": "^0.45.0",
@@ -34,7 +36,7 @@
   "devDependencies": {
     "@checkstack/drizzle-helper": "0.0.5",
     "@checkstack/scripts": "0.3.3",
-    "@checkstack/test-utils-backend": "0.1.29",
+    "@checkstack/test-utils-backend": "0.1.30",
     "@checkstack/tsconfig": "0.0.7",
     "@types/bun": "^1.0.0",
     "drizzle-kit": "^0.31.10",

package/src/automations.test.ts

@@ -0,0 +1,308 @@
+/**
+ * Behaviour tests for the dependency automation triggers + actions.
+ */
+import { describe, expect, it, mock } from "bun:test";
+import type { Logger } from "@checkstack/backend-api";
+import { createMockLogger } from "@checkstack/test-utils-backend";
+
+import {
+  createDependencyActions,
+  dependencyArtifactType,
+  dependencyCreatedTrigger,
+  dependencyDeletedTrigger,
+  dependencyImpactPropagatedTrigger,
+  dependencyTriggers,
+  dependencyUpdatedTrigger,
+} from "./automations";
+import { dependencyHooks } from "./hooks";
+import type { DependencyService } from "./services/dependency-service";
+
+const logger = createMockLogger() as Logger;
+
+const ctxBase = {
+  runId: "run-1",
+  automationId: "auto-1",
+  contextKey: null,
+  logger,
+  getService: async <T,>(): Promise<T> => {
+    throw new Error("not used");
+  },
+};
+
+describe("dependency triggers", () => {
+  it("exposes four triggers in a stable order", () => {
+    expect(dependencyTriggers).toHaveLength(4);
+    expect(dependencyTriggers[0]).toBe(
+      dependencyCreatedTrigger as (typeof dependencyTriggers)[number],
+    );
+    expect(dependencyTriggers[1]).toBe(
+      dependencyUpdatedTrigger as (typeof dependencyTriggers)[number],
+    );
+    expect(dependencyTriggers[2]).toBe(
+      dependencyDeletedTrigger as (typeof dependencyTriggers)[number],
+    );
+    expect(dependencyTriggers[3]).toBe(
+      dependencyImpactPropagatedTrigger as (typeof dependencyTriggers)[number],
+    );
+  });
+
+  it("extracts dependencyId as the contextKey on the edge-lifecycle triggers", () => {
+    const payload = {
+      dependencyId: "dep-1",
+      sourceSystemId: "sys-a",
+      targetSystemId: "sys-b",
+      impactType: "critical",
+    } as const;
+    expect(dependencyCreatedTrigger.contextKey?.(payload)).toBe("dep-1");
+    expect(dependencyUpdatedTrigger.contextKey?.(payload)).toBe("dep-1");
+    expect(dependencyDeletedTrigger.contextKey?.(payload)).toBe("dep-1");
+  });
+
+  it("extracts sourceSystemId as the contextKey on impactPropagated", () => {
+    const payload = {
+      sourceSystemId: "sys-upstream",
+      affectedSystems: [
+        { systemId: "sys-a", previousState: null, newState: "degraded" as const },
+      ],
+      timestamp: "2026-05-29T12:00:00Z",
+    };
+    expect(dependencyImpactPropagatedTrigger.contextKey?.(payload)).toBe(
+      "sys-upstream",
+    );
+  });
+
+  it("requires affectedSystems on the impactPropagated payload", () => {
+    const ok = dependencyImpactPropagatedTrigger.payloadSchema.safeParse({
+      sourceSystemId: "sys-1",
+      affectedSystems: [],
+      timestamp: "2026-05-29T12:00:00Z",
+    });
+    expect(ok.success).toBe(true);
+
+    const bad = dependencyImpactPropagatedTrigger.payloadSchema.safeParse({
+      sourceSystemId: "sys-1",
+      timestamp: "2026-05-29T12:00:00Z",
+    });
+    expect(bad.success).toBe(false);
+  });
+
+  it("rejects edge-lifecycle payloads missing required fields", () => {
+    const bad = dependencyCreatedTrigger.payloadSchema.safeParse({
+      dependencyId: "dep-1",
+      sourceSystemId: "sys-a",
+    });
+    expect(bad.success).toBe(false);
+  });
+});
+
+describe("dependencyArtifactType", () => {
+  it("validates the canonical edge shape", () => {
+    const ok = dependencyArtifactType.schema.safeParse({
+      dependencyId: "dep-1",
+      sourceSystemId: "sys-a",
+      targetSystemId: "sys-b",
+      impactType: "critical",
+    });
+    expect(ok.success).toBe(true);
+
+    // The artifact schema now uses the canonical ImpactType enum, so a
+    // value outside it is rejected.
+    const bad = dependencyArtifactType.schema.safeParse({
+      dependencyId: "dep-1",
+      sourceSystemId: "sys-a",
+      targetSystemId: "sys-b",
+      impactType: "soft",
+    });
+    expect(bad.success).toBe(false);
+  });
+});
+
+interface FakeDependencyRow {
+  id: string;
+  sourceSystemId: string;
+  targetSystemId: string;
+  impactType: string;
+  transitive: boolean;
+  label: string | null;
+}
+
+function makeService(args: {
+  createBehaviour?:
+    | { ok: true; row: FakeDependencyRow }
+    | { ok: false; error: string };
+  existingForRemove?: FakeDependencyRow;
+  deleteResult?: boolean;
+}): DependencyService & {
+  createMock: ReturnType<typeof mock>;
+  deleteMock: ReturnType<typeof mock>;
+  getByIdMock: ReturnType<typeof mock>;
+} {
+  const createMock = mock(async (input: unknown) => {
+    if (args.createBehaviour && !args.createBehaviour.ok) {
+      throw new Error(args.createBehaviour.error);
+    }
+    if (args.createBehaviour?.ok) return args.createBehaviour.row;
+    const i = input as { sourceSystemId: string; targetSystemId: string; impactType: string };
+    return {
+      id: "generated",
+      sourceSystemId: i.sourceSystemId,
+      targetSystemId: i.targetSystemId,
+      impactType: i.impactType,
+      transitive: false,
+      label: null,
+    };
+  });
+  const deleteMock = mock(async (_id: string) => args.deleteResult ?? true);
+  const getByIdMock = mock(async (_id: string) => args.existingForRemove);
+  return {
+    createDependency: createMock,
+    deleteDependency: deleteMock,
+    getDependencyById: getByIdMock,
+    createMock,
+    deleteMock,
+    getByIdMock,
+  } as unknown as DependencyService & {
+    createMock: ReturnType<typeof mock>;
+    deleteMock: ReturnType<typeof mock>;
+    getByIdMock: ReturnType<typeof mock>;
+  };
+}
+
+describe("dependency.create", () => {
+  it("creates an edge, fires dependencyCreated, and emits an artifact", async () => {
+    const service = makeService({
+      createBehaviour: {
+        ok: true,
+        row: {
+          id: "dep-1",
+          sourceSystemId: "sys-a",
+          targetSystemId: "sys-b",
+          impactType: "critical",
+          transitive: false,
+          label: null,
+        },
+      },
+    });
+    const emitHook = mock(async (_hook: unknown, _payload: unknown) => {});
+    const [create] = createDependencyActions({ service, emitHook: emitHook as never });
+
+    const result = await create!.execute({
+      ...ctxBase,
+      consumedArtifacts: {},
+      config: {
+        sourceSystemId: "sys-a",
+        targetSystemId: "sys-b",
+        impactType: "critical",
+        transitive: false,
+      } as never,
+    });
+
+    expect(result.success).toBe(true);
+    if (!result.success) return;
+    expect(result.externalId).toBe("dep-1");
+    expect((result.artifact as { dependencyId: string }).dependencyId).toBe("dep-1");
+    expect(emitHook).toHaveBeenCalledTimes(1);
+    const emitCall = emitHook.mock.calls[0]!;
+    expect(emitCall[0]).toBe(dependencyHooks.dependencyCreated);
+  });
+
+  it("returns a failure when service.createDependency throws (e.g. cycle detected)", async () => {
+    const service = makeService({
+      createBehaviour: {
+        ok: false,
+        error: "Cannot create dependency: would form a circular chain: a → b → a",
+      },
+    });
+    const emitHook = mock(async (_hook: unknown, _payload: unknown) => {});
+    const [create] = createDependencyActions({ service, emitHook: emitHook as never });
+
+    const result = await create!.execute({
+      ...ctxBase,
+      consumedArtifacts: {},
+      config: {
+        sourceSystemId: "a",
+        targetSystemId: "b",
+        impactType: "soft",
+      } as never,
+    });
+
+    expect(result.success).toBe(false);
+    if (result.success) return;
+    expect(result.error).toMatch(/circular chain/);
+    expect(emitHook).not.toHaveBeenCalled();
+  });
+});
+
+describe("dependency.remove", () => {
+  it("removes an edge, fires dependencyDeleted, and emits an artifact reflecting the removed edge", async () => {
+    const service = makeService({
+      existingForRemove: {
+        id: "dep-1",
+        sourceSystemId: "sys-a",
+        targetSystemId: "sys-b",
+        impactType: "critical",
+        transitive: false,
+        label: null,
+      },
+      deleteResult: true,
+    });
+    const emitHook = mock(async (_hook: unknown, _payload: unknown) => {});
+    const [, remove] = createDependencyActions({ service, emitHook: emitHook as never });
+
+    const result = await remove!.execute({
+      ...ctxBase,
+      consumedArtifacts: {},
+      config: { dependencyId: "dep-1" } as never,
+    });
+
+    expect(result.success).toBe(true);
+    if (!result.success) return;
+    expect(result.externalId).toBe("dep-1");
+    expect(emitHook).toHaveBeenCalledTimes(1);
+    expect(emitHook.mock.calls[0]![0]).toBe(dependencyHooks.dependencyDeleted);
+  });
+
+  it("returns failure if the dependency does not exist", async () => {
+    const service = makeService({ existingForRemove: undefined });
+    const emitHook = mock(async (_hook: unknown, _payload: unknown) => {});
+    const [, remove] = createDependencyActions({ service, emitHook: emitHook as never });
+
+    const result = await remove!.execute({
+      ...ctxBase,
+      consumedArtifacts: {},
+      config: { dependencyId: "missing" } as never,
+    });
+
+    expect(result.success).toBe(false);
+    if (result.success) return;
+    expect(result.error).toMatch(/not found/i);
+    expect(emitHook).not.toHaveBeenCalled();
+  });
+
+  it("returns failure if delete returns false (race-deleted)", async () => {
+    const service = makeService({
+      existingForRemove: {
+        id: "dep-1",
+        sourceSystemId: "sys-a",
+        targetSystemId: "sys-b",
+        impactType: "critical",
+        transitive: false,
+        label: null,
+      },
+      deleteResult: false,
+    });
+    const emitHook = mock(async (_hook: unknown, _payload: unknown) => {});
+    const [, remove] = createDependencyActions({ service, emitHook: emitHook as never });
+
+    const result = await remove!.execute({
+      ...ctxBase,
+      consumedArtifacts: {},
+      config: { dependencyId: "dep-1" } as never,
+    });
+
+    expect(result.success).toBe(false);
+    if (result.success) return;
+    expect(result.error).toMatch(/disappeared mid-delete/);
+    expect(emitHook).not.toHaveBeenCalled();
+  });
+});

package/src/automations.ts

@@ -0,0 +1,287 @@
+/**
+ * Dependency triggers + actions registered with the Automation Platform.
+ *
+ * Triggers expose the existing `dependencyHooks` as automation entry
+ * points (`dependency.created`, `dependency.updated`, `dependency.deleted`).
+ * Actions wrap `DependencyService.createDependency` / `deleteDependency`
+ * so operators can build / remove edges from automation flows.
+ *
+ * The plan also mentions a `dependency.impact_propagated` trigger.
+ * That event isn't emitted today — propagation runs synchronously
+ * inside `evaluateAndNotifyDownstream`. Adding a hook there is a
+ * separate change because it requires deciding what payload to pass
+ * (which downstream systems were re-evaluated, what their new status
+ * is, whether to deduplicate). Tracked as a follow-up in the plan;
+ * not included in this chunk.
+ *
+ * Mutation actions emit their hook themselves (via the `emitHook`
+ * factory dep) so downstream automations / caches react the same way
+ * they do when the mutation comes in via RPC.
+ */
+import { z } from "zod";
+import { Versioned, type Hook } from "@checkstack/backend-api";
+import type {
+  ActionDefinition,
+  TriggerDefinition,
+} from "@checkstack/automation-backend";
+import { extractErrorMessage } from "@checkstack/common";
+import {
+  DerivedStateSchema,
+  ImpactTypeSchema,
+} from "@checkstack/dependency-common";
+
+import { dependencyHooks } from "./hooks";
+import type { DependencyService } from "./services/dependency-service";
+
+// ─── Payload schemas — match the hook payloads exactly ─────────────────
+
+const dependencyCreatedPayloadSchema = z.object({
+  dependencyId: z.string(),
+  sourceSystemId: z.string(),
+  targetSystemId: z.string(),
+  impactType: ImpactTypeSchema,
+});
+
+const dependencyUpdatedPayloadSchema = z.object({
+  dependencyId: z.string(),
+  sourceSystemId: z.string(),
+  targetSystemId: z.string(),
+  impactType: ImpactTypeSchema,
+});
+
+const dependencyDeletedPayloadSchema = z.object({
+  dependencyId: z.string(),
+  sourceSystemId: z.string(),
+  targetSystemId: z.string(),
+});
+
+const dependencyImpactPropagatedPayloadSchema = z.object({
+  sourceSystemId: z.string(),
+  affectedSystems: z.array(
+    z.object({
+      systemId: z.string(),
+      previousState: DerivedStateSchema.nullable(),
+      newState: DerivedStateSchema.nullable(),
+    }),
+  ),
+  timestamp: z.string(),
+});
+
+// ─── Triggers ──────────────────────────────────────────────────────────
+
+export const dependencyCreatedTrigger: TriggerDefinition<
+  z.infer<typeof dependencyCreatedPayloadSchema>
+> = {
+  id: "created",
+  displayName: "Dependency Created",
+  description: "Fires when a new dependency edge is added between two systems",
+  category: "Dependencies",
+  icon: "Network",
+  payloadSchema: dependencyCreatedPayloadSchema,
+  hook: dependencyHooks.dependencyCreated,
+  contextKey: (p) => p.dependencyId,
+};
+
+export const dependencyUpdatedTrigger: TriggerDefinition<
+  z.infer<typeof dependencyUpdatedPayloadSchema>
+> = {
+  id: "updated",
+  displayName: "Dependency Updated",
+  description: "Fires when an existing dependency's impact-type or label changes",
+  category: "Dependencies",
+  icon: "Network",
+  payloadSchema: dependencyUpdatedPayloadSchema,
+  hook: dependencyHooks.dependencyUpdated,
+  contextKey: (p) => p.dependencyId,
+};
+
+export const dependencyDeletedTrigger: TriggerDefinition<
+  z.infer<typeof dependencyDeletedPayloadSchema>
+> = {
+  id: "deleted",
+  displayName: "Dependency Deleted",
+  description: "Fires when a dependency edge is removed",
+  category: "Dependencies",
+  icon: "Network",
+  payloadSchema: dependencyDeletedPayloadSchema,
+  hook: dependencyHooks.dependencyDeleted,
+  contextKey: (p) => p.dependencyId,
+};
+
+export const dependencyImpactPropagatedTrigger: TriggerDefinition<
+  z.infer<typeof dependencyImpactPropagatedPayloadSchema>
+> = {
+  id: "impact_propagated",
+  displayName: "Dependency Impact Propagated",
+  description:
+    "Fires once per upstream health change with the list of downstream systems whose derived state actually moved",
+  category: "Dependencies",
+  icon: "Network",
+  payloadSchema: dependencyImpactPropagatedPayloadSchema,
+  hook: dependencyHooks.impactPropagated,
+  contextKey: (p) => p.sourceSystemId,
+};
+
+export const dependencyTriggers: TriggerDefinition<unknown>[] = [
+  dependencyCreatedTrigger as TriggerDefinition<unknown>,
+  dependencyUpdatedTrigger as TriggerDefinition<unknown>,
+  dependencyDeletedTrigger as TriggerDefinition<unknown>,
+  dependencyImpactPropagatedTrigger as TriggerDefinition<unknown>,
+];
+
+// ─── Action configs ────────────────────────────────────────────────────
+
+const impactTypeSchema = ImpactTypeSchema.describe(
+  "How the target is affected when the source is affected — `critical` propagates the upstream's status (degraded → degraded, down → down), `degraded` always pulls the downstream to degraded, `informational` warns only.",
+);
+
+const dependencyCreateConfigSchema = z.object({
+  sourceSystemId: z.string().min(1).describe("Source (upstream) system id"),
+  targetSystemId: z.string().min(1).describe("Target (downstream) system id"),
+  impactType: impactTypeSchema,
+  transitive: z.boolean().optional().default(false),
+  label: z.string().optional(),
+});
+
+export type DependencyCreateConfig = z.infer<
+  typeof dependencyCreateConfigSchema
+>;
+
+const dependencyRemoveConfigSchema = z.object({
+  dependencyId: z.string().min(1).describe("Id of the dependency to remove"),
+});
+
+export type DependencyRemoveConfig = z.infer<
+  typeof dependencyRemoveConfigSchema
+>;
+
+// ─── Artifact type ─────────────────────────────────────────────────────
+
+const dependencyArtifactSchema = z.object({
+  dependencyId: z.string(),
+  sourceSystemId: z.string(),
+  targetSystemId: z.string(),
+  impactType: ImpactTypeSchema,
+});
+
+export type DependencyArtifact = z.infer<typeof dependencyArtifactSchema>;
+
+export const dependencyArtifactType = {
+  id: "edge",
+  displayName: "Dependency Edge",
+  description: "Source → target edge produced or removed by an automation",
+  schema: dependencyArtifactSchema,
+} as const;
+
+// ─── Actions ───────────────────────────────────────────────────────────
+
+export interface DependencyActionDeps {
+  service: DependencyService;
+  emitHook: <T>(hook: Hook<T>, payload: T) => Promise<void>;
+}
+
+export function createDependencyActions(
+  deps: DependencyActionDeps,
+): ActionDefinition<unknown, unknown>[] {
+  const createAction: ActionDefinition<
+    DependencyCreateConfig,
+    DependencyArtifact
+  > = {
+    id: "create",
+    displayName: "Create Dependency",
+    description: "Add a dependency edge between two systems",
+    category: "Dependencies",
+    icon: "Network",
+    config: new Versioned({
+      version: 1,
+      schema: dependencyCreateConfigSchema,
+    }),
+    produces: "dependency.edge",
+    execute: async ({ config, logger }) => {
+      try {
+        const created = await deps.service.createDependency({
+          sourceSystemId: config.sourceSystemId,
+          targetSystemId: config.targetSystemId,
+          impactType: config.impactType,
+          transitive: config.transitive,
+          label: config.label,
+          healthCheckRules: [],
+        });
+        await deps.emitHook(dependencyHooks.dependencyCreated, {
+          dependencyId: created.id,
+          sourceSystemId: created.sourceSystemId,
+          targetSystemId: created.targetSystemId,
+          impactType: created.impactType,
+        });
+        logger.info(`Automation created dependency ${created.id}`);
+        return {
+          success: true,
+          externalId: created.id,
+          artifact: {
+            dependencyId: created.id,
+            sourceSystemId: created.sourceSystemId,
+            targetSystemId: created.targetSystemId,
+            impactType: created.impactType,
+          },
+        };
+      } catch (error) {
+        // Both duplicate-edge and cycle detection throw — surface the
+        // user-facing message so the run-detail UI shows the reason.
+        return { success: false, error: extractErrorMessage(error) };
+      }
+    },
+  };
+
+  const removeAction: ActionDefinition<
+    DependencyRemoveConfig,
+    DependencyArtifact
+  > = {
+    id: "remove",
+    displayName: "Remove Dependency",
+    description: "Delete a dependency edge by id",
+    category: "Dependencies",
+    icon: "Network",
+    config: new Versioned({
+      version: 1,
+      schema: dependencyRemoveConfigSchema,
+    }),
+    produces: "dependency.edge",
+    execute: async ({ config, logger }) => {
+      const existing = await deps.service.getDependencyById(config.dependencyId);
+      if (!existing) {
+        return {
+          success: false,
+          error: `Dependency not found: ${config.dependencyId}`,
+        };
+      }
+      const removed = await deps.service.deleteDependency(config.dependencyId);
+      if (!removed) {
+        return {
+          success: false,
+          error: `Dependency ${config.dependencyId} disappeared mid-delete`,
+        };
+      }
+      await deps.emitHook(dependencyHooks.dependencyDeleted, {
+        dependencyId: existing.id,
+        sourceSystemId: existing.sourceSystemId,
+        targetSystemId: existing.targetSystemId,
+      });
+      logger.info(`Automation removed dependency ${existing.id}`);
+      return {
+        success: true,
+        externalId: existing.id,
+        artifact: {
+          dependencyId: existing.id,
+          sourceSystemId: existing.sourceSystemId,
+          targetSystemId: existing.targetSystemId,
+          impactType: existing.impactType,
+        },
+      };
+    },
+  };
+
+  return [
+    createAction as ActionDefinition<unknown, unknown>,
+    removeAction as ActionDefinition<unknown, unknown>,
+  ];
+}

package/src/hooks.ts

@@ -1,8 +1,17 @@
 import { createHook } from "@checkstack/backend-api";
+import type {
+  DerivedState,
+  ImpactType,
+} from "@checkstack/dependency-common";
 
 /**
  * Dependency hooks for cross-plugin communication.
  * Other plugins can subscribe to these hooks to react to dependency changes.
+ *
+ * `impactType` and the derived-state fields carry the canonical
+ * `ImpactType` / `DerivedState` enum values, so automation triggers
+ * built on these hooks can offer the known values for `==` comparisons
+ * in the editor.
  */
 export const dependencyHooks = {
   /**
@@ -12,7 +21,7 @@ export const dependencyHooks = {
     dependencyId: string;
     sourceSystemId: string;
     targetSystemId: string;
-    impactType: string;
+    impactType: ImpactType;
   }>("dependency.created"),
 
   /**
@@ -22,7 +31,7 @@ export const dependencyHooks = {
     dependencyId: string;
     sourceSystemId: string;
     targetSystemId: string;
-    impactType: string;
+    impactType: ImpactType;
   }>("dependency.updated"),
 
   /**
@@ -33,4 +42,27 @@ export const dependencyHooks = {
     sourceSystemId: string;
     targetSystemId: string;
   }>("dependency.deleted"),
+
+  /**
+   * Emitted when an upstream system's state change has propagated
+   * through the dependency graph and produced derived-state changes
+   * on one or more downstream systems. Carries the list of affected
+   * downstream systems with their previous and new derived states so
+   * subscribers don't have to re-query the graph.
+   *
+   * Fires only when at least one downstream state actually changed —
+   * upstream events that don't move any downstream's derived state
+   * are silent. Emitted from `evaluateAndNotifyDownstream` once per
+   * upstream event (deduplicated by `sourceSystemId`, not by
+   * downstream).
+   */
+  impactPropagated: createHook<{
+    sourceSystemId: string;
+    affectedSystems: Array<{
+      systemId: string;
+      previousState: DerivedState | null;
+      newState: DerivedState | null;
+    }>;
+    timestamp: string;
+  }>("dependency.impact_propagated"),
 } as const;

package/src/index.ts

@@ -8,10 +8,21 @@ import {
   dependencyGroupSubscription,
 } from "@checkstack/dependency-common";
 import { createBackendPlugin, coreServices } from "@checkstack/backend-api";
+import {
+  automationActionExtensionPoint,
+  automationArtifactTypeExtensionPoint,
+  automationTriggerExtensionPoint,
+} from "@checkstack/automation-backend";
 import { DependencyService } from "./services/dependency-service";
 import { WarningEvaluationService } from "./services/warning-evaluation-service";
 import type { SystemStatus } from "./services/warning-evaluation-service";
 import { createRouter } from "./router";
+import {
+  createDependencyActions,
+  dependencyArtifactType,
+  dependencyTriggers,
+} from "./automations";
+import { dependencyHooks } from "./hooks";
 import { CatalogApi } from "@checkstack/catalog-common";
 import { HealthCheckApi } from "@checkstack/healthcheck-common";
 import { MaintenanceApi } from "@checkstack/maintenance-common";
@@ -36,6 +47,17 @@ export default createBackendPlugin({
       dependencyGroupSubscription,
     ]);
 
+    // ─── Automation Platform: triggers + artifact type ─────────────────
+    const automationTriggers = env.getExtensionPoint(
+      automationTriggerExtensionPoint,
+    );
+    for (const trigger of dependencyTriggers) {
+      automationTriggers.registerTrigger(trigger, pluginMetadata);
+    }
+    env
+      .getExtensionPoint(automationArtifactTypeExtensionPoint)
+      .registerArtifactType(dependencyArtifactType, pluginMetadata);
+
     // ─── GitOps Entity Kind Registration ─────────────────────────────
     let gitopsService: DependencyService | undefined;
     const kindRegistry = env.getExtensionPoint(entityKindExtensionPoint);
@@ -85,12 +107,35 @@ export default createBackendPlugin({
         rpcClient,
         logger,
         onHook,
+        emitHook,
         signalService,
       }) => {
+        // Bound callback that fires `dependency.impact_propagated`
+        // when `evaluateAndNotifyDownstream` reports actual downstream
+        // state transitions. Local so we don't pass the full
+        // `emitHook` into helper modules that should only know about
+        // the one hook they fire.
+        const emitImpactPropagated = (event: {
+          sourceSystemId: string;
+          affectedSystems: Array<{
+            systemId: string;
+            previousState: string | null;
+            newState: string | null;
+          }>;
+          timestamp: string;
+        }) => emitHook(dependencyHooks.impactPropagated, event);
         const typedDb = database as SafeDatabase<typeof schema>;
         const service = new DependencyService(typedDb);
         const warningService = new WarningEvaluationService();
 
+        // Register automation actions now that `emitHook` is available.
+        const automationActions = env.getExtensionPoint(
+          automationActionExtensionPoint,
+        );
+        for (const action of createDependencyActions({ service, emitHook })) {
+          automationActions.registerAction(action, pluginMetadata);
+        }
+
         const catalogClient = rpcClient.forPlugin(CatalogApi);
         const healthCheckClient = rpcClient.forPlugin(HealthCheckApi);
         const maintenanceClient = rpcClient.forPlugin(MaintenanceApi);
@@ -189,6 +234,7 @@ export default createBackendPlugin({
               incidentClient,
               signalService,
               logger,
+              emitImpactPropagated,
             });
           },
           {
@@ -215,6 +261,7 @@ export default createBackendPlugin({
               incidentClient,
               signalService,
               logger,
+              emitImpactPropagated,
             });
           },
           {

package/src/notifications.ts

@@ -190,6 +190,7 @@ export async function evaluateAndNotifyDownstream({
   incidentClient,
   signalService,
   logger,
+  emitImpactPropagated,
 }: {
   changedSystemId: string;
   db: Db;
@@ -204,6 +205,21 @@ export async function evaluateAndNotifyDownstream({
   incidentClient: InferClient<typeof IncidentApi>;
   signalService: SignalService;
   logger: Logger;
+  /**
+   * Optional callback fired when at least one downstream system's
+   * derived state actually changed. Wired in `afterPluginsReady` to
+   * emit `dependencyHooks.impactPropagated`; left undefined in tests
+   * + stripped-down harnesses to keep them allocation-free.
+   */
+  emitImpactPropagated?: (event: {
+    sourceSystemId: string;
+    affectedSystems: Array<{
+      systemId: string;
+      previousState: string | null;
+      newState: string | null;
+    }>;
+    timestamp: string;
+  }) => Promise<void>;
 }): Promise<void> {
   try {
     // 1. Find all downstream systems that depend on the changed system
@@ -309,6 +325,11 @@ export async function evaluateAndNotifyDownstream({
     // 6. Evaluate state changes and collect systems that need notification
     const changedSystemIds: string[] = [];
     const systemsToNotify: SystemNotificationEntry[] = [];
+    const impactPropagatedAffected: Array<{
+      systemId: string;
+      previousState: string | null;
+      newState: string | null;
+    }> = [];
 
     for (const systemId of downstreamIds) {
       const currentWarning = warningMap.get(systemId);
@@ -320,6 +341,16 @@ export async function evaluateAndNotifyDownstream({
         continue;
       }
 
+      // Always record every derived-state transition for the
+      // automation hook — including ones suppressed for end-user
+      // notifications, since an operator may want to react to
+      // propagation regardless of suppression.
+      impactPropagatedAffected.push({
+        systemId,
+        previousState: previousState ?? null,
+        newState: currentState ?? null,
+      });
+
       // State changed — update DB first
       await (currentState
         ? db
@@ -389,6 +420,26 @@ export async function evaluateAndNotifyDownstream({
         affectedSystemIds: changedSystemIds,
       });
     }
+
+    // 9. Fire the `dependency.impact_propagated` automation hook
+    // exactly once per upstream event, with the full set of
+    // downstream state transitions. Best-effort — failures are
+    // logged but never propagated up so a misbehaving subscriber
+    // can't disrupt notifications or signal broadcasts.
+    if (emitImpactPropagated && impactPropagatedAffected.length > 0) {
+      try {
+        await emitImpactPropagated({
+          sourceSystemId: changedSystemId,
+          affectedSystems: impactPropagatedAffected,
+          timestamp: new Date().toISOString(),
+        });
+      } catch (error) {
+        logger.error(
+          `Failed to emit dependency.impact_propagated hook for upstream ${changedSystemId}:`,
+          error,
+        );
+      }
+    }
   } catch (error) {
     // Don't crash the hook handler
     logger.error(

package/tsconfig.json

@@ -4,6 +4,9 @@
     "src"
   ],
   "references": [
+    {
+      "path": "../automation-backend"
+    },
     {
       "path": "../backend-api"
     },