@elevasis/core 0.13.0 → 0.14.0

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

@@ -0,0 +1,160 @@
+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)
+          }
+        }
+      }
+    }
+  })
+})

package/src/business/acquisition/derive-actions.test.ts

@@ -0,0 +1,518 @@
+import { describe, expect, it } from 'vitest'
+import type { AcqDealRow } from './types'
+import type { Action, ActionDef } from './derive-actions'
+import { DEFAULT_CRM_ACTIONS, SendReplyActionPayloadSchema, deriveActions } from './derive-actions'
+
+// ---------------------------------------------------------------------------
+// Fixture builder
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a minimal AcqDealRow suitable for `isAvailableFor()` predicate checks.
+ * Only stage_key and state_key affect availability logic; all other required
+ * columns are filled with safe, inert defaults.
+ */
+function makeDeal(overrides: Partial<Pick<AcqDealRow, 'stage_key' | 'state_key'>> = {}): AcqDealRow {
+  return {
+    id: 'deal-fixture-id',
+    organization_id: 'org-fixture-id',
+    contact_id: null,
+    contact_email: 'fixture@example.com',
+    pipeline_key: 'default',
+    stage_key: null,
+    state_key: null,
+    activity_log: [],
+    closed_lost_at: null,
+    closed_lost_reason: null,
+    discovery_data: null,
+    discovery_submitted_at: null,
+    discovery_submitted_by: null,
+    initial_fee: null,
+    monthly_fee: null,
+    payment_link_sent_at: null,
+    payment_received_at: null,
+    proposal_data: null,
+    proposal_generated_at: null,
+    proposal_pdf_url: null,
+    proposal_reviewed_at: null,
+    proposal_reviewed_by: null,
+    proposal_sent_at: null,
+    proposal_signed_at: null,
+    signature_envelope_id: null,
+    source_list_id: null,
+    source_type: null,
+    stripe_payment_id: null,
+    stripe_payment_link: null,
+    stripe_payment_link_id: null,
+    stripe_subscription_id: null,
+    created_at: '2026-01-01T00:00:00.000Z',
+    updated_at: '2026-01-01T00:00:00.000Z',
+    ...overrides
+  }
+}
+
+// ---------------------------------------------------------------------------
+// DEFAULT_CRM_ACTIONS static contract
+// ---------------------------------------------------------------------------
+
+describe('DEFAULT_CRM_ACTIONS static contract', () => {
+  const EXPECTED_KEYS = [
+    'move_to_proposal',
+    'move_to_closing',
+    'move_to_closed_won',
+    'move_to_closed_lost',
+    'move_to_nurturing',
+    'send_reply',
+    'send_link',
+    'send_nudge',
+    'mark_no_show',
+    'rebook'
+  ]
+
+  it('contains all 10 expected action keys', () => {
+    const keys = DEFAULT_CRM_ACTIONS.map((a) => a.key)
+    expect(keys).toEqual(EXPECTED_KEYS)
+  })
+
+  it('every entry has key, label, isAvailableFor, and workflowId', () => {
+    for (const def of DEFAULT_CRM_ACTIONS) {
+      expect(typeof def.key).toBe('string')
+      expect(def.key.length).toBeGreaterThan(0)
+      expect(typeof def.label).toBe('string')
+      expect(def.label.length).toBeGreaterThan(0)
+      expect(typeof def.isAvailableFor).toBe('function')
+      expect(typeof def.workflowId).toBe('string')
+      expect(def.workflowId.length).toBeGreaterThan(0)
+    }
+  })
+
+  it('no two ActionDefs share the same key', () => {
+    const keys = DEFAULT_CRM_ACTIONS.map((a) => a.key)
+    const unique = new Set(keys)
+    expect(unique.size).toBe(keys.length)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// isAvailableFor() predicates — per stage / state
+// ---------------------------------------------------------------------------
+
+describe('isAvailableFor() predicates', () => {
+  describe('move_to_proposal', () => {
+    const def = DEFAULT_CRM_ACTIONS.find((a) => a.key === 'move_to_proposal')!
+
+    it('is available for interested stage', () => {
+      expect(def.isAvailableFor(makeDeal({ stage_key: 'interested' }))).toBe(true)
+    })
+
+    it.each(['proposal', 'closing', 'closed_won', 'closed_lost', 'nurturing', null])(
+      'is NOT available for stage %s',
+      (stage) => {
+        expect(def.isAvailableFor(makeDeal({ stage_key: stage }))).toBe(false)
+      }
+    )
+  })
+
+  describe('move_to_closing', () => {
+    const def = DEFAULT_CRM_ACTIONS.find((a) => a.key === 'move_to_closing')!
+
+    it('is available for proposal stage', () => {
+      expect(def.isAvailableFor(makeDeal({ stage_key: 'proposal' }))).toBe(true)
+    })
+
+    it.each(['interested', 'closing', 'closed_won', 'closed_lost', 'nurturing', null])(
+      'is NOT available for stage %s',
+      (stage) => {
+        expect(def.isAvailableFor(makeDeal({ stage_key: stage }))).toBe(false)
+      }
+    )
+  })
+
+  describe('move_to_closed_won', () => {
+    const def = DEFAULT_CRM_ACTIONS.find((a) => a.key === 'move_to_closed_won')!
+
+    it('is available for closing stage', () => {
+      expect(def.isAvailableFor(makeDeal({ stage_key: 'closing' }))).toBe(true)
+    })
+
+    it.each(['interested', 'proposal', 'closed_won', 'closed_lost', 'nurturing', null])(
+      'is NOT available for stage %s',
+      (stage) => {
+        expect(def.isAvailableFor(makeDeal({ stage_key: stage }))).toBe(false)
+      }
+    )
+  })
+
+  describe('move_to_closed_lost', () => {
+    const def = DEFAULT_CRM_ACTIONS.find((a) => a.key === 'move_to_closed_lost')!
+
+    it.each(['interested', 'proposal', 'closing'])('is available for stage %s', (stage) => {
+      expect(def.isAvailableFor(makeDeal({ stage_key: stage }))).toBe(true)
+    })
+
+    it.each(['closed_won', 'closed_lost', 'nurturing', null])('is NOT available for stage %s', (stage) => {
+      expect(def.isAvailableFor(makeDeal({ stage_key: stage }))).toBe(false)
+    })
+  })
+
+  describe('move_to_nurturing', () => {
+    const def = DEFAULT_CRM_ACTIONS.find((a) => a.key === 'move_to_nurturing')!
+
+    it.each(['interested', 'proposal', 'closing'])('is available for stage %s', (stage) => {
+      expect(def.isAvailableFor(makeDeal({ stage_key: stage }))).toBe(true)
+    })
+
+    it.each(['closed_won', 'closed_lost', 'nurturing', null])('is NOT available for stage %s', (stage) => {
+      expect(def.isAvailableFor(makeDeal({ stage_key: stage }))).toBe(false)
+    })
+  })
+
+  describe('send_link', () => {
+    const def = DEFAULT_CRM_ACTIONS.find((a) => a.key === 'send_link')!
+
+    it('is available for interested/discovery_replied', () => {
+      expect(def.isAvailableFor(makeDeal({ stage_key: 'interested', state_key: 'discovery_replied' }))).toBe(true)
+    })
+
+    it.each([
+      { stage_key: 'interested', state_key: null },
+      { stage_key: 'interested', state_key: 'discovery_link_sent' },
+      { stage_key: 'interested', state_key: 'discovery_nudging' },
+      { stage_key: 'interested', state_key: 'discovery_booking_cancelled' },
+      { stage_key: 'proposal', state_key: 'discovery_replied' },
+      { stage_key: null, state_key: null }
+    ])('is NOT available for %o', (overrides) => {
+      expect(def.isAvailableFor(makeDeal(overrides))).toBe(false)
+    })
+  })
+
+  describe('send_nudge', () => {
+    const def = DEFAULT_CRM_ACTIONS.find((a) => a.key === 'send_nudge')!
+
+    it.each(['discovery_link_sent', 'discovery_nudging'])('is available for interested/%s', (state) => {
+      expect(def.isAvailableFor(makeDeal({ stage_key: 'interested', state_key: state }))).toBe(true)
+    })
+
+    it.each([
+      { stage_key: 'interested', state_key: null },
+      { stage_key: 'interested', state_key: 'discovery_replied' },
+      { stage_key: 'interested', state_key: 'discovery_booking_cancelled' },
+      { stage_key: 'proposal', state_key: 'discovery_link_sent' },
+      { stage_key: null, state_key: null }
+    ])('is NOT available for %o', (overrides) => {
+      expect(def.isAvailableFor(makeDeal(overrides))).toBe(false)
+    })
+  })
+
+  describe('mark_no_show', () => {
+    const def = DEFAULT_CRM_ACTIONS.find((a) => a.key === 'mark_no_show')!
+
+    it('is available for interested/discovery_nudging', () => {
+      expect(def.isAvailableFor(makeDeal({ stage_key: 'interested', state_key: 'discovery_nudging' }))).toBe(true)
+    })
+
+    it.each([
+      { stage_key: 'interested', state_key: null },
+      { stage_key: 'interested', state_key: 'discovery_replied' },
+      { stage_key: 'interested', state_key: 'discovery_link_sent' },
+      { stage_key: 'interested', state_key: 'discovery_booking_cancelled' },
+      { stage_key: 'proposal', state_key: 'discovery_nudging' },
+      { stage_key: null, state_key: null }
+    ])('is NOT available for %o', (overrides) => {
+      expect(def.isAvailableFor(makeDeal(overrides))).toBe(false)
+    })
+  })
+
+  describe('rebook', () => {
+    const def = DEFAULT_CRM_ACTIONS.find((a) => a.key === 'rebook')!
+
+    it('is available for interested/discovery_booking_cancelled', () => {
+      expect(def.isAvailableFor(makeDeal({ stage_key: 'interested', state_key: 'discovery_booking_cancelled' }))).toBe(
+        true
+      )
+    })
+
+    it.each([
+      { stage_key: 'interested', state_key: null },
+      { stage_key: 'interested', state_key: 'discovery_replied' },
+      { stage_key: 'interested', state_key: 'discovery_link_sent' },
+      { stage_key: 'interested', state_key: 'discovery_nudging' },
+      { stage_key: 'proposal', state_key: 'discovery_booking_cancelled' },
+      { stage_key: null, state_key: null }
+    ])('is NOT available for %o', (overrides) => {
+      expect(def.isAvailableFor(makeDeal(overrides))).toBe(false)
+    })
+  })
+
+  describe('terminal stages produce empty action lists', () => {
+    it.each(['closed_won', 'closed_lost', 'nurturing', null])('returns [] for stage %s', (stage) => {
+      expect(deriveActions(makeDeal({ stage_key: stage }))).toEqual([])
+    })
+  })
+})
+
+// ---------------------------------------------------------------------------
+// deriveActions() integration
+// ---------------------------------------------------------------------------
+
+describe('deriveActions()', () => {
+  it('returns render-time shape { key, label } only — no isAvailableFor, workflowId, or payload fields', () => {
+    const actions = deriveActions(makeDeal({ stage_key: 'interested' }))
+
+    expect(actions.length).toBeGreaterThan(0)
+    for (const action of actions) {
+      expect(action).not.toHaveProperty('isAvailableFor')
+      expect(action).not.toHaveProperty('workflowId')
+      // Old fields from prior shape
+      expect(action).not.toHaveProperty('available')
+      expect(action).not.toHaveProperty('handler')
+      expect(action).not.toHaveProperty('kind')
+      expect(action).not.toHaveProperty('payload')
+      // Required render-time fields
+      expect(action).toHaveProperty('key')
+      expect(action).toHaveProperty('label')
+    }
+  })
+
+  it('actions without payloadSchema render with payloadSchema undefined (button branch)', () => {
+    const actions = deriveActions(makeDeal({ stage_key: 'interested' }))
+    for (const action of actions) {
+      expect(action.payloadSchema).toBeUndefined()
+    }
+  })
+
+  it('custom action set works: deriveActions(deal, [customAction]) filters by the override', () => {
+    const alwaysAvailableAction: ActionDef = {
+      key: 'custom_action',
+      label: 'Custom Action',
+      isAvailableFor: () => true,
+      workflowId: 'custom-action-workflow'
+    }
+    const neverAvailableAction: ActionDef = {
+      key: 'blocked_action',
+      label: 'Blocked Action',
+      isAvailableFor: () => false,
+      workflowId: 'blocked-action-workflow'
+    }
+
+    const actions = deriveActions(makeDeal({ stage_key: 'interested' }), [alwaysAvailableAction, neverAvailableAction])
+
+    expect(actions).toEqual([{ key: 'custom_action', label: 'Custom Action' }])
+  })
+
+  it('empty action set returns empty array', () => {
+    expect(deriveActions(makeDeal({ stage_key: 'interested' }), [])).toEqual([])
+  })
+
+  it('uses DEFAULT_CRM_ACTIONS when no second argument is provided', () => {
+    const withDefaults = deriveActions(makeDeal({ stage_key: 'proposal' }))
+    const withExplicit = deriveActions(makeDeal({ stage_key: 'proposal' }), DEFAULT_CRM_ACTIONS)
+    expect(withDefaults).toEqual(withExplicit)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// SendReplyActionPayloadSchema boundary tests
+// ---------------------------------------------------------------------------
+
+describe('SendReplyActionPayloadSchema', () => {
+  it('rejects empty string', () => {
+    expect(SendReplyActionPayloadSchema.safeParse({ replyBody: '' }).success).toBe(false)
+  })
+
+  it('rejects whitespace-only string after trim', () => {
+    expect(SendReplyActionPayloadSchema.safeParse({ replyBody: '   ' }).success).toBe(false)
+  })
+
+  it('accepts single character after trim', () => {
+    expect(SendReplyActionPayloadSchema.safeParse({ replyBody: 'x' }).success).toBe(true)
+  })
+
+  it('accepts string at the 10000-character limit', () => {
+    expect(SendReplyActionPayloadSchema.safeParse({ replyBody: 'x'.repeat(10000) }).success).toBe(true)
+  })
+
+  it('rejects string exceeding 10000 characters', () => {
+    expect(SendReplyActionPayloadSchema.safeParse({ replyBody: 'x'.repeat(10001) }).success).toBe(false)
+  })
+
+  it('trims leading and trailing whitespace from replyBody', () => {
+    const result = SendReplyActionPayloadSchema.safeParse({ replyBody: '  hello  ' })
+    expect(result.success).toBe(true)
+    if (result.success) {
+      expect(result.data.replyBody).toBe('hello')
+    }
+  })
+
+  it('rejects unknown fields (strict schema)', () => {
+    expect(SendReplyActionPayloadSchema.safeParse({ replyBody: 'hello', extra: 'field' }).success).toBe(false)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// deriveActions() — custom action set isolation
+// ---------------------------------------------------------------------------
+
+describe('deriveActions() — custom action set isolation', () => {
+  it('filters only against the provided set — does not merge with DEFAULT_CRM_ACTIONS', () => {
+    const customOnly: ActionDef = {
+      key: 'custom_only',
+      label: 'Custom Only',
+      isAvailableFor: () => true,
+      workflowId: 'custom-only-workflow'
+    }
+
+    const result = deriveActions(makeDeal({ stage_key: 'interested' }), [customOnly])
+
+    const resultKeys = result.map((a) => a.key)
+    expect(resultKeys).toEqual(['custom_only'])
+    const defaultKeys = DEFAULT_CRM_ACTIONS.map((a) => a.key)
+    for (const key of defaultKeys) {
+      expect(resultKeys).not.toContain(key)
+    }
+  })
+
+  it('always-available custom action appears for any deal state', () => {
+    const alwaysOn: ActionDef = {
+      key: 'always_on',
+      label: 'Always On',
+      isAvailableFor: () => true,
+      workflowId: 'always-on-workflow'
+    }
+
+    for (const stage of ['interested', 'proposal', 'closing', 'closed_won', 'closed_lost', 'nurturing', null]) {
+      const result = deriveActions(makeDeal({ stage_key: stage }), [alwaysOn])
+      expect(result).toEqual([{ key: 'always_on', label: 'Always On' }])
+    }
+  })
+})
+
+// ---------------------------------------------------------------------------
+// deriveActions() — action metadata preservation
+// ---------------------------------------------------------------------------
+
+describe('deriveActions() — action metadata preservation', () => {
+  it('send_reply action includes payloadSchema in output', () => {
+    const actions = deriveActions(makeDeal({ stage_key: 'interested', state_key: 'discovery_replied' }))
+    const sendReply = actions.find((a) => a.key === 'send_reply')
+    expect(sendReply).toBeDefined()
+    expect(sendReply?.payloadSchema).toBeDefined()
+    expect(sendReply?.payloadSchema).toBe(SendReplyActionPayloadSchema)
+  })
+
+  it('move_to_proposal does NOT include payloadSchema', () => {
+    const actions = deriveActions(makeDeal({ stage_key: 'interested' }))
+    const action = actions.find((a) => a.key === 'move_to_proposal')
+    expect(action).toBeDefined()
+    expect(action?.payloadSchema).toBeUndefined()
+  })
+
+  it('returned actions preserve key and label properties', () => {
+    const actions = deriveActions(makeDeal({ stage_key: 'interested' }))
+    expect(actions.length).toBeGreaterThan(0)
+    for (const action of actions) {
+      expect(typeof action.key).toBe('string')
+      expect(action.key.length).toBeGreaterThan(0)
+      expect(typeof action.label).toBe('string')
+      expect(action.label.length).toBeGreaterThan(0)
+    }
+  })
+})
+
+// ---------------------------------------------------------------------------
+// deriveActions() — deduplication and ordering
+// ---------------------------------------------------------------------------
+
+describe('deriveActions() — deduplication and ordering', () => {
+  it.each([
+    { stage_key: 'interested', state_key: null },
+    { stage_key: 'interested', state_key: 'discovery_replied' },
+    { stage_key: 'interested', state_key: 'discovery_link_sent' },
+    { stage_key: 'interested', state_key: 'discovery_nudging' },
+    { stage_key: 'interested', state_key: 'discovery_booking_cancelled' },
+    { stage_key: 'proposal', state_key: null },
+    { stage_key: 'closing', state_key: null }
+  ] as const)('no duplicate action keys for %o', (overrides) => {
+    const actions = deriveActions(makeDeal(overrides))
+    const keys = actions.map((a) => a.key)
+    expect(new Set(keys).size).toBe(keys.length)
+  })
+
+  it('returns the same order for repeated calls with identical input', () => {
+    const deal = makeDeal({ stage_key: 'interested', state_key: 'discovery_replied' })
+    const first = deriveActions(deal).map((a) => a.key)
+    const second = deriveActions(deal).map((a) => a.key)
+    expect(first).toEqual(second)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// deriveActions() — multi-state discovery path coverage
+// ---------------------------------------------------------------------------
+
+describe('deriveActions() — multi-state discovery path coverage', () => {
+  it('interested + null state: base actions only, no state-specific actions', () => {
+    expect(deriveActions(makeDeal({ stage_key: 'interested', state_key: null }))).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('interested + discovery_replied: base actions plus send_reply and send_link', () => {
+    expect(deriveActions(makeDeal({ stage_key: 'interested', state_key: 'discovery_replied' }))).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: SendReplyActionPayloadSchema },
+      { key: 'send_link', label: 'Send Booking Link' }
+    ])
+  })
+
+  it('interested + discovery_link_sent: base actions plus send_reply and send_nudge', () => {
+    expect(deriveActions(makeDeal({ stage_key: 'interested', state_key: 'discovery_link_sent' }))).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: SendReplyActionPayloadSchema },
+      { key: 'send_nudge', label: 'Send Nudge' }
+    ])
+  })
+
+  it('interested + discovery_nudging: base actions plus send_reply, send_nudge, and mark_no_show', () => {
+    expect(deriveActions(makeDeal({ stage_key: 'interested', state_key: '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: SendReplyActionPayloadSchema },
+      { key: 'send_nudge', label: 'Send Nudge' },
+      { key: 'mark_no_show', label: 'Mark No-Show' }
+    ])
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Type-level smoke tests (compile-time only, no runtime assertions)
+// ---------------------------------------------------------------------------
+
+describe('type-level smoke', () => {
+  it('Action and ActionDef are usable as TypeScript types', () => {
+    // If this file compiles without error, these types are valid at the use-site.
+    function acceptsAction(_action: Action): void {}
+    function acceptsActionDef(_def: ActionDef): void {}
+
+    const sampleAction: Action = { key: 'test', label: 'Test' }
+    const sampleDef: ActionDef = {
+      key: 'test',
+      label: 'Test',
+      isAvailableFor: () => true,
+      workflowId: 'test-workflow'
+    }
+
+    acceptsAction(sampleAction)
+    acceptsActionDef(sampleDef)
+
+    // No runtime assertion needed — compilation success is the contract
+    expect(true).toBe(true)
+  })
+})