@elevasis/core 0.18.0 → 0.20.0

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

@@ -1,10 +1,45 @@
 import { z } from 'zod'
 import { UuidSchema, NonEmptyStringSchema } from '../../platform/utils/validation'
-import { LEAD_GEN_STAGE_CATALOG } from '../../organization-model/domains/sales'
+import { CRM_PIPELINE_DEFINITION, LEAD_GEN_STAGE_CATALOG } from '../../organization-model/domains/sales'
+import { CAPABILITY_REGISTRY } from '../../organization-model/domains/prospecting'
 import { isProspectingBuildTemplateId } from './build-templates'
 export { CrmPriorityBucketKeySchema, CrmPriorityBucketOverrideSchema, CrmPriorityOverrideSchema } from './crm-priority'
 export type { CrmPriorityBucketOverride, CrmPriorityOverride, ResolvedCrmPriorityRuleConfig } from './crm-priority'
 
+export const ProcessingStageStatusSchema = z.enum(['success', 'no_result', 'skipped', 'error'])
+
+export const LeadGenStageKeySchema = z
+  .string()
+  .refine((value) => Object.prototype.hasOwnProperty.call(LEAD_GEN_STAGE_CATALOG, value), {
+    message: 'processing state key must match LEAD_GEN_STAGE_CATALOG'
+  })
+
+export const LeadGenCapabilityKeySchema = z
+  .string()
+  .refine((value) => CAPABILITY_REGISTRY.some((c) => c.id === value), {
+    message: 'capabilityKey must match CAPABILITY_REGISTRY'
+  })
+
+const crmStageKeys = CRM_PIPELINE_DEFINITION.stages.map((stage) => stage.stageKey) as [string, ...string[]]
+const crmStateKeys = CRM_PIPELINE_DEFINITION.stages.flatMap((stage) => stage.states.map((state) => state.stateKey)) as [
+  string,
+  ...string[]
+]
+
+export const CrmStageKeySchema = z.enum(crmStageKeys)
+export const CrmStateKeySchema = z.enum(crmStateKeys)
+
+export const ProcessingStateEntrySchema = z
+  .object({
+    status: ProcessingStageStatusSchema,
+    data: z.unknown().optional()
+  })
+  .passthrough()
+
+export const ProcessingStateSchema = z.record(LeadGenStageKeySchema, ProcessingStateEntrySchema)
+export const CompanyProcessingStateSchema = ProcessingStateSchema
+export const ContactProcessingStateSchema = ProcessingStateSchema
+
 /**
  * Deal Management API Schemas
  *
@@ -21,7 +56,7 @@ export type { CrmPriorityBucketOverride, CrmPriorityOverride, ResolvedCrmPriorit
 // Enum literals (must match DB CHECK constraints exactly)
 // ---------------------------------------------------------------------------
 
-export const DealStageSchema = z.enum(['interested', 'proposal', 'closing', 'closed_won', 'closed_lost', 'nurturing'])
+export const DealStageSchema = CrmStageKeySchema
 
 export const AcqDealTaskKindSchema = z.enum(['call', 'email', 'meeting', 'other'])
 
@@ -89,7 +124,17 @@ export const TransitionItemRequestSchema = z
   .object({
     pipelineKey: z.string().min(1),
     stageKey: z.string().min(1),
-    stateKey: z.string().nullable().optional(),
+    stateKey: z.string().min(1).nullable().optional(),
+    reason: z.string().optional(),
+    expectedUpdatedAt: z.string().datetime().optional()
+  })
+  .strict()
+
+export const CrmTransitionItemRequestSchema = z
+  .object({
+    pipelineKey: z.literal(CRM_PIPELINE_DEFINITION.pipelineKey),
+    stageKey: CrmStageKeySchema,
+    stateKey: CrmStateKeySchema.nullable().optional(),
     reason: z.string().optional(),
     expectedUpdatedAt: z.string().datetime().optional()
   })
@@ -97,7 +142,7 @@ export const TransitionItemRequestSchema = z
 
 export const TransitionDealStateRequestSchema = z
   .object({
-    stateKey: z.string().min(1),
+    stateKey: CrmStateKeySchema,
     reason: z.string().optional(),
     expectedUpdatedAt: z.string().datetime().optional()
   })
@@ -132,7 +177,7 @@ export const DealContactSummarySchema = z.object({
   title: z.string().nullable(),
   headline: z.string().nullable(),
   linkedin_url: z.string().nullable(),
-  pipeline_status: z.record(z.string(), z.unknown()).nullable(),
+  processing_state: ProcessingStateSchema.nullable(),
   enrichment_data: z.record(z.string(), z.unknown()).nullable(),
   company: z
     .object({
@@ -305,6 +350,11 @@ export const DealTaskListResponseSchema = z.array(DealTaskResponseSchema)
 // ---------------------------------------------------------------------------
 
 export const DealSchemas = {
+  // Primitives
+  CrmStageKey: CrmStageKeySchema,
+  CrmStateKey: CrmStateKeySchema,
+  DealStage: DealStageSchema,
+
   // Params
   DealIdParams: DealIdParamsSchema,
   DealTaskIdParams: DealTaskIdParamsSchema,
@@ -317,7 +367,7 @@ export const DealSchemas = {
   // Request bodies
   CreateDealNoteRequest: CreateDealNoteRequestSchema,
   CreateDealTaskRequest: CreateDealTaskRequestSchema,
-  TransitionItemRequest: TransitionItemRequestSchema,
+  TransitionItemRequest: CrmTransitionItemRequestSchema,
   TransitionDealStateRequest: TransitionDealStateRequestSchema,
   ExecuteActionParams: ExecuteActionParamsSchema,
   ExecuteActionRequest: ExecuteActionRequestSchema,
@@ -340,6 +390,8 @@ export const DealSchemas = {
 // ---------------------------------------------------------------------------
 
 export type DealStage = z.infer<typeof DealStageSchema>
+export type CrmStageKey = z.infer<typeof CrmStageKeySchema>
+export type CrmStateKey = z.infer<typeof CrmStateKeySchema>
 export type AcqDealTaskKind = z.infer<typeof AcqDealTaskKindSchema>
 export type DealIdParams = z.infer<typeof DealIdParamsSchema>
 export type DealTaskIdParams = z.infer<typeof DealTaskIdParamsSchema>
@@ -349,6 +401,7 @@ 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 CrmTransitionItemRequest = z.infer<typeof CrmTransitionItemRequestSchema>
 export type TransitionDealStateRequest = z.infer<typeof TransitionDealStateRequestSchema>
 export type ExecuteActionParams = z.infer<typeof ExecuteActionParamsSchema>
 export type ExecuteActionRequest = z.infer<typeof ExecuteActionRequestSchema>
@@ -442,10 +495,10 @@ export const BuildPlanSnapshotStepSchema = z
     description: z.string().trim().min(1).max(2000).optional(),
     primaryEntity: z.enum(['company', 'contact']),
     outputs: z.array(z.enum(['company', 'contact', 'export'])).min(1),
-    stageKey: z.string().trim().min(1).max(100),
+    stageKey: LeadGenStageKeySchema,
     dependsOn: z.array(z.string().trim().min(1).max(100)).optional(),
     dependencyMode: z.literal('per-record-eligibility'),
-    capabilityKey: z.string().trim().min(1).max(100),
+    capabilityKey: LeadGenCapabilityKeySchema,
     defaultBatchSize: z.number().int().positive(),
     maxBatchSize: z.number().int().positive()
   })
@@ -454,11 +507,38 @@ export const BuildPlanSnapshotStepSchema = z
     path: ['defaultBatchSize']
   })
 
-export const BuildPlanSnapshotSchema = z.object({
-  templateId: z.string().trim().min(1).max(100),
-  templateLabel: z.string().trim().min(1).max(120),
-  steps: z.array(BuildPlanSnapshotStepSchema).min(1)
-})
+export const BuildPlanSnapshotSchema = z
+  .object({
+    templateId: z.string().trim().min(1).max(100),
+    templateLabel: z.string().trim().min(1).max(120),
+    steps: z.array(BuildPlanSnapshotStepSchema).min(1)
+  })
+  .superRefine((snapshot, ctx) => {
+    const stepIds = new Set<string>()
+
+    snapshot.steps.forEach((step, index) => {
+      if (stepIds.has(step.id)) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: `duplicate build-plan step id "${step.id}"`,
+          path: ['steps', index, 'id']
+        })
+      }
+      stepIds.add(step.id)
+    })
+
+    snapshot.steps.forEach((step, index) => {
+      for (const dependencyId of step.dependsOn ?? []) {
+        if (!stepIds.has(dependencyId)) {
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `dependsOn references unknown build-plan step "${dependencyId}"`,
+            path: ['steps', index, 'dependsOn']
+          })
+        }
+      }
+    })
+  })
 
 export const AcqListMetadataSchema = z
   .object({
@@ -638,13 +718,6 @@ 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,
@@ -704,29 +777,6 @@ export const AcqCompanyStatusSchema = z.enum(['active', 'invalid'])
 export const AcqContactStatusSchema = z.enum(['active', 'invalid'])
 export const AcqEmailValidSchema = z.enum(['VALID', 'INVALID', 'RISKY', 'UNKNOWN'])
 
-/**
- * Zod schema mirroring the CompanyPipelineStatus interface from types.ts.
- * Used by operations-layer CompanyRecord schemas to validate pipelineStatus
- * against the canonical shape instead of using open passthrough().
- */
-export const CompanyPipelineStatusSchema = z
-  .object({
-    acquired: z.boolean().optional(),
-    enrichment: z
-      .record(
-        z.string(),
-        z
-          .object({
-            status: z.enum(['pending', 'complete', 'failed', 'skipped']),
-            completedAt: z.string().optional(),
-            error: z.string().optional()
-          })
-          .passthrough()
-      )
-      .optional()
-  })
-  .passthrough()
-
 export const CompanyIdParamsSchema = z.object({
   companyId: UuidSchema
 })
