@checkstack/automation-backend 0.2.0 → 0.3.0

package/src/entity/registry.ts

@@ -0,0 +1,200 @@
+/**
+ * The entity registry — the runtime behind the `automation.entity`
+ * extension point. It produces `defineEntity` (and its sibling
+ * `declareNonReactiveState`), enforces the load-time validation rules
+ * (§6.3), tracks declarable expression indexes for init-time creation, and
+ * records escape-hatch declarations for the (later-phase) lint rule.
+ *
+ * Model B: `defineEntity` owns no current-state storage. Every kind declares
+ * a plugin `read` accessor pointing at wherever its state lives (its own
+ * table, an in-memory map, or a computed value).
+ *
+ * One registry instance per automation-backend process. `defineEntity` is
+ * callable from another plugin's `register`/`init` (Proxy-buffered until the
+ * impl registers), so the registry tolerates being driven before the DB is
+ * resolved: handles capture a lazily-set transition store via an indirection,
+ * and change events buffer via the emitter (see `change-emitter.ts`). The
+ * store/db are bound once at init.
+ */
+import { z } from "zod";
+
+import type {
+  DeclareNonReactiveStateInput,
+  DefineEntity,
+  DefineEntityInput,
+  EntityHandle,
+  EntityRead,
+} from "./define-entity";
+import type { EntityStore } from "./entity-store";
+import { createEntityHandle } from "./create-handle";
+import type { ChangeEmitter } from "./change-emitter";
+import type { RunSecretRegistry } from "../dispatch/run-secret-registry";
+
+/** A registered escape-hatch declaration (for the lint rule, later phase). */
+export type NonReactiveDeclaration = DeclareNonReactiveStateInput;
+
+/** A batched per-kind read resolver: `getMany(ids)` for one kind. */
+export type EntityKindResolver = (
+  ids: ReadonlyArray<string>,
+) => Promise<Record<string, Record<string, unknown>>>;
+
+export interface EntityRegistry {
+  /** The `defineEntity` impl exposed on the extension point. */
+  readonly defineEntity: DefineEntity;
+  /** The `declareNonReactiveState` impl exposed on the extension point. */
+  declareNonReactiveState(input: DeclareNonReactiveStateInput): void;
+
+  /**
+   * Bind the DB-backed transition store once init has resolved the database.
+   * The transition store owns the tx + transition log for every kind.
+   */
+  setStore(args: { store: EntityStore }): void;
+  /** Whether a store has been bound yet. */
+  readonly hasStore: boolean;
+
+  /** Every recorded escape-hatch declaration (for the lint rule). */
+  getNonReactiveDeclarations(): ReadonlyArray<NonReactiveDeclaration>;
+  /** Registered entity kinds, in registration order. */
+  getKinds(): ReadonlyArray<string>;
+  /**
+   * The kind-agnostic read resolver behind the reactive `wait_until` wake
+   * re-eval + scope enrichment (reactive automation engine §3.6, §8): routes
+   * each kind to its plugin `read` accessor. Returns `undefined` for an
+   * unknown kind (enrichment leaves it unresolved, fail-open).
+   */
+  entityResolverFor(kind: string): EntityKindResolver | undefined;
+}
+
+/** Hard-fail validation for a malformed registration (§6.3). */
+function validateInput<TState extends Record<string, unknown>>(args: {
+  input: DefineEntityInput<TState>;
+  registeredKinds: ReadonlySet<string>;
+}): void {
+  const { input, registeredKinds } = args;
+  const { kind, state, read } = input;
+
+  if (typeof kind !== "string" || kind.trim().length === 0) {
+    throw new Error("defineEntity: `kind` must be a non-empty string");
+  }
+  if (registeredKinds.has(kind)) {
+    throw new Error(
+      `defineEntity: duplicate kind "${kind}" — entity kinds must be globally unique`,
+    );
+  }
+  // Model B: every kind owns its state and exposes it through a plugin `read`
+  // accessor.
+  if (typeof read !== "function") {
+    throw new TypeError(
+      `defineEntity: kind "${kind}" — \`read\` must be a function`,
+    );
+  }
+  // The state schema MUST be a z.object: scope projection, UI introspection,
+  // and per-field transitions all rely on enumerable top-level fields. The
+  // static type says `state` is a ZodObject, but callers reaching us through
+  // the extension point are untyped, so this guard is a real runtime check —
+  // read through `unknown` since TS narrows the failing branch to `never`.
+  if (!(state instanceof z.ZodObject)) {
+    const received: unknown = state;
+    const describe =
+      received == null
+        ? String(received)
+        : ((received as { constructor?: { name?: string } }).constructor
+            ?.name ?? typeof received);
+    throw new Error(
+      `defineEntity: kind "${kind}" — \`state\` must be a z.object (got ${describe})`,
+    );
+  }
+}
+
+export function createEntityRegistry(args: {
+  secretRegistry: RunSecretRegistry;
+  emitter: ChangeEmitter;
+}): EntityRegistry {
+  const { secretRegistry, emitter } = args;
+
+  const registeredKinds = new Set<string>();
+  const kindsInOrder: string[] = [];
+  const nonReactive: NonReactiveDeclaration[] = [];
+  // Per-kind plugin `read` accessor. Backs `entityResolverFor`.
+  const reads = new Map<string, EntityKindResolver>();
+
+  // The transition store is bound lazily at init. Handles created during
+  // `register` capture this mutable indirection so a mutation issued before
+  // init throws a clear error rather than a cryptic
+  // "undefined.runInTransaction" (mutations realistically only happen from
+  // `init` onward, by which point the store is bound).
+  let store: EntityStore | undefined;
+
+  function requireStore(): EntityStore {
+    if (!store) {
+      throw new Error(
+        "entity store not initialized yet — defineEntity handles can only mutate from init() onward",
+      );
+    }
+    return store;
+  }
+  const storeProxy: EntityStore = {
+    runInTransaction: (fn) => requireStore().runInTransaction(fn),
+    appendTransitions: (a) => requireStore().appendTransitions(a),
+    inStateSince: (a) => requireStore().inStateSince(a),
+    transitionCount: (a) => requireStore().transitionCount(a),
+  };
+
+  const defineEntity: DefineEntity = <
+    TState extends Record<string, unknown>,
+  >(
+    input: DefineEntityInput<TState>,
+  ): EntityHandle<TState> => {
+    validateInput({ input, registeredKinds });
+
+    registeredKinds.add(input.kind);
+    kindsInOrder.push(input.kind);
+
+    // Every kind exposes its current state through a plugin `read` accessor
+    // (its own table, an in-memory map, or a computed value). `defineEntity`
+    // owns no current-state storage.
+    const read: EntityRead<TState> = input.read;
+
+    // Register the read accessor so `entityResolverFor` can route scope
+    // enrichment + wake re-eval to it (cast: the resolver is untyped record).
+    reads.set(input.kind, (ids) =>
+      read(ids) as Promise<Record<string, Record<string, unknown>>>,
+    );
+
+    return createEntityHandle<TState>({
+      kind: input.kind,
+      schema: input.state,
+      store: storeProxy,
+      emitter,
+      secretRegistry,
+      read,
+    });
+  };
+
+  return {
+    defineEntity,
+
+    declareNonReactiveState(input) {
+      nonReactive.push({ ...input });
+    },
+
+    setStore({ store: nextStore }) {
+      store = nextStore;
+    },
+    get hasStore() {
+      return store !== undefined;
+    },
+
+    getNonReactiveDeclarations() {
+      return nonReactive;
+    },
+    getKinds() {
+      return kindsInOrder;
+    },
+
+    entityResolverFor(kind) {
+      // Plugin-backed kinds resolve through their own `read` immediately.
+      return reads.get(kind);
+    },
+  };
+}

