@checkstack/automation-backend 0.2.0 → 0.3.0

package/src/dispatch/window-store.ts

@@ -0,0 +1,102 @@
+/**
+ * Drizzle-backed implementation of `WindowStore` — the windowed-count / rate
+ * trigger occurrence log. Kept thin: each method maps almost 1:1 to a DB
+ * statement, mirroring `dwell-store.ts`.
+ *
+ * The append log is the source of truth. `recordAndCount` does the proven
+ * "insert one row, then COUNT(*) within the trailing window" shape (relocated
+ * from the former healthcheck flapping detector) so the gate is durable and
+ * pod-independent: the INSERT runs once on the pod that claimed the emission
+ * from the work queue, and the COUNT is pure SQL so every pod computes the
+ * same total.
+ */
+import { and, eq, gte, isNull, lt, sql } from "drizzle-orm";
+import type { SafeDatabase } from "@checkstack/backend-api";
+
+import { automationWindowEvents } from "../schema";
+import type { RecordWindowInput, WindowStore } from "./types";
+
+type Schema = { automationWindowEvents: typeof automationWindowEvents };
+
+/** Build the `(automationId, triggerId, contextKey)` match predicate. */
+function keyWhere(
+  automationId: string,
+  triggerId: string,
+  contextKey: string | null,
+) {
+  return and(
+    eq(automationWindowEvents.automationId, automationId),
+    eq(automationWindowEvents.triggerId, triggerId),
+    contextKey === null
+      ? isNull(automationWindowEvents.contextKey)
+      : eq(automationWindowEvents.contextKey, contextKey),
+  );
+}
+
+export function createWindowStore(db: SafeDatabase<Schema>): WindowStore {
+  return {
+    async recordAndCount(input: RecordWindowInput): Promise<boolean> {
+      const {
+        automationId,
+        triggerId,
+        eventId,
+        contextKey,
+        occurredAt,
+        windowMinutes,
+        threshold,
+        refire,
+      } = input;
+
+      // (1) Append the qualifying occurrence. One INSERT per claimed emission,
+      // so the count below can't double-count across pods.
+      await db.insert(automationWindowEvents).values({
+        automationId,
+        triggerId,
+        eventId,
+        contextKey,
+        occurredAt,
+      });
+
+      // (2) Count rows in the trailing window (inclusive of the row just
+      // inserted) — a pure DB read, identical on every pod.
+      const windowStart = new Date(
+        occurredAt.getTime() - windowMinutes * 60_000,
+      );
+      const result = await db
+        .select({ count: sql<number>`COUNT(*)::int` })
+        .from(automationWindowEvents)
+        .where(
+          and(
+            keyWhere(automationId, triggerId, contextKey),
+            gte(automationWindowEvents.occurredAt, windowStart),
+          ),
+        );
+      const newCount = result[0]?.count ?? 0;
+
+      // (3) Apply the re-fire policy.
+      //  - `every`: fire on every occurrence at/over the threshold.
+      //  - `once`: fire only on the crossing edge (newCount === threshold);
+      //    re-arms naturally as old rows age out and the count re-crosses.
+      //
+      // At-least-once caveat: if the work queue redelivers an emission, the
+      // same logical occurrence inserts twice and the count can skip the exact
+      // `=== threshold` edge, so `once` may miss a fire. This is best-effort,
+      // fail-open (matching the dwell re-confirm posture) — `every` is
+      // redelivery-tolerant; pick `once` knowing the trade-off.
+      if (refire === "once") return newCount === threshold;
+      return newCount >= threshold;
+    },
+
+    async sweepExpired(cutoff: Date): Promise<void> {
+      await db
+        .delete(automationWindowEvents)
+        .where(lt(automationWindowEvents.occurredAt, cutoff));
+    },
+
+    async deleteForAutomation(automationId: string): Promise<void> {
+      await db
+        .delete(automationWindowEvents)
+        .where(eq(automationWindowEvents.automationId, automationId));
+    },
+  };
+}

package/src/entity/change-derivers.test.ts

