Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

41.5 KB
Raw Blame
import { match } from 'ts-pattern'

import { getSeriesColor } from 'lib/colors'
import { MAX_EXPERIMENT_VARIANTS } from 'lib/constants'
import { uuid } from 'lib/utils/dom'
import { MathAvailability } from 'scenes/insights/filters/ActionFilter/ActionFilterRow/types'
import { SeriesNode, isActionsSeriesNode, isEventsSeriesNode } from 'scenes/insights/filters/ActionFilter/seriesNode'

import { isFunnelsQuery, isNodeWithSource, isTrendsQuery } from '~/queries/schema/node-guards'
import {
    ActionsNode,
    AnyEntityNode,
    Breakdown,
    CachedNewExperimentQueryResponse,
    ExperimentEventExposureConfig,
    ExperimentExposureConfig,
    ExperimentFunnelMetricStep,
    ExperimentFunnelsQuery,
    ExperimentMetric,
    ExperimentMetricSource,
    ExperimentMetricType,
    ExperimentTrendsQuery,
    NodeKind,
    ProductKey,
    TrendsQuery,
    isExperimentFunnelMetric,
    isExperimentMeanMetric,
    isExperimentRatioMetric,
    isExperimentExposureNode,
    isExperimentRetentionMetric,
} from '~/queries/schema/schema-general'
import { isValidQueryForExperiment } from '~/queries/utils'
import {
    AnyPropertyFilter,
    BreakdownAttributionType,
    ChartDisplayType,
    Experiment,
    ExperimentMetricGoal,
    ExperimentMetricMathType,
    FeatureFlagBasicType,
    FeatureFlagType,
    FunnelConversionWindowTimeUnit,
    MultivariateFlagVariant,
    PropertyFilterType,
    type InsightModel,
    UniversalFiltersGroupValue,
} from '~/types'

import { EXPERIMENT_VARIANT_MULTIPLE } from 'products/experiments/frontend/constants'
import type {
    ExperimentFeatureFlagFiltersApi,
    ExperimentFeatureFlagInputApi,
    ExperimentToSavedMetricApi,
} from 'products/experiments/frontend/generated/api.schemas'

import { EXPOSURE_DEFAULT_EVENT, resolvedExposureEvent } from './exposureContract'
import { SharedMetric } from './SharedMetrics/sharedMetricLogic'

const MULTIPLE_VARIANT_WARNING_THRESHOLD = 0.5 // on the 0-100 scale (0.5 = 0.5%)

export function filterLowMultipleVariant<T extends { variant: string; percentage: number }>(variants: T[]): T[] {
    return variants.filter(
        (v) => v.variant !== EXPERIMENT_VARIANT_MULTIPLE || v.percentage > MULTIPLE_VARIANT_WARNING_THRESHOLD
    )
}

/**
 * Resolves the effective multi-variant handling, applying the backend default when unset.
 * See products/experiments/backend/hogql_queries/exposure_query_logic.py (default = `EXCLUDE`).
 */
export function resolveMultipleVariantHandling(
    handling: 'exclude' | 'first_seen' | undefined
): 'exclude' | 'first_seen' {
    return handling ?? 'exclude'
}

export function isEventExposureConfig(config: ExperimentExposureConfig): config is ExperimentEventExposureConfig {
    return config.kind === NodeKind.ExperimentEventExposureConfig || 'event' in config
}

export function getExposureConfigDisplayName(config: ExperimentExposureConfig): string {
    if (isEventExposureConfig(config)) {
        return config.event || 'Unknown Event'
    }
    if (config.kind === NodeKind.ExperimentWarehouseNativeExposureConfig) {
        return 'Warehouse-native query'
    }
    return config.name || `Action ${config.id}`
}

export function getVariantColor(variantKey: string, featureFlagVariants: MultivariateFlagVariant[]): string {
    const variantIndex = featureFlagVariants.findIndex((v) => v.key === variantKey)
    return variantIndex !== -1 ? getSeriesColor(variantIndex) : 'var(--muted)'
}

/**
 * Variants for an experiment. Saved experiments resolve from the linked feature flag (the source
 * of truth); an unsaved draft has no flag yet, so it resolves from the draft flag config instead.
 */
export function getExperimentVariants(experiment: Partial<Experiment> | null | undefined): MultivariateFlagVariant[] {
    return (
        experiment?.feature_flag?.filters?.multivariate?.variants ??
        experiment?.feature_flag_config?.filters?.multivariate?.variants ??
        []
    )
}

/**
 * Variants for a standalone feature flag (no experiment in hand). Reads the flag's saved config only.
 */
export function getFlagVariants(
    flag: FeatureFlagBasicType | FeatureFlagType | null | undefined
): MultivariateFlagVariant[] {
    return flag?.filters?.multivariate?.variants ?? []
}

/**
 * The effective baseline variant, mirroring the backend rule (get_baseline_variant_key):
 * the configured stats_config.baseline_variant_key, else 'control' when the flag has one,
 * else the flag's first variant. A control-less draft can lack the configured key until
 * launch pins it, so callers must not assume 'control' exists.
 */
