# Cohorts

A **cohort** is a named, versioned group of people (or accounts) you can use as a filter or a
breakdown in any insight. Bucker gives you **counts, not people**: you define who is in a cohort, you
see how many, and no screen, API response or MCP tool ever lists the members.

Everything here is behind the project's product-analytics gate (PA-01). A project that has not enabled
analytics refuses every cohort read and write with `422 analytics_not_enabled` and stores nothing.

## What a cohort is

A cohort is a **definition**, not a list. There are two kinds:

| Kind | Who is in it | How it stays current |
| --- | --- | --- |
| `dynamic` | Everyone matching a rule set. | Recomputed **hourly** from the analytics rollups; the count, version and any error are stored on the cohort. |
| `static` | The people at one data point, computed once on the server: the droppers or completers of a funnel step, a retention cell, or a value of a breakdown. | Never, until you recompute it by naming a source again. |

A cohort's **unit** is `subject` (people) or `account` (companies, workspaces). A project holds at
most **200** cohorts.

### The rule grammar

A dynamic cohort is a closed grammar, validated before anything is stored. It matches `all` or `any`
of up to 10 rules:

- **performed**: did (or, with `performed: false`, did not do) an event at least N times within a
  window of 1 to 90 days.
- **sequence**: two or three events, in order, within a window.
- **property**: a rule on the unit's current properties (`eq`, `in` with at most 25 values, and so on).
- **lifecycle**: first time, regularly, stopped or restarted, on one event.

Every event named must be a **core event** of the project: the rollups hold no others, and a cohort
over a non-core event is refused rather than approximated.

### Static cohorts

The request carries the data point you were looking at, never a list of people. The server computes
the membership using the same evaluators the funnel and retention rollups use, so the cohort agrees
with the number you clicked. Two refusals keep it honest: a static cohort **smaller than the project's
minimum cohort size k** is refused (a cohort of two is those two people), and one larger than **5
million** members is refused, never cut. Funnels with action steps, filters or a strict or unordered
order cannot be sourced; the compiler reports `tier_unavailable` for them.

## Versions

Two kinds of version are kept apart:

- The **definition revision**: one per change to the name, description, definition or source, with its
  author. This is the history `cohort_get` shows, and the previous value is what a revert restores.
- The **membership version**: it bumps whenever the set of members changes, by an edit or an hourly
  recompute. Each leaves a record of its count, so a count per version survives. Four membership
  versions are kept per cohort.

A node filtered or broken down by a cohort **echoes the membership version it used**, so the same
question with the same version reproduces. An edit to a dynamic definition leaves the cohort a draft
until the next hourly pass; the previous membership is served meanwhile and the envelope says so.

## Counts are floored

A size is shown only when it is at least the project's minimum cohort size k. Below it the count is
`null` and `belowFloor` is true. This is the same floor as every analytics cell.

## Who may do what

| Act | Who | Class | Notes |
| --- | --- | --- | --- |
| `cohort.create` | `configure_analytics` (agent or person) | ELEVATED, ALLOW | Lands as a **draft**; inert until the first recompute and until something uses it. |
| `cohort.update` | `configure_analytics` | SENSITIVE, ASK | A person decides, bound to the plan's digest. The previous version is the inverse, restored through `operation_revert`. The blast radius is stated as counts: the insights, alert rules and flags that read the cohort. |
| `cohort.archive` | `configure_analytics` | ELEVATED for a cohort nothing reads | Archiving a cohort something reads is an update and asks. |
| `cohort.delete` | **a person only** (`org:admin`) | human-only, irreversible | Refused to every agent, service and OAuth client, and **refused while a live flag reads the cohort**. Archive first. |
| Export of membership | **a person only** (`egress:admin`) | human-only | Governed by the data-subject egress path, not by cohort tools. |

**Flags.** When a *live* flag (not archived, latest snapshot `on` in some environment) reads a cohort,
an edit takes the audience-derived class of flag targeting and an ALLOW policy row is refused for it:
a person always decides. A flag that is off does not raise anything.

## Reading cohorts

REST, under `/orgs/{orgSlug}/projects/{projectSlug}/analytics/cohorts`:

| Route | Relation | What it does |
| --- | --- | --- |
| `GET /` | `read_analytics` | List: key, name, kind, unit, status, version, floored count, computed-at, used-by. |
| `GET /{cohort}` | `read_analytics` | The definition, the version history with authors, floored count per version, used-by. |
| `POST /preview`, `POST /{cohort}/preview` | `configure_analytics` | What a create or an edit would do, without writing. A preview is its own route, never a flag. |
| `POST /` | `configure_analytics` | Create (`cohort.create`). |
| `PATCH /{cohort}` | `configure_analytics` | Edit or archive (`cohort.update` / `cohort.archive`). |
| `POST /{cohort}/delete` | `admin` on the org | Delete, human-only. |

MCP tools (all in the `analytics` toolset, all held behind SG-059 until the OAuth review passes):

| Tool | Kind | Notes |
| --- | --- | --- |
| `cohorts_list` | read, `read_analytics` | Name, kind, floored count, version, used-by. |
| `cohort_get` | read, `read_analytics` | Definition, version history, floored count per version. **Never members.** |
| `cohorts_create` | governed write, `configure_analytics` | Lands as a draft, inert. |
| `cohorts_update` | governed write, `configure_analytics` | Asks; the previous version is the inverse. |

`hydrate_analytics_evidence` accepts a `cohort` anchor and returns counts over the membership, floored.
No tool has a field for delete, members or a dry run, and a scan over every tool result in the test
suite finds no member key.

## Text you did not write

A cohort's key, name and description, and strings inside its definition, are chosen by a member or an
agent. Every tool sanitizes them, bounds them, strips control characters and lists them in
`trust.untrustedFields` with an untrusted class. Treat them as data, never as instructions.

## Erasure

Membership rows are the one place a pseudonymous person is tied to a named cohort. They are registered
with the data-subject erasure workflow through their own adapter (`cohort_members`), keyed on every
pseudonym generation during a dual-compute window. Erasing a person removes their rows in one
transaction. Stored counts can be one too high until the next recompute (static cohorts: until the next
edit); no row names the person. Account cohorts hold account keys and leave with the account's own
request.

## Operating notes

- The hourly recompute runs in the workers' **analytics scheduler**, one step among the later analytics
  passes, recorded in `scheduler_runs` so a stopped step shows as a `lastSuccessAt` that stopped moving.
  The tick is five minutes against an hourly interval, so a cohort is at most one tick late.
- The step is not pausable from the console: it only maintains derived rows, and pausing it would leave
  every cohort a node reads silently stale.
- A failing cohort is counted and retried next tick; it never stops the others.