@@ -0,0 +1,148 @@
+import { describe, it, expect } from "bun:test";
+import { SYSTEM_ACTOR } from "@checkstack/common";
+import type { EntityChanged } from "@checkstack/automation-common";
+
+import { createChangeDeriverRegistry } from "./change-derivers";
+
+function change(overrides: Partial<EntityChanged> = {}): EntityChanged {
+  return {
+    kind: "fake",
+    id: "id-1",
+    prev: null,
+    next: { status: "open" },
+    delta: { status: "open" },
+    changedFields: ["status"],
+    actor: SYSTEM_ACTOR,
+    occurredAt: new Date().toISOString(),
+    ...overrides,
+  };
+}
+
+describe("ChangeDeriverRegistry", () => {
+  it("returns [] for a kind with no registered deriver", () => {
+    const reg = createChangeDeriverRegistry();
+    expect(reg.derive(change())).toEqual([]);
+  });
+
+  it("routes a change through a registered per-kind deriver", () => {
+    const reg = createChangeDeriverRegistry();
+    reg.register({
+      kind: "fake",
+      derive: (c) =>
+        c.next?.status === "open" ? ["fake.opened"] : ["fake.closed"],
+    });
+    expect(reg.derive(change({ next: { status: "open" } }))).toEqual([
+      "fake.opened",
+    ]);
+    expect(reg.derive(change({ next: { status: "done" } }))).toEqual([
+      "fake.closed",
+    ]);
+  });
+
+  it("only invokes derivers for the matching kind", () => {
+    const reg = createChangeDeriverRegistry();
+    reg.register({ kind: "fake", derive: () => ["fake.evt"] });
+    expect(reg.derive(change({ kind: "other" }))).toEqual([]);
+  });
+
+  it("unions + de-duplicates across multiple derivers for one kind", () => {
+    const reg = createChangeDeriverRegistry();
+    reg.register({ kind: "fake", derive: () => ["a", "shared"] });
+    reg.register({ kind: "fake", derive: () => ["shared", "b"] });
+    expect(reg.derive(change())).toEqual(["a", "shared", "b"]);
+  });
+
+  it("isolates a throwing deriver from the others", () => {
+    const reg = createChangeDeriverRegistry();
+    reg.register({
+      kind: "fake",
+      derive: () => {
+        throw new Error("boom");
+      },
+    });
+    reg.register({ kind: "fake", derive: () => ["safe"] });
+    expect(reg.derive(change())).toEqual(["safe"]);
+  });
+
+  it("ignores duplicate registration of the same deriver function", () => {
+    const reg = createChangeDeriverRegistry();
+    const derive = () => ["once"];
+    reg.register({ kind: "fake", derive });
+    reg.register({ kind: "fake", derive });
+    expect(reg.derive(change())).toEqual(["once"]);
+  });
+
+  it("rejects an empty kind", () => {
+    const reg = createChangeDeriverRegistry();
+    expect(() => reg.register({ kind: "", derive: () => [] })).toThrow();
+  });
+
+  it("lists kinds with derivers", () => {
+    const reg = createChangeDeriverRegistry();
+    reg.register({ kind: "a", derive: () => [] });
+    reg.register({ kind: "b", derive: () => [] });
+    expect(reg.kinds().toSorted()).toEqual(["a", "b"]);
+  });
+});
+
+describe("ChangeDeriverRegistry — payload mapper", () => {
+  it("returns undefined when the kind has no registered mapper", () => {
+    const reg = createChangeDeriverRegistry();
+    reg.register({ kind: "fake", derive: () => ["fake.evt"] });
+    expect(reg.payload(change())).toBeUndefined();
+  });
+
+  it("maps a change to the domain-named payload via the registered mapper", () => {
+    const reg = createChangeDeriverRegistry();
+    reg.register({
+      kind: "fake",
+      derive: () => ["fake.evt"],
+      toPayload: (c) => ({ fakeId: c.id, status: c.next?.["status"] }),
+    });
+    expect(reg.payload(change({ id: "x", next: { status: "open" } }))).toEqual({
+      fakeId: "x",
+      status: "open",
+    });
+  });
+
+  it("only applies the mapper for the matching kind", () => {
+    const reg = createChangeDeriverRegistry();
+    reg.register({
+      kind: "fake",
+      derive: () => [],
+      toPayload: () => ({ mapped: true }),
+    });
+    expect(reg.payload(change({ kind: "other" }))).toBeUndefined();
+  });
+
+  it("allows registering the deriver and mapper in one call", () => {
+    const reg = createChangeDeriverRegistry();
+    reg.register({
+      kind: "fake",
+      derive: () => ["fake.evt"],
+      toPayload: (c) => ({ id: c.id }),
+    });
+    expect(reg.derive(change())).toEqual(["fake.evt"]);
+    expect(reg.payload(change({ id: "id-1" }))).toEqual({ id: "id-1" });
+  });
+
+  it("re-registering the SAME mapper for a kind is harmless", () => {
+    const reg = createChangeDeriverRegistry();
+    const toPayload = (c: EntityChanged) => ({ id: c.id });
+    reg.register({ kind: "fake", derive: () => [], toPayload });
+    reg.register({ kind: "fake", derive: () => [], toPayload });
+    expect(reg.payload(change({ id: "id-1" }))).toEqual({ id: "id-1" });
+  });
+
+  it("throws on a second DISTINCT mapper for the same kind", () => {
+    const reg = createChangeDeriverRegistry();
+    reg.register({ kind: "fake", derive: () => [], toPayload: () => ({ a: 1 }) });
+    expect(() =>
+      reg.register({
+        kind: "fake",
+        derive: () => [],
+        toPayload: () => ({ b: 2 }),
+      }),
+    ).toThrow();
+  });
+});

