# 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.
