@checkstack/catalog-backend 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,107 @@
 # @checkstack/catalog-backend
 
+## 1.3.0
+
+### Minor Changes
+
+- b995afb: Make `catalog-system` and `catalog-group` plugin-backed reactive entities via the Model-B entity state machine.
+
+  Catalog defines a `catalog-system` entity `{ name, description, metadata }` and a `catalog-group` entity `{ name, metadata }`. The `systems` / `groups` tables are BOTH authoritative AND the entities' current-state storage - there is no framework `entity_state` row for a catalog system/group. `defineEntity` is given plugin `read` accessors (`EntityService.getManySystemEntityStates` / `getManyGroupEntityStates`) that project the reactive subsets straight off those tables, and every reactive-state write goes through `handle.mutate` / `handle.remove`: `apply` performs the REAL `systems` / `groups` write (the plugin's own db/tx) and returns the new state; the framework snapshots `prev` via `read` BEFORE the write, appends the transition log, and emits `ENTITY_CHANGED` AFTER the write commits. Covered sites: create-system, update-system, delete-system (tombstone), create-group, update-group, delete-group (tombstone), and the `system.update_metadata` automation action. Create sites pre-generate the id so the handle is keyed on it and the create's `prev` snapshot reads the not-yet-existing row as absent; `EntityService.createSystem` / `createGroup` accept an optional pre-generated `id` (server-owned either way).
+
+  Change -> trigger-event derivers reproduce the existing qualified events (emitting the TRIGGER event ids automations match on, not the dotted hook ids):
+
+  - `catalog-system`: create -> `catalog.created`; tombstone -> `catalog.deleted`; field update -> `catalog.updated`.
+  - `catalog-group`: create -> `catalog.group.created`; tombstone -> `catalog.group.deleted` (a pure group update fires nothing).
+
+  Mirrors are diff-suppressed (a save-with-no-diff stays a no-op). The `catalog.system.*` / `catalog.group.*` cross-plugin hooks are removed in the same effort (see the healthcheck/catalog hook-removal changeset); cross-plugin consumers (incident, dependency, slo, healthcheck) read via `onEntityChanged`.
+
+  BREAKING CHANGES (behavior): none for trigger-event consumers - the same qualified trigger events still fire via the change derivers, and `onEntityChanged` consumers see the same change event. The only observable change is internal: catalog current state is read from the `systems` / `groups` tables instead of `entity_state`, and writes route through the entity handle. The `system.update_metadata` action's race-deleted ("disappeared mid-update") path now drives a no-op entity write (the framework diffs it as no change) before returning failure, instead of skipping the write entirely; no event fires either way.
+
+- b995afb: Close a run-secret masking gap on run-originated catalog entity writes (security).
+
+  `writeCatalogSystemEntity` / `writeCatalogGroupEntity` had no `opts` parameter, so the `system.update_metadata` automation action (which has the dispatch `runId` in scope) could not forward it. Catalog `metadata` is `z.record(z.string(), z.unknown())` — the only reactive catalog field that can carry an arbitrary secret string — so a run-resolved secret merged into metadata would land UNMASKED in both the `entity_transitions` rows and the cluster-wide `ENTITY_CHANGED` event.
+
+  The catalog entity writers now accept `opts?: EntityMutationOpts` and forward it into `handle.mutate` / `handle.remove` (mirroring maintenance/slo), and `system.update_metadata` passes `opts: { runId }`. Run-resolved secrets in metadata are now masked in both the emit and the transition rows.
+
+- b995afb: Remove the now-unused healthcheck + catalog entity hooks; rely on the reactive entities + change derivers (reactive automation engine Phase 4, final step of §10.3 / §10.4).
+
+  Now that every cross-plugin consumer (slo, dependency, incident, and healthcheck's own catalog-cleanup) reads these domains via `onEntityChanged`, the producers stop emitting the entity-change hooks and the trigger registrations become entity-driven (fired by the entity change deriver via Stage-1 routing, with a no-op `setup` so they stay in the editor's trigger catalog).
+
+  - **healthcheck**: stops emitting `healthcheck.system.degraded` / `.healthy` / `.health_changed` from the queue executor (the `health` entity mirror is the single source of truth). Its own `catalog.system.deleted` consumer switched to `onEntityChanged({ kind: "catalog-system" })` on tombstones (work-queue delivery preserved). The directional/umbrella triggers are now entity-driven.
+  - **catalog**: stops emitting `catalog.system.created` / `.updated` / `.deleted` and `catalog.group.created` / `.deleted` from the router + the `system.update_metadata` action (the `catalog-system` / `catalog-group` mirrors are authoritative). The system triggers are now entity-driven.
+
+  CORRECTNESS FIX (also affects the earlier healthcheck/catalog Phase-4 steps in this branch): the change derivers now emit the TRIGGER qualifiedIds that automations actually store in `trigger.event` and that Stage-1 routing matches on (`findEnabledByTriggerEvent`), NOT the dotted hook ids. Healthcheck triggers use underscore ids, so the deriver emits `healthcheck.system_degraded` / `system_healthy` / `system_health_changed` (not `healthcheck.system.degraded`). Catalog system triggers use ids `created`/`updated`/`deleted`, so the deriver emits `catalog.created` / `catalog.updated` / `catalog.deleted` (not `catalog.system.created`). Without this fix the migrated automations would never fire.
+
+  BREAKING CHANGES:
+
+  - `healthcheck.system.degraded` / `healthcheck.system.healthy` / `healthcheck.system.health_changed` cross-plugin hooks are removed. The reactive `health` entity drives the matching trigger events (`healthcheck.system_degraded` / `_healthy` / `_health_changed`), so existing automations keep firing. Kept healthcheck hooks: `assignment.changed`, `check.completed`, `check.failed`, `flapping_detected`.
+  - `catalog.system.created` / `.updated` / `.deleted` and `catalog.group.created` / `.deleted` cross-plugin hooks are removed. The reactive `catalog-system` / `catalog-group` entities drive the matching trigger events (`catalog.created` / `.updated` / `.deleted`); cross-plugin cleanup reactors subscribe to the `catalog-system` tombstone via `onEntityChanged`. `catalogHooks` / `healthCheckHooks` remain exported (the removed members are gone) for a stable import surface.
+
+- b995afb: Restore the documented domain payload fields on entity-driven automation triggers.
+
+  Migrated triggers declare domain-named `payloadSchema`s (incident `incidentId`; health `systemId` / `previousStatus`; catalog `systemId` / `changedFields`; dependency `dependencyId`), but Stage-2 dispatch built `trigger.payload` from the generic entity-change shape (`{ kind, id, prev, next, delta, ...next }`). Operator filters and templates reading `trigger.payload.incidentId` / `.systemId` / `.previousStatus` silently resolved to `undefined` — a regression vs the legacy hook payloads.
+
+  Changes:
+
+  - `@checkstack/automation-backend`: `registerChangeDeriver` now accepts an optional per-kind `toPayload(changed) => Record<string, unknown>` mapper (at most one per kind; a second distinct mapper throws). Stage-2's `changedToPayload` uses the registered mapper to build `trigger.payload` so it matches the kind's declared `payloadSchema`, falling back to the generic change shape for kinds without a mapper. New exported type `EntityChangePayloadMapper`.
+  - `@checkstack/incident-backend`, `@checkstack/healthcheck-backend`, `@checkstack/catalog-backend`, `@checkstack/dependency-backend`: implement and register a `toPayload` for each entity-driven kind so `trigger.payload` carries the legacy domain keys again.
+
+  Descriptive incident payload fields not derivable from the reactive entity state (`title`, `description`, `createdAt`, `resolvedAt`) are now OPTIONAL on the incident trigger `payloadSchema`s — they were always absent from an entity-driven payload.
+
+### Patch Changes
+
+- b995afb: Extract a shared `withEntityWrite` / `withEntityRemove` guard for PLUGIN-BACKED (Model B) reactive entities and refactor the per-domain copies onto it.
+
+  Every plugin-backed domain (incident, catalog, dependency, maintenance, slo, satellite) reimplemented the same "no handle wired → run the plugin write directly; handle wired → route through `handle.mutate` / `handle.remove`" guard, varying only in the id-key name. `@checkstack/automation-backend` now exports `withEntityWrite` / `withEntityRemove` (from the entity barrel) and each domain's thin, well-named wrappers (`writeIncidentEntity`, `writeMaintenanceEntity`, satellite's `mirror`, …) delegate to it, so the branch lives in exactly one place. Behavior is unchanged.
+
+  `writeHealthEntity` (healthcheck-backend) is intentionally NOT migrated onto the helper — it is genuinely bespoke (closure-captured durable state, distinct rethrow-vs-fail-soft branches, a per-system serializer, and it returns the computed state). SLO keeps its fail-soft `onError` wrapper around the shared guard.
+
+- Updated dependencies [270ef29]
+- Updated dependencies [b995afb]
+- Updated dependencies [b995afb]
+- Updated dependencies [b995afb]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [b995afb]
+- Updated dependencies [b995afb]
+- Updated dependencies [270ef29]
+- Updated dependencies [b995afb]
+- Updated dependencies [270ef29]
+- Updated dependencies [b995afb]
+- Updated dependencies [b995afb]
+- Updated dependencies [270ef29]
+- Updated dependencies [b995afb]
+- Updated dependencies [b995afb]
+- Updated dependencies [270ef29]
+- Updated dependencies [b995afb]
+- Updated dependencies [b995afb]
+- Updated dependencies [b995afb]
+- Updated dependencies [b995afb]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [b995afb]
+- Updated dependencies [b995afb]
+  - @checkstack/backend-api@0.19.0
+  - @checkstack/automation-backend@0.3.0
+  - @checkstack/gitops-common@0.5.0
+  - @checkstack/gitops-backend@0.4.0
+  - @checkstack/auth-backend@0.4.32
+  - @checkstack/cache-api@0.3.7
+  - @checkstack/command-backend@0.1.32
+  - @checkstack/cache-utils@0.2.12
+
 ## 1.2.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/catalog-backend",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "license": "Elastic-2.0",
   "type": "module",
   "main": "src/index.ts",
