@checkstack/catalog-backend 1.1.6 → 1.3.0

package/src/catalog-entity.ts

@@ -0,0 +1,274 @@
+/**
+ * The reactive `catalog-system` + `catalog-group` entities (reactive
+ * automation engine §10.4).
+ *
+ * Model B PLUGIN-BACKED entities: the catalog `systems` / `groups` tables
+ * are authoritative AND ARE the entities' current-state storage — there is
+ * NO framework `entity_state` row for a catalog system/group.
+ * `defineEntity({ read })` makes that plugin state reactive: every
+ * reactive-state write goes through `handle.mutate`, whose `apply()` performs
+ * the REAL `systems`/`groups` write via the catalog `EntityService` (the
+ * plugin's own db/tx) and returns the resulting reactive subset. The
+ * framework snapshots `prev` via `read`, appends the transition log (its own
+ * db), and emits `ENTITY_CHANGED`. The change → trigger-event derivers
+ * reproduce `catalog.created/.updated/.deleted` +
+ * `catalog.group.created/.deleted` so automations keep firing.
+ */
+import { z } from "zod";
+import type {
+  EntityChangeDeriver,
+  EntityChangePayloadMapper,
+  EntityHandle,
+  EntityMutationOpts,
+  EntityRead,
+} from "@checkstack/automation-backend";
+import {
+  withEntityRemove,
+  withEntityWrite,
+} from "@checkstack/automation-backend";
+
+import type { EntityService } from "./services/entity-service";
+
+export const CATALOG_SYSTEM_ENTITY_KIND = "catalog-system";
+export const CATALOG_GROUP_ENTITY_KIND = "catalog-group";
+
+/** Reactive state for a catalog system. */
+export const CatalogSystemStateSchema = z.object({
+  name: z.string(),
+  description: z.string().nullable(),
+  metadata: z.record(z.string(), z.unknown()),
+});
+export type CatalogSystemState = z.infer<typeof CatalogSystemStateSchema>;
+
+/** Reactive state for a catalog group. */
+export const CatalogGroupStateSchema = z.object({
+  name: z.string(),
+  metadata: z.record(z.string(), z.unknown()),
+});
+export type CatalogGroupState = z.infer<typeof CatalogGroupStateSchema>;
+
+/**
+ * Qualified TRIGGER event ids (`${pluginId}.${trigger.id}`) that automations
+ * store in `trigger.event` and Stage-1 routing matches on — NOT the dotted
+ * hook ids. The catalog system triggers use ids `created`/`updated`/`deleted`
+ * (pluginId `catalog`), so the deriver emits `catalog.created` etc., not the
+ * hook id `catalog.system.created`. (Verified against `automations.ts`.)
+ *
+ * There are NO registered catalog GROUP triggers today, so the group deriver
+ * fires nothing that any automation matches — kept for forward-compat + so
+ * group changes still drive scope/wake resolution as a known reactive kind.
+ */
+export const CATALOG_SYSTEM_TRIGGER_EVENTS = {
+  created: "catalog.created",
+  updated: "catalog.updated",
+  deleted: "catalog.deleted",
+} as const;
+
+export const CATALOG_GROUP_TRIGGER_EVENTS = {
+  created: "catalog.group.created",
+  deleted: "catalog.group.deleted",
+} as const;
+
+/**
+ * `catalog-system` change → trigger events. Create (`prev === null`),
+ * tombstone (`next === null`), or a field update map to the matching
+ * lifecycle event. A no-op diff never reaches a deriver (the handle
+ * suppresses it), so an update always carries a real change.
+ */
+export const deriveCatalogSystemTriggerEvents: EntityChangeDeriver = (
+  changed,
+) => {
+  if (changed.prev === null && changed.next !== null) {
+    return [CATALOG_SYSTEM_TRIGGER_EVENTS.created];
+  }
+  if (changed.next === null) {
+    return [CATALOG_SYSTEM_TRIGGER_EVENTS.deleted];
+  }
+  return [CATALOG_SYSTEM_TRIGGER_EVENTS.updated];
+};
+
+/**
+ * `catalog-group` change → trigger events. Only create + delete have
+ * matching hooks today (there is no `catalog.group.updated`), so a pure
+ * update diff fires nothing.
+ */
+export const deriveCatalogGroupTriggerEvents: EntityChangeDeriver = (
+  changed,
+) => {
+  if (changed.prev === null && changed.next !== null) {
+    return [CATALOG_GROUP_TRIGGER_EVENTS.created];
+  }
+  if (changed.next === null) {
+    return [CATALOG_GROUP_TRIGGER_EVENTS.deleted];
+  }
+  return [];
+};
+
+/** The catalog `system.updated` trigger's `changedFields` enum members. */
+const CATALOG_SYSTEM_CHANGED_FIELDS = ["name", "description", "metadata"] as const;
+
+function readName(state: Record<string, unknown> | null): string | undefined {
+  if (state === null) return undefined;
+  const name = state["name"];
+  return typeof name === "string" ? name : undefined;
+}
+
+/**
+ * Map a `catalog-system` change to the domain-named `trigger.payload` the
+ * catalog system triggers declare via `payloadSchema` (`systemId`,
+ * `systemName`, `changedFields`). Restores the keys operators read
+ * (`trigger.payload.systemId`, `.systemName`, `.changedFields`) that the
+ * generic change shape omits.
+ *
+ * `systemId` is the entity id; `systemName` is `next.name` (absent on a
+ * tombstone, where the `deleted` schema marks it optional); `changedFields` is
+ * the change's `changedFields` intersected with the system trigger enum
+ * (`name` / `description` / `metadata`).
+ */
+export const catalogSystemChangeToPayload: EntityChangePayloadMapper = (
+  changed,
+) => {
+  const changedFields = changed.changedFields.filter(
+    (f): f is (typeof CATALOG_SYSTEM_CHANGED_FIELDS)[number] =>
+      (CATALOG_SYSTEM_CHANGED_FIELDS as readonly string[]).includes(f),
+  );
+  const systemName = readName(changed.next);
+  return {
+    systemId: changed.id,
+    ...(systemName === undefined ? {} : { systemName }),
+    changedFields,
+  };
+};
+
+/**
+ * Map a `catalog-group` change to a domain-named `trigger.payload`
+ * (`groupId`, `groupName`). There are NO registered catalog GROUP triggers
+ * today, so this fires for no automation yet — it is supplied for forward
+ * compatibility + parity so a group change carries the same domain shape the
+ * other kinds do when group triggers are added.
+ */
+export const catalogGroupChangeToPayload: EntityChangePayloadMapper = (
+  changed,
+) => {
+  const groupName = readName(changed.next);
+  return {
+    groupId: changed.id,
+    ...(groupName === undefined ? {} : { groupName }),
+  };
+};
+
+/**
+ * Build the PLUGIN-BACKED `read` accessor for the `catalog-system` entity.
+ * Routes straight to the service's batched authoritative read over the
+ * `systems` table — no framework storage.
+ */
+export function createCatalogSystemEntityRead(
+  service: EntityService,
+): EntityRead<CatalogSystemState> {
+  return (ids) => service.getManySystemEntityStates(ids);
+}
+
+/**
+ * Build the PLUGIN-BACKED `read` accessor for the `catalog-group` entity.
+ * Routes straight to the service's batched authoritative read over the
+ * `groups` table — no framework storage.
+ */
+export function createCatalogGroupEntityRead(
+  service: EntityService,
+): EntityRead<CatalogGroupState> {
+  return (ids) => service.getManyGroupEntityStates(ids);
+}
+
+/**
+ * Project a catalog system row onto the reactive `{ name, description,
+ * metadata }` subset. The router's service writes return the full row; this
+ * is the `apply()` return for `handle.mutate`.
+ */
+export function toCatalogSystemState(system: {
+  name: string;
+  description: string | null | undefined;
+  metadata: Record<string, unknown> | null | undefined;
+}): CatalogSystemState {
+  return {
+    name: system.name,
+    description: system.description ?? null,
+    metadata: system.metadata ?? {},
+  };
+}
+
+/**
+ * Project a catalog group row onto the reactive `{ name, metadata }` subset.
+ */
+export function toCatalogGroupState(group: {
+  name: string;
+  metadata: Record<string, unknown> | null | undefined;
+}): CatalogGroupState {
+  return {
+    name: group.name,
+    metadata: group.metadata ?? {},
+  };
+}
+
+/**
+ * Drive a reactive-state `catalog-system` write through `handle.mutate`
+ * (§10.4). `apply` performs the REAL `systems` write via the service (the
+ * plugin's own db/tx) and returns the new reactive state. The framework
+ * snapshots `prev`, appends the transition log, and emits `ENTITY_CHANGED`
+ * (the deriver turns that into `catalog.created/.updated`).
+ *
+ * When no handle is available (tests construct the router without one), the
+ * write still runs — the entity reactivity is layered on top, never required
+ * for the underlying write to succeed.
+ */
+export async function writeCatalogSystemEntity(args: {
+  handle: EntityHandle<CatalogSystemState> | undefined;
+  systemId: string;
+  /**
+   * Mutation context (actor / runId). When the write originates inside a
+   * dispatch run (e.g. `system.update_metadata`), pass `opts: { runId }` so a
+   * run-resolved secret that lands in `metadata` is masked in the
+   * `entity_transitions` rows + the cluster-wide `ENTITY_CHANGED` — `metadata`
+   * is `z.record(z.string(), z.unknown())`, the only reactive catalog field
+   * that can carry an arbitrary secret string.
+   */
+  opts?: EntityMutationOpts;
+  apply: () => Promise<CatalogSystemState>;
+}): Promise<void> {
+  const { handle, systemId, opts, apply } = args;
+  await withEntityWrite({ handle, id: systemId, opts, apply });
+}
+
+/**
+ * Drive a reactive-state `catalog-group` write through `handle.mutate`
+ * (§10.4). Mirrors {@link writeCatalogSystemEntity} for the group kind.
+ */
+export async function writeCatalogGroupEntity(args: {
+  handle: EntityHandle<CatalogGroupState> | undefined;
+  groupId: string;
+  /** Mutation context (actor / runId) — see {@link writeCatalogSystemEntity}. */
+  opts?: EntityMutationOpts;
+  apply: () => Promise<CatalogGroupState>;
+}): Promise<void> {
+  const { handle, groupId, opts, apply } = args;
+  await withEntityWrite({ handle, id: groupId, opts, apply });
+}
+
+/**
+ * Drive a catalog entity tombstone through `handle.remove` (§10.4). `apply`
+ * performs the REAL delete via the service; the framework records the
+ * tombstone transition and emits a tombstone change (the deriver fires
+ * `catalog.deleted` / `catalog.group.deleted`). Without a handle, the delete
+ * still runs.
+ */
+export async function removeCatalogEntity<
+  TState extends Record<string, unknown>,
+>(args: {
+  handle: EntityHandle<TState> | undefined;
+  id: string;
+  /** Mutation context (actor / runId) — see {@link writeCatalogSystemEntity}. */
+  opts?: EntityMutationOpts;
+  apply: () => Promise<void>;
+}): Promise<void> {
+  const { handle, id, opts, apply } = args;
+  await withEntityRemove({ handle, id, opts, apply });
+}

