Skip to content
bucker

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.