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
mapPostHog(body)ormapSegment(body)(pure) read the parsed JSON and return the items, the subject operations and one outcome per semantic met.applyPayloadSemanticsis the write path. It checks the per-project product-analytics gate (PA-01) first. While the DPA amendment is unpublished (ANALYTICS_DPA_VERSIONis null) or the project has not enabled analytics, it refuses with 422analytics_not_enabled(causedpa_amendment_pendingand so on) and stores nothing: no alias, no account, no count.- 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_eventenvelope; 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_dangerouslyis 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.falsekeeps the id an anonymous subject; absent (server SDKs) ortrueis an identified distinct id. An$identifycarries the new id and$anon_distinct_id, and the door links the anonymous subject once. - Personless.
$process_person_profile: falseand the$posthog_cookielesssentinel store the event with no subject and no property write. - URLs.
$current_urlis reduced to$hostand$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_urland$initial_referrerin$set_once, and the rest), and Segment'surlandreferrerproperties, keep scheme, host and path only; Segment'ssearchis 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 (
categoryand the rest); the Spec's page fields (url,path,referrer,search,title,name) become the derived ones. - Groups. PostHog
$groupsand Segmentgroupmap 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 (defaultgroup). - Re-sends. A PostHog
uuidand a SegmentmessageIdbecome 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. |