metricname

Documentation

Overview

Package metricname holds the measured-vs-estimated naming rule for the stats documents this product publishes, as code rather than as prose.

The failure it prevents is one specific misreading: a count of records presented under a name that makes it a count of people. Every number in these documents is a count of observation rows, of anonymous rotating buckets, or of reports — and none of them is a count of users, installs or machines, because no defensible method for any of those exists here (docs/activation-funnel.md §6, and the sentence the README already carries: unique/active users, live MCP processes and successful installs are not measured).

A caveat printed beside a number does not survive being quoted. A field name does. So the rule is applied to names.

Index

• Constants
• Variables
• type Violation
  • func Check(doc any) []Violation

Constants

const (
	RuleForbiddenActor     = "forbidden-actor-noun"
	RuleUndeclaredBucket   = "undeclared-bucket-noun"
	RuleUnlabelledEstimate = "unlabelled-estimate"
)

Rule identifiers, so a failing test says which rule and not only which field.

Variables

var BucketNouns = map[string]string{
	"peers": "today's distinct daily anonymous buckets; they rotate at UTC " +
		"midnight, so this cannot be summed over time and is never a head count",
	"projectsMonth": "distinct monthly project buckets; the path is HMAC input " +
		"only and is not recoverable, and one person's three checkouts are three",
}

BucketNouns is the deliberate allowlist: JSON field name → what one unit actually is. Adding an entry is how a reviewer is made to say it.

Types

type Violation

type Violation struct {
	// Field is the JSON path, so a nested document reports where it is.
	Field string
	Rule  string
	Why   string
}

Violation is one field that breaks the rule.

func Check

func Check(doc any) []Violation

Check reports every naming violation in the struct type of doc.

Only fields a consumer can actually read are checked: unexported fields and json:"-" never reach the wire, so they make no claim to anyone.