# Product events

`product_event` is a Bucker SDK envelope item for product analytics. It is not a Sentry item. This page is what the door does with one, the per-item answer, the caps, and what is and is not stored.

An item is accepted only for a project whose analytics gate is open (PA-01); otherwise it is refused at accept with `product_category_disabled`. It meters as the `product` category.

## The accept stages

The stages run per item, in this order, and are never reordered. Each refusal writes an outcome row with its reason and appears in the per-item `results` array of the response. Nothing is dropped silently.

| Order | Stage | What it decides |
| --- | --- | --- |
| 30 | `reserved_names_caps` | Strips the server-owned item keys (an SDK cannot assert its own basis or claim the overflow lane). Checks the reserved-name table, the caps, and a timestamp more than 23 hours ahead of the server clock (`future_timestamp`). Corrects `sent_at` skew unless the envelope declares import mode; in import mode the event times are kept and `import_id` is stamped. |
| 40 | `illegal_ids` | An illegal `distinct_id` (empty, `null`, `undefined`, `anonymous`, and similar) does not refuse the item: it is stored personless with `illegal_distinct_id`, and counted. |
| 50 | `consent_basis` | Resolves the storage basis from the consent header, the project posture and the dataset rule. No acceptable basis is `consent_required`, or the item folds into exempt aggregates only where the register permits. |
| 70 | `dedupe` | A uuid seen in the last 48 hours for the project is `duplicate` (outcome `product_event_duplicate`) and folds nothing. |
| 80 | `hot_keys` | A (project, distinct id) stream above 5,000 events a minute goes to the overflow lane: no subject processing, a warning row, result `accepted` with warning `overflow`. |

## Caps

| Cap | Value | Reason on breach |
| --- | --- | --- |
| Event size | 64 KB | `property_cap_exceeded` |
| Properties per event | 500 | `property_cap_exceeded` |
| Property key | 200 characters | `property_cap_exceeded` |
| String value | 1 KiB | `property_cap_exceeded` |
| Event name | 200 characters | `property_cap_exceeded` |

## Results

Each item of the response `results` array carries `result` (`accepted`, `refused` or `duplicate`), a `reason` and an optional `warning`.

| Result | Reason or warning | Meaning |
| --- | --- | --- |
| `accepted` | none | Queued for the worker. |
| `accepted` | warning `overflow` | Hot-key overflow lane; counted, no subject processing. |
| `accepted` | warning `illegal_distinct_id` | Stored personless. |
| `duplicate` | `product_event_duplicate` | Same uuid inside 48 hours. Folds nothing. |
| `refused` | `property_cap_exceeded`, `reserved_event_name`, `future_timestamp`, `consent_required` | Not stored. One outcome row. |

## The worker

The worker takes every `product_event` item of a job as one batch. It resolves the subject and the session, derives the actor type and traffic class, stamps the basis, then writes through the `TelemetryStore` seam in one transaction with the batch token. The folds (sessions, product rollups, web, interactions, flag exposures, surveys, subject properties) run inside that transaction through the fold seam; the door imports no writer.

An item that passed accept and is still unusable is **poison**: an `invalid` outcome with reason `poison_event:<code>`, counted, and the job completes. Only infrastructure failures raise and retry.

The `product_events` pillar gates the worker branch. With it off the items are accepted and metered, and the worker defers them with the reason `behind pillar`.

## What is stored

- Folded counts in sessions and declared rollups, and the batch log (a token and counts).
- The dedupe ledger: a uuid and a day, kept for two days.
- Warning rows per project, hour, kind and event name (names past 50 in an hour file under `$other`).
- Outcome rows for every refusal.

## What is not stored

- No raw event body, property value, raw `distinct_id`, IP address or User-Agent in any table. End-user identifiers at rest are keyed pseudonyms.
- The analytics lane's job payload and envelope blob are deleted when the job completes. Raw ids live for the life of the job; the seven-day retention of the durable log applies to errors only. A job that dies keeps its payload for dead-letter inspection until the ordinary prune.

## Reading the warnings

`GET /orgs/:orgSlug/projects/:projectSlug/product-events/warnings` (project read; query `windowHours`, default 24, at most 14 days) returns the warning rows for the project: kind, event name, count, window.
