// ============================================================================
// Lead-Gen Stage Catalog (OM Spine processing-state model)
//
// Canonical set of processing stage keys for acq_companies.processing_state and
// acq_contacts.processing_state. These keys coordinate build templates, workflow
// factory validation, API filters, and UI progress projections.
//
// State is sparse: absent keys mean "not attempted"; present keys hold terminal
// status entries such as success, no_result, skipped, or error.
//
// Historical sources:
//   ACQ_LIST_MEMBERS_LEAD_GEN_PIPELINE   -> personalized, uploaded, interested,
//                                          discovered, verified
//   ACQ_LIST_COMPANIES_LEAD_GEN_PIPELINE -> populated, extracted, qualified
//   Design plan hint (lead-gen-domain-cleanup.mdx section 4) -> scraped, enriched
//
// ============================================================================

/** One entry in the lead-gen stage catalog. */
export interface LeadGenStageCatalogEntry {
  /** Matches the status key written into processing_state jsonb (e.g. 'scraped'). */
  key: string
  /** Human-readable label for UI display. */
  label: string
  /** Short description of what this stage represents. */
  description: string
  /** Canonical pipeline order for UI sorting. Lower = earlier in the funnel. */
  order: number
  /** Which entity's processing_state jsonb carries this stage status. */
  entity: 'company' | 'contact'
  /** Additional entities allowed to write/read this processing_state key. */
  additionalEntities?: Array<'company' | 'contact'>
  /**
   * Optional read-side override for Records views when a company-scoped step
   * produces records on a different entity.
   */
  recordEntity?: 'company' | 'contact'
  /** Stage key to read from recordEntity.processing_state for Records views. */
  recordStageKey?: string
}

