: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.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
/**
* Preserve group-based feature-flag targeting when MCP agents send partial `filters`.
* Agents rebuild release conditions with only `key` / `operator` / `value`. The API rejects a
* property that has no `type`. A condition set without `aggregation_group_type_index` takes the
* flag-level value, so it can lose its group targeting. The merge therefore restores these
* omitted fields from the stored flag (PostHog/posthog#46501).
*
* The read tools add a `condition_id` to each condition set (see conditionIds.ts). When the payload
* carries any condition_id, each set takes the stored set with the same ID as its source, at any
* position. A set without an ID is then new. The merge refuses an ID that matches no stored set.
* Such an ID usually means that the flag changed after the agent read it. A property whose key its
* source does not hold takes its type from every stored set that holds the key. This also applies
* on a flag whose stored sets aggregate on different group types. When that type does not fit the
* set's aggregation, the API rejects the write. The rules below that pair sets by position and by
* content apply only to a payload without IDs.
*
* An incoming condition set takes the stored set at its own index as its source when every stored
* set keeps its property keys at its index. New sets may only follow the stored ones. On a flag
* whose stored sets aggregate on different group types, nothing else tells a moved set from an
* edited one. The merge therefore refuses any other edit to such a flag, unless the payload changes
* the flag-level aggregation or each set without a source states, clears, or implies its own: it
* sends aggregation_group_type_index, carries an explicit person-aggregated property, or carries a
* group property with a group_type_index. A set loses its source on such a flag when another stored
* set on a different aggregation has the same keys and the incoming operators or values differ from
* the stored ones, because a swap of the two sets and an in-place edit of their filters send the
* same payload. On a flag whose sets all aggregate the same way, a set that keeps its keys at its
* index keeps its source even when other sets change.
*
* A group-aggregated set on an older flag can hold a group property on another group type than its
* own. A deletion or a swap can pair a set with the wrong stored set. On such a flag the pairing
* decides which group type that property keeps, and the set's group type when the agent echoes the
* property. The merge therefore refuses a payload without IDs on such a flag unless each set repeats
* the filters of the stored set at its index and no other stored set has the same filters. A payload
* with IDs can drop the ID of a stored set that holds such a property. The merge refuses each set
* without an ID that repeats the filters of such a stored set when no ID in the payload names that
* stored set. As a new set, it would move the property to its own group type.
*
* A set's aggregation then decides its property types. A group-aggregated set restores a
* person-aggregated type that its source holds for the key. A group-aggregated set with no source
* looks the key up in every stored set instead when the stored sets all aggregate the same way, or
* when the set states or implies its own group type. A group-aggregated set types a property as
* `group` against its own group type index when the stored filters it reads hold the key as a group
* property or hold no person-aggregated type for it. Otherwise the person-aggregated filters decide
* the type.
*
* A person-aggregated set can filter on a group property. The flag evaluator reads each property
* by its own type and group_type_index (see mixed_targeting_flag in
* rust/feature-flags/src/flags/test_flag_matching.rs). A person-aggregated set therefore restores
* `group` and the stored group_type_index from a source that is also stored as person-aggregated.
* From a group-aggregated source, or from another stored set, it restores only person-aggregated
* types. A set without a source can come from a stored set that holds the key as a group property.
* When one does, the set restores a person-aggregated type only from a stored filter with the same
* operator and value, and only when no group filter on the key also has them. Otherwise the property
* stays untyped. A group property in a group-aggregated set says nothing about a person set. An echo of a
* group property that a person-aggregated source holds does not move the set to group aggregation.
* On a flag whose stored sets all aggregate on persons, a set without a source compares its echo
* against every stored set instead. An appended set also has no source.
* check_property_types_match_aggregation in products/feature_flags/backend/filters_validation.py
* reports a group property in a person set, a person-aggregated property in a group set, and a group
* property on another group type than its set. The evaluator supports these shapes. The merge keeps
* them where the stored flag already has them.
*
* In either kind of set, the stored filters that decide a type narrow to the ones that match the
* incoming operator and value, then to the ones with its operator. When the rest hold more than one
* typing, the property stays untyped. The API then rejects the write. A person-aggregated set with a
* source reads other stored sets only when the source holds no filter on the key whose type it can
* restore.
*
* An incoming person-aggregated set can keep the filters of other person-aggregated sets with the
* same keys. The merge checks the incoming set's types against those sets only when the incoming set
* changes the filters, rollout, or variant of its source, or when the payload does not keep them at
* their own index, as after a deletion. A move
* from any of those sets and an in-place edit that copies their filters send the same payload. The
* edits can need different types, so the set restores a type only when typing the property from the
* source and from each of those sets gives the same type and group_type_index. It looks up no other
* stored set. A property that those stored sets type differently stays untyped, which makes the API
* reject the write. When the source or one of those sets has every typed group property of the
* incoming set on the same group type, those properties do not move the incoming set to group
* aggregation.
*
* `aggregation_group_type_index: null` means person aggregation. Only a missing key is
* filled from the existing flag.
*
* A condition set pinned to person aggregation never gains group aggregation. A set is
* pinned when it clears its own aggregation, when the payload changes the flag level to null, or
* when it carries an explicit property of any type except `group` without setting a group index
* itself.
*
* `super_groups` is ignored: the flags API drops it from writes
* (LEGACY_UNKNOWN_FILTER_KEYS in products/feature_flags/backend/api/filters_schema.py).
*/
import { isDeepStrictEqual } from 'node:util'
import { ToolInputValidationError } from '@/lib/errors'
import { canonicalJson, hasKey, isRecord } from '@/lib/plain-object'
import {
explicitlyClearsAggregation,
flagLevelGroupIndex,
isPresentGroupIndex,
resolveGroupIndex,
storedAggregation,
} from './aggregation'
import { conditionId } from './conditionIds'
export type FlagProperty = {
key?: string
type?: string | null
group_type_index?: number | null
operator?: string
value?: unknown
[key: string]: unknown
}
export type FlagConditionGroup = {
properties?: FlagProperty[] | null
rollout_percentage?: number | null
variant?: string | null
aggregation_group_type_index?: number | null
[key: string]: unknown
}
export type FlagFilters = {
groups?: FlagConditionGroup[] | null
super_groups?: FlagConditionGroup[] | null
aggregation_group_type_index?: number | null
multivariate?: unknown
payloads?: unknown
[key: string]: unknown
}
function isPresentType(type: unknown): type is string {
return typeof type === 'string' && type.length > 0
}
/**
* `!== 'group'` is the complement of PERSON_AGGREGATED_PROPERTY_TYPES in filters_validation.py.
* It holds only while 'group' is the sole type outside that tuple. A Python test asserts that:
* products/feature_flags/backend/test/test_filters_validation.py. The complement also accepts a
* stored type the backend tuples omit, such as `person_metadata`, which a hardcoded list drops.
*/
function isPersonAggregatedType(type: unknown): type is string {
return isPresentType(type) && type !== 'group'
}
function hasExplicitPersonProperty(group: FlagConditionGroup): boolean {
return Array.isArray(group.properties) && group.properties.some((p) => isPersonAggregatedType(p?.type))
}
/**
* A set that carries its own group index is never pinned, which matches the backend's per-set
* fallback in filters_validation.py. Any other set is pinned when it clears its own aggregation,
* when the payload changes the flag level to null, or when it carries an explicit person-aggregated
* property.
*/
function isPinnedToPerson(group: FlagConditionGroup, flagClearsAggregation: boolean): boolean {
return (
!isPresentGroupIndex(group.aggregation_group_type_index) &&
(hasKey(group, 'aggregation_group_type_index') || flagClearsAggregation || hasExplicitPersonProperty(group))
)
}
function indexProperties(properties: FlagProperty[] | null | undefined): Map<string, FlagProperty[]> {
const byKey = new Map<string, FlagProperty[]>()
if (!Array.isArray(properties)) {
return byKey
}
for (const prop of properties) {
if (!prop || typeof prop.key !== 'string' || prop.key.length === 0) {
continue
}
const list = byKey.get(prop.key) ?? []
list.push(prop)
byKey.set(prop.key, list)
}
return byKey
}
/** `aggregation` is null for a set that aggregates on persons. */
type ExistingSet = { group: FlagConditionGroup; propsByKey: Map<string, FlagProperty[]>; aggregation: number | null }
function indexExistingSets(
existing: FlagFilters | null | undefined,
flagLevel: number | undefined
): (ExistingSet | undefined)[] {
const groups = existing?.groups
if (!Array.isArray(groups)) {
return []
}
return groups.map((group) =>
isRecord(group)
? {
group,
propsByKey: indexProperties(group.properties),
aggregation: storedAggregation(group, flagLevel),
}
: undefined
)
}
function indexPropertiesAcrossSets(existingSets: (ExistingSet | undefined)[]): Map<string, FlagProperty[]> {
return indexProperties(
existingSets.flatMap((existingSet) =>
Array.isArray(existingSet?.group.properties) ? existingSet.group.properties : []
)
)
}
function hasSameKeySet(incoming: ReadonlyMap<string, unknown>, existing: ReadonlyMap<string, unknown>): boolean {
return incoming.size === existing.size && [...incoming.keys()].every((key) => existing.has(key))
}
/** The flag evaluator ignores the value of an existence filter. */
const EXISTENCE_OPERATORS = new Set(['is_set', 'is_not_set'])
/** The flag evaluator reads a missing operator as `exact`. */
function evaluatedOperator(prop: FlagProperty): string {
return prop.operator ?? 'exact'
}
/**
* matchesFilter compares the same operator and value without building the pair. A filter that
* matches another therefore always shares its signature.
*/
function evaluatedFilter(prop: FlagProperty): [operator: string, value: unknown] {
const operator = evaluatedOperator(prop)
return [operator, EXISTENCE_OPERATORS.has(operator) ? null : prop.value]
}
function matchesFilter(stored: FlagProperty, incoming: FlagProperty): boolean {
const operator = evaluatedOperator(stored)
return (
operator === evaluatedOperator(incoming) &&
(EXISTENCE_OPERATORS.has(operator) || isDeepStrictEqual(stored.value, incoming.value))
)
}
/** A type or group_type_index that the agent sends and that differs from the stored filter is a change. */
function keepsExplicitTyping(stored: FlagProperty, incoming: FlagProperty): boolean {
return (
matchesFilter(stored, incoming) &&
(!isPresentType(incoming.type) || incoming.type === stored.type) &&
(!isPresentGroupIndex(incoming.group_type_index) || incoming.group_type_index === stored.group_type_index)
)
}
/**
* The filters under each key compare as a multiset of operator and value pairs, so a removed, added,
* or changed filter on a key is a change.
*/
function keepsFilters(
incoming: FlagConditionGroup,
source: ExistingSet,
matches: (stored: FlagProperty, incoming: FlagProperty) => boolean = matchesFilter
): boolean {
const incomingByKey = indexProperties(incoming.properties)
return (
hasSameKeySet(incomingByKey, source.propsByKey) &&
[...incomingByKey].every(([key, props]) => {
const unmatched = [...(source.propsByKey.get(key) ?? [])]
return (
props.length === unmatched.length &&
props.every((prop) => {
const match = unmatched.findIndex((stored) => matches(stored, prop))
if (match === -1) {
return false
}
unmatched.splice(match, 1)
return true
})
)
})
)
}
/** The values the flag evaluator reads for a missing or null field. */
const CONDITION_DEFAULTS = { rollout_percentage: 100, variant: null } as const
/**
* An omitted field compares as the value the flag evaluator reads for it. The API replaces each
* condition set whole. It does not keep the stored value of a field that the agent leaves out.
*/
function keepsCondition(incoming: FlagConditionGroup, source: ExistingSet): boolean {
return (
keepsFilters(incoming, source, keepsExplicitTyping) &&
Object.entries(CONDITION_DEFAULTS).every(([field, fallback]) =>
isDeepStrictEqual(incoming[field] ?? fallback, source.group[field] ?? fallback)
)
)
}
/** Sets that keepsFilters treats as having the same filters on the same keys share this signature. */
function filterSignature(propsByKey: Map<string, FlagProperty[]>): string {
return JSON.stringify(
[...propsByKey.values()]
.flat()
.map((prop) => canonicalJson([prop.key, ...evaluatedFilter(prop)]))
.sort()
)
}
/** Sets with this signature in common type every property the same way and hold the same group properties. */
function typingSignature(propsByKey: Map<string, FlagProperty[]>): string {
return JSON.stringify(
[...propsByKey.entries()]
.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
.map(([key, props]) => [
key,
props.map((prop) => [
prop.operator ?? null,
canonicalJson(prop.value),
prop.type ?? null,
prop.group_type_index ?? null,
]),
])
)
}
/** `set` stands for every stored person set in `indexes`. */
type SameTypingSets = { set: ExistingSet; indexes: number[] }
/** A changed set compares against one stored set per typing instead of against every stored set. */
function groupPersonSetsByFilters(existingSets: (ExistingSet | undefined)[]): Map<string, SameTypingSets[]> {
const byFilters = new Map<string, Map<string, SameTypingSets>>()
existingSets.forEach((existingSet, index) => {
if (!existingSet || existingSet.aggregation !== null) {
return
}
const filters = filterSignature(existingSet.propsByKey)
const byTyping = byFilters.get(filters) ?? new Map<string, SameTypingSets>()
byFilters.set(filters, byTyping)
const typing = typingSignature(existingSet.propsByKey)
const sameTyping = byTyping.get(typing)
if (sameTyping) {
sameTyping.indexes.push(index)
} else {
byTyping.set(typing, { set: existingSet, indexes: [index] })
}
})
return new Map([...byFilters].map(([filters, byTyping]) => [filters, [...byTyping.values()]]))
}
/** A person-aggregated set does not count. The person-set rules in the module doc decide its group properties. */
function holdsCrossGroupProperty(existingSet: ExistingSet): boolean {
return (
existingSet.aggregation !== null &&
[...existingSet.propsByKey.values()]
.flat()
.some(
(prop) =>
prop.type === 'group' &&
isPresentGroupIndex(prop.group_type_index) &&
prop.group_type_index !== existingSet.aggregation
)
)
}
function keepsKeys(incoming: FlagConditionGroup | undefined, existingSet: ExistingSet | undefined): boolean {
const incomingKeys = isRecord(incoming) ? indexProperties(incoming.properties) : new Map()
return hasSameKeySet(incomingKeys, existingSet?.propsByKey ?? new Map())
}
function usableCandidates(
candidates: FlagProperty[] | undefined,
usableType: (type: unknown) => boolean
): FlagProperty[] {
return (candidates ?? []).filter((candidate) => usableType(candidate.type))
}
function hasSameTypeAndGroupIndex(a: FlagProperty, b: FlagProperty): boolean {
return a.type === b.type && (a.group_type_index ?? null) === (b.group_type_index ?? null)
}
function restoredTyping(stored: FlagProperty, incoming: FlagProperty): FlagProperty {
return stored.type === 'group' && !isPresentGroupIndex(incoming.group_type_index)
? { type: stored.type, group_type_index: stored.group_type_index }
: { type: stored.type }
}
/** Returning undefined when the typings disagree keeps the result independent of the order of the stored filters. */
function pickTyping(usable: FlagProperty[], incoming: FlagProperty): FlagProperty | undefined {
const operator = evaluatedOperator(incoming)
const matching = usable.filter((candidate) => matchesFilter(candidate, incoming))
const sameOperator = usable.filter((candidate) => evaluatedOperator(candidate) === operator)
const remaining = [matching, sameOperator, usable].find((tier) => tier.length > 0) ?? []
const [first, ...rest] = remaining.map((candidate) => restoredTyping(candidate, incoming))
return first && rest.every((typing) => hasSameTypeAndGroupIndex(typing, first)) ? first : undefined
}
function unambiguousPersonCandidates(
candidates: FlagProperty[] | undefined,
incoming: FlagProperty
): FlagProperty[] | undefined {
if (!candidates?.some((candidate) => candidate.type === 'group')) {
return candidates
}
const matching = candidates.filter((candidate) => matchesFilter(candidate, incoming))
return matching.some((candidate) => candidate.type === 'group') ? [] : matching
}
/**
* A group property follows its set's group type, so a retarget moves it with the set. That holds for a
* property with no index, which the evaluator reads on its set's group type, and for a property on the
* group type its source aggregates on. Older flags can also hold a group property on another group type
* than its set. The evaluator reads the property's own group type, so moving such a property would
* change which group the filter reads. The property therefore keeps that index. A person-aggregated
* source aggregates on no group type, so every group property with an index in it keeps that index.
* Undefined means the stored filters on the key disagree and the agent sent no index. The caller then
* returns the property as the agent sent it, because the API rejects an untyped property whatever
* FEATURE_FLAG_FILTERS_ENFORCED_RULES holds. A typed group property without an index saves while that
* setting leaves out `group_property_type_index_mismatch`, and the evaluator then reads it on the
* set's group type.
*/
function groupTypeIndexFor(
prop: FlagProperty,
candidates: FlagProperty[] | undefined,
sourceAggregation: ExistingSet['aggregation'] | undefined,
setGroupTypeIndex: number
): number | undefined {
const mergedIndex = (index: number | null | undefined): number =>
sourceAggregation !== undefined && isPresentGroupIndex(index) && index !== sourceAggregation
? index
: setGroupTypeIndex
if (isPresentGroupIndex(prop.group_type_index)) {
return mergedIndex(prop.group_type_index)
}
const storedGroupFilters = usableCandidates(candidates, (type) => type === 'group').map((stored) => ({
...stored,
group_type_index: mergedIndex(stored.group_type_index),
}))
if (storedGroupFilters.length === 0) {
return setGroupTypeIndex
}
return pickTyping(storedGroupFilters, prop)?.group_type_index ?? undefined
}
/** `sourceAggregation` is undefined when no source holds the key. */
function mergeProperty(
incoming: FlagProperty,
candidates: FlagProperty[] | undefined,
otherCandidates: FlagProperty[] | undefined,
setGroupTypeIndex: number | undefined,
sourceAggregation: ExistingSet['aggregation'] | undefined
): FlagProperty {
const out: FlagProperty = { ...incoming }
if (!isPresentType(out.type)) {
if (isPresentGroupIndex(setGroupTypeIndex)) {
const personTyped = usableCandidates(candidates, isPersonAggregatedType)
// Candidates that also hold the key as a group property leave the type ambiguous.
const restoredType =
candidates?.some((candidate) => candidate.type === 'group') || personTyped.length === 0
? 'group'
: pickTyping(personTyped, out)?.type
if (restoredType) {
out.type = restoredType
}
} else {
// A person-aggregated source restores the group property it filters on, index
// included. Any other candidate restores only a person-aggregated type, because
// restoring `group` from it would name fields the agent never sent. Leaving the type
// unset then makes the API report the property the agent actually sent.
const hasSource = sourceAggregation !== undefined
const fromSource = hasSource
? usableCandidates(candidates, sourceAggregation === null ? isPresentType : isPersonAggregatedType)
: []
const others = hasSource ? otherCandidates : unambiguousPersonCandidates(otherCandidates, out)
const usable = fromSource.length > 0 ? fromSource : usableCandidates(others, isPersonAggregatedType)
const typing = pickTyping(usable, out)
if (typing) {
Object.assign(out, typing)
}
}
}
if (out.type === 'group' && isPresentGroupIndex(setGroupTypeIndex)) {
const groupTypeIndex = groupTypeIndexFor(out, candidates, sourceAggregation, setGroupTypeIndex)
if (groupTypeIndex === undefined) {
return incoming
}
out.group_type_index = groupTypeIndex
}
return out
}
type MergeConditionOptions = {
/** The payload changes the flag-level aggregation, which decides every set that sends none. */
payloadChangesFlagAggregation: boolean
/** This set never gains group aggregation. See isPinnedToPerson. */
pinnedToPerson: boolean
/** Property maps of the stored sets that this set may come from. */
storedSetProps: (Map<string, FlagProperty[]> | undefined)[]
}
function holdsGroupProperty(propsByKey: Map<string, FlagProperty[]> | undefined, prop: FlagProperty): boolean {
return (
typeof prop.key === 'string' &&
!!propsByKey
?.get(prop.key)
?.some((stored) => stored.type === 'group' && stored.group_type_index === prop.group_type_index)
)
}
function explicitGroupPropertyIndex(
group: FlagConditionGroup,
storedSetProps: (Map<string, FlagProperty[]> | undefined)[]
): number | undefined {
const properties = Array.isArray(group.properties) ? group.properties : []
const typed = properties.filter(
(prop): prop is FlagProperty & { group_type_index: number } =>
prop?.type === 'group' && isPresentGroupIndex(prop.group_type_index)
)
if (storedSetProps.some((propsByKey) => typed.every((prop) => holdsGroupProperty(propsByKey, prop)))) {
return undefined
}
const unique = [...new Set(typed.map((prop) => prop.group_type_index))]
return unique.length === 1 ? unique[0] : undefined
}
function resolveSetAggregation(
incoming: FlagConditionGroup,
sourceSet: ExistingSet | undefined,
options: MergeConditionOptions
): FlagConditionGroup {
const out: FlagConditionGroup = { ...incoming }
// One explicit property of a person-aggregated type stops this set from keeping or
// gaining group targeting. An explicit incoming group index still wins. The API then
// reports the contradiction in the agent's own payload.
if (hasExplicitPersonProperty(incoming) && !isPresentGroupIndex(out.aggregation_group_type_index)) {
out.aggregation_group_type_index = null
}
const { pinnedToPerson, payloadChangesFlagAggregation, storedSetProps } = options
// Fill only when the key is absent. An explicit null means person aggregation. A payload
// that changes the flag level already decides this set, the same way the API distributes
// the flag level into every set that sends no index of its own. A group property that the
// agent typed with an index names the group type of its own set. A retarget that the agent
// sends only on the property therefore survives. A set whose typed group properties all
// repeat ones that a single map in storedSetProps holds names no group type, because they echo
// stored filters. A person-aggregated set filters on such properties without aggregating on
// their group type. A group-aggregated source can hold them on another group type than its own.
if (!pinnedToPerson && !payloadChangesFlagAggregation && !hasKey(out, 'aggregation_group_type_index')) {
const restored =
explicitGroupPropertyIndex(incoming, storedSetProps) ?? sourceSet?.group.aggregation_group_type_index
if (isPresentGroupIndex(restored)) {
out.aggregation_group_type_index = restored
}
}
return out
}
function typeSetProperties(
group: FlagConditionGroup,
sourceSet: ExistingSet | undefined,
fallbackCandidatesByKey: Map<string, FlagProperty[]> | undefined,
crossSetPropsByKey: Map<string, FlagProperty[]>,
setGroupTypeIndex: number | undefined,
matchedSets: ExistingSet[]
): FlagConditionGroup {
const out: FlagConditionGroup = { ...group }
if (Array.isArray(out.properties)) {
out.properties = out.properties.map((prop) => {
if (!prop || typeof prop !== 'object') {
return prop
}
const key = prop.key
if (typeof key !== 'string') {
return prop
}
const candidates = sourceSet?.propsByKey.get(key)
if (matchedSets.length === 0) {
// A key the source does not hold takes its type from every stored set, even on a mixed flag.
const sourceHoldsKey = candidates !== undefined
return mergeProperty(
prop,
sourceHoldsKey ? candidates : fallbackCandidatesByKey?.get(key),
crossSetPropsByKey.get(key),
setGroupTypeIndex,
sourceHoldsKey ? sourceSet?.aggregation : undefined
)
}
// The set either moved from one of the matched sets or copies its filters in place. Each
// reading types the property from a different person set. Only a type that every reading
// gives is safe.
const fromSource = mergeProperty(prop, candidates, undefined, setGroupTypeIndex, sourceSet?.aggregation)
const allAgree = matchedSets.every((matched) => {
const fromMatched = mergeProperty(
prop,
matched.propsByKey.get(key),
undefined,
setGroupTypeIndex,
matched.aggregation
)
return hasSameTypeAndGroupIndex(fromMatched, fromSource)
})
return allAgree ? fromSource : prop
})
}
return out
}
function groupPaths(indexes: number[]): string {
return indexes.map((index) => `filters.groups[${index}]`).join(', ')
}
function unresolvedAggregationMessage(unresolved: number[]): string {
const paths = groupPaths(unresolved)
return (
"This flag's release conditions don't all target the same thing: some target persons and others a " +
'group type, or they target different group types. This update adds, removes, or reorders conditions, ' +
"or changes the properties they filter on, so the tool can't tell which target each condition should keep. " +
`Set aggregation_group_type_index on each of these conditions: ${paths}. ` +
'Use a group type index to target that group type, or null to target persons. Alternatively, send the ' +
'condition_id from the read on each condition that came from the flag, and set ' +
'aggregation_group_type_index only on new conditions. Then send the update again.'
)
}
function staleConditionIdMessage(stale: number[]): string {
const paths = groupPaths(stale)
return (
`The condition_id on ${paths} matches no condition on the flag. ` +
'A condition_id only matches conditions on the flag you read it from. If you copied this condition ' +
'from a different flag, remove its condition_id and send it as a new condition. ' +
'Otherwise the flag may have changed after you read it. Read the flag again, then build the update ' +
'from its current conditions and their condition_id values.'
)
}
function crossGroupPropertyMessage(unpaired: number[]): string {
const paths = groupPaths(unpaired)
return (
"At least one of this flag's conditions filters on a group property of a group type that the condition " +
"doesn't target. The flag checks each such property on the property's own group type. This update " +
"changes, adds, removes, or reorders conditions without condition_id, so the tool can't tell which " +
`stored condition these come from: ${paths}. It needs that to keep each property on its group type. ` +
'Read the flag with feature-flag-get-definition or feature-flag-get-definition-by-key to get each ' +
"condition's condition_id. Send it on each condition that came from the flag, and leave it off new " +
'conditions. Then send the update again.'
)
}
function sourcesByConditionId(
incomingGroups: FlagConditionGroup[],
conditionIds: (string | undefined)[],
existingSets: (ExistingSet | undefined)[],
existingFlagGroupIndex: number | undefined
): (ExistingSet | undefined)[] {
const storedById = new Map<string, ExistingSet>()
for (const existingSet of existingSets) {
if (!existingSet) {
continue
}
const id = conditionId(existingSet.group, existingFlagGroupIndex)
if (!storedById.has(id)) {
storedById.set(id, existingSet)
}
}
const stale = conditionIds.flatMap((id, index) => (id !== undefined && !storedById.has(id) ? [index] : []))
if (stale.length > 0) {
throw new ToolInputValidationError(staleConditionIdMessage(stale), {
fields: ['filters.groups.N.condition_id:stale_condition_id'],
})
}
const sentIds = new Set(conditionIds)
const unnamedCrossGroupSets = [...storedById].flatMap(([id, existingSet]) =>
!sentIds.has(id) && holdsCrossGroupProperty(existingSet) ? [existingSet] : []
)
const lostIds = incomingGroups.flatMap((group, index) =>
isRecord(group) &&
conditionIds[index] === undefined &&
unnamedCrossGroupSets.some((existingSet) => keepsFilters(group, existingSet))
? [index]
: []
)
if (lostIds.length > 0) {
throw new ToolInputValidationError(crossGroupPropertyMessage(lostIds), {
fields: ['filters.groups.N.condition_id:cross_group_property'],
})
}
return conditionIds.map((id) => (id === undefined ? undefined : storedById.get(id)))
}
type SetSources = { sourceSets: (ExistingSet | undefined)[]; matchedPersonSets: ExistingSet[][] }
function matchSetsByPositionAndContent(
incomingGroups: FlagConditionGroup[],
existingSets: (ExistingSet | undefined)[],
mixedAggregation: boolean
): SetSources {
const keptKeys = existingSets.map((existingSet, index) => keepsKeys(incomingGroups[index], existingSet))
// On a single-aggregation flag a positional source cannot carry the wrong aggregation.
const positionHolds = !mixedAggregation || (incomingGroups.length >= existingSets.length && keptKeys.every(Boolean))
const sourceSets = incomingGroups.map((group, index) => {
const existingSet = existingSets[index]
const ambiguous =
mixedAggregation &&
!!existingSet &&
isRecord(group) &&
existingSets.some(
(other) =>
!!other &&
other.aggregation !== existingSet.aggregation &&
hasSameKeySet(other.propsByKey, existingSet.propsByKey)
) &&
!keepsFilters(group, existingSet)
return positionHolds && keptKeys[index] && !ambiguous ? existingSet : undefined
})
const keptConditions = existingSets.map((existingSet, index) => {
const group = incomingGroups[index]
return !!existingSet && isRecord(group) && keepsCondition(group, existingSet)
})
const personSetsByFilters = groupPersonSetsByFilters(existingSets)
const changedTypings = new Set(
[...personSetsByFilters.values()]
.flat()
.filter((sameTyping) => sameTyping.indexes.some((otherIndex) => !keptConditions[otherIndex]))
)
const matchedPersonSets = sourceSets.map((sourceSet, index) => {
const group = incomingGroups[index]
if (sourceSet?.aggregation !== null || !isRecord(group)) {
return []
}
return (personSetsByFilters.get(filterSignature(indexProperties(group.properties))) ?? [])
.filter(
(sameTyping) =>
sameTyping.indexes.some((otherIndex) => otherIndex !== index) &&
keepsFilters(group, sameTyping.set) &&
(!keptConditions[index] || changedTypings.has(sameTyping))
)
.map((sameTyping) => sameTyping.set)
})
if (existingSets.some((existingSet) => existingSet && holdsCrossGroupProperty(existingSet))) {
const signatures = existingSets.map((existingSet) => existingSet && filterSignature(existingSet.propsByKey))
const unpaired = incomingGroups.flatMap((group, index) => {
const sourceSet = sourceSets[index]
const paired =
!isRecord(group) ||
(!!sourceSet &&
signatures.filter((signature) => signature === signatures[index]).length === 1 &&
keepsFilters(group, sourceSet))
return paired ? [] : [index]
})
if (unpaired.length > 0) {
throw new ToolInputValidationError(crossGroupPropertyMessage(unpaired), {
fields: ['filters.groups.N.condition_id:cross_group_property'],
})
}
}
return { sourceSets, matchedPersonSets }
}
/**
* Merge incoming MCP filters with the flag's current filters. Explicitly set incoming
* values always win, `null` included, and only missing `type`, `group_type_index`, and
* `aggregation_group_type_index` keys are filled from the existing flag. The one exception
* is a group property's `group_type_index`, which follows the index its own condition set
* aggregates on, so a retarget moves the property with its set. A property whose sent or stored
* index names a group type other than the one its source aggregates on keeps that index (see
* groupTypeIndexFor). The API reports that contradiction as `group_property_type_index_mismatch`.
*/
export function preserveGroupTargetingFilters(
existing: FlagFilters | null | undefined,
incoming: FlagFilters | null | undefined
): FlagFilters | null | undefined {
if (!incoming || typeof incoming !== 'object') {
return incoming
}
const result: FlagFilters = { ...incoming }
const existingFlagGroupIndex = flagLevelGroupIndex(existing)
// An echo of the stored flag level decides nothing new. validate_filters in
// products/feature_flags/backend/api/feature_flag.py re-derives the stored flag level from the
// condition sets on every write. It sets the flag level to null when the sets disagree. A
// stored numeric flag level therefore equals the aggregation of every set the merge restores.
const payloadChangesFlagAggregation =
hasKey(incoming, 'aggregation_group_type_index') &&
incoming.aggregation_group_type_index !== existing?.aggregation_group_type_index
const incomingClearsAggregation = payloadChangesFlagAggregation && explicitlyClearsAggregation(incoming)
// The flag-level index is the UI's "Target by" group type.
if (!payloadChangesFlagAggregation && isPresentGroupIndex(existingFlagGroupIndex)) {
result.aggregation_group_type_index = existingFlagGroupIndex
}
const effectiveFlagGroupIndex = resolveGroupIndex(
incomingClearsAggregation,
result.aggregation_group_type_index,
existingFlagGroupIndex
)
if (Array.isArray(result.groups)) {
const existingSets = indexExistingSets(existing, existingFlagGroupIndex)
const crossSetPropsByKey = indexPropertiesAcrossSets(existingSets)
const conditionIds = result.groups.map((group) =>
isRecord(group) && typeof group.condition_id === 'string' ? group.condition_id : undefined
)
result.groups = result.groups.map((group) => {
if (!isRecord(group)) {
return group
}
const { condition_id: _conditionId, ...rest } = group
return rest
})
const carriesConditionIds = conditionIds.some((id) => id !== undefined)
const pinnedToPerson = result.groups.map(
(group) => isRecord(group) && isPinnedToPerson(group, incomingClearsAggregation)
)
const aggregations = existingSets.map((existingSet) => existingSet?.aggregation)
const storedAggregations = new Set(aggregations.filter((aggregation) => aggregation !== undefined))
const mixedAggregation = storedAggregations.size > 1
const aggregatesOnPersonsOnly = storedAggregations.size === 1 && storedAggregations.has(null)
const { sourceSets, matchedPersonSets }: SetSources = carriesConditionIds
? {
sourceSets: sourcesByConditionId(result.groups, conditionIds, existingSets, existingFlagGroupIndex),
matchedPersonSets: [],
}
: matchSetsByPositionAndContent(result.groups, existingSets, mixedAggregation)
const storedSetPropsFor = (index: number): (Map<string, FlagProperty[]> | undefined)[] =>
sourceSets[index]
? [sourceSets[index], ...(matchedPersonSets[index] ?? [])].map((storedSet) => storedSet?.propsByKey)
: [aggregatesOnPersonsOnly ? crossSetPropsByKey : undefined]
const resolvedGroups = result.groups.map((group, index) =>
isRecord(group)
? resolveSetAggregation(group, sourceSets[index], {
payloadChangesFlagAggregation,
pinnedToPerson: pinnedToPerson[index] ?? false,
storedSetProps: storedSetPropsFor(index),
})
: group
)
const statesOwnGroupType = resolvedGroups.map(
(group) => isRecord(group) && isPresentGroupIndex(group.aggregation_group_type_index)
)
if (mixedAggregation && !payloadChangesFlagAggregation) {
const unresolved = resolvedGroups.flatMap((group, index) =>
isRecord(group) && !sourceSets[index] && !pinnedToPerson[index] && !statesOwnGroupType[index]
? [index]
: []
)
if (unresolved.length > 0) {
throw new ToolInputValidationError(unresolvedAggregationMessage(unresolved), {
fields: ['filters.groups.N.aggregation_group_type_index:unresolved_aggregation'],
})
}
}
result.groups = resolvedGroups.map((group, index) => {
if (!isRecord(group)) {
return group
}
const fallbackCandidatesByKey =
!mixedAggregation || statesOwnGroupType[index] || sourceSets[index] ? crossSetPropsByKey : undefined
return typeSetProperties(
group,
sourceSets[index],
fallbackCandidatesByKey,
crossSetPropsByKey,
resolveGroupIndex(
pinnedToPerson[index] ?? false,
group.aggregation_group_type_index,
effectiveFlagGroupIndex
),
matchedPersonSets[index] ?? []
)
})
}
return result
}