package/src/entity/stable-stringify.test.ts

@@ -0,0 +1,55 @@
+import { describe, it, expect } from "bun:test";
+import { stableStringify, structurallyEqual } from "./stable-stringify";
+
+describe("stableStringify", () => {
+  it("is key-order independent", () => {
+    expect(stableStringify({ a: 1, b: 2 })).toBe(
+      stableStringify({ b: 2, a: 1 }),
+    );
+  });
+
+  it("treats undefined as absent (matches JSON semantics)", () => {
+    expect(stableStringify({ a: 1, b: undefined })).toBe(
+      stableStringify({ a: 1 }),
+    );
+  });
+
+  it("serializes nested objects deterministically", () => {
+    const a = { outer: { z: 1, a: 2 }, list: [3, { y: 1, x: 2 }] };
+    const b = { list: [3, { x: 2, y: 1 }], outer: { a: 2, z: 1 } };
+    expect(stableStringify(a)).toBe(stableStringify(b));
+  });
+
+  it("distinguishes different values", () => {
+    expect(stableStringify({ a: 1 })).not.toBe(stableStringify({ a: 2 }));
+  });
+
+  it("distinguishes array order (arrays are ordered)", () => {
+    expect(stableStringify([1, 2])).not.toBe(stableStringify([2, 1]));
+  });
+
+  it("normalizes non-finite numbers to null", () => {
+    expect(stableStringify({ a: Number.NaN })).toBe(stableStringify({ a: null }));
+    expect(stableStringify({ a: Infinity })).toBe(stableStringify({ a: null }));
+  });
+
+  it("treats an explicit-null field as distinct from an absent field", () => {
+    // `{a: null}` is `{"a":null}`; `{a: undefined}` drops the key entirely,
+    // so they are NOT structurally equal — a field explicitly set to null
+    // is a real value, whereas undefined means absent.
+    expect(structurallyEqual({ a: null }, { a: undefined })).toBe(false);
+    expect(structurallyEqual({ a: undefined }, {})).toBe(true);
+  });
+});
+
+describe("structurallyEqual", () => {
+  it("returns true for structurally equal objects with different key order", () => {
+    expect(structurallyEqual({ a: 1, b: { c: 2 } }, { b: { c: 2 }, a: 1 })).toBe(
+      true,
+    );
+  });
+
+  it("returns false on a real difference", () => {
+    expect(structurallyEqual({ a: 1 }, { a: 1, b: 2 })).toBe(false);
+  });
+});

