# 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](./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. |
