@checkstack/dependency-backend 1.1.6 → 1.3.0

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,36 +1,43 @@
 import { createHook } from "@checkstack/backend-api";
+import type { DerivedState } 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 = {
-  /**
-   * Emitted when a dependency is created.
-   */
-  dependencyCreated: createHook<{
-    dependencyId: string;
-    sourceSystemId: string;
-    targetSystemId: string;
-    impactType: string;
-  }>("dependency.created"),
-
-  /**
-   * Emitted when a dependency is updated.
-   */
-  dependencyUpdated: createHook<{
-    dependencyId: string;
-    sourceSystemId: string;
-    targetSystemId: string;
-    impactType: string;
-  }>("dependency.updated"),
+  // 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 a dependency is 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).
    */
-  dependencyDeleted: createHook<{
-    dependencyId: string;
+  impactPropagated: createHook<{
     sourceSystemId: string;
-    targetSystemId: string;
-  }>("dependency.deleted"),
+    affectedSystems: Array<{
+      systemId: string;
+      previousState: DerivedState | null;
+      newState: DerivedState | null;
+    }>;
+    timestamp: string;
+  }>("dependency.impact_propagated"),
 } as const;

package/src/index.ts

@@ -8,18 +8,42 @@ import {
   dependencyGroupSubscription,
 } from "@checkstack/dependency-common";
 import { createBackendPlugin, coreServices } from "@checkstack/backend-api";
+import {
+  automationActionExtensionPoint,
+  automationArtifactTypeExtensionPoint,
+  automationTriggerExtensionPoint,
+  entityExtensionPoint,
+  type EntityHandle,
+} 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";
 import { IncidentApi } from "@checkstack/incident-common";
 import { NotificationApi } from "@checkstack/notification-common";
-import { catalogHooks } from "@checkstack/catalog-backend";
-import { healthCheckHooks } from "@checkstack/healthcheck-backend";
+import { CATALOG_SYSTEM_ENTITY_KIND } from "@checkstack/catalog-backend";
+import {
+  HEALTH_ENTITY_KIND,
+  classifyHealthChange,
+} from "@checkstack/healthcheck-backend";
 import { evaluateAndNotifyDownstream } from "./notifications";
+import {
+  DEPENDENCY_EDGE_ENTITY_KIND,
+  DependencyEdgeStateSchema,
+  createDependencyEntityRead,
+  dependencyChangeToPayload,
+  deriveDependencyTriggerEvents,
+  type DependencyEdgeState,
+} from "./dependency-entity";
 import { entityKindExtensionPoint } from "@checkstack/gitops-backend";
 import { registerDependencyGitOpsKinds } from "./dependency-gitops-kinds";
 
@@ -27,6 +51,17 @@ import { registerDependencyGitOpsKinds } from "./dependency-gitops-kinds";
 // Plugin Definition
 // =============================================================================
 