package/src/entity/stable-stringify.ts

@@ -0,0 +1,49 @@
+/**
+ * Deterministic JSON stringify for structural equality.
+ *
+ * The entity store diffs a freshly-validated state object against the
+ * prior persisted row. A naive `JSON.stringify` is key-order-sensitive,
+ * so two structurally-equal objects with differently-ordered keys would
+ * read as a "change". This walker emits object keys in sorted order so
+ * the serialization is canonical: equal values ⇒ equal strings.
+ *
+ * `undefined` is treated as absent (matching JSON.stringify): an explicit
+ * `undefined` property and a missing property serialize identically, so a
+ * `set` that drops an optional field to `undefined` no-ops against a prior
+ * row that never had it.
+ */
+export function stableStringify(value: unknown): string {
+  return serialize(value);
+}
+
+function serialize(value: unknown): string {
+  if (value === null) return "null";
+  if (value === undefined) return "null";
+  const type = typeof value;
+  if (type === "number") {
+    return Number.isFinite(value) ? String(value) : "null";
+  }
+  if (type === "boolean") return value ? "true" : "false";
+  if (type === "string") return JSON.stringify(value);
+  if (type === "bigint") return JSON.stringify((value as bigint).toString());
+  if (Array.isArray(value)) {
+    return `[${value.map((v) => serialize(v)).join(",")}]`;
+  }
+  if (type === "object") {
+    const obj = value as Record<string, unknown>;
+    const keys = Object.keys(obj)
+      .filter((k) => obj[k] !== undefined)
+      .toSorted();
+    const body = keys
+      .map((k) => `${JSON.stringify(k)}:${serialize(obj[k])}`)
+      .join(",");
+    return `{${body}}`;
+  }
+  // Functions / symbols cannot appear in zod-parsed state; coerce to null.
+  return "null";
+}
+
+/** Structural equality via canonical serialization. */
+export function structurallyEqual(a: unknown, b: unknown): boolean {
+  return stableStringify(a) === stableStringify(b);
+}