export function getBaselineVariantKey(experiment: Partial<Experiment> | null | undefined): string {
    const configured = experiment?.stats_config?.baseline_variant_key
    if (configured) {
        return configured
    }
    const variants = getExperimentVariants(experiment)
    if (variants.length === 0 || variants.some((variant) => variant.key === 'control')) {
        return 'control'
    }
    return variants[0].key
}

export function formatUnitByQuantity(value: number, unit: string): string {
    return value === 1 ? unit : unit + 's'
}

export function ensureIsPercent(value: string | number | undefined): number {
    const parsedNum = typeof value === 'string' ? parseInt(value, 10) : (value ?? 0)
    const num = isNaN(parsedNum) ? 0 : parsedNum
    return Math.min(100, Math.max(0, num))
}

export function percentageDistribution(variantCount: number): number[] {
    const basePercentage = Math.floor(100 / variantCount)
    const percentages = Array.from<number>({ length: variantCount }).fill(basePercentage)
    let remaining = 100 - basePercentage * variantCount
    for (let i = 0; remaining > 0; i++, remaining--) {
        // try to equally distribute `remaining` across variants
        percentages[i] += 1
    }
    return percentages
}

export function isEvenlyDistributed(variants: MultivariateFlagVariant[]): boolean {
    const evenPercentages = percentageDistribution(variants.length)
    return variants.every((variant, index) => variant.rollout_percentage === evenPercentages[index])
}

// The experiments backend replaces these HogQL filter keys with the team's current evaluation pass rules. Other query
// kinds cannot resolve them, so queries outside the experiment results drop them.
const EVALUATION_PASS_MARKERS = new Set(['aiEvaluationGraded()', 'aiEvaluationPassed()'])

function withoutEvaluationPassMarkers(properties: AnyPropertyFilter[]): AnyPropertyFilter[] {
    return properties.filter((p) => !(p.type === PropertyFilterType.HogQL && EVALUATION_PASS_MARKERS.has(p.key)))
}

function seriesToFilter(series: AnyEntityNode | ExperimentMetricSource): UniversalFiltersGroupValue | null {
    if (series.kind === NodeKind.EventsNode) {
        return {
            id: series.event ?? null,
            name: series.event as string,
            type: 'events',
            properties: withoutEvaluationPassMarkers(series.properties ?? []),
        }
    }

    if (series.kind === NodeKind.ActionsNode) {
        return {
            id: series.id,
            name: series.name,
            type: 'actions',
        }
    }

    if (series.kind === NodeKind.ExperimentDataWarehouseNode) {
        return {
            id: series.table_name,
            name: series.name,
            type: 'data_warehouse',
        }
    }

    return null
}

/**
 * Event/action filters for one metric's sources — the "session reached this metric" part of a
 * recordings query. Data-warehouse sources have no session events and are skipped, so a metric
 * whose every source is a data-warehouse node (or a retention metric, whose steps the recordings
 * surfaces don't enumerate) yields no filters.
 */
export function getMetricSessionFilters(metric: ExperimentMetric): UniversalFiltersGroupValue[] {
    const sources: (ExperimentMetricSource | ExperimentFunnelMetricStep)[] = isExperimentMeanMetric(metric)
        ? [metric.source]
        : isExperimentFunnelMetric(metric)
          ? metric.series
          : isExperimentRatioMetric(metric)
            ? [metric.numerator, metric.denominator]
            : []
    return sources
        .filter((source) => source.kind === NodeKind.EventsNode || source.kind === NodeKind.ActionsNode)
        .map((source) => seriesToFilter(source))
        .filter((filter): filter is UniversalFiltersGroupValue => filter !== null)
}

/**
 * The distinct events a metric counts. A metric's name is free text ("Rageclicks per user"), so
 * on its own it doesn't say what a session has to have fired to match.
 */
export function getMetricSourceEventNames(metric: ExperimentMetric): string[] {
    const names = getMetricSessionFilters(metric)
        // Only entity filters name an event; a nested filter group (which the type allows) doesn't.
        .flatMap((filter) => ('id' in filter ? [String(filter.name ?? filter.id ?? '')] : []))
        .filter(Boolean)
    return [...new Set(names)]
}

export const NOT_A_FUNNEL_REASON = "This filter reads a funnel's last step, so it needs a funnel metric."

export const FUNNEL_SERVER_SIDE_COMPLETION_REASON =
    "This filter reads a funnel's last step. This one is captured server-side without a session ID, so recordings can't be matched."

export const FUNNEL_DATA_WAREHOUSE_COMPLETION_REASON =
    "This filter reads a funnel's last step. This one is measured in the data warehouse, which has no session events to match recordings on."

/**
 * Why drop-off can't be asked of this metric, or null when it can. An experiment funnel's first
 * step is always the exposure event (the analysis prepends it), so drop-off reads only the
 * funnel's last step, and that step alone has to be matchable. The whole-metric linkability
 * check can't stand in for this, since a funnel stays matchable on its other steps. Mirrors the
 * `session_buckets` endpoint, which refuses the same shapes rather than counting a completion no
 * recording can show as zero in every session.
 */