package/src/hooks.ts

@@ -1,44 +1,14 @@
-import { createHook } from "@checkstack/backend-api";
-
 /**
- * Catalog hooks for cross-plugin communication
+ * Catalog cross-plugin hooks.
+ *
+ * The `catalog.system.created` / `.updated` / `.deleted` +
+ * `catalog.group.created` / `.deleted` hooks were removed in Phase 4
+ * (§10.4): catalog systems + groups are now the reactive `catalog-system`
+ * / `catalog-group` entities, whose change derivers fire the matching
+ * `catalog.created` / `.updated` / `.deleted` trigger events through
+ * Stage-1 routing, and cross-plugin cleanup reactors subscribe to the
+ * `catalog-system` tombstone via `onEntityChanged`. No cross-plugin hook
+ * remains, so this object is intentionally empty (kept for the stable
+ * `export { catalogHooks }` surface).
  */
-export const catalogHooks = {
-  /**
-   * Emitted when a system is created.
-   * Plugins can subscribe (work-queue mode) to bootstrap related state
-   * (e.g. per-system notification groups).
-   */
-  systemCreated: createHook<{
-    systemId: string;
-    systemName: string;
-  }>("catalog.system.created"),
-
-  /**
-   * Emitted when a system is deleted.
-   * Plugins can subscribe (work-queue mode) to clean up related data.
-   */
-  systemDeleted: createHook<{
-    systemId: string;
-    systemName?: string;
-  }>("catalog.system.deleted"),
-
-  /**
-   * Emitted when a catalog group is created.
-   * Plugins can subscribe to bootstrap related state (e.g. anomaly creates
-   * its own per-group notification group on this signal).
-   */
-  groupCreated: createHook<{
-    groupId: string;
-    groupName: string;
-  }>("catalog.group.created"),
-
-  /**
-   * Emitted when a group is deleted.
-   * Plugins can subscribe (work-queue mode) to clean up related data.
-   */
-  groupDeleted: createHook<{
-    groupId: string;
-    groupName?: string;
-  }>("catalog.group.deleted"),
-} as const;
+export const catalogHooks = {} as const;

