@checkstack/dependency-backend 1.2.0 → 1.3.0

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);
+  });
+});

package/src/dependency-entity.ts

@@ -0,0 +1,157 @@
+/**
+ * The reactive `dependency-edge` entity (reactive automation engine §10.5).
+ *
+ * Model B PLUGIN-BACKED entity: the `dependencies` table is authoritative AND
+ * IS the entity's current-state storage — there is NO framework `entity_state`
+ * row for a dependency edge. `defineEntity({ read })` makes that plugin state
+ * reactive: every reactive-state write goes through `handle.mutate`, whose
+ * `apply()` performs the REAL `dependencies` write via the `DependencyService`
+ * (the plugin's own db/tx) and returns the resulting reactive subset
+ * `{ sourceSystemId, targetSystemId, impactType, transitive }`. The framework
+ * snapshots `prev` via `read`, appends the transition log (its own db), and
+ * emits `ENTITY_CHANGED`. The change → trigger-event deriver reproduces
+ * `dependency.created/.updated/.deleted` so automations keep firing.
+ *
+ * `dependency_derived_states` (the propagation cursor) and the
+ * `dependency.impact_propagated` notification stay NON-reactive (§5):
+ * derived per-system state is reachable via the `health` entity, and
+ * impact propagation is a fan-out signal, not a single mutable field.
+ */
+import { z } from "zod";
+import { ImpactTypeSchema } from "@checkstack/dependency-common";
+import type {
+  EntityChangeDeriver,
+  EntityChangePayloadMapper,
+  EntityHandle,
+  EntityRead,
+} from "@checkstack/automation-backend";
+import {
+  withEntityRemove,
+  withEntityWrite,
+} from "@checkstack/automation-backend";
+
+import type { DependencyService } from "./services/dependency-service";
+
+export const DEPENDENCY_EDGE_ENTITY_KIND = "dependency-edge";
+
+export const DependencyEdgeStateSchema = z.object({
+  sourceSystemId: z.string(),
+  targetSystemId: z.string(),
+  impactType: ImpactTypeSchema,
+  transitive: z.boolean(),
+});
+
+export type DependencyEdgeState = z.infer<typeof DependencyEdgeStateSchema>;
+
+export const DEPENDENCY_TRIGGER_EVENTS = {
+  created: "dependency.created",
+  updated: "dependency.updated",
+  deleted: "dependency.deleted",
+} as const;
+
+/**
+ * `dependency-edge` change → trigger events. Create (`prev === null`),
+ * tombstone (`next === null`), or a field update map to the matching
+ * lifecycle event (the handle suppresses no-op diffs, so an update always
+ * carries a real change).
+ */
+export const deriveDependencyTriggerEvents: EntityChangeDeriver = (changed) => {
+  if (changed.prev === null && changed.next !== null) {
+    return [DEPENDENCY_TRIGGER_EVENTS.created];
+  }
+  if (changed.next === null) {
+    return [DEPENDENCY_TRIGGER_EVENTS.deleted];
+  }
+  return [DEPENDENCY_TRIGGER_EVENTS.updated];
+};
+
+/**
+ * Map a `dependency-edge` change to the domain-named `trigger.payload` the
+ * dependency triggers declare via `payloadSchema` (`dependencyId`,
+ * `sourceSystemId`, `targetSystemId`, `impactType`). Restores the keys
+ * operators read (`trigger.payload.dependencyId`, `.sourceSystemId`, …) that
+ * the generic change shape omits.
+ *
+ * `dependencyId` is the entity id. The edge fields are read from `next`, or
+ * from `prev` on a tombstone (`deleted`), so a delete trigger still carries
+ * the removed edge's endpoints. `impactType` is omitted on a delete (the
+ * `deleted` schema does not declare it).
+ */
+export const dependencyChangeToPayload: EntityChangePayloadMapper = (
+  changed,
+) => {
+  const source = changed.next ?? changed.prev;
+  const impactType = source?.["impactType"];
+  return {
+    dependencyId: changed.id,
+    sourceSystemId: source?.["sourceSystemId"],
+    targetSystemId: source?.["targetSystemId"],
+    ...(impactType === undefined ? {} : { impactType }),
+  };
+};
+
+/**
+ * Build the PLUGIN-BACKED `read` accessor for the `dependency-edge` entity.
+ * Routes straight to the service's batched authoritative read over the
+ * `dependencies` table — no framework storage.
+ */
+export function createDependencyEntityRead(
+  service: DependencyService,
+): EntityRead<DependencyEdgeState> {
+  return (ids) => service.getManyEntityStates(ids);
+}
+
+/**
+ * Project a dependency row onto the reactive `{ sourceSystemId,
+ * targetSystemId, impactType, transitive }` subset. The router/action service
+ * writes return the full dependency; this is the `apply()` return for
+ * `handle.mutate`.
+ */
+export function toDependencyEdgeState(dependency: {
+  sourceSystemId: string;
+  targetSystemId: string;
+  impactType: DependencyEdgeState["impactType"];
+  transitive: boolean;
+}): DependencyEdgeState {
+  return {
+    sourceSystemId: dependency.sourceSystemId,
+    targetSystemId: dependency.targetSystemId,
+    impactType: dependency.impactType,
+    transitive: dependency.transitive,
+  };
+}
+
+/**
+ * Drive a reactive-state `dependency-edge` write through `handle.mutate`
+ * (§10.5). `apply` performs the REAL `dependencies` write via the service
+ * (the plugin's own db/tx) and returns the new reactive state. The framework
+ * snapshots `prev`, appends the transition log, and emits `ENTITY_CHANGED`
+ * (the deriver turns that into `dependency.created/.updated`).
+ *
+ * When no handle is available (tests construct the router without one), the
+ * write still runs — the entity reactivity is layered on top, never required
+ * for the underlying write to succeed.
+ */
+export async function writeDependencyEdge(args: {
+  handle: EntityHandle<DependencyEdgeState> | undefined;
+  dependencyId: string;
+  apply: () => Promise<DependencyEdgeState>;
+}): Promise<void> {
+  const { handle, dependencyId, apply } = args;
+  await withEntityWrite({ handle, id: dependencyId, apply });
+}
+
+/**
+ * Drive a dependency-edge tombstone through `handle.remove` (§10.5). `apply`
+ * performs the REAL delete via the service; the framework records the
+ * tombstone transition and emits a tombstone change (the deriver fires
+ * `dependency.deleted`). Without a handle, the delete still runs.
+ */
+export async function removeDependencyEdge(args: {
+  handle: EntityHandle<DependencyEdgeState> | undefined;
+  dependencyId: string;
+  apply: () => Promise<void>;
+}): Promise<void> {
+  const { handle, dependencyId, apply } = args;
+  await withEntityRemove({ handle, id: dependencyId, apply });
+}