export function getFunnelDropoffReason(metric: ExperimentMetric, unlinkableEventNames: Set<string>): string | null {
    if (!isExperimentFunnelMetric(metric) || metric.series.length === 0) {
        return NOT_A_FUNNEL_REASON
    }
    const completion = metric.series[metric.series.length - 1]
    if (completion.kind === NodeKind.ExperimentDataWarehouseNode) {
        return FUNNEL_DATA_WAREHOUSE_COMPLETION_REASON
    }
    if (completion.kind === NodeKind.EventsNode && completion.event && unlinkableEventNames.has(completion.event)) {
        return FUNNEL_SERVER_SIDE_COMPLETION_REASON
    }
    return null
}

/**
 * Whether a recordings event filter can only match zero sessions: the project has never seen the
 * event with a `$session_id` (e.g. it is captured server-side). Action and data warehouse filters
 * pass through unchecked, matching the replay playlist's own posture.
 */
export function isUnlinkableEventFilter(
    filter: UniversalFiltersGroupValue,
    unlinkableEventNames: Set<string>
): boolean {
    return (
        'type' in filter &&
        filter.type === 'events' &&
        'name' in filter &&
        typeof filter.name === 'string' &&
        unlinkableEventNames.has(filter.name)
    )
}

export const METRIC_UNLINKABLE_REASON =
    "This metric's events are captured server-side without a session ID, so recordings can't be matched."

export const RETENTION_UNLINKABLE_REASON =
    'Retention metrics measure a return visit, which happens in a later session than the one that starts it. No single recording can show both, so these metrics are left out of the filter.'

export const DATA_WAREHOUSE_UNLINKABLE_REASON =
    'This metric is measured entirely in the data warehouse, which has no session events to match recordings on.'

/**
 * Why a metric cannot narrow a recordings list, as a value telemetry can count. The prose the
 * viewer reads is derived from this, so a copy change can never shift what a report measures.
 */
export type ExperimentMetricUnlinkableCode = 'server_side_events' | 'retention' | 'data_warehouse'

/**
 * Why a metric can't narrow a recordings list, or null when it can. A metric is unlinkable when
 * every one of its sources is a never-session-linked event, or when it yields no session filter at
 * all (a retention metric, or one measured only in the data warehouse). Either way its filter could
 * only match zero sessions. Pass an empty `unlinkableEventNames` while the linkability check loads,
 * which fails open, the posture every linkability consumer shares.
 */
export function getMetricUnlinkableCode(
    metric: ExperimentMetric,
    unlinkableEventNames: Set<string>
): ExperimentMetricUnlinkableCode | null {
    const filters = getMetricSessionFilters(metric)
    if (filters.length === 0) {
        return isExperimentRetentionMetric(metric) ? 'retention' : 'data_warehouse'
    }
    return filters.every((filter) => isUnlinkableEventFilter(filter, unlinkableEventNames))
        ? 'server_side_events'
        : null
}

const METRIC_UNLINKABLE_REASONS: Record<ExperimentMetricUnlinkableCode, string> = {
    server_side_events: METRIC_UNLINKABLE_REASON,
    retention: RETENTION_UNLINKABLE_REASON,
    data_warehouse: DATA_WAREHOUSE_UNLINKABLE_REASON,
}

/** The prose for `getMetricUnlinkableCode`, as the tab's own metric dropdown reads it. */
export function getMetricUnlinkableReason(metric: ExperimentMetric, unlinkableEventNames: Set<string>): string | null {
    const code = getMetricUnlinkableCode(metric, unlinkableEventNames)
    return code === null ? null : METRIC_UNLINKABLE_REASONS[code]
}

/**
 * The single event an experiment's exposure is counted on, for the session-linkability check.
 * Null for an action exposure config, which can match several events, so no one name applies.
 */
export function getExposureLinkabilityEventName(experiment: Experiment): string | null {
    const exposureConfig = experiment.exposure_criteria?.exposure_config
    if (exposureConfig && !(isEventExposureConfig(exposureConfig) && exposureConfig.event === EXPOSURE_DEFAULT_EVENT)) {
        return isEventExposureConfig(exposureConfig) && exposureConfig.event ? exposureConfig.event : null
    }
    return resolvedExposureEvent(experiment)
}

/**
 * Event names whose session-linkability must be checked before building "View recordings" links:
 * the exposure event plus every plain-event metric step across primary, secondary and shared
 * metrics. Action and data warehouse steps pass through unchecked (same as the replay playlist's
 * own check), as do "all events" steps, which have no event name.
 */
export function getSessionLinkabilityEventNames(experiment: Experiment): string[] {
    const eventNames = new Set<string>()

    const exposureEventName = getExposureLinkabilityEventName(experiment)
    if (exposureEventName) {
        eventNames.add(exposureEventName)
    }

    const metrics = [
        ...(experiment.metrics || []),
        ...(experiment.metrics_secondary || []),
        ...(experiment.saved_metrics || []).map((savedMetric: { query?: ExperimentMetric }) => savedMetric?.query),
    ].filter((metric): metric is ExperimentMetric => metric?.kind === NodeKind.ExperimentMetric)

    for (const metric of metrics) {
        const sources: (ExperimentMetricSource | ExperimentFunnelMetricStep)[] = isExperimentMeanMetric(metric)
            ? [metric.source]
            : isExperimentFunnelMetric(metric)
              ? metric.series
              : isExperimentRatioMetric(metric)
                ? [metric.numerator, metric.denominator]
                : []
        for (const source of sources) {
            if (source.kind === NodeKind.EventsNode && source.event) {
                eventNames.add(source.event)
            }
        }
    }

    return Array.from(eventNames)
}

