Skip to content
bucker

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.