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 isproposed, a revision isproposed, an edit that changes a certified metric's name, unit or definition demotes it toproposed(a description or an owner does not), and a restore isproposed. So anoperation_revertcan 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:
POST …/analytics/metrics/:key/versions/:v/certify/previewreturns 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.…/certify/challengemints the step-up challenge, bound to the card's digest.…/certifycertifies. In one transaction under a lock on the key: the version becomescertified, the version it supersedes becomesarchived, the audit row is written and a signedmetric_certifiedreceipt 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/metricsandGET …/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 ofdefinitionsalso 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.