// Mirrors the backend eligibility rule (experiment_eligibility_error): multivariate with 2-20 variants
export function featureFlagEligibleForExperiment(featureFlag: FeatureFlagType): true {
    const variants = getFlagVariants(featureFlag)
    if (variants.length < 2) {
        throw new Error('Feature flag must have at least 2 variants (a baseline and at least one test variant).')
    }
    if (variants.length > MAX_EXPERIMENT_VARIANTS) {
        throw new Error(`Feature flag must have at most ${MAX_EXPERIMENT_VARIANTS} variants.`)
    }
    return true
}

/**
 * TODO: review. Probably deprecated
 */
export function getDefaultFunnelMetric(): ExperimentMetric {
    return {
        kind: NodeKind.ExperimentMetric,
        uuid: uuid(),
        metric_type: ExperimentMetricType.FUNNEL,
        goal: ExperimentMetricGoal.Increase,
        series: [
            {
                kind: NodeKind.EventsNode,
                event: '$pageview',
                name: '$pageview',
            },
        ],
    }
}

/**
 * @deprecated
 */
export function getDefaultCountMetric(): ExperimentMetric {
    return {
        kind: NodeKind.ExperimentMetric,
        uuid: uuid(),
        metric_type: ExperimentMetricType.MEAN,
        goal: ExperimentMetricGoal.Increase,
        source: {
            kind: NodeKind.EventsNode,
            event: '$pageview',
            math: ExperimentMetricMathType.TotalCount,
        },
    }
}

export function getDefaultRatioMetric(): ExperimentMetric {
    return {
        kind: NodeKind.ExperimentMetric,
        uuid: uuid(),
        metric_type: ExperimentMetricType.RATIO,
        goal: ExperimentMetricGoal.Increase,
        numerator: {
            kind: NodeKind.EventsNode,
            event: '$pageview',
            name: '$pageview',
            math: ExperimentMetricMathType.TotalCount,
        },
        denominator: {
            kind: NodeKind.EventsNode,
            event: '$pageview',
            name: '$pageview',
            math: ExperimentMetricMathType.TotalCount,
        },
    }
}

export function getDefaultRetentionMetric(): ExperimentMetric {
    return {
        kind: NodeKind.ExperimentMetric,
        uuid: uuid(),
        metric_type: ExperimentMetricType.RETENTION,
        goal: ExperimentMetricGoal.Increase,
        start_event: {
            kind: NodeKind.EventsNode,
            event: '$pageview',
            name: '$pageview',
            math: ExperimentMetricMathType.TotalCount,
        },
        completion_event: {
            kind: NodeKind.EventsNode,
            event: '$pageview',
            name: '$pageview',
            math: ExperimentMetricMathType.TotalCount,
        },
        retention_window_start: 1,
        retention_window_end: 1,
        retention_window_unit: FunnelConversionWindowTimeUnit.Day,
        start_handling: 'first_seen',
    }
}

export function getDefaultExperimentMetric(metricType: ExperimentMetricType): ExperimentMetric {
    switch (metricType) {
        case ExperimentMetricType.FUNNEL:
            return getDefaultFunnelMetric()
        case ExperimentMetricType.RATIO:
            return getDefaultRatioMetric()
        case ExperimentMetricType.RETENTION:
            return getDefaultRetentionMetric()
        default:
            return getDefaultCountMetric()
    }
}

export function getExperimentMetricFromInsight(insight: InsightModel | null): ExperimentMetric | undefined {
    if (!insight?.query || !isValidQueryForExperiment(insight?.query) || !isNodeWithSource(insight.query)) {
        return undefined
    }

    const metricName = (insight?.name || insight?.derived_name) ?? undefined

    if (isFunnelsQuery(insight.query.source)) {
        return {
            kind: NodeKind.ExperimentMetric,
            uuid: uuid(),
            metric_type: ExperimentMetricType.FUNNEL,
            goal: ExperimentMetricGoal.Increase,
            name: metricName,
            series: insight.query.source.series.map((series) => ({
                ...series,
                // Ensure we have proper node structure
                kind: series.kind || NodeKind.EventsNode,
                event: series.kind === NodeKind.EventsNode ? series.event : undefined,
                name: series.name || (series.kind === NodeKind.EventsNode ? series.event : undefined),
            })) as ExperimentFunnelMetricStep[],
        }
    }

    /**
     * TODO: add support for trends queries. IsValidQueryForExperiment
     * has a isFunnelsQuery check, so this is never called. Trend queries
     * get undefined.
     */
    if (isTrendsQuery(insight.query.source)) {
        // For trends queries, convert the first series to a mean metric
        const firstSeries = insight.query.source.series?.[0]
        if (!firstSeries) {
            return undefined
        }

        return {
            kind: NodeKind.ExperimentMetric,
            uuid: uuid(),
            metric_type: ExperimentMetricType.MEAN,
            goal: ExperimentMetricGoal.Increase,
            name: metricName,
            source: {
                ...firstSeries,
                kind: NodeKind.EventsNode,
                event: firstSeries.name,
                name: firstSeries.name,
                math: firstSeries.math || ExperimentMetricMathType.TotalCount,
            },
        }
    }

    return undefined
}