package/src/entity/change-derivers.ts

@@ -0,0 +1,143 @@
+/**
+ * Entity-change → trigger-event derivation registry (reactive automation
+ * engine §7, Stage-1 routing).
+ *
+ * Stage 1 turns an `ENTITY_CHANGED` into the set of qualified trigger event
+ * ids to route to fresh runs (via `findEnabledByTriggerEvent`). The mapping
+ * from "this kind changed like THIS" to "these trigger events fired" is
+ * DOMAIN knowledge — incident's `incident.created`/`.resolved`, health's
+ * `system.degraded`, etc. — so it can't live in the kind-agnostic engine.
+ *
+ * This is the generic registry the engine owns: domains register a per-kind
+ * deriver in Phase 4 (their migration). In Phase 5 no real domains are
+ * migrated, so this routes nothing in production yet — that is expected and
+ * correct. The engine calls every deriver registered for the changed kind
+ * and unions their results.
+ *
+ * A deriver receives the validated `EntityChanged` payload and returns the
+ * trigger event id(s) the change should fire (e.g. `["healthcheck.system.degraded"]`).
+ * It returns an empty array when the change fires nothing.
+ */
+import type { EntityChanged } from "@checkstack/automation-common";
+
+/**
+ * Derive the qualified trigger event id(s) a change of one entity kind
+ * should route to. Pure + synchronous. Returns `[]` for "no trigger event".
+ */
+export type EntityChangeDeriver = (
+  changed: EntityChanged,
+) => ReadonlyArray<string>;
+
+/**
+ * Map an entity change to the DOMAIN-named trigger payload (`trigger.payload`)
+ * a fresh run sees. Pure + synchronous.
+ *
+ * The generic `EntityChanged` shape (`{ kind, id, prev, next, delta, ... }`)
+ * is editor/engine-internal; operators author filters and templates against
+ * the domain-named `payloadSchema` a trigger declares (incident `incidentId`,
+ * health `systemId` / `previousStatus`, …). Without a mapper the runtime
+ * payload would NOT carry those documented keys and `trigger.payload.incidentId`
+ * etc. would silently resolve to `undefined` (a regression vs the legacy hook
+ * payloads). A domain registers `toPayload` alongside its deriver so the
+ * runtime payload matches its declared `payloadSchema`. Stage-2 falls back to
+ * the generic shape for kinds without a mapper.
+ */
+export type EntityChangePayloadMapper = (
+  changed: EntityChanged,
+) => Record<string, unknown>;
+
+export interface ChangeDeriverRegistry {
+  /**
+   * Register a deriver (and optional payload mapper) for an entity `kind`.
+   * Multiple derivers may be registered per kind (their outputs union);
+   * registering the same deriver twice is harmless.
+   *
+   * `toPayload`, when supplied, maps a change of this kind to the domain-named
+   * `trigger.payload` shape the kind's `payloadSchema` declares (see
+   * {@link EntityChangePayloadMapper}). At most one payload mapper may be
+   * registered per kind — a second distinct mapper throws (the payload shape
+   * for a kind must be unambiguous).
+   */
+  register(args: {
+    kind: string;
+    derive: EntityChangeDeriver;
+    toPayload?: EntityChangePayloadMapper;
+  }): void;
+
+  /**
+   * Derive the union of qualified trigger event ids for a change, across
+   * every deriver registered for `changed.kind`. De-duplicated, stable
+   * order (registration order, first-seen wins).
+   */
+  derive(changed: EntityChanged): ReadonlyArray<string>;
+
+  /**
+   * Map a change to its domain-named `trigger.payload`, using the payload
+   * mapper registered for `changed.kind`. Returns `undefined` when the kind
+   * has no registered mapper (the caller falls back to the generic payload
+   * shape).
+   */
+  payload(changed: EntityChanged): Record<string, unknown> | undefined;
+
+  /** Kinds that have at least one registered deriver. */
+  kinds(): ReadonlyArray<string>;
+}
+
+export function createChangeDeriverRegistry(): ChangeDeriverRegistry {
+  const byKind = new Map<string, EntityChangeDeriver[]>();
+  const payloadByKind = new Map<string, EntityChangePayloadMapper>();
+
+  return {
+    register({ kind, derive, toPayload }) {
+      if (typeof kind !== "string" || kind.trim().length === 0) {
+        throw new Error("registerChangeDeriver: `kind` must be a non-empty string");
+      }
+      const list = byKind.get(kind);
+      if (list) {
+        if (!list.includes(derive)) list.push(derive);
+      } else {
+        byKind.set(kind, [derive]);
+      }
+      if (toPayload) {
+        const existing = payloadByKind.get(kind);
+        if (existing && existing !== toPayload) {
+          throw new Error(
+            `registerChangeDeriver: a payload mapper is already registered for kind "${kind}"`,
+          );
+        }
+        payloadByKind.set(kind, toPayload);
+      }
+    },
+
+    derive(changed) {
+      const derivers = byKind.get(changed.kind);
+      if (!derivers || derivers.length === 0) return [];
+      const seen = new Set<string>();
+      const out: string[] = [];
+      for (const derive of derivers) {
+        let ids: ReadonlyArray<string>;
+        try {
+          ids = derive(changed);
+        } catch {
+          // A misbehaving deriver must not wedge routing for the others.
+          continue;
+        }
+        for (const id of ids) {
+          if (typeof id !== "string" || id.length === 0 || seen.has(id)) continue;
+          seen.add(id);
+          out.push(id);
+        }
+      }
+      return out;
+    },
+
+    payload(changed) {
+      const mapper = payloadByKind.get(changed.kind);
+      return mapper ? mapper(changed) : undefined;
+    },
+
+    kinds() {
+      return [...byKind.keys()];
+    },
+  };
+}

