@checkstack/automation-backend 0.2.0 → 0.3.0

package/src/entity/on-entity-changed.test.ts

@@ -0,0 +1,189 @@
+import { describe, it, expect } from "bun:test";
+import { SYSTEM_ACTOR } from "@checkstack/common";
+import type { HookEventMeta } from "@checkstack/backend-api";
+import type { EntityChanged } from "@checkstack/automation-common";
+
+import {
+  createEntityChangedSubscriptions,
+  type OnHookFn,
+} from "./on-entity-changed";
+import { ENTITY_CHANGED_HOOK } from "./hook";
+
+const noopLogger = {
+  debug: () => {},
+  info: () => {},
+  warn: () => {},
+  error: () => {},
+} as unknown as Parameters<
+  ReturnType<typeof createEntityChangedSubscriptions>["wire"]
+>[0]["logger"];
+
+/**
+ * A fake `onHook` that records each subscription with its options and lets
+ * a test emit a payload to the matching hook id.
+ */
+function fakeOnHook() {
+  const subs: Array<{
+    hookId: string;
+    listener: (payload: unknown, meta?: HookEventMeta) => Promise<void>;
+    options: unknown;
+    active: boolean;
+  }> = [];
+  const onHook = ((hook, listener, options) => {
+    const entry = {
+      hookId: hook.id,
+      listener: listener as (
+        payload: unknown,
+        meta?: HookEventMeta,
+      ) => Promise<void>,
+      options,
+      active: true,
+    };
+    subs.push(entry);
+    return async () => {
+      entry.active = false;
+    };
+  }) as OnHookFn;
+  const emit = async (payload: EntityChanged) => {
+    for (const s of subs) {
+      if (s.active && s.hookId === ENTITY_CHANGED_HOOK.id) {
+        await s.listener(payload, { actor: SYSTEM_ACTOR });
+      }
+    }
+  };
+  return { onHook, subs, emit };
+}
+
+function change(overrides: Partial<EntityChanged> = {}): EntityChanged {
+  return {
+    kind: "health",
+    id: "sys-1",
+    prev: { status: "healthy" },
+    next: { status: "degraded" },
+    delta: { status: "degraded" },
+    changedFields: ["status"],
+    actor: SYSTEM_ACTOR,
+    occurredAt: new Date().toISOString(),
+    ...overrides,
+  };
+}
+
+describe("onEntityChanged", () => {
+  it("delivers matching-kind changes to the handler after wiring", async () => {
+    const svc = createEntityChangedSubscriptions();
+    const got: EntityChanged[] = [];
+    svc.onEntityChanged({ kind: "health", handler: (c) => void got.push(c) });
+
+    const fake = fakeOnHook();
+    svc.wire({ onHook: fake.onHook, logger: noopLogger });
+
+    await fake.emit(change());
+    expect(got).toHaveLength(1);
+    expect(got[0]?.id).toBe("sys-1");
+    expect(got[0]?.delta).toEqual({ status: "degraded" });
+  });
+
+  it("filters out changes of a different kind", async () => {
+    const svc = createEntityChangedSubscriptions();
+    const got: EntityChanged[] = [];
+    svc.onEntityChanged({ kind: "incident", handler: (c) => void got.push(c) });
+    const fake = fakeOnHook();
+    svc.wire({ onHook: fake.onHook, logger: noopLogger });
+
+    await fake.emit(change({ kind: "health" }));
+    expect(got).toHaveLength(0);
+  });
+
+  it("defaults to broadcast delivery", () => {
+    const svc = createEntityChangedSubscriptions();
+    svc.onEntityChanged({ kind: "health", handler: () => {} });
+    const fake = fakeOnHook();
+    svc.wire({ onHook: fake.onHook, logger: noopLogger });
+    expect(fake.subs[0]?.options).toEqual({ mode: "broadcast" });
+  });
+
+  it("honours work-queue delivery with a worker group", () => {
+    const svc = createEntityChangedSubscriptions();
+    svc.onEntityChanged({
+      kind: "incident",
+      handler: () => {},
+      delivery: { mode: "work-queue", workerGroup: "slo-react", maxRetries: 2 },
+    });
+    const fake = fakeOnHook();
+    svc.wire({ onHook: fake.onHook, logger: noopLogger });
+    expect(fake.subs[0]?.options).toEqual({
+      mode: "work-queue",
+      workerGroup: "slo-react",
+      maxRetries: 2,
+    });
+  });
+
+  it("rejects work-queue delivery without a worker group", () => {
+    const svc = createEntityChangedSubscriptions();
+    expect(() =>
+      svc.onEntityChanged({
+        kind: "incident",
+        handler: () => {},
+        // @ts-expect-error — intentionally omit the required workerGroup
+        delivery: { mode: "work-queue" },
+      }),
+    ).toThrow(/workerGroup/);
+  });
+
+  it("rejects an empty kind", () => {
+    const svc = createEntityChangedSubscriptions();
+    expect(() =>
+      svc.onEntityChanged({ kind: "  ", handler: () => {} }),
+    ).toThrow(/kind/);
+  });
+
+  it("buffers a subscription registered before wiring", async () => {
+    const svc = createEntityChangedSubscriptions();
+    const got: EntityChanged[] = [];
+    // Register BEFORE wire().
+    svc.onEntityChanged({ kind: "health", handler: (c) => void got.push(c) });
+    const fake = fakeOnHook();
+    // No subscription wired yet.
+    expect(fake.subs).toHaveLength(0);
+    svc.wire({ onHook: fake.onHook, logger: noopLogger });
+    expect(fake.subs).toHaveLength(1);
+    await fake.emit(change());
+    expect(got).toHaveLength(1);
+  });
+
+  it("stops delivering after unsubscribe", async () => {
+    const svc = createEntityChangedSubscriptions();
+    const got: EntityChanged[] = [];
+    const unsub = svc.onEntityChanged({
+      kind: "health",
+      handler: (c) => void got.push(c),
+    });
+    const fake = fakeOnHook();
+    svc.wire({ onHook: fake.onHook, logger: noopLogger });
+    await fake.emit(change());
+    await unsub();
+    await fake.emit(change());
+    expect(got).toHaveLength(1);
+  });
+
+  it("isolates a throwing handler", async () => {
+    const svc = createEntityChangedSubscriptions();
+    let secondRan = false;
+    svc.onEntityChanged({
+      kind: "health",
+      handler: () => {
+        throw new Error("boom");
+      },
+    });
+    svc.onEntityChanged({
+      kind: "health",
+      handler: () => {
+        secondRan = true;
+      },
+    });
+    const fake = fakeOnHook();
+    svc.wire({ onHook: fake.onHook, logger: noopLogger });
+    await fake.emit(change());
+    expect(secondRan).toBe(true);
+  });
+});