@@ -15,28 +15,28 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@checkstack/backend-api": "0.17.1",
-    "@checkstack/automation-backend": "0.1.0",
-    "@checkstack/cache-api": "0.3.5",
-    "@checkstack/cache-utils": "0.2.10",
-    "@checkstack/auth-common": "0.7.1",
-    "@checkstack/catalog-common": "2.2.2",
-    "@checkstack/command-backend": "0.1.30",
-    "@checkstack/auth-backend": "0.4.30",
-    "@checkstack/gitops-backend": "0.3.6",
-    "@checkstack/gitops-common": "0.4.1",
-    "@checkstack/notification-common": "1.2.0",
+    "@checkstack/backend-api": "0.18.0",
+    "@checkstack/automation-backend": "0.2.0",
+    "@checkstack/cache-api": "0.3.6",
+    "@checkstack/cache-utils": "0.2.11",
+    "@checkstack/auth-common": "0.7.2",
+    "@checkstack/catalog-common": "2.2.3",
+    "@checkstack/command-backend": "0.1.31",
+    "@checkstack/auth-backend": "0.4.31",
+    "@checkstack/gitops-backend": "0.3.7",
+    "@checkstack/gitops-common": "0.4.2",
+    "@checkstack/notification-common": "1.2.1",
     "@orpc/server": "^1.13.2",
     "drizzle-orm": "^0.45.0",
     "hono": "^4.12.14",
     "uuid": "^14.0.0",
     "zod": "^4.2.1",
