@checkstack/dependency-backend 1.2.0 → 1.3.0

package/src/index.ts

@@ -12,6 +12,8 @@ import {
   automationActionExtensionPoint,
   automationArtifactTypeExtensionPoint,
   automationTriggerExtensionPoint,
+  entityExtensionPoint,
+  type EntityHandle,
 } from "@checkstack/automation-backend";
 import { DependencyService } from "./services/dependency-service";
 import { WarningEvaluationService } from "./services/warning-evaluation-service";
@@ -28,9 +30,20 @@ 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";
 
@@ -38,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) {
@@ -58,6 +82,40 @@ export default createBackendPlugin({
       .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);
@@ -88,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({
@@ -97,6 +158,7 @@ export default createBackendPlugin({
           catalogClient,
           healthCheckClient,
           logger,
+          getDependencyEntity: () => dependencyEntity,
         });
         rpc.registerRouter(router, dependencyContract);
 
@@ -106,7 +168,6 @@ export default createBackendPlugin({
         database,
         rpcClient,
         logger,
-        onHook,
         emitHook,
         signalService,
       }) => {
@@ -132,7 +193,11 @@ export default createBackendPlugin({
         const automationActions = env.getExtensionPoint(
           automationActionExtensionPoint,
         );
-        for (const action of createDependencyActions({ service, emitHook })) {
+        for (const action of createDependencyActions({
+          service,
+          emitHook,
+          getDependencyEntity: () => dependencyEntity,
+        })) {
           automationActions.registerAction(action, pluginMetadata);
         }
 
@@ -203,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,
@@ -237,20 +317,23 @@ export default createBackendPlugin({
               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,
@@ -264,11 +347,11 @@ export default createBackendPlugin({
               emitImpactPropagated,
             });
           },
-          {
+          delivery: {
             mode: "work-queue",
             workerGroup: "dependency-notification-recovery",
           },
-        );
+        });
 
         logger.debug("✅ Dependency Backend afterPluginsReady complete.");
       },

package/src/router.ts

@@ -16,11 +16,17 @@ import type {
   WarningEvaluationService,
   SystemStatus,
 } from "./services/warning-evaluation-service";
-import { dependencyHooks } from "./hooks";
 import type { InferClient } from "@checkstack/common";
 import { extractErrorMessage } from "@checkstack/common";
 import { CatalogApi } from "@checkstack/catalog-common";
 import { HealthCheckApi } from "@checkstack/healthcheck-common";
+import type { EntityHandle } from "@checkstack/automation-backend";
+import {
+  removeDependencyEdge,
+  toDependencyEdgeState,
+  writeDependencyEdge,
+  type DependencyEdgeState,
+} from "./dependency-entity";
 
 export function createRouter({
   service,
@@ -29,6 +35,7 @@ export function createRouter({
   catalogClient,
   healthCheckClient,
   logger,
+  getDependencyEntity,
 }: {
   service: DependencyService;
   warningService: WarningEvaluationService;
@@ -36,6 +43,8 @@ export function createRouter({
   catalogClient: InferClient<typeof CatalogApi>;
   healthCheckClient: InferClient<typeof HealthCheckApi>;
   logger: Logger;
+  /** Resolver for the reactive `dependency-edge` entity (§10.5). */
+  getDependencyEntity?: () => EntityHandle<DependencyEdgeState> | undefined;
 }) {
   /**
    * Fetch system statuses for warning evaluation using the bulk health status API.
@@ -181,9 +190,27 @@ export function createRouter({
     ),
 
     createDependency: os.createDependency.handler(
-      async ({ input, context }) => {
+      async ({ input }) => {
         try {
-          const result = await service.createDependency(input);
+          // Drive the create through the reactive `dependency-edge` entity
+          // (§10.5): `apply` performs the REAL `dependencies` write (the
+          // plugin's own db/tx, including cycle/duplicate validation that may
+          // throw) and returns the new reactive state; the deriver fires
+          // `dependency.created` from the resulting change. The id is
+          // generated up front so the handle is keyed on it and the create's
+          // `prev` snapshot reads the not-yet-existing row as absent. A
+          // throwing `apply` means no transition is appended and nothing is
+          // emitted (the create never happened).
+          const dependencyId = crypto.randomUUID();
+          let result!: Awaited<ReturnType<typeof service.createDependency>>;
+          await writeDependencyEdge({
+            handle: getDependencyEntity?.(),
+            dependencyId,
+            apply: async () => {
+              result = await service.createDependency(input, dependencyId);
+              return toDependencyEdgeState(result);
+            },
+          });
 
           // Broadcast signal
           await signalService.broadcast(DEPENDENCY_CHANGED, {
@@ -193,14 +220,6 @@ export function createRouter({
             action: "created",
           });
 
-          // Emit hook
-          await context.emitHook(dependencyHooks.dependencyCreated, {
-            dependencyId: result.id,
-            sourceSystemId: result.sourceSystemId,
-            targetSystemId: result.targetSystemId,
-            impactType: result.impactType,
-          });
-
           // Notify affected systems about warning changes
           await signalService.broadcast(DEPENDENCY_WARNINGS_CHANGED, {
             affectedSystemIds: [result.sourceSystemId],
@@ -221,26 +240,43 @@ export function createRouter({
     ),
 
     updateDependency: os.updateDependency.handler(
-      async ({ input, context }) => {
-        const result = await service.updateDependency(input);
-        if (!result) {
+      async ({ input }) => {
+        // Probe existence first so a missing dependency still surfaces as
+        // NOT_FOUND without driving an entity write.
+        const exists = await service.getDependencyById(input.id);
+        if (!exists) {
           throw new ORPCError("NOT_FOUND", {
             message: "Dependency not found",
           });
         }
 
-        await signalService.broadcast(DEPENDENCY_CHANGED, {
-          dependencyId: result.id,
-          sourceSystemId: result.sourceSystemId,
-          targetSystemId: result.targetSystemId,
-          action: "updated",
+        // Drive the update through the reactive `dependency-edge` entity
+        // (§10.5); the REAL update runs INSIDE `apply`, so `prev` is
+        // snapshotted before the write and the deriver fires
+        // `dependency.updated` from the resulting change.
+        let result!: NonNullable<
+          Awaited<ReturnType<typeof service.updateDependency>>
+        >;
+        await writeDependencyEdge({
+          handle: getDependencyEntity?.(),
+          dependencyId: input.id,
+          apply: async () => {
+            const updated = await service.updateDependency(input);
+            if (!updated) {
+              throw new ORPCError("NOT_FOUND", {
+                message: "Dependency not found",
+              });
+            }
+            result = updated;
+            return toDependencyEdgeState(result);
+          },
         });
 
-        await context.emitHook(dependencyHooks.dependencyUpdated, {
+        await signalService.broadcast(DEPENDENCY_CHANGED, {
           dependencyId: result.id,
           sourceSystemId: result.sourceSystemId,
           targetSystemId: result.targetSystemId,
-          impactType: result.impactType,
+          action: "updated",
         });
 
         await signalService.broadcast(DEPENDENCY_WARNINGS_CHANGED, {
@@ -252,9 +288,22 @@ export function createRouter({
     ),
 
     deleteDependency: os.deleteDependency.handler(
-      async ({ input, context }) => {
+      async ({ input }) => {
         const existing = await service.getDependencyById(input.id);
-        const success = await service.deleteDependency(input.id);
+
+        // 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`
+        // from the tombstone. `success` tracks whether the row was actually
+        // deleted.
+        let success = false;
+        await removeDependencyEdge({
+          handle: getDependencyEntity?.(),
+          dependencyId: input.id,
+          apply: async () => {
+            success = await service.deleteDependency(input.id);
+          },
+        });
 
         if (success && existing) {
           await signalService.broadcast(DEPENDENCY_CHANGED, {
@@ -264,12 +313,6 @@ export function createRouter({
             action: "deleted",
           });
 
-          await context.emitHook(dependencyHooks.dependencyDeleted, {
-            dependencyId: input.id,
-            sourceSystemId: existing.sourceSystemId,
-            targetSystemId: existing.targetSystemId,
-          });
-
           await signalService.broadcast(DEPENDENCY_WARNINGS_CHANGED, {
             affectedSystemIds: [existing.sourceSystemId],
           });

package/src/services/dependency-service.ts

@@ -11,6 +11,7 @@ import type {
   CreateDependencyInput,
   UpdateDependencyInput,
   NodePosition,
+  ImpactType,
 } from "@checkstack/dependency-common";
 
 type Db = SafeDatabase<typeof schema>;
@@ -59,8 +60,17 @@ export class DependencyService {
   /**
    * Create a new dependency with cycle detection.
    * Throws if the dependency would create a circular chain.
+   *
+   * `id` may be supplied by the caller so the reactive `dependency-edge`
+   * entity can be keyed on a known id BEFORE the insert runs (the create's
+   * `prev` snapshot must read the not-yet-existing row as absent — see
+   * §10.5). When omitted, a fresh id is generated. The id is server-owned
+   * either way.
    */
-  async createDependency(input: CreateDependencyInput): Promise<Dependency> {
+  async createDependency(
+    input: CreateDependencyInput,
+    id: string = generateId(),
+  ): Promise<Dependency> {
     // Check for duplicate edge
     const [existing] = await this.db
       .select()
@@ -90,7 +100,6 @@ export class DependencyService {
       );
     }
 
-    const id = generateId();
     await this.db.insert(dependencies).values({
       id,
       sourceSystemId: input.sourceSystemId,
@@ -213,12 +222,67 @@ export class DependencyService {
 
     return {
       ...row,
-       
+
       label: row.label ?? null,
       healthCheckRules: rules.length > 0 ? rules : undefined,
     };
   }
 
+  /**
+   * Batched reactive-state read for the `dependency-edge` entity (Model B
+   * plugin-backed `read` accessor). Given dependency ids, return the reactive
+   * subset `{ sourceSystemId, targetSystemId, impactType, transitive }` for
+   * each that exists (missing ids omitted). Reads the AUTHORITATIVE
+   * `dependencies` table — no framework `entity_state` storage. This is the
+   * single source of truth `handle.mutate` snapshots `prev` from and
+   * `get`/`getMany`/scope enrichment route through.
+   */
+  async getManyEntityStates(
+    ids: ReadonlyArray<string>,
+  ): Promise<
+    Record<
+      string,
+      {
+        sourceSystemId: string;
+        targetSystemId: string;
+        impactType: ImpactType;
+        transitive: boolean;
+      }
+    >
+  > {
+    if (ids.length === 0) return {};
+
+    const rows = await this.db
+      .select({
+        id: dependencies.id,
+        sourceSystemId: dependencies.sourceSystemId,
+        targetSystemId: dependencies.targetSystemId,
+        impactType: dependencies.impactType,
+        transitive: dependencies.transitive,
+      })
+      .from(dependencies)
+      .where(inArray(dependencies.id, [...ids]));
+
+    const out: Record<
+      string,
+      {
+        sourceSystemId: string;
+        targetSystemId: string;
+        impactType: ImpactType;
+        transitive: boolean;
+      }
+    > = {};
+    for (const row of rows) {
+      out[row.id] = {
+        sourceSystemId: row.sourceSystemId,
+        targetSystemId: row.targetSystemId,
+        impactType: row.impactType,
+        transitive: row.transitive,
+      };
+    }
+    return out;
+  }
+
   // ===========================================================================
   // NODE POSITIONS
   // ===========================================================================