Skip to content
bucker

Canonical metrics: one number for one question

Two people, or a person and an agent, can ask "what is our activation rate?" and get two different answers because each built their own query. A metric is the project's one agreed definition of a number. An agent can propose one; only a person can make it canonical.

A metric is stored per project, behind the product-analytics gate (PA-01): a project that has not opened the gate has no metrics to read and every read here says so.

What a metric is

Field Meaning
key Lower-case letters, digits and _ (64 at most). The handle; never reused for another meaning.
version (project, key, version) is unique. A revision is a new version, never an overwrite.
name, description, unit unit is one of count, percent, ratio, seconds, currency, score.
definition ONE node (a trends node with one series and no breakdown, or a funnel), or a ratio of two such trends nodes (numerator, denominator), or a shared insight of the project (sourceInsightId: the insight's served node is the definition). filters are added to the node, or to both nodes of a ratio.
ownerPrincipalId A member or an agent of this organization.
provenance createdVia (dashboard, mcp, config), modelId (self-reported, never a decision input), reasoning (the proposer's words: untrusted text).
digest SHA-256 over key, version, name, unit and the nodes. A description or an owner is not in it: they do not change the number.

The three states

Status Authority
proposed None. What an agent writes, and what a person writes before certifying. Nothing reads it as "the" number.
certified A person certified this exact version. Canonical only while it is not drifted.
archived Retired, or superseded by a newer certified version. Restorable (as proposed) for 90 days.

Canonical = certified and not drifted. At most one version of a key is certified, and at most one proposal per key is live (a new proposal archives the previous one).

Who can do what

Act Who How it is decided
Propose a new key, or a revision of one (revisionOf) analytics:write, an agent included metric_definition.create, ELEVATED, applied under the organization's default policy. Lands proposed.
Edit in place (target), archive, restore analytics:write metric_definition.update / .archive, SENSITIVE, asks a person. There is no MCP tool for them.
Certify A person on their own session with project admin metric_definition.certify, human-only. Refused to every agent, service, OAuth-client, delegated and derived credential, and to a member without admin.

Rules the engine enforces, and the suites pin:

  • No write of the family ever stores certified. A create is proposed, a revision is proposed, an edit that changes a certified metric's name, unit or definition demotes it to proposed (a description or an owner does not), and a restore is proposed. So an operation_revert can never put a certified number back: a person's certification is not something an inverse can launder.
  • A create never overwrites. A key that exists is refused unless the call names the version it revises.
  • A revision leaves the certified version canonical until a person certifies the revision, which supersedes the certified version in the same step.
  • A source insight must be shared and in this project. A draft, an archived insight, another project's and another organization's are one refusal, so nothing can be learned from the answer.

Drift

A metric built from an insight is drifted the moment that insight's served revision changes (a promotion, a restore). A draft revision of a shared insight serves nothing and is not drift. A drifted metric keeps its status and loses its authority; archiving or deleting the source has the same effect, and restoring an archived source does not undo it. The insight writer flags the metrics in the same transaction as each of its three transitions (the served revision moves, the insight is archived, the insight is deleted), and evicts the cached answers that said "canonical". Every resolver and list also evaluates the rule against the insights as they stand and reconcileMetricDrift persists it, so a row written by any other door is never read as canonical; the one thing such a door can leave behind is a cached envelope that still says "canonical" until the next reconcile or the cache's own expiry (an hour to a day).

The remedy is a revision built from the insight as it is now (revisionOf with sourceInsightId): a fresh proposal, not drifted, that a person certifies.

Certifying

The certify card is a person's own act in the dashboard, never a typed word in a conversation:

  1. POST …/analytics/metrics/:key/versions/:v/certify/preview returns the card: the definition, the field-by-field difference from the certified version it would supersede, the newest 90 days of values (read as you, behind the cohort floor), the boards and alert rules that read the source insight, and the proposer's words labelled untrusted. Nothing is written.
  2. …/certify/challenge mints the step-up challenge, bound to the card's digest.
  3. …/certify certifies. In one transaction under a lock on the key: the version becomes certified, the version it supersedes becomes archived, the audit row is written and a signed metric_certified receipt is appended to the organization's receipt log. The receipt names ids, a digest and a revision: no name, no text, no node.

The digest the step-up is bound to covers the definition, what it supersedes and the drift state. It does not cover the values, which move with every event that lands. A definition that changed since the card, a proposal that was revised or archived, or a source that moved is preview_stale (409); a drifted proposal is refused (422 metric_drifted).

The step-up is enforced in production (nodeEnv), like the identity acts and the operator console.

Reading it

  • GET …/analytics/metrics and GET …/analytics/metrics/:key: key, status, canonical, drifted, the definition and who certified it. GET …/versions/:v/values: 90 days, read as the caller.
  • taxonomy_get (MCP, held): the first page of definitions also lists the project's metrics (kind: metric): key, status, drifted, owner and the last value of the first few certified ones, canonical first. The last value is a floored aggregate.
  • Every number carries its tier. The insight envelope gains extensions.metric: { canonical: { metricKey, version } } when the node answered is exactly a canonical metric's node, { noncanonical: { nodeHash, kind } } for every other. An agent that reports a number from a noncanonical node says so, with its node. The dashboard draws the trust-tier badge from it.
  • A board tile and an analytics alert condition on a saved insight prefer the canonical metric built from it, and fall back to the insight's own node (noncanonical) when there is none or it has drifted.

Writing it from an agent

taxonomy_update takes a metrics entry (one per call, never together with events or properties): { key, name, unit?, node | numerator + denominator | sourceInsightId, reasoning?, revisionOf? }. It lands proposed, and says so in the answer (metric.status: "proposed"). The tool has no field for an in-place edit, an archive, a restore or a certification.

Limits

200 metric keys per project, 50 versions per key, names of 120 characters, descriptions and reasoning of 1,000. A ratio metric is canonical as a metric (its key and version); the two component nodes, read on their own, are noncanonical, because a single node cannot name a ratio.

Held (SG-059): taxonomy_update needs analytics:write and the analytics toolset, which no token a production path can mint carries until the security review is signed off.