-    "@checkstack/common": "0.11.0"
+    "@checkstack/common": "0.12.0"
   },
   "devDependencies": {
     "@checkstack/drizzle-helper": "0.0.5",
-    "@checkstack/scripts": "0.3.3",
-    "@checkstack/test-utils-backend": "0.1.30",
+    "@checkstack/scripts": "0.3.4",
+    "@checkstack/test-utils-backend": "0.1.31",
     "@checkstack/tsconfig": "0.0.7",
     "@types/bun": "^1.3.5",
     "@types/node": "^20.0.0",

package/src/automations.test.ts

@@ -22,7 +22,6 @@ import {
 } from "./automations";
 import type { EntityService } from "./services/entity-service";
 import type { createCatalogCache } from "./cache";
-import { catalogHooks } from "./hooks";
 
 const logger = createMockLogger() as Logger;
 
@@ -57,7 +56,10 @@ describe("catalog triggers", () => {
     const parsed = systemCreatedTrigger.payloadSchema.safeParse(payload);
     expect(parsed.success).toBe(true);
     expect(systemCreatedTrigger.contextKey?.(payload)).toBe("sys-1");
-    expect(systemCreatedTrigger.hook).toBe(catalogHooks.systemCreated);
+    // Entity-driven now (§10.4): no hook, a no-op setup keeps it in the
+    // editor catalog; the `catalog-system` deriver fires `catalog.created`.
+    expect(systemCreatedTrigger.hook).toBeUndefined();
+    expect(typeof systemCreatedTrigger.setup).toBe("function");
   });
 
   it("requires changedFields on the systemUpdated payload", () => {
@@ -128,7 +130,10 @@ interface FakeSystemRow {
 interface ActionFixture {
   service: EntityService;
   cache: ReturnType<typeof createCatalogCache>;
-  emitHookMock: ReturnType<typeof mock>;
+  mutateMock: ReturnType<typeof mock>;
+  /** Reactive states returned by each `apply()` the action drove. */
+  mutateResults: unknown[];
+  getSystemEntity: () => never;
   updateSystemMock: ReturnType<typeof mock>;
   getSystemMock: ReturnType<typeof mock>;
   invalidateTopologyMock: ReturnType<typeof mock>;
@@ -168,12 +173,30 @@ function makeFixture(args: {
     invalidateContacts: mock(async () => {}),
   } as unknown as ReturnType<typeof createCatalogCache>;
 
-  const emitHookMock = mock(async () => {});
+  // The action now drives its write through `handle.mutate({ id, apply })`:
+  // it runs `apply()` (the real `updateSystem`) once and records the id + the
+  // resulting reactive state, mirroring the framework handle.
+  const mutateResults: unknown[] = [];
+  const mutateMock = mock(
+    async (input: {
+      id: string;
+      opts?: { runId?: string };
+      apply: () => Promise<unknown>;
+    }) => {
+      const next = await input.apply();
+      mutateResults.push(next);
+      return next;
+    },
+  );
+  const getSystemEntity = () =>
+    ({ kind: "catalog-system", mutate: mutateMock }) as never;
 
   return {
     service,
     cache,
-    emitHookMock,
+    mutateMock,
+    mutateResults,
+    getSystemEntity,
     updateSystemMock,
     getSystemMock,
     invalidateTopologyMock,
@@ -192,7 +215,7 @@ describe("catalog.system.update_metadata", () => {
     const [action] = createCatalogActions({
       entityService: fx.service,
       cache: fx.cache,
-      emitHook: fx.emitHookMock as never,
+      getSystemEntity: fx.getSystemEntity,
     });
 
     const result = await action!.execute({
@@ -228,14 +251,55 @@ describe("catalog.system.update_metadata", () => {
       });
 
     expect(fx.invalidateTopologyMock).toHaveBeenCalledTimes(1);
-    expect(fx.emitHookMock).toHaveBeenCalledTimes(1);
-    const emitCall = fx.emitHookMock.mock.calls[0]!;
-    expect(emitCall[0]).toBe(catalogHooks.systemUpdated);
-    expect(emitCall[1]).toEqual({
-      systemId: "sys-1",
-      systemName: "API",
-      changedFields: ["metadata"],
+    // The old `systemUpdated` hook emission was replaced by driving the edit
+    // through the reactive `catalog-system` entity via `handle.mutate` (§10.4):
+    // the handle is keyed by system id, and `apply` returns the resulting
+    // reactive state.
+    expect(fx.mutateMock).toHaveBeenCalledTimes(1);
+    const mutateCall = fx.mutateMock.mock.calls[0]![0] as { id: string };
+    expect(mutateCall.id).toBe("sys-1");
+    expect(fx.mutateResults[0]).toEqual({
+      name: "API",
+      description: null,
+      metadata: {
+        tier: "platinum",
+        region: "eu-central-1",
+        owner: "platform",
+      },
+    });
+  });
+
+  // Fix 3 (security): the action resolves config (including `metadata` values)
+  // against the run scope, which can contain run-resolved secrets. It MUST pass
+  // `opts: { runId }` into the entity write so the framework handle masks any
+  // such secret in the `entity_transitions` rows + the cluster-wide
+  // `ENTITY_CHANGED` (the masking itself is proven end-to-end in
+  // automation-backend's mutate-handle masking test).
+  it("forwards the dispatch runId to handle.mutate (secret-masking choke point)", async () => {
+    const fx = makeFixture({
+      initialRow: { id: "sys-1", name: "API", metadata: {} },
+    });
+    const [action] = createCatalogActions({
+      entityService: fx.service,
+      cache: fx.cache,
+      getSystemEntity: fx.getSystemEntity,
+    });
+
+    await action!.execute({
+      ...ctxBase,
+      consumedArtifacts: {},
+      config: {
+        systemId: "sys-1",
+        strategy: "merge",
+        metadata: { token: "resolved-secret-value" },
+      } as never,
     });
+
+    expect(fx.mutateMock).toHaveBeenCalledTimes(1);
+    const mutateCall = fx.mutateMock.mock.calls[0]![0] as {
+      opts?: { runId?: string };
+    };
+    expect(mutateCall.opts?.runId).toBe("run-1");
   });
 
   it("replaces the whole metadata object when strategy=replace", async () => {
@@ -249,7 +313,7 @@ describe("catalog.system.update_metadata", () => {
     const [action] = createCatalogActions({
       entityService: fx.service,
       cache: fx.cache,
-      emitHook: fx.emitHookMock as never,
+      getSystemEntity: fx.getSystemEntity,
     });
 
     const result = await action!.execute({
@@ -285,7 +349,7 @@ describe("catalog.system.update_metadata", () => {
     const [action] = createCatalogActions({
       entityService: fx.service,
       cache: fx.cache,
-      emitHook: fx.emitHookMock as never,
+      getSystemEntity: fx.getSystemEntity,
     });
 
     const result = await action!.execute({
@@ -311,7 +375,7 @@ describe("catalog.system.update_metadata", () => {
     const [action] = createCatalogActions({
       entityService: fx.service,
       cache: fx.cache,
-      emitHook: fx.emitHookMock as never,
+      getSystemEntity: fx.getSystemEntity,
     });
 
     const result = await action!.execute({
@@ -329,7 +393,8 @@ describe("catalog.system.update_metadata", () => {
     expect(result.error).toMatch(/System not found/);
     expect(fx.updateSystemMock).not.toHaveBeenCalled();
     expect(fx.invalidateTopologyMock).not.toHaveBeenCalled();
-    expect(fx.emitHookMock).not.toHaveBeenCalled();
+    // The probe failed, so no entity write was driven.
+    expect(fx.mutateMock).not.toHaveBeenCalled();
   });
 
   it("returns failure if updateSystem returns undefined (race-deleted mid-update)", async () => {
@@ -347,7 +412,7 @@ describe("catalog.system.update_metadata", () => {
     const [action] = createCatalogActions({
       entityService: fx.service,
       cache: fx.cache,
-      emitHook: fx.emitHookMock as never,
+      getSystemEntity: fx.getSystemEntity,
     });
 
     const result = await action!.execute({
@@ -364,6 +429,14 @@ describe("catalog.system.update_metadata", () => {
     if (result.success) return;
     expect(result.error).toMatch(/disappeared mid-update/);
     expect(fx.invalidateTopologyMock).not.toHaveBeenCalled();
-    expect(fx.emitHookMock).not.toHaveBeenCalled();
+    // The probe found the row, so the write was driven — but `apply` fell
+    // back to the pre-write state, so the framework handle would diff it as a
+    // no-op (no spurious `catalog.updated`). The action still reports failure.
+    expect(fx.mutateMock).toHaveBeenCalledTimes(1);
+    expect(fx.mutateResults[0]).toEqual({
+      name: "API",
+      description: null,
+      metadata: {},
+    });
   });
 });

package/src/automations.ts

@@ -20,15 +20,22 @@
  * hook so downstream automations + cache subscribers see the change.
  */
 import { z } from "zod";
-import { Versioned, type Hook } from "@checkstack/backend-api";
+import { Versioned } from "@checkstack/backend-api";
 import type {
   ActionDefinition,
   TriggerDefinition,
 } from "@checkstack/automation-backend";
-
-import { catalogHooks } from "./hooks";
+import {
+  makeEntityDrivenTriggerSetup,
+  type EntityHandle,
+} from "@checkstack/automation-backend";
 import type { EntityService } from "./services/entity-service";
 import type { createCatalogCache } from "./cache";
+import {
+  toCatalogSystemState,
+  writeCatalogSystemEntity,
+  type CatalogSystemState,
+} from "./catalog-entity";
 
 // ─── Payload schemas — match the hook payloads exactly ─────────────────
 
@@ -50,6 +57,10 @@ const systemDeletedPayloadSchema = z.object({
 
 // ─── Triggers ──────────────────────────────────────────────────────────
 
+// These triggers are ENTITY-DRIVEN (§10.4): the `catalog-system` entity's
+// change deriver fires `catalog.created/.updated/.deleted` via Stage-1
+// routing, so they no longer subscribe to a hook. A no-op `setup` keeps
+// them in the editor's trigger catalog without re-introducing a hook.
 export const systemCreatedTrigger: TriggerDefinition<
   z.infer<typeof systemCreatedPayloadSchema>
 > = {
@@ -59,7 +70,9 @@ export const systemCreatedTrigger: TriggerDefinition<
   category: "Catalog",
   icon: "Activity",
   payloadSchema: systemCreatedPayloadSchema,
-  hook: catalogHooks.systemCreated,
+  setup: makeEntityDrivenTriggerSetup<
+    z.infer<typeof systemCreatedPayloadSchema>
+  >(),
   contextKey: (p) => p.systemId,
 };
 
@@ -72,7 +85,9 @@ export const systemUpdatedTrigger: TriggerDefinition<
   category: "Catalog",
   icon: "Activity",
   payloadSchema: systemUpdatedPayloadSchema,
-  hook: catalogHooks.systemUpdated,
+  setup: makeEntityDrivenTriggerSetup<
+    z.infer<typeof systemUpdatedPayloadSchema>
+  >(),
   contextKey: (p) => p.systemId,
 };
 
@@ -85,7 +100,9 @@ export const systemDeletedTrigger: TriggerDefinition<
   category: "Catalog",
   icon: "Activity",
   payloadSchema: systemDeletedPayloadSchema,
-  hook: catalogHooks.systemDeleted,
+  setup: makeEntityDrivenTriggerSetup<
+    z.infer<typeof systemDeletedPayloadSchema>
+  >(),
   contextKey: (p) => p.systemId,
 };
 
@@ -134,11 +151,12 @@ export interface CatalogActionDeps {
   entityService: EntityService;
   cache: ReturnType<typeof createCatalogCache>;
   /**
-   * `emitHook` bound during `afterPluginsReady`. Required so the
-   * action fires `systemUpdated` downstream — without it, other
-   * automations waiting on the trigger wouldn't see the change.
+   * Resolver for the reactive `catalog-system` entity (§10.4). The
+   * `update_metadata` action mirrors its edit here; the entity's change
+   * deriver fires the `catalog.updated` trigger event downstream (the old
+   * `systemUpdated` hook emission was removed).
    */
-  emitHook: <T>(hook: Hook<T>, payload: T) => Promise<void>;
+  getSystemEntity?: () => EntityHandle<CatalogSystemState> | undefined;
 }
 
 export function createCatalogActions(
@@ -159,7 +177,7 @@ export function createCatalogActions(
       schema: systemUpdateMetadataConfigSchema,
     }),
     produces: "catalog.system_record",
-    execute: async ({ config, logger }) => {
+    execute: async ({ config, logger, runId }) => {
       const existing = await deps.entityService.getSystem(config.systemId);
       if (!existing) {
         return {
@@ -175,9 +193,39 @@ export function createCatalogActions(
           ? config.metadata
           : { ...existingMetadata, ...config.metadata };
 
-      const updated = await deps.entityService.updateSystem(config.systemId, {
-        metadata: nextMetadata,
+      // Drive the update through the reactive `catalog-system` entity (§10.4);
+      // the REAL `updateSystem` runs INSIDE `apply`, so `prev` is snapshotted
+      // before the write and the deriver fires `catalog.updated`. If the row
+      // was race-deleted mid-update, `apply` falls back to the pre-write
+      // state so the diff is a no-op (no spurious `catalog.updated`), and the
+      // failure is surfaced from the captured `updated`.
+      // Capture the post-write row in a holder so TS control-flow tracks the
+      // assignment made inside the async `apply` closure (a plain `let`
+      // mutated in a closure is invisible to CFA and would narrow to `never`).
+      const captured: {
+        row: Awaited<ReturnType<typeof deps.entityService.updateSystem>> | null;
+      } = { row: null };
+      await writeCatalogSystemEntity({
+        handle: deps.getSystemEntity?.(),
+        systemId: config.systemId,
+        // Run-secret masking choke point: this action resolves config
+        // (including `metadata` values) against the run scope, which can
+        // contain run-resolved secrets. Passing `runId` masks any such secret
+        // in the `entity_transitions` rows + the cluster-wide `ENTITY_CHANGED`.
+        opts: { runId },
+        apply: async () => {
+          const row = await deps.entityService.updateSystem(config.systemId, {
+            metadata: nextMetadata,
+          });
+          captured.row = row ?? null;
+          return toCatalogSystemState({
+            name: row?.name ?? existing.name,
+            description: row?.description ?? existing.description,
+            metadata: row ? nextMetadata : existingMetadata,
+          });
+        },
       });
+      const updated = captured.row;
       if (!updated) {
         return {
           success: false,
@@ -186,11 +234,6 @@ export function createCatalogActions(
       }
 
       await deps.cache.invalidateTopology();
-      await deps.emitHook(catalogHooks.systemUpdated, {
-        systemId: updated.id,
-        systemName: updated.name,
-        changedFields: ["metadata"],
-      });
 
       logger.info(
         `Automation updated metadata on system ${updated.id} (${config.strategy})`,