package/src/entity/change-emitter.test.ts

@@ -0,0 +1,66 @@
+import { describe, it, expect } from "bun:test";
+import { SYSTEM_ACTOR } from "@checkstack/common";
+import type { EntityChanged } from "@checkstack/automation-common";
+
+import { createChangeEmitter } from "./change-emitter";
+
+function makeEvent(id: string): EntityChanged {
+  return {
+    kind: "incident",
+    id,
+    prev: null,
+    next: { status: "open" },
+    delta: { status: "open" },
+    changedFields: ["status"],
+    actor: SYSTEM_ACTOR,
+    occurredAt: new Date().toISOString(),
+  };
+}
+
+describe("change emitter — deferred wiring window", () => {
+  it("buffers events emitted before the emitter is wired, then flushes in order", async () => {
+    const emitter = createChangeEmitter();
+    expect(emitter.isWired).toBe(false);
+    await emitter.emit(makeEvent("a"));
+    await emitter.emit(makeEvent("b"));
+
+    const received: string[] = [];
+    await emitter.wire(async (p) => {
+      received.push(p.id);
+    });
+    expect(emitter.isWired).toBe(true);
+    expect(received).toEqual(["a", "b"]);
+  });
+
+  it("emits synchronously once wired", async () => {
+    const received: string[] = [];
+    const emitter = createChangeEmitter();
+    await emitter.wire(async (p) => {
+      received.push(p.id);
+    });
+    await emitter.emit(makeEvent("c"));
+    expect(received).toEqual(["c"]);
+  });
+
+  it("drops the oldest when the buffer limit is exceeded (guarded, logged)", async () => {
+    const warnings: string[] = [];
+    const emitter = createChangeEmitter({
+      bufferLimit: 2,
+      logger: {
+        debug: () => {},
+        info: () => {},
+        warn: (m: string) => warnings.push(m),
+        error: () => {},
+      } as never,
+    });
+    await emitter.emit(makeEvent("1"));
+    await emitter.emit(makeEvent("2"));
+    await emitter.emit(makeEvent("3")); // evicts "1"
+    const received: string[] = [];
+    await emitter.wire(async (p) => {
+      received.push(p.id);
+    });
+    expect(received).toEqual(["2", "3"]);
+    expect(warnings.length).toBeGreaterThan(0);
+  });
+});

