# The taxonomy: what a project's events and properties are

Product analytics begins with names an application chose: `signup`, `Signup`, `plan`, `$pageview`.
The taxonomy is where Bucker records what each name **means** (a description, an owner, tags),
what it **is** (the type seen in traffic, how often, since when) and whether to **show** it. It is
stored per project, behind the product-analytics gate (PA-01): a project that has not opened the
gate has no definitions and every read here says so.

Every definition has two halves, and they never write each other:

| Half | Written by | Fields |
| --- | --- | --- |
| **Detected** | the ingest fold, from traffic | the type seen, first and last seen, the 30-day volume estimate and units |
| **Authored** | a person, an agent, `bucker.yml` | description, owner, tags, hidden, a property's declared type, verified |

A tagging edit therefore never moves a count, and ingest never overwrites a description.

## Definitions

* **Events** (at most 10,000 per project) and **properties** (at most 20,000). A name past the cap
  is not stored; the overflow is counted and shown in the `warnings` block, largest names first.
* **The volume is an estimate.** The door keeps no raw event, so `volume30d` is a 30-day
  exponentially decayed count, decayed to the moment you read. It is labelled `basis: estimate`.
* **Types.** `string`, `number`, `boolean`, `datetime`, `object`, `array`; traffic that disagrees
  with itself is `mixed`. A declared type that disagrees with the detected one is a `typeMismatch`
  (a datetime is a string by another name and is not one).
* **Samples.** Up to five distinct values per property, scrubbed at the agent tier, with a value
  that reads as an instruction **withheld and counted**. A personal or sensitive property is never
  sampled. Every sample is served with `label: "untrusted"`: it is a value anyone holding the public
  key could have sent.
* **Near-duplicates.** Names that differ only by case, separators or a plural (`Signup`,
  `sign_up`, `signups`). The answer is always *hide the duplicate, keep the canonical name* (a
  verified one, else the largest). **There is no rename**: an event name is the key of its rows and
  of everything counted under it.
* **Usage.** Which insights, cohorts, metrics and certified metrics read a definition.
* **Revisions.** Every authored change and every verify writes a revision with its before and after.

## Reading it

`GET /orgs/:org/projects/:project/taxonomy?block=…` and the MCP tool `taxonomy_get`:

| Block | What it holds |
| --- | --- |
| `definitions` | events or properties, paged, largest first, hidden excluded unless asked |
| `setup` | the gate, the core-event declaration, how many are undescribed, unowned, hidden, verified |
| `identity` | counts only (the identity health of the project) |
| `warnings` | the last seven days of cap overflows and fold warnings |
| `filters` | ingestion filters by mode (the filters themselves ship with the ingestion package) |
| `checks`, `imports`, `compatibility`, `gaps` | `not_available`, naming the package that owns each |

`GET …/taxonomy/definition?kind=event&name=…` (or `kind=property&eventName=…&name=…`) is one
definition in depth. A block that cannot be answered says so; it never reads as zeros.

`taxonomy_get` is a **held** tool (SG-059): it needs `analytics:read` and the `analytics` toolset,
which no token a production path can mint carries until the security review is signed off. Names,
descriptions, tags and samples are listed in `trust.untrustedFields` with their F-16 class.

## Changing it

One governed door, the `taxonomy` operation family: the REST route `POST …/taxonomy`, the MCP tool
`taxonomy_update`; the dashboard tab and `bucker.yml` follow with the wiring and frontend packages and
use the same family. The input is a **desired state**: the
definitions to change and the value each field should have. The engine diffs it against the rows,
drops what already holds, and derives the act from what is left:

| What the diff does | Act | Class |
| --- | --- | --- |
| description, tags, owner, hidden on an unverified definition | `taxonomy.update` | ELEVATED, allowed by default |
| anything on a **verified** definition | `taxonomy.update` | SENSITIVE, asks a person |
| hiding an event a **certified** metric reads | `taxonomy.update` | SENSITIVE |
| a change to the core-event set | `taxonomy.update` | SENSITIVE (a new rollup version) |
| a property's declared type | `property_definition.update` | SENSITIVE, asks; no MCP tool |
| marking an event definition verified | `event_definition.verify` | **human-only**, project admin |

At most 50 operations a call: one call is one plan, one digest, one approval. A `202` carries
`approvalRequestId`; the same body with that id applies the approved plan once, and a definition
edited since the yes makes the retry `TARGET_CHANGED`. Every change can be undone with
`operation_revert` (a compare-and-swap on the definition's revision).

### The autonomy ladder (`analytics_tagging`)

An agent's standing on this category is a rung: it starts by being asked, and what a rung changes
today is the number of approvers an ASK needs. Two things **demote** an actor one rung, written as
ladder events:

1. any attempted operation on a **verified** definition, whether the engine asked, refused or applied;
2. a description driven by payload text: the operation's input provenance is `untrusted_text`
   (the F-16 match found a sample value the session had been served inside the description).

Promotion is offered, never taken: 30 applied operations over 14 days with no revert and 90 % of
the descriptions still unchanged. Write descriptions from what a property **means**, not from what
it contains.

### What an agent cannot do

* verify a definition, change a declared type, rename an event, or edit the core-event set through
  `taxonomy_update` (the tool has no field for any of them);
* touch another project: a name that is not this project's is "no such definition".

## The weekly pass

Once a week, per project, a detector (`taxonomy_weekly_pass`, shadow first) files tagging plans as
ordinary issues, each with its evidence:

| Plan | Evidence | Proposal |
| --- | --- | --- |
| `undescribed_high_volume` | events with volume and no description | none: the words are the author's |
| `unowned` | events with volume and no owner | none |
| `near_duplicate` | names that differ only by case, separators or a plural | hide the duplicates, keep the canonical name |
| `dead` | visible, unverified events not seen for 90 days | hide them |

A proposal is exactly the `events` array `taxonomy_update` takes (at most 50) and never names a
verified definition. The pass changes nothing. The issue's words are Bucker's; the application's
names ride in `extra` as clipped data.

## The core-event set

The set of events the rollups keep (at most 20) is declared once per project and **versioned**: a
change is a new version and the rollup rows are keyed by it. It is edited through `taxonomy.update`
(asked for), written as a compare-and-swap on the version the plan was made against.
