# Accounts

An **account** is a company, a workspace or a team that your product's users belong to. Bucker
treats it as a first-class unit of analysis, next to the user, with **no add-on and no multiplier**:
an account never changes the unit budget or the bill, and every insight can aggregate by it.

Everything here is behind the project's product-analytics gate (PA-01). A project that has not
enabled analytics refuses the two account reads with `422 analytics_not_enabled`; configuring account
types does not read an end user and does not need the gate.

## Account types

A project defines **at most five** account types (index 0 to 4), for example `company`, `workspace`
and `team`. A type is a lower-case key (`[a-z][a-z0-9_]{0,31}`) the SDK names in
`accounts: { company: "acme" }`, a label, and a `nonPersonal` flag. **A person defines them**; there
is no MCP tool for any of it, because types are set once and change ingestion.

| Act | Who | Class | What it does |
| --- | --- | --- | --- |
| `account_type.create` | a person's approved request | SENSITIVE, always asked | Adds a type. **It lands archived and inert**: no event links to it. Putting it to work is the same act again, approved on its own digest. |
| `account_type.archive` | a person's approved request | SENSITIVE, always asked | Stops linking **new** events to the type. Nothing is removed; un-archiving is the reversal. |
| `account_type.narrow` | `analytics:write` | ELEVATED | Makes a non-personal type personal again, so its names stop reaching readers. |
| `account_type.widen` | **a person only** (`org:admin`) | human-only | Marks a type non-personal. An agent, a service, an OAuth client (even for the person who authorized it) and a derived credential are refused. A stated reason is required and the owners are told. |
| `account_type.delete` | **a person only** (`org:admin`) | human-only, irreversible | Removes the type, its accounts, their usage and the membership recorded on subjects. The key is typed back after a preview that lists what goes. Archiving is the reversible path. |

The first three run through the operations engine: the request names a type and states **one thing**
it should be (`label` for a new type, `archived`, or `nonPersonal`); the family reads the act from the
difference, never from an argument. A request that would widen is refused before anyone is asked.
`POST .../account-types/preview` shows the act and whether a governed request can carry it, without
writing anything. The five-type cap counts archived types.

## How events link to an account

An event carries `accounts: { type: key }`. The ingest door turns each key into a keyed pseudonym
(purpose `account`, computed from the type and the identifier together, so the same identifier under two types is two accounts) before anything is stored, so no raw account identifier is ever held. The account
fold links an event only to a **live** type: an archived type, an unknown type and a key that is not a
pseudonym link nothing and are counted. A subject's current account of each type is recorded on the
subject, so an account is a population of subjects and leaves with them on erasure. A subject in two
companies is a member of the one it was last seen under.

Account properties (`name`, plan, anything else, up to 100 keys and 8 KiB) arrive through account sets.
They are customer-supplied strings.

## What a reader sees

| Surface | Key | Name | Properties | Usage |
| --- | --- | --- | --- | --- |
| `GET .../accounts`, `GET .../accounts/{key}` | always (a pseudonym) | only for a **non-personal** type, scrubbed and labelled `untrusted` | never | 7, 30 or 90 days, withheld under the floor |

- **Names.** A name reaches a reader without `pii:read` only when a person marked the type non-personal,
  and then it passes the agent-tier scrub and the injection scanner and is labelled untrusted. A name the
  scanner refuses is withheld and says so.
- **The floor is counted in accounts and in subjects.** An account whose busiest day had fewer active
  subjects than the project's cohort floor reports no usage. A count of accounts below the floor is not
  stated. Inside an insight, an account with fewer member subjects than the floor contributes none, a
  filter that names several accounts and keeps fewer than the floor describes a few accounts and resolves
  to nobody, and an aggregation bucket with fewer than the floor active accounts reads 0.
- **Usage** per account and day is events, distinct active subjects and sessions, exact per day. The
  distinct counts are not additive across days, so the read names the sum `activeSubjectDays`.

## Insights by account

Every subject-keyed node (retention, lifecycle, stickiness, funnel) takes the account filter:

```json
{ "type": "account", "account_type": "company", "op": "in", "values": ["acme", "globex"] }
```

`values` are the identifiers your SDK sent or the accounts' keys. The filter resolves to the subjects
that currently belong to those accounts and can only **narrow** a node. Trends and paths keep no subject
in their rollups, so for trends the account question is two aggregations in `series.math`:

- `x_active_accounts`: distinct accounts with any product event in the bucket.
- `x_events_per_active_account`: the bucket's product events over its distinct active accounts.

Both read the per-account daily rollup (the series' event does not narrow them), are exact across the
days of a week or month bucket for the distinct count, and state that buckets under the floor were
suppressed. The envelope carries an `accounts` block naming the floor and the types.

## The insight widget

A dashboard tile of type `insight` shows a **saved** insight: its config is `{ "insightId": "...",
"display"?: "line" | "bar" | "big_number" | "table" }`, never a node. It runs the saved node through the
same compiler as everything above, as a fixed principal without `pii:read`, so every viewer of a board
sees the same figures. A draft insight renders as a note (share it to put it on a board), a project
without product analytics renders a note, an insight the rollups cannot answer says why, and an insight
of another organization is an empty tile. Widget rows written before widgets had keys still load.

## Doors

| Route | Relation |
| --- | --- |
| `GET /orgs/{org}/projects/{project}/account-types` | `read_analytics` |
| `POST .../account-types/preview` | `configure_analytics` |
| `POST .../account-types` | `configure_analytics`, governed `account_type.create` |
| `POST .../account-types/{type}/archive` | `configure_analytics`, governed `account_type.archive` |
| `POST .../account-types/{type}/narrow` | `configure_analytics`, governed `account_type.narrow` |
| `POST .../account-types/{type}/widen` | `admin` on the organization, human-only |
| `POST .../account-types/{type}/delete/preview` | `admin` on the organization |
| `POST .../account-types/{type}/delete` | `admin` on the organization, human-only |
| `GET .../accounts?type=&window=&limit=&cursor=` | `read_analytics` |
| `GET .../accounts/{accountKey}?type=&window=` | `read_analytics` |

Another organization's project is the same 404 as one that does not exist.
