@checkstack/automation-backend 0.2.0 → 0.3.0

package/src/index.ts

@@ -1,6 +1,8 @@
 import {
   createBackendPlugin,
   coreServices,
+  withXactLock,
+  type SafeDatabase,
 } from "@checkstack/backend-api";
 import {
   automationAccess,
@@ -12,7 +14,19 @@ import {
 import { resolveRoute, extractErrorMessage } from "@checkstack/common";
 import type { PluginMetadata } from "@checkstack/common";
 import { registerSearchProvider } from "@checkstack/command-backend";
-import { createDefaultFilterRegistry } from "@checkstack/template-engine";
+import {
+  createDefaultFilterRegistry,
+  type FilterRegistry,
+} from "@checkstack/template-engine";
+import { HealthCheckApi } from "@checkstack/healthcheck-common";
+import { entityKindExtensionPoint } from "@checkstack/gitops-backend";
+import { CHECKSTACK_API_VERSION } from "@checkstack/gitops-common";
+import {
+  reconcileAutomation,
+  deleteAutomationEntity,
+} from "./gitops-kinds";
+import { registerAutomationGitOpsDocumentation } from "./gitops-docs";
+import { AutomationDefinitionSchema } from "@checkstack/automation-common";
 
 import type {
   ActionDefinition,
@@ -29,12 +43,36 @@ import { createArtifactStore } from "./artifact-store";
 import { createAutomationStore } from "./automation-store";
 import { createAutomationRouter } from "./router";
 import { runWebhookSubscriptionMigration } from "./migration/from-webhook-subscriptions";
+import { runFlappingAutomationMigration } from "./migration/flapping-to-window";
 import {
   startDelayQueueConsumer,
   type DelayQueueConsumer,
 } from "./dispatch/delay-queue";
+import {
+  startDwellQueueConsumer,
+  type DwellQueueConsumer,
+} from "./dispatch/dwell-queue";
+import {
+  startWaitTimeoutQueueConsumer,
+  type WaitTimeoutQueueConsumer,
+} from "./dispatch/wait-timeout-queue";
+import {
+  startDispatchQueueConsumer,
+  type DispatchQueueConsumer,
+} from "./dispatch/stage2-dispatch";
+import {
+  startStage1Router,
+  type Stage1Router,
+} from "./dispatch/stage1-router";
+import { createDwellStore } from "./dispatch/dwell-store";
+import { createWindowStore } from "./dispatch/window-store";
 import { createRunStore } from "./dispatch/run-state";
 import { createRunStateStore } from "./dispatch/run-state-store";
+import { createRunSecretRegistry } from "./dispatch/run-secret-registry";
+import {
+  SECRET_RESOLVER_REF_ID,
+  CONNECTION_STORE_REF_ID,
+} from "./dispatch/secret-ref-ids";
 import {
   startStalledSweeper,
   type StalledSweeper,
@@ -44,10 +82,12 @@ import {
   type TriggerSubscriptions,
 } from "./dispatch/trigger-subscriber";
 import type { DispatchDeps } from "./dispatch/types";
+import { assembleDispatchGetService } from "./dispatch/assemble-get-service";
 import {
   automationActionExtensionPoint,
   automationArtifactStoreRef,
   automationArtifactTypeExtensionPoint,
+  automationFilterExtensionPoint,
   automationRegistriesRef,
   automationTriggerExtensionPoint,
 } from "./extension-points";
@@ -55,6 +95,19 @@ import {
   registerBuiltinTriggerConsumer,
   registerBuiltinTriggers,
 } from "./builtin-triggers";
+import {
+  createChangeDeriverRegistry,
+  createChangeEmitter,
+  createEntityChangedSubscriptions,
+  createEntityRegistry,
+  createEntityStore,
+  entityExtensionPoint,
+  type ChangeDeriverRegistry,
+  type ChangeEmitter,
+  type EntityChangedSubscriptions,
+  type EntityRegistry,
+} from "./entity";
+import { ENTITY_CHANGED_HOOK } from "./entity/hook";
 import {
   createNotifyUserAction,
   logAction,
@@ -73,21 +126,75 @@ interface EnvStash {
   artifactTypeRegistry: ArtifactTypeRegistry;
   dispatchDeps: DispatchDeps;
   automationStore: ReturnType<typeof createAutomationStore>;
+  entityRegistry: EntityRegistry;
+  entityChangeEmitter: ChangeEmitter;
+  entityChangedSubscriptions: EntityChangedSubscriptions;
+  changeDerivers: ChangeDeriverRegistry;
   triggerSubscriptions?: TriggerSubscriptions;
   stalledSweeper?: StalledSweeper;
   delayConsumer?: DelayQueueConsumer;
+  dwellConsumer?: DwellQueueConsumer;
+  waitTimeoutConsumer?: WaitTimeoutQueueConsumer;
+  dispatchConsumer?: DispatchQueueConsumer;
+  stage1Router?: Stage1Router;
 }
 
 export default createBackendPlugin({
   metadata: pluginMetadata,
 
   register(env) {
+    // Mutable DB ref — populated in init(), consumed by the GitOps
+    // reconcile/delete closures (only called during sync, after init).
+    let gitopsDb: SafeDatabase<typeof schema> | undefined;
+
     const triggerRegistry = createTriggerRegistry();
     const actionRegistry = createActionRegistry();
     const artifactTypeRegistry = createArtifactTypeRegistry();
+    // Shared filter registry — seeded with the built-in defaults (incl.
+    // the Wave-2 duration helpers) and extended by plugins via the
+    // filter extension point in Phase 1. The dispatch engine reads from
+    // this same instance, so plugin filters are live by `init()`.
+    const filterRegistry: FilterRegistry = createDefaultFilterRegistry();
+
+    // Run-scoped secret registry — created here in `register()` (it has no
+    // deps) so the SAME instance backs both the dispatch masking choke
+    // points (wired in `init()`) and the entity-store masking choke point
+    // (run-originated entity writes mask through this in the handle).
+    const secretRegistry = createRunSecretRegistry();
+
+    // Entity state machine (reactive automation engine §4). The change
+    // emitter buffers until `emitHook` is wired in `afterPluginsReady`
+    // (§3.7); the registry exposes `defineEntity` / `declareNonReactiveState`
+    // through the extension point below, callable from other plugins'
+    // `register`/`init`. The DB-backed store is bound in `init()` (after
+    // migrations run).
+    const entityChangeEmitter = createChangeEmitter();
+    const entityRegistry = createEntityRegistry({
+      secretRegistry,
+      emitter: entityChangeEmitter,
+    });
+
+    // Reactive dispatch pipeline (reactive automation engine §7). The
+    // change-deriver registry maps a kind's change → trigger event id(s)
+    // for Stage-1 routing; per-domain derivers are registered in Phase 4.
+    // The entity-changed subscription service rides ENTITY_CHANGED (filtered
+    // by kind) so other plugins can react without touching the internal hook
+    // (§6.1). Both buffer registrations made before afterPluginsReady wires
+    // the real `onHook`.
+    const changeDerivers = createChangeDeriverRegistry();
+    const entityChangedSubscriptions = createEntityChangedSubscriptions();
 
     env.registerAccessRules(automationAccessRules);
 
+    // Phase 1: register the entity extension point so other plugins can
+    // resolve it and call `defineEntity` during their own register/init.
+    env.registerExtensionPoint(entityExtensionPoint, {
+      defineEntity: entityRegistry.defineEntity,
+      declareNonReactiveState: entityRegistry.declareNonReactiveState,
+      onEntityChanged: entityChangedSubscriptions.onEntityChanged,
+      registerChangeDeriver: (input) => changeDerivers.register(input),
+    });
+
     env.registerExtensionPoint(automationTriggerExtensionPoint, {
       registerTrigger: <TPayload, TConfig = void>(
         definition: TriggerDefinition<TPayload, TConfig>,
@@ -124,6 +231,64 @@ export default createBackendPlugin({
       },
     });
 
+    // Filters registered by plugins in Phase 1 are collected here and
+    // applied (with collision-warning) in `init()` where a logger is
+    // available. Collecting first keeps `register()` logger-free.
+    const pendingFilters: Array<{
+      name: string;
+      filter: Parameters<FilterRegistry["register"]>[1];
+      pluginId: string;
+    }> = [];
+    env.registerExtensionPoint(automationFilterExtensionPoint, {
+      registerFilter: (definition, metadata) => {
+        pendingFilters.push({
+          name: definition.name,
+          filter: definition.filter,
+          pluginId: metadata.pluginId,
+        });
+      },
+    });
+
+    // GitOps `Automation` kind. The DB isn't available until init(), so a
+    // mutable ref is populated there and read by the reconcile closures
+    // (only invoked during sync, well after init) — mirrors catalog-backend.
+    const kindRegistry = env.getExtensionPoint(entityKindExtensionPoint);
+    kindRegistry.registerKind({
+      apiVersion: CHECKSTACK_API_VERSION,
+      kind: "Automation",
+      specSchema: AutomationDefinitionSchema,
+      reconcile: async ({ entity, existingEntityId, context }) => {
+        if (!gitopsDb) throw new Error("Automation database not initialized");
+        return reconcileAutomation(gitopsDb, {
+          entity,
+          existingEntityId,
+          logger: context.logger,
+        });
+      },
+      delete: async ({ entityId, context }) => {
+        if (!gitopsDb) throw new Error("Automation database not initialized");
+        await deleteAutomationEntity(gitopsDb, {
+          entityId,
+          logger: context.logger,
+        });
+      },
+    });
+
+    // Register the GitOps spec-schema documentation PROVIDER for the
+    // `Automation` kind HERE in register() (not afterPluginsReady). It is a
+    // LAZY provider: it re-reads the trigger/action registries on every
+    // kind-browser query (`describeKinds()`), so it needs no populated
+    // registries at registration time — registering it early, before any
+    // init / afterPluginsReady ordering, guarantees it is always present.
+    // Surfaces each trigger's / provider action's config schema in the Kind
+    // Registry, conditioned on the chosen `triggers[].event` /
+    // `actions[].action`.
+    registerAutomationGitOpsDocumentation({
+      kindRegistry,
+      triggerRegistry,
+      actionRegistry,
+    });
+
     env.registerInit({
       schema,
       deps: {
@@ -132,6 +297,7 @@ export default createBackendPlugin({
         rpcClient: coreServices.rpcClient,
         queueManager: coreServices.queueManager,
         signalService: coreServices.signalService,
+        advisoryLock: coreServices.advisoryLock,
       },
       init: async ({
         logger,
@@ -140,14 +306,37 @@ export default createBackendPlugin({
         rpcClient,
         queueManager,
         signalService,
+        advisoryLock,
       }) => {
         logger.debug("⚙️  Initializing Automation Backend...");
 
-        const artifactStore = createArtifactStore(database);
-        const runStore = createRunStore(database);
-        const runStateStore = createRunStateStore(database);
+        // Populate the mutable DB ref the GitOps reconcile closures read.
+        gitopsDb = database as SafeDatabase<typeof schema>;
+
+        // Run-scoped secret registry: created in `register()` (the SAME
+        // instance) so it accumulates every secret value resolved during a
+        // run and every persistence choke point (run store step/run output,
+        // run-state scope snapshot, artifact data, AND run-originated entity
+        // writes) masks before write.
+        const artifactStore = createArtifactStore(database, secretRegistry);
+        const runStore = createRunStore(database, logger, secretRegistry);
+        const runStateStore = createRunStateStore(
+          database,
+          advisoryLock,
+          secretRegistry,
+        );
+        const dwellStore = createDwellStore(database);
+        const windowStore = createWindowStore(database);
         const automationStore = createAutomationStore(database);
 
+        // Bind the DB-backed transition store to the registry (the extension
+        // point impl registered in `register()` forwards through it). Model B:
+        // the transition store owns the tx + `entity_transitions` log for
+        // EVERY kind. Bound here in `init()` — after migrations have run — so
+        // the table exists.
+        const entityStore = createEntityStore(database);
+        entityRegistry.setStore({ store: entityStore });
+
         env.registerService(automationArtifactStoreRef, artifactStore);
         env.registerService(automationRegistriesRef, {
           triggers: triggerRegistry,
@@ -188,9 +377,21 @@ export default createBackendPlugin({
         );
         await registerBuiltinTriggerConsumer({ queueManager, logger });
 
+        // Apply plugin-contributed filters collected in register(),
+        // skipping any that would shadow a built-in (warn, don't clobber).
+        for (const pf of pendingFilters) {
+          if (filterRegistry.has(pf.name)) {
+            logger.warn(
+              `Plugin ${pf.pluginId} tried to register filter "${pf.name}" which already exists; skipping.`,
+            );
+            continue;
+          }
+          filterRegistry.register(pf.name, pf.filter);
+        }
+
         const dispatchDeps: DispatchDeps = {
           logger,
-          filters: createDefaultFilterRegistry(),
+          filters: filterRegistry,
           registries: {
             triggers: triggerRegistry,
             actions: actionRegistry,
@@ -199,12 +400,40 @@ export default createBackendPlugin({
           artifactStore,
           runStore,
           runStateStore,
+          dwellStore,
+          windowStore,
           queueManager,
-          getService: async () => {
-            throw new Error(
-              "getService not yet wired — automation dispatch invoked too early",
-            );
-          },
+          // Sensing-layer scope pre-resolution reads live health state
+          // through this client. forPlugin is lazy; the actual RPC only
+          // fires at evaluation time.
+          healthCheckClient: rpcClient.forPlugin(HealthCheckApi),
+          // Kind-agnostic entity resolver for reactive `wait_until` wake
+          // re-evaluation (Model B): the registry routes each kind to its
+          // plugin `read` accessor. Unknown kinds
+          // yield `undefined` (enrichment leaves them unresolved, fail-open).
+          // This is what lets a wait on `state.<kind>.<id>` (incident, slo, …)
+          // re-evaluate correctly when that kind changes (not just health).
+          entityResolverFor: (kind) => entityRegistry.entityResolverFor(kind),
+          // Registry-backed resolution of provider-action deps (connection
+          // store, secret resolver, ...) at execute time. Safe here because
+          // dispatch only runs from afterPluginsReady onward, by which point
+          // every service is registered. `env.getService` resolves through
+          // the real ServiceRegistry and throws clearly on a missing ref.
+          getService: assembleDispatchGetService({
+            envGetService: env.getService,
+          }),
+          // Run-wide secret masking: the engine wraps each run's getService
+          // to register resolved secrets here, and the run store masks step
+          // / run output before persistence.
+          secretRegistry,
+          secretResolverRefId: SECRET_RESOLVER_REF_ID,
+          connectionStoreRefId: CONNECTION_STORE_REF_ID,
+          // Serialize the concurrency-mode check-then-create with a
+          // transaction-scoped advisory lock (blocks until granted,
+          // auto-releases at COMMIT) so racing fires can't double-run a
+          // single-mode automation.
+          withConcurrencyLock: <T>(key: string, fn: () => Promise<T>) =>
+            withXactLock({ db: database, key, fn: () => fn() }),
         };
 
         const stash = env as unknown as EnvStash;
@@ -213,6 +442,10 @@ export default createBackendPlugin({
         stash.artifactTypeRegistry = artifactTypeRegistry;
         stash.dispatchDeps = dispatchDeps;
         stash.automationStore = automationStore;
+        stash.entityRegistry = entityRegistry;
+        stash.entityChangeEmitter = entityChangeEmitter;
+        stash.entityChangedSubscriptions = entityChangedSubscriptions;
+        stash.changeDerivers = changeDerivers;
 
         const router = createAutomationRouter({
           db: database,
@@ -260,19 +493,43 @@ export default createBackendPlugin({
         env.registerCleanup(async () => {
           const s = env as unknown as EnvStash;
           await s.triggerSubscriptions?.dispose();
+          await s.stage1Router?.dispose();
+          await s.entityChangedSubscriptions?.disposeAll();
           s.stalledSweeper?.stop();
           await s.delayConsumer?.stop();
+          await s.dwellConsumer?.stop();
+          await s.waitTimeoutConsumer?.stop();
+          await s.dispatchConsumer?.stop();
         });
 
         logger.debug("✅ Automation Backend initialized.");
       },
 
-      afterPluginsReady: async ({ database, logger, onHook, rpcClient }) => {
+      afterPluginsReady: async ({
+        database,
+        logger,
+        onHook,
+        emitHook,
+        rpcClient,
+      }) => {
         const stash = env as unknown as EnvStash;
         const triggers = stash.triggerRegistry.getTriggers();
         const actions = stash.actionRegistry.getActions();
         const artifactTypes = stash.artifactTypeRegistry.getArtifactTypes();
 
+        // Wire the deferred entity-change emitter to the real `emitHook`
+        // (only injectable here — §3.7). Any change events buffered during
+        // the init / afterPluginsReady window are flushed in order now, so
+        // there is no silent no-emit gap.
+        await stash.entityChangeEmitter.wire((payload) =>
+          emitHook(ENTITY_CHANGED_HOOK, payload),
+        );
+
+        // Wire the public cross-plugin entity-change subscription service
+        // (§6.1). Subscriptions registered by other plugins during their
+        // register/init are bound to the real `onHook` now.
+        stash.entityChangedSubscriptions.wire({ onHook, logger });
+
         logger.debug(
           `⚙️  Registered ${triggers.length} automation triggers${
             triggers.length > 0
@@ -313,6 +570,46 @@ export default createBackendPlugin({
           logger,
         });
 
+        // `for:` dwell: register the consumer that fires when a dwell's
+        // scheduled job pops, re-confirming state before starting the run.
+        stash.dwellConsumer = await startDwellQueueConsumer({
+          deps: stash.dispatchDeps,
+          automationStore: stash.automationStore,
+          logger,
+        });
+
+        // Reactive `wait_until` timeout timer: the consumer that fires when
+        // a suspended wait's single deadline job pops, applying the
+        // continue/fail-on-timeout policy. Reactive waits are otherwise woken
+        // by Stage-1 routing on a relevant ENTITY_CHANGED (no polling).
+        stash.waitTimeoutConsumer = await startWaitTimeoutQueueConsumer({
+          deps: stash.dispatchDeps,
+          automationStore: stash.automationStore,
+          logger,
+        });
+
+        // Stage-2 dispatch fan-out: the consumer that runs each per-run
+        // dispatch job enqueued by Stage-1 routing (reason: trigger →
+        // dispatchTrigger; reason: wake → resume the suspended wait_until).
+        stash.dispatchConsumer = await startDispatchQueueConsumer({
+          deps: stash.dispatchDeps,
+          automationStore: stash.automationStore,
+          changeDerivers: stash.changeDerivers,
+          logger,
+        });
+
+        // Stage-1 routing: claim each ENTITY_CHANGED on the
+        // `automation-entity-route` work-queue (exactly one instance), do
+        // cheap indexed routing (wake-index intersection + trigger-event
+        // derivation), and enqueue Stage-2 jobs.
+        stash.stage1Router = await startStage1Router({
+          deps: stash.dispatchDeps,
+          automationStore: stash.automationStore,
+          changeDerivers: stash.changeDerivers,
+          onHook,
+          logger,
+        });
+
         // Restart safety + horizontal scaling: periodically scan for
         // runs whose heartbeat is older than the threshold and resume
         // them under an advisory lock.
@@ -340,6 +637,19 @@ export default createBackendPlugin({
           );
         }
 
+        // One-time migration: rewrite legacy `healthcheck.flapping_detected`
+        // triggers onto the generic windowed-count gate over
+        // `healthcheck.system_health_changed` (the flapping trigger + hook
+        // were removed). Idempotent — already-migrated / non-flapping rows are
+        // skipped — so it is safe to run on every boot.
+        try {
+          await runFlappingAutomationMigration({ db: database, logger });
+        } catch (error) {
+          logger.error(
+            `Flapping automation migration failed unexpectedly: ${extractErrorMessage(error, "unknown error")}`,
+          );
+        }
+
         logger.debug("✅ Automation Backend afterPluginsReady complete.");
       },
     });
@@ -356,6 +666,37 @@ export {
   automationArtifactStoreRef,
 } from "./extension-points";
 
+// Entity state machine — the typed path to reactive state. The internal
+// ENTITY_CHANGED hook is intentionally NOT re-exported (§6.1).
+export { entityExtensionPoint } from "./entity";
+export { withEntityWrite, withEntityRemove } from "./entity";
+export type {
+  EntityExtensionPoint,
+  DefineEntity,
+  DefineEntityInput,
+  DeclareNonReactiveState,
+  DeclareNonReactiveStateInput,
+  EntityHandle,
+  EntityMutationOpts,
+  EntityRead,
+  MutateInput,
+  RemoveInput,
+  EntityTx,
+  EntityChangeDeriver,
+  EntityChangePayloadMapper,
+  RegisterChangeDeriver,
+  OnEntityChanged,
+  OnEntityChangedInput,
+  EntityChangedHandler,
+  EntityChangedDelivery,
+  EntityChangedUnsubscribe,
+} from "./entity";
+
+// The validated entity-change payload (Phase 4 derivers + cross-plugin
+// consumers type against this). Re-exported from automation-common so a
+// domain plugin needs only the automation-backend dependency.
+export type { EntityChanged } from "@checkstack/automation-common";
+
 export type {
   TriggerDefinition,
   ActionDefinition,
@@ -371,9 +712,12 @@ export type {
   TriggerTeardown,
 } from "./action-types";
 
+export { makeEntityDrivenTriggerSetup } from "./entity-driven-trigger";
+
 export type { ArtifactStore, PersistedArtifact } from "./artifact-store";
 export type { TriggerRegistry } from "./trigger-registry";
 export type { ActionRegistry } from "./action-registry";
 export type { ArtifactTypeRegistry } from "./artifact-type-registry";
 export type { AutomationRegistries } from "./extension-points";
 export type { AutomationStore } from "./automation-store";
+export type { LoadedAutomation } from "./dispatch/types";

package/src/migration/flapping-to-window.test.ts

@@ -0,0 +1,123 @@
+import { describe, expect, it } from "bun:test";
+
+import {
+  DEFAULT_FLAPPING_COUNT,
+  DEFAULT_FLAPPING_MINUTES,
+  FLAPPING_FILTER,
+  HEALTH_CHANGED_EVENT,
+  LEGACY_FLAPPING_EVENT,
+  rewriteFlappingTriggers,
+} from "./flapping-to-window";
+
+function def(triggers: unknown[]): Record<string, unknown> {
+  return {
+    name: "Flapping",
+    triggers,
+    conditions: [],
+    actions: [{ action: "incident.create", config: {} }],
+    mode: "single",
+    max_runs: 1,
+  };
+}
+
+describe("rewriteFlappingTriggers", () => {
+  it("maps {transitions, windowMinutes} → window {count, minutes, refire: once}", () => {
+    const out = rewriteFlappingTriggers(
+      def([
+        {
+          id: "flap",
+          event: LEGACY_FLAPPING_EVENT,
+          config: { transitions: 5, windowMinutes: 15 },
+        },
+      ]),
+    );
+    expect(out.rewritten).toBe(1);
+    const triggers = out.definition["triggers"] as Record<string, unknown>[];
+    expect(triggers[0]).toEqual({
+      id: "flap",
+      event: HEALTH_CHANGED_EVENT,
+      filter: FLAPPING_FILTER,
+      window: { count: 5, minutes: 15, refire: "once" },
+    });
+    // config is dropped
+    expect("config" in triggers[0]!).toBe(false);
+  });
+
+  it("applies 3/60 defaults when config is missing", () => {
+    const out = rewriteFlappingTriggers(
+      def([{ event: LEGACY_FLAPPING_EVENT }]),
+    );
+    const triggers = out.definition["triggers"] as Record<string, unknown>[];
+    expect(triggers[0]!["window"]).toEqual({
+      count: DEFAULT_FLAPPING_COUNT,
+      minutes: DEFAULT_FLAPPING_MINUTES,
+      refire: "once",
+    });
+  });
+
+  it("applies defaults for a PARTIAL config", () => {
+    const out = rewriteFlappingTriggers(
+      def([
+        { event: LEGACY_FLAPPING_EVENT, config: { transitions: 7 } },
+      ]),
+    );
+    const triggers = out.definition["triggers"] as Record<string, unknown>[];
+    expect(triggers[0]!["window"]).toEqual({
+      count: 7,
+      minutes: DEFAULT_FLAPPING_MINUTES,
+      refire: "once",
+    });
+  });
+
+  it("replaces a pre-existing filter with the canonical one (safe option) and reports it", () => {
+    const out = rewriteFlappingTriggers(
+      def([
+        {
+          event: LEGACY_FLAPPING_EVENT,
+          filter: 'trigger.payload.systemId == "sys-1"',
+          config: { transitions: 3, windowMinutes: 60 },
+        },
+      ]),
+    );
+    expect(out.replacedFilter).toBe(true);
+    const triggers = out.definition["triggers"] as Record<string, unknown>[];
+    expect(triggers[0]!["filter"]).toBe(FLAPPING_FILTER);
+  });
+
+  it("preserves non-flapping triggers untouched", () => {
+    const out = rewriteFlappingTriggers(
+      def([
+        { event: "healthcheck.check_failed" },
+        { event: LEGACY_FLAPPING_EVENT, config: { transitions: 2 } },
+      ]),
+    );
+    expect(out.rewritten).toBe(1);
+    const triggers = out.definition["triggers"] as Record<string, unknown>[];
+    expect(triggers[0]).toEqual({ event: "healthcheck.check_failed" });
+    expect(triggers[1]!["event"]).toBe(HEALTH_CHANGED_EVENT);
+  });
+
+  it("is idempotent: a definition with no flapping trigger is left untouched", () => {
+    const input = def([{ event: HEALTH_CHANGED_EVENT, window: { count: 3, minutes: 60, refire: "once" } }]);
+    const out = rewriteFlappingTriggers(input);
+    expect(out.rewritten).toBe(0);
+    expect(out.definition).toBe(input); // same reference, untouched
+  });
+
+  it("rewrites multiple flapping triggers in one definition", () => {
+    const out = rewriteFlappingTriggers(
+      def([
+        { id: "a", event: LEGACY_FLAPPING_EVENT, config: { transitions: 2, windowMinutes: 10 } },
+        { id: "b", event: LEGACY_FLAPPING_EVENT },
+      ]),
+    );
+    expect(out.rewritten).toBe(2);
+    const triggers = out.definition["triggers"] as Record<string, unknown>[];
+    expect(triggers[0]!["window"]).toEqual({ count: 2, minutes: 10, refire: "once" });
+    expect(triggers[1]!["window"]).toEqual({
+      count: DEFAULT_FLAPPING_COUNT,
+      minutes: DEFAULT_FLAPPING_MINUTES,
+      refire: "once",
+    });
+  });
+});