export function exposureConfigToSeries(exposureConfig: ExperimentExposureConfig): SeriesNode[] {
    if (exposureConfig.kind === NodeKind.ExperimentEventExposureConfig) {
        return [
            {
                kind: NodeKind.EventsNode,
                event: exposureConfig.event,
                name: exposureConfig.event,
                properties: exposureConfig.properties,
            },
        ]
    }
    if (exposureConfig.kind === NodeKind.ActionsNode) {
        return [exposureConfig]
    }
    return []
}

/**
 * Only an event or an action can mark exposure, so any other series gives no config.
 */
export function seriesToExposureConfig(series: SeriesNode[]): ExperimentEventExposureConfig | ActionsNode | undefined {
    const [node] = series
    if (isEventsSeriesNode(node)) {
        return {
            kind: NodeKind.ExperimentEventExposureConfig,
            // "All events" leaves `event` null, which the API rejects as an exposure event.
            event: node.event as string,
            properties: node.properties ?? [],
        }
    }
    if (isActionsSeriesNode(node)) {
        return {
            kind: NodeKind.ActionsNode,
            id: node.id,
            name: node.name,
            properties: node.properties,
        }
    }
    return undefined
}

/**
 * returns the math availability for a metric type
 */
export function getMathAvailability(metricType: ExperimentMetricType): MathAvailability {
    switch (metricType) {
        case ExperimentMetricType.MEAN:
        case ExperimentMetricType.RATIO:
            return MathAvailability.All
        default:
            return MathAvailability.None
    }
}

/**
 * returns the allowed math types that can be used when creating a metric
 */
export function getAllowedMathTypes(metricType: ExperimentMetricType): ExperimentMetricMathType[] {
    switch (metricType) {
        case ExperimentMetricType.MEAN:
            return [
                ExperimentMetricMathType.TotalCount,
                ExperimentMetricMathType.Sum,
                ExperimentMetricMathType.UniqueUsers,
                ExperimentMetricMathType.UniqueGroup,
                ExperimentMetricMathType.Avg,
                ExperimentMetricMathType.Min,
                ExperimentMetricMathType.Max,
                ExperimentMetricMathType.UniqueSessions,
                ExperimentMetricMathType.HogQL,
            ]
        case ExperimentMetricType.RATIO:
            return [
                ExperimentMetricMathType.TotalCount,
                ExperimentMetricMathType.Sum,
                ExperimentMetricMathType.UniqueUsers,
                ExperimentMetricMathType.UniqueGroup,
                ExperimentMetricMathType.UniqueSessions,
                ExperimentMetricMathType.Avg,
                ExperimentMetricMathType.Min,
                ExperimentMetricMathType.Max,
            ]
        default:
            return [ExperimentMetricMathType.TotalCount]
    }
}

/**
 * Check if a query is a legacy experiment metric.
 *
 * We use `unknown` here because in some cases, the query is not typed.
 */
export const isLegacyExperimentQuery = (query: unknown): query is ExperimentTrendsQuery | ExperimentFunnelsQuery => {
    /**
     * since query could be an object literal type, we need to check for the kind property
     */
    return (
        !!query &&
        typeof query === 'object' &&
        'kind' in query &&
        (query.kind === NodeKind.ExperimentTrendsQuery || query.kind === NodeKind.ExperimentFunnelsQuery)
    )
}

/**
 * True when an inline or shared metric of the experiment still uses the legacy ExperimentTrendsQuery or
 * ExperimentFunnelsQuery shape. The app shows no results for such an experiment until it is migrated.
 */
export const isLegacyExperiment = (experiment?: Experiment | null): boolean => {
    if (!experiment) {
        return false
    }
    const { metrics, metrics_secondary, saved_metrics } = experiment
    // saved_metrics has a different structure and so we need to check for it separately
    if ((saved_metrics ?? []).some(isLegacySharedMetric)) {
        return true
    }
    return [...(metrics ?? []), ...(metrics_secondary ?? [])].some(isLegacyExperimentQuery)
}

export const isLegacySharedMetric = ({ query }: SharedMetric): boolean => isLegacyExperimentQuery(query)

