deepline 0.3.88 → 0.3.89

package/dist/bundling-sources/shared_libs/product-notifications/catalog.ts

@@ -0,0 +1,877 @@
+import type {
+  ProductNotificationDefaultRule,
+  ProductNotificationFacts,
+  ProductNotificationRepeatMode,
+  ProductNotificationTrigger,
+} from './configuration';
+import { PRODUCT_NOTIFICATION_EVENT_CATALOG } from './contract';
+import {
+  ProductNotificationEvent,
+  getProductNotificationEventDefinition,
+  productNotificationTriggerIsAllowed,
+  type ProductNotificationEventName,
+} from './events';
+import { legacySlackNotificationType } from './legacy-slack';
+import type { NotificationText } from './content';
+
+type NotificationTypeDefinition = {
+  id: string;
+  eventName: ProductNotificationEventName;
+  requiredFilter: ProductNotificationFacts;
+  allowedTriggers: ProductNotificationTrigger['kind'][];
+};
+
+/**
+ * The sections the configuration surface skims by. Declared here so UI, API,
+ * and CLI order and label them identically.
+ */
+export const PRODUCT_NOTIFICATION_CATEGORIES = [
+  { id: 'credits', name: 'Credits and usage' },
+  { id: 'plays', name: 'Play runs' },
+] as const;
+
+export type ProductNotificationCategoryId =
+  (typeof PRODUCT_NOTIFICATION_CATEGORIES)[number]['id'];
+
+type ProductNotificationTypeCatalogMetadata = {
+  name: string;
+  description: string;
+  category: ProductNotificationCategoryId;
+  allowMultiple: boolean;
+  editor:
+    | {
+        kind: 'threshold';
+        label: string;
+        defaultThreshold: number;
+        minimum: number;
+        maximum?: number;
+        suffix?: string;
+        /**
+         * When set, editors show and accept `remainingOf - threshold` (for
+         * example percent remaining) while the stored trigger stays in the
+         * runtime's "used" terms. Bounds and defaults are stored values.
+         */
+        remainingOf?: number;
+      }
+    | { kind: 'play_failure'; defaultFailureCount: number }
+    | { kind: 'play_scope' }
+    | { kind: 'none' };
+};
+
+export type ProductNotificationPresentation = {
+  title: string;
+  summary: NotificationText;
+  details: NotificationText[];
+  targetUrl: string;
+  subjectKind: string;
+  subjectId: string;
+};
+
+type ProductNotificationRuleInput = {
+  ruleKey: string;
+  groupKey: string;
+  notificationType: ConfigurableProductNotificationType;
+  threshold?: number;
+  playFailure?: ProductNotificationPlayFailureSettings;
+};
+
+type ProductNotificationRuleBase = Omit<
+  ProductNotificationDefaultRule,
+  'trigger'
+>;
+
+type ProductNotificationRuleDefinition = {
+  default?: { ruleKey: string; groupKey: string };
+  conditionSubject?: 'workspace';
+  rearm?: {
+    eventName: ProductNotificationEventName;
+    matches: (payload: ProductNotificationFacts) => boolean;
+  };
+  create?: (
+    input: ProductNotificationRuleInput,
+    base: ProductNotificationRuleBase,
+    editor: ProductNotificationTypeCatalogMetadata['editor'],
+  ) => ProductNotificationDefaultRule;
+  validate?: (trigger: ProductNotificationTrigger) => void;
+  present?: (input: {
+    payload: ProductNotificationFacts;
+    trigger: ProductNotificationTrigger;
+  }) => ProductNotificationPresentation;
+};
+
+type NotificationTypeRegistration = NotificationTypeDefinition & {
+  catalog?: ProductNotificationTypeCatalogMetadata;
+  rule?: ProductNotificationRuleDefinition;
+};
+
+function validateInsufficientCreditDisable(
+  trigger: ProductNotificationTrigger,
+) {
+  if (
+    trigger.kind !== 'state_transition' ||
+    trigger.targetState !== 'disabled' ||
+    trigger.reasonCode !== 'insufficient_credits'
+  ) {
+    throw new Error(
+      'Insufficient-credit rules must enter disabled for insufficient_credits.',
+    );
+  }
+}
+
+function validateFailedOutcome(trigger: ProductNotificationTrigger) {
+  if (trigger.kind === 'consecutive_outcomes' && trigger.outcome !== 'failed') {
+    throw new Error('Failure rules require failed consecutive outcomes.');
+  }
+}
+
+function playRunPresentation(
+  payload: ProductNotificationFacts,
+  succeeded: boolean,
+): ProductNotificationPresentation {
+  return {
+    title: succeeded ? 'Play succeeded' : 'Play failed',
+    summary: [
+      `${payload.playName} ${succeeded ? 'succeeded' : 'failed'} in your `,
+      { workspace: true },
+      '.',
+    ],
+    details: [`Run: ${payload.runId}`],
+    targetUrl: String(payload.targetUrl),
+    subjectKind: 'play',
+    subjectId: String(payload.playId),
+  };
+}
+
+function webhookDeliveryPresentation(
+  payload: ProductNotificationFacts,
+  succeeded: boolean,
+): ProductNotificationPresentation {
+  return {
+    title: succeeded ? 'Webhook delivery succeeded' : 'Webhook delivery failed',
+    summary: [
+      `${payload.endpointName} delivery ${succeeded ? 'succeeded' : 'failed'} in your `,
+      { workspace: true },
+      '.',
+    ],
+    details: [`Delivery: ${payload.deliveryId}`],
+    targetUrl: String(payload.targetUrl),
+    subjectKind: 'webhook',
+    subjectId: String(payload.endpointId),
+  };
+}
+
+/** Narrow a Play rule to all Plays, one trigger kind, or a single Play. */
+function applyPlayScope(
+  eventFilter: ProductNotificationFacts,
+  settings: ProductNotificationPlayFailureSettings,
+) {
+  if (settings.scope === 'cron') eventFilter.triggerKind = 'cron';
+  if (settings.scope === 'webhook') eventFilter.triggerKind = 'webhook';
+  if (settings.scope === 'specific') {
+    if (!settings.playId) throw new Error('Choose a specific Play.');
+    eventFilter.playId = settings.playId;
+    if (settings.playName) eventFilter.playName = settings.playName;
+  }
+  return eventFilter;
+}
+
+function defaultThreshold(
+  editor: ProductNotificationTypeCatalogMetadata['editor'],
+) {
+  if (editor.kind !== 'threshold') {
+    throw new Error('Threshold rules require a threshold editor.');
+  }
+  return editor.defaultThreshold;
+}
+
+function formatCredits(value: number): string {
+  return value.toLocaleString('en-US', { maximumFractionDigits: 2 });
+}
+
+/** One canonical registry owns every notification type's runtime and UI metadata. */
+const PRODUCT_NOTIFICATION_TYPE_REGISTRY = [
+  {
+    id: 'monitor.disabled.insufficient_credits',
+    eventName: ProductNotificationEvent.MonitorLifecycleChanged,
+    requiredFilter: {},
+    allowedTriggers: ['state_transition'],
+    catalog: {
+      name: 'Monitor disabled due to insufficient credits',
+      category: 'credits',
+      description:
+        'Notify when Deepline disables a Monitor because the workspace ran out of credits.',
+      allowMultiple: false,
+      editor: { kind: 'none' },
+    },
+    rule: {
+      conditionSubject: 'workspace',
+      rearm: {
+        eventName: ProductNotificationEvent.CreditsBalanceChanged,
+        matches: (payload) =>
+          Number(payload.currentCredits) > Number(payload.previousCredits),
+      },
+      create: (_input, base) => ({
+        ...base,
+        trigger: {
+          kind: 'state_transition',
+          targetState: 'disabled',
+          reasonCode: 'insufficient_credits',
+        },
+      }),
+      validate: validateInsufficientCreditDisable,
+      present: ({ payload }) => ({
+        title: 'Monitor disabled due to insufficient credits',
+        summary: [
+          `${payload.monitorName} was disabled because your `,
+          { workspace: true },
+          ' ran out of credits.',
+        ],
+        details: [],
+        targetUrl: String(payload.targetUrl),
+        subjectKind: 'monitor',
+        subjectId: String(payload.monitorId),
+      }),
+    },
+  },
+  {
+    id: 'play.disabled.insufficient_credits',
+    eventName: ProductNotificationEvent.PlayLifecycleChanged,
+    requiredFilter: {},
+    allowedTriggers: ['state_transition'],
+    catalog: {
+      name: 'Play temporarily disabled due to insufficient credits',
+      category: 'credits',
+      description:
+        'Notify when Deepline temporarily disables a scheduled Play because the workspace ran out of credits. Future runs resume automatically once the workspace has enough credits.',
+      allowMultiple: false,
+      editor: { kind: 'none' },
+    },
+    rule: {
+      default: { ruleKey: 'default.play_disabled', groupKey: 'default' },
+      conditionSubject: 'workspace',
+      rearm: {
+        eventName: ProductNotificationEvent.CreditsBalanceChanged,
+        matches: (payload) =>
+          Number(payload.currentCredits) > Number(payload.previousCredits),
+      },
+      create: (_input, base) => ({
+        ...base,
+        trigger: {
+          kind: 'state_transition',
+          targetState: 'disabled',
+          reasonCode: 'insufficient_credits',
+        },
+      }),
+      validate: validateInsufficientCreditDisable,
+      present: ({ payload }) => ({
+        title: 'Play temporarily disabled due to insufficient credits',
+        summary: [
+          `${payload.playName} was temporarily disabled because your `,
+          { workspace: true },
+          ' ran out of credits.',
+        ],
+        details: [
+          'Future scheduled runs will resume automatically once the workspace has enough credits.',
+          'Missed runs will not be replayed.',
+        ],
+        targetUrl: String(payload.targetUrl),
+        subjectKind: 'play',
+        subjectId: String(payload.playId),
+      }),
+    },
+  },
+  {
+    id: 'usage.monthly.limit_reached',
+    eventName: ProductNotificationEvent.CreditsUsageRecorded,
+    requiredFilter: {},
+    allowedTriggers: ['threshold_crossing'],
+    catalog: {
+      name: 'Usage limit reached',
+      category: 'credits',
+      description: 'Notify when monthly usage reaches the workspace limit.',
+      allowMultiple: false,
+      editor: { kind: 'none' },
+    },
+    rule: {
+      default: {
+        ruleKey: 'default.usage_limit_reached',
+        groupKey: 'default',
+      },
+      conditionSubject: 'workspace',
+      create: (_input, base) => ({
+        ...base,
+        trigger: {
+          kind: 'threshold_crossing',
+          direction: 'at_or_above',
+          threshold: 100,
+          unit: 'percent',
+        },
+      }),
+      validate: (trigger) => {
+        if (
+          trigger.kind !== 'threshold_crossing' ||
+          trigger.direction !== 'at_or_above' ||
+          trigger.unit !== 'percent' ||
+          trigger.threshold !== 100
+        ) {
+          throw new Error('Usage-limit-reached rules must cross 100 percent.');
+        }
+      },
+      present: ({ payload }) => {
+        const actualUsage = Number(payload.actualUsage ?? payload.currentUsage);
+        return {
+          title: 'Usage limit reached',
+          summary:
+            payload.limitDenied === true
+              ? [
+                  'An operation was blocked by your ',
+                  { workspace: true },
+                  ' monthly usage limit.',
+                ]
+              : [
+                  'Your ',
+                  { workspace: true },
+                  ' reached its monthly usage limit.',
+                ],
+          details: [
+            [
+              'Current usage: ',
+              {
+                strong: `${formatCredits(actualUsage)} of ${formatCredits(Number(payload.limit))}`,
+              },
+              ` ${payload.unit}`,
+            ],
+          ],
+          targetUrl: String(payload.targetUrl),
+          subjectKind: 'workspace',
+          subjectId: String(payload.accountId),
+        };
+      },
+    },
+  },
+  {
+    id: 'credits.low',
+    eventName: ProductNotificationEvent.CreditsBalanceChanged,
+    requiredFilter: {},
+    allowedTriggers: ['threshold_crossing'],
+    catalog: {
+      name: 'Low credit warning',
+      category: 'credits',
+      description:
+        'Notify when the workspace credit balance crosses below a threshold.',
+      allowMultiple: false,
+      editor: {
+        kind: 'threshold',
+        label: 'Credit threshold',
+        defaultThreshold: 10,
+        minimum: 0,
+      },
+    },
+    rule: {
+      default: { ruleKey: 'default.low_credits', groupKey: 'default' },
+      conditionSubject: 'workspace',
+      create: (input, base, editor) => ({
+        ...base,
+        trigger: {
+          kind: 'threshold_crossing',
+          direction: 'below',
+          threshold: input.threshold ?? defaultThreshold(editor),
+          unit: 'credits',
+        },
+      }),
+      validate: (trigger) => {
+        if (
+          trigger.kind !== 'threshold_crossing' ||
+          trigger.direction !== 'below' ||
+          (trigger.unit !== undefined && trigger.unit !== 'credits')
+        ) {
+          throw new Error(
+            'Low-credit rules must cross below a credit threshold.',
+          );
+        }
+        if (!Number.isFinite(trigger.threshold) || trigger.threshold < 0) {
+          throw new Error(
+            'Low-credit thresholds must be finite and nonnegative.',
+          );
+        }
+      },
+      present: ({ payload, trigger }) => {
+        if (trigger.kind !== 'threshold_crossing') {
+          throw new Error('Low-credit presentation requires a threshold.');
+        }
+        return {
+          title: 'Low credit balance',
+          summary: [
+            'Your ',
+            { workspace: true },
+            ` credit balance crossed below ${formatCredits(trigger.threshold)} credits.`,
+          ],
+          details: [
+            [
+              'Current balance: ',
+              { strong: formatCredits(Number(payload.currentCredits)) },
+              ' credits',
+            ],
+          ],
+          targetUrl: String(payload.targetUrl),
+          subjectKind: 'workspace',
+          subjectId: String(payload.accountId),
+        };
+      },
+    },
+  },
+  {
+    id: 'usage.monthly.nearing_limit',
+    eventName: ProductNotificationEvent.CreditsUsageRecorded,
+    requiredFilter: {},
+    allowedTriggers: ['threshold_crossing'],
+    catalog: {
+      name: 'Usage limit warning',
+      category: 'credits',
+      description:
+        'Notify when only a configurable percentage of the monthly usage limit remains.',
+      allowMultiple: false,
+      editor: {
+        kind: 'threshold',
+        label: 'Remaining usage',
+        // Stored as percent used; shown as percent remaining (default 10%).
+        defaultThreshold: 90,
+        minimum: 1,
+        maximum: 99,
+        suffix: '%',
+        remainingOf: 100,
+      },
+    },
+    rule: {
+      conditionSubject: 'workspace',
+      create: (input, base, editor) => ({
+        ...base,
+        trigger: {
+          kind: 'threshold_crossing',
+          direction: 'at_or_above',
+          threshold: input.threshold ?? defaultThreshold(editor),
+          unit: 'percent',
+        },
+      }),
+      validate: (trigger) => {
+        if (
+          trigger.kind !== 'threshold_crossing' ||
+          trigger.direction !== 'at_or_above' ||
+          trigger.unit !== 'percent'
+        ) {
+          throw new Error(
+            'Usage-near-limit rules must cross above a percentage threshold.',
+          );
+        }
+        if (
+          !Number.isFinite(trigger.threshold) ||
+          trigger.threshold < 1 ||
+          trigger.threshold > 99
+        ) {
+          throw new Error(
+            'Usage-near-limit thresholds must be between 1 and 99 percent.',
+          );
+        }
+      },
+      present: ({ payload, trigger }) => {
+        if (trigger.kind !== 'threshold_crossing') {
+          throw new Error(
+            'Usage-near-limit presentation requires a threshold.',
+          );
+        }
+        const percent =
+          (Number(payload.currentUsage) / Number(payload.limit)) * 100;
+        return {
+          title: 'Usage near limit',
+          summary: [
+            `Only ${100 - trigger.threshold}% of your `,
+            { workspace: true },
+            ' monthly usage limit remains.',
+          ],
+          details: [['Current usage: ', { strong: `${Math.round(percent)}%` }]],
+          targetUrl: String(payload.targetUrl),
+          subjectKind: 'workspace',
+          subjectId: String(payload.accountId),
+        };
+      },
+    },
+  },
+  {
+    id: 'play.failed',
+    eventName: ProductNotificationEvent.PlayRunCompleted,
+    requiredFilter: { outcome: 'failed' },
+    allowedTriggers: ['each_match', 'consecutive_outcomes'],
+    catalog: {
+      name: 'Play failed',
+      category: 'plays',
+      description:
+        'Notify for all, scheduled, webhook-triggered, or specific Play failures.',
+      allowMultiple: true,
+      editor: { kind: 'play_failure', defaultFailureCount: 1 },
+    },
+    rule: {
+      create: (input, base) => {
+        const settings = input.playFailure ?? {
+          scope: 'all' as const,
+          failureCount: 1,
+        };
+        const eventFilter = applyPlayScope({ ...base.eventFilter }, settings);
+        const count = Math.max(1, Math.floor(settings.failureCount));
+        return {
+          ...base,
+          eventFilter,
+          repeatMode: count === 1 ? 'every_match' : 'on_enter',
+          trigger:
+            count === 1
+              ? { kind: 'each_match' }
+              : {
+                  kind: 'consecutive_outcomes',
+                  count,
+                  outcome: 'failed',
+                  maxLookback: count,
+                },
+        };
+      },
+      validate: validateFailedOutcome,
+      present: ({ payload }) => playRunPresentation(payload, false),
+    },
+  },
+  {
+    id: 'play.succeeded',
+    eventName: ProductNotificationEvent.PlayRunCompleted,
+    requiredFilter: { outcome: 'succeeded' },
+    allowedTriggers: ['each_match'],
+    catalog: {
+      name: 'Play succeeded',
+      category: 'plays',
+      description:
+        'Notify for all, scheduled, webhook-triggered, or specific Play successes.',
+      allowMultiple: true,
+      editor: { kind: 'play_scope' },
+    },
+    rule: {
+      create: (input, base) => ({
+        ...base,
+        eventFilter: applyPlayScope(
+          { ...base.eventFilter },
+          input.playFailure ?? { scope: 'all', failureCount: 1 },
+        ),
+        repeatMode: 'every_match',
+        trigger: { kind: 'each_match' },
+      }),
+      present: ({ payload }) => playRunPresentation(payload, true),
+    },
+  },
+  {
+    id: 'webhook.delivery.failed',
+    eventName: ProductNotificationEvent.WebhookDeliveryCompleted,
+    requiredFilter: { outcome: 'failed' },
+    allowedTriggers: ['each_match', 'consecutive_outcomes'],
+    // Nothing emits webhook.delivery.completed yet, so these stay out of the
+    // customer catalog until a producer exists.
+    catalog: undefined,
+    rule: {
+      validate: validateFailedOutcome,
+      present: ({ payload }) => webhookDeliveryPresentation(payload, false),
+    },
+  },
+  {
+    id: 'webhook.delivery.succeeded',
+    eventName: ProductNotificationEvent.WebhookDeliveryCompleted,
+    requiredFilter: { outcome: 'succeeded' },
+    allowedTriggers: ['each_match'],
+    catalog: undefined,
+    rule: {
+      present: ({ payload }) => webhookDeliveryPresentation(payload, true),
+    },
+  },
+] as const satisfies readonly NotificationTypeRegistration[];
+
+export type ProductNotificationType =
+  (typeof PRODUCT_NOTIFICATION_TYPE_REGISTRY)[number]['id'];
+type ConfigurableProductNotificationRegistration = Extract<
+  (typeof PRODUCT_NOTIFICATION_TYPE_REGISTRY)[number],
+  { catalog: ProductNotificationTypeCatalogMetadata }
+>;
+export type ConfigurableProductNotificationType =
+  ConfigurableProductNotificationRegistration['id'];
+export type ProductNotificationTypeCatalogItem =
+  ProductNotificationTypeCatalogMetadata & {
+    id: ConfigurableProductNotificationType;
+  };
+
+/**
+ * Rows that stand for several types at once. Two events say one thing to a
+ * reader — Deepline stopped something because the workspace ran out of credits
+ * — so they share a row while their rules stay separate underneath.
+ */
+export const PRODUCT_NOTIFICATION_MERGED_ROWS: readonly {
+  key: string;
+  name: string;
+  category: ProductNotificationCategoryId;
+  typeIds: readonly ConfigurableProductNotificationType[];
+}[] = [
+  {
+    key: 'out-of-credits',
+    name: 'Out of credits',
+    category: 'credits',
+    typeIds: [
+      'monitor.disabled.insufficient_credits',
+      'play.disabled.insufficient_credits',
+    ],
+  },
+];
+
+export const PRODUCT_NOTIFICATION_TYPE_DEFINITIONS: readonly NotificationTypeDefinition[] =
+  PRODUCT_NOTIFICATION_TYPE_REGISTRY.map((registration) => ({
+    id: registration.id,
+    eventName: registration.eventName,
+    requiredFilter: registration.requiredFilter,
+    allowedTriggers: registration.allowedTriggers,
+  }));
+
+export type ProductNotificationPlayFailureSettings = {
+  scope: 'all' | 'cron' | 'webhook' | 'specific';
+  playId?: string;
+  playName?: string;
+  failureCount: number;
+};
+
+/** Build the canonical stored rule for one customer-facing type. */
+export function createProductNotificationRule(input: {
+  ruleKey: string;
+  groupKey: string;
+  notificationType: ConfigurableProductNotificationType;
+  threshold?: number;
+  playFailure?: ProductNotificationPlayFailureSettings;
+  repeatMode?: ProductNotificationRepeatMode;
+}): ProductNotificationDefaultRule {
+  const registration = PRODUCT_NOTIFICATION_TYPE_REGISTRY.find(
+    (candidate) => candidate.id === input.notificationType,
+  )!;
+  const rule = (registration as NotificationTypeRegistration).rule;
+  const base = {
+    ruleKey: input.ruleKey,
+    groupKey: input.groupKey,
+    enabled: true,
+    notificationType: input.notificationType,
+    eventName: registration.eventName,
+    eventFilter: { ...registration.requiredFilter },
+    repeatMode: input.repeatMode ?? 'on_enter',
+    conditionGeneration: 1,
+  };
+  if (rule?.create) {
+    const editor = registration.catalog?.editor;
+    if (!editor) {
+      throw new Error(`${input.notificationType} is not configurable.`);
+    }
+    return rule.create(input, base, editor);
+  }
+  throw new Error(
+    `Notification type ${input.notificationType} has no rule builder.`,
+  );
+}
+
+/** Customer-facing catalog used by UI, API, and CLI configuration surfaces. */
+export const PRODUCT_NOTIFICATION_TYPE_CATALOG: readonly ProductNotificationTypeCatalogItem[] =
+  PRODUCT_NOTIFICATION_TYPE_REGISTRY.flatMap(({ id, catalog }) =>
+    catalog ? [{ id, ...catalog }] : [],
+  );
+
+/** Code-owned defaults declared beside the notification types they enable. */
+export const PRODUCT_NOTIFICATION_DEFAULT_RULES =
+  PRODUCT_NOTIFICATION_TYPE_REGISTRY.flatMap((registration) => {
+    const defaultRule = (registration as NotificationTypeRegistration).rule
+      ?.default;
+    return defaultRule
+      ? [
+          createProductNotificationRule({
+            ...defaultRule,
+            notificationType:
+              registration.id as ConfigurableProductNotificationType,
+          }),
+        ]
+      : [];
+  });
+
+/** Render type-specific content without teaching the processor each rule name. */
+export function presentProductNotification(input: {
+  notificationType: string;
+  payload: ProductNotificationFacts;
+  trigger: ProductNotificationTrigger;
+}): ProductNotificationPresentation {
+  const registration = PRODUCT_NOTIFICATION_TYPE_REGISTRY.find(
+    (candidate) => candidate.id === input.notificationType,
+  ) as NotificationTypeRegistration | undefined;
+  const present = registration?.rule?.present;
+  if (!present) {
+    throw new Error(
+      `No notification presentation exists for ${input.notificationType}.`,
+    );
+  }
+  return present({ payload: input.payload, trigger: input.trigger });
+}
+
+/** Return a registered override for condition arming-state scope. */
+export function productNotificationConditionSubject(
+  notificationType: string,
+): 'workspace' | undefined {
+  const registration = PRODUCT_NOTIFICATION_TYPE_REGISTRY.find(
+    (candidate) => candidate.id === notificationType,
+  ) as NotificationTypeRegistration | undefined;
+  return registration?.rule?.conditionSubject;
+}
+
+/** A rule with an external rearm event ignores inactive observations itself. */
+export function productNotificationHasExternalRearm(notificationType: string) {
+  const registration = PRODUCT_NOTIFICATION_TYPE_REGISTRY.find(
+    (candidate) => candidate.id === notificationType,
+  ) as NotificationTypeRegistration | undefined;
+  return Boolean(registration?.rule?.rearm);
+}
+
+/** Decide whether this event rearms a registered rule condition. */
+export function productNotificationRearmsOnEvent(input: {
+  notificationType: string;
+  eventName: ProductNotificationEventName;
+  payload: ProductNotificationFacts;
+}) {
+  const registration = PRODUCT_NOTIFICATION_TYPE_REGISTRY.find(
+    (candidate) => candidate.id === input.notificationType,
+  ) as NotificationTypeRegistration | undefined;
+  const rearm = registration?.rule?.rearm;
+  return Boolean(
+    rearm &&
+    rearm.eventName === input.eventName &&
+    rearm.matches(input.payload),
+  );
+}
+
+export const PRODUCT_NOTIFICATION_COMPATIBILITY_TYPE_DEFINITIONS: readonly NotificationTypeDefinition[] =
+  PRODUCT_NOTIFICATION_EVENT_CATALOG.map(({ id: eventName }) => ({
+    id: legacySlackNotificationType(eventName),
+    eventName,
+    requiredFilter: {},
+    allowedTriggers: ['each_match'],
+  }));
+
+function definitionFor(notificationType: string) {
+  const definition = [
+    ...PRODUCT_NOTIFICATION_TYPE_DEFINITIONS,
+    ...PRODUCT_NOTIFICATION_COMPATIBILITY_TYPE_DEFINITIONS,
+  ].find((candidate) => candidate.id === notificationType);
+  if (!definition) {
+    throw new Error(`Unknown notification type ${notificationType}.`);
+  }
+  return definition;
+}
+
+function validateSharedBounds(
+  rule: Pick<ProductNotificationDefaultRule, 'eventFilter' | 'trigger'>,
+) {
+  const filterEntries = Object.entries(rule.eventFilter);
+  if (filterEntries.length > 20) {
+    throw new Error('Notification event filters exceed the 20-fact bound.');
+  }
+  for (const [key, value] of filterEntries) {
+    if (!key || key.length > 128) {
+      throw new Error(
+        'Notification event filter keys are outside their bounds.',
+      );
+    }
+    if (typeof value === 'string' && (!value.trim() || value.length > 512)) {
+      throw new Error(
+        `Notification event filter ${key} is outside its bounds.`,
+      );
+    }
+    if (typeof value === 'number' && !Number.isFinite(value)) {
+      throw new Error(`Notification event filter ${key} must be finite.`);
+    }
+  }
+  if (
+    rule.trigger.kind === 'consecutive_outcomes' &&
+    (!Number.isInteger(rule.trigger.count) ||
+      rule.trigger.count < 1 ||
+      !Number.isInteger(rule.trigger.maxLookback) ||
+      rule.trigger.maxLookback < rule.trigger.count ||
+      rule.trigger.maxLookback > 100 ||
+      !rule.trigger.outcome ||
+      rule.trigger.outcome.length > 128)
+  ) {
+    throw new Error('Consecutive-outcome bounds are invalid.');
+  }
+}
+
+/** Reject rules that cannot be interpreted by one registered V1 composition. */
+export function validateProductNotificationRuleDefinition(
+  rule: Pick<
+    ProductNotificationDefaultRule,
+    | 'notificationType'
+    | 'eventName'
+    | 'eventFilter'
+    | 'trigger'
+    | 'repeatMode'
+    | 'conditionGeneration'
+  >,
+) {
+  if (
+    rule.repeatMode !== undefined &&
+    rule.repeatMode !== 'on_enter' &&
+    rule.repeatMode !== 'every_match'
+  ) {
+    throw new Error('Notification repeat mode is invalid.');
+  }
+  if (
+    rule.conditionGeneration !== undefined &&
+    (!Number.isInteger(rule.conditionGeneration) ||
+      rule.conditionGeneration < 1)
+  ) {
+    throw new Error('Notification condition generation must be positive.');
+  }
+  validateSharedBounds(rule);
+  const definition = definitionFor(rule.notificationType);
+  if (rule.eventName !== definition.eventName) {
+    throw new Error(
+      `${rule.notificationType} requires event ${definition.eventName}.`,
+    );
+  }
+  for (const [key, value] of Object.entries(definition.requiredFilter)) {
+    if (rule.eventFilter[key] !== value) {
+      throw new Error(
+        `${rule.notificationType} requires filter ${key}=${value}.`,
+      );
+    }
+  }
+  const eventDefinition = getProductNotificationEventDefinition(
+    definition.eventName,
+  );
+  const filterFields = {
+    ...eventDefinition.requiredFacts,
+    ...eventDefinition.optionalFacts,
+  };
+  for (const [key, value] of Object.entries(rule.eventFilter)) {
+    if (!filterFields[key]) {
+      throw new Error(
+        `${rule.notificationType} does not support filter ${key}.`,
+      );
+    }
+    if (typeof value !== filterFields[key]) {
+      throw new Error(
+        `${rule.notificationType} filter ${key} must be ${filterFields[key]}.`,
+      );
+    }
+  }
+  if (
+    !definition.allowedTriggers.includes(rule.trigger.kind) ||
+    !productNotificationTriggerIsAllowed(definition.eventName, rule.trigger)
+  ) {
+    throw new Error(
+      `${rule.trigger.kind} is not supported by ${rule.notificationType}.`,
+    );
+  }
+  const registration = PRODUCT_NOTIFICATION_TYPE_REGISTRY.find(
+    (candidate) => candidate.id === rule.notificationType,
+  ) as NotificationTypeRegistration | undefined;
+  registration?.rule?.validate?.(rule.trigger);
+  return definition;
+}