package/src/entity/change-emitter.ts

@@ -0,0 +1,76 @@
+/**
+ * Deferred `ENTITY_CHANGED` emitter.
+ *
+ * `emitHook` is only injected in `afterPluginsReady` (reactive automation
+ * engine §3.7). Plugins, however, call `defineEntity` in `init` and may
+ * mutate entities during `init`/`afterPluginsReady` before automation-
+ * backend's own `afterPluginsReady` runs and wires the emitter. To avoid a
+ * silent no-emit window, change events produced before the emitter is set
+ * are BUFFERED and flushed (in order) the moment it is wired.
+ *
+ * Persistence (the plugin write + transition append) is NOT deferred — only
+ * the change-event emission is, since the plugin store is always the source
+ * of truth and Stage-1 routing/wake (later phases) re-reads it.
+ */
+import type { EntityChanged } from "@checkstack/automation-common";
+import type { Logger } from "@checkstack/backend-api";
+
+export type EmitEntityChanged = (payload: EntityChanged) => Promise<void>;
+
+export interface ChangeEmitter {
+  /** Emit a change event now, or buffer it until the emitter is wired. */
+  emit(payload: EntityChanged): Promise<void>;
+  /**
+   * Wire the real emitter (called from automation-backend's
+   * `afterPluginsReady`). Flushes any buffered events in order.
+   */
+  wire(emit: EmitEntityChanged): Promise<void>;
+  /** Whether the real emitter has been wired. */
+  readonly isWired: boolean;
+}
+
+export function createChangeEmitter(args?: {
+  logger?: Logger;
+  /** Cap on buffered events before the emitter is wired (guards a runaway). */
+  bufferLimit?: number;
+}): ChangeEmitter {
+  const logger = args?.logger;
+  const bufferLimit = args?.bufferLimit ?? 10_000;
+  let emit: EmitEntityChanged | undefined;
+  const buffer: EntityChanged[] = [];
+
+  return {
+    get isWired() {
+      return emit !== undefined;
+    },
+
+    async emit(payload) {
+      if (emit) {
+        await emit(payload);
+        return;
+      }
+      if (buffer.length >= bufferLimit) {
+        logger?.warn(
+          `entity change buffer full (${bufferLimit}); dropping the oldest buffered ${payload.kind}:${payload.id} change event`,
+        );
+        buffer.shift();
+      }
+      buffer.push(payload);
+    },
+
+    async wire(realEmit) {
+      emit = realEmit;
+      if (buffer.length > 0) {
+        logger?.debug(
+          `flushing ${buffer.length} buffered entity change event(s) on emitter wire`,
+        );
+      }
+      // Drain in arrival order; clearing as we go so a re-entrant emit
+      // (an emitter that itself mutates an entity) appends, not duplicates.
+      while (buffer.length > 0) {
+        const next = buffer.shift();
+        if (next) await realEmit(next);
+      }
+    },
+  };
+}