package/src/index.ts

@@ -3,6 +3,27 @@ import {
   type SafeDatabase,
 } from "@checkstack/backend-api";
 import { coreServices } from "@checkstack/backend-api";
+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,
@@ -27,19 +48,107 @@ import { entityKindExtensionPoint } from "@checkstack/gitops-backend";
 import { CHECKSTACK_API_VERSION, entityRefSchema, GitOpsApi } from "@checkstack/gitops-common";
 import { z } from "zod";
 
+import {
+  catalogTriggers,
+  createCatalogActions,
+  systemRecordArtifactType,
+} from "./automations";
+
 // Database schema is still needed for types in creating the router
 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) {
     env.registerAccessRules(catalogAccessRules);
 
+    // ─── Automation Platform: triggers + artifact type ─────────────────
+    // Buffered behind the extension point until automation-backend's
+    // register() runs. The action factory is wired in afterPluginsReady
+    // below — that's where `emitHook` becomes available, which the
+    // `update_metadata` action needs in order to fire `systemUpdated`.
+    const automationTriggers = env.getExtensionPoint(
+      automationTriggerExtensionPoint,
+    );
+    for (const trigger of catalogTriggers) {
+      automationTriggers.registerTrigger(trigger, pluginMetadata);
+    }
+    env
+      .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
@@ -197,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);
@@ -212,6 +326,8 @@ export default createBackendPlugin({
           gitOpsClient,
           pluginId: pluginMetadata.pluginId,
           cache,
+          getSystemEntity: () => systemEntity,
+          getGroupEntity: () => groupEntity,
         });
         rpc.registerRouter(catalogRouter, catalogContract);
 