const getEventCountSeries = (metric: ExperimentMetric): AnyEntityNode[] => {
    /**
     * we short circuit for funnel metrics
     */
    if (isExperimentFunnelMetric(metric)) {
        const lastStep = metric.series[metric.series.length - 1]
        if (lastStep) {
            if (lastStep.kind === NodeKind.EventsNode) {
                return [
                    {
                        kind: NodeKind.EventsNode,
                        name: lastStep.event || undefined,
                        event: lastStep.event,
                        math: ExperimentMetricMathType.TotalCount,
                        ...(lastStep.properties &&
                            lastStep.properties.length > 0 && {
                                properties: withoutEvaluationPassMarkers(lastStep.properties),
                            }),
                    },
                ]
            } else if (lastStep.kind === NodeKind.ActionsNode) {
                return [
                    {
                        kind: NodeKind.ActionsNode,
                        id: lastStep.id,
                        name: lastStep.name,
                        math: ExperimentMetricMathType.TotalCount,
                        ...(lastStep.properties &&
                            lastStep.properties.length > 0 && { properties: lastStep.properties }),
                    },
                ]
            }
        }
    }

    const source: ExperimentMetricSource | null = match(metric)
        .when(isExperimentRatioMetric, (ratioMetric) => ratioMetric.numerator)
        // An exposure-anchored start has no literal event to preview, so show completion-event activity
        .when(isExperimentRetentionMetric, (retentionMetric) =>
            isExperimentExposureNode(retentionMetric.start_event)
                ? retentionMetric.completion_event
                : retentionMetric.start_event
        )
        .when(isExperimentMeanMetric, (meanMetric) => meanMetric.source)
        .otherwise(() => null)

    if (!source) {
        return []
    }

    const series: AnyEntityNode[] = match(source)
        .with({ kind: NodeKind.EventsNode }, (eventsNode) => [
            {
                kind: NodeKind.EventsNode as const,
                name: eventsNode.event || undefined,
                event: eventsNode.event || undefined,
                math: ExperimentMetricMathType.TotalCount,
                ...(eventsNode.properties &&
                    eventsNode.properties.length > 0 && {
                        properties: withoutEvaluationPassMarkers(eventsNode.properties),
                    }),
            },
        ])
        .with({ kind: NodeKind.ActionsNode }, (actionsNode) => [
            {
                kind: NodeKind.ActionsNode as const,
                id: actionsNode.id,
                name: actionsNode.name,
                math: ExperimentMetricMathType.TotalCount,
                ...(actionsNode.properties &&
                    actionsNode.properties.length > 0 && { properties: actionsNode.properties }),
            },
        ])
        .with({ kind: NodeKind.ExperimentDataWarehouseNode }, (dataWarehouseNode) => [
            {
                kind: NodeKind.DataWarehouseNode as const,
                id: dataWarehouseNode.table_name,
                id_field: dataWarehouseNode.data_warehouse_join_key,
                table_name: dataWarehouseNode.table_name,
                timestamp_field: dataWarehouseNode.timestamp_field,
                distinct_id_field: dataWarehouseNode.events_join_key,
                name: dataWarehouseNode.name,
                math: ExperimentMetricMathType.TotalCount,
                ...(dataWarehouseNode.properties &&
                    dataWarehouseNode.properties.length > 0 && { properties: dataWarehouseNode.properties }),
            },
        ])
        // PostHog holds no rows of a warehouse-native source, so it has no recent activity to count.
        .with({ kind: NodeKind.ExperimentWarehouseNativeNode }, () => [])
        .exhaustive()

    return series
}

/**
 * Builds a TrendsQuery for counting events in the last 14 days for experiment metric preview
 */
export function getEventCountQuery(metric: ExperimentMetric, filterTestAccounts: boolean): TrendsQuery | null {
    const series = getEventCountSeries(metric)

    if (series.length === 0) {
        return null
    }

    // Data warehouse tables don't support test account filters — those filters
    // reference the events table (e.g. events.properties.*), which doesn't exist
    // on a DW table and causes "Unable to resolve field: events". This matches
    // product analytics behavior, where the toggle is disabled for DW sources.
    const isDWQuery = series.some((s) => s.kind === NodeKind.DataWarehouseNode)

    return {
        kind: NodeKind.TrendsQuery,
        series,
        trendsFilter: {
            formulaNodes: [],
            display: ChartDisplayType.BoldNumber,
        },
        dateRange: {
            date_from: '-14d',
            date_to: null,
            explicitDate: false,
        },
        interval: 'day',
        filterTestAccounts: isDWQuery ? false : filterTestAccounts,
        tags: {
            productKey: ProductKey.PRODUCT_ANALYTICS,
        },
    }
}

/**
 * Returns metric indices in display order. Metrics whose UUID appears in
 * orderedUuids come first (in that order), followed by any remaining metrics
 * in their original array position. Each entry is the original index into the
 * metrics array so callers can write results to the correct positional slot.
 *
 * The ordering array is a display hint, not a membership list. An entry that matches no
 * metric is ignored, and a metric the array does not list still renders after the listed
 * ones. Filtering by the array instead would hide any metric whose uuid never reached it.
 */
export function getDisplayOrderedIndices(
    metrics: { uuid?: string }[],
    orderedUuids: string[] | null | undefined
): number[] {
    if (!orderedUuids || orderedUuids.length === 0) {
        return metrics.map((_, i) => i)
    }

    const uuidToIndex = new Map<string, number>()
    for (let i = 0; i < metrics.length; i++) {
        const uuid = metrics[i].uuid
        if (uuid) {
            uuidToIndex.set(uuid, i)
        }
    }

    const ordered: number[] = []
    const seen = new Set<number>()

    for (const uuid of orderedUuids) {
        const idx = uuidToIndex.get(uuid)
        if (idx !== undefined && !seen.has(idx)) {
            ordered.push(idx)
            seen.add(idx)
        }
    }

    for (let i = 0; i < metrics.length; i++) {
        if (!seen.has(i)) {
            ordered.push(i)
        }
    }

    return ordered
}

