Skip to content
bucker

Payload semantics: PostHog and Segment on the product-event model

Re-pointing an existing SDK is the migration path, so Bucker reads the payloads PostHog and Segment SDKs send. The wire endpoints are SDK-20's; this page is what the payloads MEAN (PA-30). Everything maps onto the product-event item (PA-03, product-events.md) and the subject operations of PA-04 (identify once, alias as repair, no merge).

Tested against posthog-js >= 1.200.0 and <= 1.438.13 (shipped 2026-10-20) and the Segment Spec (identify, track, page, screen, group, alias; Analytics.js 2.0 and @segment/analytics-node 2.x). A change to either is a change to the fixtures in api/test/ingest/payload-semantics.test.ts first.

How a call is handled

  1. mapPostHog(body) or mapSegment(body) (pure) read the parsed JSON and return the items, the subject operations and one outcome per semantic met.
  2. applyPayloadSemantics is the write path. It checks the per-project product-analytics gate (PA-01) first. While the DPA amendment is unpublished (ANALYTICS_DPA_VERSION is null) or the project has not enabled analytics, it refuses with 422 analytics_not_enabled (cause dpa_amendment_pending and so on) and stores nothing: no alias, no account, no count.
  3. Behind an open gate it performs the operations the door cannot express and counts every outcome, then returns the items. The caller puts them in a product_event envelope; the door judges each again (reserved names, caps, consent basis, dedupe, hot keys) and resolves the subject.

Identifiers are pseudonymised with the F-04 keyed pseudonym: the door hashes distinct_id, anon_id and device_id (purposes subject, anon, device); an alias hashes both ids; a group key is hashed under purpose account together with its type. Nothing the module counts or stores carries a raw id.

Dispositions

Disposition Meaning
honoured Accepted with the meaning it has at the source.
mapped Accepted in Bucker's shape; the table says what it becomes.
ignored Accepted, no effect. Counted.
refused Counted, nothing stored for it. A refusal is never silent.

Every outcome is counted per source in product_event_warnings: kinds semantics_honoured, semantics_mapped, semantics_ignored and refused_semantics, event name <source>:<semantic>. The names are the closed set below, so the per-kind cap of 50 names is never reached.

Decisions worth knowing

  • Merging is human-only. $merge_dangerously is refused. An alias is one hop and never joins two identified subjects (alias_refused); the way to link an anonymous visitor to a user is identify.
  • Anonymous versus identified. posthog-js sends $is_identified. false keeps the id an anonymous subject; absent (server SDKs) or true is an identified distinct id. An $identify carries the new id and $anon_distinct_id, and the door links the anonymous subject once.
  • Personless. $process_person_profile: false and the $posthog_cookieless sentinel store the event with no subject and no property write.
  • URLs. $current_url is reduced to $host and $pathname; the query string is not stored (it can carry identifiers). The same holds for every other URL an SDK sends: any $ property holding an http(s) URL ($session_entry_url, $initial_current_url and $initial_referrer in $set_once, and the rest), and Segment's url and referrer properties, keep scheme, host and path only; Segment's search is read for UTM values and never stored. UTM values are kept as $utm_*.
  • Segment page properties. A page or screen call keeps the customer's own properties (category and the rest); the Spec's page fields (url, path, referrer, search, title, name) become the derived ones.
  • Groups. PostHog $groups and Segment group map onto account types (PA-16). The type must be a live account type of the project; Segment's group lands on the type named by the caller (default group).
  • Re-sends. A PostHog uuid and a Segment messageId become the item uuid, so a re-send is a duplicate for 48 hours. Without one the server mints a uuid and a re-send is stored again.
  • Not adopted. Autocapture ($autocapture), recording ($snapshot), errors ($exception; use the error envelope) and Hog transformations.

Fidelity table

Generated from FIDELITY_TABLE in domain/src/modules/ingest/payload-semantics.ts; the suite fails if a row here and a row there differ, or if a row is never produced by a fixture.

posthog