+// Reactive `dependency-edge` entity handle (§10.5). Defined in register();
+// mutated from the router/actions onward.
+let dependencyEntity: EntityHandle<DependencyEdgeState> | undefined;
+
+// The DependencyService is created in init() (it needs the resolved
+// database), but the PLUGIN-BACKED entity `read` accessor must be supplied at
+// `defineEntity` time in register(). This holder bridges the two: the `read`
+// closure resolves the service lazily, and init() sets it before any mutation
+// runs (the registry only mutates from init() onward).
+let dependencyServiceRef: DependencyService | undefined;
+
 export default createBackendPlugin({
   metadata: pluginMetadata,
   register(env) {
@@ -36,6 +71,51 @@ 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);
+
+    // ─── Reactive `dependency-edge` entity (§10.5) ─────────────────────
+    // PLUGIN-BACKED (Model B): the `dependencies` table IS the current-state
+    // storage. `read` routes straight to the service's batched authoritative
+    // read — no framework `entity_state` row, so no `indexes` (those only
+    // apply to store-backed kinds). The `read` closure resolves the service
+    // set by init() (mutations only happen from init on).
+    const entityPoint = env.getExtensionPoint(entityExtensionPoint);
+    dependencyEntity = entityPoint.defineEntity<DependencyEdgeState>({
+      kind: DEPENDENCY_EDGE_ENTITY_KIND,
+      state: DependencyEdgeStateSchema,
+      read: (ids) => {
+        const svc = dependencyServiceRef;
+        if (!svc) {
+          throw new Error(
+            "dependency entity read before init: service not yet resolved",
+          );
+        }
+        return createDependencyEntityRead(svc)(ids);
+      },
+    });
+    entityPoint.registerChangeDeriver({
+      kind: DEPENDENCY_EDGE_ENTITY_KIND,
+      derive: deriveDependencyTriggerEvents,
+      toPayload: dependencyChangeToPayload,
+    });
+    const onEntityChanged = entityPoint.onEntityChanged;
+    // The propagation cursor is internal bookkeeping (§5): derived
+    // per-system state is reachable via the `health` entity, not this table.
+    entityPoint.declareNonReactiveState({
+      table: "dependency_derived_states",
+      reason: "bookkeeping",
+      note: "Propagation cursor for downstream impact evaluation. Derived per-system state is reachable via the health entity.",
+    });
+
     // ─── GitOps Entity Kind Registration ─────────────────────────────
     let gitopsService: DependencyService | undefined;
     const kindRegistry = env.getExtensionPoint(entityKindExtensionPoint);
@@ -66,6 +146,9 @@ export default createBackendPlugin({
           database as SafeDatabase<typeof schema>,
         );
         gitopsService = service;
+        // Publish the service for the PLUGIN-BACKED entity `read` accessor
+        // (defined in register()). Mutations only run from here onward.
+        dependencyServiceRef = service;
         const warningService = new WarningEvaluationService();
 
         const router = createRouter({
@@ -75,6 +158,7 @@ export default createBackendPlugin({
           catalogClient,
           healthCheckClient,
           logger,
+          getDependencyEntity: () => dependencyEntity,
         });
         rpc.registerRouter(router, dependencyContract);
 
@@ -84,13 +168,39 @@ export default createBackendPlugin({
         database,
         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,
+          getDependencyEntity: () => dependencyEntity,
+        })) {
+          automationActions.registerAction(action, pluginMetadata);
+        }
+
         const catalogClient = rpcClient.forPlugin(CatalogApi);
         const healthCheckClient = rpcClient.forPlugin(HealthCheckApi);
         const maintenanceClient = rpcClient.forPlugin(MaintenanceApi);
@@ -158,27 +268,42 @@ export default createBackendPlugin({
           return statuses;
         }
 
-        // Subscribe to catalog system deletion to clean up dependencies
-        onHook(
-          catalogHooks.systemDeleted,
-          async (payload) => {
+        // Cross-plugin consumers now react to the reactive `catalog-system`
+        // / `health` ENTITY changes via `onEntityChanged` instead of the
+        // (being-removed) catalog/healthcheck hooks (§10.5). All keep
+        // `work-queue` delivery: cleanup + downstream-propagation are
+        // side-effecting writes that must run exactly once per cluster, not
+        // per-instance (broadcast would re-run them N times).
+
+        // Subscribe to catalog system deletion (tombstone) to clean up edges
+        onEntityChanged({
+          kind: CATALOG_SYSTEM_ENTITY_KIND,
+          handler: async (change) => {
+            if (change.next !== null) return; // tombstone only
+            const systemId = change.id;
             logger.debug(
-              `Cleaning up dependencies for deleted system: ${payload.systemId}`,
+              `Cleaning up dependencies for deleted system: ${systemId}`,
             );
-            await service.removeSystemDependencies(payload.systemId);
+            await service.removeSystemDependencies(systemId);
           },
-          { mode: "work-queue", workerGroup: "dependency-system-cleanup" },
-        );
+          delivery: {
+            mode: "work-queue",
+            workerGroup: "dependency-system-cleanup",
+          },
+        });
 
-        // Subscribe to health check state changes to notify downstream dependents
-        onHook(
-          healthCheckHooks.systemDegraded,
-          async (payload) => {
+        // Upstream health DEGRADED → evaluate downstream dependents
+        onEntityChanged({
+          kind: HEALTH_ENTITY_KIND,
+          handler: async (change) => {
+            const { systemId, degraded, previousStatus, newStatus } =
+              classifyHealthChange(change);
+            if (!degraded) return;
             logger.debug(
-              `Upstream ${payload.systemId} degraded (${payload.previousStatus} → ${payload.newStatus}), evaluating downstream dependencies`,
+              `Upstream ${systemId} degraded (${previousStatus} → ${newStatus}), evaluating downstream dependencies`,
             );
             await evaluateAndNotifyDownstream({
-              changedSystemId: payload.systemId,
+              changedSystemId: systemId,
               db: typedDb,
               dependencyService: service,
               warningService,
@@ -189,22 +314,26 @@ export default createBackendPlugin({
               incidentClient,
               signalService,
               logger,
+              emitImpactPropagated,
             });
           },
-          {
+          delivery: {
             mode: "work-queue",
             workerGroup: "dependency-notification-evaluator",
           },
-        );
+        });
 
-        onHook(
-          healthCheckHooks.systemHealthy,
-          async (payload) => {
+        // Upstream health RECOVERED → evaluate downstream dependents
+        onEntityChanged({
+          kind: HEALTH_ENTITY_KIND,
+          handler: async (change) => {
+            const { systemId, recovered } = classifyHealthChange(change);
+            if (!recovered) return;
             logger.debug(
-              `Upstream ${payload.systemId} recovered, evaluating downstream dependencies`,
+              `Upstream ${systemId} recovered, evaluating downstream dependencies`,
             );
             await evaluateAndNotifyDownstream({
-              changedSystemId: payload.systemId,
+              changedSystemId: systemId,
               db: typedDb,
               dependencyService: service,
               warningService,
@@ -215,13 +344,14 @@ export default createBackendPlugin({
               incidentClient,
               signalService,
               logger,
+              emitImpactPropagated,
             });
           },
-          {
+          delivery: {
             mode: "work-queue",
             workerGroup: "dependency-notification-recovery",
           },
-        );
+        });
 
         logger.debug("✅ Dependency Backend afterPluginsReady complete.");
       },

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(