package/src/hooks.ts

@@ -1,8 +1,5 @@
 import { createHook } from "@checkstack/backend-api";
-import type {
-  DerivedState,
-  ImpactType,
-} from "@checkstack/dependency-common";
+import type { DerivedState } from "@checkstack/dependency-common";
 
 /**
  * Dependency hooks for cross-plugin communication.
@@ -14,34 +11,12 @@ import type {
  * in the editor.
  */
 export const dependencyHooks = {
-  /**
-   * Emitted when a dependency is created.
-   */
-  dependencyCreated: createHook<{
-    dependencyId: string;
-    sourceSystemId: string;
-    targetSystemId: string;
-    impactType: ImpactType;
-  }>("dependency.created"),
-
-  /**
-   * Emitted when a dependency is updated.
-   */
-  dependencyUpdated: createHook<{
-    dependencyId: string;
-    sourceSystemId: string;
-    targetSystemId: string;
-    impactType: ImpactType;
-  }>("dependency.updated"),
-
-  /**
-   * Emitted when a dependency is deleted.
-   */
-  dependencyDeleted: createHook<{
-    dependencyId: string;
-    sourceSystemId: string;
-    targetSystemId: string;
-  }>("dependency.deleted"),
+  // The `dependency.created` / `.updated` / `.deleted` hooks were removed in
+  // Phase 4 (§10.5): dependency edges are now the reactive `dependency-edge`
+  // entity, whose change deriver fires the matching `dependency.created` /
+  // `.updated` / `.deleted` trigger events through Stage-1 routing. The
+  // `impact_propagated` hook below is KEPT — it is a derived fan-out signal
+  // (per-downstream deltas), not a single mutable entity field.
 
   /**
    * Emitted when an upstream system's state change has propagated