/**
 * A shared metric's link to an experiment, as the experiment API returns it. The generated type leaves
 * `query` and `metadata` untyped, so this narrows them to the shapes the experiment scene reads and edits.
 */
export type ExperimentSavedMetric = Omit<ExperimentToSavedMetricApi, 'metadata' | 'query' | 'effective_query'> & {
    metadata: {
        type: 'primary' | 'secondary'
        breakdowns?: Breakdown[]
        breakdownAttributionType?: BreakdownAttributionType
        breakdownAttributionValue?: number
        breakdown_limit?: number
    }
    query: ExperimentMetric
    // Optional because a new frontend can briefly receive a response from an API server that predates the field.
    effective_query?: ExperimentMetric | null
}

/**
 * The backend applies the link overrides to the saved query and serves the result as `effective_query`.
 * A legacy shared metric takes no overrides and has no effective query, so its saved query applies as is.
 * A link that carries no query gets an empty metric. Results map to metrics by position, and the callers
 * read fields of every metric, so the link must keep its position.
 */
export const sharedMetricEffectiveQuery = ({
    query,
    effective_query,
}: Pick<ExperimentSavedMetric, 'query' | 'effective_query'>): ExperimentMetric =>
    effective_query ?? query ?? ({} as ExperimentMetric)

export const sharedMetricsToExperimentMetrics = (
    sharedMetrics: ExperimentSavedMetric[] | undefined,
    type: 'primary' | 'secondary'
): ExperimentMetric[] =>
    (sharedMetrics || []).filter(({ metadata }) => metadata.type === type).map(sharedMetricEffectiveQuery)

function enrichSharedMetric(sharedMetric: ExperimentSavedMetric): ExperimentMetric {
    return {
        ...sharedMetricEffectiveQuery(sharedMetric),
        name: sharedMetric.name,
        sharedMetricId: sharedMetric.saved_metric,
        isSharedMetric: true,
    } as ExperimentMetric
}

export type MetricWithResult = {
    metric: ExperimentMetric
    result: CachedNewExperimentQueryResponse | undefined
    error: unknown
    displayIndex: number
    metricIndex: number
}

/**
 * Narrows to a real, saved experiment: present and not the "new"/draft sentinel id. Used by the
 * recalculation-flow component wrappers before mounting experiment-keyed child logics.
 */
export const isSavedExperiment = (experiment: Experiment | null | undefined): experiment is Experiment =>
    experiment?.id != null && experiment.id !== 'new'

export type ExperimentWritePayload<T> = Omit<T, 'feature_flag' | 'feature_flag_config'> & {
    feature_flag?: ExperimentFeatureFlagInputApi
}

/** Update payload for the experiment API: flag config travels in the write shape. An echoed
 * read-only flag is also accepted — the backend ignores flag objects carrying a non-null id. */
export type ExperimentUpdatePayload = Omit<Partial<Experiment>, 'feature_flag'> & {
    feature_flag?: ExperimentFeatureFlagInputApi | Experiment['feature_flag']
    update_feature_flag_params?: boolean
    original_experiment?: Record<string, any>
}

export type ExperimentUpdateRequest = ExperimentUpdatePayload & {
    /**
     * After a 409 conflict, show the server's copy of the sent fields instead of keeping the rejected values for
     * review. A control that applies its value at once sets this. A kept value would look saved there, and the
     * next save would send it over the change that caused the conflict.
     */
    discardOnConflict?: boolean
}

/** The scalar fields experiment surfaces PATCH, sent as base values so the server can three-way
 * merge them per field: a stale write only conflicts when the same field changed on both sides. */
const CONCURRENCY_SCALAR_BASE_FIELDS = [
    'name',
    'description',
    'start_date',
    'end_date',
    'exposure_criteria',
    'stats_config',
    'running_time_calculation',
    'holdout_id',
    'conclusion',
    'conclusion_comment',
    'excluded_variants',
    'only_count_matured_users',
    'parameters',
] as const

/** Concurrency context for experiment PATCHes: the version last read plus the state that version
 * belongs to (metric collections and scalar bases), so the server can merge concurrent edits per
 * metric uuid / per field and reject only true same-field conflicts with a 409, instead of letting
 * a stale write clobber them. */
export function toConcurrencyPayload(
    unmodified: Experiment | null
): Pick<ExperimentUpdatePayload, 'version' | 'original_experiment'> {
    if (!unmodified || typeof unmodified.id !== 'number') {
        return {}
    }
    return {
        version: unmodified.version ?? 0,
        original_experiment: {
            metrics: unmodified.metrics,
            metrics_secondary: unmodified.metrics_secondary,
            saved_metrics_ids: (unmodified.saved_metrics || []).map((sharedMetric) => ({
                id: sharedMetric.saved_metric,
                metadata: sharedMetric.metadata,
            })),
            // Explicit null over undefined: a missing base key makes the server fall back to
            // rejecting any change to that field, while null means "the field was empty".
            ...Object.fromEntries(CONCURRENCY_SCALAR_BASE_FIELDS.map((field) => [field, unmodified[field] ?? null])),
        },
    }
}

