leaderboard

Documentation

Overview

Package leaderboard is the ranking of who uses AI most, in your org and globally.

It ranks who leads inside an org, which orgs lead globally, and draws a GitHub-style per-day contribution graph for one subject — all opt-in for public listing.

It is a DERIVED, read-only lens over the ONE usage ledger (hanzo.cloud_usage) through the datastore OLAP rollup — it adds no metering path and double-counts nothing.

Surface (all /v1, NO /api/ prefix; org-scoped, fail-closed):

GET  /v1/usage/leaderboard   ranked top users (personal|org) or orgs (global)
GET  /v1/usage/activity      per-day series for a heatmap + timeline (authorized subject)
GET  /v1/usage/leaderboard/optin       the caller's opt-in + their org's opt-in
PUT  /v1/usage/leaderboard/optin        set the caller's OWN public-listing opt-in
PUT  /v1/usage/leaderboard/optin/org    set the ORG's public-board opt-in (org admin)
POST /v1/usage/rollup/backfill          seed the rollup from ledger history (SuperAdmin, once)

It co-owns the /v1/usage/* prefix with apps/usage (the cost footprint at /v1/usage/summary) — a DISTINCT concern (who leads + your activity graph) at its own paths, registered as a separate subsystem so it stays isolated. Its auto health route is /v1/leaderboard/health (the spec name). apps/usage's own doc claims it "owns ALL usage"; two packages under one prefix is one prefix with no owner, and the name here (leaderboard) does not match the prefix it serves.

TENANT ISOLATION (the bar). The org is the VALIDATED IAM owner claim (principal.Org — the trusted X-Org-Id the identity middleware minted from the verified bearer, HIP-0026; NEVER a client header) AND a validated principal is required. Every datastore read binds the org POSITIONALLY (never interpolated). A user board only ever contains the caller's own org's rows; an org board carries org-level aggregates only; cross-org detail is structurally impossible. Fail closed: no principal → 401; datastore not connected → honest-empty (available:false), never fabricated ranks.

PRIVACY (opt-in). Public listing is OPT-IN and PRIVATE by default: a user sees their OWN rank always, but is shown to others only after opting in with a chosen handle; an org appears on the cross-org global board only after an org admin opts it in. See view.go for the naming/anonymization policy.

Index

• func BackfillUsageRollup(ctx context.Context, before time.Time) error
• func EnsureUsageRollup(ctx context.Context) error
• func Mount(app cloud.Router, deps cloud.Deps) error
• func Shutdown(_ context.Context) error
• type ActivityPoint
• type ActivityTotals
• type ActivityView
• type LeaderboardRow
• type LeaderboardView
• type SelfRank

Functions

func BackfillUsageRollup

func BackfillUsageRollup(ctx context.Context, before time.Time) error

BackfillUsageRollup seeds the rollup from ledger history before the cutoff. It is the DEPLOY-GATED, run-ONCE step: because SummingMergeTree accumulates, re-seeding a day it already holds would double that day, so the handler guards on the seed's own range (rollupRowsSeeded) or an explicit force. `before` is snapped to UTC midnight so the seed's day-range and the guard's are identical.

func EnsureUsageRollup

func EnsureUsageRollup(ctx context.Context) error

EnsureUsageRollup creates the derived rollup table + the incremental MV if they do not exist (the base ledger first, since the MV reads it). Idempotent and latched: a transient datastore blip does not permanently poison later attempts. Every leaderboard/activity read calls it first — the same discipline as EnsureCloudUsageTable — so the feature self-provisions its rollup the first time it runs against a connected datastore.

func Mount

func Mount(app cloud.Router, deps cloud.Deps) error

Mount wires the leaderboard surface onto app per HIP-0106 — one line over the generic subsystem entrypoint.

func Shutdown

func Shutdown(_ context.Context) error

Shutdown closes the opt-in store on SIGTERM (registered as the subsystem's Shutdown hook). Idempotent.

Types

type ActivityPoint

type ActivityPoint struct {
	Day       string `json:"day"` // "2006-01-02"
	Requests  int64  `json:"requests"`
	Tokens    int64  `json:"tokens"`
	CostCents int64  `json:"costCents"`
}

ActivityPoint is one day of a subject's usage — the atom of the contribution heatmap + timeline. CostCents populated only when the viewer may see spend.

type ActivityTotals

type ActivityTotals struct {
	Requests    int64 `json:"requests"`
	Tokens      int64 `json:"tokens"`
	CostCents   int64 `json:"costCents"`
	ActiveDays  int   `json:"activeDays"` // days with any usage
	MaxTokens   int64 `json:"maxTokens"`  // busiest day's tokens (heatmap intensity ceiling)
	MaxRequests int64 `json:"maxRequests"`
}

ActivityTotals are the window sums + heatmap-scaling hints.

type ActivityView

type ActivityView struct {
	Subject   string          `json:"subject"` // user|org|project
	ID        string          `json:"id"`      // resolved subject id (echoed)
	From      string          `json:"from"`
	To        string          `json:"to"`
	Days      []ActivityPoint `json:"days"`
	Totals    ActivityTotals  `json:"totals"`
	Available bool            `json:"available"`
	Source    string          `json:"source"`
	Note      string          `json:"note,omitempty"` // honest note (e.g. project attribution not in the ledger)
}

ActivityView is the per-day series for one authorized subject.

type LeaderboardRow

type LeaderboardRow struct {
	Rank      int    `json:"rank"`
	Handle    string `json:"handle"`
	Anonymous bool   `json:"anonymous"`
	Self      bool   `json:"self"`
	Requests  int64  `json:"requests"`
	Tokens    int64  `json:"tokens"`
	CostCents int64  `json:"costCents"`
	Metric    int64  `json:"metric"`
}

LeaderboardRow is one ranked subject (a user or an org). Handle is the display identity per the privacy model; Anonymous marks a withheld identity; Self marks the caller's own row. Requests/Tokens are non-sensitive volume aggregates; CostCents is populated ONLY when the viewer is authorized to see this subject's spend (self, admin, or an explicit cost board — see costVisible). Metric is the value the board is ranked by (for bar sizing on the client).

type LeaderboardView

type LeaderboardView struct {
	Scope     string           `json:"scope"`   // personal|org|global
	Subject   string           `json:"subject"` // user|org
	Metric    string           `json:"metric"`  // tokens|requests|cost
	Period    string           `json:"period"`  // day|week|month|all|custom
	Start     string           `json:"start"`   // "" for all
	End       string           `json:"end"`
	Rows      []LeaderboardRow `json:"rows"`
	Self      *SelfRank        `json:"self,omitempty"`
	Total     int64            `json:"total"` // ranked subjects in the window
	Available bool             `json:"available"`
	Source    string           `json:"source"`
}

LeaderboardView is the whole leaderboard response.

type SelfRank

type SelfRank struct {
	Ranked    bool   `json:"ranked"`
	Rank      int    `json:"rank"`
	OfTotal   int64  `json:"ofTotal"`
	Requests  int64  `json:"requests"`
	Tokens    int64  `json:"tokens"`
	CostCents int64  `json:"costCents"`
	Metric    int64  `json:"metric"`
	Handle    string `json:"handle"`
	Listed    bool   `json:"listed"` // is the caller publicly listed (opted in)
}

SelfRank is the caller's own standing on a user board, INCLUDED even when the caller falls outside the top-N page. Ranked=false means the caller has no usage in the window (unranked) — the client shows "—", never a fabricated rank.