@elevasis/core 0.15.0 → 0.16.0

package/src/business/acquisition/crm-priority.ts

@@ -0,0 +1,349 @@
+import { z } from 'zod'
+import {
+  DEFAULT_CRM_PRIORITY_RULE_CONFIG,
+  type CrmPriorityBucketDefinition,
+  type CrmPriorityBucketKey,
+  type CrmPriorityRuleConfig
+} from '../../organization-model/domains/sales'
+import { getDealOwnership } from './deal-ownership'
+import type { DealPriority } from './types'
+
+export interface CrmPriorityInput {
+  stage_key: string | null
+  state_key: string | null
+  activity_log: unknown
+  updated_at: string
+  created_at: string
+}
+
+export interface EvaluateCrmDealPriorityOptions {
+  config?: CrmPriorityRuleConfig | ResolvedCrmPriorityRuleConfig
+  now?: Date | string
+}
+
+export const CrmPriorityBucketKeySchema = z.enum(['needs_response', 'follow_up_due', 'waiting', 'stale', 'closed_low'])
+
+export const CrmPriorityBucketOverrideSchema = z
+  .object({
+    label: z.string().trim().min(1).max(80).optional(),
+    color: z.string().trim().min(1).max(40).optional(),
+    rank: z.number().int().min(0).max(10000).optional()
+  })
+  .strict()
+
+const CrmPriorityBucketDefinitionSchema = z
+  .object({
+    bucketKey: CrmPriorityBucketKeySchema,
+    label: z.string(),
+    rank: z.number().int(),
+    color: z.string()
+  })
+  .strict()
+
+const CrmPriorityRuleConfigSchema = z
+  .object({
+    enabled: z.boolean().optional(),
+    buckets: z.array(CrmPriorityBucketDefinitionSchema),
+    closedStageKeys: z.array(z.string()),
+    followUpAfterDaysByStateKey: z.record(z.string(), z.number().int()),
+    staleAfterDays: z.number().int()
+  })
+  .strict()
+
+export const CrmPriorityOverrideSchema = z
+  .object({
+    enabled: z.boolean().optional(),
+    staleAfterDays: z.number().int().min(1).max(365).optional(),
+    bucketOrder: z.array(CrmPriorityBucketKeySchema).optional(),
+    buckets: z.partialRecord(CrmPriorityBucketKeySchema, CrmPriorityBucketOverrideSchema).optional(),
+    followUpAfterDaysByStateKey: z
+      .record(z.string().trim().min(1).max(120), z.number().int().min(0).max(365))
+      .optional(),
+    closedStageKeys: z.array(z.string().trim().min(1).max(120)).optional()
+  })
+  .strict()
+
+export type CrmPriorityBucketOverride = z.infer<typeof CrmPriorityBucketOverrideSchema>
+export type CrmPriorityOverride = z.infer<typeof CrmPriorityOverrideSchema>
+
+/**
+ * Resolved CRM priority settings used by evaluators.
+ *
+ * When enabled is false, priority evaluation is intentionally neutral: all deals
+ * receive the configured waiting bucket and no follow-up/stale urgency is computed.
+ */
+export type ResolvedCrmPriorityRuleConfig = CrmPriorityRuleConfig & {
+  enabled: boolean
+}
+
+interface ParsedActivity {
+  type: string | null
+  occurredAt: string
+}
+
+const MS_PER_DAY = 24 * 60 * 60 * 1000
+
+export function evaluateCrmDealPriority(
+  input: CrmPriorityInput,
+  options: EvaluateCrmDealPriorityOptions = {}
+): DealPriority {
+  const config = resolveCrmPriorityRuleConfig(options.config)
+  const now = parseDate(options.now ?? new Date()) ?? new Date()
+  const latestActivityAt = getLatestActivityAt(input)
+  const nextActionAt = getNextActionAt(input.state_key, latestActivityAt, config)
+
+  if (!config.enabled) {
+    return buildPriority('waiting', config, {
+      reason: 'CRM priority evaluation is disabled.',
+      latestActivityAt,
+      nextActionAt: null
+    })
+  }
+
+  if (input.stage_key && config.closedStageKeys.includes(input.stage_key)) {
+    return buildPriority('closed_low', config, {
+      reason: `Deal is in ${input.stage_key}.`,
+      latestActivityAt,
+      nextActionAt: null
+    })
+  }
+
+  const ownership = getDealOwnership(input)
+
+  if (ownership === 'us') {
+    return buildPriority('needs_response', config, {
+      reason: 'Lead replied last — we owe the next move.',
+      latestActivityAt,
+      nextActionAt
+    })
+  }
+
+  // ownership === 'them' or null: check age against staleAfterDays first
+  if (latestActivityAt) {
+    const latestActivityDate = parseDate(latestActivityAt)
+    if (latestActivityDate && now.getTime() - latestActivityDate.getTime() >= config.staleAfterDays * MS_PER_DAY) {
+      return buildPriority('stale', config, {
+        reason: `No meaningful activity in ${config.staleAfterDays} days.`,
+        latestActivityAt,
+        nextActionAt: null
+      })
+    }
+  }
+
+  if (ownership === 'them') {
+    if (nextActionAt) {
+      const nextActionDate = parseDate(nextActionAt)
+      if (nextActionDate && nextActionDate <= now) {
+        return buildPriority('follow_up_due', config, {
+          reason: 'Configured follow-up window has elapsed.',
+          latestActivityAt,
+          nextActionAt
+        })
+      }
+    }
+
+    return buildPriority('waiting', config, {
+      reason: 'Waiting on their reply.',
+      latestActivityAt,
+      nextActionAt
+    })
+  }
+
+  // ownership === null (no inbound/outbound events): fall back to follow_up/waiting
+  if (nextActionAt) {
+    const nextActionDate = parseDate(nextActionAt)
+    if (nextActionDate && nextActionDate <= now) {
+      return buildPriority('follow_up_due', config, {
+        reason: 'Configured follow-up window has elapsed.',
+        latestActivityAt,
+        nextActionAt
+      })
+    }
+
+    return buildPriority('waiting', config, {
+      reason: 'Waiting until the configured next action time.',
+      latestActivityAt,
+      nextActionAt
+    })
+  }
+
+  return buildPriority('waiting', config, {
+    reason: 'No immediate response or follow-up is due.',
+    latestActivityAt,
+    nextActionAt: null
+  })
+}
+
+export function resolveCrmPriorityRuleConfig(input?: unknown): ResolvedCrmPriorityRuleConfig {
+  const candidate = extractPriorityOverride(input)
+  const fullConfigResult = CrmPriorityRuleConfigSchema.safeParse(candidate)
+
+  if (fullConfigResult.success) return buildResolvedConfig(fullConfigResult.data)
+
+  const result = CrmPriorityOverrideSchema.safeParse(candidate)
+
+  if (!result.success) return buildDefaultResolvedConfig()
+
+  return mergeCrmPriorityOverride(result.data)
+}
+
+function mergeCrmPriorityOverride(override: CrmPriorityOverride): ResolvedCrmPriorityRuleConfig {
+  const defaultConfig = buildDefaultResolvedConfig()
+  const bucketOverrides = override.buckets ?? {}
+  const orderedBucketKeys = override.bucketOrder ? [...new Set(override.bucketOrder)] : []
+  const orderRanks = new Map<CrmPriorityBucketKey, number>()
+
+  orderedBucketKeys.forEach((bucketKey, index) => {
+    orderRanks.set(bucketKey, (index + 1) * 10)
+  })
+
+  const buckets = defaultConfig.buckets
+    .map((bucket) => {
+      const bucketOverride = bucketOverrides[bucket.bucketKey]
+
+      return {
+        ...bucket,
+        rank: bucketOverride?.rank ?? orderRanks.get(bucket.bucketKey) ?? bucket.rank,
+        label: bucketOverride?.label ?? bucket.label,
+        color: bucketOverride?.color ?? bucket.color
+      }
+    })
+    .sort((a, b) => a.rank - b.rank)
+
+  return {
+    enabled: override.enabled ?? defaultConfig.enabled,
+    buckets,
+    closedStageKeys: override.closedStageKeys ?? defaultConfig.closedStageKeys,
+    followUpAfterDaysByStateKey: {
+      ...defaultConfig.followUpAfterDaysByStateKey,
+      ...(override.followUpAfterDaysByStateKey ?? {})
+    },
+    staleAfterDays: override.staleAfterDays ?? defaultConfig.staleAfterDays
+  }
+}
+
+function buildDefaultResolvedConfig(): ResolvedCrmPriorityRuleConfig {
+  return buildResolvedConfig(DEFAULT_CRM_PRIORITY_RULE_CONFIG)
+}
+
+function buildResolvedConfig(config: CrmPriorityRuleConfig & { enabled?: boolean }): ResolvedCrmPriorityRuleConfig {
+  return {
+    enabled: config.enabled ?? true,
+    buckets: config.buckets.map((bucket) => ({ ...bucket })),
+    closedStageKeys: [...config.closedStageKeys],
+    followUpAfterDaysByStateKey: { ...config.followUpAfterDaysByStateKey },
+    staleAfterDays: config.staleAfterDays
+  }
+}
+
+function extractPriorityOverride(input: unknown): unknown {
+  if (!isPlainRecord(input)) return input
+
+  const crm = input.crm
+  if (isPlainRecord(crm) && Object.prototype.hasOwnProperty.call(crm, 'priority')) {
+    return crm.priority
+  }
+
+  return input
+}
+
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value)
+}
+
+function buildPriority(
+  bucketKey: CrmPriorityBucketKey,
+  config: CrmPriorityRuleConfig,
+  values: Pick<DealPriority, 'reason' | 'latestActivityAt' | 'nextActionAt'>
+): DealPriority {
+  const bucket = findBucket(config.buckets, bucketKey)
+
+  return {
+    bucketKey: bucket.bucketKey,
+    rank: bucket.rank,
+    label: bucket.label,
+    color: bucket.color,
+    reason: values.reason,
+    latestActivityAt: values.latestActivityAt,
+    nextActionAt: values.nextActionAt
+  }
+}
+
+function findBucket(
+  buckets: CrmPriorityBucketDefinition[],
+  bucketKey: CrmPriorityBucketKey
+): CrmPriorityBucketDefinition {
+  const bucket = buckets.find((candidate) => candidate.bucketKey === bucketKey)
+  if (bucket) return bucket
+
+  return {
+    bucketKey,
+    label: bucketKey,
+    rank: Number.MAX_SAFE_INTEGER,
+    color: 'gray'
+  }
+}
+
+function getLatestActivityAt(input: CrmPriorityInput): string | null {
+  const timestamps = getParsedActivities(input.activity_log).map((activity) => activity.occurredAt)
+  const fallback = normalizeTimestamp(input.updated_at) ?? normalizeTimestamp(input.created_at)
+  if (fallback) timestamps.push(fallback)
+
+  return timestamps.sort((a, b) => new Date(b).getTime() - new Date(a).getTime())[0] ?? null
+}
+
+function getParsedActivities(activityLog: unknown): ParsedActivity[] {
+  if (!Array.isArray(activityLog)) return []
+
+  const parsed: ParsedActivity[] = []
+
+  for (const entry of activityLog) {
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) continue
+
+    const record = entry as Record<string, unknown>
+    const occurredAt =
+      normalizeTimestamp(record.timestamp) ??
+      normalizeTimestamp(record.occurredAt) ??
+      normalizeTimestamp(record.createdAt) ??
+      normalizeTimestamp(record.updatedAt) ??
+      normalizeTimestamp(record.sentAt)
+
+    if (!occurredAt) continue
+
+    parsed.push({
+      type: typeof record.type === 'string' ? record.type : null,
+      occurredAt
+    })
+  }
+
+  return parsed
+}
+
+function getNextActionAt(
+  stateKey: string | null,
+  latestActivityAt: string | null,
+  config: CrmPriorityRuleConfig
+): string | null {
+  if (!stateKey || !latestActivityAt) return null
+
+  const days = config.followUpAfterDaysByStateKey[stateKey]
+  if (days === undefined) return null
+
+  const latestActivityDate = parseDate(latestActivityAt)
+  if (!latestActivityDate) return null
+
+  return new Date(latestActivityDate.getTime() + days * MS_PER_DAY).toISOString()
+}
+
+function normalizeTimestamp(value: unknown): string | null {
+  const date = parseDate(value)
+  return date ? date.toISOString() : null
+}
+
+function parseDate(value: unknown): Date | null {
+  if (value instanceof Date) return Number.isNaN(value.getTime()) ? null : value
+  if (typeof value !== 'string') return null
+
+  const date = new Date(value)
+  return Number.isNaN(date.getTime()) ? null : date
+}

