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
warningsblock, largest names first. - The volume is an estimate. The door keeps no raw event, so
volume30dis a 30-day exponentially decayed count, decayed to the moment you read. It is labelledbasis: estimate. - Types.
string,number,boolean,datetime,object,array; traffic that disagrees with itself ismixed. A declared type that disagrees with the detected one is atypeMismatch(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:
- any attempted operation on a verified definition, whether the engine asked, refused or applied;
- 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.