@@ -271,7 +387,13 @@ export default createBackendPlugin({
         logger.debug("✅ Catalog Backend initialized.");
       },
       // Phase 3: Safe to make RPC calls after all plugins are ready
-      afterPluginsReady: async ({ database, rpcClient, logger, onHook }) => {
+      afterPluginsReady: async ({
+        database,
+        rpcClient,
+        logger,
+        onHook,
+        cacheManager,
+      }) => {
         const typedDb = database as SafeDatabase<typeof schema>;
         const notificationClient = rpcClient.forPlugin(NotificationApi);
 
@@ -282,13 +404,29 @@ export default createBackendPlugin({
         // provisioning happens server-side from this signal.
         await bootstrapNotificationTargets(typedDb, notificationClient, logger);
 
+        // 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,
+        );
+        const entityService = new EntityService(typedDb);
+        const cache = createCatalogCache({ cacheManager, logger });
+        for (const action of createCatalogActions({
+          entityService,
+          cache,
+          getSystemEntity: () => systemEntity,
+        })) {
+          automationActions.registerAction(action, pluginMetadata);
+        }
+
         // Subscribe to user deletion to clean up user contacts
         onHook(
           authHooks.userDeleted,
           async ({ userId }) => {
             logger.debug(`Cleaning up contacts for deleted user: ${userId}`);
-            const entityService = new EntityService(typedDb);
-            await entityService.deleteContactsByUserId(userId);
+            const userCleanupService = new EntityService(typedDb);
+            await userCleanupService.deleteContactsByUserId(userId);
             logger.debug(`Cleaned up contacts for user: ${userId}`);
           },
           { mode: "work-queue", workerGroup: "user-cleanup" },