@checkstack/automation-backend 0.2.0 → 0.3.0

package/src/dispatch/state-scope.test.ts

@@ -0,0 +1,234 @@
+import { describe, it, expect } from "bun:test";
+import type { Logger } from "@checkstack/backend-api";
+import {
+  enrichScopeWithState,
+  MAX_RESOLVED_SYSTEMS,
+  type ScopeHealthNamespace,
+} from "./state-scope";
+
+const noopLogger = {
+  debug: () => {},
+  info: () => {},
+  warn: () => {},
+  error: () => {},
+} as unknown as Logger;
+
+function collectingLogger(): { logger: Logger; warnings: string[] } {
+  const warnings: string[] = [];
+  const logger = {
+    debug: () => {},
+    info: () => {},
+    warn: (msg: string) => warnings.push(msg),
+    error: () => {},
+  } as unknown as Logger;
+  return { logger, warnings };
+}
+
+function makeState(over: Record<string, unknown> = {}) {
+  return {
+    status: "unhealthy",
+    inStatusSince: new Date("2026-05-30T11:00:00.000Z"),
+    inStatusForMs: 3_600_000,
+    latencyMs: 42,
+    avgLatencyMs: 50,
+    p95LatencyMs: 120,
+    successRate: 0.9,
+    lastRunAt: new Date("2026-05-30T11:59:00.000Z"),
+    inMaintenance: false,
+    transitionsInWindow: 0,
+    transitionWindowMinutes: 60,
+    evaluatedAt: new Date("2026-05-30T12:00:00.000Z"),
+    ...over,
+  };
+}
+
+/** Minimal mock health client recording the systemIds it was asked for. */
+function makeClient(
+  states: Record<string, ReturnType<typeof makeState>>,
+  opts?: { throws?: boolean },
+) {
+  const calls: string[][] = [];
+  const windows: Array<number | undefined> = [];
+  return {
+    calls,
+    windows,
+    client: {
+      getBulkHealthState: async ({
+        systemIds,
+        transitionWindowMinutes,
+      }: {
+        systemIds: string[];
+        transitionWindowMinutes?: number;
+      }) => {
+        calls.push(systemIds);
+        windows.push(transitionWindowMinutes);
+        if (opts?.throws) throw new Error("provider down");
+        const out: Record<string, unknown> = {};
+        for (const id of systemIds) if (states[id]) out[id] = states[id];
+        return { states: out };
+      },
+    } as never,
+  };
+}
+
+function getHealth(scope: Record<string, unknown>): ScopeHealthNamespace {
+  return scope.health as ScopeHealthNamespace;
+}
+
+describe("enrichScopeWithState", () => {
+  it("folds the context system under health.system and health.systems[id]", async () => {
+    const { client, calls } = makeClient({ "sys-1": makeState() });
+    const scope: Record<string, unknown> = {};
+    await enrichScopeWithState({
+      scope,
+      client,
+      logger: noopLogger,
+      contextKey: "sys-1",
+    });
+    expect(calls).toEqual([["sys-1"]]);
+    const health = getHealth(scope);
+    expect(health.system?.status).toBe("unhealthy");
+    expect(health.system?.in_status_for_ms).toBe(3_600_000);
+    expect(health.systems["sys-1"]?.status).toBe("unhealthy");
+  });
+
+  it("folds the windowed transition count + window minutes and forwards the window", async () => {
+    const { client, windows } = makeClient({
+      "sys-1": makeState({ transitionsInWindow: 5, transitionWindowMinutes: 90 }),
+    });
+    const scope: Record<string, unknown> = {};
+    await enrichScopeWithState({
+      scope,
+      client,
+      logger: noopLogger,
+      contextKey: "sys-1",
+      transitionWindowMinutes: 90,
+    });
+    const health = getHealth(scope);
+    expect(health.system?.transitions_in_window).toBe(5);
+    expect(health.system?.transition_window_minutes).toBe(90);
+    // the per-automation window is forwarded to the provider
+    expect(windows).toEqual([90]);
+  });
+
+  it("converts Date fields to ISO strings (for duration filters)", async () => {
+    const { client } = makeClient({ "sys-1": makeState() });
+    const scope: Record<string, unknown> = {};
+    await enrichScopeWithState({
+      scope,
+      client,
+      logger: noopLogger,
+      contextKey: "sys-1",
+    });
+    const health = getHealth(scope);
+    expect(health.system?.in_status_since).toBe("2026-05-30T11:00:00.000Z");
+    expect(health.system?.last_run_at).toBe("2026-05-30T11:59:00.000Z");
+    expect(health.system?.evaluated_at).toBe("2026-05-30T12:00:00.000Z");
+  });
+
+  it("preserves null inStatusSince as null", async () => {
+    const { client } = makeClient({
+      "sys-1": makeState({ inStatusSince: null }),
+    });
+    const scope: Record<string, unknown> = {};
+    await enrichScopeWithState({
+      scope,
+      client,
+      logger: noopLogger,
+      contextKey: "sys-1",
+    });
+    expect(getHealth(scope).system?.in_status_since).toBeNull();
+  });
+
+  it("resolves uses_state ids in addition to the context system, de-duped", async () => {
+    const { client, calls } = makeClient({
+      "sys-1": makeState(),
+      "sys-2": makeState({ status: "degraded" }),
+    });
+    const scope: Record<string, unknown> = {};
+    await enrichScopeWithState({
+      scope,
+      client,
+      logger: noopLogger,
+      contextKey: "sys-1",
+      usesState: ["sys-2", "sys-1"], // sys-1 duplicate dropped
+    });
+    expect(calls).toEqual([["sys-1", "sys-2"]]);
+    const health = getHealth(scope);
+    expect(health.systems["sys-2"]?.status).toBe("degraded");
+    // system still points at the context system
+    expect(health.system?.status).toBe("unhealthy");
+  });
+
+  it("exposes an empty namespace when there is no context key and no uses_state", async () => {
+    const { client, calls } = makeClient({});
+    const scope: Record<string, unknown> = {};
+    await enrichScopeWithState({
+      scope,
+      client,
+      logger: noopLogger,
+      contextKey: null,
+    });
+    expect(calls).toEqual([]); // no query issued
+    expect(getHealth(scope)).toEqual({ systems: {} });
+  });
+
+  it("exposes an empty namespace when no client is wired (fail-open)", async () => {
+    const scope: Record<string, unknown> = {};
+    await enrichScopeWithState({
+      scope,
+      client: undefined,
+      logger: noopLogger,
+      contextKey: "sys-1",
+    });
+    expect(getHealth(scope)).toEqual({ systems: {} });
+  });
+
+  it("fails open to an empty namespace and warns on provider error", async () => {
+    const { client } = makeClient({}, { throws: true });
+    const { logger, warnings } = collectingLogger();
+    const scope: Record<string, unknown> = {};
+    await enrichScopeWithState({
+      scope,
+      client,
+      logger,
+      contextKey: "sys-1",
+    });
+    expect(getHealth(scope)).toEqual({ systems: {} });
+    expect(warnings.some((w) => w.includes("failed to resolve"))).toBe(true);
+  });
+
+  it("caps the resolved set and warns when over the limit", async () => {
+    const big = Array.from(
+      { length: MAX_RESOLVED_SYSTEMS + 5 },
+      (_, i) => `sys-${i}`,
+    );
+    const { client, calls } = makeClient({});
+    const { logger, warnings } = collectingLogger();
+    const scope: Record<string, unknown> = {};
+    await enrichScopeWithState({
+      scope,
+      client,
+      logger,
+      contextKey: big[0]!,
+      usesState: big.slice(1),
+    });
+    expect(calls[0]?.length).toBe(MAX_RESOLVED_SYSTEMS);
+    expect(warnings.some((w) => w.includes("cap reached"))).toBe(true);
+  });
+
+  it("leaves health.system undefined when the context system has no state", async () => {
+    // client returns nothing for the requested id
+    const { client } = makeClient({});
+    const scope: Record<string, unknown> = {};
+    await enrichScopeWithState({
+      scope,
+      client,
+      logger: noopLogger,
+      contextKey: "sys-1",
+    });
+    const health = getHealth(scope);
+    expect(health.system).toBeUndefined();
+    expect(health.systems).toEqual({});
+  });
+});