package/src/entity/wake-index.it.test.ts

@@ -0,0 +1,251 @@
+/**
+ * Integration test (real Postgres) for the wake-index arm race + lookup.
+ *
+ * Part of the surgical integration lane (plan §14.4 #3). It pins the two
+ * behaviours fakes cannot model against real Postgres:
+ *
+ *   1. The `(wait_lock_id, ref)` UNIQUE index + `ON CONFLICT DO NOTHING`
+ *      arm: concurrent inserts of the SAME pair must leave EXACTLY ONE row
+ *      (the arm race must not double-insert).
+ *   2. The key-intersection lookup join (§8.2) returns the owning
+ *      `kind: "until"` wait lock for a changed `kind:id` ref, including the
+ *      kind-level wildcard.
+ *
+ * Gated behind `CHECKSTACK_IT=1` so the default `bun test` never runs it. The
+ * `integration` CI job sets the flag and provides a real Postgres service.
+ * Connection comes from `CHECKSTACK_IT_PG_URL` (defaulting to the
+ * `docker-compose-dev.yml` Postgres port). Each run isolates itself in a
+ * freshly created Postgres schema and cleans up after itself.
+ */
+import { afterAll, beforeAll, describe, expect, it } from "bun:test";
+import { drizzle } from "drizzle-orm/node-postgres";
+import { and, eq } from "drizzle-orm";
+import { Pool } from "pg";
+
+import {
+  automationRunState,
+  automationRunSteps,
+  automationRuns,
+  automationWaitLocks,
+  automationWakeIndex,
+} from "../schema";
+import { createRunStore } from "../dispatch/run-state";
+
+const PG_URL =
+  process.env.CHECKSTACK_IT_PG_URL ??
+  "postgres://postgres:postgres@localhost:5432/postgres";
+
+const SCHEMA = `it_wake_${crypto.randomUUID().replace(/-/g, "")}`;
+
+describe.skipIf(!process.env.CHECKSTACK_IT)(
+  "wake-index arm race + intersection lookup (real Postgres)",
+  () => {
+    let pool: Pool;
+
+    beforeAll(async () => {
+      const setupPool = new Pool({ connectionString: PG_URL });
+      try {
+        await setupPool.query(`CREATE SCHEMA IF NOT EXISTS "${SCHEMA}"`);
+        await setupPool.query(`SET search_path TO "${SCHEMA}"`);
+        await setupPool.query(`
+          CREATE TABLE "${SCHEMA}".automations (
+            id text PRIMARY KEY,
+            name text NOT NULL,
+            status text NOT NULL DEFAULT 'enabled',
+            definition jsonb NOT NULL,
+            created_at timestamp NOT NULL DEFAULT now(),
+            updated_at timestamp NOT NULL DEFAULT now()
+          )
+        `);
+        await setupPool.query(`
+          CREATE TABLE "${SCHEMA}".automation_runs (
+            id text PRIMARY KEY,
+            automation_id text NOT NULL,
+            trigger_id text NOT NULL,
+            trigger_event_id text NOT NULL,
+            trigger_payload jsonb NOT NULL,
+            context_key text,
+            status text NOT NULL DEFAULT 'running',
+            error_message text,
+            started_at timestamp NOT NULL DEFAULT now(),
+            finished_at timestamp
+          )
+        `);
+        await setupPool.query(`
+          CREATE TABLE "${SCHEMA}".automation_wait_locks (
+            id text PRIMARY KEY,
+            run_id text NOT NULL
+              REFERENCES "${SCHEMA}".automation_runs(id) ON DELETE CASCADE,
+            action_path text NOT NULL,
+            kind text NOT NULL DEFAULT 'trigger',
+            event_id text NOT NULL,
+            context_key text,
+            filter_template text,
+            wait_config jsonb,
+            timeout_at timestamp,
+            created_at timestamp NOT NULL DEFAULT now()
+          )
+        `);
+        await setupPool.query(`
+          CREATE TABLE "${SCHEMA}".automation_wake_index (
+            id text PRIMARY KEY,
+            wait_lock_id text NOT NULL
+              REFERENCES "${SCHEMA}".automation_wait_locks(id) ON DELETE CASCADE,
+            ref text NOT NULL
+          )
+        `);
+        await setupPool.query(`
+          CREATE UNIQUE INDEX automation_wake_index_lock_ref_unique
+            ON "${SCHEMA}".automation_wake_index (wait_lock_id, ref)
+        `);
+        await setupPool.query(`
+          CREATE INDEX automation_wake_index_ref_idx
+            ON "${SCHEMA}".automation_wake_index (ref)
+        `);
+      } finally {
+        await setupPool.end();
+      }
+
+      pool = new Pool({
+        connectionString: PG_URL,
+        options: `-c search_path=${SCHEMA}`,
+      });
+    });
+
+    afterAll(async () => {
+      await pool.end();
+      const cleanupPool = new Pool({ connectionString: PG_URL });
+      try {
+        await cleanupPool.query(`DROP SCHEMA IF EXISTS "${SCHEMA}" CASCADE`);
+      } finally {
+        await cleanupPool.end();
+      }
+    });
+
+    function makeStore() {
+      const db = drizzle({
+        client: pool,
+        schema: {
+          automationRuns,
+          automationRunSteps,
+          automationWaitLocks,
+          automationRunState,
+          automationWakeIndex,
+        },
+      });
+      return createRunStore(db);
+    }
+
+    async function seedRun(): Promise<string> {
+      const automationId = crypto.randomUUID();
+      await pool.query(
+        `INSERT INTO "${SCHEMA}".automations (id, name, definition)
+           VALUES ($1, $2, $3)`,
+        [automationId, "IT wake automation", JSON.stringify({})],
+      );
+      const store = makeStore();
+      return store.createRun({
+        automationId,
+        triggerId: "t",
+        triggerEventId: "test.event",
+        triggerPayload: {},
+        contextKey: "sys-1",
+      });
+    }
+
+    it("intersection lookup returns the owning until-lock for a concrete ref", async () => {
+      const store = makeStore();
+      const runId = await seedRun();
+      await store.createWaitLockWithWakeRefs({
+        runId,
+        actionPath: "actions[0]",
+        eventId: "@@until",
+        contextKey: "sys-1",
+        timeoutAt: null,
+        waitConfig: {
+          condition: "state.health['sys-1'].status == 'healthy'",
+          continueOnTimeout: true,
+        },
+        wakeRefs: ["health:sys-1", "incident:inc-9"],
+      });
+
+      const byExact = await store.findWaitLocksByWakeRef("health:sys-1");
+      expect(byExact).toHaveLength(1);
+      expect(byExact[0]?.runId).toBe(runId);
+
+      const byOther = await store.findWaitLocksByWakeRef("incident:inc-9");
+      expect(byOther).toHaveLength(1);
+
+      const noMatch = await store.findWaitLocksByWakeRef("health:other");
+      expect(noMatch).toHaveLength(0);
+    });
+
+    it("matches a kind-level wildcard wait", async () => {
+      const store = makeStore();
+      const runId = await seedRun();
+      await store.createWaitLockWithWakeRefs({
+        runId,
+        actionPath: "actions[0]",
+        eventId: "@@until",
+        contextKey: null,
+        timeoutAt: null,
+        waitConfig: {
+          condition: "state.slo[trigger.id].budget < 10",
+          continueOnTimeout: true,
+        },
+        wakeRefs: ["slo:*"],
+      });
+      const matched = await store.findWaitLocksByWakeRef("slo:obj-42");
+      expect(matched.some((l) => l.runId === runId)).toBe(true);
+    });
+
+    it("concurrent same-(lock, ref) inserts leave exactly one row", async () => {
+      const runId = await seedRun();
+      const store = makeStore();
+      // First, create the wait lock with one ref.
+      const lockId = await store.createWaitLockWithWakeRefs({
+        runId,
+        actionPath: "actions[0]",
+        eventId: "@@until",
+        contextKey: "sys-1",
+        timeoutAt: null,
+        waitConfig: {
+          condition: "state.health['sys-1'].status == 'healthy'",
+          continueOnTimeout: true,
+        },
+        wakeRefs: ["health:sys-1"],
+      });
+
+      // Now race many concurrent inserts of the SAME (lock, ref) pair under
+      // ON CONFLICT DO NOTHING — the unique index must collapse them to one.
+      const db = drizzle({
+        client: pool,
+        schema: { automationWakeIndex },
+      });
+      await Promise.all(
+        Array.from({ length: 8 }, () =>
+          db
+            .insert(automationWakeIndex)
+            .values({ waitLockId: lockId, ref: "health:sys-1" })
+            .onConflictDoNothing({
+              target: [
+                automationWakeIndex.waitLockId,
+                automationWakeIndex.ref,
+              ],
+            }),
+        ),
+      );
+
+      const rows = await db
+        .select()
+        .from(automationWakeIndex)
+        .where(
+          and(
+            eq(automationWakeIndex.waitLockId, lockId),
+            eq(automationWakeIndex.ref, "health:sys-1"),
+          ),
+        );
+      expect(rows).toHaveLength(1);
+    });
+  },
+);