Semantic Disposition Becomes Note
capture honoured product event, same name A customer event name (no $ prefix).
uuid honoured item uuid Used as sent; the door dedupes it for 48 hours.
sent_at mapped sent_at skew correction Returned as sentAt for the envelope; the door corrects event time with it.
historical_migration mapped import mode Returned as historical: true for the envelope header.
api_key ignored - Authentication is the DSN key; the value is never read or stored.
$identify mapped $identify item with distinct_id and anon_id $anon_distinct_id becomes anon_id; the door links the anonymous subject once.
$set honoured subject property set Applied by the door to the subject (200 keys, 16 KiB).
$set_once honoured subject property set-once Applied by the door; a key the subject already has is kept.
$unset honoured subject property unset Applied by the door.
$create_alias mapped subject alias (one-hop repair) Never a merge: refused when it would join two identified subjects (alias_refused).
$groupidentify mapped account properties The group type must be a live account type; the key is pseudonymised (purpose account).
$groups mapped accounts on the item At most five account types per event.
groups_dropped ignored - A $groups entry past five, or with a type that is not an account type key.
$process_person_profile mapped personless: true false makes the event personless: no subject row, no property write.
set_on_personless ignored - $set, $set_once and $unset on a personless event are dropped.
$is_identified mapped anon_id instead of distinct_id false keeps the id anonymous; absent or true is an identified distinct id.
$device_id mapped device_id Stored as an expiring keyed hash, only with consent.
$session_id mapped session_id Kept only when a UUIDv7 (the door judges it).
$pageview mapped $pageview with $pathname, $host, $referring_domain Derived from $current_url and $referrer.
$pageleave mapped $pageleave with the same derived fields As $pageview.
$screen mapped $pageview with $screen_name A mobile screen view is a page view of a named screen; no path is invented.
$current_url mapped $host, $pathname The full URL is not stored: its query string can carry identifiers.
$referrer mapped $referring_domain Host only.
utm_params mapped $utm_* session properties From utm_* properties or the URL query.
$feature_flag_called honoured flag exposure event Passed through for the exposure fold.
reserved_event honoured the same reserved event Any other name on the server-interpreted list ($rageclick, $survey_sent, ...).
$autocapture refused - Autocapture is off (PA-35); the interaction recorder carries clicks.
$exception refused - Errors use the error envelope, not a product event.
$merge_dangerously refused - Merging two people is a human act; nothing is merged.
$posthog_cookieless refused personless event The sentinel is never a person; the event is stored personless.
$snapshot refused - Session recording has its own door.
unknown_reserved_name refused - A $ name the server does not interpret.
missing_distinct_id refused - No distinct_id on the event or in its properties.
personless_identify refused - An identify cannot be personless.
bad_event refused - Not an object, no event name, or a field of the wrong shape.
batch_over_cap refused - Messages past the batch cap are dropped and counted.
group_type_unknown refused - The group type is not a live account type of the project.
alias_refused refused - The alias would chain, join two identified subjects, or has no known target.
identity_paused refused - Subject writes are paused for the deployment; the alias or group properties are not written.
uuid_generated mapped item uuid No uuid: the server mints one, so a re-send is not deduplicated.

segment

Semantic Disposition Becomes Note
track mapped product event, same name A name starting with $ is refused.
identify mapped $identify item userId is distinct_id, anonymousId is anon_id, traits is $set.
page mapped $pageview Path, host and referrer host derived; name is $page_name.
screen mapped $pageview with $screen_name As the PostHog $screen.
group mapped $groupidentify item with accounts and account properties The account type is the configured one (default group); the traits are account properties.
alias mapped subject alias (one-hop repair) previousId joins userId; never a merge of two identified subjects.
messageId mapped item uuid A UUID is used as sent; any other id becomes a deterministic UUID.
uuid_generated mapped item uuid No messageId: the server mints one, so a re-send is not deduplicated.
sent_at mapped sent_at skew correction Returned as sentAt for the envelope.
context.ip_user_agent mapped $ip, $user_agent The door derives country and device from them, then drops them.
context.campaign mapped $utm_* session properties name, source, medium, term, content.
context.page mapped page fields Fallback for a page or screen call without properties.
context.other ignored - library, device, os, locale, timezone, network and the rest.
integrations ignored - Destination routing is accepted and ignored.
writeKey ignored - Authentication is the DSN key; the value is never read or stored.
server_stamps ignored - receivedAt, version, channel: the server stamps its own.
unsupported_type refused - Not one of identify, track, page, screen, group, alias.
reserved_event_name refused - A track name starting with $ is the server namespace.
message_too_large refused - Over Segment's 32 KiB per message.
missing_identity refused - Neither userId nor anonymousId (or no groupId, previousId).
bad_event refused - Not an object, or a field of the wrong shape.
batch_over_cap refused - Messages past the batch cap are dropped and counted.
group_type_unknown refused - The configured group type is not a live account type of the project.
alias_refused refused - The alias would chain, join two identified subjects, or has no known target.
identity_paused refused - Subject writes are paused for the deployment; the alias or group traits are not written.