package/src/dispatch/state-scope.ts

@@ -0,0 +1,322 @@
+/**
+ * Live-state pre-resolution for the sensing layer (Wave 2 Phase 14).
+ *
+ * The template engine is strictly synchronous and has no call syntax, so
+ * a template can never query the database inline. Instead, live health
+ * state is resolved up front (one batched query per evaluation) and
+ * folded into the scope under a `health` namespace, then read as plain
+ * data: `{{ health.system.status }}`, `{{ health.system.in_status_since }}`.
+ *
+ * This mirrors `resolveConsumedArtifacts` (which awaits the artifact
+ * store and folds the result into scope before an action runs) and HA's
+ * approach of resolving trigger entities up front rather than lazily.
+ *
+ * Resolution policy (decision D2): implicitly resolve the system named by
+ * the trigger's `contextKey`, plus any ids listed in the automation's
+ * `uses_state` escape hatch. The resolved set is bounded; truncation is
+ * logged, never silent.
+ */
+import type { Logger } from "@checkstack/backend-api";
+import type { InferClient } from "@checkstack/common";
+import type { HealthCheckApi } from "@checkstack/healthcheck-common";
+
+type HealthCheckClient = InferClient<typeof HealthCheckApi>;
+
+/**
+ * Hard cap on systems resolved per evaluation. `uses_state` is already
+ * schema-capped at 50; this is the runtime backstop including the
+ * implicit context system.
+ */
+export const MAX_RESOLVED_SYSTEMS = 50;
+
+/** snake_case state shape exposed to templates under `health.*`. */
+export interface ScopeHealthState {
+  status: string;
+  in_status_since: string | null;
+  in_status_for_ms: number;
+  latency_ms?: number;
+  avg_latency_ms?: number;
+  p95_latency_ms?: number;
+  success_rate?: number;
+  last_run_at?: string;
+  in_maintenance: boolean;
+  /** Status changes in the trailing window (generalized flapping). */
+  transitions_in_window: number;
+  /** The window (minutes) `transitions_in_window` was counted over. */
+  transition_window_minutes: number;
+  evaluated_at: string;
+}
+
+/** The `health` namespace folded into scope. */
+export interface ScopeHealthNamespace {
+  /** State of the system named by the trigger's contextKey, if resolvable. */
+  system?: ScopeHealthState;
+  /** State of every resolved system, keyed by system id. */
+  systems: Record<string, ScopeHealthState>;
+}
+
+/**
+ * Map a wire `HealthStateResponse` (Date fields, camelCase) into the
+ * snake_case, ISO-string shape templates read. ISO strings (not Date
+ * objects) so the duration filters (`older_than`, `duration_since`)
+ * receive parseable values and snapshots serialise cleanly.
+ */
+function toScopeState(state: {
+  status: string;
+  inStatusSince: Date | string | null;
+  inStatusForMs: number;
+  latencyMs?: number;
+  avgLatencyMs?: number;
+  p95LatencyMs?: number;
+  successRate?: number;
+  lastRunAt?: Date | string;
+  inMaintenance: boolean;
+  transitionsInWindow: number;
+  transitionWindowMinutes: number;
+  evaluatedAt: Date | string;
+}): ScopeHealthState {
+  const iso = (v: Date | string | null | undefined): string | undefined => {
+    if (v == null) return undefined;
+    return v instanceof Date ? v.toISOString() : v;
+  };
+  return {
+    status: state.status,
+    in_status_since: iso(state.inStatusSince) ?? null,
+    in_status_for_ms: state.inStatusForMs,
+    latency_ms: state.latencyMs,
+    avg_latency_ms: state.avgLatencyMs,
+    p95_latency_ms: state.p95LatencyMs,
+    success_rate: state.successRate,
+    last_run_at: iso(state.lastRunAt),
+    in_maintenance: state.inMaintenance,
+    transitions_in_window: state.transitionsInWindow,
+    transition_window_minutes: state.transitionWindowMinutes,
+    evaluated_at: iso(state.evaluatedAt) ?? new Date().toISOString(),
+  };
+}
+
+export interface EnrichScopeArgs {
+  /** The mutable scope to fold `health` into. Returned for convenience. */
+  scope: Record<string, unknown>;
+  client: HealthCheckClient | undefined;
+  logger: Logger;
+  /** Resolved trigger context key — treated as the implicit system id. */
+  contextKey: string | null;
+  /** Extra system ids from the automation's `uses_state` escape hatch. */
+  usesState?: ReadonlyArray<string>;
+  /**
+   * Trailing window (minutes) for the folded `transitions_in_window`
+   * count (the automation's `state_window_minutes`). Provider default
+   * (60) applies when omitted.
+   */
+  transitionWindowMinutes?: number;
+}
+
+/**
+ * Resolve live health state for the implicit context system + any
+ * `uses_state` ids and fold it into `scope.health`. One batched
+ * `getBulkHealthState` call. Fail-open: a missing client or a provider
+ * error yields an empty `health` namespace and a warn-log — a
+ * healthcheck outage never wedges unrelated automations.
+ */
+export async function enrichScopeWithState(
+  args: EnrichScopeArgs,
+): Promise<Record<string, unknown>> {
+  const { scope, client, logger, contextKey, usesState, transitionWindowMinutes } =
+    args;
+
+  // Build the bounded, de-duplicated id set: implicit context system first.
+  const ids: string[] = [];
+  const seen = new Set<string>();
+  const add = (id: string) => {
+    if (id.length === 0 || seen.has(id)) return;
+    seen.add(id);
+    ids.push(id);
+  };
+  if (contextKey) add(contextKey);
+  for (const id of usesState ?? []) add(id);
+
+  // Nothing to resolve, or no client wired — still expose an empty
+  // namespace so templates referencing `health.systems` don't throw.
+  const emptyNamespace: ScopeHealthNamespace = { systems: {} };
+  if (ids.length === 0 || !client) {
+    scope.health = emptyNamespace;
+    return scope;
+  }
+
+  let resolveIds = ids;
+  if (ids.length > MAX_RESOLVED_SYSTEMS) {
+    logger.warn(
+      `enrichScopeWithState: resolving only the first ${MAX_RESOLVED_SYSTEMS} of ${ids.length} requested systems (cap reached)`,
+    );
+    resolveIds = ids.slice(0, MAX_RESOLVED_SYSTEMS);
+  }
+
+  try {
+    const { states } = await client.getBulkHealthState({
+      systemIds: resolveIds,
+      transitionWindowMinutes,
+    });
+    const systems: Record<string, ScopeHealthState> = {};
+    for (const [id, state] of Object.entries(states)) {
+      systems[id] = toScopeState(state);
+    }
+    const namespace: ScopeHealthNamespace = {
+      systems,
+      system: contextKey ? systems[contextKey] : undefined,
+    };
+    scope.health = namespace;
+    return scope;
+  } catch (error) {
+    logger.warn(
+      `enrichScopeWithState: failed to resolve health state; falling back to empty namespace: ${
+        (error as Error).message
+      }`,
+    );
+    scope.health = emptyNamespace;
+    return scope;
+  }
+}
+
+// ─── Generic entity scope enrichment (reactive automation engine §3.6) ──────
+//
+// Two complementary projections of live state coexist by design, not as a
+// migration shim:
+//
+//   - `scope.health.*` (rich condition snapshot) — populated by
+//     `enrichScopeWithState` above. It carries the FULL health aggregate
+//     (status, latency_ms, p95_latency_ms, success_rate, in_status_since,
+//     in_status_for_ms, in_maintenance, transitions_in_window, …) that the
+//     structured `state` / `numeric_state` condition evaluators read. The
+//     health aggregate is not stored as a framework entity row, so it is
+//     resolved through the healthcheck RPC, not the entity store.
+//
+//   - `scope.state.<kind>.<id>.<field>` (minimal reactive entity view) —
+//     populated here. It carries the small reactive subset each kind's
+//     `defineEntity` exposes through its plugin `read` accessor (e.g. an
+//     incident's `{ status, severity }`, or health's
+//     `{ status, healthyChecks, totalChecks }`). This is what the reactive
+//     `wait_until` wake re-eval resolves so a wait on any entity kind sees
+//     current state after a change.
+//
+// The two are kept strictly separate: this generic path folds ONLY
+// `scope.state.<kind>.<id>` and never writes `scope.health`. The wait
+// re-eval (`reEnrichWaitScope`) resolves health via the RICH RPC path and
+// EXCLUDES the `health` kind from the refs it passes here, so health is
+// resolved at most once per scope build and conditions always read the rich
+// `scope.health` snapshot.
+
+/** A `{kind, id}` entity reference to pre-resolve into scope. */
+export interface EntityRef {
+  kind: string;
+  id: string;
+}
+
+/**
+ * Batched, per-kind resolver — `getMany(ids)` for a single kind, mirroring
+ * `getBulkHealthState`. Missing ids are simply absent from the result.
+ */
+export type EntityKindResolver = (
+  ids: ReadonlyArray<string>,
+) => Promise<Record<string, Record<string, unknown>>>;
+
+export interface EnrichScopeWithEntitiesArgs {
+  /** The mutable scope to fold `state.<kind>.<id>` into. Returned for convenience. */
+  scope: Record<string, unknown>;
+  logger: Logger;
+  /** The refs to resolve (deduped + bounded internally). */
+  refs: ReadonlyArray<EntityRef>;
+  /** Resolve a `getMany` resolver for a kind, or undefined if unknown. */
+  resolverFor: (kind: string) => EntityKindResolver | undefined;
+}
+
+/** Read the `state` namespace off scope, creating it if absent. */
+function stateNamespace(
+  scope: Record<string, unknown>,
+): Record<string, Record<string, Record<string, unknown>>> {
+  const existing = scope.state;
+  if (
+    typeof existing === "object" &&
+    existing !== null &&
+    !Array.isArray(existing)
+  ) {
+    return existing as Record<
+      string,
+      Record<string, Record<string, unknown>>
+    >;
+  }
+  const fresh: Record<string, Record<string, Record<string, unknown>>> = {};
+  scope.state = fresh;
+  return fresh;
+}
+
+/**
+ * Resolve the given entity refs through their per-kind resolvers and fold
+ * them into `scope.state.<kind>.<id>`. Refs are de-duplicated per kind and
+ * the total resolved set is bounded by {@link MAX_RESOLVED_SYSTEMS} (the
+ * runtime backstop). A kind with no resolver, or a resolver error, is
+ * fail-open: the kind is left absent and a warn is logged — one kind's
+ * outage never wedges unrelated automations.
+ *
+ * This folds ONLY `scope.state.<kind>.<id>`. The rich `scope.health.*`
+ * condition snapshot is owned exclusively by `enrichScopeWithState` (the
+ * health aggregate is computed on read via the healthcheck RPC, not stored
+ * as a framework entity row), so this generic path never touches it.
+ */
+export async function enrichScopeWithEntities(
+  args: EnrichScopeWithEntitiesArgs,
+): Promise<Record<string, unknown>> {
+  const { scope, logger, refs, resolverFor } = args;
+  const state = stateNamespace(scope);
+
+  // Group de-duplicated ids per kind, bounded overall.
+  const byKind = new Map<string, string[]>();
+  const seen = new Set<string>();
+  let total = 0;
+  let capped = false;
+  for (const { kind, id } of refs) {
+    if (kind.length === 0 || id.length === 0) continue;
+    const key = `${kind}:${id}`;
+    if (seen.has(key)) continue;
+    if (total >= MAX_RESOLVED_SYSTEMS) {
+      capped = true;
+      break;
+    }
+    seen.add(key);
+    total += 1;
+    const ids = byKind.get(kind);
+    if (ids) ids.push(id);
+    else byKind.set(kind, [id]);
+  }
+  if (capped) {
+    logger.warn(
+      `enrichScopeWithEntities: resolving only the first ${MAX_RESOLVED_SYSTEMS} refs (cap reached)`,
+    );
+  }
+
+  for (const [kind, ids] of byKind) {
+    const resolver = resolverFor(kind);
+    if (!resolver) {
+      logger.warn(
+        `enrichScopeWithEntities: no resolver for kind "${kind}"; leaving it unresolved`,
+      );
+      continue;
+    }
+    try {
+      const resolved = await resolver(ids);
+      const kindBucket = state[kind] ?? {};
+      for (const [id, entityState] of Object.entries(resolved)) {
+        kindBucket[id] = entityState;
+      }
+      state[kind] = kindBucket;
+    } catch (error) {
+      logger.warn(
+        `enrichScopeWithEntities: failed to resolve kind "${kind}": ${
+          (error as Error).message
+        }`,
+      );
+    }
+  }
+
+  return scope;
+}