mappedSpeciesSet, mappedCalltypes := collectMappedLabels(mapping, dataCalltypes)
	// Validate species exist in DB
	if err := validateMappedSpecies(queryer, mappedSpeciesSet, &result); err != nil {
		return result, err
	}
	// Validate calltypes exist in DB
	if err := validateMappedCalltypes(queryer, mappedCalltypes, &result); err != nil {
		return result, err
	}
	return result, nil
}
// collectMappedLabels builds sets of mapped species and calltype labels
func collectMappedLabels(mapping MappingFile, dataCalltypes map[string]map[string]bool) (map[string]bool, map[string]map[string]string) {

	// Validate species exist in DB

	return mappedSpeciesSet, mappedCalltypes
}
// validateMappedSpecies checks that all mapped species exist in the database
func validateMappedSpecies(queryer DB, mappedSpeciesSet map[string]bool, result *MappingValidationResult) error {

	if len(speciesLabels) == 0 {
		return nil
	}

	if len(speciesLabels) > 0 {
		query := `SELECT label FROM species WHERE label IN (` + db.Placeholders(len(speciesLabels)) + `) AND active = true`
		args := make([]any, len(speciesLabels))
		for i, s := range speciesLabels {
			args[i] = s
		}

	query := `SELECT label FROM species WHERE label IN (` + db.Placeholders(len(speciesLabels)) + `) AND active = true`
	args := make([]any, len(speciesLabels))
	for i, s := range speciesLabels {
		args[i] = s
	}

		rows, err := queryer.Query(query, args...)
		if err != nil {
			return result, fmt.Errorf("failed to query species: %w", err)
		}
		defer rows.Close()

	rows, err := queryer.Query(query, args...)
	if err != nil {
		return fmt.Errorf("failed to query species: %w", err)
	}
	defer rows.Close()

		foundSpecies := make(map[string]bool)
		for rows.Next() {
			var label string
			if err := rows.Scan(&label); err == nil {
				foundSpecies[label] = true
			}

	foundSpecies := make(map[string]bool)
	for rows.Next() {
		var label string
		if err := rows.Scan(&label); err == nil {
			foundSpecies[label] = true

	}

		for _, s := range speciesLabels {
			if !foundSpecies[s] {
				result.MissingDBSpecies = append(result.MissingDBSpecies, s)
			}

	for _, s := range speciesLabels {
		if !foundSpecies[s] {
			result.MissingDBSpecies = append(result.MissingDBSpecies, s)

	return nil
}

	// Validate calltypes exist in DB

// validateMappedCalltypes checks that all mapped calltypes exist in the database
func validateMappedCalltypes(queryer DB, mappedCalltypes map[string]map[string]string, result *MappingValidationResult) error {

			return result, fmt.Errorf("failed to query calltypes for species %s: %w", dbSpecies, err)

			return fmt.Errorf("failed to query calltypes for species %s: %w", dbSpecies, err)

	return result, nil

	return nil

	if input.DatasetID == nil || strings.TrimSpace(*input.DatasetID) == "" {
		return output, fmt.Errorf("dataset_id is required when creating a cluster")
	}
	if input.LocationID == nil || strings.TrimSpace(*input.LocationID) == "" {
		return output, fmt.Errorf("location_id is required when creating a cluster")
	}
	if input.Name == nil || strings.TrimSpace(*input.Name) == "" {
		return output, fmt.Errorf("name is required when creating a cluster")
	}
	if input.SampleRate == nil {
		return output, fmt.Errorf("sample_rate is required when creating a cluster")
	}
	// Validate ID formats
	if err := utils.ValidateShortID(*input.DatasetID, "dataset_id"); err != nil {

	if err := validateCreateClusterFields(input); err != nil {

	if err := utils.ValidateShortID(*input.LocationID, "location_id"); err != nil {

	// Validate ID formats and common fields
	if err := validateCreateClusterIDs(input); err != nil {

	// Validate optional pattern ID format

	var datasetExists, datasetActive bool
	var datasetName string
	err = tx.QueryRowContext(ctx,
		"SELECT EXISTS(SELECT 1 FROM dataset WHERE id = ?), COALESCE((SELECT active FROM dataset WHERE id = ?), false), COALESCE((SELECT name FROM dataset WHERE id = ?), '')",
		*input.DatasetID, *input.DatasetID, *input.DatasetID,
	).Scan(&datasetExists, &datasetActive, &datasetName)

	datasetName, err := verifyDatasetForCluster(ctx, tx, *input.DatasetID)

		return output, fmt.Errorf("failed to verify dataset: %w", err)
	}
	if !datasetExists {
		return output, fmt.Errorf("dataset with ID '%s' does not exist", *input.DatasetID)
	}
	if !datasetActive {
		return output, fmt.Errorf("dataset '%s' (ID: %s) is not active", datasetName, *input.DatasetID)

		return output, err

	var locationExists, locationActive bool
	var locationName string
	var locationDatasetID string
	err = tx.QueryRowContext(ctx,
		"SELECT EXISTS(SELECT 1 FROM location WHERE id = ?), COALESCE((SELECT active FROM location WHERE id = ?), false), COALESCE((SELECT name FROM location WHERE id = ?), ''), COALESCE((SELECT dataset_id FROM location WHERE id = ?), '')",
		*input.LocationID, *input.LocationID, *input.LocationID, *input.LocationID,
	).Scan(&locationExists, &locationActive, &locationName, &locationDatasetID)

	locationName, err := verifyLocationForCluster(ctx, tx, *input.LocationID, *input.DatasetID, datasetName)

		return output, fmt.Errorf("failed to verify location: %w", err)

		return output, err

	if !locationExists {
		return output, fmt.Errorf("location with ID '%s' does not exist", *input.LocationID)
	}
	if !locationActive {
		return output, fmt.Errorf("location '%s' (ID: %s) is not active", locationName, *input.LocationID)
	}
	if locationDatasetID != *input.DatasetID {
		return output, fmt.Errorf("location '%s' (ID: %s) does not belong to dataset '%s' (ID: %s) - it belongs to dataset ID '%s'",
			locationName, *input.LocationID, datasetName, *input.DatasetID, locationDatasetID)
	}

		var patternExists, patternActive bool
		err = tx.QueryRowContext(ctx,
			"SELECT EXISTS(SELECT 1 FROM cyclic_recording_pattern WHERE id = ?), COALESCE((SELECT active FROM cyclic_recording_pattern WHERE id = ?), false)",
			*input.CyclicRecordingPatternID, *input.CyclicRecordingPatternID,
		).Scan(&patternExists, &patternActive)
		if err != nil {
			return output, fmt.Errorf("failed to verify cyclic recording pattern: %w", err)

		if err := verifyPatternExists(ctx, tx, *input.CyclicRecordingPatternID); err != nil {
			return output, err

		if !patternExists {
			return output, fmt.Errorf("cyclic recording pattern with ID '%s' does not exist", *input.CyclicRecordingPatternID)
		}
		if !patternActive {
			return output, fmt.Errorf("cyclic recording pattern with ID '%s' is not active", *input.CyclicRecordingPatternID)
		}

	var existingID string
	err = tx.QueryRowContext(ctx,
		"SELECT id FROM cluster WHERE location_id = ? AND name = ? AND active = true",
		*input.LocationID, *input.Name,
	).Scan(&existingID)

	existing, err := findExistingClusterInLocation(ctx, tx, *input.LocationID, *input.Name)

		// Cluster with this name already exists in location - return existing (consistent duplicate handling)
		var cluster db.Cluster
		err = tx.QueryRowContext(ctx,
			"SELECT id, dataset_id, location_id, name, description, created_at, last_modified, active, cyclic_recording_pattern_id, sample_rate FROM cluster WHERE id = ?",
			existingID,
		).Scan(&cluster.ID, &cluster.DatasetID, &cluster.LocationID, &cluster.Name, &cluster.Description,
			&cluster.CreatedAt, &cluster.LastModified, &cluster.Active, &cluster.CyclicRecordingPatternID, &cluster.SampleRate)
		if err != nil {
			return output, fmt.Errorf("failed to fetch existing cluster: %w", err)
		}

		// Cluster with this name already exists - return existing

		output.Cluster = cluster
		output.Message = fmt.Sprintf("Cluster '%s' already exists in location '%s' (ID: %s) - returning existing cluster", cluster.Name, locationName, cluster.ID)

		output.Cluster = existing
		output.Message = fmt.Sprintf("Cluster '%s' already exists in location '%s' (ID: %s) - returning existing cluster", existing.Name, locationName, existing.ID)

	// Generate ID

	// Generate ID and insert

	// Insert cluster

	var cluster db.Cluster
	err = tx.QueryRowContext(ctx,
		"SELECT id, dataset_id, location_id, name, description, created_at, last_modified, active, cyclic_recording_pattern_id, sample_rate FROM cluster WHERE id = ?",
		id,
	).Scan(&cluster.ID, &cluster.DatasetID, &cluster.LocationID, &cluster.Name, &cluster.Description,
		&cluster.CreatedAt, &cluster.LastModified, &cluster.Active, &cluster.CyclicRecordingPatternID, &cluster.SampleRate)

	cluster, err := fetchClusterByID(ctx, tx, id)

// validateCreateClusterFields validates required fields for creating a cluster
func validateCreateClusterFields(input ClusterInput) error {
	if input.DatasetID == nil || strings.TrimSpace(*input.DatasetID) == "" {
		return fmt.Errorf("dataset_id is required when creating a cluster")
	}
	if input.LocationID == nil || strings.TrimSpace(*input.LocationID) == "" {
		return fmt.Errorf("location_id is required when creating a cluster")
	}
	if input.Name == nil || strings.TrimSpace(*input.Name) == "" {
		return fmt.Errorf("name is required when creating a cluster")
	}
	if input.SampleRate == nil {
		return fmt.Errorf("sample_rate is required when creating a cluster")
	}
	return nil
}
// validateCreateClusterIDs validates ID format fields
func validateCreateClusterIDs(input ClusterInput) error {
	if err := utils.ValidateShortID(*input.DatasetID, "dataset_id"); err != nil {
		return err
	}
	return utils.ValidateShortID(*input.LocationID, "location_id")
}
// verifyDatasetForCluster verifies dataset exists and is active within a transaction
func verifyDatasetForCluster(ctx context.Context, tx *db.LoggedTx, datasetID string) (string, error) {
	var exists, active bool
	var name string
	err := tx.QueryRowContext(ctx,
		"SELECT EXISTS(SELECT 1 FROM dataset WHERE id = ?), COALESCE((SELECT active FROM dataset WHERE id = ?), false), COALESCE((SELECT name FROM dataset WHERE id = ?), '')",
		datasetID, datasetID, datasetID,
	).Scan(&exists, &active, &name)
	if err != nil {
		return "", fmt.Errorf("failed to verify dataset: %w", err)
	}
	if !exists {
		return "", fmt.Errorf("dataset with ID '%s' does not exist", datasetID)
	}
	if !active {
		return "", fmt.Errorf("dataset '%s' (ID: %s) is not active", name, datasetID)
	}
	return name, nil
}
// verifyLocationForCluster verifies location exists, is active, and belongs to the dataset
func verifyLocationForCluster(ctx context.Context, tx *db.LoggedTx, locationID, datasetID, datasetName string) (string, error) {
	var exists, active bool
	var name, locDatasetID string
	err := tx.QueryRowContext(ctx,
		"SELECT EXISTS(SELECT 1 FROM location WHERE id = ?), COALESCE((SELECT active FROM location WHERE id = ?), false), COALESCE((SELECT name FROM location WHERE id = ?), ''), COALESCE((SELECT dataset_id FROM location WHERE id = ?), '')",
		locationID, locationID, locationID, locationID,
	).Scan(&exists, &active, &name, &locDatasetID)
	if err != nil {
		return "", fmt.Errorf("failed to verify location: %w", err)
	}
	if !exists {
		return "", fmt.Errorf("location with ID '%s' does not exist", locationID)
	}
	if !active {
		return "", fmt.Errorf("location '%s' (ID: %s) is not active", name, locationID)
	}
	if locDatasetID != datasetID {
		return "", fmt.Errorf("location '%s' (ID: %s) does not belong to dataset '%s' (ID: %s) - it belongs to dataset ID '%s'",
			name, locationID, datasetName, datasetID, locDatasetID)
	}
	return name, nil
}
// verifyPatternExists verifies a cyclic recording pattern exists and is active
func verifyPatternExists(ctx context.Context, tx *db.LoggedTx, patternID string) error {
	var exists, active bool
	err := tx.QueryRowContext(ctx,
		"SELECT EXISTS(SELECT 1 FROM cyclic_recording_pattern WHERE id = ?), COALESCE((SELECT active FROM cyclic_recording_pattern WHERE id = ?), false)",
		patternID, patternID,
	).Scan(&exists, &active)
	if err != nil {
		return fmt.Errorf("failed to verify cyclic recording pattern: %w", err)
	}
	if !exists {
		return fmt.Errorf("cyclic recording pattern with ID '%s' does not exist", patternID)
	}
	if !active {
		return fmt.Errorf("cyclic recording pattern with ID '%s' is not active", patternID)
	}
	return nil
}
// findExistingClusterInLocation checks for an existing cluster with the same name in a location
func findExistingClusterInLocation(ctx context.Context, tx *db.LoggedTx, locationID, name string) (db.Cluster, error) {
	var existingID string
	err := tx.QueryRowContext(ctx,
		"SELECT id FROM cluster WHERE location_id = ? AND name = ? AND active = true",
		locationID, name,
	).Scan(&existingID)
	if err != nil {
		return db.Cluster{}, err
	}
	return fetchClusterByID(ctx, tx, existingID)
}
// fetchClusterByID fetches a cluster row by ID
func fetchClusterByID(ctx context.Context, tx *db.LoggedTx, id string) (db.Cluster, error) {
	var c db.Cluster
	err := tx.QueryRowContext(ctx,
		"SELECT id, dataset_id, location_id, name, description, created_at, last_modified, active, cyclic_recording_pattern_id, sample_rate FROM cluster WHERE id = ?",
		id,
	).Scan(&c.ID, &c.DatasetID, &c.LocationID, &c.Name, &c.Description,
		&c.CreatedAt, &c.LastModified, &c.Active, &c.CyclicRecordingPatternID, &c.SampleRate)
	return c, err
}

	summariseFiles(filePaths, input, &output, operatorSet, reviewerSet)

	// Process each file

	// Count segments for total
	if input.Brief {
		for _, fs := range output.Filters {
			output.TotalSegments += fs.Segments
		}
	} else {
		output.TotalSegments = len(output.Segments)
	}
	finaliseSummary(&output, operatorSet, reviewerSet, input.Brief)
	return output, nil
}
// summariseFiles processes all data files, populating output stats
func summariseFiles(filePaths []string, input CallsSummariseInput, output *CallsSummariseOutput, operatorSet, reviewerSet map[string]bool) {

			// Extract just the filename for skipped list

		// Track operator and reviewer
		if df.Meta != nil {
			if df.Meta.Operator != "" {
				operatorSet[df.Meta.Operator] = true
			}
			if df.Meta.Reviewer != "" {
				reviewerSet[df.Meta.Reviewer] = true
			}
		}

		trackMeta(df.Meta, operatorSet, reviewerSet)

		// Extract relative filename for segments (only needed if not brief)

		// Process segments

			// Filter labels if --filter is specified
			var filteredLabels []*utils.Label
			for _, l := range seg.Labels {
				if input.Filter == "" || l.Filter == input.Filter {
					filteredLabels = append(filteredLabels, l)
				}
			}
			// Skip segments with no matching labels when filter is active

			filteredLabels := filterLabels(seg.Labels, input.Filter)

			// Build label summaries (only if not brief)
			var labels []LabelSummary

			updateStatsFromLabels(filteredLabels, output)

				for _, l := range filteredLabels {
					labelSummary := LabelSummary{
						Filter:    l.Filter,
						Certainty: l.Certainty,
						Species:   l.Species,
					}
					if l.CallType != "" {
						labelSummary.CallType = l.CallType
					}
					if l.Comment != "" {
						labelSummary.Comment = l.Comment
					}
					if l.Bookmark {
						labelSummary.Bookmark = true
					}
					labels = append(labels, labelSummary)
				}

				output.Segments = append(output.Segments, SegmentSummary{
					File:      relPath,
					StartTime: seg.StartTime,
					EndTime:   seg.EndTime,
					Labels:    buildLabelSummaries(filteredLabels),
				})

		}
	}
}

			// Update filter stats and review status (using filtered labels)
			for _, l := range filteredLabels {
				// Update filter stats
				fs, exists := output.Filters[l.Filter]
				if !exists {
					fs = FilterStats{
						Segments:  0,
						Species:   make(map[string]int),
						Calltypes: make(map[string]map[string]int),
					}
				}
				fs.Segments++
				fs.Species[l.Species]++

// trackMeta records operator and reviewer from file metadata
func trackMeta(meta *utils.DataMeta, operatorSet, reviewerSet map[string]bool) {
	if meta == nil {
		return
	}
	if meta.Operator != "" {
		operatorSet[meta.Operator] = true
	}
	if meta.Reviewer != "" {
		reviewerSet[meta.Reviewer] = true
	}
}

				// Track calltypes if present
				if l.CallType != "" {
					if fs.Calltypes[l.Species] == nil {
						fs.Calltypes[l.Species] = make(map[string]int)
					}
					fs.Calltypes[l.Species][l.CallType]++
				}
				output.Filters[l.Filter] = fs

// filterLabels returns labels matching the filter, or all labels if filter is empty
func filterLabels(labels []*utils.Label, filter string) []*utils.Label {
	if filter == "" {
		return labels
	}
	var filtered []*utils.Label
	for _, l := range labels {
		if l.Filter == filter {
			filtered = append(filtered, l)
		}
	}
	return filtered
}

				// Update review status
				switch l.Certainty {
				case 100:
					output.ReviewStatus.Confirmed++
				case 0:
					output.ReviewStatus.DontKnow++
				default:
					output.ReviewStatus.Unreviewed++
				}

// buildLabelSummaries converts labels to label summaries
func buildLabelSummaries(labels []*utils.Label) []LabelSummary {
	var summaries []LabelSummary
	for _, l := range labels {
		ls := LabelSummary{
			Filter:    l.Filter,
			Certainty: l.Certainty,
			Species:   l.Species,
		}
		if l.CallType != "" {
			ls.CallType = l.CallType
		}
		if l.Comment != "" {
			ls.Comment = l.Comment
		}
		if l.Bookmark {
			ls.Bookmark = true
		}
		summaries = append(summaries, ls)
	}
	return summaries
}

				if l.CallType != "" {
					output.ReviewStatus.WithCallType++
				}
				if l.Comment != "" {
					output.ReviewStatus.WithComments++
				}
				if l.Bookmark {
					output.ReviewStatus.Bookmarked++
				}
			}

// updateStatsFromLabels updates filter stats and review status from a set of labels
func updateStatsFromLabels(labels []*utils.Label, output *CallsSummariseOutput) {
	for _, l := range labels {
		updateFilterStats(l, output)
		updateReviewStatus(l, output)
	}
}

			// Create segment summary only if not brief
			if !input.Brief {
				segSummary := SegmentSummary{
					File:      relPath,
					StartTime: seg.StartTime,
					EndTime:   seg.EndTime,
					Labels:    labels,
				}
				output.Segments = append(output.Segments, segSummary)
			}

// updateFilterStats increments filter-level statistics for a single label
func updateFilterStats(l *utils.Label, output *CallsSummariseOutput) {
	fs, exists := output.Filters[l.Filter]
	if !exists {
		fs = FilterStats{
			Segments:  0,
			Species:   make(map[string]int),
			Calltypes: make(map[string]map[string]int),

	fs.Segments++
	fs.Species[l.Species]++

	// Count segments for total
	if input.Brief {
		// Recount from filter stats since we didn't track segments
		for _, fs := range output.Filters {
			output.TotalSegments += fs.Segments

	if l.CallType != "" {
		if fs.Calltypes[l.Species] == nil {
			fs.Calltypes[l.Species] = make(map[string]int)

	} else {
		output.TotalSegments = len(output.Segments)

		fs.Calltypes[l.Species][l.CallType]++
	}
	output.Filters[l.Filter] = fs
}
// updateReviewStatus increments review status counters for a single label
func updateReviewStatus(l *utils.Label, output *CallsSummariseOutput) {
	switch l.Certainty {
	case 100:
		output.ReviewStatus.Confirmed++
	case 0:
		output.ReviewStatus.DontKnow++
	default:
		output.ReviewStatus.Unreviewed++
	}
	if l.CallType != "" {
		output.ReviewStatus.WithCallType++
	}
	if l.Comment != "" {
		output.ReviewStatus.WithComments++
	}
	if l.Bookmark {
		output.ReviewStatus.Bookmarked++

}

	// Clean up empty calltypes maps (omitempty doesn't work on non-nil empty maps)

// finaliseSummary sorts output, cleans empty maps, and converts sets to sorted slices
func finaliseSummary(output *CallsSummariseOutput, operatorSet, reviewerSet map[string]bool, brief bool) {
	// Clean up empty calltypes maps

	// Sort segments by file, then start time (only if not brief)
	if !input.Brief {

	// Sort segments by file, then start time
	if !brief {

	return output, nil

	if input.File == "" {
		output.Error = "--file is required"

	if err := validatePropagateInput(&output, input); err != nil {
		return output, err
	}
	df, err := utils.ParseDataFile(input.File)
	if err != nil {
		output.Error = fmt.Sprintf("parse %s: %v", input.File, err)

	if input.FromFilter == "" {
		output.Error = "--from is required"
		return output, fmt.Errorf("%s", output.Error)

	// Fast path: skip files that don't contain both filters at all.
	if !hasBothFilters(df, input.FromFilter, input.ToFilter) {
		output.FiltersMissing = true
		return output, nil

	if input.ToFilter == "" {
		output.Error = "--to is required"
		return output, fmt.Errorf("%s", output.Error)

	sources := collectPropagateSources(df, input.FromFilter, input.Species)
	propagateTargets(df, sources, input, &output)
	if output.Propagated > 0 {
		df.Meta.Reviewer = "Skraak"
		if err := df.Write(input.File); err != nil {
			output.Error = fmt.Sprintf("write %s: %v", input.File, err)
			return output, fmt.Errorf("%s", output.Error)
		}
	}
	return output, nil
}
// validatePropagateInput checks required fields and file existence
func validatePropagateInput(output *CallsPropagateOutput, input CallsPropagateInput) error {
	checks := []struct {
		val string
		msg string
	}{
		{input.File, "--file is required"},
		{input.FromFilter, "--from is required"},
		{input.ToFilter, "--to is required"},
		{input.Species, "--species is required"},

	if input.Species == "" {
		output.Error = "--species is required"
		return output, fmt.Errorf("%s", output.Error)

	for _, c := range checks {
		if c.val == "" {
			output.Error = c.msg
			return fmt.Errorf("%s", c.msg)
		}

		return output, fmt.Errorf("%s", output.Error)

		return fmt.Errorf("%s", output.Error)

		return output, fmt.Errorf("%s", output.Error)

		return fmt.Errorf("%s", output.Error)

	return nil
}

	df, err := utils.ParseDataFile(input.File)
	if err != nil {
		output.Error = fmt.Sprintf("parse %s: %v", input.File, err)
		return output, fmt.Errorf("%s", output.Error)
	}
	// Fast path: skip files that don't contain both filters at all.

// hasBothFilters checks whether the data file contains both from and to filters
func hasBothFilters(df *utils.DataFile, fromFilter, toFilter string) bool {

			if lbl.Filter == input.FromFilter {

			if lbl.Filter == fromFilter {

			if lbl.Filter == input.ToFilter {

			if lbl.Filter == toFilter {

				break

				return true

		if hasFrom && hasTo {
			break
		}
	}
	if !hasFrom || !hasTo {
		output.FiltersMissing = true
		return output, nil

	return false
}

	type sourceRef struct {
		seg   *utils.Segment
		label *utils.Label
	}

// sourceRef pairs a segment with its matching source label
type sourceRef struct {
	seg   *utils.Segment
	label *utils.Label
}
// collectPropagateSources gathers verified source labels (certainty==100) for the given filter/species
func collectPropagateSources(df *utils.DataFile, fromFilter, species string) []sourceRef {

			if lbl.Filter == input.FromFilter && lbl.Species == input.Species && lbl.Certainty == 100 {

			if lbl.Filter == fromFilter && lbl.Species == species && lbl.Certainty == 100 {

	return sources
}

	changed := false

// propagateTargets iterates target segments, finds overlapping sources, and applies agreed classifications
func propagateTargets(df *utils.DataFile, sources []sourceRef, input CallsPropagateInput, output *CallsPropagateOutput) {

		var toLabel *utils.Label
		for _, lbl := range tSeg.Labels {
			if lbl.Filter == input.ToFilter && (lbl.Certainty == 70 || lbl.Certainty == 0) {
				toLabel = lbl
				break
			}
		}

		toLabel := findUpdatableTargetLabel(tSeg.Labels, input.ToFilter)

		var overlaps []sourceRef
		for _, s := range sources {
			if s.seg.StartTime < tSeg.EndTime && tSeg.StartTime < s.seg.EndTime {
				overlaps = append(overlaps, s)
			}
		}

		overlaps := findOverlappingSources(sources, tSeg)

		agreedCallType := overlaps[0].label.CallType
		conflict := false
		for _, s := range overlaps[1:] {
			if s.label.CallType != agreedCallType {
				conflict = true
				break
			}
		}

		agreedCallType, conflict := resolveCallType(overlaps)

			choices := make([]PropagateSourceChoice, 0, len(overlaps))
			for _, s := range overlaps {
				choices = append(choices, PropagateSourceChoice{
					Start:    s.seg.StartTime,
					End:      s.seg.EndTime,
					Species:  s.label.Species,
					CallType: s.label.CallType,
				})
			}
			output.Conflicts = append(output.Conflicts, PropagateConflict{
				TargetStart:    tSeg.StartTime,
				TargetEnd:      tSeg.EndTime,
				TargetCallType: toLabel.CallType,
				SourceChoices:  choices,
			})

			output.Conflicts = append(output.Conflicts, buildConflictRecord(tSeg, toLabel, overlaps))

		change := PropagateChange{
			TargetStart:   tSeg.StartTime,
			TargetEnd:     tSeg.EndTime,
			PrevSpecies:   toLabel.Species,
			PrevCallType:  toLabel.CallType,
			PrevCertainty: toLabel.Certainty,
			NewSpecies:    input.Species,
			NewCallType:   agreedCallType,
			NewCertainty:  90,

		applyPropagation(toLabel, input.Species, agreedCallType, tSeg, output)
	}
}
// findUpdatableTargetLabel finds a target label with certainty 70 or 0 for the given filter
func findUpdatableTargetLabel(labels []*utils.Label, toFilter string) *utils.Label {
	for _, lbl := range labels {
		if lbl.Filter == toFilter && (lbl.Certainty == 70 || lbl.Certainty == 0) {
			return lbl
		}
	}
	return nil
}
// findOverlappingSources returns sources whose segments overlap with the target segment
func findOverlappingSources(sources []sourceRef, tSeg *utils.Segment) []sourceRef {
	var overlaps []sourceRef
	for _, s := range sources {
		if s.seg.StartTime < tSeg.EndTime && tSeg.StartTime < s.seg.EndTime {
			overlaps = append(overlaps, s)

	}
	return overlaps
}

		toLabel.Species = input.Species
		toLabel.CallType = agreedCallType
		toLabel.Certainty = 90
		changed = true

// resolveCallType checks if all overlapping sources agree on a call type.
// Returns the agreed call type and whether there is a conflict.
func resolveCallType(overlaps []sourceRef) (string, bool) {
	agreedCallType := overlaps[0].label.CallType
	for _, s := range overlaps[1:] {
		if s.label.CallType != agreedCallType {
			return "", true
		}
	}
	return agreedCallType, false
}

		output.Propagated++
		output.Changes = append(output.Changes, change)

// buildConflictRecord creates a PropagateConflict from overlapping disagreeing sources
func buildConflictRecord(tSeg *utils.Segment, toLabel *utils.Label, overlaps []sourceRef) PropagateConflict {
	choices := make([]PropagateSourceChoice, 0, len(overlaps))
	for _, s := range overlaps {
		choices = append(choices, PropagateSourceChoice{
			Start:    s.seg.StartTime,
			End:      s.seg.EndTime,
			Species:  s.label.Species,
			CallType: s.label.CallType,
		})
	}
	return PropagateConflict{
		TargetStart:    tSeg.StartTime,
		TargetEnd:      tSeg.EndTime,
		TargetCallType: toLabel.CallType,
		SourceChoices:  choices,

}

	if changed {
		df.Meta.Reviewer = "Skraak"
		if err := df.Write(input.File); err != nil {
			output.Error = fmt.Sprintf("write %s: %v", input.File, err)
			return output, fmt.Errorf("%s", output.Error)
		}

// applyPropagation updates the target label and records the change
func applyPropagation(toLabel *utils.Label, species, callType string, tSeg *utils.Segment, output *CallsPropagateOutput) {
	change := PropagateChange{
		TargetStart:   tSeg.StartTime,
		TargetEnd:     tSeg.EndTime,
		PrevSpecies:   toLabel.Species,
		PrevCallType:  toLabel.CallType,
		PrevCertainty: toLabel.Certainty,
		NewSpecies:    species,
		NewCallType:   callType,
		NewCertainty:  90,

	toLabel.Species = species
	toLabel.CallType = callType
	toLabel.Certainty = 90

	return output, nil

	output.Propagated++
	output.Changes = append(output.Changes, change)

// processRavenFileCached processes a single Raven selection file using a DirCache for WAV lookup
func processRavenFileCached(ravenFile string, cache *DirCache) ([]ClusteredCall, bool, bool, error) {
	// Open file
	file, err := os.Open(ravenFile)
	if err != nil {
		return nil, false, false, fmt.Errorf("failed to open file: %w", err)
	}
	defer func() { _ = file.Close() }()
	// Read header and selections (tab-separated)
	scanner := bufio.NewScanner(file)

	// Read header line
	if !scanner.Scan() {
		return nil, false, false, fmt.Errorf("empty file")
	}
	header := strings.Split(scanner.Text(), "\t")
	// Find column indices
	beginTimeIdx := -1
	endTimeIdx := -1
	lowFreqIdx := -1
	highFreqIdx := -1
	speciesIdx := -1

// ravenColumnIndices holds the column index positions for a Raven file
type ravenColumnIndices struct {
	beginTimeIdx int
	endTimeIdx   int
	lowFreqIdx   int
	highFreqIdx  int
	speciesIdx   int
}

// parseRavenHeader finds column indices from a tab-separated header line
func parseRavenHeader(header []string) (ravenColumnIndices, error) {
	idx := ravenColumnIndices{beginTimeIdx: -1, endTimeIdx: -1, lowFreqIdx: -1, highFreqIdx: -1, speciesIdx: -1}

			beginTimeIdx = i

			idx.beginTimeIdx = i

			endTimeIdx = i

			idx.endTimeIdx = i

			lowFreqIdx = i

			idx.lowFreqIdx = i

			highFreqIdx = i

			idx.highFreqIdx = i

			speciesIdx = i

			idx.speciesIdx = i

	if beginTimeIdx == -1 || endTimeIdx == -1 || speciesIdx == -1 {
		return nil, false, false, fmt.Errorf("missing required columns in Raven file")

	if idx.beginTimeIdx == -1 || idx.endTimeIdx == -1 || idx.speciesIdx == -1 {
		return idx, fmt.Errorf("missing required columns in Raven file")

	return idx, nil
}

	// Read selections

// parseRavenSelections reads all selection rows from a scanner and returns parsed selections
func parseRavenSelections(scanner *bufio.Scanner, idx ravenColumnIndices) ([]RavenSelection, error) {

		if len(fields) <= speciesIdx {

		if len(fields) <= idx.speciesIdx {

		var sel RavenSelection
		if _, err := fmt.Sscanf(fields[beginTimeIdx], "%f", &sel.StartTime); err != nil {
			return nil, false, false, fmt.Errorf("failed to parse begin time %q: %w", fields[beginTimeIdx], err)

		sel, err := parseRavenRow(fields, idx)
		if err != nil {
			return nil, err

		if _, err := fmt.Sscanf(fields[endTimeIdx], "%f", &sel.EndTime); err != nil {
			return nil, false, false, fmt.Errorf("failed to parse end time %q: %w", fields[endTimeIdx], err)
		}
		if lowFreqIdx >= 0 && lowFreqIdx < len(fields) {
			if _, err := fmt.Sscanf(fields[lowFreqIdx], "%f", &sel.FreqLow); err != nil {
				return nil, false, false, fmt.Errorf("failed to parse low freq %q: %w", fields[lowFreqIdx], err)
			}
		}
		if highFreqIdx >= 0 && highFreqIdx < len(fields) {
			if _, err := fmt.Sscanf(fields[highFreqIdx], "%f", &sel.FreqHigh); err != nil {
				return nil, false, false, fmt.Errorf("failed to parse high freq %q: %w", fields[highFreqIdx], err)
			}
		}
		sel.Species = fields[speciesIdx]

		return nil, false, false, fmt.Errorf("error reading file: %w", err)

		return nil, fmt.Errorf("error reading file: %w", err)

	return selections, nil
}

	if len(selections) == 0 {
		return nil, false, true, nil // No selections, skip

// parseRavenRow parses a single tab-separated row into a RavenSelection
func parseRavenRow(fields []string, idx ravenColumnIndices) (RavenSelection, error) {
	var sel RavenSelection
	if _, err := fmt.Sscanf(fields[idx.beginTimeIdx], "%f", &sel.StartTime); err != nil {
		return sel, fmt.Errorf("failed to parse begin time %q: %w", fields[idx.beginTimeIdx], err)
	}
	if _, err := fmt.Sscanf(fields[idx.endTimeIdx], "%f", &sel.EndTime); err != nil {
		return sel, fmt.Errorf("failed to parse end time %q: %w", fields[idx.endTimeIdx], err)
	}
	if idx.lowFreqIdx >= 0 && idx.lowFreqIdx < len(fields) {
		if _, err := fmt.Sscanf(fields[idx.lowFreqIdx], "%f", &sel.FreqLow); err != nil {
			return sel, fmt.Errorf("failed to parse low freq %q: %w", fields[idx.lowFreqIdx], err)
		}
	}
	if idx.highFreqIdx >= 0 && idx.highFreqIdx < len(fields) {
		if _, err := fmt.Sscanf(fields[idx.highFreqIdx], "%f", &sel.FreqHigh); err != nil {
			return sel, fmt.Errorf("failed to parse high freq %q: %w", fields[idx.highFreqIdx], err)
		}

	sel.Species = fields[idx.speciesIdx]
	return sel, nil
}

	// Derive WAV path from Raven filename
	// "20230610_150000.Table.1.selections.txt" -> "20230610_150000"

// deriveWAVBaseName extracts the base WAV filename from a Raven .selections.txt filename
func deriveWAVBaseName(ravenFile string) string {

	// Remove .selections.txt

	// Remove .Table.X (or similar pattern)

	}
	return nameWithoutSuffix
}
// processRavenFileCached processes a single Raven selection file using a DirCache for WAV lookup
func processRavenFileCached(ravenFile string, cache *DirCache) ([]ClusteredCall, bool, bool, error) {
	file, err := os.Open(ravenFile)
	if err != nil {
		return nil, false, false, fmt.Errorf("failed to open file: %w", err)

	defer func() { _ = file.Close() }()
	scanner := bufio.NewScanner(file)

	// Find WAV file using DirCache (O(1) lookup instead of O(N) directory scan)
	var wavPath string
	if cache != nil {
		wavPath = cache.FindWAV(nameWithoutSuffix)
	} else {
		wavPath = findWAVFile(filepath.Dir(ravenFile), nameWithoutSuffix)

	if !scanner.Scan() {
		return nil, false, false, fmt.Errorf("empty file")
	}
	header := strings.Split(scanner.Text(), "\t")
	idx, err := parseRavenHeader(header)
	if err != nil {
		return nil, false, false, err
	}
	selections, err := parseRavenSelections(scanner, idx)
	if err != nil {
		return nil, false, false, err
	}
	if len(selections) == 0 {
		return nil, false, true, nil

	// Find WAV file
	wavPath := resolveWAVPath(ravenFile, cache)

		return nil, false, true, nil // WAV not found, skip

		return nil, false, true, nil

	// Check if WAV exists (to get sample rate and duration)

		return nil, false, true, nil // Skip if WAV not found or invalid

		return nil, false, true, nil

	// Convert selections to segments

	// Build metadata
	meta := AviaNZMeta{
		Operator: "Raven",
		Duration: duration,
	}

	meta := AviaNZMeta{Operator: "Raven", Duration: duration}

	// Write .data file (safe write)

	// Convert to ClusteredCalls for output

}
// resolveWAVPath finds the WAV file corresponding to a Raven file
func resolveWAVPath(ravenFile string, cache *DirCache) string {
	baseName := deriveWAVBaseName(ravenFile)
	if cache != nil {
		return cache.FindWAV(baseName)
	}
	return findWAVFile(filepath.Dir(ravenFile), baseName)

// predFileSpeciesKey groups detections by file and ebird code
type predFileSpeciesKey struct {
	File      string
	EbirdCode string
}

	// Filter must not be empty

	// Open CSV file
	file, err := os.Open(input.CSVPath)

	_, detections, clipDuration, err := readPredCSV(input.CSVPath)

		errMsg := fmt.Sprintf("Failed to open CSV file: %v", err)

		errMsg := err.Error()

		return output, fmt.Errorf("%s", errMsg)

		return output, err
	}
	output.ClipDuration = clipDuration
	gapMultiplier := CLUSTER_GAP_MULTIPLIER
	if input.GapMultiplier > 0 {
		gapMultiplier = input.GapMultiplier
	}
	minDetections := MIN_DETECTIONS_PER_CLUSTER
	if input.MinDetections >= 0 {
		minDetections = input.MinDetections
	}
	gapThreshold := float64(gapMultiplier) * clipDuration
	output.GapThreshold = gapThreshold
	allCalls, speciesCount := clusterDetections(detections, clipDuration, gapThreshold, minDetections)
	output.Calls = allCalls
	output.TotalCalls = len(allCalls)
	output.SpeciesCount = speciesCount
	if input.WriteDotData {
		dataFilesWritten, dataFilesSkipped, err := writeDotFiles(input.CSVPath, filter, allCalls, input.ProgressHandler)
		if err != nil {
			errMsg := fmt.Sprintf("Error writing .data files: %v", err)
			output.Error = &errMsg
			return output, fmt.Errorf("%s", errMsg)
		}
		output.DataFilesWritten = dataFilesWritten
		output.DataFilesSkipped = dataFilesSkipped
	}
	return output, nil
}
// readPredCSV opens and reads a predictions CSV, returning column mappings, detections, and clip duration
func readPredCSV(csvPath string) (predCSVColumns, map[predFileSpeciesKey][]float64, float64, error) {
	file, err := os.Open(csvPath)
	if err != nil {
		return predCSVColumns{}, nil, 0, fmt.Errorf("failed to open CSV file: %w", err)

	// Read CSV

	reader.ReuseRecord = true // Memory optimization for large files

	reader.ReuseRecord = true

	// Read header

		errMsg := fmt.Sprintf("Failed to read CSV header: %v", err)
		output.Error = &errMsg
		return output, fmt.Errorf("%s", errMsg)

		return predCSVColumns{}, nil, 0, fmt.Errorf("failed to read CSV header: %w", err)
	}
	cols, err := findPredCSVColumns(header)
	if err != nil {
		return predCSVColumns{}, nil, 0, err

	// Find column indices
	fileIdx := -1
	startTimeIdx := -1
	endTimeIdx := -1
	var ebirdCodes []string
	var ebirdIdx []int

	detections, clipDuration, err := readPredCSVRows(reader, cols)
	if err != nil {
		return predCSVColumns{}, nil, 0, err
	}
	return cols, detections, clipDuration, nil
}

	// Columns to ignore (not ebird codes)
	ignoredColumns := map[string]bool{
		"NotKiwi": true,
		"0.0":     true,

// predCSVColumns holds the column indices for a predictions CSV
type predCSVColumns struct {
	fileIdx      int
	startTimeIdx int
	endTimeIdx   int
	ebirdCodes   []string
	ebirdIdx     []int
}
// findPredCSVColumns parses the CSV header to find column indices
func findPredCSVColumns(header []string) (predCSVColumns, error) {
	cols := predCSVColumns{
		fileIdx:      -1,
		startTimeIdx: -1,
		endTimeIdx:   -1,

	ignoredColumns := map[string]bool{"NotKiwi": true, "0.0": true}

			fileIdx = i

			cols.fileIdx = i

			startTimeIdx = i

			cols.startTimeIdx = i

			endTimeIdx = i

			cols.endTimeIdx = i

			// Skip ignored columns

			// All other columns are ebird codes
			ebirdCodes = append(ebirdCodes, col)
			ebirdIdx = append(ebirdIdx, i)

			cols.ebirdCodes = append(cols.ebirdCodes, col)
			cols.ebirdIdx = append(cols.ebirdIdx, i)

	if fileIdx == -1 || startTimeIdx == -1 || endTimeIdx == -1 {
		errMsg := "CSV must have 'file', 'start_time', and 'end_time' columns"
		output.Error = &errMsg
		return output, fmt.Errorf("%s", errMsg)

	if cols.fileIdx == -1 || cols.startTimeIdx == -1 || cols.endTimeIdx == -1 {
		return cols, fmt.Errorf("CSV must have 'file', 'start_time', and 'end_time' columns")

	if len(ebirdCodes) == 0 {
		errMsg := "CSV must have at least one ebird code column"
		output.Error = &errMsg
		return output, fmt.Errorf("%s", errMsg)

	if len(cols.ebirdCodes) == 0 {
		return cols, fmt.Errorf("CSV must have at least one ebird code column")

	return cols, nil
}

	// Read all rows and organize by (file, ebird_code) -> start_times
	// Using maps for efficient grouping
	type FileEbirdKey struct {
		File      string
		EbirdCode string
	}
	detections := make(map[FileEbirdKey][]float64)

// readPredCSVRows reads all CSV data rows and returns detections grouped by file+species, plus clip duration
func readPredCSVRows(reader *csv.Reader, cols predCSVColumns) (map[predFileSpeciesKey][]float64, float64, error) {
	detections := make(map[predFileSpeciesKey][]float64)

	// Read first row to get clip duration

	if err != nil && err != io.EOF {
		errMsg := fmt.Sprintf("Failed to read first CSV row: %v", err)
		output.Error = &errMsg
		return output, fmt.Errorf("%s", errMsg)

	if err == io.EOF {
		return detections, 0, nil
	}
	if err != nil {
		return nil, 0, fmt.Errorf("failed to read first CSV row: %w", err)

	if err != io.EOF {
		startTime, _ := strconv.ParseFloat(record[startTimeIdx], 64)
		endTime, _ := strconv.ParseFloat(record[endTimeIdx], 64)
		clipDuration = endTime - startTime
		output.ClipDuration = clipDuration

	startTime, _ := strconv.ParseFloat(record[cols.startTimeIdx], 64)
	endTime, _ := strconv.ParseFloat(record[cols.endTimeIdx], 64)
	clipDuration = endTime - startTime
	addDetectionsFromRow(record, cols, startTime, detections)

		// Process first row
		fileName := record[fileIdx]
		for i, idx := range ebirdIdx {
			if record[idx] == "1" {
				key := FileEbirdKey{File: fileName, EbirdCode: ebirdCodes[i]}
				detections[key] = append(detections[key], startTime)
			}

	for {
		record, err := reader.Read()
		if err == io.EOF {
			break
		}
		if err != nil {
			return nil, 0, fmt.Errorf("failed to read CSV row: %w", err)

		// Read remaining rows
		for {
			record, err := reader.Read()
			if err == io.EOF {
				break
			}
			if err != nil {
				errMsg := fmt.Sprintf("Failed to read CSV row: %v", err)
				output.Error = &errMsg
				return output, fmt.Errorf("%s", errMsg)
			}

		startTime, _ = strconv.ParseFloat(record[cols.startTimeIdx], 64)
		addDetectionsFromRow(record, cols, startTime, detections)
	}

			startTime, _ := strconv.ParseFloat(record[startTimeIdx], 64)
			fileName := record[fileIdx]

	return detections, clipDuration, nil
}

			for i, idx := range ebirdIdx {
				if record[idx] == "1" {
					key := FileEbirdKey{File: fileName, EbirdCode: ebirdCodes[i]}
					detections[key] = append(detections[key], startTime)
				}
			}

// addDetectionsFromRow adds positive detections from a single CSV row
func addDetectionsFromRow(record []string, cols predCSVColumns, startTime float64, detections map[predFileSpeciesKey][]float64) {
	fileName := record[cols.fileIdx]
	for i, idx := range cols.ebirdIdx {
		if record[idx] == "1" {
			key := predFileSpeciesKey{File: fileName, EbirdCode: cols.ebirdCodes[i]}
			detections[key] = append(detections[key], startTime)

	}
	// Calculate gap threshold
	gapMultiplier := CLUSTER_GAP_MULTIPLIER
	if input.GapMultiplier > 0 {
		gapMultiplier = input.GapMultiplier
	}
	minDetections := MIN_DETECTIONS_PER_CLUSTER
	if input.MinDetections >= 0 {
		minDetections = input.MinDetections

	gapThreshold := float64(gapMultiplier) * clipDuration
	output.GapThreshold = gapThreshold

}

	// Cluster detections by (file, ebird_code)

// clusterDetections groups detections into clusters and produces sorted ClusteredCalls
func clusterDetections(detections map[predFileSpeciesKey][]float64, clipDuration, gapThreshold float64, minDetections int) ([]ClusteredCall, map[string]int) {

		// Sort start times

		// Cluster consecutive detections

		// Convert clusters to calls

	// Sort calls by file, then start time

	output.Calls = allCalls
	output.TotalCalls = len(allCalls)
	output.SpeciesCount = speciesCount

	// Write .data files if requested
	if input.WriteDotData {
		dataFilesWritten, dataFilesSkipped, err := writeDotFiles(input.CSVPath, filter, allCalls, input.ProgressHandler)
		if err != nil {
			// Return error - this includes clobber protection and parse errors
			errMsg := fmt.Sprintf("Error writing .data files: %v", err)
			output.Error = &errMsg
			return output, fmt.Errorf("%s", errMsg)
		}
		output.DataFilesWritten = dataFilesWritten
		output.DataFilesSkipped = dataFilesSkipped
	}
	return output, nil

	return allCalls, speciesCount

// runCallsPushCertainty promotes certainty=90 segments to certainty=100 for a filtered set.
//
// JSON output schema:
//
//	{
//	  "segments_updated": int,      // Number of segments promoted from 90→100
//	  "files_updated": int,         // Number of .data files modified
//	  "time_filtered_count": int    // Files skipped by --night/--day filter
//	}
func runCallsPushCertainty(args []string) {
	var folder, file, filter, species, timezone string
	var night, day bool
	var lat, lng float64
	var latSet, lngSet bool

// pushCertaintyFlags holds the parsed CLI flags for push-certainty
type pushCertaintyFlags struct {
	folder   string
	file     string
	filter   string
	species  string
	timezone string
	night    bool
	day      bool
	lat      float64
	lng      float64
	latSet   bool
	lngSet   bool
}

// parsePushCertaintyArgs parses CLI arguments into flags
func parsePushCertaintyArgs(args []string) pushCertaintyFlags {
	var f pushCertaintyFlags

			if i+1 >= len(args) {
				fmt.Fprintf(os.Stderr, "Error: --folder requires a value\n")
				os.Exit(1)
			}
			folder = args[i+1]
			i += 2

			f.folder = requireValue(arg, args, &i)

			if i+1 >= len(args) {
				fmt.Fprintf(os.Stderr, "Error: --file requires a value\n")
				os.Exit(1)
			}
			file = args[i+1]
			i += 2

			f.file = requireValue(arg, args, &i)

			if i+1 >= len(args) {
				fmt.Fprintf(os.Stderr, "Error: --filter requires a value\n")
				os.Exit(1)
			}
			filter = args[i+1]
			i += 2

			f.filter = requireValue(arg, args, &i)

			if i+1 >= len(args) {
				fmt.Fprintf(os.Stderr, "Error: --species requires a value\n")
				os.Exit(1)
			}
			species = args[i+1]
			i += 2

			f.species = requireValue(arg, args, &i)

			night = true

			f.night = true

			day = true

			f.day = true

			if i+1 >= len(args) {
				fmt.Fprintf(os.Stderr, "Error: --lat requires a value\n")
				os.Exit(1)
			}
			v, err := strconv.ParseFloat(args[i+1], 64)
			if err != nil {
				fmt.Fprintf(os.Stderr, "Error: --lat must be a number\n")
				os.Exit(1)
			}
			lat = v
			latSet = true
			i += 2

			f.lat = requireFloat(arg, args, &i)
			f.latSet = true

			if i+1 >= len(args) {
				fmt.Fprintf(os.Stderr, "Error: --lng requires a value\n")
				os.Exit(1)
			}
			v, err := strconv.ParseFloat(args[i+1], 64)
			if err != nil {
				fmt.Fprintf(os.Stderr, "Error: --lng must be a number\n")
				os.Exit(1)
			}
			lng = v
			lngSet = true
			i += 2

			f.lng = requireFloat(arg, args, &i)
			f.lngSet = true

			if i+1 >= len(args) {
				fmt.Fprintf(os.Stderr, "Error: --timezone requires a value\n")
				os.Exit(1)
			}
			timezone = args[i+1]
			i += 2

			f.timezone = requireValue(arg, args, &i)

	return f
}

	if folder == "" && file == "" {

// requireValue returns the next argument after a flag, or exits with an error
func requireValue(flag string, args []string, i *int) string {
	if *i+1 >= len(args) {
		fmt.Fprintf(os.Stderr, "Error: %s requires a value\n", flag)
		os.Exit(1)
	}
	v := args[*i+1]
	*i += 2
	return v
}
// requireFloat parses the next argument as a float64, or exits with an error
func requireFloat(flag string, args []string, i *int) float64 {
	s := requireValue(flag, args, i)
	v, err := strconv.ParseFloat(s, 64)
	if err != nil {
		fmt.Fprintf(os.Stderr, "Error: %s must be a number\n", flag)
		os.Exit(1)
	}
	return v
}
// validatePushCertaintyFlags checks flag combinations and exits on error
func validatePushCertaintyFlags(f pushCertaintyFlags) {
	if f.folder == "" && f.file == "" {

	if night && day {

	if f.night && f.day {

	if (night || day) && (!latSet || !lngSet) {

	if (f.night || f.day) && (!f.latSet || !f.lngSet) {

}

// runCallsPushCertainty promotes certainty=90 segments to certainty=100 for a filtered set.
//
// JSON output schema:
//
//	{
//	  "segments_updated": int,      // Number of segments promoted from 90→100
//	  "files_updated": int,         // Number of .data files modified
//	  "time_filtered_count": int    // Files skipped by --night/--day filter
//	}
func runCallsPushCertainty(args []string) {
	f := parsePushCertaintyArgs(args)
	validatePushCertaintyFlags(f)

	speciesName, callType := utils.ParseSpeciesCallType(species)

	speciesName, callType := utils.ParseSpeciesCallType(f.species)

		Folder:   folder,
		File:     file,
		Filter:   filter,

		Folder:   f.folder,
		File:     f.file,
		Filter:   f.filter,

		Night:    night,
		Day:      day,
		Lat:      lat,
		Lng:      lng,
		Timezone: timezone,

		Night:    f.night,
		Day:      f.day,
		Lat:      f.lat,
		Lng:      f.lng,
		Timezone: f.timezone,

}
// nextUniqueValue returns the next argument after the flag, or exits if already set.
func (p *clipArgParser) nextUniqueValue(flag, current string) string {
	if current != "" {
		fmt.Fprintf(os.Stderr, "Error: %s can only be specified once\n", flag)
		os.Exit(1)
	}
	return p.nextValue(flag)

// RunCallsClip handles the "calls clip" subcommand
//
// JSON output schema:
//
//	{
//	  "files_processed": int,       // .data files processed
//	  "segments_clipped": int,      // Segments that generated clips
//	  "night_skipped": int,         // Segments skipped (--night, omitted if 0)
//	  "day_skipped": int,           // Segments skipped (--day, omitted if 0)
//	  "output_files": [string],     // Paths to generated clip files (.wav/.png)
//	  "errors": [string]            // Error messages (omitted if empty)
//	}
func RunCallsClip(args []string) {
	var file, folder, output, prefix, filter, species, timezone string
	var size, certainty int
	var color, wavOnly, night, day bool
	var lat, lng float64
	var latSet, lngSet bool

	// Default to -1 (no certainty filter)
	certainty = -1

// clipFlags holds the parsed CLI flags for calls clip
type clipFlags struct {
	file      string
	folder    string
	output    string
	prefix    string
	filter    string
	species   string
	timezone  string
	size      int
	certainty int
	color     bool
	wavOnly   bool
	night     bool
	day       bool
	lat       float64
	lng       float64
	latSet    bool
	lngSet    bool
}

	// Parse arguments

// parseClipArgs parses CLI arguments into clip flags
func parseClipArgs(args []string) clipFlags {
	f := clipFlags{certainty: -1}

			file = p.nextValue(arg)

			f.file = p.nextValue(arg)

			folder = p.nextValue(arg)

			f.folder = p.nextValue(arg)

			output = p.nextValue(arg)

			f.output = p.nextValue(arg)

			prefix = p.nextValue(arg)

			f.prefix = p.nextValue(arg)

			if filter != "" {
				fmt.Fprintf(os.Stderr, "Error: --filter can only be specified once\n")
				os.Exit(1)
			}
			filter = p.nextValue(arg)

			f.filter = p.nextUniqueValue(arg, f.filter)

			if species != "" {
				fmt.Fprintf(os.Stderr, "Error: --species can only be specified once\n")
				os.Exit(1)
			}
			species = p.nextValue(arg)

			f.species = p.nextUniqueValue(arg, f.species)

			certainty = v

			f.certainty = v

			size = p.nextInt(arg)

			f.size = p.nextInt(arg)

			color = true

			f.color = true

			wavOnly = true

			f.wavOnly = true

			night = true

			f.night = true

			day = true

			f.day = true

			lat = p.nextFloat(arg)
			latSet = true

			f.lat = p.nextFloat(arg)
			f.latSet = true

			lng = p.nextFloat(arg)
			lngSet = true

			f.lng = p.nextFloat(arg)
			f.lngSet = true

			timezone = p.nextValue(arg)

			f.timezone = p.nextValue(arg)

	return f
}

	// Validate required flags

// validateClipFlags checks required flags and flag combinations
func validateClipFlags(f clipFlags) {

	if file == "" && folder == "" {

	if f.file == "" && f.folder == "" {

	if output == "" {

	if f.output == "" {

	if prefix == "" {

	if f.prefix == "" {

	if night && day {

	if f.night && f.day {

	if (night || day) && (!latSet || !lngSet) {

	if (f.night || f.day) && (!f.latSet || !f.lngSet) {

}
// RunCallsClip handles the "calls clip" subcommand
//
// JSON output schema:
//
//	{
//	  "files_processed": int,       // .data files processed
//	  "segments_clipped": int,      // Segments that generated clips
//	  "night_skipped": int,         // Segments skipped (--night, omitted if 0)
//	  "day_skipped": int,           // Segments skipped (--day, omitted if 0)
//	  "output_files": [string],     // Paths to generated clip files (.wav/.png)
//	  "errors": [string]            // Error messages (omitted if empty)
//	}
func RunCallsClip(args []string) {
	f := parseClipArgs(args)
	validateClipFlags(f)

		File:      file,
		Folder:    folder,
		Output:    output,
		Prefix:    prefix,
		Filter:    filter,
		Species:   species,
		Certainty: certainty,
		Size:      size,
		Color:     color,
		WavOnly:   wavOnly,
		Night:     night,
		Day:       day,
		Lat:       lat,
		Lng:       lng,
		Timezone:  timezone,

		File:      f.file,
		Folder:    f.folder,
		Output:    f.output,
		Prefix:    f.prefix,
		Filter:    f.filter,
		Species:   f.species,
		Certainty: f.certainty,
		Size:      f.size,
		Color:     f.color,
		WavOnly:   f.wavOnly,
		Night:     f.night,
		Day:       f.day,
		Lat:       f.lat,
		Lng:       f.lng,
		Timezone:  f.timezone,

## [2026-05-04] Reduce cyclomatic complexity of 8 functions over gocyclo 30
Refactored 8 functions that exceeded cyclomatic complexity of 30 by extracting
helper functions with clear responsibilities:
1. **`CallsPropagate` (39→6)**: Extracted `validatePropagateInput`, `hasBothFilters`,
   `collectPropagateSources`, `propagateTargets`, `findUpdatableTargetLabel`,
   `findOverlappingSources`, `resolveCallType`, `buildConflictRecord`, `applyPropagation`.
2. **`CallsSummarise` (38→5)**: Extracted `summariseFiles`, `trackMeta`, `filterLabels`,
   `buildLabelSummaries`, `updateStatsFromLabels`, `updateFilterStats`,
   `updateReviewStatus`, `finaliseSummary`.
3. **`runCallsPushCertainty` (35→7)**: Extracted `parsePushCertaintyArgs`,
   `requireValue`, `requireFloat`, `validatePushCertaintyFlags`.
4. **`RunCallsClip` (35→2)**: Extracted `parseClipArgs`, `validateClipFlags`,
   `nextUniqueValue` on clipArgParser.
5. **`createCluster` (34→19)**: Extracted `validateCreateClusterFields`,
   `validateCreateClusterIDs`, `verifyDatasetForCluster`, `verifyLocationForCluster`,
   `verifyPatternExists`, `findExistingClusterInLocation`, `fetchClusterByID`.
6. **`ValidateMappingAgainstDB` (32→5)**: Extracted `collectMappedLabels`,
   `validateMappedSpecies`, `validateMappedCalltypes`.
7. **`CallsFromPreds` (32→8)**: Extracted `readPredCSV`, `findPredCSVColumns`,
   `readPredCSVRows`, `addDetectionsFromRow`, `clusterDetections`.
8. **`processRavenFileCached` (31→10)**: Extracted `parseRavenHeader`,
   `parseRavenSelections`, `parseRavenRow`, `deriveWAVBaseName`, `resolveWAVPath`.