@checkstack/catalog-backend 1.1.6 → 1.3.0

package/src/router.ts

@@ -12,10 +12,19 @@ import * as schema from "./schema";
 import { NotificationApi } from "@checkstack/notification-common";
 import { AuthApi } from "@checkstack/auth-common";
 import type { InferClient } from "@checkstack/common";
-import { catalogHooks } from "./hooks";
 import { eq } from "drizzle-orm";
 import { GitOpsApi } from "@checkstack/gitops-common";
 import type { CatalogCache } from "./cache";
+import type { EntityHandle } from "@checkstack/automation-backend";
+import {
+  removeCatalogEntity,
+  toCatalogGroupState,
+  toCatalogSystemState,
+  writeCatalogGroupEntity,
+  writeCatalogSystemEntity,
+  type CatalogGroupState,
+  type CatalogSystemState,
+} from "./catalog-entity";
 
 /**
  * Creates the catalog router using contract-based implementation.
@@ -35,6 +44,9 @@ export interface CatalogRouterDeps {
   gitOpsClient: InferClient<typeof GitOpsApi>;
   pluginId: string;
   cache: CatalogCache;
+  /** Resolvers for the reactive catalog entities (§10.4). Undefined in tests. */
+  getSystemEntity?: () => EntityHandle<CatalogSystemState> | undefined;
+  getGroupEntity?: () => EntityHandle<CatalogGroupState> | undefined;
 }
 
 export const createCatalogRouter = ({
@@ -44,6 +56,8 @@ export const createCatalogRouter = ({
   gitOpsClient,
   pluginId: _pluginId,
   cache,
+  getSystemEntity,
+  getGroupEntity,
 }: CatalogRouterDeps) => {
   const entityService = new EntityService(database);
 
@@ -218,8 +232,27 @@ export const createCatalogRouter = ({
     },
   );
 
-  const createSystem = os.createSystem.handler(async ({ input, context }) => {
-    const result = await entityService.createSystem(input);
+  const createSystem = os.createSystem.handler(async ({ input }) => {
+    // Drive the create through the reactive `catalog-system` entity (§10.4):
+    // `apply` performs the REAL `systems` write (the plugin's own db/tx) and
+    // returns the new reactive state; the deriver fires `catalog.created`
+    // from the resulting change. The id is generated up front so the handle
+    // is keyed on it and the create's `prev` snapshot correctly reads the
+    // not-yet-existing row as absent.
+    const systemId = crypto.randomUUID();
+    let result!: Awaited<ReturnType<typeof entityService.createSystem>>;
+    await writeCatalogSystemEntity({
+      handle: getSystemEntity?.(),
+      systemId,
+      apply: async () => {
+        result = await entityService.createSystem(input, systemId);
+        return toCatalogSystemState({
+          name: result.name,
+          description: result.description,
+          metadata: result.metadata as Record<string, unknown> | null,
+        });
+      },
+    });
 
     // Push the new system into notification-backend's resource registry.
     // notification-backend handles all per-spec group provisioning from
@@ -230,14 +263,6 @@ export const createCatalogRouter = ({
 
     await cache.invalidateTopology();
 
-    // Hooks remain for non-notification cleanup concerns (e.g. incident
-    // associations) — emitting plugins no longer use them for
-    // subscription provisioning.
-    await context.emitHook(catalogHooks.systemCreated, {
-      systemId: result.id,
-      systemName: result.name,
-    });
-
     return result as typeof result & {
       metadata: Record<string, unknown> | null;
     };
@@ -245,70 +270,127 @@ export const createCatalogRouter = ({
 
   const updateSystem = os.updateSystem.handler(async ({ input }) => {
     await enforceNotGitOpsLocked("System", input.id);
-    // Convert null to undefined and filter out fields
+    // Convert null to undefined and filter out fields. The entity mirror
+    // diffs internally now, so we no longer track `changedFields` for a
+    // hook payload (§10.4).
     const cleanData: Partial<{
       name: string;
       description?: string;
       metadata?: Record<string, unknown>;
     }> = {};
-    if (input.data.name !== undefined) cleanData.name = input.data.name;
-    if (input.data.description !== undefined)
+    if (input.data.name !== undefined) {
+      cleanData.name = input.data.name;
+    }
+    if (input.data.description !== undefined) {
       cleanData.description = input.data.description ?? undefined;
-    if (input.data.metadata !== undefined)
+    }
+    if (input.data.metadata !== undefined) {
       cleanData.metadata = input.data.metadata ?? undefined;
+    }
 
-    const result = await entityService.updateSystem(input.id, cleanData);
-    if (!result) {
+    // Probe existence first so a missing system still surfaces as NOT_FOUND
+    // without driving an entity write.
+    const exists = await entityService.getSystem(input.id);
+    if (!exists) {
       throw new ORPCError("NOT_FOUND", {
         message: "System not found",
       });
     }
+
+    // Drive the update through the reactive `catalog-system` entity (§10.4).
+    // The REAL update runs INSIDE `apply`, so `prev` is snapshotted before
+    // the write and the deriver fires `catalog.updated` from the resulting
+    // change. The handle diffs internally, so a save-with-no-diff stays a
+    // no-op — preserving the old "don't fire automations on no-op updates"
+    // behavior without the explicit `changedFields` guard.
+    let result!: NonNullable<
+      Awaited<ReturnType<typeof entityService.updateSystem>>
+    >;
+    await writeCatalogSystemEntity({
+      handle: getSystemEntity?.(),
+      systemId: input.id,
+      apply: async () => {
+        const updated = await entityService.updateSystem(input.id, cleanData);
+        if (!updated) {
+          throw new ORPCError("NOT_FOUND", { message: "System not found" });
+        }
+        result = updated;
+        return toCatalogSystemState({
+          name: result.name,
+          description: result.description,
+          metadata: result.metadata as Record<string, unknown> | null,
+        });
+      },
+    });
+
     await cache.invalidateTopology();
     // Refresh display label in notification-backend on rename so the
     // settings/audit UI shows the current name.
     if (input.data.name !== undefined) {
       await upsertSystemResource({ id: result.id, name: result.name });
     }
+
     return result as typeof result & {
       metadata: Record<string, unknown> | null;
     };
   });
 
-  const deleteSystem = os.deleteSystem.handler(async ({ input, context }) => {
+  const deleteSystem = os.deleteSystem.handler(async ({ input }) => {
     await enforceNotGitOpsLocked("System", input);
-    await entityService.deleteSystem(input);
+
+    // Drive the delete through the reactive `catalog-system` entity tombstone
+    // (§10.4). The REAL delete runs INSIDE `apply`, so `prev` is snapshotted
+    // before it and the deriver fires `catalog.deleted` from the tombstone.
+    // Cross-plugin cleanup reactors (incident/dependency/slo/healthcheck)
+    // subscribe to that `catalog-system` tombstone via onEntityChanged.
+    await removeCatalogEntity({
+      handle: getSystemEntity?.(),
+      id: input,
+      apply: async () => {
+        await entityService.deleteSystem(input);
+      },
+    });
 
     await removeSystemResource(input);
 
-    // Drop catalog topology + this system's contacts BEFORE the hook fires,
-    // so downstream plugins (e.g. healthcheck) and any frontend that
-    // refetches in response see fresh data.
+    // Drop catalog topology + this system's contacts so downstream plugins
+    // (e.g. healthcheck) and any frontend that refetches in response see
+    // fresh data.
     await Promise.all([
       cache.invalidateTopology(),
       cache.invalidateContacts(input),
     ]);
 
-    // Emit hook for other plugins to clean up related data
-    await context.emitHook(catalogHooks.systemDeleted, { systemId: input });
-
     return { success: true };
   });
 
-  const createGroup = os.createGroup.handler(async ({ input, context }) => {
-    const result = await entityService.createGroup({
-      name: input.name,
-      metadata: input.metadata,
+  const createGroup = os.createGroup.handler(async ({ input }) => {
+    // Drive the create through the reactive `catalog-group` entity (§10.4):
+    // `apply` performs the REAL `groups` write and returns the new reactive
+    // state; the deriver fires `catalog.group.created`. The id is generated
+    // up front so the handle is keyed on it and the create's `prev` snapshot
+    // reads the not-yet-existing row as absent.
+    const groupId = crypto.randomUUID();
+    let result!: Awaited<ReturnType<typeof entityService.createGroup>>;
+    await writeCatalogGroupEntity({
+      handle: getGroupEntity?.(),
+      groupId,
+      apply: async () => {
+        result = await entityService.createGroup(
+          { name: input.name, metadata: input.metadata },
+          groupId,
+        );
+        return toCatalogGroupState({
+          name: result.name,
+          metadata: result.metadata as Record<string, unknown> | null,
+        });
+      },
     });
 
     await upsertGroupResource({ id: result.id, name: result.name });
 
     await cache.invalidateTopology();
 
-    await context.emitHook(catalogHooks.groupCreated, {
-      groupId: result.id,
-      groupName: result.name,
-    });
-
     // New groups have no systems yet
     return {
       ...result,
@@ -324,40 +406,76 @@ export const createCatalogRouter = ({
       ...input.data,
       metadata: input.data.metadata ?? undefined,
     };
-    const result = await entityService.updateGroup(input.id, cleanData);
-    if (!result) {
+    // Probe existence first so a missing group still surfaces as NOT_FOUND
+    // without driving an entity write.
+    const existing = await entityService.getGroups();
+    const existingGroup = existing.find((g) => g.id === input.id);
+    if (!existingGroup) {
       throw new ORPCError("NOT_FOUND", {
         message: "Group not found",
       });
     }
-    // Get the full group with systemIds after update
-    const groups = await entityService.getGroups();
-    const fullGroup = groups.find((g) => g.id === result.id);
-    if (!fullGroup) {
-      throw new ORPCError("INTERNAL_SERVER_ERROR", {
-        message: "Group not found after update",
-      });
-    }
+
+    // Drive the update through the reactive `catalog-group` entity (§10.4).
+    // The REAL update runs INSIDE `apply`, so `prev` is snapshotted before
+    // the write. There is no `catalog.group.updated` hook, so the deriver
+    // fires nothing on a pure update — but the entity state stays current
+    // for scope/conditions.
+    let fullGroup!: NonNullable<
+      Awaited<ReturnType<typeof entityService.getGroups>>[number]
+    >;
+    await writeCatalogGroupEntity({
+      handle: getGroupEntity?.(),
+      groupId: input.id,
+      apply: async () => {
+        const result = await entityService.updateGroup(input.id, cleanData);
+        if (!result) {
+          throw new ORPCError("NOT_FOUND", { message: "Group not found" });
+        }
+        // Get the full group with systemIds after update
+        const groups = await entityService.getGroups();
+        const updated = groups.find((g) => g.id === result.id);
+        if (!updated) {
+          throw new ORPCError("INTERNAL_SERVER_ERROR", {
+            message: "Group not found after update",
+          });
+        }
+        fullGroup = updated;
+        return toCatalogGroupState({
+          name: fullGroup.name,
+          metadata: fullGroup.metadata as Record<string, unknown> | null,
+        });
+      },
+    });
+
     await cache.invalidateTopology();
     if (input.data.name !== undefined) {
       await upsertGroupResource({ id: fullGroup.id, name: fullGroup.name });
     }
+
     return fullGroup as unknown as typeof fullGroup & {
       metadata: Record<string, unknown> | null;
     };
   });
 
-  const deleteGroup = os.deleteGroup.handler(async ({ input, context }) => {
+  const deleteGroup = os.deleteGroup.handler(async ({ input }) => {
     await enforceNotGitOpsLocked("Group", input);
-    await entityService.deleteGroup(input);
+
+    // Drive the delete through the reactive `catalog-group` entity tombstone
+    // (§10.4). The REAL delete runs INSIDE `apply`; the deriver fires
+    // `catalog.group.deleted` from the tombstone.
+    await removeCatalogEntity({
+      handle: getGroupEntity?.(),
+      id: input,
+      apply: async () => {
+        await entityService.deleteGroup(input);
+      },
+    });
 
     await removeGroupResource(input);
 
     await cache.invalidateTopology();
 
-    // Emit hook for other plugins to clean up related data
-    await context.emitHook(catalogHooks.groupDeleted, { groupId: input });
-
     return { success: true };
   });
 

package/src/services/entity-service.ts

@@ -1,8 +1,34 @@
-import { eq, and } from "drizzle-orm";
+import { eq, and, inArray } from "drizzle-orm";
 import * as schema from "../schema";
 import { SafeDatabase } from "@checkstack/backend-api";
 import { v4 as uuidv4 } from "uuid";
 
+/** Reactive subset of a catalog system (the `catalog-system` entity state). */
+type CatalogSystemEntityState = {
+  name: string;
+  description: string | null;
+  metadata: Record<string, unknown>;
+};
+
+/** Reactive subset of a catalog group (the `catalog-group` entity state). */
+type CatalogGroupEntityState = {
+  name: string;
+  metadata: Record<string, unknown>;
+};
+
+/**
+ * Narrow the drizzle `json()` column (typed `unknown`) to the reactive
+ * `Record<string, unknown>` metadata shape, defaulting non-object values
+ * (null / scalars / arrays) to an empty object so the entity state is always
+ * a well-formed record.
+ */
+function normalizeMetadata(value: unknown): Record<string, unknown> {
+  if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+    return value as Record<string, unknown>;
+  }
+  return {};
+}
+
 // Type aliases for entity creation
 type NewSystem = {
   name: string;
@@ -49,10 +75,19 @@ export class EntityService {
     return result[0];
   }
 
-  async createSystem(data: NewSystem) {
+  /**
+   * Create a system.
+   *
+   * `id` may be supplied by the caller so the reactive `catalog-system`
+   * entity can be keyed on a known id BEFORE the insert runs (the create's
+   * `prev` snapshot must read the not-yet-existing row as absent — see
+   * §10.4). When omitted, a fresh id is generated. The id is server-owned
+   * either way.
+   */
+  async createSystem(data: NewSystem, id: string = uuidv4()) {
     const result = await this.database
       .insert(schema.systems)
-      .values({ id: uuidv4(), ...data })
+      .values({ id, ...data })
       .returning();
     return result[0];
   }
@@ -70,6 +105,40 @@ export class EntityService {
     await this.database.delete(schema.systems).where(eq(schema.systems.id, id));
   }
 
+  /**
+   * Batched reactive-state read for the `catalog-system` entity (Model B
+   * plugin-backed `read` accessor). Given system ids, return the reactive
+   * subset `{ name, description, metadata }` for each that exists (missing
+   * ids omitted). Reads the AUTHORITATIVE `systems` table — no framework
+   * `entity_state` storage. This is the single source of truth
+   * `handle.mutate` snapshots `prev` from and `get`/`getMany`/scope
+   * enrichment route through.
+   */
+  async getManySystemEntityStates(
+    ids: ReadonlyArray<string>,
+  ): Promise<Record<string, CatalogSystemEntityState>> {
+    if (ids.length === 0) return {};
+    const rows = await this.database
+      .select({
+        id: schema.systems.id,
+        name: schema.systems.name,
+        description: schema.systems.description,
+        metadata: schema.systems.metadata,
+      })
+      .from(schema.systems)
+      .where(inArray(schema.systems.id, [...ids]));
+
+    const out: Record<string, CatalogSystemEntityState> = {};
+    for (const row of rows) {
+      out[row.id] = {
+        name: row.name,
+        description: row.description ?? null,
+        metadata: normalizeMetadata(row.metadata),
+      };
+    }
+    return out;
+  }
+
   // System Contacts
   async getContactsForSystem(systemId: string) {
     return this.database
@@ -147,10 +216,18 @@ export class EntityService {
     }));
   }
 
-  async createGroup(data: NewGroup) {
+  /**
+   * Create a group.
+   *
+   * `id` may be supplied so the reactive `catalog-group` entity can be keyed
+   * on a known id BEFORE the insert runs (the create's `prev` snapshot must
+   * read the not-yet-existing row as absent — see §10.4). When omitted, a
+   * fresh id is generated. The id is server-owned either way.
+   */
+  async createGroup(data: NewGroup, id: string = uuidv4()) {
     const result = await this.database
       .insert(schema.groups)
-      .values({ id: uuidv4(), ...data })
+      .values({ id, ...data })
       .returning();
     return result[0];
   }
@@ -168,6 +245,36 @@ export class EntityService {
     await this.database.delete(schema.groups).where(eq(schema.groups.id, id));
   }
 
+  /**
+   * Batched reactive-state read for the `catalog-group` entity (Model B
+   * plugin-backed `read` accessor). Given group ids, return the reactive
+   * subset `{ name, metadata }` for each that exists (missing ids omitted).
+   * Reads the AUTHORITATIVE `groups` table — no framework `entity_state`
+   * storage.
+   */
+  async getManyGroupEntityStates(
+    ids: ReadonlyArray<string>,
+  ): Promise<Record<string, CatalogGroupEntityState>> {
+    if (ids.length === 0) return {};
+    const rows = await this.database
+      .select({
+        id: schema.groups.id,
+        name: schema.groups.name,
+        metadata: schema.groups.metadata,
+      })
+      .from(schema.groups)
+      .where(inArray(schema.groups.id, [...ids]));
+
+    const out: Record<string, CatalogGroupEntityState> = {};
+    for (const row of rows) {
+      out[row.id] = {
+        name: row.name,
+        metadata: normalizeMetadata(row.metadata),
+      };
+    }
+    return out;
+  }
+
   async getGroupsForSystem(systemId: string) {
     const associations = await this.database
       .select()

package/tsconfig.json

@@ -10,6 +10,9 @@
     {
       "path": "../auth-common"
     },
+    {
+      "path": "../automation-backend"
+    },
     {
       "path": "../backend-api"
     },
@@ -39,6 +42,9 @@
     },
     {
       "path": "../notification-common"
+    },
+    {
+      "path": "../test-utils-backend"
     }
   ]
 }