@@ -743,6 +793,7 @@ export const ListCompaniesQuerySchema = z
     website: z.string().trim().min(1).max(2048).optional(),
     segment: z.string().trim().min(1).max(255).optional(),
     category: z.string().trim().min(1).max(255).optional(),
+    pipelineStatus: z.unknown().optional(),
     batchId: z.string().trim().min(1).max(255).optional(),
     status: AcqCompanyStatusSchema.optional(),
     includeAll: QueryBooleanSchema.optional(),
@@ -776,6 +827,7 @@ export const CreateCompanyRequestSchema = z
     category: z.string().trim().min(1).max(255).optional(),
     source: z.string().trim().min(1).max(255).optional(),
     batchId: z.string().trim().min(1).max(255).optional(),
+    pipelineStatus: z.unknown().optional(),
     verticalResearch: z.string().trim().min(1).max(5000).optional()
   })
   .strict()
@@ -792,7 +844,8 @@ export const UpdateCompanyRequestSchema = z
     locationState: z.string().trim().min(1).max(255).optional(),
     category: z.string().trim().min(1).max(255).optional(),
     segment: z.string().trim().min(1).max(255).optional(),
-    pipelineStatus: z.record(z.string(), z.unknown()).optional(),
+    processingState: CompanyProcessingStateSchema.optional(),
+    pipelineStatus: z.unknown().optional(),
     enrichmentData: z.record(z.string(), z.unknown()).optional(),
     source: z.string().trim().min(1).max(255).optional(),
     batchId: z.string().trim().min(1).max(255).optional(),
