@elevasis/core 0.13.0 → 0.15.0

package/src/business/acquisition/api-schemas.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod'
-import { UuidSchema } from '../../platform/utils/validation'
+import { UuidSchema, NonEmptyStringSchema } from '../../platform/utils/validation'
+import { LEAD_GEN_STAGE_CATALOG } from '../../organization-model/domains/sales'
 
 /**
  * Deal Management API Schemas
@@ -91,6 +92,27 @@ export const TransitionItemRequestSchema = z
   })
   .strict()
 
+export const TransitionDealStateRequestSchema = z
+  .object({
+    stateKey: z.string().min(1),
+    reason: z.string().optional(),
+    expectedUpdatedAt: z.string().datetime().optional()
+  })
+  .strict()
+
+export const ExecuteActionParamsSchema = z
+  .object({
+    dealId: UuidSchema,
+    actionKey: NonEmptyStringSchema
+  })
+  .strict()
+
+export const ExecuteActionRequestSchema = z
+  .object({
+    payload: z.record(z.string(), z.unknown()).optional()
+  })
+  .strict()
+
 // ---------------------------------------------------------------------------
 // Response schemas (no .strict() — allows forward-compatible additions)
 // ---------------------------------------------------------------------------
@@ -166,6 +188,7 @@ export const DealListResponseSchema = z.object({
 export const DealStageSummarySchema = z.object({
   stage: z.string(),
   count: z.number().int(),
+  totalValue: z.number(),
   oldestUpdatedAt: z.string().nullable(),
   newestUpdatedAt: z.string().nullable()
 })
@@ -263,6 +286,9 @@ export const DealSchemas = {
   CreateDealNoteRequest: CreateDealNoteRequestSchema,
   CreateDealTaskRequest: CreateDealTaskRequestSchema,
   TransitionItemRequest: TransitionItemRequestSchema,
+  TransitionDealStateRequest: TransitionDealStateRequestSchema,
+  ExecuteActionParams: ExecuteActionParamsSchema,
+  ExecuteActionRequest: ExecuteActionRequestSchema,
 
   // Responses
   DealListResponse: DealListResponseSchema,
@@ -289,6 +315,9 @@ export type ListDealTasksDueQuery = z.infer<typeof ListDealTasksDueQuerySchema>
 export type CreateDealNoteRequest = z.infer<typeof CreateDealNoteRequestSchema>
 export type CreateDealTaskRequest = z.infer<typeof CreateDealTaskRequestSchema>
 export type TransitionItemRequest = z.infer<typeof TransitionItemRequestSchema>
+export type TransitionDealStateRequest = z.infer<typeof TransitionDealStateRequestSchema>
+export type ExecuteActionParams = z.infer<typeof ExecuteActionParamsSchema>
+export type ExecuteActionRequest = z.infer<typeof ExecuteActionRequestSchema>
 export type DealListResponse = z.infer<typeof DealListResponseSchema>
 export type DealSummaryResponse = z.infer<typeof DealSummaryResponseSchema>
 export type DealLookupItem = z.infer<typeof DealLookupItemSchema>
@@ -313,61 +342,61 @@ export type DealTaskListResponse = z.infer<typeof DealTaskListResponseSchema>
 // ---------------------------------------------------------------------------
 
 // ---------------------------------------------------------------------------
-// Primitives — list config subtrees
+// Primitives — list status enum + jsonb config schemas
 // ---------------------------------------------------------------------------
 
-export const ListQualificationSchema = z.object({
-  targetDescription: z.string(),
-  minReviewCount: z.number().int().min(0),
-  minRating: z.number().min(0).max(5),
-  excludeFranchises: z.boolean(),
-  customRules: z.string()
-})
-
-export const ListEnrichmentSchema = z.object({
-  emailDiscovery: z
-    .object({
-      primary: z.enum(['tomba', 'anymailfinder']),
-      credentialName: z.string().optional()
-    })
-    .optional(),
-  emailVerification: z
-    .object({
-      provider: z.literal('millionverifier'),
-      threshold: z.enum(['ok', 'ok+catch_all']).optional()
-    })
-    .optional()
-})
+/**
+ * Lifecycle status enum for `acq_lists.status` (mirrors DB CHECK constraint
+ * from migration 20260428000003_lead_gen_acq_lists_status_and_config.sql).
+ */
+export const ListStatusSchema = z.enum(['draft', 'enriching', 'launched', 'closing', 'archived'])
 
