# Analytics actions: named, retroactive sets of events

An **action** gives a name to a set of things people did, so a funnel, a trend or an alias can say
"checkout" instead of listing events. It is a definition only: nothing is captured for it. It is
applied, at read time, to what Bucker has already stored, so an action created today counts last
month. (The page is named `actions-analytics` so it never reads as the remediation actions
registry, `actions.md`.)

An action is stored per project, behind the product-analytics gate (PA-01). A project that has not
opened the gate has no actions and every read and write here refuses.

## Matchers

An action holds one to ten **matchers**. A person counts for the action when **any** matcher fits
(OR across matchers). A matcher fits only when **every** part it names fits the same occurrence
(AND within one).

| Kind | Fits | Read from |
| --- | --- | --- |
| `event` | a custom event, optionally one value of a promoted property (`where: { property, equals }`) | `pa_core_event_daily` |
| `url` | a page view whose path `equals`, `contains` or fits a `route` template such as `/orders/:id` | the page-view event's promoted path property (`$pageview` / `$pathname` unless the matcher names others) |
| `click` | an interaction-layer click: a selector chain (matched on its leaf), the element text, on an optional route template | `interaction_route_hours` |
| `screen` | a screen name of a mobile surface | the `$screen` event's promoted `$screen_name` |

Every event a matcher reads must be a **core event** of the project: the rollups hold no other, so
an action over one could never count and would read as "nothing happened". Creating one is a 422
that names the declared set.

### What the counts mean

* **A row counts once.** The union of matchers is a union of stored rows, so two matchers that fit
  the same row (an `equals` and a `route` over the same path; two clicks on one selector) never
  double count. Each matcher also reports its own count.
* **Counts, not people.** A match count is a number of events or interactions. Clicks are
  interactions, not people; the answer says so in `approximation`.
* **Values folded into `other`** by the rollup's per-day value cap cannot be matched by a URL,
  screen or property matcher; the answer says so.
* **Element text is stored nowhere.** No rollup keeps what an element said, so a matcher that
  names text is `text_not_stored` and contributes nothing. It is stated beside the number, never
  counted as zero. A click matcher that combines a selector with text is unverifiable for the same
  reason.
* **A URL, screen or property matcher on a property that is not promoted** is
  `property_not_promoted`: breakdown rows exist only for promoted properties.
* Interaction rollups are kept 90 days; a window that reaches past that says so.

## Funnels, trends and aliases

A funnel step may name an action (`{ "action": "checkout" }`) wherever it names an event, and the
saved insight is bound to the action's **revision**: a change to the matchers is a new answer, never
a cached one.

**Only a plain-event action can be a funnel step.** A funnel needs, per person, the first time each
step happened, and the stored first sightings are keyed by core event only: no URL, no selector, no
property value. A plain-event action's step is the union of its events' sightings, one per person
and day (the earliest), so a person who did two of its events in one day enters once. An action with
a URL, click, screen or property matcher answers counts (a preview, a trend) and is
`tier_unavailable` as a funnel step, with the reason `action_not_subject_level` naming the matcher
kinds. Counting only its event half would be a silently wrong number.

**The preview reproduces in the saved insight where it can.** For a plain-event action the preview
reports `entries`, the number of (person, day) pairs the action's events have a first sighting on:
exactly the `entered` of a funnel's first step over the same days.

An action can also be the alias that names near-duplicate event names (`sign_up`, `Signup`): make an
action of both and use it. Trend series and cohort rules read the action through the same
`matchActionSet` once the insight grammar's series accept an `action` (see the wiring note).

## Creating one

`POST /orgs/:org/projects/:project/analytics/actions`, or the MCP tool `analytics_action_create`.
Both are the governed operation `analytics_action.create`:

* **ELEVATED, allowed by default.** It changes no number that exists: nothing reads an action until
  an insight names it.
* **It asks a person when a click selector is fragile.** The server checks every click matcher
  against the click stream of the last seven days, using the same leaf identity as
  `heatmap_get`'s `selector_check`. A matcher is fragile when its leaf is a bare tag (`button`) or a
  position (`li:nth-child(3)`), was not seen on its route (or on any route, when it names none) in
  the last seven days, or names only element text. **The fact is computed on the server; no
  argument states it**, and an ALLOW policy row cannot lift it. An agent should call `heatmap_get`
  with `include: ["selector_check"]` first.
* A preview is its own route (`POST …/actions/preview`): the 30-day counts per matcher and for the
  union, the selector check, and whether the create would ask. It stores nothing.
* **A key that is taken is refused (422 `action_key_taken`)**, whatever the other values. The
  create doors never turn into an edit of the existing action: that would hand an agent
  `analytics_action.update`, which has no MCP tool.

## Changing and removing

| Act | Class | Who |
| --- | --- | --- |
| `analytics_action.create` | ELEVATED, ALLOW (asks on a fragile selector) | a person or an agent |
| `analytics_action.update` | SENSITIVE, ASK | a person through the dashboard or API; **no MCP tool** |
| `analytics_action.archive` | ELEVATED, ALLOW for an action nothing reads; an edit (ASK) for one a saved insight or metric reads | a person or an agent through the API |
| `analytics_action.delete` | human-only (`org:admin`), irreversible | a person on their own sign-in |

An agent that wants a different action creates a new one and a person archives the old one, so no
number an insight shows changes under an agent. The previous values are the inverse
(`operation_revert`); a create's inverse is an archive. Delete is a person's act: an agent, an OAuth
client or an organization token is refused. A saved insight that names a deleted action fails with
"Action not found" rather than computing without it; archive is the reversible path.

## Reading them

* `GET …/analytics/actions` lists actions with their 30-day counts and what reads each.
* `GET …/analytics/actions/:action` shows the matchers, each matcher's count and status, the daily
  series, the selector checks and the revision history.
* `taxonomy_get` lists actions in the `definitions` block of the events page as `kind: "action"`
  with a 30-day match count: names, counts and matcher kinds only. No selector, URL pattern or
  element text reaches an agent through that block.

Selector chains and click text come from customer pages: they are never echoed by
`analytics_action_create`, and a plan that carries them records them as free text so the engine can
tell a value an agent copied from served telemetry.

## Limits

At most 200 actions per project and ten matchers per action; a matcher value is at most 200
characters, a selector chain 1,024 and element text 64. A read pulls at most 50,000 rollup rows and
says `read_truncated` when it stopped.