@@ -812,6 +865,7 @@ export const UpdateCompanyRequestSchema = z
       data.locationState !== undefined ||
       data.category !== undefined ||
       data.segment !== undefined ||
+      data.processingState !== undefined ||
       data.pipelineStatus !== undefined ||
       data.enrichmentData !== undefined ||
       data.source !== undefined ||
@@ -833,7 +887,8 @@ export const CreateContactRequestSchema = z
     title: z.string().trim().min(1).max(255).optional(),
     source: z.string().trim().min(1).max(255).optional(),
     sourceId: z.string().trim().min(1).max(255).optional(),
-    batchId: z.string().trim().min(1).max(255).optional()
+    batchId: z.string().trim().min(1).max(255).optional(),
+    pipelineStatus: z.unknown().optional()
   })
   .strict()
 
@@ -848,7 +903,8 @@ export const UpdateContactRequestSchema = z
     headline: z.string().trim().min(1).max(5000).optional(),
     filterReason: z.string().trim().min(1).max(5000).optional(),
     openingLine: z.string().trim().min(1).max(5000).optional(),
-    pipelineStatus: z.record(z.string(), z.unknown()).optional(),
+    processingState: ContactProcessingStateSchema.optional(),
+    pipelineStatus: z.unknown().optional(),
     enrichmentData: z.record(z.string(), z.unknown()).optional(),
     status: AcqContactStatusSchema.optional()
   })