package/src/entity/on-entity-changed.ts

@@ -0,0 +1,214 @@
+/**
+ * Public cross-plugin entity-change subscription service (reactive
+ * automation engine §6.1 design decision).
+ *
+ * Other plugins (slo-backend, dependency-backend, …) must react to ANOTHER
+ * domain's entity changes WITHOUT touching the internal `ENTITY_CHANGED`
+ * hook, which stays unexported so `defineEntity` remains the only typed path
+ * that EMITS a change. This service is the typed, validated path that
+ * CONSUMES changes: a subscriber names the `kind` it cares about and gets a
+ * handler called with `{ kind, id, prev, next, delta, changedFields, actor }`
+ * for every matching change.
+ *
+ * ## Delivery semantics
+ *
+ * Two modes, picked by the subscriber:
+ *
+ *   - `"broadcast"` (DEFAULT): every instance's handler runs for every
+ *     change. Correct for reactors that maintain PER-INSTANCE state — an
+ *     in-memory cache to invalidate, a local fan-out, a websocket push. A
+ *     cleanup reactor that must touch each instance wants this.
+ *   - `"work-queue"`: exactly one instance in the cluster runs the handler
+ *     per change (load-balanced, retried). Correct for "do this side-effect
+ *     once per change" work (write a derived row, enqueue a notification).
+ *     Requires a `workerGroup` so distinct subscribers don't share a claim.
+ *
+ * The default is broadcast because the safe failure mode of "every instance
+ * reacts" is redundant work, whereas a wrong work-queue grouping silently
+ * DROPS a reactor's delivery on all but one instance — a far worse default
+ * for a cross-plugin API whose callers can't see the engine's internals.
+ *
+ * Subscriptions are registered eagerly (during another plugin's
+ * `register`/`init`) and the actual `onHook` wiring is deferred until
+ * automation-backend's `afterPluginsReady` (the only place `onHook` is
+ * injected, §3.7) — exactly like the change emitter buffers emits.
+ */
+import {
+  EntityChangedSchema,
+  type EntityChanged,
+} from "@checkstack/automation-common";
+import type { HookEventMeta, Logger } from "@checkstack/backend-api";
+
+import { ENTITY_CHANGED_HOOK } from "./hook";
+
+/** Payload delivered to an `onEntityChanged` handler (the validated change). */
+export type EntityChangedDelivery = EntityChanged;
+
+/** Handler invoked for each matching entity change. */
+export type EntityChangedHandler = (
+  change: EntityChangedDelivery,
+) => Promise<void> | void;
+
+export interface OnEntityChangedInput {
+  /** Entity kind to subscribe to (e.g. `"health"`, `"incident"`). */
+  kind: string;
+  /** Called for every change of `kind`. */
+  handler: EntityChangedHandler;
+  /**
+   * Delivery semantics. Defaults to `"broadcast"` (every instance). Use
+   * `"work-queue"` for exactly-once-per-cluster work; a `workerGroup` is
+   * then required so distinct subscribers don't compete for one claim.
+   */
+  delivery?:
+    | { mode?: "broadcast" }
+    | { mode: "work-queue"; workerGroup: string; maxRetries?: number };
+}
+
+/** Unsubscribe handle. Idempotent. */
+export type EntityChangedUnsubscribe = () => Promise<void>;
+
+/**
+ * The public surface registered on the entity extension point. Callable
+ * from another plugin's `register`/`init`; the underlying hook subscription
+ * is wired when automation-backend reaches `afterPluginsReady`.
+ */
+export type OnEntityChanged = (
+  input: OnEntityChangedInput,
+) => EntityChangedUnsubscribe;
+
+/** Type of the `onHook` fn injected in afterPluginsReady (mirrors backend-api). */
+export type OnHookFn = <T>(
+  hook: { id: string; _type?: T },
+  listener: (payload: T, meta?: HookEventMeta) => Promise<void>,
+  options?:
+    | { mode?: "broadcast"; maxRetries?: number }
+    | { mode: "work-queue"; workerGroup: string; maxRetries?: number }
+    | { mode: "instance-local" },
+) => () => Promise<void>;
+
+interface PendingSubscription {
+  input: OnEntityChangedInput;
+  /** Set once wired; calling it unsubscribes the live hook. */
+  liveUnsub?: () => Promise<void>;
+  /** True once the caller unsubscribed before wiring completed. */
+  cancelled: boolean;
+}
+
+export interface EntityChangedSubscriptions {
+  /** The `onEntityChanged` impl exposed on the entity extension point. */
+  readonly onEntityChanged: OnEntityChanged;
+  /**
+   * Wire every pending (and future) subscription to the real `onHook`.
+   * Called once from automation-backend's `afterPluginsReady`.
+   */
+  wire(args: { onHook: OnHookFn; logger: Logger }): void;
+  /** Tear down every live subscription (cleanup). */
+  disposeAll(): Promise<void>;
+}
+
+export function createEntityChangedSubscriptions(): EntityChangedSubscriptions {
+  const pending: PendingSubscription[] = [];
+  let wiring:
+    | { onHook: OnHookFn; logger: Logger }
+    | undefined;
+
+  /** Build the listener that validates + filters by kind + invokes handler. */
+  function makeListener(
+    sub: PendingSubscription,
+    logger: Logger,
+  ): (payload: EntityChanged, meta?: HookEventMeta) => Promise<void> {
+    return async (payload) => {
+      // Validate the wire payload (defensive — the hook is internal, but the
+      // public API contract is the validated shape).
+      const parsed = EntityChangedSchema.safeParse(payload);
+      if (!parsed.success) {
+        logger.warn(
+          `onEntityChanged(${sub.input.kind}): dropping malformed ENTITY_CHANGED payload`,
+        );
+        return;
+      }
+      if (parsed.data.kind !== sub.input.kind) return;
+      try {
+        await sub.input.handler(parsed.data);
+      } catch (error) {
+        logger.warn(
+          `onEntityChanged(${sub.input.kind}) handler threw: ${(error as Error).message}`,
+        );
+      }
+    };
+  }
+
+  /** Wire one subscription to the live hook. */
+  function wireOne(
+    sub: PendingSubscription,
+    onHook: OnHookFn,
+    logger: Logger,
+  ): void {
+    if (sub.cancelled) return;
+    const delivery = sub.input.delivery;
+    const listener = makeListener(sub, logger);
+    const unsub =
+      delivery && delivery.mode === "work-queue"
+        ? onHook(ENTITY_CHANGED_HOOK, listener, {
+            mode: "work-queue",
+            workerGroup: delivery.workerGroup,
+            maxRetries: delivery.maxRetries,
+          })
+        : onHook(ENTITY_CHANGED_HOOK, listener, { mode: "broadcast" });
+    sub.liveUnsub = unsub;
+  }
+
+  const onEntityChanged: OnEntityChanged = (input) => {
+    if (typeof input.kind !== "string" || input.kind.trim().length === 0) {
+      throw new Error("onEntityChanged: `kind` must be a non-empty string");
+    }
+    if (
+      input.delivery &&
+      input.delivery.mode === "work-queue" &&
+      (!input.delivery.workerGroup ||
+        input.delivery.workerGroup.trim().length === 0)
+    ) {
+      throw new Error(
+        "onEntityChanged: work-queue delivery requires a non-empty `workerGroup`",
+      );
+    }
+
+    const sub: PendingSubscription = { input, cancelled: false };
+    pending.push(sub);
+    // If wiring already happened, wire immediately.
+    if (wiring) wireOne(sub, wiring.onHook, wiring.logger);
+
+    return async () => {
+      sub.cancelled = true;
+      if (sub.liveUnsub) {
+        const unsub = sub.liveUnsub;
+        sub.liveUnsub = undefined;
+        await unsub();
+      }
+    };
+  };
+
+  return {
+    onEntityChanged,
+    wire({ onHook, logger }) {
+      wiring = { onHook, logger };
+      for (const sub of pending) {
+        if (!sub.liveUnsub) wireOne(sub, onHook, logger);
+      }
+    },
+    async disposeAll() {
+      for (const sub of pending) {
+        sub.cancelled = true;
+        if (sub.liveUnsub) {
+          const unsub = sub.liveUnsub;
+          sub.liveUnsub = undefined;
+          try {
+            await unsub();
+          } catch {
+            // best-effort cleanup
+          }
+        }
+      }
+    },
+  };
+}