package/src/business/acquisition/crm-state-actions.test.ts

@@ -1,160 +1,151 @@
-import { describe, expect, it } from 'vitest'
-import { DEFAULT_ORGANIZATION_MODEL_SALES, LEAD_GEN_PIPELINE_DEFINITIONS } from '../../organization-model/domains/sales'
-import { ActivityEventSchema } from './activity-events'
-import { DealStageSchema, TransitionItemRequestSchema } from './api-schemas'
-import { deriveActions } from './derive-actions'
-import type { DealStage } from './types'
-
-const DEAL_STAGES = [
-  'interested',
-  'proposal',
-  'closing',
-  'closed_won',
-  'closed_lost',
-  'nurturing'
-] as const satisfies readonly DealStage[]
-
-function deal(stageKey: string | null, stateKey: string | null = null): Parameters<typeof deriveActions>[0] {
-  return { stage_key: stageKey, state_key: stateKey } as Parameters<typeof deriveActions>[0]
-}
-
-describe('CRM deal action derivation', () => {
-  it('derives the exact base actions for interested deals', () => {
-    expect(deriveActions(deal('interested'))).toEqual([
-      { key: 'move_to_proposal', label: 'Move to Proposal' },
-      { key: 'move_to_closed_lost', label: 'Close Lost' },
-      { key: 'move_to_nurturing', label: 'Move to Nurturing' }
-    ])
-  })
-
-  it.each([
-    ['discovery_replied', { key: 'send_link', label: 'Send Booking Link' }],
-    ['discovery_link_sent', { key: 'send_nudge', label: 'Send Nudge' }],
-    ['discovery_booking_cancelled', { key: 'rebook', label: 'Rebook' }]
-  ] as const)('adds the expected workflow action for interested/%s', (stateKey, expectedAction) => {
-    const expected = [
-      { key: 'move_to_proposal', label: 'Move to Proposal' },
-      { key: 'move_to_closed_lost', label: 'Close Lost' },
-      { key: 'move_to_nurturing', label: 'Move to Nurturing' },
-      expectedAction
-    ]
-
-    if (stateKey === 'discovery_replied' || stateKey === 'discovery_link_sent') {
-      expected.splice(3, 0, {
-        key: 'send_reply',
-        label: 'Send Reply',
-        payloadSchema: expect.any(Object)
-      } as never)
-    }
-
-    expect(deriveActions(deal('interested', stateKey))).toEqual(expected)
-  })
-
-  it('adds reply, nudge, and no-show actions for interested/discovery_nudging', () => {
-    expect(deriveActions(deal('interested', 'discovery_nudging'))).toEqual([
-      { key: 'move_to_proposal', label: 'Move to Proposal' },
-      { key: 'move_to_closed_lost', label: 'Close Lost' },
-      { key: 'move_to_nurturing', label: 'Move to Nurturing' },
-      { key: 'send_reply', label: 'Send Reply', payloadSchema: expect.any(Object) },
-      { key: 'send_nudge', label: 'Send Nudge' },
-      { key: 'mark_no_show', label: 'Mark No-Show' }
-    ])
-  })
-
-  it('derives exact proposal and closing transitions', () => {
-    expect(deriveActions(deal('proposal'))).toEqual([
-      { key: 'move_to_closing', label: 'Move to Closing' },
-      { key: 'move_to_closed_lost', label: 'Close Lost' },
-      { key: 'move_to_nurturing', label: 'Move to Nurturing' }
-    ])
-
-    expect(deriveActions(deal('closing'))).toEqual([
-      { key: 'move_to_closed_won', label: 'Close Won' },
-      { key: 'move_to_closed_lost', label: 'Close Lost' },
-      { key: 'move_to_nurturing', label: 'Move to Nurturing' }
-    ])
-  })
-
-  it.each(['closed_won', 'closed_lost', 'nurturing', 'legacy_stage', null] as const)(
-    'derives no actions for terminal or non-canonical stage %s',
-    (stageKey) => {
-      expect(deriveActions(deal(stageKey))).toEqual([])
-    }
-  )
-})
-
-describe('ActivityEventSchema', () => {
-  const timestamp = '2026-04-27T12:34:56.000Z'
-
-  // Platform events only (8 members). Domain events (reply_received, booking_nudge_sent, etc.)
-  // live in external/elevasis/operations as CrmDomainActivityEventSchema.
-  // See Open Decision #5 in crm-action-system.mdx for rationale.
-  it.each([
-    [{ type: 'stage_change', timestamp, stageBefore: 'interested', stageAfter: 'proposal', reason: 'qualified' }],
-    [{ type: 'state_change', timestamp, stateBefore: null, stateAfter: 'discovery_replied' }],
-    [{ type: 'action_taken', timestamp, actionKey: 'send_link', payload: { channel: 'email' } }],
-    [{ type: 'approval_created', timestamp, commandId: 'cmd_123', dealStageBefore: 'proposal' }],
-    [{ type: 'approval_resolved', timestamp, commandId: 'cmd_123', resolution: 'superseded' }],
-    [{ type: 'approval_stale', timestamp, commandId: 'cmd_123', dealStageAfter: 'closing' }],
-    [{ type: 'task_created', timestamp, taskId: 'task_123' }],
-    [{ type: 'deal_created', timestamp }]
-  ])('accepts expected %s events', (event) => {
-    expect(ActivityEventSchema.safeParse(event).success).toBe(true)
-  })
-
-  it.each([
-    [{ type: 'deal_created', timestamp: 'not-a-date' }],
-    [{ type: 'unknown_event', timestamp }],
-    [{ type: 'stage_change', timestamp, stageBefore: 'interested' }],
-    [{ type: 'approval_resolved', timestamp, commandId: 'cmd_123', resolution: 'approved' }],
-    [{ type: 'booking_nudge_sent', timestamp, followupDay: '2' }],
-    [{ type: 'action_taken', timestamp }]
-  ])('rejects malformed event payload %o', (event) => {
-    expect(ActivityEventSchema.safeParse(event).success).toBe(false)
-  })
-})
-
-describe('CRM stage and transition vocabulary contracts', () => {
-  it('keeps DealStage, DealStageSchema, and the default sales pipeline stages aligned', () => {
-    const defaultPipeline = DEFAULT_ORGANIZATION_MODEL_SALES.pipelines.find(
-      (pipeline) => pipeline.id === DEFAULT_ORGANIZATION_MODEL_SALES.defaultPipelineId
-    )
-    const defaultSalesStages = defaultPipeline?.stages
-      .toSorted((left, right) => left.order - right.order)
-      .map((stage) => stage.id)
-
-    expect(defaultSalesStages).toEqual([...DEAL_STAGES])
-    expect(DealStageSchema.options).toEqual([...DEAL_STAGES])
-  })
-
-  it('accepts every canonical CRM deal stage in transition requests', () => {
-    for (const stageKey of DEAL_STAGES) {
-      expect(
-        TransitionItemRequestSchema.safeParse({
-          pipelineKey: DEFAULT_ORGANIZATION_MODEL_SALES.defaultPipelineId,
-          stageKey,
-          stateKey: null,
-          expectedUpdatedAt: '2026-04-27T12:34:56.000Z'
-        }).success
-      ).toBe(true)
-    }
-  })
-
-  it('accepts canonical lead-gen stage/state pairs in transition requests', () => {
-    for (const pipelineDefinitions of Object.values(LEAD_GEN_PIPELINE_DEFINITIONS)) {
-      for (const pipeline of pipelineDefinitions) {
-        for (const stage of pipeline.stages) {
-          for (const state of stage.states) {
-            expect(
-              TransitionItemRequestSchema.safeParse({
-                pipelineKey: pipeline.pipelineKey,
-                stageKey: stage.stageKey,
-                stateKey: state.stateKey
-              }).success
-            ).toBe(true)
-          }
-        }
-      }
-    }
-  })
-})
+import { describe, expect, it } from 'vitest'
+import { DEFAULT_ORGANIZATION_MODEL_SALES, LEAD_GEN_PIPELINE_DEFINITIONS } from '../../organization-model/domains/sales'
+import { ActivityEventSchema } from './activity-events'
+import { DealStageSchema, TransitionItemRequestSchema } from './api-schemas'
+import { deriveActions } from './derive-actions'
+import type { DealStage } from './types'
+
+const DEAL_STAGES = [
+  'interested',
+  'proposal',
+  'closing',
+  'closed_won',
+  'closed_lost',
+  'nurturing'
+] as const satisfies readonly DealStage[]
+
+function deal(stageKey: string | null, stateKey: string | null = null): Parameters<typeof deriveActions>[0] {
+  return { stage_key: stageKey, state_key: stateKey } as Parameters<typeof deriveActions>[0]
+}
+
+describe('CRM deal action derivation', () => {
+  it('derives the exact base actions for interested deals', () => {
+    expect(deriveActions(deal('interested'))).toEqual([
+      { key: 'move_to_proposal', label: 'Move to Proposal' },
+      { key: 'move_to_closed_lost', label: 'Close Lost' },
+      { key: 'move_to_nurturing', label: 'Move to Nurturing' }
+    ])
+  })
+
+  it.each([
+    ['discovery_replied', { key: 'send_link', label: 'Send Booking Link' }],
+    ['discovery_link_sent', { key: 'send_nudge', label: 'Send Nudge' }],
+    ['discovery_booking_cancelled', { key: 'rebook', label: 'Rebook' }]
+  ] as const)('adds the expected workflow action for interested/%s', (stateKey, expectedAction) => {
+    const expected = [
+      { key: 'move_to_proposal', label: 'Move to Proposal' },
+      { key: 'move_to_closed_lost', label: 'Close Lost' },
+      { key: 'move_to_nurturing', label: 'Move to Nurturing' },
+      expectedAction
+    ]
+
+    expect(deriveActions(deal('interested', stateKey))).toEqual(expected)
+  })
+
+  it('adds nudge and no-show actions for interested/discovery_nudging', () => {
+    expect(deriveActions(deal('interested', 'discovery_nudging'))).toEqual([
+      { key: 'move_to_proposal', label: 'Move to Proposal' },
+      { key: 'move_to_closed_lost', label: 'Close Lost' },
+      { key: 'move_to_nurturing', label: 'Move to Nurturing' },
+      { key: 'send_nudge', label: 'Send Nudge' },
+      { key: 'mark_no_show', label: 'Mark No-Show' }
+    ])
+  })
+
+  it('derives exact proposal and closing transitions', () => {
+    expect(deriveActions(deal('proposal'))).toEqual([
+      { key: 'move_to_closing', label: 'Move to Closing' },
+      { key: 'move_to_closed_lost', label: 'Close Lost' },
+      { key: 'move_to_nurturing', label: 'Move to Nurturing' }
+    ])
+
+    expect(deriveActions(deal('closing'))).toEqual([
+      { key: 'move_to_closed_won', label: 'Close Won' },
+      { key: 'move_to_closed_lost', label: 'Close Lost' },
+      { key: 'move_to_nurturing', label: 'Move to Nurturing' }
+    ])
+  })
+
+  it.each(['closed_won', 'closed_lost', 'nurturing', 'legacy_stage', null] as const)(
+    'derives no actions for terminal or non-canonical stage %s',
+    (stageKey) => {
+      expect(deriveActions(deal(stageKey))).toEqual([])
+    }
+  )
+})
+
+describe('ActivityEventSchema', () => {
+  const timestamp = '2026-04-27T12:34:56.000Z'
+
+  // Platform events only (8 members). Domain events (reply_received, booking_nudge_sent, etc.)
+  // live in @repo/elevasis-operations as CrmDomainActivityEventSchema.
+  // See Open Decision #5 in crm-action-system.mdx for rationale.
+  it.each([
+    [{ type: 'stage_change', timestamp, stageBefore: 'interested', stageAfter: 'proposal', reason: 'qualified' }],
+    [{ type: 'state_change', timestamp, stateBefore: null, stateAfter: 'discovery_replied' }],
+    [{ type: 'action_taken', timestamp, actionKey: 'send_link', payload: { channel: 'email' } }],
+    [{ type: 'approval_created', timestamp, commandId: 'cmd_123', dealStageBefore: 'proposal' }],
+    [{ type: 'approval_resolved', timestamp, commandId: 'cmd_123', resolution: 'superseded' }],
+    [{ type: 'approval_stale', timestamp, commandId: 'cmd_123', dealStageAfter: 'closing' }],
+    [{ type: 'task_created', timestamp, taskId: 'task_123' }],
+    [{ type: 'deal_created', timestamp }]
+  ])('accepts expected %s events', (event) => {
+    expect(ActivityEventSchema.safeParse(event).success).toBe(true)
+  })
+
+  it.each([
+    [{ type: 'deal_created', timestamp: 'not-a-date' }],
+    [{ type: 'unknown_event', timestamp }],
+    [{ type: 'stage_change', timestamp, stageBefore: 'interested' }],
+    [{ type: 'approval_resolved', timestamp, commandId: 'cmd_123', resolution: 'approved' }],
+    [{ type: 'booking_nudge_sent', timestamp, followupDay: '2' }],
+    [{ type: 'action_taken', timestamp }]
+  ])('rejects malformed event payload %o', (event) => {
+    expect(ActivityEventSchema.safeParse(event).success).toBe(false)
+  })
+})
+
+describe('CRM stage and transition vocabulary contracts', () => {
+  it('keeps DealStage, DealStageSchema, and the default sales pipeline stages aligned', () => {
+    const defaultPipeline = DEFAULT_ORGANIZATION_MODEL_SALES.pipelines.find(
+      (pipeline) => pipeline.id === DEFAULT_ORGANIZATION_MODEL_SALES.defaultPipelineId
+    )
+    const defaultSalesStages = defaultPipeline?.stages
+      .toSorted((left, right) => left.order - right.order)
+      .map((stage) => stage.id)
+
+    expect(defaultSalesStages).toEqual([...DEAL_STAGES])
+    expect(DealStageSchema.options).toEqual([...DEAL_STAGES])
+  })
+
+  it('accepts every canonical CRM deal stage in transition requests', () => {
+    for (const stageKey of DEAL_STAGES) {
+      expect(
+        TransitionItemRequestSchema.safeParse({
+          pipelineKey: DEFAULT_ORGANIZATION_MODEL_SALES.defaultPipelineId,
+          stageKey,
+          stateKey: null,
+          expectedUpdatedAt: '2026-04-27T12:34:56.000Z'
+        }).success
+      ).toBe(true)
+    }
+  })
+
+  it('accepts canonical lead-gen stage/state pairs in transition requests', () => {
+    for (const pipelineDefinitions of Object.values(LEAD_GEN_PIPELINE_DEFINITIONS)) {
+      for (const pipeline of pipelineDefinitions) {
+        for (const stage of pipeline.stages) {
+          for (const state of stage.states) {
+            expect(
+              TransitionItemRequestSchema.safeParse({
+                pipelineKey: pipeline.pipelineKey,
+                stageKey: stage.stageKey,
+                stateKey: state.stateKey
+              }).success
+            ).toBe(true)
+          }
+        }
+      }
+    }
+  })
+})