@checkstack/dependency-backend 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,97 @@
 # @checkstack/dependency-backend
 
+## 1.3.0
+
+### Minor Changes
+
+- b995afb: Make `dependency-edge` a plugin-backed reactive entity via the Model-B entity state machine + rewire cross-plugin consumers.
+
+  Dependency defines a `dependency-edge` entity `{ sourceSystemId, targetSystemId, impactType, transitive }` keyed by dependency id. The `dependencies` table is BOTH authoritative AND the entity's current-state storage - there is no framework `entity_state` row for a dependency edge. `defineEntity` is given a plugin `read` accessor (`DependencyService.getManyEntityStates`) that projects the reactive subset straight off that table, and every reactive-state write goes through `handle.mutate` / `handle.remove`: `apply` performs the REAL `dependencies` write (the plugin's own db/tx, including the cycle/duplicate validation that may throw) and returns the new state; the framework snapshots `prev` via `read` BEFORE the write, appends the transition log, and emits `ENTITY_CHANGED` AFTER the write commits. Covered sites: create, update, delete (tombstone), plus the `dependency.create` / `dependency.remove` automation actions. Create sites pre-generate the id so the create's `prev` snapshot reads the not-yet-existing row as absent; `createDependency` accepts an optional pre-generated `id` (server-owned either way). The `dependency_derived_states` propagation cursor is declared non-reactive (bookkeeping).
+
+  A change -> trigger-event deriver reproduces the existing `dependency.created` / `.updated` / `.deleted` qualified events so automations keep firing. The old `dependency.created` / `.updated` / `.deleted` change hooks are removed; the catalog + healthcheck consumers switched from `onHook(<hook>)` to `onEntityChanged({ kind })`, all keeping `work-queue` delivery (cleanup + downstream-propagation are side-effecting writes that must run once per cluster):
+
+  - `dependency-system-cleanup`: reacts to `catalog-system` tombstones (`change.next === null`).
+  - `dependency-notification-evaluator` / `-recovery`: react to `health` changes filtered to a degraded / recovered transition via `classifyHealthChange`, reproducing the old `systemDegraded` / `systemHealthy` predicates.
+
+  `@checkstack/automation-backend` adds `makeEntityDrivenTriggerSetup()` - a no-op `setup` factory so a migrated domain's lifecycle triggers stay in the editor's trigger catalog (and register cleanly) while being fired by the entity change deriver via Stage-1 routing rather than a hook.
+
+  BREAKING CHANGES:
+
+  - The `dependency.created` / `dependency.updated` / `dependency.deleted` cross-plugin hooks (the `createHook` descriptors) are removed. Dependency lifecycle is now the reactive `dependency-edge` entity; the matching trigger events still fire (via the entity change deriver), so existing automations on `dependency.created/.updated/.deleted` keep working. The `dependency.impact_propagated` hook is KEPT (a derived fan-out signal, not a single mutable field). No in-repo plugin subscribed to the removed hooks.
+  - On the RPC create path, the `dependency.created` entity emit (via `mutate`) now precedes the `DEPENDENCY_CHANGED` realtime signal broadcast (previously the signal fired first, then the mirror); both still fire on a successful create.
+  - NARROWING: `dependency.updated` now fires only on a change to the REACTIVE state (`impactType`, `source`, `target`, or `transitive`). A label-only edit no longer fires `dependency.updated` (the label is not reactive entity state). Re-author any automation that needed to react to a label-only dependency edit against a different signal.
+
+- b995afb: Restore the documented domain payload fields on entity-driven automation triggers.
+
+  Migrated triggers declare domain-named `payloadSchema`s (incident `incidentId`; health `systemId` / `previousStatus`; catalog `systemId` / `changedFields`; dependency `dependencyId`), but Stage-2 dispatch built `trigger.payload` from the generic entity-change shape (`{ kind, id, prev, next, delta, ...next }`). Operator filters and templates reading `trigger.payload.incidentId` / `.systemId` / `.previousStatus` silently resolved to `undefined` — a regression vs the legacy hook payloads.
+
+  Changes:
+
+  - `@checkstack/automation-backend`: `registerChangeDeriver` now accepts an optional per-kind `toPayload(changed) => Record<string, unknown>` mapper (at most one per kind; a second distinct mapper throws). Stage-2's `changedToPayload` uses the registered mapper to build `trigger.payload` so it matches the kind's declared `payloadSchema`, falling back to the generic change shape for kinds without a mapper. New exported type `EntityChangePayloadMapper`.
+  - `@checkstack/incident-backend`, `@checkstack/healthcheck-backend`, `@checkstack/catalog-backend`, `@checkstack/dependency-backend`: implement and register a `toPayload` for each entity-driven kind so `trigger.payload` carries the legacy domain keys again.
+
+  Descriptive incident payload fields not derivable from the reactive entity state (`title`, `description`, `createdAt`, `resolvedAt`) are now OPTIONAL on the incident trigger `payloadSchema`s — they were always absent from an entity-driven payload.
+
+### Patch Changes
+
+- b995afb: Extract a shared `withEntityWrite` / `withEntityRemove` guard for PLUGIN-BACKED (Model B) reactive entities and refactor the per-domain copies onto it.
+
+  Every plugin-backed domain (incident, catalog, dependency, maintenance, slo, satellite) reimplemented the same "no handle wired → run the plugin write directly; handle wired → route through `handle.mutate` / `handle.remove`" guard, varying only in the id-key name. `@checkstack/automation-backend` now exports `withEntityWrite` / `withEntityRemove` (from the entity barrel) and each domain's thin, well-named wrappers (`writeIncidentEntity`, `writeMaintenanceEntity`, satellite's `mirror`, …) delegate to it, so the branch lives in exactly one place. Behavior is unchanged.
+
+  `writeHealthEntity` (healthcheck-backend) is intentionally NOT migrated onto the helper — it is genuinely bespoke (closure-captured durable state, distinct rethrow-vs-fail-soft branches, a per-system serializer, and it returns the computed state). SLO keeps its fail-soft `onError` wrapper around the shared guard.
+
+- Updated dependencies [270ef29]
+- Updated dependencies [b995afb]
+- Updated dependencies [b995afb]
+- Updated dependencies [b995afb]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [b995afb]
+- Updated dependencies [b995afb]
+- Updated dependencies [b995afb]
+- Updated dependencies [b995afb]
+- Updated dependencies [270ef29]
+- Updated dependencies [b995afb]
+- Updated dependencies [270ef29]
+- Updated dependencies [b995afb]
+- Updated dependencies [b995afb]
+- Updated dependencies [270ef29]
+- Updated dependencies [b995afb]
+- Updated dependencies [b995afb]
+- Updated dependencies [270ef29]
+- Updated dependencies [b995afb]
+- Updated dependencies [b995afb]
+- Updated dependencies [b995afb]
+- Updated dependencies [b995afb]
+- Updated dependencies [b995afb]
+- Updated dependencies [b995afb]
+- Updated dependencies [b995afb]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [b995afb]
+- Updated dependencies [b995afb]
+  - @checkstack/backend-api@0.19.0
+  - @checkstack/automation-backend@0.3.0
+  - @checkstack/gitops-common@0.5.0
+  - @checkstack/gitops-backend@0.4.0
+  - @checkstack/healthcheck-backend@1.4.0
+  - @checkstack/healthcheck-common@1.4.0
+  - @checkstack/maintenance-common@1.3.0
+  - @checkstack/catalog-backend@1.3.0
+
 ## 1.2.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/dependency-backend",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "license": "Elastic-2.0",
   "type": "module",
   "main": "src/index.ts",