package/src/entity/registry.test.ts

@@ -0,0 +1,181 @@
+import { describe, it, expect } from "bun:test";
+import { z } from "zod";
+
+import { createEntityRegistry } from "./registry";
+import { createChangeEmitter } from "./change-emitter";
+import { createFakeEntityStore } from "./fake-entity-store";
+import { createRunSecretRegistry } from "../dispatch/run-secret-registry";
+
+function makeRegistry() {
+  const secretRegistry = createRunSecretRegistry();
+  const emitter = createChangeEmitter();
+  return createEntityRegistry({ secretRegistry, emitter });
+}
+
+const stateSchema = z.object({ status: z.string(), region: z.string() });
+/** A trivial plugin `read` returning nothing — every kind needs one (Model B). */
+const emptyRead = async () => ({});
+
+describe("entity registry — validation (§6.3)", () => {
+  it("rejects a missing/empty kind", () => {
+    const reg = makeRegistry();
+    expect(() =>
+      reg.defineEntity({ kind: "   ", state: stateSchema, read: emptyRead }),
+    ).toThrow(/non-empty string/);
+  });
+
+  it("rejects a non-z.object state (hard fail)", () => {
+    const reg = makeRegistry();
+    expect(() =>
+      reg.defineEntity({
+        kind: "bad",
+        // @ts-expect-error — deliberately not a z.object
+        state: z.string(),
+        read: emptyRead,
+      }),
+    ).toThrow(/must be a z\.object/);
+  });
+
+  it("rejects a duplicate kind (globally unique)", () => {
+    const reg = makeRegistry();
+    reg.defineEntity({ kind: "incident", state: stateSchema, read: emptyRead });
+    expect(() =>
+      reg.defineEntity({
+        kind: "incident",
+        state: stateSchema,
+        read: emptyRead,
+      }),
+    ).toThrow(/duplicate kind/);
+  });
+
+  it("rejects a missing `read` (Model B requires a plugin read accessor)", () => {
+    const reg = makeRegistry();
+    expect(() =>
+      // @ts-expect-error — `read` is required in Model B
+      reg.defineEntity({ kind: "incident", state: stateSchema }),
+    ).toThrow(/`read` must be a function/);
+  });
+
+  it("tracks registered kinds in order", () => {
+    const reg = makeRegistry();
+    reg.defineEntity({ kind: "a", state: stateSchema, read: emptyRead });
+    reg.defineEntity({ kind: "b", state: stateSchema, read: emptyRead });
+    expect(reg.getKinds()).toEqual(["a", "b"]);
+  });
+});
+
+describe("entity registry — declareNonReactiveState", () => {
+  it("records declarations for the lint rule", () => {
+    const reg = makeRegistry();
+    reg.declareNonReactiveState({
+      table: "health_check_runs",
+      reason: "raw-sample",
+      note: "firehose; the aggregate is the entity",
+    });
+    const decls = reg.getNonReactiveDeclarations();
+    expect(decls).toHaveLength(1);
+    expect(decls[0]).toEqual({
+      table: "health_check_runs",
+      reason: "raw-sample",
+      note: "firehose; the aggregate is the entity",
+    });
+  });
+});
+
+describe("entity registry — store binding", () => {
+  it("throws a clear error if a handle mutates before the store is bound", async () => {
+    const reg = makeRegistry();
+    const store = createFakeEntityStore();
+    const handle = reg.defineEntity({
+      kind: "incident",
+      state: stateSchema,
+      read: store.readFor("incident"),
+    });
+    expect(reg.hasStore).toBe(false);
+    await expect(
+      handle.mutate({
+        id: "inc-1",
+        apply: async () => {
+          store.rows.set("incident:inc-1", { status: "open", region: "eu" });
+          return { status: "open", region: "eu" };
+        },
+      }),
+    ).rejects.toThrow(/store not initialized/);
+  });
+
+  it("works once the store is bound", async () => {
+    const reg = makeRegistry();
+    const store = createFakeEntityStore();
+    const handle = reg.defineEntity({
+      kind: "incident",
+      state: stateSchema,
+      read: store.readFor("incident"),
+    });
+    reg.setStore({ store });
+    expect(reg.hasStore).toBe(true);
+    await handle.mutate({
+      id: "inc-1",
+      apply: async () => {
+        store.rows.set("incident:inc-1", { status: "open", region: "eu" });
+        return { status: "open", region: "eu" };
+      },
+    });
+    expect(store.rows.get("incident:inc-1")).toEqual({
+      status: "open",
+      region: "eu",
+    });
+  });
+});
+
+describe("entity registry — Model B read + entityResolverFor", () => {
+  const incidentSchema = z.object({ status: z.string(), severity: z.string() });
+
+  it("rejects a `read` that is not a function", () => {
+    const reg = makeRegistry();
+    expect(() =>
+      reg.defineEntity({
+        kind: "incident",
+        state: incidentSchema,
+        // @ts-expect-error — deliberately not a function
+        read: 42,
+      }),
+    ).toThrow(/`read` must be a function/);
+  });
+
+  it("entityResolverFor routes a kind to its plugin `read`", async () => {
+    const reg = makeRegistry();
+    const read = async (ids: ReadonlyArray<string>) => {
+      const out: Record<string, { status: string; severity: string }> = {};
+      for (const id of ids) out[id] = { status: "open", severity: "high" };
+      return out;
+    };
+    reg.defineEntity({ kind: "incident", state: incidentSchema, read });
+    const resolver = reg.entityResolverFor("incident");
+    expect(resolver).toBeDefined();
+    expect(await resolver!(["inc-1"])).toEqual({
+      "inc-1": { status: "open", severity: "high" },
+    });
+  });
+
+  it("entityResolverFor routes a plugin-backed kind through its `read` over a backing map", async () => {
+    const reg = makeRegistry();
+    const store = createFakeEntityStore();
+    reg.defineEntity({
+      kind: "health",
+      state: incidentSchema,
+      read: store.readFor("health"),
+    });
+    reg.setStore({ store });
+    store.rows.set("health:sys-1", { status: "open", severity: "low" });
+    const resolver = reg.entityResolverFor("health");
+    expect(resolver).toBeDefined();
+    expect(await resolver!(["sys-1"])).toEqual({
+      "sys-1": { status: "open", severity: "low" },
+    });
+  });
+
+  it("entityResolverFor returns undefined for an unknown kind", () => {
+    const reg = makeRegistry();
+    expect(reg.entityResolverFor("nope")).toBeUndefined();
+  });
+});