/** Whether an API error is the experiment concurrency conflict (as opposed to any other 409,
 * e.g. an approval-required response, which carries no `current_version`). */
export function isExperimentConflictError(error: any): boolean {
    return error?.status === 409 && error?.data?.current_version !== undefined
}

const CONFLICT_UNPRESERVABLE_KEYS = new Set([
    'metrics',
    'metrics_secondary',
    'saved_metrics_ids',
    'primary_metrics_ordered_uuids',
    'secondary_metrics_ordered_uuids',
    'version',
    'original_experiment',
    'update_feature_flag_params',
    'feature_flag',
])

/** The fields of a 409-rejected update worth keeping in local state: the user's scalar edits.
 * Collection and bookkeeping fields are dropped — re-applying a stale metric array over the
 * fresh state would reintroduce exactly the clobbering the conflict prevented. */
export function conflictPreservedFields(payload: ExperimentUpdatePayload): Partial<Experiment> {
    return Object.fromEntries(Object.entries(payload).filter(([key]) => !CONFLICT_UNPRESERVABLE_KEYS.has(key)))
}

/** Flag config the API projects into `parameters` on read. The linked flag owns these keys, so they
 * are absent from the type but present at runtime on every response. */
const PROJECTED_FLAG_CONFIG_KEYS = new Set([
    'feature_flag_variants',
    'rollout_percentage',
    'aggregation_group_type_index',
    'feature_flag_payloads',
    'ensure_experience_continuity',
])

/** Drops the projected flag config, so updating an experiment-owned key does not echo the
 * deprecated flag dialect back to the API. The `feature_flag` sibling of this is
 * {@link toExperimentWritePayload}. */
export function withoutProjectedFlagConfig(parameters: Experiment['parameters'] | undefined): Experiment['parameters'] {
    return Object.fromEntries(
        Object.entries(parameters ?? {}).filter(([key]) => !PROJECTED_FLAG_CONFIG_KEYS.has(key))
    ) as Experiment['parameters']
}

/** Maps UI variants to the flag's write shape, dropping null names the generated type disallows. */
export function toFlagVariantsInput(
    variants: MultivariateFlagVariant[]
): NonNullable<ExperimentFeatureFlagFiltersApi['multivariate']>['variants'] {
    return variants.map(({ key, name, rollout_percentage }) => ({
        key,
        ...(name != null ? { name } : {}),
        rollout_percentage,
    }))
}

/**
 * Builds an experiment write payload. Draft flag config lives on `feature_flag_config` in the
 * flag's own input shape; it moves to the `feature_flag` write field. The read-only `feature_flag`
 * echoed by a GET response is dropped, and `feature_flag_config` never travels literally.
 *
 * Pass `omitFlagConfig` when the experiment links to a pre-existing flag: the flag is linked
 * as-is, and the API rejects explicit config for it.
 */
export function toExperimentWritePayload<T extends Pick<Experiment, 'feature_flag_config'>>(
    experiment: T,
    { omitFlagConfig = false }: { omitFlagConfig?: boolean } = {}
): ExperimentWritePayload<T> {
    const {
        feature_flag: _echoedFlag,
        feature_flag_config,
        ...rest
    } = experiment as T & { feature_flag?: unknown; feature_flag_config?: ExperimentFeatureFlagInputApi }
    const payload = { ...rest } as ExperimentWritePayload<T>

    if (!omitFlagConfig && feature_flag_config) {
        payload.feature_flag = feature_flag_config
    }
    return payload
}

/**
 * Pure zip of one metric type (`primary` | `secondary`) with its results and errors, in display order.
 * Curried over the experiment, so a caller can bind it once per experiment instance and reuse it for
 * both primary and secondary:
 *
 *   const zip = metricResults(experiment)
 *   const primary = zip(primaryResults, primaryErrors, 'primary')
 *   const secondary = zip(secondaryResults, secondaryErrors, 'secondary')
 *
 * Results and errors are positional over `[...inline, ...shared]`, the layout the loaders write to.
 */
export const metricResults =
    (experiment: Experiment) =>
    (
        results: CachedNewExperimentQueryResponse[],
        errors: unknown[],
        type: 'primary' | 'secondary'
    ): MetricWithResult[] => {
        const regularMetrics = (
            type === 'secondary' ? experiment.metrics_secondary || [] : experiment.metrics || []
        ) as ExperimentMetric[]

        const sharedMetrics = (experiment.saved_metrics || [])
            .filter((sharedMetric) => sharedMetric.metadata?.type === type)
            .map(enrichSharedMetric)

        const allMetrics = [...regularMetrics, ...sharedMetrics]
        const orderedUuids =
            type === 'secondary' ? experiment.secondary_metrics_ordered_uuids : experiment.primary_metrics_ordered_uuids

        return getDisplayOrderedIndices(allMetrics, orderedUuids).map((index, displayIndex) => ({
            metric: allMetrics[index],
            result: results[index],
            error: errors[index],
            displayIndex,
            metricIndex: index,
        }))
    }