@checkstack/catalog-backend 1.2.0 → 1.3.0

package/src/index.ts

@@ -7,7 +7,23 @@ import {
   automationActionExtensionPoint,
   automationArtifactTypeExtensionPoint,
   automationTriggerExtensionPoint,
+  entityExtensionPoint,
+  type EntityHandle,
 } from "@checkstack/automation-backend";
+import {
+  CATALOG_GROUP_ENTITY_KIND,
+  CATALOG_SYSTEM_ENTITY_KIND,
+  CatalogGroupStateSchema,
+  CatalogSystemStateSchema,
+  catalogGroupChangeToPayload,
+  catalogSystemChangeToPayload,
+  createCatalogGroupEntityRead,
+  createCatalogSystemEntityRead,
+  deriveCatalogGroupTriggerEvents,
+  deriveCatalogSystemTriggerEvents,
+  type CatalogGroupState,
+  type CatalogSystemState,
+} from "./catalog-entity";
 import {
   catalogAccessRules,
   catalogAccess,
@@ -43,9 +59,46 @@ import * as schema from "./schema";
 
 export let db: SafeDatabase<typeof schema> | undefined;
 
+// Reactive catalog entity handles (§10.4). Defined in register() via the
+// entity extension point; mutate from init()/afterPluginsReady onward.
+let systemEntity: EntityHandle<CatalogSystemState> | undefined;
+let groupEntity: EntityHandle<CatalogGroupState> | undefined;
+
+// The catalog EntityService is created in init() (it needs the resolved
+// database), but the PLUGIN-BACKED entity `read` accessors must be supplied
+// at `defineEntity` time in register(). This holder bridges the two: the
+// `read` closures resolve the service lazily, and init() sets it before any
+// mutation runs (the registry only mutates from init() onward).
+let catalogEntityServiceRef: EntityService | undefined;
+
+/**
+ * Resolve the catalog EntityService for the PLUGIN-BACKED entity `read`
+ * accessors. Throws if invoked before init() has published the service —
+ * which never happens in practice, since the registry only reads/mutates
+ * from init() onward.
+ */
+function resolveCatalogEntityService(): EntityService {
+  const svc = catalogEntityServiceRef;
+  if (!svc) {
+    throw new Error(
+      "catalog entity read before init: service not yet resolved",
+    );
+  }
+  return svc;
+}
+
 // Export hooks for other plugins to subscribe to
 export { catalogHooks } from "./hooks";
 
+// Re-export the reactive catalog entity kind ids so cross-plugin consumers
+// (incident, dependency, slo) can subscribe via onEntityChanged (§10.4).
+export {
+  CATALOG_SYSTEM_ENTITY_KIND,
+  CATALOG_GROUP_ENTITY_KIND,
+  type CatalogSystemState,
+  type CatalogGroupState,
+} from "./catalog-entity";
+
 export default createBackendPlugin({
   metadata: pluginMetadata,
   register(env) {
@@ -66,6 +119,36 @@ export default createBackendPlugin({
       .getExtensionPoint(automationArtifactTypeExtensionPoint)
       .registerArtifactType(systemRecordArtifactType, pluginMetadata);
 
+    // ─── Reactive catalog entities (§10.4) ─────────────────────────────
+    // PLUGIN-BACKED (Model B): the `systems` / `groups` tables ARE the
+    // current-state storage. `read` routes straight to the EntityService's
+    // batched authoritative read — no framework `entity_state` row, so no
+    // `indexes` (those only apply to store-backed kinds). The `read` closures
+    // resolve the service set by init() (mutations only happen from init on).
+    const entityPoint = env.getExtensionPoint(entityExtensionPoint);
+    systemEntity = entityPoint.defineEntity<CatalogSystemState>({
+      kind: CATALOG_SYSTEM_ENTITY_KIND,
+      state: CatalogSystemStateSchema,
+      read: (ids) =>
+        createCatalogSystemEntityRead(resolveCatalogEntityService())(ids),
+    });
+    groupEntity = entityPoint.defineEntity<CatalogGroupState>({
+      kind: CATALOG_GROUP_ENTITY_KIND,
+      state: CatalogGroupStateSchema,
+      read: (ids) =>
+        createCatalogGroupEntityRead(resolveCatalogEntityService())(ids),
+    });
+    entityPoint.registerChangeDeriver({
+      kind: CATALOG_SYSTEM_ENTITY_KIND,
+      derive: deriveCatalogSystemTriggerEvents,
+      toPayload: catalogSystemChangeToPayload,
+    });
+    entityPoint.registerChangeDeriver({
+      kind: CATALOG_GROUP_ENTITY_KIND,
+      derive: deriveCatalogGroupTriggerEvents,
+      toPayload: catalogGroupChangeToPayload,
+    });
+
     // ─── GitOps Entity Kind Registration ───────────────────────────────
     // Mutable DB reference — populated during init(), consumed by reconcile closures.
     // Safe because reconcile is only called during sync (afterPluginsReady), by which
@@ -223,6 +306,11 @@ export default createBackendPlugin({
 
         const typedDb = database as SafeDatabase<typeof schema>;
 
+        // Publish the EntityService for the PLUGIN-BACKED catalog entity
+        // `read` accessors (defined in register()). Mutations only run from
+        // here onward, so the lazy `read` closures always find it resolved.
+        catalogEntityServiceRef = new EntityService(typedDb);
+
         // Get notification client for group management and sending notifications
         const notificationClient = rpcClient.forPlugin(NotificationApi);
         const authClient = rpcClient.forPlugin(AuthApi);
@@ -238,6 +326,8 @@ export default createBackendPlugin({
           gitOpsClient,
           pluginId: pluginMetadata.pluginId,
           cache,
+          getSystemEntity: () => systemEntity,
+          getGroupEntity: () => groupEntity,
         });
         rpc.registerRouter(catalogRouter, catalogContract);
 
@@ -302,7 +392,6 @@ export default createBackendPlugin({
         rpcClient,
         logger,
         onHook,
-        emitHook,
         cacheManager,
       }) => {
         const typedDb = database as SafeDatabase<typeof schema>;
@@ -315,9 +404,9 @@ export default createBackendPlugin({
         // provisioning happens server-side from this signal.
         await bootstrapNotificationTargets(typedDb, notificationClient, logger);
 
-        // Register automation actions now that `emitHook` is available
-        // — the `update_metadata` action needs to fire `systemUpdated`
-        // downstream so other automations + caches react to the change.
+        // Register automation actions. The `update_metadata` action mirrors
+        // its edit into the `catalog-system` entity, whose deriver fires the
+        // `catalog.updated` trigger event downstream (§10.4).
         const automationActions = env.getExtensionPoint(
           automationActionExtensionPoint,
         );
@@ -326,7 +415,7 @@ export default createBackendPlugin({
         for (const action of createCatalogActions({
           entityService,
           cache,
-          emitHook,
+          getSystemEntity: () => systemEntity,
         })) {
           automationActions.registerAction(action, pluginMetadata);
         }

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,47 +263,66 @@ 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;
     };
   });
 
-  const updateSystem = os.updateSystem.handler(async ({ input, context }) => {
+  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>;
     }> = {};
-    const changedFields: Array<"name" | "description" | "metadata"> = [];
     if (input.data.name !== undefined) {
       cleanData.name = input.data.name;
-      changedFields.push("name");
     }
     if (input.data.description !== undefined) {
       cleanData.description = input.data.description ?? undefined;
-      changedFields.push("description");
     }
     if (input.data.metadata !== undefined) {
       cleanData.metadata = input.data.metadata ?? undefined;
-      changedFields.push("metadata");
     }
 
-    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.
@@ -278,56 +330,67 @@ export const createCatalogRouter = ({
       await upsertSystemResource({ id: result.id, name: result.name });
     }
 
-    // Emit only when a tracked field actually changed (skip no-op
-    // updates so automations don't fire on every save-with-no-diff).
-    if (changedFields.length > 0) {
-      await context.emitHook(catalogHooks.systemUpdated, {
-        systemId: result.id,
-        systemName: result.name,
-        changedFields,
-      });
-    }
-
     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,
@@ -343,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()