@@ -15,28 +15,28 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@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.6",
-    "@checkstack/healthcheck-common": "1.2.0",
-    "@checkstack/healthcheck-backend": "1.2.0",
-    "@checkstack/maintenance-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.6",
-    "@checkstack/gitops-common": "0.4.1",
-    "@checkstack/common": "0.11.0",
+    "@checkstack/backend-api": "0.18.0",
+    "@checkstack/automation-backend": "0.2.0",
+    "@checkstack/dependency-common": "1.1.3",
+    "@checkstack/catalog-common": "2.2.3",
+    "@checkstack/catalog-backend": "1.2.0",
+    "@checkstack/healthcheck-common": "1.3.0",
+    "@checkstack/healthcheck-backend": "1.3.0",
+    "@checkstack/maintenance-common": "1.2.3",
+    "@checkstack/incident-common": "1.3.1",
+    "@checkstack/notification-common": "1.2.1",
+    "@checkstack/signal-common": "0.2.5",
+    "@checkstack/gitops-backend": "0.3.7",
+    "@checkstack/gitops-common": "0.4.2",
+    "@checkstack/common": "0.12.0",
     "drizzle-orm": "^0.45.0",
     "zod": "^4.2.1",
     "@orpc/server": "^1.13.2"
   },
   "devDependencies": {
     "@checkstack/drizzle-helper": "0.0.5",
-    "@checkstack/scripts": "0.3.3",
-    "@checkstack/test-utils-backend": "0.1.30",
+    "@checkstack/scripts": "0.3.4",
+    "@checkstack/test-utils-backend": "0.1.31",
     "@checkstack/tsconfig": "0.0.7",
     "@types/bun": "^1.0.0",
     "drizzle-kit": "^0.31.10",

package/src/automations.test.ts

@@ -14,7 +14,6 @@ import {
   dependencyTriggers,
   dependencyUpdatedTrigger,
 } from "./automations";
-import { dependencyHooks } from "./hooks";
 import type { DependencyService } from "./services/dependency-service";
 
 const logger = createMockLogger() as Logger;
@@ -184,7 +183,28 @@ describe("dependency.create", () => {
       },
     });
     const emitHook = mock(async (_hook: unknown, _payload: unknown) => {});
