@checkstack/dependency-backend 1.1.6 → 1.3.0

package/src/automations.ts

@@ -0,0 +1,327 @@
+/**
+ * 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 { makeEntityDrivenTriggerSetup } from "@checkstack/automation-backend";
+import { extractErrorMessage } from "@checkstack/common";
+import {
+  DerivedStateSchema,
+  ImpactTypeSchema,
+} from "@checkstack/dependency-common";
+
+import type { EntityHandle } from "@checkstack/automation-backend";
+import { dependencyHooks } from "./hooks";
+import type { DependencyService } from "./services/dependency-service";
+import {
+  removeDependencyEdge,
+  toDependencyEdgeState,
+  writeDependencyEdge,
+  type DependencyEdgeState,
+} from "./dependency-entity";
+
+// ─── 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 ──────────────────────────────────────────────────────────
+
+// These three triggers are ENTITY-DRIVEN (§10.5): the `dependency-edge`
+// entity's change deriver fires `dependency.created/.updated/.deleted` via
+// Stage-1 routing, so they no longer subscribe to a hook. A no-op `setup`
+// keeps them in the editor's trigger catalog without re-introducing a hook.
+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,
+  setup: makeEntityDrivenTriggerSetup<
+    z.infer<typeof dependencyCreatedPayloadSchema>
+  >(),
+  contextKey: (p) => p.dependencyId,
+};
+
+export const dependencyUpdatedTrigger: TriggerDefinition<
+  z.infer<typeof dependencyUpdatedPayloadSchema>
+> = {
+  id: "updated",
+  displayName: "Dependency Updated",
+  description:
+    "Fires when an existing dependency's reactive state changes (impact type, source, target, or transitivity). A label-only edit does not fire this trigger.",
+  category: "Dependencies",
+  icon: "Network",
+  payloadSchema: dependencyUpdatedPayloadSchema,
+  setup: makeEntityDrivenTriggerSetup<
+    z.infer<typeof dependencyUpdatedPayloadSchema>
+  >(),
+  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,
+  setup: makeEntityDrivenTriggerSetup<
+    z.infer<typeof dependencyDeletedPayloadSchema>
+  >(),
+  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>;
+  /** Resolver for the reactive `dependency-edge` entity (§10.5). */
+  getDependencyEntity?: () => EntityHandle<DependencyEdgeState> | undefined;
+}
+
+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 {
+        // Drive the create through the reactive `dependency-edge` entity
+        // (§10.5): the REAL create (with cycle/duplicate validation that may
+        // throw) runs INSIDE `apply`, so `prev` is snapshotted (absent →
+        // null) BEFORE the insert and the deriver fires `dependency.created`.
+        // The id is generated up front so the create's `prev` snapshot reads
+        // the not-yet-existing row as absent.
+        const dependencyId = crypto.randomUUID();
+        let created!: Awaited<
+          ReturnType<typeof deps.service.createDependency>
+        >;
+        await writeDependencyEdge({
+          handle: deps.getDependencyEntity?.(),
+          dependencyId,
+          apply: async () => {
+            created = await deps.service.createDependency(
+              {
+                sourceSystemId: config.sourceSystemId,
+                targetSystemId: config.targetSystemId,
+                impactType: config.impactType,
+                transitive: config.transitive,
+                label: config.label,
+                healthCheckRules: [],
+              },
+              dependencyId,
+            );
+            return toDependencyEdgeState(created);
+          },
+        });
+        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}`,
+        };
+      }
+      // Drive the delete through the reactive `dependency-edge` entity
+      // tombstone (§10.5); the REAL delete runs INSIDE `apply`, so `prev` is
+      // snapshotted before it and the deriver fires `dependency.deleted`.
+      let removed = false;
+      await removeDependencyEdge({
+        handle: deps.getDependencyEntity?.(),
+        dependencyId: existing.id,
+        apply: async () => {
+          removed = await deps.service.deleteDependency(config.dependencyId);
+        },
+      });
+      if (!removed) {
+        return {
+          success: false,
+          error: `Dependency ${config.dependencyId} disappeared mid-delete`,
+        };
+      }
+      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/dependency-entity.test.ts

@@ -0,0 +1,270 @@
+import { describe, it, expect } from "bun:test";
+import type {
+  EntityChanged,
+  EntityHandle,
+} from "@checkstack/automation-backend";
+import { SYSTEM_ACTOR } from "@checkstack/common";
+
+import {
+  DEPENDENCY_EDGE_ENTITY_KIND,
+  DEPENDENCY_TRIGGER_EVENTS,
+  DependencyEdgeStateSchema,
+  createDependencyEntityRead,
+  dependencyChangeToPayload,
+  deriveDependencyTriggerEvents,
+  removeDependencyEdge,
+  toDependencyEdgeState,
+  writeDependencyEdge,
+  type DependencyEdgeState,
+} from "./dependency-entity";
+import {
+  dependencyCreatedTrigger,
+  dependencyDeletedTrigger,
+  dependencyUpdatedTrigger,
+} from "./automations";
+import type { DependencyService } from "./services/dependency-service";
+
+function change(overrides: Partial<EntityChanged> = {}): EntityChanged {
+  return {
+    kind: DEPENDENCY_EDGE_ENTITY_KIND,
+    id: "dep-1",
+    prev: {
+      sourceSystemId: "a",
+      targetSystemId: "b",
+      impactType: "degraded",
+      transitive: false,
+    },
+    next: {
+      sourceSystemId: "a",
+      targetSystemId: "b",
+      impactType: "critical",
+      transitive: false,
+    },
+    delta: { impactType: "critical" },
+    changedFields: ["impactType"],
+    actor: SYSTEM_ACTOR,
+    occurredAt: new Date().toISOString(),
+    ...overrides,
+  };
+}
+
+describe("dependencyChangeToPayload — payloadSchema parity", () => {
+  it("a create payload validates against the created trigger's payloadSchema", () => {
+    const payload = dependencyChangeToPayload(
+      change({
+        prev: null,
+        next: {
+          sourceSystemId: "a",
+          targetSystemId: "b",
+          impactType: "degraded",
+          transitive: false,
+        },
+      }),
+    );
+    const parsed = dependencyCreatedTrigger.payloadSchema.parse(payload);
+    expect(parsed.dependencyId).toBe("dep-1");
+    expect(parsed.sourceSystemId).toBe("a");
+    expect(parsed.targetSystemId).toBe("b");
+    expect(parsed.impactType).toBe("degraded");
+  });
+
+  it("an update payload validates against the updated trigger's payloadSchema", () => {
+    const parsed = dependencyUpdatedTrigger.payloadSchema.parse(
+      dependencyChangeToPayload(change()),
+    );
+    expect(parsed.dependencyId).toBe("dep-1");
+    expect(parsed.impactType).toBe("critical");
+  });
+
+  it("a delete payload validates against the deleted trigger's payloadSchema (endpoints from prev)", () => {
+    const parsed = dependencyDeletedTrigger.payloadSchema.parse(
+      dependencyChangeToPayload(change({ next: null })),
+    );
+    expect(parsed.dependencyId).toBe("dep-1");
+    // The deleted edge's endpoints come from `prev` (next is the tombstone).
+    expect(parsed.sourceSystemId).toBe("a");
+    expect(parsed.targetSystemId).toBe("b");
+  });
+});
+
+describe("deriveDependencyTriggerEvents", () => {
+  it("create → dependency.created", () => {
+    expect(
+      deriveDependencyTriggerEvents(
+        change({
+          prev: null,
+          next: {
+            sourceSystemId: "a",
+            targetSystemId: "b",
+            impactType: "degraded",
+            transitive: false,
+          },
+        }),
+      ),
+    ).toEqual([DEPENDENCY_TRIGGER_EVENTS.created]);
+  });
+  it("tombstone → dependency.deleted", () => {
+    expect(deriveDependencyTriggerEvents(change({ next: null }))).toEqual([
+      DEPENDENCY_TRIGGER_EVENTS.deleted,
+    ]);
+  });
+  it("update → dependency.updated", () => {
+    expect(deriveDependencyTriggerEvents(change())).toEqual([
+      DEPENDENCY_TRIGGER_EVENTS.updated,
+    ]);
+  });
+});
+
+describe("DependencyEdgeStateSchema", () => {
+  it("parses the reactive subset", () => {
+    const parsed = DependencyEdgeStateSchema.parse({
+      sourceSystemId: "a",
+      targetSystemId: "b",
+      impactType: "degraded",
+      transitive: true,
+    });
+    expect(parsed.transitive).toBe(true);
+  });
+});
+
+describe("toDependencyEdgeState", () => {
+  it("projects the reactive subset off a full dependency", () => {
+    expect(
+      toDependencyEdgeState({
+        sourceSystemId: "a",
+        targetSystemId: "b",
+        impactType: "critical",
+        transitive: true,
+      }),
+    ).toEqual({
+      sourceSystemId: "a",
+      targetSystemId: "b",
+      impactType: "critical",
+      transitive: true,
+    });
+  });
+});
+
+describe("createDependencyEntityRead", () => {
+  it("routes the batched read straight to the service (plugin-backed)", async () => {
+    const seen: ReadonlyArray<string>[] = [];
+    const service = {
+      async getManyEntityStates(ids: ReadonlyArray<string>) {
+        seen.push(ids);
+        return {
+          "dep-1": {
+            sourceSystemId: "a",
+            targetSystemId: "b",
+            impactType: "degraded" as const,
+            transitive: false,
+          },
+        };
+      },
+    } as unknown as DependencyService;
+    const read = createDependencyEntityRead(service);
+    const out = await read(["dep-1", "dep-2"]);
+    expect(seen).toEqual([["dep-1", "dep-2"]]);
+    expect(out["dep-1"]).toEqual({
+      sourceSystemId: "a",
+      targetSystemId: "b",
+      impactType: "degraded",
+      transitive: false,
+    });
+  });
+});
+
+describe("writeDependencyEdge", () => {
+  it("drives the write through handle.mutate keyed by dependency id", async () => {
+    const calls: Array<{ id: string; next: DependencyEdgeState }> = [];
+    const handle = {
+      kind: DEPENDENCY_EDGE_ENTITY_KIND,
+      async mutate(input: {
+        id: string;
+        apply: () => Promise<DependencyEdgeState>;
+      }) {
+        const next = await input.apply();
+        calls.push({ id: input.id, next });
+        return next;
+      },
+    } as unknown as EntityHandle<DependencyEdgeState>;
+    let applied = false;
+    await writeDependencyEdge({
+      handle,
+      dependencyId: "dep-9",
+      apply: async () => {
+        applied = true;
+        return {
+          sourceSystemId: "a",
+          targetSystemId: "b",
+          impactType: "critical",
+          transitive: true,
+        };
+      },
+    });
+    expect(applied).toBe(true);
+    expect(calls).toEqual([
+      {
+        id: "dep-9",
+        next: {
+          sourceSystemId: "a",
+          targetSystemId: "b",
+          impactType: "critical",
+          transitive: true,
+        },
+      },
+    ]);
+  });
+
+  it("still runs the plugin write when no handle is wired", async () => {
+    let applied = false;
+    await writeDependencyEdge({
+      handle: undefined,
+      dependencyId: "x",
+      apply: async () => {
+        applied = true;
+        return {
+          sourceSystemId: "a",
+          targetSystemId: "b",
+          impactType: "degraded",
+          transitive: false,
+        };
+      },
+    });
+    expect(applied).toBe(true);
+  });
+});
+
+describe("removeDependencyEdge", () => {
+  it("tombstones via handle.remove({ apply })", async () => {
+    const removed: string[] = [];
+    let deleted = false;
+    const handle = {
+      kind: DEPENDENCY_EDGE_ENTITY_KIND,
+      async remove(input: { id: string; apply: () => Promise<void> }) {
+        await input.apply();
+        removed.push(input.id);
+      },
+    } as unknown as EntityHandle<DependencyEdgeState>;
+    await removeDependencyEdge({
+      handle,
+      dependencyId: "dep-9",
+      apply: async () => {
+        deleted = true;
+      },
+    });
+    expect(deleted).toBe(true);
+    expect(removed).toEqual(["dep-9"]);
+  });
+
+  it("still runs the delete when no handle is wired", async () => {
+    let deleted = false;
+    await removeDependencyEdge({
+      handle: undefined,
+      dependencyId: "x",
+      apply: async () => {
+        deleted = true;
+      },
+    });
+    expect(deleted).toBe(true);
+  });
+});