: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
import { DateTime } from 'luxon'
import { PersonMessage } from '~/common/persons/person-message'
import { PersonRepositoryTransaction } from '~/common/persons/repositories/person-repository-transaction'
import { CreatePersonResult } from '~/common/utils/db/db'
import { BatchWritingStore } from '~/ingestion/common/stores/batch-writing-store'
import { Properties } from '~/plugin-scaffold'
import { InternalPerson, PropertiesLastOperation, PropertiesLastUpdatedAt } from '~/types'
import { MergeMode } from './person-merge-types'
import { EventOps } from './person-update'
export type FlushResult = {
messages: PersonMessage[]
teamId: number
distinctId?: string
uuid?: string
}
/** One source distinct id to merge into the target, with the event that asked for it. */
export interface MergePersonsSource {
distinctId: string
eventUuid: string
}
/**
* Per-source merge verdicts. Both backends share the vocabulary;
* 'skipped_race' and 'failed_*' come only from Postgres, 'error' in
* practice only from the saga.
*/
export type MergePersonsOutcome =
| 'merged'
| 'noop_same_person'
| 'attached'
| 'skipped_illegal'
| 'skipped_already_identified'
| 'skipped_conflict'
| 'skipped_move_limit'
/**
* Definitively refused before destroying anything; the recorded
* verdict replays on every retry, so the pair settles as a lost merge.
*/
| 'skipped_refused'
| 'skipped_race'
| 'failed_source_not_found'
| 'failed_target_not_found'
| 'failed_source_has_distinct_ids'
| 'error'
/**
* A verdict this build cannot name, from a backend running ahead;
* distinct from 'error' because the merge may well have happened.
*/
| 'unknown'
export interface MergePersonsSourceResult {
sourceDistinctId: string
outcome: MergePersonsOutcome
/**
* The backend's durability statement: false means a retry under the
* same op id may change the answer. Personhog only; absent is settled.
*/
settled?: boolean
/** The source person the verdict speaks about. Postgres only; the saga reports ids. */
sourcePersonUuid?: string
/**
* The source person this verdict destroyed, present only on a merged
* source. Merging away is permanent, so a caller may reconcile cached
* state against it without re-reading, including entries cached under
* distinct ids the request never named. Absent or null on every other
* verdict.
*/
sourcePersonId?: string | null
}
export interface MergePersonsRequest {
teamId: number
targetDistinctId: string
/**
* Ordered; earlier sources beat later ones on property precedence,
* the target beats all. More than one source only from a fold plan.
*/
sources: MergePersonsSource[]
/**
* The source belonging to the event that initiated this request; not
* always the first source, because a fold plan's first event can be
* dropped before the person step. When a folded merge finds no target
* person, the Postgres merge bootstraps this source first.
*/
triggerSourceDistinctId?: string
/** The merge event's property ops; each backend applies them to the survivor its own way. */
eventOps: EventOps
/**
* The merge-triggering event's uuid, the idempotency root: backends
* derive their durable op ids from it, so a repeated delivery of the
* same event must present the same value and cannot merge twice.
*/
eventUuid: string
/** $merge_dangerously legally merges already-identified sources; $identify does not. */
allowIdentifiedSources: boolean
/**
* The caller's move policy, from the same config the processor's
* over-limit handling reads; both backends bound their moves by it.
*/
mergeMode: MergeMode
/**
* Merge event created_at, epoch millis; consulted only where a person
* is born from the request. Otherwise the survivor keeps the earliest
* created_at among the merged persons.
*/
createdAtMs: number
}
/** The trigger id marks a fold request, so a single-pair fold counts as one too. */
export function isFoldRequest(request: MergePersonsRequest): boolean {
return request.sources.length > 1 || request.triggerSourceDistinctId !== undefined
}
export type MergeFoldAbortReason = 'limit' | 'conflict' | 'refused' | 'deadlock' | 'error'
export interface MergePersonsResult {
/** The surviving person; null when the merge settled without one. */
survivor: InternalPerson | null
results: MergePersonsSourceResult[]
/** Post-commit ClickHouse production the caller may chain on; absent when the backend produced before returning. */
kafkaAck?: Promise<void>
/**
* Whether the caller still needs its follow-up property update; absent
* means true. Postgres reports false when its own creation applied the
* event's properties; personhog never claims it.
*/
survivorNeedsUpdate?: boolean
/**
* Multi-source only: the folded transaction rolled back and the caller
* falls back to per-event merges. Not always untouched — a bootstrap
* creation can commit before the fold begins, and its `kafkaAck` travels
* on this result for the caller to await.
*/
foldAborted?: MergeFoldAbortReason
}
/** Which person-storage backend a store writes to. Labels metrics whose causes differ between them. */
export type PersonsBackend = 'postgres' | 'personhog'
export interface PersonsStore extends BatchWritingStore<FlushResult> {
readonly backend: PersonsBackend
/** Existence-class read; replica-backed where the backend has one. */
fetchForChecking(teamId: number, distinctId: string, batchId: number): Promise<InternalPerson | null>
/** Update-class read from the authoritative side; its answer feeds writes. */
fetchForUpdate(teamId: number, distinctId: string, batchId: number): Promise<InternalPerson | null>
createPerson(
createdAt: DateTime,
properties: Properties,
propertiesLastUpdatedAt: PropertiesLastUpdatedAt,
propertiesLastOperation: PropertiesLastOperation,
teamId: number,
isUserId: number | null,
isIdentified: boolean,
uuid: string,
primaryDistinctId: { distinctId: string; version?: number },
extraDistinctIds: { distinctId: string; version?: number }[] | undefined,
tx: PersonRepositoryTransaction | undefined,
batchId: number
): Promise<CreatePersonResult>
/**
* Applies one event's extracted ops to a person, resolving what they
* mean against this store's own state.
*/
applyEventOps(
person: InternalPerson,
ops: EventOps,
distinctId: string,
batchId: number
): Promise<[InternalPerson, PersonMessage[]]>
/**
* Updates person for regular updates with specific properties to set and unset
*/
updatePersonWithPropertiesDiffForUpdate(
person: InternalPerson,
propertiesToSet: Properties,
propertiesToUnset: string[],
otherUpdates: Partial<InternalPerson>,
distinctId: string,
batchId: number,
forceUpdate?: boolean,
tx?: PersonRepositoryTransaction
): Promise<[InternalPerson, PersonMessage[], boolean]>
/**
* Merge the sources into the target through this backend's own merge
* machinery (the identity service's saga, or the PostgresPersonMerge
* the Postgres store runs internally). Settled verdicts come back as
* per-source outcomes; retryable Postgres conflicts throw for the
* caller's retry loop.
*/
mergePersons(request: MergePersonsRequest, batchId: number): Promise<MergePersonsResult>
personPropertiesSize(personId: string, teamId: number): Promise<number>
/**
* Stop any background work (e.g., periodic metric emission) and flush
* remaining accumulated metrics. Called on graceful shutdown. Does NOT
* clear data caches.
*/
shutdown(): Promise<void>
/**
* Best-effort cache warmer. Entries carry their own batchIds so one
* fetch can serve concurrent batches' eviction tracking.
*/
prefetchPersons(teamDistinctIds: { teamId: number; distinctId: string; batchId: number }[]): Promise<void>
/**
* Flushes the batch
*/
flush(): Promise<FlushResult[]>
/**
* Releases cache entries associated with the given batch ID, using reference
* counting so entries shared across concurrent batches are only evicted when
* all referencing batches have completed.
*/
releaseBatch(batchId: number): void
}