-    const [create] = createDependencyActions({ service, emitHook: emitHook as never });
+    // The action now drives the create through `handle.mutate({ id, apply })`:
+    // it pre-generates the dependency id (keying the handle), runs `apply()`
+    // (the real `createDependency`), and the handle records the resulting
+    // reactive state.
+    const mutateCalls: Array<{ id: string; next: unknown }> = [];
+    const getDependencyEntity = () =>
+      ({
+        kind: "dependency-edge",
+        async mutate(input: {
+          id: string;
+          apply: () => Promise<unknown>;
+        }) {
+          const next = await input.apply();
+          mutateCalls.push({ id: input.id, next });
+          return next;
+        },
+      }) as never;
+    const [create] = createDependencyActions({
+      service,
+      emitHook: emitHook as never,
+      getDependencyEntity,
+    });
 
     const result = await create!.execute({
       ...ctxBase,
@@ -201,9 +221,24 @@ describe("dependency.create", () => {
     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);
+    // The old `dependencyCreated` hook emission was replaced by driving the
+    // create through the reactive `dependency-edge` entity via `handle.mutate`
+    // (§10.5): the handle is keyed by the pre-generated dependency id, and
+    // `apply` returns the resulting reactive state.
+    expect(emitHook).not.toHaveBeenCalled();
+    expect(mutateCalls).toHaveLength(1);
+    // The id keying the handle is the pre-generated id passed into the
+    // service create (server-owned uuid), not asserted to a literal here.
+    expect(typeof mutateCalls[0]!.id).toBe("string");
+    expect(mutateCalls[0]!.next).toEqual({
+      sourceSystemId: "sys-a",
+      targetSystemId: "sys-b",
+      impactType: "critical",
+      transitive: false,
+    });
+    // The create was driven with the pre-generated id as its second arg.
+    expect(service.createMock).toHaveBeenCalledTimes(1);
+    expect(service.createMock.mock.calls[0]![1]).toBe(mutateCalls[0]!.id);
   });
 
   it("returns a failure when service.createDependency throws (e.g. cycle detected)", async () => {
@@ -247,7 +282,23 @@ describe("dependency.remove", () => {
       deleteResult: true,
     });
     const emitHook = mock(async (_hook: unknown, _payload: unknown) => {});
-    const [, remove] = createDependencyActions({ service, emitHook: emitHook as never });
+    // The action now drives the delete through `handle.remove({ id, apply })`:
+    // it runs `apply()` (the real `deleteDependency`) and the handle records
+    // the tombstoned id.
+    const removeCalls: string[] = [];
+    const getDependencyEntity = () =>
+      ({
+        kind: "dependency-edge",
+        async remove(input: { id: string; apply: () => Promise<void> }) {
+          await input.apply();
+          removeCalls.push(input.id);
+        },
+      }) as never;
+    const [, remove] = createDependencyActions({
+      service,
+      emitHook: emitHook as never,
+      getDependencyEntity,
+    });
 
     const result = await remove!.execute({
       ...ctxBase,
@@ -258,8 +309,12 @@ describe("dependency.remove", () => {
     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);
+    // The old `dependencyDeleted` hook emission was replaced by driving the
+    // tombstone through the reactive `dependency-edge` entity via
+    // `handle.remove` (§10.5). The real delete ran inside `apply`.
+    expect(emitHook).not.toHaveBeenCalled();
+    expect(service.deleteMock).toHaveBeenCalledTimes(1);
+    expect(removeCalls).toEqual(["dep-1"]);
   });
 
   it("returns failure if the dependency does not exist", async () => {

package/src/automations.ts

@@ -24,14 +24,22 @@ 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 ─────────────────
 
@@ -69,6 +77,10 @@ const dependencyImpactPropagatedPayloadSchema = z.object({
 
 // ─── 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>
 > = {
@@ -78,7 +90,9 @@ export const dependencyCreatedTrigger: TriggerDefinition<
   category: "Dependencies",
   icon: "Network",
   payloadSchema: dependencyCreatedPayloadSchema,
-  hook: dependencyHooks.dependencyCreated,
+  setup: makeEntityDrivenTriggerSetup<
+    z.infer<typeof dependencyCreatedPayloadSchema>
+  >(),
   contextKey: (p) => p.dependencyId,
 };
 
@@ -87,11 +101,14 @@ export const dependencyUpdatedTrigger: TriggerDefinition<
 > = {
   id: "updated",
   displayName: "Dependency Updated",
-  description: "Fires when an existing dependency's impact-type or label changes",
+  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,
-  hook: dependencyHooks.dependencyUpdated,
+  setup: makeEntityDrivenTriggerSetup<
+    z.infer<typeof dependencyUpdatedPayloadSchema>
+  >(),
   contextKey: (p) => p.dependencyId,
 };
 
@@ -104,7 +121,9 @@ export const dependencyDeletedTrigger: TriggerDefinition<
   category: "Dependencies",
   icon: "Network",
   payloadSchema: dependencyDeletedPayloadSchema,
-  hook: dependencyHooks.dependencyDeleted,
+  setup: makeEntityDrivenTriggerSetup<
+    z.infer<typeof dependencyDeletedPayloadSchema>
+  >(),
   contextKey: (p) => p.dependencyId,
 };
 
@@ -178,6 +197,8 @@ export const dependencyArtifactType = {
 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(
@@ -199,19 +220,33 @@ export function createDependencyActions(
     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,
+        // 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 {
@@ -254,18 +289,23 @@ export function createDependencyActions(
           error: `Dependency not found: ${config.dependencyId}`,
         };
       }
-      const removed = await deps.service.deleteDependency(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`,
         };
       }
-      await deps.emitHook(dependencyHooks.dependencyDeleted, {
-        dependencyId: existing.id,
-        sourceSystemId: existing.sourceSystemId,
-        targetSystemId: existing.targetSystemId,
-      });
       logger.info(`Automation removed dependency ${existing.id}`);
       return {
         success: true,