@@ -864,6 +920,7 @@ export const UpdateContactRequestSchema = z
       data.headline !== undefined ||
       data.filterReason !== undefined ||
       data.openingLine !== undefined ||
+      data.processingState !== undefined ||
       data.pipelineStatus !== undefined ||
       data.enrichmentData !== undefined ||
       data.status !== undefined,
@@ -886,7 +943,8 @@ export const AcqCompanyResponseSchema = z.object({
   category: z.string().nullable(),
   categoryPain: z.string().nullable(),
   segment: z.string().nullable(),
-  pipelineStatus: z.record(z.string(), z.unknown()).nullable(),
+  processingState: CompanyProcessingStateSchema.nullable(),
+  pipelineStatus: z.unknown().nullable().optional(),
   enrichmentData: z.record(z.string(), z.unknown()).nullable(),
   source: z.string().nullable(),
   batchId: z.string().nullable(),
@@ -936,7 +994,8 @@ export const AcqContactResponseSchema = z.object({
   openingLine: z.string().nullable(),
   source: z.string().nullable(),
   sourceId: z.string().nullable(),
-  pipelineStatus: z.record(z.string(), z.unknown()).nullable(),
+  processingState: ContactProcessingStateSchema.nullable(),
+  pipelineStatus: z.unknown().nullable().optional(),
   enrichmentData: z.record(z.string(), z.unknown()).nullable(),
   attioPersonId: z.string().nullable(),
   batchId: z.string().nullable(),
@@ -1058,11 +1117,12 @@ export const AcqListCompanyResponseSchema = z.object({
 })
 
 // ---------------------------------------------------------------------------
-// Track B: Transition Request (shared by list, list-member, list-company)
-// TransitionItemRequestSchema already exists above (for deals) — reuse it.
+// Track B: Transition request for list, list-member, and list-company substrate routes.
+// CRM deals use DealSchemas.TransitionItemRequest, which is catalog-backed.
 // ---------------------------------------------------------------------------
 
 export const AcqCompanySchemas = {
+  CompanyProcessingState: CompanyProcessingStateSchema,
   CompanyIdParams: CompanyIdParamsSchema,
   ListCompaniesQuery: ListCompaniesQuerySchema,
   CreateCompanyRequest: CreateCompanyRequestSchema,
@@ -1073,6 +1133,7 @@ export const AcqCompanySchemas = {
 }
 
 export const AcqContactSchemas = {
+  ContactProcessingState: ContactProcessingStateSchema,
   ContactIdParams: ContactIdParamsSchema,
   ListContactsQuery: ListContactsQuerySchema,
   CreateContactRequest: CreateContactRequestSchema,
@@ -1116,7 +1177,10 @@ export const AcqListSchemas = {
   BuildPlanSnapshot: BuildPlanSnapshotSchema,
   BuildPlanSnapshotStep: BuildPlanSnapshotStepSchema,
   AcqListMetadata: AcqListMetadataSchema,
+  LeadGenStageKey: LeadGenStageKeySchema,
+  LeadGenCapabilityKey: LeadGenCapabilityKeySchema,
   ProcessingStageStatus: ProcessingStageStatusSchema,
+  ProcessingState: ProcessingStateSchema,
   ListStageCounts: ListStageCountsSchema,
   ListTelemetry: ListTelemetrySchema,
 
@@ -1160,7 +1224,7 @@ export const AcqSubstrateSchemas = {
   ListCompanyIdParams: ListCompanyIdParamsSchema,
   AcqListCompanyResponse: AcqListCompanyResponseSchema,
 
-  // Transition (shared with deals — TransitionItemRequestSchema)
+  // Transition (generic stateful substrate)
   TransitionItemRequest: TransitionItemRequestSchema
 }
 
@@ -1195,6 +1259,7 @@ export type PipelineConfig = z.infer<typeof PipelineConfigSchema>
 export type BuildPlanSnapshotStep = z.infer<typeof BuildPlanSnapshotStepSchema>
 export type BuildPlanSnapshot = z.infer<typeof BuildPlanSnapshotSchema>
 export type AcqListMetadata = z.infer<typeof AcqListMetadataSchema>
+export type LeadGenCapabilityKey = z.infer<typeof LeadGenCapabilityKeySchema>
 export type ProcessingStageStatus = z.infer<typeof ProcessingStageStatusSchema>
 export type ListStageCountsInput = z.infer<typeof ListStageCountsSchema>['stageCounts']
 export type ListTelemetryInput = z.infer<typeof ListTelemetrySchema>

package/src/business/acquisition/build-templates.test.ts

@@ -0,0 +1,212 @@
+import { describe, expect, it } from 'vitest'
+import {
+  DEFAULT_PROSPECTING_BUILD_TEMPLATE_ID,
+  PROSPECTING_BUILD_TEMPLATE_OPTIONS,
+  createBuildPlanSnapshotFromTemplateId,
+  isProspectingBuildTemplateId
+} from './build-templates'
+
+// ---------------------------------------------------------------------------
+// isProspectingBuildTemplateId
+// ---------------------------------------------------------------------------
+
+describe('isProspectingBuildTemplateId', () => {
+  it('returns true for every id in PROSPECTING_BUILD_TEMPLATE_OPTIONS', () => {
+    for (const option of PROSPECTING_BUILD_TEMPLATE_OPTIONS) {
+      expect(isProspectingBuildTemplateId(option.id)).toBe(true)
+    }
+  })
+
+  it('returns true for the known "local-services" template id', () => {
+    expect(isProspectingBuildTemplateId('local-services')).toBe(true)
+  })
+
+  it('returns true for the known "dtc-subscription-apollo-clickup" template id', () => {
+    expect(isProspectingBuildTemplateId('dtc-subscription-apollo-clickup')).toBe(true)
+  })
+
+  it('returns false for an unknown string', () => {
+    expect(isProspectingBuildTemplateId('not-a-template')).toBe(false)
+  })
+
+  it('returns false for an empty string', () => {
+    expect(isProspectingBuildTemplateId('')).toBe(false)
+  })
+
+  it('returns false for a partial id match', () => {
+    expect(isProspectingBuildTemplateId('local')).toBe(false)
+    expect(isProspectingBuildTemplateId('dtc-subscription')).toBe(false)
+  })
+
+  it('returns false for a whitespace-padded id', () => {
+    expect(isProspectingBuildTemplateId(' local-services ')).toBe(false)
+  })
+
+  it('verifies PROSPECTING_BUILD_TEMPLATE_OPTIONS contains at least two entries', () => {
+    expect(PROSPECTING_BUILD_TEMPLATE_OPTIONS.length).toBeGreaterThanOrEqual(2)
+  })
+
+  it('verifies DEFAULT_PROSPECTING_BUILD_TEMPLATE_ID is itself a valid template id', () => {
+    expect(isProspectingBuildTemplateId(DEFAULT_PROSPECTING_BUILD_TEMPLATE_ID)).toBe(true)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// createBuildPlanSnapshotFromTemplateId — unknown id
+// ---------------------------------------------------------------------------
+
+describe('createBuildPlanSnapshotFromTemplateId — unknown id', () => {
+  it('returns null for an unknown template id', () => {
+    expect(createBuildPlanSnapshotFromTemplateId('not-a-template')).toBeNull()
+  })
+
+  it('returns null for an empty string', () => {
+    expect(createBuildPlanSnapshotFromTemplateId('')).toBeNull()
+  })
+})
+
+// ---------------------------------------------------------------------------
+// createBuildPlanSnapshotFromTemplateId — "local-services"
+// ---------------------------------------------------------------------------
+
+describe('createBuildPlanSnapshotFromTemplateId — "local-services"', () => {
+  const snapshot = createBuildPlanSnapshotFromTemplateId('local-services')
+
+  it('returns a non-null snapshot', () => {
+    expect(snapshot).not.toBeNull()
+  })
+
+  it('preserves the template id in the snapshot', () => {
+    expect(snapshot?.templateId).toBe('local-services')
+  })
+
+  it('includes a non-empty templateLabel', () => {
+    expect(snapshot?.templateLabel).toBeTruthy()
+  })
+
+  it('produces a steps array with length matching the catalog (7 steps)', () => {
+    expect(snapshot?.steps).toHaveLength(7)
+  })
+
+  it('every step has required fields: id, label, primaryEntity, outputs, stageKey, dependencyMode, capabilityKey', () => {
+    for (const step of snapshot?.steps ?? []) {
+      expect(step.id).toBeTruthy()
+      expect(step.label).toBeTruthy()
+      expect(['company', 'contact']).toContain(step.primaryEntity)
+      expect(step.outputs.length).toBeGreaterThanOrEqual(1)
+      expect(step.stageKey).toBeTruthy()
+      expect(step.dependencyMode).toBe('per-record-eligibility')
+      expect(step.capabilityKey).toBeTruthy()
+    }
+  })
+
+  it('every step has positive defaultBatchSize and maxBatchSize', () => {
+    for (const step of snapshot?.steps ?? []) {
+      expect(step.defaultBatchSize).toBeGreaterThan(0)
+      expect(step.maxBatchSize).toBeGreaterThanOrEqual(step.defaultBatchSize)
+    }
+  })
+
+  it('steps with declared dependsOn in the catalog have dependsOn in the snapshot', () => {
+    const withDeps = snapshot?.steps.filter((step) => step.dependsOn !== undefined) ?? []
+    expect(withDeps.length).toBeGreaterThan(0)
+    for (const step of withDeps) {
+      expect(Array.isArray(step.dependsOn)).toBe(true)
+      expect((step.dependsOn ?? []).length).toBeGreaterThan(0)
+    }
+  })
+
+  it('the first step (source-companies) has no dependsOn', () => {
+    const first = snapshot?.steps[0]
+    expect(first?.id).toBe('source-companies')
+    expect(first?.dependsOn).toBeUndefined()
+  })
+
+  it('outputs arrays are copies (mutation does not affect subsequent calls)', () => {
+    const snapshotA = createBuildPlanSnapshotFromTemplateId('local-services')
+    const snapshotB = createBuildPlanSnapshotFromTemplateId('local-services')
+    snapshotA?.steps[0]?.outputs.push('export' as never)
+    expect(snapshotB?.steps[0]?.outputs).not.toContain('export')
+  })
+})
+
+// ---------------------------------------------------------------------------
+// createBuildPlanSnapshotFromTemplateId — "dtc-subscription-apollo-clickup"
+// ---------------------------------------------------------------------------
+
+describe('createBuildPlanSnapshotFromTemplateId — "dtc-subscription-apollo-clickup"', () => {
+  const snapshot = createBuildPlanSnapshotFromTemplateId('dtc-subscription-apollo-clickup')
+
+  it('returns a non-null snapshot', () => {
+    expect(snapshot).not.toBeNull()
+  })
+
+  it('preserves the template id in the snapshot', () => {
+    expect(snapshot?.templateId).toBe('dtc-subscription-apollo-clickup')
+  })
+
+  it('produces a steps array with length matching the catalog (6 steps)', () => {
+    expect(snapshot?.steps).toHaveLength(6)
+  })
+
+  it('every step has required fields: id, label, primaryEntity, outputs, stageKey, dependencyMode, capabilityKey', () => {
+    for (const step of snapshot?.steps ?? []) {
+      expect(step.id).toBeTruthy()
+      expect(step.label).toBeTruthy()
+      expect(['company', 'contact']).toContain(step.primaryEntity)
+      expect(step.outputs.length).toBeGreaterThanOrEqual(1)
+      expect(step.stageKey).toBeTruthy()
+      expect(step.dependencyMode).toBe('per-record-eligibility')
+      expect(step.capabilityKey).toBeTruthy()
+    }
+  })
+
+  it('every step has positive defaultBatchSize and maxBatchSize', () => {
+    for (const step of snapshot?.steps ?? []) {
+      expect(step.defaultBatchSize).toBeGreaterThan(0)
+      expect(step.maxBatchSize).toBeGreaterThanOrEqual(step.defaultBatchSize)
+    }
+  })
+
+  it('the first step (import-apollo-search) has no dependsOn', () => {
+    const first = snapshot?.steps[0]
+    expect(first?.id).toBe('import-apollo-search')
+    expect(first?.dependsOn).toBeUndefined()
+  })
+
+  it('the first step outputs both company and contact', () => {
+    const first = snapshot?.steps[0]
+    expect(first?.outputs).toContain('company')
+    expect(first?.outputs).toContain('contact')
+  })
+
+  it('the final step (review-and-export) outputs export', () => {
+    const last = snapshot?.steps[snapshot.steps.length - 1]
+    expect(last?.id).toBe('review-and-export')
+    expect(last?.outputs).toContain('export')
+  })
+
+  it('steps with descriptions in the catalog include description in the snapshot', () => {
+    const withDesc = snapshot?.steps.filter((step) => step.description !== undefined) ?? []
+    expect(withDesc.length).toBeGreaterThan(0)
+    for (const step of withDesc) {
+      expect(typeof step.description).toBe('string')
+      expect(step.description!.length).toBeGreaterThan(0)
+    }
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Snapshot shape contract — applies to every valid template id
+// ---------------------------------------------------------------------------
+
+describe('createBuildPlanSnapshotFromTemplateId — shape contract for all templates', () => {
+  it('returns a snapshot for every id that isProspectingBuildTemplateId reports valid', () => {
+    for (const option of PROSPECTING_BUILD_TEMPLATE_OPTIONS) {
+      const snapshot = createBuildPlanSnapshotFromTemplateId(option.id)
+      expect(snapshot).not.toBeNull()
+      expect(snapshot?.templateId).toBe(option.id)
+      expect(snapshot?.steps.length).toBeGreaterThan(0)
+    }
+  })
+})

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

@@ -20,7 +20,7 @@ function makeDeal(
     organization_id: 'org-fixture-id',
     contact_id: null,
     contact_email: 'fixture@example.com',
-    pipeline_key: 'default',
+    pipeline_key: 'crm',
     stage_key: null,
     state_key: null,
     activity_log: [],

package/src/business/acquisition/types.ts

@@ -1,5 +1,7 @@
 import type { Database } from '../../supabase/database.types'
-import type { PipelineStage } from './api-schemas'
+import type { Capability } from '../../organization-model/domains/prospecting'
+import type { LEAD_GEN_STAGE_CATALOG } from '../../organization-model/domains/sales'
+import type { PipelineStage, ProcessingStageStatus } from './api-schemas'
 
 // =============================================================================
 // Supabase-Generated Types (Re-exported from database.types)
@@ -49,43 +51,20 @@ export interface WebPost {
   aiInsight?: string
 }
 
-/**
- * Tracks pipeline status for a company across all processing stages.
- */
-export interface CompanyPipelineStatus {
-  acquired: boolean
-  enrichment: {
-    [source: string]: {
-      status: 'pending' | 'complete' | 'failed' | 'skipped'
-      completedAt?: string
-      error?: string
-    }
-  }
-}
+export type LeadGenStageKey = (typeof LEAD_GEN_STAGE_CATALOG)[keyof typeof LEAD_GEN_STAGE_CATALOG]['key']
+export type LeadGenCapabilityKey = Capability['id']
 
-/**
- * Tracks pipeline status for a contact across all processing stages.
- */
-export interface ContactPipelineStatus {
-  enrichment: {
-    [source: string]: {
-      status: 'pending' | 'complete' | 'failed' | 'skipped'
-      completedAt?: string
-      error?: string
-    }
-  }
-  personalization: {
-    status: 'pending' | 'complete' | 'failed' | 'skipped'
-    completedAt?: string
-  }
-  outreach: {
-    status: 'pending' | 'sent' | 'replied' | 'bounced' | 'opted-out'
-    sentAt?: string
-    channel?: string
-    campaignId?: string
-  }
+export interface ProcessingStateEntry {
+  status: ProcessingStageStatus
+  data?: unknown
 }
 
+export type ProcessingState = Partial<Record<LeadGenStageKey, ProcessingStateEntry>>
+export type CompanyProcessingState = ProcessingState
+export type ContactProcessingState = ProcessingState
+/** @deprecated Use `processingState`. Retained only as a compile-time/read-shape bridge for external tenants. */
+export type LegacyPipelineStatus = unknown
+
 /**
  * Enrichment data collected for a company from various sources.
  */
@@ -241,7 +220,9 @@ export interface AcqCompany {
   category: string | null
   categoryPain: string | null
   segment: string | null
-  pipelineStatus: CompanyPipelineStatus | null
+  processingState: CompanyProcessingState | null
+  /** @deprecated Use `processingState`. This legacy DB column has been removed; responses return null. */
+  pipelineStatus?: LegacyPipelineStatus | null
   enrichmentData: CompanyEnrichmentData | null
   source: string | null
   batchId: string | null
@@ -277,7 +258,9 @@ export interface AcqContact {
   openingLine: string | null
   source: string | null
   sourceId: string | null
-  pipelineStatus: ContactPipelineStatus | null
+  processingState: ContactProcessingState | null
+  /** @deprecated Use `processingState`. This legacy DB column has been removed; responses return null. */
+  pipelineStatus?: LegacyPipelineStatus | null
   enrichmentData: ContactEnrichmentData | null
   /** Attio Person record ID - set when contact responds and is added to CRM */
   attioPersonId: string | null
@@ -318,7 +301,7 @@ export interface DealContact {
   title: string | null
   headline: string | null
   linkedin_url: string | null
-  pipeline_status: Record<string, unknown> | null
+  processing_state: Record<string, unknown> | null
   enrichment_data: Record<string, unknown> | null
   company: {
     id: string