package/src/entity/with-entity-write.test.ts

@@ -0,0 +1,100 @@
+import { describe, it, expect } from "bun:test";
+import type { EntityHandle, EntityMutationOpts } from "./define-entity";
+import { withEntityWrite, withEntityRemove } from "./with-entity-write";
+
+interface TestState extends Record<string, unknown> {
+  value: string;
+}
+
+describe("withEntityWrite", () => {
+  it("routes the write through handle.mutate keyed by id (with opts)", async () => {
+    const calls: Array<{
+      id: string;
+      opts?: EntityMutationOpts;
+      next: TestState;
+    }> = [];
+    const handle = {
+      kind: "test",
+      async mutate(input: {
+        id: string;
+        opts?: EntityMutationOpts;
+        apply: () => Promise<TestState>;
+      }) {
+        const next = await input.apply();
+        calls.push({ id: input.id, opts: input.opts, next });
+        return next;
+      },
+    } as unknown as EntityHandle<TestState>;
+
+    let applied = false;
+    await withEntityWrite({
+      handle,
+      id: "e-1",
+      opts: { runId: "run-1" },
+      apply: async () => {
+        applied = true;
+        return { value: "next" };
+      },
+    });
+
+    expect(applied).toBe(true);
+    expect(calls).toEqual([
+      { id: "e-1", opts: { runId: "run-1" }, next: { value: "next" } },
+    ]);
+  });
+
+  it("runs the plugin write directly when no handle is wired", async () => {
+    let applied = false;
+    await withEntityWrite<TestState>({
+      handle: undefined,
+      id: "e-2",
+      apply: async () => {
+        applied = true;
+        return { value: "next" };
+      },
+    });
+    expect(applied).toBe(true);
+  });
+});
+
+describe("withEntityRemove", () => {
+  it("tombstones via handle.remove keyed by id (with opts)", async () => {
+    const removed: Array<{ id: string; opts?: EntityMutationOpts }> = [];
+    let deleted = false;
+    const handle = {
+      kind: "test",
+      async remove(input: {
+        id: string;
+        opts?: EntityMutationOpts;
+        apply: () => Promise<void>;
+      }) {
+        await input.apply();
+        removed.push({ id: input.id, opts: input.opts });
+      },
+    } as unknown as EntityHandle<TestState>;
+
+    await withEntityRemove<TestState>({
+      handle,
+      id: "e-9",
+      opts: { runId: "run-9" },
+      apply: async () => {
+        deleted = true;
+      },
+    });
+
+    expect(deleted).toBe(true);
+    expect(removed).toEqual([{ id: "e-9", opts: { runId: "run-9" } }]);
+  });
+
+  it("runs the delete directly when no handle is wired", async () => {
+    let deleted = false;
+    await withEntityRemove<TestState>({
+      handle: undefined,
+      id: "e-3",
+      apply: async () => {
+        deleted = true;
+      },
+    });
+    expect(deleted).toBe(true);
+  });
+});