-export const ListPersonalizationSchema = z.object({
-  industryContext: z.string().optional(),
-  emailBody: z.string().optional(),
-  creativeDirection: z.string().optional(),
-  exclusionRules: z.array(z.string()).optional()
+/**
+ * Scraping criteria stored in `acq_lists.scraping_config` jsonb.
+ * Edited via the UI; consumed by lgn-01 prospecting workflows (Apify input shape,
+ * geography, vertical, size). All fields are optional — empty config is valid.
+ */
+export const ScrapingConfigSchema = z.object({
+  vertical: z.string().trim().max(255).optional(),
+  geography: z.string().trim().max(500).optional(),
+  size: z.string().trim().max(255).optional(),
+  apifyInput: z.record(z.string(), z.unknown()).optional()
 })
 
-export const PipelineStepSchema = z.object({
-  key: z.string(),
-  label: z.string(),
-  resourceId: z.string(),
-  inputTemplate: z.record(z.string(), z.unknown()),
-  enabled: z.boolean(),
-  order: z.number().int()
+/**
+ * ICP / qualification rubric stored in `acq_lists.icp` jsonb.
+ * Replaces the legacy `config.qualification` blob. Consumed by the
+ * company-qualification workflow.
+ */
+export const IcpRubricSchema = z.object({
+  qualificationRubricKey: z.string().trim().max(255).nullish(),
+  targetDescription: z.string().optional(),
+  minReviewCount: z.number().int().min(0).optional(),
+  minRating: z.number().min(0).max(5).optional(),
+  excludeFranchises: z.boolean().optional(),
+  customRules: z.string().optional()
 })
 
-export const ListPipelineSchema = z.object({
-  steps: z.array(PipelineStepSchema)
+/**
+ * One stage entry in a list's `pipeline_config.stages[]`. The `key` is
+ * validated against `LEAD_GEN_STAGE_CATALOG` so list pipeline definitions
+ * stay aligned with the org-os semantic layer.
+ */
+export const PipelineStageSchema = z.object({
+  key: z.string().refine((value) => Object.prototype.hasOwnProperty.call(LEAD_GEN_STAGE_CATALOG, value), {
+    message: 'pipeline stage key must match LEAD_GEN_STAGE_CATALOG'
+  }),
+  label: z.string().optional(),
+  enabled: z.boolean().optional(),
+  order: z.number().int().optional()
 })
 
 /**
- * Full ListConfig shape. `qualification` is required; everything else optional.
- * Matches `acq_lists.config` jsonb and ListConfig type in types.ts.
+ * Pipeline presentation contract stored in `acq_lists.pipeline_config` jsonb.
+ * `stages[].key` validates against the catalog; the rest is presentation only.
  */
-export const ListConfigSchema = z.object({
-  qualification: ListQualificationSchema,
-  enrichment: ListEnrichmentSchema.optional(),
-  personalization: ListPersonalizationSchema.optional(),
-  pipeline: ListPipelineSchema.optional()
+export const PipelineConfigSchema = z.object({
+  stages: z.array(PipelineStageSchema).optional()
 })
 
 // ---------------------------------------------------------------------------
@@ -375,6 +404,8 @@ export const ListConfigSchema = z.object({
 // ---------------------------------------------------------------------------
 
 export const ListStageCountsSchema = z.object({
+  // Attempted counts by canonical lead-gen stage. The detailed status
+  // distribution lives on ListProgress; telemetry keeps the overview payload small.
   stageCounts: z.object({
     populated: z.number().int(),
     extracted: z.number().int(),
@@ -418,8 +449,10 @@ export const CreateListRequestSchema = z
   .object({
     name: z.string().trim().min(1).max(255),
     description: z.string().trim().nullable().optional(),
-    type: z.string().default('manual'),
-    config: ListConfigSchema.optional()
+    status: ListStatusSchema.optional(),
+    scrapingConfig: ScrapingConfigSchema.optional(),
+    icp: IcpRubricSchema.optional(),
+    pipelineConfig: PipelineConfigSchema.optional()
   })
   .strict()
 
@@ -427,35 +460,38 @@ export const UpdateListRequestSchema = z
   .object({
     name: z.string().trim().min(1).max(255).optional(),
     description: z.string().trim().nullable().optional(),
-    status: z.string().optional(),
     batchIds: z.array(z.string()).optional()
   })
   .strict()
-  .refine(
-    (data) =>
-      data.name !== undefined ||
-      data.description !== undefined ||
-      data.status !== undefined ||
-      data.batchIds !== undefined,
-    {
-      message: 'At least one field (name, description, status, or batchIds) must be provided'
-    }
-  )
+  .refine((data) => data.name !== undefined || data.description !== undefined || data.batchIds !== undefined, {
+    message: 'At least one field (name, description, or batchIds) must be provided'
+  })
 
 /**
- * Partial patch for list.config — UI sends only the edited tab's subtree.
- * Zod v4: use .partial() on each subtree and remake the root schema.
- * Since the root ListConfigSchema marks `qualification` as required, we must
- * produce a manually-built deep-partial that makes qualification optional too.
+ * Status-only PATCH body for `/acquisition/lists/:listId/status`.
+ * Replaces the previous `transitionList` flow.
+ */
+export const UpdateListStatusRequestSchema = z
+  .object({
+    status: ListStatusSchema
+  })
+  .strict()
+
+/**
+ * Partial patch for the three jsonb config columns. UI sends only the edited
+ * subtree; server writes the field as-is (no deep merge — each column is
+ * replaced atomically when present in the patch).
  */
 export const UpdateListConfigRequestSchema = z
   .object({
-    qualification: ListQualificationSchema.partial().optional(),
-    enrichment: ListEnrichmentSchema.partial().optional(),
-    personalization: ListPersonalizationSchema.partial().optional(),
-    pipeline: ListPipelineSchema.partial().optional()
+    scrapingConfig: ScrapingConfigSchema.partial().optional(),
+    icp: IcpRubricSchema.partial().optional(),
+    pipelineConfig: PipelineConfigSchema.partial().optional()
   })
   .strict()
+  .refine((data) => data.scrapingConfig !== undefined || data.icp !== undefined || data.pipelineConfig !== undefined, {
+    message: 'At least one of scrapingConfig, icp, or pipelineConfig must be provided'
+  })
 
 export const AddCompaniesToListRequestSchema = z
   .object({
@@ -498,12 +534,18 @@ export const AcqListResponseSchema = z.object({
   type: z.string(),
   batchIds: z.array(z.string()),
   instantlyCampaignId: z.string().nullable(),
-  status: z.string(),
+  /** Lifecycle status (draft | enriching | launched | closing | archived). */
+  status: ListStatusSchema,
   metadata: z.record(z.string(), z.unknown()),
   launchedAt: z.string().nullable(),
   completedAt: z.string().nullable(),
   createdAt: z.string(),
-  config: ListConfigSchema
+  /** Scraping criteria stored as jsonb on the row. */
+  scrapingConfig: ScrapingConfigSchema,
+  /** ICP / qualification rubric stored as jsonb on the row. */
+  icp: IcpRubricSchema,
+  /** Pipeline presentation contract stored as jsonb on the row. */
+  pipelineConfig: PipelineConfigSchema
 })
 
 export const AcqListListResponseSchema = z.array(AcqListResponseSchema)
@@ -512,6 +554,42 @@ export const ListTelemetryResponseSchema = ListTelemetrySchema
 
 export const ListTelemetryListResponseSchema = z.array(ListTelemetrySchema)
 
+/**
+ * Terminal row-level status for one lead-gen processing stage.
+ * Missing key still means not attempted; legacy boolean `true` is normalized
+ * to `success` by the API reader during rollout.
+ */
+export const ProcessingStageStatusSchema = z.enum(['success', 'no_result', 'skipped', 'error'])
+
+/**
+ * Per-stage progress aggregate for a single pipeline stage.
+ * `attempted` counts terminal statuses, including success, no-result, skipped,
+ * error, and tolerant-reader `other` values.
+ * `total` = total member/company count for the list.
+ */
+export const ListStageProgressSchema = z.object({
+  total: z.number().int().min(0),
+  attempted: z.number().int().min(0),
+  success: z.number().int().min(0),
+  noResult: z.number().int().min(0),
+  skipped: z.number().int().min(0),
+  error: z.number().int().min(0),
+  other: z.number().int().min(0),
+  notAttempted: z.number().int().min(0)
+})
+
+/**
+ * Progress response for GET /acquisition/lists/:listId/progress.
+ * Aggregated on-demand from processing_state status values.
+ * Stage keys are discovered from observed processing_state keys.
+ */
+export const ListProgressResponseSchema = z.object({
+  totalMembers: z.number().int().min(0),
+  totalCompanies: z.number().int().min(0),
+  byCompanyStage: z.record(z.string(), ListStageProgressSchema),
+  byContactStage: z.record(z.string(), ListStageProgressSchema)
+})
+
 /**
  * Row from acq_list_executions joined with the execution summary,
  * shaped for the /lists/:id/executions response.
@@ -767,6 +845,115 @@ export const AcqContactListResponseSchema = z.object({
   offset: z.number().int()
 })
 
+// ---------------------------------------------------------------------------
+// Track A: Artifacts API Schemas
+// ---------------------------------------------------------------------------
+
+export const AcqArtifactOwnerKindSchema = z.enum(['company', 'contact', 'deal', 'list', 'list_member'])
+
+export const ListArtifactsQuerySchema = z
+  .object({
+    ownerKind: AcqArtifactOwnerKindSchema,
+    ownerId: UuidSchema
+  })
+  .strict()
+
+export const CreateArtifactRequestSchema = z
+  .object({
+    ownerKind: AcqArtifactOwnerKindSchema,
+    ownerId: UuidSchema,
+    kind: z.string().trim().min(1).max(255),
+    content: z.record(z.string(), z.unknown()),
+    sourceExecutionId: UuidSchema.optional()
+  })
+  .strict()
+
+export const AcqArtifactResponseSchema = z.object({
+  id: z.string(),
+  organizationId: z.string(),
+  ownerKind: z.string(),
+  ownerId: z.string(),
+  kind: z.string(),
+  content: z.record(z.string(), z.unknown()),
+  sourceExecutionId: z.string().nullable(),
+  createdBy: z.string().nullable(),
+  createdAt: z.string(),
+  version: z.number().int()
+})
+
+export const AcqArtifactListResponseSchema = z.object({
+  artifacts: z.array(AcqArtifactResponseSchema)
+})
+
+// ---------------------------------------------------------------------------
+// Track B: List Members API Schemas
+// ---------------------------------------------------------------------------
+
+export const ListMembersQuerySchema = z
+  .object({
+    limit: z.coerce.number().int().min(1).max(500).default(50),
+    offset: z.coerce.number().int().min(0).default(0)
+  })
+  .strict()
+
+export const MemberIdParamsSchema = z.object({
+  memberId: UuidSchema
+})
+
+export const AcqListMemberContactSummarySchema = z.object({
+  id: z.string(),
+  email: z.string(),
+  firstName: z.string().nullable(),
+  lastName: z.string().nullable(),
+  title: z.string().nullable(),
+  linkedinUrl: z.string().nullable(),
+  companyId: z.string().nullable()
+})
+
+export const AcqListMemberResponseSchema = z.object({
+  id: z.string(),
+  listId: z.string(),
+  contactId: z.string(),
+  pipelineKey: z.string(),
+  stageKey: z.string(),
+  stateKey: z.string(),
+  activityLog: z.unknown(),
+  addedAt: z.string(),
+  addedBy: z.string().nullable(),
+  sourceExecutionId: z.string().nullable(),
+  contact: AcqListMemberContactSummarySchema.nullable()
+})
+
+export const AcqListMembersResponseSchema = z.object({
+  members: z.array(AcqListMemberResponseSchema)
+})
+
+// ---------------------------------------------------------------------------
+// Track B: List Companies API Schemas
+// ---------------------------------------------------------------------------
+
+export const ListCompanyIdParamsSchema = z.object({
+  listCompanyId: UuidSchema
+})
+
+export const AcqListCompanyResponseSchema = z.object({
+  id: z.string(),
+  listId: z.string(),
+  companyId: z.string(),
+  pipelineKey: z.string(),
+  stageKey: z.string(),
+  stateKey: z.string(),
+  activityLog: z.unknown(),
+  addedAt: z.string(),
+  addedBy: z.string().nullable(),
+  sourceExecutionId: z.string().nullable()
+})
+
+// ---------------------------------------------------------------------------
+// Track B: Transition Request (shared by list, list-member, list-company)
+// TransitionItemRequestSchema already exists above (for deals) — reuse it.
+// ---------------------------------------------------------------------------
+
 export const AcqCompanySchemas = {
   CompanyIdParams: CompanyIdParamsSchema,
   ListCompaniesQuery: ListCompaniesQuerySchema,
@@ -813,14 +1000,19 @@ export const AcqListSchemas = {
   ListIdParams: ListIdParamsSchema,
 
   // Primitives (for UI / tests)
-  ListConfig: ListConfigSchema,
+  ListStatus: ListStatusSchema,
+  ScrapingConfig: ScrapingConfigSchema,
+  IcpRubric: IcpRubricSchema,
+  PipelineConfig: PipelineConfigSchema,
+  PipelineStage: PipelineStageSchema,
+  ProcessingStageStatus: ProcessingStageStatusSchema,
   ListStageCounts: ListStageCountsSchema,
   ListTelemetry: ListTelemetrySchema,
-  PipelineStep: PipelineStepSchema,
 
   // Requests
   CreateListRequest: CreateListRequestSchema,
   UpdateListRequest: UpdateListRequestSchema,
+  UpdateListStatusRequest: UpdateListStatusRequestSchema,
   UpdateListConfigRequest: UpdateListConfigRequestSchema,
   AddCompaniesToListRequest: AddCompaniesToListRequestSchema,
   RemoveCompaniesFromListRequest: RemoveCompaniesFromListRequestSchema,
@@ -832,20 +1024,70 @@ export const AcqListSchemas = {
   AcqListListResponse: AcqListListResponseSchema,
   ListTelemetryResponse: ListTelemetryResponseSchema,
   ListTelemetryListResponse: ListTelemetryListResponseSchema,
-  ListExecutionsResponse: ListExecutionsResponseSchema
+  ListExecutionsResponse: ListExecutionsResponseSchema,
+  ListProgressResponse: ListProgressResponseSchema
+}
+
+// ---------------------------------------------------------------------------
+// Track A/B bundled schemas
+// ---------------------------------------------------------------------------
+
+export const AcqSubstrateSchemas = {
+  // Artifacts
+  ListArtifactsQuery: ListArtifactsQuerySchema,
+  CreateArtifactRequest: CreateArtifactRequestSchema,
+  AcqArtifactResponse: AcqArtifactResponseSchema,
+  AcqArtifactListResponse: AcqArtifactListResponseSchema,
+
+  // List members
+  ListMembersQuery: ListMembersQuerySchema,
+  MemberIdParams: MemberIdParamsSchema,
+  AcqListMemberResponse: AcqListMemberResponseSchema,
+  AcqListMembersResponse: AcqListMembersResponseSchema,
+
+  // List companies
+  ListCompanyIdParams: ListCompanyIdParamsSchema,
+  AcqListCompanyResponse: AcqListCompanyResponseSchema,
+
+  // Transition (shared with deals — TransitionItemRequestSchema)
+  TransitionItemRequest: TransitionItemRequestSchema
 }
 
 // ---------------------------------------------------------------------------
 // Inferred types
 // ---------------------------------------------------------------------------
 
-export type ListConfigInput = z.infer<typeof ListConfigSchema>
+// ---------------------------------------------------------------------------
+// Inferred types — Track A/B substrate
+// ---------------------------------------------------------------------------
+
+export type AcqArtifactOwnerKind = z.infer<typeof AcqArtifactOwnerKindSchema>
+export type ListArtifactsQuery = z.infer<typeof ListArtifactsQuerySchema>
+export type CreateArtifactRequest = z.infer<typeof CreateArtifactRequestSchema>
+export type AcqArtifactResponse = z.infer<typeof AcqArtifactResponseSchema>
+export type AcqArtifactListResponse = z.infer<typeof AcqArtifactListResponseSchema>
+export type ListMembersQuery = z.infer<typeof ListMembersQuerySchema>
+export type MemberIdParams = z.infer<typeof MemberIdParamsSchema>
+export type AcqListMemberContactSummary = z.infer<typeof AcqListMemberContactSummarySchema>
+export type AcqListMemberResponse = z.infer<typeof AcqListMemberResponseSchema>
+export type AcqListMembersResponse = z.infer<typeof AcqListMembersResponseSchema>
+export type ListCompanyIdParams = z.infer<typeof ListCompanyIdParamsSchema>
+export type AcqListCompanyResponse = z.infer<typeof AcqListCompanyResponseSchema>
+
+// ---------------------------------------------------------------------------
+
+export type ListStatus = z.infer<typeof ListStatusSchema>
+export type ScrapingConfig = z.infer<typeof ScrapingConfigSchema>
+export type IcpRubric = z.infer<typeof IcpRubricSchema>
+export type PipelineStage = z.infer<typeof PipelineStageSchema>
+export type PipelineConfig = z.infer<typeof PipelineConfigSchema>
+export type ProcessingStageStatus = z.infer<typeof ProcessingStageStatusSchema>
 export type ListStageCountsInput = z.infer<typeof ListStageCountsSchema>['stageCounts']
 export type ListTelemetryInput = z.infer<typeof ListTelemetrySchema>
-export type PipelineStepInput = z.infer<typeof PipelineStepSchema>
 export type ListIdParams = z.infer<typeof ListIdParamsSchema>
 export type CreateListRequest = z.infer<typeof CreateListRequestSchema>
 export type UpdateListRequest = z.infer<typeof UpdateListRequestSchema>
+export type UpdateListStatusRequest = z.infer<typeof UpdateListStatusRequestSchema>
 export type UpdateListConfigRequest = z.infer<typeof UpdateListConfigRequestSchema>
 export type AddCompaniesToListRequest = z.infer<typeof AddCompaniesToListRequestSchema>
 export type RemoveCompaniesFromListRequest = z.infer<typeof RemoveCompaniesFromListRequestSchema>
@@ -857,3 +1099,5 @@ export type ListTelemetryResponse = z.infer<typeof ListTelemetryResponseSchema>
 export type ListTelemetryListResponse = z.infer<typeof ListTelemetryListResponseSchema>
 export type ListExecutionSummaryInput = z.infer<typeof ListExecutionSummarySchema>
 export type ListExecutionsResponse = z.infer<typeof ListExecutionsResponseSchema>
+export type ListStageProgress = z.infer<typeof ListStageProgressSchema>
+export type ListProgress = z.infer<typeof ListProgressResponseSchema>

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)
+          }
+        }
+      }
+    }
+  })
+})