# The interaction stream

DX-04's write side, and DX-14's. `$action` and `$visit` events (and the scroll depth a `$pageleave` carries) are **folded at write**
into hourly route rows, a click heatmap and the session's counters. **No raw interaction row is stored anywhere**: the columnar
tier that would hold one is a separate decision, and until it exists an interaction is counted and forgotten.

The code is `domain/src/modules/interactions/`. It registers on the product-event fold seam (`identity/folds.ts`) when it is
loaded, after the session fold. It is inert until two locks are open and a consent basis admits the session.

## What is kept

| Store | Key | Holds | Retention |
| --- | --- | --- | --- |
| `interaction_route_hours` | project, route template, hour, action kind, selector leaf | `count`, `sessions` (an HLL sketch, standard error 0.81 %), `errorsWithin1s`, `rageCount`, `deadCount` | 90 days |
| `heatmap_cells` | project, route template, UTC day, viewport bucket, selector chain digest, x, y on a 100 by 100 grid | `clicks`; on a sentinel cell (-1, -1) a 16-bucket scroll-depth histogram | 90 days |
| `sessions` (P3-47) | the session | `actions`, `rageClicks`, `deadClicks`, `errorClicks`, `maxScrollPct` | by retention class |
| `cross_refs` | issue and session | an `issue_session` link with `anchorMs`, for the error join | with the issue |

Nothing holds a subject key, a URL, a query string, an input value or a coordinate pair beside a person. A route is a template
(path only); a selector is the last element of the micro-DOM chain plus a digest of the whole chain; an action name is at most
64 characters, scrubbed at the stored tier, and kept only in the metadata of an error link, labelled untrusted.

Both rollups are registered in `ROLLUPS` as `proposed` writer taps (`derived_90d`), with the non-negative and monotonic checks.
`pruneRouteHours` and `pruneHeatmapCells` delete what is past 90 days; the retention pass calls them.

## The events

| Event | Properties read |
| --- | --- |
| `$action` | `$action_type` (`click`, `input`, `submit`, `scroll`; `custom` is not kept), `$target`, `$action_name`, `$pathname` or `$current_url`, `$viewport_width`, `$x`, `$y` (fractions of the page, 0 to 1), `$rage`, `$dead`, `$error_click`, `$scroll_pct` |
| `$visit` | `$pathname` or `$current_url`, `$viewport_width`, `$view_id`, `$tab_id`, `$scroll_pct` |
| `$pageleave` | `$pathname`, `$scroll_pct`, `$viewport_width` (scroll depth only; WEB-02 owns the event) |
| `$exception_link` | `$exception_issue_id` (the error join) |

Viewport buckets: `mobile` under 640 px, `tablet` under 1024, `desktop` under 1536, `wide`, and `unknown` when there is no width.

## The locks

1. **The PA-01 gate.** `assertAnalyticsEnabled(projectId)` first. A shut gate throws 422 `analytics_not_enabled` and the batch
   rolls back with nothing stored. The two reads (`interactionsForRoute`, `heatmapCells`) refuse the same way.
2. **The `interaction_stream` pillar** (P3-08, off by default). Off: nothing is stored, nothing is claimed.
3. **Consent.** Only a basis that admits interaction storage folds: `consent`, `contract`, `legitimate_interest`, or `not_required`
   (stored personless by the posture). `exempt_audience` and `unknown` fold nothing, because the `interaction_events` dataset
   exempts nothing (P3-36). The same rule holds for the interaction counters on the session row: under a refused basis an
   `$action` or `$visit` counts as an event and moves no `actions`, rage, dead, error-click or scroll counter. Replay
   recording is DX-05's separate gate and is not touched here.

There is no sampling: 100 % of consented sessions.

## The rate cap

A session may send 2,000 interaction events in a UTC hour. The 2,001st and later are dropped, counted as
`interaction_rate_capped` (outcome `rate_limited`, category `product`) in the ingest ledger, and recorded once per batch in
`product_event_warnings`. The counter is **per process**: a restart or a second api machine can admit another 2,000, never more
than 2,000 per process. A fold that throws gives its admissions back; a batch rolled back by a later fold in the same
transaction does not, which errs toward capping.

## The error join

An interaction (click, input or submit) within 1 second before an error event, in the same session, links the error's issue
to the session through `cross_refs` (`issue_session`, `bKind` `session`, `source` `rule`) with `anchorMs` (the click's time),
`errorAtMs`, `kind`, `route`, `selector` and, when present, `name`, so DX-11's bundle can cite it and a replay can seek to it.
The link is one per (issue, session) and keeps the first click's `anchorMs`. The route-hour row of the click that preceded
an error gets `errorsWithin1s + 1` for every error event, so a second error after another click counts on that click; a
replayed error event counts nothing, because its claim was already made.

The window of recent actions is in process memory (16 per session, 10,000 sessions). An error that reaches a different
process from its click finds only what its own batch carried; the SDK sends a click and the error it caused in one envelope.
The issue the event names must belong to the event's own project or nothing is linked.

## Idempotence and erasure

Each event is claimed in `product_event_uuids` under a uuid derived in this fold's own namespace, so a replay changes nothing.
The rollups hold no subject or session key (the sketch is hashed registers and cannot be read back), so the only store that
names a session is the error link; `eraseSubjectInteractions` removes a subject's links under every key generation the caller
passes (v2, retired generations, v1) and forgets those sessions in the in-process window. It runs before the subject erasure
deletes the session rows, or is given `sessionIds`.

## Reads

`interactionsForRoute(projectId, route, { from, to })` and `heatmapCells(projectId, route, { fromDay, toDay }, { viewportBucket })`.
Both are bounded (90 days, 5,000 rows) and return page-authored text (`route`, `selectorLeaf`) that a door must fence as
untrusted when it reaches an agent.
