TIER /api/v1 compatibility contract

v0.7.0 identity, coaching and retention: Developers and their declared viewers can open verified coaching cards, with every view logged before construction. Real-data developer startup requires an active permitted viewer credential, a nonempty admin token and a named audited operator. Shared reads are name-free. Writable developer mode starts raw-data retention at startup and daily; once armed, it continues in team/division mode. See developer access and upload identity for current commands and restrictions.

This document is the stability contract for TIER's HTTP API. It pins, for every /api/v1 endpoint: its stability guarantee, its response schema, and the project's rules for what may change without a version bump and what may not.

It exists because a JSON field's meaning can change while it stays parseable, and nothing in the wire bytes announces it. #187 demoted the top-level /scores developers/teams/total fields to a pooled back-compat summary that is explicitly not a cross-type ranking, with no version signal and no changelog a consumer could detect. External orgs scripting against /scores kept computing a comparison the project itself now calls a category error. This contract makes that class of change announced and detectable instead of silent.

The Go response structs in internal/api/ are the authoritative field definitions; this document must be kept in step with them (see Changing the API).

• Base path: /api/v1 (the Prometheus scrape at /metrics is the one documented exception, mounted at the root).
• Scope: single-process, single-tenant. There is no /v2 today.
• Out-of-scope HTTP surfaces: the inbound POST /webhook/github seam (mounted at the root when TIER_WEBHOOK_SECRET is set) and the dashboard UI at / are not part of this /api/v1 contract — the webhook is a GitHub-governed wire seam (see the JSONL ingestion contract) and the dashboard is UI, both governed separately.
• Encoding: UTF-8 JSON unless noted. The four bulk exports also emit CSV via Accept: text/csv.

#1476 — root-authored vendor mappings, Part 1

These additive routes require root authority in both handler and store. Root browser sessions use the existing same-origin and mutation CSRF checks; root bearer scripts remain supported. Other credential kinds and static tokens get 403. In read-only serving, POST on the collection path returns 405 because GET shares that path; End and Void return 404 because their routes are unregistered.

Mapping fields are tenant_id, id, vendor, vendor_user_id, developer, effective_from, created_at, created_by, nullable ended_at and voided_at. The effective date is server-owned: the next UTC midnight. Mapping interval strings use the event timestamp's UTC storage format; creation uses fixed-width RFC3339 UTC. Bulk creation accepts 1–200 pairs, atomically, with one audit row per pair, with a dedicated request cap that accommodates 200 maximum-length IDs. Normalized IDs are limited to 320 bytes and cannot contain control characters. Targets must be canonical roster people who have not left. Invalid IDs, unknown people, unknown JSON fields and query parameters get 400; conflicting active mappings or repeated closure get 409; missing IDs get 404. Void may follow End and permanently removes past counting eligibility. Reconciliation reads ended and voided mapping partitions too: ended intervals accept late usage; voided partitions reverse into legacy spend inside the lookback. A hard-deleted mapping partition leaves its day incomplete without deltas or settlement, while later days continue ingesting.

DSAR exports add vendor_mappings when nonempty and vendor_mapping_id on mapped events; a NULL vendor_mapping_id is omitted to preserve pre-mapping export shapes. Erase receipts add vendor_mappings when rows were removed. Empty additions are omitted to preserve legacy response shapes. Existing sealed report bytes and the legacy route golden remain unchanged. Poller wiring and the Unmapped panel follow in Parts 2 and 3.

#1431 — real-person census and upload freshness

D4 changes the k census: only rostered non-bot fixed named_subject identities with bound_upload from their own local credential or server_watch evidence in the window count. Root-mapped vendor evidence also counts when its insert-time binding remains valid; roster-login matches and legacy aliases alone do not. Census and coaching share the same evidence predicate, including the own-credential check. Shared/legacy uploads, manual costs, roster-only people, imported-unbound people and federated people cannot fill k. Device count does not increase person count. This breaks formerly visible shared-token group reports; amounts retain existing aggregation rules. Seal schema 21 adds nullable sealed_report.census_rule_version (d4-c2-v2 for new seals, d4-c2-v1 for earlier D4 seals, unknown for older ones). Census rule d4-c2-v1 is introduced by seal fold rule 3 (the upgrade from fold rule 2); the fold-rule number versions grouping, census and folding together, while the census name identifies the D4 evidence rule. Schema 21 prevents older binaries opening the database. Rule 2 seals retain their stored config digest and frozen inputs and still read and verify successfully.

The A′ legacy-golden ruling changes exactly two rows: GET /api/v1/scores, api-token admin, evaluationMode=true, fixture=evaluation-window, with aggregation team and division (admin token configured, writable routes). Those fixtures label uploads bound_upload without a credential, a state no release writes. D4 counts them zero, so the evaluation responses lose their previous counted-person shapes. The seal golden changes only config_digest for fold rule 2 → 3; its body stays unchanged. Evidence written by dev builds between 2026-10-24 02:42Z and 22:16Z with this missing credential no longer counts toward k. The fixture remains unbound so the legacy freeze exposes D4.

The A′ extension to coaching changes the 16 affected legacy coaching-card rows from 200 to 404 under the synthetic no-credential fixture: 11 on GET /api/v1/developer/{id}/coaching and 5 on its GET /api/v1/scores/{developer} alias. Other legacy route schemas and export contents retain their previous contract. Coaching events, named spend and excluded-spend share use the census's exact evidence predicate. D4 exclusion causes are confined to the root-only reporting message; legacy diagnostic categories remain unchanged.

Fresh is age <24h; Stale is 24h through exactly 7d; Silent is >7d; Never is no bound receipt. Legacy NULL credential_id receipts are Never. People, device and self views preserve Silent and the last upload date or time after retention using persisted upload-credential receipt metadata older than the retention watermark. Summary reporting includes the exact 7d boundary and excludes departed people. Its k gate uses qualifying evidence in the same seven-day window: server receipt time for uploads, event time for watch evidence; bots cannot fill k. Eligibility and reporting use the same precise receipt-time comparison, including fractional seconds. The existing tree complementary suppression gates the full forest before selecting a subtree, preventing parent-minus-children disclosure of a sub-k sibling. At evaluation k=2, tree suppression conservatively retains its shared floor of 3; k=1 has no positive sub-k residual. Root evaluation reads use the configured evaluation floor and carry evaluation_mode: true; node keys always retain the shared floor of at least 3. All reads are no-store; invisible subtree targets return 404. Shared/read tokens are refused on these routes and receive neither date nor chip fields. /org/people and device lists retain their array shapes. The node summary is the separate route above.

Admin web identity and sessions (#1417)

These routes are separate from the legacy admin/read scopes and mounted in normal and read-only serve, in every aggregation mode. Synthetic demo and trusted offline replay do not mount them. All responses, including refusals, use JSON (except 204), Cache-Control: no-store, CSP and nosniff.

node.path is a root-first array of node names. A root key with no node uses empty node id/name/level name and an empty path. capability is empty for root and personal keys. pages describes role navigation; it does not grant access to APIs that are not built. The JSON body never includes credential secrets, verifiers, labels, prefixes or token lengths. Node keys resolve their own node binding; personal keys use current holder membership. Revoked credentials and holders with left_at are refused on every request.

Missing/unknown credentials return 401; wrong kind, legacy keys, break-glass, CSRF/Origin violations and insecure off-loopback sign-in return 403. Cookie and bearer together, malformed JSON, unknown fields, trailing JSON and unsafe return paths return 400; wrong content type returns 415. Rate/lockout returns 429 with Retry-After for lockout. Store or session-capacity failure returns 503. An explicit cross-origin Origin is refused even with same-origin fetch metadata. Sign-in bootstraps CSRF; every later cookie mutation requires the session-held token. Org administration writes sent with a bearer and no cookie need neither CSRF nor Origin (below). Cookie-authenticated GET /api/v1/me also returns that session's CSRF token in the X-CSRF-Token response header, allowing a newly loaded page to sign out without persisting the token in browser storage. Bearer reads and refused requests do not return that header. This does not change the JSON body.

The static dashboard shell (#1437, plan P20) serves /signin, /org, /people, /keys, /devices, /card, /federation, /coverage, /settings, /import, /import-source, /upstream, /first-run and /admin.js. All dashboard pages and scripts, including legacy / and /dashboard.js, carry CSP, X-Content-Type-Options: nosniff and Cache-Control: no-store. The new pages use cookie-authenticated /api/v1/me for identity and allowed navigation; pages awaiting their APIs have only a labelled, empty body. Static HTML is public and confers no API access. Shell pages and /admin.js return 404 when admin web is disabled (synthetic demo or unsealed recompute). Every shell page, including auxiliary pages, requires inclusion in /me.pages; pages missing that grant keep their URL and show the access-denied page, “This page is outside this sign-in”, with a link to the first allowed navigation page. Keys and My devices also require their role navigation grant, even if an incorrect allowlist includes the page. Import pages additionally check the role: a personal or node key opening Company import, or a node key opening Source export, returns to its first allowed navigation page before any import loader runs. Only a 401 identity response opens sign-in; other failures keep the shell with a session-check retry state. Sign-in distinguishes rejected keys, 429 lockout (with Retry-After seconds), unavailable service, network failure and conflicting session requests. Sign-out clears local shell state on success or 401/403; other failures retain it and show that sign-out did not complete. The legacy dashboard assets and read-token flow remain unchanged.

The People and Settings pages (#1449, plan P22/P24) use the existing org APIs. People lists the authorized subtree, invites managers only into native strict descendants, and confirms move, leave, root viewer declarations and typed root erasure. Add-person and recovery responses show the claim code once; manager invitations show the node key once. Hide, same-tab navigation, pagehide and session loss clear the transient result. Neither value is stored or put in a URL. Root sees reuse-refusal flags from the existing org audit beside recovery actions. A non-root self-granting move remains available and displays the API's 409 refusal. Actions never render server error bodies: 403/404 use the approved refusal copy, and 429 uses Retry-After seconds when present, disabling actions during the wait. Move choices exclude the person's current node. Other than viewer-declaration refusals, 400 responses ask for request correction and retry. Open card links resolve to /card for the holder and /api/v1/scores/{dev} for a declared viewer. The leave-date default, maximum and submit guard use the UTC calendar day.

Settings shows resolved values and sources; explicit pins disable controls and saves for that setting. Saves carry the session CSRF token. Retention lowering shows the server's exact preview and confirms the identical request with its confirmation token. /first-run is included in root's /me.pages; its evaluation control uses the same settings API and honors pins. The setup prompt appears only when the People inventory has at most one person. /card shows the signed-in subject's declaration and effective-access notices from /api/v1/me/notices, including both granted and removed viewers; reading notices adds no write. It also shows the viewer, label, route and time from GET /api/v1/me/views. This personal-key bearer/session route returns only the resolved holder's coaching_view_audit rows as [{viewer,label,route,ts}], or []. It accepts no query parameters (400) or caller-supplied subject. Root, node and legacy tokens receive 403. It is mounted in normal and read-only serve in team, division and developer modes, writes nothing and needs no verified spend. The card routes still return 404 without verified spend in the window. Responses and refusals are no-store; identity/session errors follow the rules below.

The cookie is HttpOnly/SameSite=Strict/Path=/, with Secure and the __Host- name prefix whenever the effective origin is HTTPS. On permitted plain-HTTP loopback it uses the plain tier-session name without Secure. Both names have a serving-port suffix on nonstandard ports. A cookie-bearing admin-web request with an explicit foreign Origin is refused before session lookup or rate accounting, including GET; absent-Origin GET fetch-metadata rules are unchanged. Sessions expire after 60 minutes idle or 12 hours total, are re-resolved on each request, and disappear on restart. Sign-out uses a cookie session; scripts retain bearer reads. See identity access for the trusted-proxy and sticky-startup contract. Legacy route status, access and cache behavior are unchanged: legacy routes never read the admin session cookie, so a live or stale cookie neither authorizes nor refuses there. A root, node or personal key sent as a bearer to a legacy route is refused 403. Legacy export carries node_id on org_hierarchy and hierarchy_membership rows, and the subject's org records in org_people and org_audit. Legacy erasure reports every erased table in deleted, org_people and org_audit included, and total_deleted is their sum; a subject with only org records is erased with 200, not 404.

Federation wire contract (#1430)

internal/federation defines the pure tier-federation/v1 push payload in docs/contracts/tier-federation-push.schema.json. This package adds no HTTP route, authentication, persistence or outbound traffic. Every field is required and non-null; empty lists use []. Decode refuses unknown fields, duplicate keys, case-altered property names and trailing JSON. Bodies above 1 MiB return typed code too_large; a supplied contract other than exactly tier-federation/v1 returns bad_contract; other invalid input returns malformed. These are package codes, with HTTP mapping left to the transport.

Each period requires k ≥ 3, an end after its start and a matching digest; the payload requires a canonical lowercase UUID server id and seq ≥ 1. All org-node ids use the same exact 8-4-4-4-12 lowercase hexadecimal UUID spelling; parent ids may also be empty for the root. Duplicate period bounds, duplicate group ids within a period and groups that name themselves as parent are malformed. sent_at, period_start and period_end must be byte-equal to their UTC time.RFC3339Nano encoding (Go layout 2006-01-02T15:04:05.999999999Z07:00), ending in literal Z. Fractions are optional, use 1–9 digits and have no trailing zero; offsets including +00:00 and -00:00 are refused. Integers use whole-number syntax without a fraction or exponent (5.0 is refused). The schema bounds k to the 64-bit Go int maximum, sequence and micro-costs to int64, and points to finite float64 values. The digest is sha256: plus lowercase hexadecimal SHA-256 over the complete period with only digest omitted. Object keys are sorted recursively, with compact Go JSON encoding and HTML escaping disabled (&, < and > remain literal), shortest round-trip floating-point numbers and exact integer micro-costs. Array order and group names are significant; accepted timestamp strings survive re-encoding unchanged. The golden fixture pins the marshalled shape; regeneration is explicit through go test ./internal/federation -run '^TestPayloadGoldenV1$' -update.

Closed periods are frozen increments under the append-only federation design. Sequence replay checks, exact retries and period-conflict handling belong to the receiver; this package validates each payload independently.

Org administration routes (#1421, #1422, #1423)

These routes are available in every aggregation mode outside synthetic/offline replay. GETs accept root/node/personal credentials as specified below, via bearer or session; unknown, repeated or undecodable query parameters give 400. Per D2, a mutation sent with a bearer and no session cookie (a script) needs no CSRF token and no Origin; a cookie-session mutation requires the server-held CSRF token and exact Origin (or same-origin fetch metadata when Origin is absent). Both require JSON content type; cookie plus bearer is 400. Every response, including errors, is no-store. Read-only serve mounts the GETs and an explicit 403 refusal for claim redemption; other mutations are absent. Legacy credentials and break-glass are denied. Every successful write arms the D1 admin-web flag in its own transaction.

The key inventory is [{credential_id,holder,label,kind,capability,node_path:[], issued_at,revoked_at,used,last_data_date,freshness}]. Capability, revocation and last-data date are nullable; paths are root-first names. Inventory never selects or returns credential secrets, hashes, prefixes or lengths. Personal device responses add exact last_data_at, and manager/root-added devices include added_by and added_by_label; ancestor inventories contain dates only. Freshness is Fresh (<24 hours), Stale (1–7 days), Silent (>7 days), or Never. used includes persisted last-seen or data receipt, excluding sign-in. People claim state is invited (with claim_expires_at), claimed (with claimed_at), expired, or left; pre-claim legacy people can be uninvited, and a cancelled code can show cancelled. Codes never appear in lists. Lists derive expiry without writing; it is audited and notified once by the next redemption, reissue or leave. People status is active, not_counted, imported_unbound, or left; creation starts not_counted. left_on and last_upload_date may be null.

Malformed bodies, unknown fields or trailing JSON give 400; wrong JSON content type gives 415. Missing/unknown keys give 401; wrong kind/capability and CSRF or Origin failure on a cookie mutation give 403. Hidden or missing targets give 404; a visible source move without authority over both parents, or a change to a key listed in the caller's inventory that it may not change, gives 403. Duplicate active labels (per holder and kind, and per binding for node keys), existing people, cycles, invalid tree level/depth, nonempty deletion, level-0 renaming, operations on already-revoked keys and reissue for an inactive holder give 409. Node removal also returns 409 while a leaver placed there holds any unrevoked key. Root's full key inventory retains revoked keys after their placement node is removed. A move to the current parent is a no-op with no audit row. A subtree with people cannot move to another level-0 org (409); its placement, dated membership and billing membership stay unchanged. Empty subtrees can move between orgs. Credential rate limits (60/minute, shared with sessions) and the persisted people cap give 429. Write lock contention gives 503 with Retry-After. Reads resolve one snapshot; writes re-resolve the verifier and authorize against the tree inside the same write transaction as mutation, audit and sticky activation. All successful writes are audited with opaque actors and D10 named/free detail separation.

Time to merge (#1342, v0.6.2)

GET /api/v1/time-to-merge is read-scoped, including on the read-only server. It is a descriptive measure, not covered by verify. Calling it never writes or changes a seal or the /scores response. For anonymized sealed months, median and p90 are stored at seal time and never recomputed; counts, including exclusion and contributor counts, are not published. Live windows retain their existing statistics and counts. Its definition is pr_created_to_merged, labelled PR created → merged (includes draft time): merged_at − created_at, using both captured timestamps, including timestamps stored by backfill. It never substitutes outcome ts for merge evidence. Quality, points, cost, labels and correction eligibility do not weight or filter a duration.

In team/division modes, parameters and the sealed-read gate match /scores: only ?period=YYYY-MM is accepted, with omission selecting the latest sealed month. Free since, until and before bounds are refused with 400; no sealer returns 503. Sealed figures use the score seal snapshot, with median and p90 computed once inside the seal transaction. Every count is null with null_reason: "sealed_counts_not_published"; exclusion reason counts are null as well. Months sealed before these statistics were stored return null median and p90 with null_reason: "sealed_before_ttm_stored", and are never backfilled. The dashboard passes the same period as its /scores request.

The synthetic demo keeps the existing /scores window helpers: since, until, and before (the legacy alias for until), with UTC whole-day bounds, half-open [since, until) selection by outcome ts, default since 90 days ago at UTC midnight, and omitted until meaning open-ended. Invalid/unknown parameters return 400; retention violations return 422. This is an org-wide read: repo, team and work_type are not accepted. Aggregation mode is the server's existing setting, never a client mode parameter. Real-data developer mode returns 403 before store reads. The synthetic demo uses the team fold and echoes window.aggregation: "team"; its four synthetic authors are below k=5, so its tile is withheld rather than publishing group figures.

The frozen wire shape is:

The following example describes a live window; sealed months use the null-count rules above.

{
  "definition": "pr_created_to_merged",
  "window": {"since": "2026-10-01", "until": "2026-11-01", "aggregation": "team"},
  "groups": [{"team": "Engineering", "count": 10, "median_seconds": 14400, "p90_seconds": 86400, "null_reason": ""}],
  "residual": {"team": "other", "count": null, "median_seconds": null, "p90_seconds": null, "null_reason": "authors<k"},
  "total": {"count": null, "median_seconds": null, "p90_seconds": null, "null_reason": "withheld_with_group"},
  "excluded": {"count": 0, "reasons": {"no_created_at_before_capture": 0, "no_created_at": 0, "no_merged_at": 0, "bot": 0}, "null_reason": ""}
}

The row key is team, matching /scores (also in division mode); window.aggregation identifies its level. groups is always an array in label order; residual is an object with key other only when the shared fold actually emits that cohort, and is otherwise omitted. Omitted until is not echoed. A group or residual with no included PRs has null figures with null_reason: "no_prs", which does not withhold the total. For nonempty figures, counts and both statistics are null with null_reason: "authors<k" unless at least k distinct census-counted developers each authored an included PR in that figure. k has the same MinKAnonymity clamp as /scores.

The endpoint shares the score window load, canonical aliases, dated membership, census and PreFold/AggregateFolded rules. A group folded in /scores folds into the same residual here; if /scores withholds all rows because its residual is unsafe, this endpoint withholds them too. It may withhold more: a named score group failing the PR-author floor keeps its row with null figures. Its PRs never move into the residual. The residual independently requires k counted PR authors. No org-wide duration total is implied by a sum of group medians.

Strict protected org total. total has count, median_seconds, p90_seconds and null_reason, with no team key. It is computed over every included PR in the window, using the same statistic rules and k distinct counted PR authors at org level. Below org-k, all three figures are null with null_reason: "authors<k". An empty total instead has null figures with null_reason: "no_prs". Otherwise, whenever a group or residual with included PRs fails its floor, all three total figures are null with null_reason: "withheld_with_group". An absent residual or a cohort with zero included PRs does not withhold the total. No group failing the PR-author floor is added to that residual. This strict complementary suppression prevents subtracting a published total to recover a hidden cohort, mirroring /scores (#593). A group's short-sample p90 (n<10) is not a withheld cohort: its count and median are published, and it does not alone suppress total. The total's own p90 is null with reason "n<10" when its included n < 10.

The dashboard tile beside the headline says Time to merge · PR created → merged (includes draft time). A published total shows median X h · N of M merged PRs measured, with N = total.count and M = total.count + excluded.count, both org-wide. M is this defined reporting denominator; the exclusions can include push-only/API rows, so it is not a separate census of GitHub PRs. A withheld total or excluded block explicitly says Time to merge: withheld to protect small groups, without numbers or a denominator. An empty window with no exclusions says Time to merge: no merged PRs measured; malformed or missing figures say Time to merge: unavailable. p90 appears on hover and in off-screen screen-reader text for n ≥ 10. The tile is neutral, wraps at 390px, and states: "smaller or later-created PRs merge faster; not a quality measure".

Statistics are unweighted whole seconds. The median requires n ≥ k and is the middle value for odd n, or the arithmetic mean of the two middle durations for even n. Durations retain subsecond precision through that calculation; the result is truncated to integer seconds. p90 is nearest rank sorted[ceil(0.9*n)-1], truncated to integer seconds. For n < 10, count and median can be present but p90 is null with null_reason: "n<10" applying only to p90. No mean duration is published.

excluded.count and its four reason counts cover the whole org only; they never appear per row. The author set covers every outcome in the population, including excluded evidence, using the canonical census counting rule and excluding bots and unattributed identities. Below k counted authors, or whenever /scores suppresses its residual, excluded.count and excluded.reasons are null with excluded.null_reason: "authors<k". An empty population with no included PRs or exclusions uses "no_prs" with the same null fields; a published block has null_reason: "". Each excluded outcome is counted once, in this precedence order:

1. bot: the same canonical bot classification as the census (captured GitHub type, fixed login list or [bot] suffix), including alias-carried marks.
2. no_created_at_before_capture: a webhook/backfill PR with NULL created_at and outcome ts before 2026-10-11, when commit 840fa8da introduced capture. This is the column's release date, not this installation's upgrade date; later upgrades classify missing evidence on or after that date as no_created_at. It does not invent a creation date.
3. no_created_at: other NULL creation evidence, including push-only/API rows, and a PR whose created_at fell after its merge. Both the webhook and backfill store NULL in that case; the read also rejects inverted evidence.
4. no_merged_at: creation evidence exists but merge evidence is NULL.

Pseudo-developer rows are dropped as on /scores. Webhook and backfill sources are both included when both timestamps are present, including old merges captured by a later backfill. Smaller or later-created PRs merge faster; not a quality measure.

Pricing provenance additions (#1231, #1232)

POST /events accepts optional cache_write_evidence (nested or legacy; omitted means unknown). legacy with a nonzero 1h write count is refused. The receiver derives costs and basis; clients cannot declare a pricing snapshot or rule. Shippers preserve the evidence on current receivers and retry once without additive provenance/PR fields only for an exact unknown-field 400 from an older receiver. Other 400s retain their usual failure behavior.

GET /events appends pricing_basis, rate_snapshot and cache_write_evidence to JSON and CSV; the previous columns retain their positions. Bases include token_derived, guessed_estimate, caller_authoritative, aggregate_approx, legacy_aggregate and basis_unavailable; historical nulls export empty strings. Snapshot identities resolve inside the operator's database to immutable effective rates and a retained rule implementation.

/scores and each /scores/compare window add data_quality.aggregate_pricing when provider remainders exist in developer mode. It carries cutover, approximation/historical notices, row counts, ceiling_status and, where positive, possible_increase_micro. This is an original-rate highest-rate-per-class diagnostic, not proven overbilling. It bounds the retained rate effect on aggregate counts, with one aggregate rounding step; per-request rounding and unrecorded fees are outside that calculation, so it is not a provider-invoice bound. A full ceiling is unavailable for missing, unsupported or estimated original bases (or sum overflow); a partial known-rate amount does not bound the whole window. Anonymous modes always emit the same conditional notice with ceiling_status=not_shown and no amounts or populations. All read responses also carry constant X-TIER-Aggregate-Pricing policy text, including CSV/array views and older sealed bodies without pricing metadata. New sealed responses retain the emitted notice; old sealed bytes are not rewritten or overlaid with current metadata. The dashboard shows conditional policy text when metadata is absent. Request-level tier arithmetic, raw numeric columns, actual-paid reconciliation and completed-poller retry semantics are otherwise unchanged. See the policy and repair commands.

Per-issue report addition (#1273)

GET /api/v1/issues is a read-scoped, live developer-mode-only report, also mounted by the read-only server. Both team and division modes return 403 before reading data, including on sealed installations. No issue-level k-anonymity or tracker hierarchy is implied. Existing /scores routes and response shapes are unchanged.

Issue-id misfiling. Pull-request points and captured spend do not depend on issue ids. Misfiling can merge or split direct-push credit (one 0.5 per issue per UTC day per repository) or change which outcome a footerless revert penalises, so headline TIER can move and per-issue rows can be wrong. See the measured rate and how to avoid it.

Parameters are since, until, before (the existing alias for until), and repo. Bounds use the /scores grammar (YYYY-MM-DD, YYYY-MM, YYYY), UTC midnight and half-open [since, until) semantics. Omitted since defaults to 90 days ago at UTC midnight; omitted/empty until is open-ended, and its echo is omitted. Invalid bounds, non-increasing windows, invalid repository slugs, and unknown parameters (including sort=tier) return 400. Retention violations return 422. repo is strict equality; repo_scope_excluded, when present, discloses excluded unqualified records exactly as on /scores. All totals and shares use the selected scope and window.

The report consumes the same loadWindow path and scoring engine as /scores, with stored Event 3 policy and outcome projections read in one snapshot. Unresolved policy/projections refuse the report (500, db error). The additive wire shape is:

Each reconciliation row has kind (issue or unattributed), repo, issue_id, label, unattributed_share, cost_usd, weighted_points, outcome_n, sample_n, flagged_outcomes, tier and score_status. Issue rows carry the literal attributed (lower bound) label and the window's unattributed share beside their figures. Unattributed rows carry label unattributed and retain the sentinel issue_id as the reason (including unattributed:<reason>); an empty historical issue ID is also unattributed. Such rows have no TIER. unqualified repository identity (including historical empty repos) is retained as stored; it is never assigned to another repo by a tolerant join for this partition. Cost is accumulated in integer micro-dollars before conversion to USD; floating point JSON sums should be compared at that precision.

Rows are ordered by repository then issue ID, with unattributed rows last, never by TIER. The union includes spend-only and outcome-only issues. All spend tied to the stored (repo, issue_id) stays in that row's denominator, even from developers with no outcome. Each outcome contributes once; Event 3's debit stays on the corrected original's issue while the follow-up's own projected points stay on its own issue. outcome_n counts raw outcomes and sample_n counts the shared engine's eligible observations. Points are summed, then divided by summed issue cost / 1000. The evidence floor is applied after summing, never per developer: at least 3 eligible outcomes, at least $5, and no zero-token flags. Only then is tier a number with score_status: "scored" if repository identity is also unambiguous. A row with a repo-blind identity (the same definition used by store.RepoMatch), or a real-repo row whose issue ID has repo-blind spend or outcomes in the selected window/scope, always has tier: null and score_status: "repo-blind spend on this issue id". This status also covers outcome-only ambiguity. The disjoint stored rows are unchanged: no blind spend or outcomes are reassigned to a real repository. For example, $5 on acme/app#1 and $45 on unqualified#1 remain separate rows, and neither publishes a TIER. Absent that ambiguity, unattributed rows have no score; issue rows with zero-token flags have zero-token outcome; zero eligible accepted outcomes have no score; other insufficient evidence has below evidence floor. Each withholds TIER as JSON null, never a low numeric score. These partial denominators make issue TIER unsuitable for direct comparison with an all-spend developer score. No feature/parent rollup or seal is created by this endpoint.

tierd issues --server <url> [--since <date>] [--until <date>] [--repo owner/repo] prints this report, cost-horizon and mixed-price disclosures, and its reconciliation; --json prints the validated server response bytes, preserving additive wire fields. A covered window explicitly reports window_predates_cost_capture: false; a store with no captured cost has no horizon to report. A single-price window omits mixed_price_versions. It accepts --api-token (including @file) or TIER_API_TOKEN, allows the read token, refuses redirects and returns nonzero on mode/auth/server/decode failure. The dashboard's developer-mode per-issue table uses the same endpoint; it never fetches this breakdown in team/division mode.

Live issue reports may add as_of and attribution_notice when recovery is used: “scores are as of <ts> and may be revised as branches merge”. A reconciliation row with recovered support adds attribution_layer: "read_time_recovery" and read_time_recovery_cost_usd (omitted for a zero-dollar recovered portion). This marks mixed rows as including recovery. Developer-mode /scores and its per-issue developer detail add the same layer marker where applicable. All read routes except GET /api/v1/report_manifest and sealed reads carry the population-independent X-TIER-Attribution disclosure; stored sealed bodies stay byte-identical. Raw event exports continue to report stored attribution. See effective attribution and the read-only recovery receipt.

Feature detection

The supported feature-detection mechanism is the version field of GET /api/v1/livez. It is the build version the binary was compiled with (injected via -ldflags; falls back to "dev"). A client that needs to know whether a server supports a given field or endpoint should read livez.version rather than probing behaviour, except for the narrow events fallback below. livez is unauthenticated (a liveness probe must not need credentials), so feature detection never requires a token.

Identifying a deployment: GET /api/v1/version

Feature detection asks "what can this server do?" — a different question from "is this the build I published?" For the second, use GET /api/v1/version, also unauthenticated and also mounted in read-only mode.

🔴 First released in v0.4.1. A server running v0.4.0 or earlier answers 404 here — verified against the published 0.4.0 container image. The published v0.4.1 release binary answers 200 with its commit (measured 2026-09-25); the response below is the exact body it returned.

⚠️ 404 on this path does not mean the server is unhealthy or the wrong build — it most likely means the build predates the route. On a v0.4.0 or older target, identify a deployment with GET /api/v1/livez, which has always carried version. Note that reports the release, not the build: two binaries from a moved tag share a version string, which is exactly why this route exists.

{
  "version": "v0.4.1",
  "commit": "ec6ff60fd72c6824c22d2c01e58cdc444d49fcce",
  "modified": false,
  "go_version": "go1.26.6",
  "platform": "darwin/arm64",
  "price_table": { "version": 9, "effective_date": "2026-07-26" }
}

commit is the revision injected at build time (make build, the release binaries and the published container image set it); without that, it falls back to the vcs.revision stamp the Go toolchain embeds. modified comes only from the stamp. On a binary built with -buildvcs=false, or from a tree with no .git like the shipped container, there is no stamp and modified is omitted, never false. Absent does NOT mean clean (see GET /api/v1/version). commit is also carried on livez — additively, so an existing liveness probe is unaffected.

🔴 Why version alone is not enough, and why price_table.version is a trap. A tagged release reports the same version string however it was built, so two binaries from a moved tag are indistinguishable by it; commit is what makes "this deployment is the build I published" an assertion rather than a hope. And price_table.version bumps only when prices change: measured 2026-08-06, a deployment reported price table 9 while the newest source was also 9 — while the running binary was a full release behind. It is useful next to the build (it answers "which rates priced these numbers"), never as identity.

⚠️ A version check is only meaningful if it can say NO. Assert the expected commit, and make sure your check fails when pointed at a different build — otherwise "the version matches" is indistinguishable from "the check never ran".

Do not rely on the presence or absence of an individual response field for feature detection at runtime: additive fields (below) can appear at any release, and omitempty fields are absent whenever their value is empty even on a server that fully supports them.

Price-table content identity (#713)

On GET /api/v1/scores and GET /api/v1/scores/compare — and in tierd score-log's JSON — the price_table block carries two digests alongside version and effective_date:

🔑 Why the resolved table, not the file. The server bakes provider-default cache multipliers into every model at parse time, and those defaults come from code, not from the YAML. Change the compiled-in Anthropic cache-read multiplier and every cached-token cost in the system changes while the YAML is byte-identical — a hash over the file would certify "same rates" across a real rate change, which is worse than no hash. table_hash moves; file_hash does not.

The pair runs the other way too: a comment-only edit to the price YAML moves file_hash and leaves table_hash alone, so source-URL comments stay auditable without re-identifying the prices.

What each answers.

• version answers "which published revision of the reference table is this". It is a human-assigned label; two installs can both report 9 while one runs a --prices override that moved a rate.
• table_hash answers "do these two installs hold the same resolved price inputs". It deliberately excludes version and effective_date, so "content unchanged, version bumped" and "version unchanged, content changed" stay distinguishable.
• file_hash answers "is this the same source document".

⚠️ The scheme tag is load-bearing — compare the whole string, never the hex alone. tierpt1 names the CANONICALIZATION, and it will be bumped if the serialization ever changes. A consumer that strips the tag cannot tell "computed by a different scheme version" from "these two disagree about prices", and a guard built that way would reject every install on the older binary the first time the scheme is legitimately fixed.

🔴 These are UNKEYED digests, self-reported by the server. They are not a signature. Against an operator who controls the deployment they prove nothing — such an operator can change the table and report any hash they like. What they detect is what they are for: accidental drift between installs, an edit to the price YAML on a host whose binary you already trust, and a serializer that cannot tell two different tables apart. Do not build an attestation on them.

✅ Since #714 table_hash is also load-bearing at STARTUP, not only for comparison. A deployment records the identity of every price table it serves and refuses to open a database in which one version: integer would come to denote two different tables. See reference-price-table.md §9. That does not strengthen any claim below — the digest is still unkeyed and self-reported — it just means a mismatch now stops a boot instead of only informing a comparison.

🔴 table_hash equality is NECESSARY, not sufficient, for comparing costs across installs — and the omission that matters most is the binary. Equal digests mean equal price inputs. The pricing logic is outside the digest and cannot be inside it: which row a given model resolves to is decided by code (model-name normalization, the host-qualified key, and the self-hosted size-class patterns — that pattern list has already changed once, in #267, and altered pricing). So two installs on different builds can report the same table_hash and still price the same event differently.

Before comparing figures across installs, match all of:

⚠️ Do not treat a published digest as a trust anchor. The value changes on every price-table edit, and no gate keeps a copy pasted into a document (this one included, which is why the sample above shows the shape rather than a value). Read it from the deployment you are asking about.

🔴 The digests are NOT on GET /api/v1/version, deliberately. That endpoint is unauthenticated — identifying a build is a probe concern — and it returns price_table: {version, effective_date} only.

An unkeyed digest over a low-entropy price table is a confirmation oracle: someone who can guess a private --prices file confirms the guess in one hash, and an install running the shipped table with one negotiated rate edited is grid-searchable on that rate. Publishing that from an unauthenticated endpoint would have pushed the mitigation onto ingress configuration that many self-hosted installs do not have.

The convenience it would have bought — answering "same build and same prices" from one probe — is not needed: a third party verifying a published report reads the digests from that report's own manifest, never from a live endpoint. So this costs nothing and closes the oracle outright.

⇒ Read table_hash from /scores, /scores/compare, or GET /api/v1/report_manifest (#715 -- the report manifest this paragraph anticipated, now a real endpoint). Read commit from /api/v1/version. The two questions have two sets of endpoints, and that is the intended shape.

Query parameters are STRICTLY validated on the scores endpoints (#590)

GET /api/v1/scores, GET /api/v1/scores/{developer} and GET /api/v1/scores/compare reject any query parameter they do not implement with 400, naming the offending parameter and listing what is accepted. Matching is exact and case-sensitive: ?Repo= is not a synonym for ?repo=, it is an error.

⚠️ This is a deliberate behavioural break, and it is recorded as one rather than filed under "additive". Before #590 these endpoints silently ignored unrecognized parameters, as net/http does by default. A client that sends an extraneous parameter and previously got 200 now gets 400.

It was taken because the alternative is worse than a break. /api/v1/scores accepted ?repo= and ignored it, returning a whole-installation aggregate byte-for-byte identical to a correctly scoped one. A caller who believed they had scoped a query received a figure spanning every repository, with no way to detect it from the response. Adding the filter without this strictness would have left the same trap one keystroke away -- ?repos=, ?Repo=, ?repo_id= would each silently widen a query back to installation-wide while the caller's own assertion passed, asserting nothing.

The invariant, stated once: "could not scope" must never share a response shape with "scoped, and this is the result." A silent wrong answer is worse than an error.

This extends to query strings the strictness the write endpoints have always applied to request bodies (DisallowUnknownFields(), see the compatibility rule). It is a request-side break, which is why it ships on /v1 rather than forcing a /v2: rules 2 and 3 above govern the RESPONSE schema, where a consumer's parsing breaks silently. A rejected request fails loudly at the caller, in the one place the mistake can still be corrected.

What a client should do: send only documented parameters, and detect scoping from the response (data_quality.repo_scope), never from the request it sent. Feature-detect via livez.version as always.

The compatibility rule

JSON responses are additive-only. A field's semantics are frozen once shipped.

1. Adding a field is additive. A new response field may be added at any release. Clients MUST ignore unknown fields.
2. Renaming or removing a field is BREAKING. It is not a refactor. It requires a new field name (additive) or a /v2 (breaking), never a rename-in-place.
3. Changing a field's SEMANTICS is BREAKING even when the type and name are unchanged. If the number a field carries comes to mean something different -- a different population, unit, scope, or definition -- you MUST either introduce a new field name for the new meaning or bump to /v2. You may not repurpose an existing field in place. This is the #187 rule: the demotion should have shipped the new meaning under a new key (it did -- work_types) and the change to the OLD keys' meaning should have been announced (it was not). The narrowly scoped #1095 security exception below permits replacing raw healthz error text with classes in place.
4. Closed-set (enum) values are additive too. A new allowed value for a string enum (source, fidelity, weight_source, work_type, work_type_source, billing_mode, watcher status) may be appended; an existing value may not be renamed or removed.
5. CSV column order is append-only. The four exports (GET /events, GET /outcomes, GET /quality_events, GET /quality_history) carry a positional CSV contract. Columns are only ever appended at the end, never reordered or removed, and an existing column's VALUES never change shape (issue_id stayed "issue-42" when repo arrived in its own new column, #231). This restates the contract already enforced in internal/api/export.go (eventsCSVHeader, outcomesCSVHeader, qualityEventsCSVHeader, qualityHistoryCSVHeader) and documented in docs/how-it-works.md. With Event 3 enabled, its conditional outcome columns precede issue_rule; positional consumers must read by header name.

Request bodies are strict in the other direction: the write endpoints decode with DisallowUnknownFields(), so an unknown request field is rejected 400. Adding a new optional request field is additive (old clients omit it); making a previously-optional field required, or adding a required field, is breaking.

Additive vs breaking at a glance

Announcing a deprecation or a semantic change

When a field or endpoint is being retired, or a field's meaning is changing (which ships as a new field plus a deprecation of the old one), the change is announced two ways:

1. The Deprecation (RFC 9745) and Sunset (RFC 8594) response headers on the affected endpoint. Deprecation carries the date the field/endpoint became deprecated; Sunset carries the date after which it may be removed (a /v2 or a removal). Together they replace the single RFC 7234 Warning: 299 header precedent on POST /costs (deprecating cache_write_tokens): Warning was deprecated by RFC 9111 and is dropped by some intermediaries, so it is not a reliable deprecation signal. Warning: 299 remains only for the one already-shipped cache_write_tokens case for back-compat; new deprecations use the Deprecation/Sunset pair.
2. An entry in the API changelog below, naming the field, the change, the release, and the issue.

A semantic demotion (a field's meaning narrowing or changing, like #187) MUST additionally:

• ship the new meaning under a new field name (never repurpose the old field), and
• document, in the old field's changelog entry and its Go doc comment, exactly what it now means and what a consumer should read instead.

Endpoint catalog

Auth scopes (see internal/api/handler.go):

• write -- requires the write/admin bearer token (Authorization: Bearer). The read-only viewer token is rejected 403.
• ingest -- POST /api/v1/events only: the ingest token or the write token (#1144). The ingest token is rejected 403 on every other protected route.
• read -- satisfied by EITHER the read-only viewer token or the write token.
• metrics -- GET /metrics only: the metrics token or the write token, and in developer mode also the read-only viewer token (#944). The metrics token is rejected 403 on every other route.
• open -- no token (probes only; never exposes spend data).

When the server is started with no API token (loopback-only, fail-closed per cmd/tierd), auth is disabled and all scopes are transparent.

Error bodies are uniformly {"error": "<message>"} with a 4xx/5xx status.

Write endpoints

Every POST, PUT and PATCH below requires Content-Type: application/json (parameters such as charset are allowed) and answers 415 otherwise, in token mode too (#893). Authentication runs first, so an unauthenticated request still gets 401. A DELETE carries no body and needs no Content-Type.

POST /api/v1/costs

• Scope: write. Success: 201 Created (fresh key, or an identical/ matching re-post), empty body -- or 200 OK (a sanctioned override actually corrected a row, #346), body {"corrected": true, "old_cost_usd": <float>, "new_cost_usd": <float>}.

• Manual single-row cost import. Request: costRequest -- developer, issue_id, model (required); input_tokens, output_tokens, cache_read_tokens, cache_write_5m_tokens, cache_write_1h_tokens, cost_usd, source, fidelity, idempotency_key (optional); override, override_actor, override_reason (optional -- #346, see below); billed_to (optional -- #854, see below).

• Per row, cost_usd must be finite and in 0..10000 ($10,000), including audited overrides. Every token field must be in 0..1000000000000 (1e12), after legacy cache_write_tokens normalization. An over-limit request returns 400 naming the limit and asking callers to split a large import across rows (#1082). /actual_spend and organization invoice limits are unchanged.

• cache_write_tokens is the deprecated legacy single-bucket field (superseded by the 5m/1h split, #55); when present and non-zero it is routed to the 5m bucket and the response carries the legacy Warning: 299 header.

• source accepts only "api" or omitted; fidelity accepts "daily", "estimated", or omitted ("realtime" is rejected -- reserved for automated capture).

• ⚠️ issue_id may not be the reserved unattributed sentinel (#466). The sentinel family -- the bare unattributed plus any unattributed:<reason> sub-bucket -- is server-assigned: the collector and the proxy write it when they genuinely could not resolve an issue. A client supplying it now gets 400; it was previously written silently. The check is case-insensitive and trims surrounding whitespace, so UNATTRIBUTED:main is refused too -- ingest deliberately rejects more than the read side matches, because a case variant in the table would classify one way in SQL and another in Go. Ordinary ids that merely contain the word (unattributed-work, not-unattributed) are unaffected. Same rule on POST /outcomes; POST /events is the documented exception.

• ⚠️ A row for a provider whose org usage poller this server runs is refused 400 unless it declares billed_to: "other" (#854). The Anthropic Admin and OpenAI Usage pollers bring the org's recorded usage for their provider up to the provider's own total, and they never subtract a /costs row, so a manual row for that org's usage would be counted twice. Manual posting and the poller are alternatives for one org: use one or the other. The refusal applies to every row whose model is priced under that provider (claude-* with the Anthropic poller, gpt-* and the other OpenAI models with the OpenAI poller), with tokens or cost only, after the same case, whitespace and date-suffix normalisation the poller applies (claude-sonnet-4-20250514 is refused too). A model the price table does not recognise is admitted and is not counted by the startup warning, even when it names a polled model another way, such as anthropic/claude-sonnet-4 or Claude Sonnet 4: the poller counted that usage under the canonical id, so if the row is the polled org's usage it is counted twice unnoticed. Post canonical model ids, the names in the price table.

  • The remedy. The 400 body names the provider and carries this text, which is also what the startup warning below prints. It is PolledProviderOverlapRemedy in internal/api/handler.go; that constant is the source, and this copy follows it:

    This server runs the org usage poller for this provider, which already counts the polled org's usage, so a manual row for that usage is counted twice. To post spend billed where the poller cannot see it (Claude Max seats, Bedrock or Vertex, another org), send "billed_to": "other"; do not post the polled org's own usage. For a row already stored without billed_to: if it is Claude Max, Bedrock, Vertex or another org's usage, no action is needed; if it has an idempotency_key and repeats the polled org's usage, correct it to cost_usd 0 with the audited override, sending the stored row's idempotency_key, developer, issue_id, model and fidelity with override=true, override_actor and override_reason. The override corrects the cost only: the row's token counts stay counted. A row with no idempotency_key, or whose stored fidelity is neither daily nor estimated, cannot be corrected through the product.

  • override: true without billed_to is admitted when a row already owns the idempotency_key: it corrects that row (the remedy above). When no row owns the key, the override would insert a new undeclared row, so it gets the same 400 and nothing is written. Whether a row owns the key is decided in the same write-locked transaction as the correction.

  • billed_to accepts only "other", or omitted; any other value is 400, with or without a poller. A server with no poller for the row's provider accepts the field, stores it and otherwise behaves as before.

  • The declaration is stored on the row (billed_to, NULL when not declared) and appears in the GET /events export and the DSAR export. It is not part of the keyed re-post comparison: a re-post that differs from the stored row only in billed_to is the idempotent 201, and the stored value is left as first recorded. So a row stored without billed_to can never gain one.

  • ⚠️ A keyed retry of a row stored before the upgrade now gets 400 on a server running that provider's poller, if the retry omits billed_to. The row already exists and nothing is written either way; add "billed_to": "other" to the retry only if that spend really is billed elsewhere.

  • Startup warning. For each running poller, tierd serve logs one WARN at startup, "undeclared manual rows that may be counted twice", with the number of source='api' rows that have no billed_to, are for that provider's models, and fall on a UTC day that poller covered, their summed cost (cost_usd), and the remedy. A poller covers a day when it has stored a row for it. The day match is approximate, because a manual row's time is when it was posted, not the day the usage happened. Nothing is logged when the count is 0. The count never falls to 0 for legitimate Claude Max, Bedrock or other-org rows stored before the upgrade, because those can never gain a billed_to.

  • Listing rows stored before the upgrade. Use either route. Both only read.

    • Over the API (developer aggregation mode only: GET /api/v1/events returns 403 in team or division mode). The endpoint filters only by since, until, cursor and limit, so filter the rows yourself. TIER_URL is where your tierd is served (for example http://127.0.0.1:8080) and TIER_TOKEN is your read or write token (--read-token or --api-token):

      cursor=
      while :; do
        page=$(curl -fsS -H "Authorization: Bearer $TIER_TOKEN" \
          "$TIER_URL/api/v1/events?since=2020-01-01&limit=10000&cursor=$cursor") ||
          { echo "request failed; the listing is incomplete" >&2; break; }
        printf '%s\n' "$page" |
          jq -r '.events[] | select(.source == "api" and .billed_to == "")
                 | [.ts[0:7], .model, .developer, .issue_id, .fidelity,
                    .idempotency_key, .cost_micro] | @tsv'
        cursor=$(printf '%s\n' "$page" | jq -r .next_cursor)
        [ -n "$cursor" ] || break
      done
      

      It follows next_cursor page by page until the export is exhausted; the rows it lists can be on any page, so do not stop at the first. Each line is month, model, developer, issue id, fidelity, key (empty for an unkeyed row) and cost in millionths of a dollar: the fields the override needs. For the sum per provider per month, add up cost_micro for that provider's models in each month and divide by 1,000,000.

    • In SQL (any aggregation mode), on the machine running tierd, with DB set to the path you gave --db (default ~/.tier/tier.db):

      Prerequisite: the separate sqlite3 CLI (sudo apt install sqlite3 on Ubuntu/Debian; preinstalled on macOS).

      sqlite3 -cmd '.timeout 5000' "$DB" <<'SQL'
      SELECT substr(ts, 1, 7) AS month, model, COUNT(*) AS rows,
             SUM(idempotency_key IS NULL) AS unkeyed,
             SUM(cost_micro) / 1e6 AS usd
        FROM token_events
       WHERE source = 'api' AND billed_to IS NULL
       GROUP BY month, model
       ORDER BY month, model;
      SQL
      

      Add up the rows for the provider's models (claude-* for Anthropic; the OpenAI models for OpenAI) to get its sum for each month. This lists every undeclared manual row, not only those on days a poller covered.

• ⚠️ developer may not be the reserved unattributed sentinel either (#619). The same reserved string is the sentinel for two columns, and this is now the same rule on both -- one predicate backs both checks, so they cannot drift. A client supplying "developer": "unattributed" (or UNATTRIBUTED, or unattributed:main, or any of them with surrounding whitespace) now gets 400; it was previously written silently.

  This half mattered more than the issue_id half. TIER is points / (cost/1000). Forging issue_id moves a dollar between buckets inside your own denominator and leaves your headline score unchanged. Forging developer moves it out of your denominator entirely -- onto the unattributed pseudo-developer -- so your cost falls and your score rises.

  ⚠️ Scope, stated plainly: this removes the deniable forgery, not the ability to raise your own score. TIER is single-tenant with one shared write token and a free-form developer column, so posting "developer": "mallory-2" still moves your spend out of your own row. What the sentinel added was cover — it is indistinguishable from honest server-assigned spend and lands in a bucket nobody audits. Binding developer to the authenticating credential is the control that would close the general case, and it is separate work.

  Ordinary identities that merely contain the word (unattributed-bot, not-unattributed) are unaffected, as is unknown, the real no-identity fallback the collector emits. Same rule on POST /outcomes, POST /events, POST /actual_spend, both columns of POST /developer_alias, and PUT/POST /org_hierarchy. Unlike issue_id, developer has no allowlist anywhere, including /events: the producers that legitimately assign the developer sentinel (the org-level Anthropic-Admin and OpenAI-Usage pollers, and the proxy's own missing-header fallback) write in-process and never cross an HTTP boundary, so there is nothing on the wire to allowlist.

• Keyed re-post (idempotency_key present): an identical re-post (same key, same cost, same (developer, issue_id, model, source, fidelity)) is idempotent -- 201, no new row, and the stored row is left exactly as first recorded, token counts included. A re-post with the same key but a different cost_usd is rejected with 409 Conflict (#295): the stored cost is immutable (#233), so the correction is refused rather than applied. Divergence is judged on the stored integer cost_micro, so an honest retry whose float/FX/rounding jitter rounds to the same micro value is not a conflict. To change a recorded figure, use the sanctioned override below (#346): it replaces the stored cost on the same row and writes an audit row. ⚠️ Do not re-post under a new idempotency_key to correct a figure. A new key is a new row, and every spend read adds both, so a correction from $100 to $80 is recorded as $180. A distinct key is right only for spend that is genuinely additional, such as when the earlier row is not yours. For the one row class the override cannot reach, see the pre-#82 realtime note below.

• A re-post whose cost matches but whose (developer, issue_id, model, source, fidelity) differs from the stored row's is rejected 409 (#871) -- the same identity-mismatch response the override path below returns, and it likewise does not say whose row the key belongs to. Nothing is written for the caller and the stored row is unchanged. The cost is compared first, so a re-post whose cost AND identity both differ gets the divergent-cost 409 above. A re-post that changes only token counts is a silent no-op on those columns (they are immutable on conflict, #233, #871) -- 201, NOT a 409. One consequence: a keyed re-post of a pre-#82 row whose stored fidelity is anything outside daily/estimated (realtime is the live example; see below) now 409s even at the same cost, because no request can state that fidelity; nothing is written either way. Reuse a key only for a genuine retry of the same event -- idempotency_key is a GLOBAL namespace across every producer (client-generated /costs keys and automated MessageIdempotencyKey-derived keys from /events/JSONL/proxy alike), so reusing someone else's key is a real, not hypothetical, way to collide with a row that isn't yours.

• Sanctioned cost-correction override (#346, ruling C -- the follow-up to #295's ruling A above): set override: true plus required override_actor and override_reason (both non-empty, override_actor <= 256 chars, override_reason <= 1024 chars) to let a legitimate finance correction land on a DIVERGENT keyed re-post instead of 409ing.

  • override with a missing/empty override_actor or override_reason, or with an empty idempotency_key, is rejected 400 -- an override must be attributed and explained, never silent, and there is nothing to override without a key.

  • override_actor/override_reason set without override: true is rejected 400 rather than silently ignored.

  • The stored row's (developer, issue_id, model, source, fidelity) must match the request's -- a mismatch is rejected 409 (a DIFFERENT status detail than the plain divergent-cost 409, but the same status code; the plain path returns this same response on a same-cost mismatch, #871). The 409 body deliberately does not echo which identity the key actually belongs to -- defense in depth against a BLIND collision, not a secrecy guarantee (see the stated trust model below). That tuple is the set of stored columns a /costs request can vary, except billed_to (#854), a declaration that is deliberately not compared; repo, host, billing_mode, session_id, and ts are forced by the endpoint and are therefore NOT compared. idempotency_key is a global namespace (see above), so this is a real collision case, not a theoretical one: without this check, reusing a copy-pasted key under a different identity could rewrite the WRONG row's cost.

  • ⚠️ One row class cannot be corrected through this endpoint at all. fidelity is INSERT-only, and #82 narrowed /costs to daily/estimated/omitted -- so a pre-#82 source='api' row that still carries realtime can never be matched: stating it is a 400, omitting it defaults to estimated, and both mismatch. Every possible request 409s. No API route or tierd command corrects or deletes a single row (DELETE /api/v1/developer/{id} erases everything that developer owns, which is not a correction), so the fix is made directly in the database. Do not delete the row and re-post it: /costs takes no timestamp and stamps the new row with the time it arrives, so the spend would move from its original date to today. Re-posting under a new key without removing the old row would add the new figure to the old one.

    Instead, change the cost on the row itself, the same one-column change the override makes. It keeps the row's date and every other column. Run it on the machine running tierd; it is safe while tierd serve is running. Set DB to the path you gave --db (default ~/.tier/tier.db), then back up and look the row up by its key:

    DB=~/.tier/tier.db
    tierd backup --db "$DB" --out ~/tier-before-cost-fix.db
    sqlite3 -cmd '.timeout 5000' "$DB" <<'SQL'
    SELECT id, developer, issue_id, cost_micro, fidelity, ts
      FROM token_events
     WHERE idempotency_key = '<old key>' AND source = 'api' AND fidelity = 'realtime';
    SQL
    

    Replace <old key> with the key before you run it. The SELECT must show exactly the one row you mean to change. Note its id (a whole number). cost_micro is the cost in millionths of a dollar, so $80 is 80000000. Then change that row by its id, never by pasting the key again, with the id and the new figure in place of <id> and <new cost_micro>:

    sqlite3 -cmd '.timeout 5000' "$DB" <<'SQL'
    UPDATE token_events SET cost_micro = <new cost_micro>
     WHERE id = <id> AND source = 'api' AND fidelity = 'realtime';
    SELECT changes();
    SQL
    

    It must print 1. A 0 means the id was not a realtime api row, and nothing changed. The source and fidelity terms are there so a mistyped id cannot touch a captured row. Every spend read sums cost_micro directly, so the new figure shows at once with nothing to rebuild. Unlike the override, this writes no cost_correction_audit row, so record who made the change and why somewhere you keep. The backup is your copy of the old figure. Changing the row also changes the digest of every published report whose window covered it, so a tierd verify-report manifest saved before the change will no longer match.

  • When it actually corrects a divergent row: the UPDATE touches only cost_micro on that one row (token counts, model, source, fidelity, price_version, billing_mode are all left exactly as first recorded -- never a last-writer-wins upsert of the whole row), and an append-only audit row (old -> new, actor, reason) is written to the (internal, unexposed via any GET route today) cost_correction_audit table. 200.

  • When there is nothing to correct (fresh key, or the cost already matches): behaves exactly like the non-override path -- 201, no audit row.

  • Reprice-safe. tierd reprice --commit recomputes cost_micro from token counts, and it never reprices a source='api' row -- a manual import's cost is the caller's authoritative figure and re-deriving it from token counts (which may not exist) yields $0.00. Corrections therefore survive a reprice sweep, and the sweep reports how many rows it protected rather than omitting them silently.

• Stated trust model for the override. Read this before treating the identity check as an access control:

  • The write scope is a single global bearer token with no subject. Nothing binds the authenticating principal to the developer field, and no tenant_id column exists anywhere to put such a binding in -- TIER is single-tenant by design today.
  • The identity check therefore prevents an accidental key collision from landing a correction on the wrong row. It does not prevent a holder of the write token from deliberately correcting a row that is not theirs, because the tuple it compares is not secret: the read-scoped GET /api/v1/events export publishes every idempotency_key alongside its full identity tuple.
  • Deliberate misattribution by a write-token holder is out of scope until an identity layer exists (#65).
  • What the endpoint does structurally guarantee: it forces source="api" on every request and the identity check compares source, so the override can only ever touch a row whose stored source is api -- the manual-import lane. Automatically captured spend (every non-api source: jsonl, proxy, codex-rollout, opencode, muse, legacy stored copilot-api rows, and the org pollers anthropic-admin, openai-usage, copilot-billing, and cursor-admin) is unreachable from this endpoint.
  • override_actor is a self-asserted claim, not a verified identity. It is unvalidated free text the caller chooses, written verbatim into the audit ledger and the operator log. The audit trail records who the caller says they are. Nothing checks it against the credential that made the request, and nothing can while the write scope has no subject.
  • cost_correction_audit refuses UPDATE at the schema level (#604), so no code path can silently rewrite a recorded correction -- a mutation would have to drop the trigger first. DELETE is deliberately not refused -- erasure and retention are lawful deletes. This is not tamper-proofing against someone holding the database file.

• 503 + Retry-After: 1 when another writer holds the database write lock. Retryable, and nothing landed -- the request runs in one all-or-nothing transaction that takes the write lock before it writes, so on 503 no row was inserted, no cost was corrected and no audit row was recorded; retry to complete the request. Distinguish it from the permanent statuses: a 409 means the key genuinely conflicts (divergent cost, or an identity mismatch) and retrying is pointless, and a 500 means an unexpected store failure -- including a read-only or full database, which is deliberately NOT reported as 503 because it will never clear on its own. Only the 503 should be retried automatically. ⚠️ Since #610 this applies to the WHOLE endpoint, and that is a behavioural change on the plain path. Both halves -- override: true and the plain insert, keyed or unkeyed -- now take the write lock before they write, bounded at the same 250ms. Before #610 only the override half did: a plain post that lost the race blocked for the DSN's full 5000ms and then answered 500 with no Retry-After, so one URL called the same transient condition retryable or permanent depending on the override field. Two things move for a plain post, not one. A 500 after ~5s becomes a 503 after ~250ms -- and, because the endpoint now gives up at 250ms instead of waiting out 5000ms, contention that used to resolve into a 201 can now return 503 as well. The endpoint no longer waits on the client's behalf; the retry is the client's. That is the deliberate trade: with a single write connection, a request that waits 5s does not stall itself, it stalls every other in-flight request behind it.

POST /api/v1/events

• Scope: ingest or write (#1144). Success: 201 Created, body {"accepted": <int>, "rejected_cross_developer": <int>}.
• Cross-developer key collisions leave the original row unchanged and increment rejected_cross_developer; the server logs a WARN and the shipper warns without failing or retrying. No migration; global idempotency stays unchanged.
• Bulk repo-aware ingest (array body). accepted counts processed events excluding cross-developer rejections, not rows newly created (coherent original-basis promotion absorbs replays). Per-event fields mirror costRequest plus repo, session_id, and a required RFC3339 timestamp. Since #233 the server reprices token counts with its own price table; the client cost_usd is retained only as a cross-check.
• Each token field has the same 1e12 cap as /costs; both client cost_usd and server-resolved cost must be <= $10,000 per event. Over-limit events return 400 naming the limit and the split-across-rows remedy; the whole batch is refused. Capture and reprice clamp oversized costs, preserve token counts, and retain cost_clamped=1 clamp history (also in DSAR); the counter counts capture attempts and committed reprice changes. Existing data migrates without this ceiling. Exact integer SUM(cost_micro) is unchanged (#1082).
• ⚠️ issue_id follows an ALLOWLIST here, not the /costs rule (#466). This endpoint is the JSONL collector's own transport, and the collector legitimately assigns the unattributed sentinel when a message resolves to no issue. It therefore accepts the five exact canonical spellings -- unattributed, unattributed:main, unattributed:detached-head, unattributed:branch-without-issue, unattributed:foreign-repo (#823) -- and 400s every other member of the family, every case variant, and every near-miss. An unattributed:foreign-repo row must omit repo (it is stored as unqualified, so no foreign repository name is kept); any other repo value is a 400 that does not echo it. Why the split rather than one rule: the endpoint validates all-or-nothing, so one rejected event fails the whole batch; the shipper treats 4xx as terminal with no retry; and it is stateless, so the next run rebuilds the identical batch and fails identically. Applying the strict /costs rule here would be permanent 100% capture loss for anyone who has ever committed on main without an issue, including their well-formed attributed events.
• host is OPTIONAL and is a PRICING INPUT (#719). Omitted, an event prices at the model-only rate -- exactly how every pre-#719 client behaves, so adding the field breaks no existing integration. Supplied, the server prices at the host-qualified rate <model>@<host> when the active table has one. It exists because a source can have a rate that lives ONLY under a host key: the opencode collector stamps its provider id (zai-coding-plan) as the host because #712's GLM override rates are keyed on it (the embedded table has carried model-only glm-5.3 rows only since v10, #786). Before this field those events re-priced at the guessed self-hosted-medium fallback ($0.50/M) with no signal at all -- the pricing-divergence detector compares the server's figure against the shipper's, and the shipper's was the same guess. ⚠️ It is client-controlled input selecting a price-table key, so a caller can choose which audited rate its tokens bill at. That is the same latitude model already gives, and it sits inside this endpoint's existing trust model (the bearer token is attribution-grade; deliberate misattribution is out of scope until an identity layer exists, #65). The endpoint enforces the SHAPE: the 256-char identifier cap, and ComputeCostHost's rejection of a model string containing the host separator, so a forged "model@host" cannot bypass the host lookup. ⚠️ Version skew: the endpoint uses DisallowUnknownFields, so a shipper sending host to a pre-#719 server 400s the whole batch (all-or-nothing, and a 4xx is terminal with no retry). The field is omitempty, so a jsonl/codex batch is byte-identical to what a pre-#719 shipper sent and is unaffected; only a batch actually carrying a host is at risk, and it fails loudly.
• pr_number and branch_hash are OPTIONAL (#1074). pr_number is a positive integer; zero/negative values are a 400. branch_hash is exactly 64 lower-case hex characters; other shapes are a 400. Omitted/null fields store NULL. The hash is SHA-256 of canonical repo + "\x00" + branch, using the full name with refs/heads/ removed. Default/unknown branches and unqualified repositories do not produce a hash. The shipper sends both fields whenever set. Only an HTTP 400 whose error body contains json: unknown field "pr_number" or json: unknown field "branch_hash" resends that batch once with both fields stripped and omits them for that server for the rest of the process. Other 400s, 5xx, timeouts and network errors follow the existing error/retry path and cache nothing; a 2xx never strips fields. There is no capabilities route; ingest-token scope remains POST /api/v1/events only. Old servers accept the stripped batch but retain neither field; old shippers omit both fields even against new servers. At insert, only an unattributed event in a real repo and an unsealed month resolves through exactly one real-issue outcome on (repo, pr_number). Its pr-number-at-insert rule is server-owned and rejected as client input. Recording a merged PR fills eligible unattributed, unsealed (repo, pr_number) rows with the same rule. Branch matches on the same repo and pseudonymised head hash credit only inside [max(previous merge, PR opened − 7 days), merge], with server-owned branch-at-merge; overlapping recorded windows are skipped. Both rules export verbatim in event JSON/CSV and are rejected as client input. Branch reuse bounds later credit at the previous merge. Guessable branch names can be recovered from the hash. API outcomes have no head-ref field and leave the hash NULL; webhook/backfill set it only with head-ref evidence.
• issue_rule is OPTIONAL (#1296): client-asserted extractor provenance. The closed set is branch_first_numeric, branch_tracker_shape, body_close_directive, body_tracker_shape, body_bare_hash, commit_close_directive, commit_tracker_shape, branch_first_slot, branch_configured_key, body_configured_key, body_relation_ref and commit_configured_key. In v0.6.1 (#1297), new rows carry strict rule names from the strict issue-reference grammar; stored attribution is not rewritten. An absent or unknown value is stored as NULL; unknown values cause one warning without logging the supplied value. This assertion is never copied into outcome provenance or used to upgrade a row to strict. Upgrade the server first: the shipper reuses its single-resend fallback on an exact unknown-field HTTP 400, omitting the rejected field for that server.
• attribution_rule is OPTIONAL (#823): the rule that assigned issue_id, empty or one of the closed set store.AttributionRules() (branch, worktree-cwd, worktree-toolpath, carry). Omitted, the row stores no rule -- exactly how every pre-#823 shipper behaves. pr-number-at-insert and branch-at-merge (#1074) are server-assigned, never client-sent. Any other input is a 400 naming the allowed set; the refused value is not echoed. Stored on insert only; a replay never rewrites it. Same version skew as host: a pre-#823 server 400s a batch that carries the field, so upgrade tierd before the shippers. Claude Code capture uses carry only for isSidechain:true groups (#1016); parents never carry. Worktree attribution stays opt-in and off by default. Activation requires recorded gates, operator security rulings and an explicit operator decision. No new accuracy figures have been measured. Historical rows retain the rule recorded by their original collector.
• ⚠️ developer gets the STRICT rule here, with NO allowlist (#619). The asymmetry with issue_id directly above is deliberate, not an oversight: the local collectors this wire admits (source must be jsonl, codex-rollout, opencode or muse) label every event with --developer or the OS username, whose own no-identity fallback is unknown -- never unattributed. The producers that do assign the developer sentinel are the org pollers, which are excluded from this endpoint twice over (their sources are not shippable, and they write in-process rather than over HTTP). There is therefore nothing legitimate to allowlist, and an allowlist would only make forging as effective as honesty.

POST /api/v1/outcomes

• Scope: write. Success: 201 Created on insert, 200 OK on duplicate.
• Response outcomeResponse: status ("created" or "duplicate"; always present) plus weight_source, weight, work_type (omitempty). Dedup is on merge_commit_sha; a replay returns 200 with status: "duplicate" and echoes the stored row's weight/source/work_type.
• ⚠️ issue_id may not be the reserved unattributed sentinel (#466) -- the same case-insensitive rule as POST /costs, 400 on any member of the family. This is the path where forging actually pays: an outcome on the sentinel earns weighted points whose cost no work-type segment denominator ever sees, inflating the numerator rather than merely shifting a denominator. The GitHub webhook derives ids via issueref, which can only emit #\d+ / ABC-123 shapes, so no legitimate producer is affected.
• ⚠️ developer may not be the sentinel either (#619) -- same rule, 400. An outcome filed against the unattributed pseudo-developer credits weighted points to a pool of spend that by construction has no owner. The webhook takes its developer from the signed GitHub payload's PR author login, so no legitimate producer is affected here either.

POST /api/v1/actual_spend

• Scope: write. Success: 201 Created, empty body.
• Finance per-developer invoice total. Request: developer, period (YYYY-MM), actual_paid_usd. Rows accumulate; negatives are accepted as credit memos.
• ⚠️ developer may not be the reserved unattributed sentinel (#619) -- 400, same case-insensitive rule as POST /costs. This ledger is the tier-1 invoice input to Spend Leverage, so it is a denominator by another name: posting your own invoice under the sentinel drops your actual-paid out of your row exactly as forging /costs drops your metered cost.

POST /api/v1/org_actual_spend

• Scope: write. Success: 201 Created, empty body.
• Org-level invoice total (one contract covering N developers). Request: org, period (YYYY-MM), actual_paid_usd. Same accumulate/credit-memo semantics.
• org must be the exact string you set as org on POST /api/v1/org_hierarchy or PUT /api/v1/org_hierarchy/{developer}. The allocation joins org_actual_spend.org to period_membership.org (which the hierarchy write populates) byte-for-byte — no trimming, no case folding, on either write path (internal/store/store.go, actualSpendCTE; upsertHierarchyTx). An invoice posted under Acme when the hierarchy says acme allocates to nobody: it is accepted with 201, but no developer receives a slice and Spend Leverage keeps reading —.

GET /api/v1/org_actual_spend

• Scope: write (finance audit read; NOT granted to the viewer token).
• Success: 200 OK, orgActualSpendResponse:
  • since (string, echoed window lower bound)
  • orgs (array of {org, period, actual_paid_usd, entries})
• ?org= filters to one org; ?since= sets the window. actual_paid_usd is the net (source-scoped sum) roll-up per (org, period); entries is the row count behind that net.

POST /api/v1/developer_alias

• Scope: write. Success: 201 Created, empty body.

• Maps a raw identifier to a canonical developer. Request: alias, canonical (both required). Chain/self-map violations are 400.

• ⚠️ Neither alias nor canonical may be the reserved unattributed sentinel (#619) -- 400 on either, same case-insensitive rule. An alias is a retroactive rename of the identity space: the score join resolves every stored developer through this map before aggregating, so without this guard the checks on /costs, /events, /outcomes and /actual_spend could all be bypassed in one hop. Both directions are refused because they are two different attacks: {"alias": "alice", "canonical": "unattributed"} folds alice's whole history into the pseudo-developer (self-dealing), while {"alias": "unattributed", "canonical": "bob"} dumps every org-poller aggregate and every proxy-unresolved dollar into bob's denominator (sabotage).

• 503 + Retry-After: 1 when another writer holds the database write lock. Retryable — it is a lost race for SQLite's single writer, not a bad request and not a broken database. Distinguish it from the 400s above: those are permanent and retrying cannot help. A 500 here still means an unexpected store failure, including a database that cannot be written at all (read-only file, full disk) — deliberately NOT reported as retryable.

• The alias is joined to its canonical developer for every window, but its team placement changes only from the write on (#914): the write dates the change by the server clock, and events recorded under the alias before it stay in the team the alias was in then. 409 when the server clock reads earlier than a membership row the write would close.

DELETE /api/v1/developer_alias/{alias}

• Scope: write. Success: 204 No Content; 404 if not mapped.
• Team placement changes from the delete on (#914), as for POST. 409 as for POST; 503 + Retry-After: 1 when another writer holds the write lock.

GET /api/v1/developer_alias

• Scope: write (admin; discloses the identity map).
• Success: 200 OK, {"aliases": {<alias>: <canonical>, ...}}.

PUT /api/v1/org_hierarchy/{developer}

• Scope: write. Success: 200 OK, the stored HierarchyRow: {developer, team, division, org}. Request body: {team, division, org}.
• A changed team or division is dated by the server clock (#886); a valid_from/valid_to field is refused 400, like any unknown field. 409 when the server clock reads earlier than the developer's current membership began (the host clock stepped back): nothing was written, and the request succeeds once the clock is right.
• 503 + Retry-After: 1 when another writer holds the database write lock. Retryable — it is a lost race for SQLite's single writer, not a bad request and not a broken database. A 500 here still means an unexpected store failure.

POST /api/v1/org_hierarchy

• Scope: write. Success: 201 Created, {"accepted": <int>}.
• All-or-nothing bulk import (array of {developer, team, division, org}). Every row is dated by the same server instant (#886); 409 exactly as on the PUT above, with nothing written.
• 503 + Retry-After: 1 when another writer holds the database write lock. Retryable, and NOTHING was written — the batch is one transaction, so the whole request is safe to replay verbatim. A 500 here still means an unexpected store failure.

GET /api/v1/org_hierarchy

• Scope: write (discloses the full developer->team map).
• Success: 200 OK, {"hierarchy": [{developer, team, division, org}, ...]}.

POST /api/v1/period_membership/{developer}/end

• Scope: write. Success: 200 OK, {developer, org, period_end} (the applied end record). Request: {org, period_end}.
• 503 + Retry-After: 1 when another writer holds the database write lock. Retryable. Distinguish it from the 400 this route also returns when period_end precedes the membership's start: that one is permanent and retrying cannot help. The 503 is classified FIRST precisely so a transient lock conflict is never reported as bad input.

DELETE /api/v1/developer/{id} (GDPR Art. 17 erasure)

• Scope: write. Success: 200 OK, {"deleted": {<table>: <count>, ...}, "total_deleted": <int>}; 404 when nothing matched (which makes a repeated erasure idempotent). Each count is the rows this erasure changed in that table. Reported tables include org_claims and viewer_notices. deleted.watcher_checkpoint, and so total_deleted, counts rows tombstoned plus rows deleted (#919). deleted.sealed_person is always present and counts sealed person keys tombstoned, never deleted (#913, #914), including keys of a canonical id the person's alias was linked to when the period was sealed, which another person may hold now (#975); total_deleted includes it, so an erasure that only tombstones sealed keys returns 200, not 404. deleted.canonical_id_history is always present and counts history rows deleted, including a row recording that another person's alias once pointed at the erased id (#975). Available in team-aggregation mode (compliance tooling, not a reporting surface).
• 503 + Retry-After: 1 when another writer holds the database write lock. Retryable, and the erasure did NOT happen — the transaction is all-or-nothing, so nothing was partially deleted; retry to complete the request. A 404 means there was nothing to erase; a 500 means an unexpected store failure. Only the 503 should be retried automatically.

GET /api/v1/developer/{id}/export (GDPR Art. 15 access)

• Scope: write. Success: 200 OK, store.DeveloperExport: {developer, identifiers, token_events, outcomes, actual_spend, org_hierarchy, period_membership, hierarchy_membership, quality_events, quality_history, repo_repair_audit, push_outcome_commits, push_outcome_audit, developer_alias, watcher_checkpoint, correction_declarations, corrective_relations, correction_audit, correction_assessments, correction_allocations} (each a row array grouped by table). push_outcome_commits and push_outcome_audit (#849) are the push-capture commit ledger and its audit; a commit_sha starting pre-ledger: is a marker, not a commit. A push_outcome_commits row's push_order (#938) is its ownership sort key. The audit's stored commit_developer (another developer, the author of that commit) is left out. hierarchy_membership (#886) rows are {id, developer, team, division, valid_from, valid_to}; the stored written_by credential fingerprint is left out. outcomes rows carry author_type (#856): the PR author's GitHub account type (User, Bot, Organization, Mannequin) as the webhook recorded it, or null when not captured. 404 when the developer has no data. Available in team-aggregation mode.

Read endpoints

GET /api/v1/admin/shared-token

• Scope: admin credential. Absent from read-only serving. Success: 200 OK; Cache-Control: no-store.
• JSON keys: accepted_7_days, refused_7_days, accepted_30_days, refused_30_days (integer request counts), and last_seen_day (UTC YYYY-MM-DD or empty string).
• Windows include today and the preceding 6/29 UTC days; last_seen_day is lifetime last use. Refusals flush every 60 seconds and at graceful shutdown.

GET /api/v1/scores

• Scope: read. Success: 200 OK, scoresResponse.
• Query in developer mode: ?since= (YYYY-MM-DD / YYYY-MM / YYYY; default: the start of the UTC day 90 days back, #746), ?until= (or ?before=) exclusive upper bound, ?team=, ?work_type=, ?repo=. Any other parameter is a 400 -- see strict query-parameter validation.
• In team/division mode, only ?period=YYYY-MM is accepted (omit it for the newest sealed month). Any other parameter is a 400, including the developer-mode filters above.
• ?repo= (#590) narrows the response to ONE repository. The value must already be slug-shaped: two or more /-separated segments, no scheme and no host (acme/alpha, or group/sub/proj for a nested GitLab path). It is then canonicalized exactly as stored repo values are -- lowercased, a trailing .git and surrounding / trimmed -- so Acme/Alpha.git matches acme/alpha.
  • A value that cannot canonicalize at all is a 400: fewer than two segments, an embedded URL, illegal characters, over-length, or the reserved unqualified.
  • ⚠️ A well-formed but non-existent slug is NOT a 400. acme/alpah scopes normally and returns an empty window, and a host-qualified github.com/acme/alpha is accepted as a legal three-segment slug rather than stripped to acme/alpha (scheme/host stripping belongs to the collector's write path, not this filter). So the 400 buys "that is not a slug", not "you mistyped a repository name". Distinguish an empty result from a typo by reading the echoed data_quality.repo_scope, which reports the canonical slug actually queried.
  • ?repo= with an empty value is treated as unscoped and returns an installation-wide read; fleet-wide is spelled by OMITTING the parameter. It stays distinguishable because no repo_scope key is emitted -- assert on that key.
  • Scoping is STRICT. Only rows naming that exact repository are counted. Rows carrying the reserved unqualified sentinel -- recorded by producers that structurally cannot know a repository, such as the reverse proxy -- are excluded, never folded in. Including them would attribute every repo-blind row in the installation to whichever single repository was named, which is the same over-counting defect ?repo= exists to prevent, inverted.
  • Strictness can therefore under-count, so it is disclosed rather than left silent: see data_quality.repo_scope_excluded. A scoped figure over a window containing repo-blind rows is a lower bound, not a total.
  • unqualified itself cannot be selected as a scope. Those rows are surfaced as a disclosure, not offered as a queryable population.
  • spend_leverage and actual_paid_usd are suppressed to 0 under a scope, and the suppression is declared (data_quality.spend_leverage_suppressed). Actual spend is what the organization PAID a vendor over a period; it carries no repository and cannot be divided by one without inventing an allocation. Dividing it by one repository's list-price cost would inflate leverage by roughly the installation-to-repository ratio. The keys remain PRESENT and read 0; read the spend_leverage_suppressed flag, not the zero.
  • 🔴 ?repo= is REFUSED with a 400 in any anonymized (team/division) aggregation mode. Scoping narrows the cohort before the k-anonymity floor is applied, so a repository only one person works in can shrink a group below k and expose an individual's figures through the residual bucket -- the exact disclosure those modes exist to prevent, and the same reason ?team= is not honored there. It is rejected rather than ignored: silently dropping it would return an installation-wide aggregate that looks scoped.
  • 🔴 ?work_type= is REFUSED with a 400 in any anonymized (team/division) aggregation mode (#864). An anonymized install publishes ONE breakdown per window: its group rows and the grand total. A second breakdown differences against the first to a group below k even when every published row has k people (measured: pooled team rows minus work-type totals recovered a 3-person group's $9.21). A value that is not a work type is still the ordinary invalid work_type 400. Developer mode honors the filter as before.
  • Query parameters are parsed STRICTLY, not via a lenient decoder: a malformed pair (bad percent-encoding, or a ; -- which Go does not accept as a separator) is a 400, and so is a REPEATED parameter. Both would otherwise be silently dropped or silently resolved to the first value, widening the result while looking filtered.
• Fields:

  • since (string) -- echoed window lower bound (UTC calendar day). Since #746 this is exact rather than approximate: the default bound is snapped back to the start of its UTC day, so the day printed here is the day the window actually opens on. Before that it read 2026-05-31 for a window that began at 2026-05-31T05:00:58Z.

  • price_table ({version, effective_date, table_hash, file_hash}) -- always present price provenance stamp (#233, extended by #713). table_hash ("tierpt1:<64 hex>") is a digest of the RESOLVED in-memory table; file_hash ("sha256:<64 hex>") is a digest of the raw source bytes. See content identity below.

  • rubric ({version}) -- always present canonical weight-rubric stamp (#239, scoring.RubricVersion), the weight-side analogue of price_table. A weighted_points count (hence tier and cost_per_point) is comparable across responses ONLY when rubric.version AND price_table.version both match. See docs/rubric.md for the versioned rubric and its "what you may / may not compare" rules. There is deliberately no absolute good/ok/poor band.

  • total (teamScoreJSON or absent) -- rollup across all developers in the response. POOLED back-compat summary (#187): NOT a cross-type ranking. See work_types for the authoritative within-category comparison.

  • developers (array of developerScoreJSON) -- per-developer rows in developer mode; an explicit empty array in any anonymized mode (team/division). Same pooled caveat as total.

  • aggregation (string, omitempty, #270) -- discriminator naming the ANONYMIZED grouping level whose rows populate teams: "team" (#185) or "division". Omitted in developer mode (which ships developers, no teams). It is the seam that lets a consumer tell what each teams label means, since a division-mode response is otherwise structurally identical to a team-mode one. A future org/department level would set its own name here with the SAME teams array -- no new response field.

  • teams (array, omitempty) -- populated only in an anonymized mode: k-anonymized GROUP aggregates, no individual names. In --aggregation team (#185) each row is a team; in --aggregation division (#270) each row is a division (one level up in org_hierarchy), labelled in the same team field. The aggregation discriminator above says which. Groups are dated (#886): each cost event, outcome and invoice counts toward the group its developer held at that event's own time (an invoice at the start of its month), read from the append-only hierarchy_membership ledger, so a later move never changes a past window. A group with fewer than k contributing developers folds into the residual "other" row; a developer whose division is empty/unset folds into "other" too. A developer counts toward a group's floor once, however many rows they carry, and only with activity: a developer whose only figure there is paid spend fills no seat. 🔴 If the "other" row does not reach k, the WHOLE response is withheld (#864): teams is absent, named rows included, as is total, and data_quality.kanon_suppressed says so. A named row published beside a withheld residual differences against any other view that folds that group into a residual of its own.

  • team (teamScoreJSON, omitempty) -- populated only when ?team= filters to one team (developer mode only).

  • team_rollups (array, omitempty, #821) -- developer mode only. Partitions total by dated team membership (#886): each event counts toward the team its developer held at that event's own time. One row per team that has at least one event in this response, in byte-wise ascending team-name order, then at most one unassigned row for events whose developer had no team at that time (or one mapped to ""). An event is placed by the dated membership of the identifier it was recorded under, as the anonymized modes place it (#914): an alias carries its person's team from the moment it was added, re-pointed or deleted, and events recorded under it before then stay where they were. Each row is teamScoreJSON plus unassigned (bool, always present); the unassigned row has unassigned: true and no team key, so it can never collide with a team a customer happens to name. Every event is in exactly one row (a developer who moved inside the window can appear in two), so the rows' weighted_points and total_cost_usd sum to total's (to float64 rounding: the grouped sum re-associates the same additions). tier, cost_per_point, coverage_pct, spend_leverage and ranked are per-row ratios and do not sum. A team with an org_hierarchy row but no developer in the window has no row.

    • The mode rule alone decides presence: developer mode, whenever total is present, over the same population: the window and ?repo= narrow it; ?team= and ?work_type= do not (?team= fills team, ?work_type= narrows only work_types). Under ?team=X the X row equals the team block.
    • Top level only. work_types segments carry no team_rollups.
    • 🔴 ABSENT in any anonymized mode (team/division). A per-team rollup has no k-floor; in those modes it would re-expose every sub-k team the k-anonymized teams array folds into "other", and total - Σ named teams is the differencing channel #593 closes. It is therefore also absent whenever data_quality.kanon_suppressed is set: k-anonymity suppression only ever fires in an anonymized mode, and the #593 strip pass withholds team_rollups together with total regardless.
    • ⚠️ Read scope sees team structure. /scores is read-scoped (#190), so in developer mode the read-only viewer token now sees every team name and each team's totals, from which membership can be inferred. This is operator ruling #821 = B: the dashboard's team panel needs it. GET /org_hierarchy, the developer->team map itself, stays write-scoped.
    • Not named teams: that key is frozen as the k-anonymized array whose rows are labelled by the aggregation discriminator.

  • Additive diagnostics (#972 / U97), developer/operator mode only: data_quality.join_readiness contains arrays outcome_only_repos ({repo, outcome_count, points}), cost_only_repos ({repo, captured_cost_usd}), incompatible_repos ({developer, issue_id, cost_repo, outcome_repos}), ambiguous_repo_blind_matches ({developer, issue_id, plausible_repos}), and issue_spend_without_same_developer_outcome ({developer, issue_id, cost_repo}), plus unqualified_cost_share. The three per-(developer, issue) lists are sorted and capped at 50 rows each; incompatible_repos_total, ambiguous_repo_blind_matches_total and issue_spend_without_same_developer_outcome_total carry their uncapped counts. Arrays are empty when clean. Repository gaps compare qualified real repo ids exactly; unqualified rows cannot satisfy repository presence. Issue joins require the same canonical developer. The repository-only fold does not establish that any particular developer's issue joined. Points use the same policy-projected Outcome.Points() as scores, including corrections. Dollar figures use captured non-API costs. unqualified_cost_share divides captured micro-dollars on non-real repositories by all captured micro-dollars in the window; it is zero when the denominator is zero or under strict ?repo=. Cost presence for join checks includes manual cost rows, matching the scoring join. All inputs are loaded in the score's read snapshot; scoring and attribution are unchanged. Join readiness is entirely absent in team/division modes. Live checkpoint evidence, current engine enablement and on-disk worktree checks are absent from /scores, its comparison responses and report manifests. The separate captured-dollar diagnostics route serves that live evidence without changing reproducible scores.

  • data_quality (omitempty) -- presence contract (#351): the block is now present whenever the window has spend or outcomes (it always carries the always-on attribution shares below); it is omitted ONLY for a truly empty window. So a consumer must key off the SPECIFIC field it cares about, NOT off block presence as a boolean "a warning fired" (the pre-#351 reading -- still true for the tripwire fields, which stay omit-when-clean). Fields: the zero-token-outcome tripwire (#136): {zero_token_outcomes: [{developer, issue_id, tokens}]} in developer mode, {zero_token_outcome_count: <int>} (name-free) in team mode. May additionally carry mixed_price_versions ([<int>], omitempty, #293): the ascending distinct price_table versions that priced the window's token_events, present ONLY when that set has more than one element -- the mix cost_micro's immutability (#233) creates, which the single top-level price_table.version stamp would otherwise mask. Developer mode only (#864): it reads every row of the window, pseudo-developer spend included, so in team and division mode it is omitted, and there price_table.version names only the active table, not every table that priced the window. A floored warning is to return through a follow-up issue. It also carries the true attribution-coverage fields (#351):

    • attributed_cost_share (<float> in [0,1], omitempty) -- the fraction of window cost_micro that joins to a REAL issue rather than the unattributed sentinel (attributed / total, exact from the same window's cost composition). This is the honest coverage headline an adopter must see up front -- but it measures issue-attribution, which is NECESSARY BUT NOT SUFFICIENT for a score: spend on a real issue with no OUTCOME counts here yet drives no TIER. Read it WITH attributed_outcome_share -- the two measure DIFFERENT joins (cost->issue here, outcome->cost there) and are NOT expected to reconcile. Present whenever the window has spend; omitempty fires ONLY when there is no spend (a real 0.0 -- all spend unattributed -- IS emitted, not dropped). Do NOT confuse it with coverage_pct (see caveat below). Developer mode only (#864): team and division mode never publish it, because beside the group rows and total it bounds one person's spend even when k counted people carry the linked and the unlinked cost.
    • attribution_coverage (string, omitempty, #864) -- "not_shown" on every anonymized window that has spend, here and in each /scores/compare window's data_quality; absent in developer mode and on a window with no spend. It has that one value only. In these modes treat an absent share as "not shown", never as full coverage, whether or not this field is present.
    • excludes_unattributed_spend (<bool>, omitempty, #864) -- true on every anonymized response, here and in each /scores/compare window's data_quality; absent in developer mode. Spend recorded under the unattributed pseudo-developer (an org-usage poller's remainder, proxy requests with no developer header) is dropped before any row, total, count or share is computed, so no difference of published figures is that spend. It is constant: it does not say whether a window held such spend. The amount is visible in developer mode, and GET /api/v1/org_actual_spend (write token) carries the invoices. The pseudo-developer never holds paid spend, so spend_leverage here is captured list-price spend divided by paid spend over the same people.
    • attributed_outcome_share (<float> in [0,1], omitempty) -- the fraction of the window's outcomes whose canonical (developer, repo, issue) has ANY matching token spend (tokens > 0, a looser bar than the zero-token tripwire). Falls to ~0 under the identity-mismatch failure mode below. Present whenever the window has outcomes; omitempty fires only when it has none. Name-free. A high attributed_cost_share with a low attributed_outcome_share and a non-empty unjoined_developers is the silent-TIER=0 signature the three fields exist to make loud.
    • unjoined_developers (omitempty) -- developers present on only ONE side of the cost/outcome join (#351/#125): cost keyed to an OS username, outcomes to a GitHub login, with no developer_alias mapping them, which otherwise reads as a silent TIER=0. Shape {cost_only?: [<name>], outcome_only?: [<name>], cost_only_count, outcome_only_count}. Present only when at least one side is non-empty. In developer mode the name lists are populated so the operator can map the aliases; in team-aggregation mode (#185) the names are suppressed and only the two counts carry, through the same k-anon guard as zero_token_outcomes.

    Caveat -- coverage_pct is NOT attribution coverage. The per-developer / total / team coverage_pct is capture fidelity: the share of the spend tierd DID record that arrived per-request (realtime proxy/JSONL) rather than as a coarse estimate. It reads ~100% even when most spend never attributes to an issue, which is why it was mistaken for completeness. Its computation is unchanged (#136 keeps the wire name stable; the dashboard labels it "Fidelity"). Attribution completeness is data_quality.attributed_cost_share, added here.

    • unattributed_buckets (array, omitempty) -- the labeled split of the single unattributed mass (attribution refocus, Option B): one row per reason the join could not tie spend to an issue. Shape [{bucket, cost_usd, share}], sorted by descending cost. bucket is the stable label unattributed:main (spend recorded on main or master, so TIER could not link it to an issue), unattributed:detached-head, unattributed:branch-without-issue, unattributed:foreign-repo (#823: a worktree of a repository this install does not configure; not counted in exploratory_cost_share; its rows always carry repo = unqualified, and /events refuses any other value), or the base unattributed (host-blind producers). share is of TOTAL window cost, so the buckets + attributed_cost_share sum to 1.0. Present only when the window has unattributed spend. Developer mode only (#864): a bucket one person's spend fills publishes that spend.
    • exploratory_cost_share (<float> in [0,1], omitempty) -- the unattributed:main bucket's share of total window cost: spend recorded on main or master, so TIER could not link it to an issue. This spend stays in the denominator. The field reports how large it is; it does not remove it. The field name is historical and is kept because it is the wire contract: the value does not say whether the work was exploration, planning or anything else. A common cause: the session was started in the main checkout, and the work ran in a separate worktree. Claude Code usually records the branch checked out in the directory where the session started (measured 2026-09-26 across one install's session files); a later cd into another worktree is not recorded, and for harness worktree agents TIER substitutes the session's last named branch. Start the session inside the worktree, or on a branch named with the issue number, and the spend is attributed to the issue. That helps only if the worktree's branch names the issue; otherwise the spend lands in unattributed:branch-without-issue. Pointer-emitted so a real 0.0 carries; present alongside unattributed_buckets, so developer mode only (#864).
    • Cost horizon (#512) -- four fields that say whether this window starts before TIER began recording cost. They describe the requested scope: the whole installation without ?repo=, and only that repository with it. All four are absent when the scope holds no cost at all (on a ?repo= read, when that repository has no cost rows, even if other repositories do), and also when the server could not look the horizon up (it logs the error and still returns the scores), so absence never means "covered". Otherwise the first three are always present. Name-free; they carry in both modes. See interpreting-the-number.md for how to read them.
      • cost_coverage_start (RFC 3339 string) -- the time of the earliest cost event in the scope: the installation's cost horizon without ?repo=, or that repository's with it.
      • window_predates_cost_capture (<bool>) -- true when since is earlier than cost_coverage_start, which means the window counts outcomes against cost that was never recorded and the TIER reads too high. An explicit false is sent when the window is covered, so silence never stands in for "checked and clean".
      • cost_coverage_safe_since (YYYY-MM-DD) -- the earliest since value that clears the horizon. When the horizon falls partway through a day, this is the following day, because since always starts at midnight.
      • source_coverage_start ({<source>: <RFC 3339 string>}, omitempty) -- each capture source's own earliest cost event in the scope. Sent only when more than one source has recorded cost in the scope: a window can clear the overall horizon and still start before one source began.
    • uncounted_active_ids (omitempty, #856) -- anonymized (team/division) modes only: legacy activity diagnostics for identifiers with spend or merged work in the window that fail the roster, bot or legacy capture checks. These categories do not enumerate D4-only exclusions: an identifier can be absent from these counts and still fail the current k-anonymity rule below. Shape {manual_only, push_only, not_on_roster, bot}, all integers; each identifier is counted once, under the first reason that applies in the order bot, not_on_roster, then manual_only (it has a hand-entered POST /costs row and no captured activity) or push_only (its only activity is push-captured merged work). Stated once per window, for the whole org: it does not move with ?work_type= or ?team=, and it never appears on a teams row, a work_types[] segment or /scores/compare. Absent when the legacy checks find no exclusions, and in developer mode. The unattributed pseudo-developer (#853) never counts and is never reported here: it is not a person anyone could put on the roster.
      • Current counting rule (D4). A fixed named_subject counts toward k only when it has outcomes or cost in the window, one of the identifiers its person's cost or outcomes in the window were recorded under (aliases join identifiers into one person) holds its own roster membership overlapping the window, so an identifier idle in the window never rosters another's activity (#914), it is not a bot (GitHub account type Bot on an outcome the webhook recorded in the window, a [bot] login suffix, or a fixed list of bot logins for older rows), and it has qualifying local token-event evidence in the window: bound_upload tied to that subject's own personal/device credential, server_watch, or vendor_attributed with a root-authored insert-time mapping that still matches the subject and covers the event time without being voided. The fixed subject must remain its own canonical identity; aliases cannot lend another subject's evidence. Imported rows, shared or legacy uploads, manual costs and outcomes alone never establish a seat. An imported person needs an own-credential upload here to become locally bound before other qualifying local evidence can count for them. An uncounted identifier's figures stay summed in its row and in total, except a pseudo-developer's, which an anonymized mode drops (#864, see excludes_unattributed_spend).
      • Per-measure floor. A group is named, and a residual published, only when at least k counted people carry each figure it publishes: k with captured cost for total_cost_usd (a hand-entered POST /costs row fills no cost seat), k with outcomes for weighted_points, k with paid spend for actual_paid_usd, and both populations for each ratio: tier and cost_per_point (cost and outcomes), spend_leverage (cost and paid). coverage_pct splits cost into a realtime and a non-realtime share, and each non-zero share needs k counted carriers with captured cost in that share (a hand-entered fee is no carrier of the non-realtime share). A figure that no row carries (it is exactly 0) needs none.
      • Remedy: put the people on the roster and capture local evidence with their own personal/device credentials, server-watch, or valid root-mapped vendor attribution. A collector or proxy using a shared credential does not establish a counted person. The floor applies to shared-viewer reports.
    • kanon_suppressed (omitempty, #593) -- present when a sub-k residual cohort was WITHHELD from an anonymized (team/division) response. Shape {developers, k_anonymity, withheld_total, withheld_cost_composition, withheld_teams, withheld_segment_reconciliation}. withheld_teams (#864) is true whenever the block is present: the whole response is withheld, named rows included. withheld_cost_composition and withheld_segment_reconciliation are false: an anonymized mode never builds either block (#864). Name-free: counts only, never an identity.
      • developers counts people under the counting rule above (#853, #856) and may be 0, when the withheld group holds only uncounted identifiers. It may also be k_anonymity or more, when the residual was withheld because one of its figures is carried by fewer than k counted people (the per-measure floor). Widening the window clears a suppression only if it brings enough counted people into the residual (people with no team, or in a team too small to have its own row).
      • When it is present, teams and total are ABSENT (#864; before it the named rows stayed and only total, cost_composition and segment_reconciliation went, and the visible rows no longer summed to the window). That is deliberate. Before #593 the residual bucket was emitted with no floor, publishing a sub-k cohort's exact figures; and merely removing that row would not have closed it, because total minus the named rows reconstructs the hidden cohort by subtraction. Both the row and every unfloored aggregate over the same population are withheld together.
      • ⚠️ This retires the previous guarantee that k-anonymized rows always sum to the grand total. That property is what makes the disclosure recoverable, so it and k-anonymity cannot both hold. Consumers that reconciled rows against total must treat a suppressed response as a distinct case rather than a reconciliation failure.
      • k_anonymity is the floor actually in force, after the library's MinKAnonymity clamp -- not the value a caller requested. Note tierd serve refuses to start below MinKAnonymity (3), so on a served deployment the configured and enforced values always agree; the clamp is defence in depth for direct library callers. The field reports the enforced value regardless, so a consumer never has to know which.
      • A consumer must key off this field to distinguish "withheld for anonymity" from "this window has no data". Those demand opposite reactions: the first is fixed by widening the window or querying a level with more people in it, the second by fixing capture.
      • Developer-aggregation mode never emits this: it names everyone by design, so there is nothing to reconstruct.
      • One further placement carries the same shape (#593): /scores/compare carries a top-level kanon_suppressed rather than one inside a window's data_quality, because the two-window fold suppresses a cohort from BOTH sides together or from neither -- attaching it to one window would imply the other was unaffected. (work_types[].kanon_suppressed was a second placement until #864 removed work-type segments from anonymized responses.)
    • repo_scope (<string>, omitempty, #590) -- the canonical repository this response was narrowed to, echoed back canonicalized (what was queried, not what was typed). Present on every ?repo= read; absent on an unscoped one. This is the field that makes "scoped" and "not scoped" distinguishable on the wire, which is the whole point of #590 -- the original defect was not that ?repo= did nothing, it was that a caller could not TELL it did nothing. A consumer that requires a scoped figure must assert on this key, never on having sent the parameter. Name-free; carries in both modes.
    • repo_scope_excluded (omitempty, #590) -- what the strict scope DROPPED from the window as repo-blind. Shape {token_events, cost_usd, outcomes}. Present only on a scoped read that actually excluded something; a scoped read over a fully-qualified window omits it, and that absence is the clean signal -- the scoped figures are a true total rather than a lower bound. Read it as: this much of the window could not be placed in ANY repository. The excluded rows are not claimed to belong to the scoped repository; they are unattributable by construction, which is what the sentinel means. cost_usd is the size of the hole in the scoped denominator and outcomes the hole in the numerator -- they move a TIER score in opposite directions. Name-free. ⚠️ The two sides do not share a lower bound. token_events/cost_usd count the ATTRIBUTION BAND [since - 14d, until) and outcomes counts [since, until), because a scope can suppress a repo-blind row inside an outcome's 14-day look-back (store.UnqualifiedExclusionWindow). 🔑 The manifest pins this same quantity as report_manifest.repo_scope_excluded (#751) -- but in micro-dollars (cost_micro), and it is emitted on every scoped manifest including an all-zero one, where this block is omitted when clean. Two surfaces, two jobs; do not diff them field-for-field.
    • spend_leverage_suppressed (<bool>, omitempty, #590) -- true when a repo scope suppressed spend_leverage / actual_paid_usd, which are installation-wide by construction and cannot be scoped (see ?repo= above). Absent entirely on an unscoped read: suppression is a property of scoping, not a standing caveat. Without this field a scoped response's actual_paid_usd: 0 would be indistinguishable from "no actual spend has been recorded", which is a materially different statement. Name-free.

  • work_types (array of workTypeSegmentJSON, omitempty) -- the authoritative type-segmented view (#187): one entry per work_type, each {work_type, developers?, total?} scored over ONLY that category. This is the surface for comparing developers; the pooled developers/total above are retained for back-compat and are not a cross-type ranking. 🔴 Developer mode only (#864): absent in any anonymized mode, where the group rows are the one breakdown; the per-segment aggregation, teams and kanon_suppressed keys existed only there and are gone. #937 (an audit that solves the published sums) is the route to bring a work-type view back to anonymized modes.

  • segment_reconciliation (omitempty, #466) -- accounts for the window's WHOLE spend against the work_types segments above, so a reader can see how much the segmented view leaves out and why. Omitted when the window has no cost rows. It is ALSO dropped — silently, with a server-side ERROR log — when the block is not fit to publish: an accumulator saturated at the int64 ceiling, or any figure came out negative. That third case is the one absence this API does NOT declare on the wire, because it signals a server fault rather than a policy withhold; its only reachable trigger is a window whose summed spend approaches ~9.2e12 USD. Shape: {developers: [row], total: row} where row is {developer, window_cost_usd, window_cost_micro, outcome_linked_cost_usd, outcome_linked_cost_micro, no_outcome_cost_usd, no_outcome_cost_micro, unattributed_cost_usd, unattributed_cost_micro}. 🔴 Developer mode only (#864): the whole block is absent in any anonymized mode, which publishes no segments to reconcile, and whose no-outcome and unattributed figures would be a second breakdown of the window's cost. total is the always-present name-free rollup and carries no developer. ⚠️ A deployment running an org-usage poller will see a row whose developer is literally "unattributed" — org-level invoice aggregates that cannot honestly be split per person — with its cost wholly in unattributed_cost_micro. That is the developer sentinel, a different field from the issue sentinel discussed below.

    • Why it exists. A segment's TIER denominator is outcome-linked cost only: work_type is a property of the OUTCOME, so spend on an issue that produced none has no category to be filed under and appears in no segment. The pooled headline score keeps that spend in its denominator, so every per-type TIER read systematically better than the headline, invisibly.
    • The invariant, and exactly where it holds: outcome_linked_cost_micro + no_outcome_cost_micro + unattributed_cost_micro == window_cost_micro, EXACTLY, on the integer fields and only those. The _usd companions are independent float conversions, so a + b + c === d on them is false for roughly one triple in ten — 22601 of 216000 in a deterministic SYNTHETIC sweep spanning $0.008 to $78 per component (TestSegmentReconciliation_DollarsAreNotExact); the same sweep fails 0 of 216000 on the integers. That rate is a property of the sweep's magnitudes, not a measurement of any production window. Assert on the micros, display the dollars.
    • The invariant is INTERNAL to this block. All four figures fold from ONE DeveloperIssueCostsWindow snapshot, which makes it an arithmetic identity no concurrent writer can break. It is not a cross-block promise: window_cost_micro and the pooled total come from separate non-transactional reads over a window whose upper bound is usually open, so on a live store they can differ by rows written between them. Do not assert across blocks.
    • ⚠️ It does NOT reconcile against the segments' totals, and no invariant claims it does. The segments can legitimately double-count a cost row -- an issue carrying two work types is charged to both segments, and under the tolerant repo join (#231) a repo-blind cost row is charged to every qualified outcome sharing its issue id. Both over-counts are deliberate (they lower TIER, so ambiguity never flatters a developer), which makes "segments + gap == window" false on ordinary data. This block partitions the underlying cost ROWS instead, each counted exactly once, under the identical repo rule the segments use.
    • ⚠️ no_outcome and unattributed are DIFFERENT and are never merged. no_outcome is cost tied to a REAL issue id that produced no outcome in the window (abandoned work, work in flight, a PR that never merged) -- the gap this block exists to surface. unattributed is cost the collector could not tie to any issue at all (the unattributed sentinel family), which is the established meaning of the word elsewhere in this API and matches cost_composition's split. It is reported here only so the three parts sum to the window.
    • Not narrowed by ?work_type: the gap is a property of the developer's window, not of the segment the caller asked for.

  • cost_composition (omitempty) -- cost-composition sidecar (#234): a whole-window, name-free breakdown of WHERE spend went, for optimization. Omitted when the window has no token spend. Shape: {total_cost_usd, attributed_cost_usd, unattributed_cost_usd, unattributed_share, cache_read_share, premium_model_share, by_model: [{model, host, cost_usd, share, premium}], by_class: {input_tok, output_tok, cache_read, cache_write}}. Dollar figures are USD; shares are fractions in [0,1]. Reconciliation (exact in the underlying integer micro-dollars; the USD floats reconcile to micro-dollar precision): attributed_cost_usd + unattributed_cost_usd == total_cost_usd and sum(by_model[].cost_usd) == total_cost_usd (no residual bucket). cache_read_share is cache_read / (input + cache_read + cache_write) (input-side hit share, docs/ pricing-philosophy.md §4); premium_model_share is the SPEND share on models pricing >= $4/M base input (the frontier/reasoning tier; PremiumInputRateThresholdPerM, lowered from $5/M with price table v10; releases up to v0.4.1 still use $5/M). by_class is TOKEN counts, not allocated dollars (a stored blended cost_micro is not exactly splittable per class); by_model.premium and the model breakdown are host-aware (#300), so an open-weights model split across hosts stays multiple rows. 🔴 Developer mode only (#864): absent in any anonymized mode. Naming no individual is not enough: every field but total_cost_usd splits the window's cost a second way, and a model one developer used published that developer's spend in by_model (measured: $4.44). total_cost_usd restates total, which stays. #937 is the route to bring a per-model view back to anonymized modes.

• developerScoreJSON: developer, tier, weighted_points, total_cost_usd, actual_paid_usd, spend_leverage, coverage_pct, exploratory_cost_share, cost_per_point, sample_n, ci_low, ci_high, cost_per_point_ci_low, cost_per_point_ci_high, ranked, flagged_outcomes. exploratory_cost_share (attribution refocus, Option B) is this developer's unattributed:main cost / their total window cost -- the per-developer companion to data_quality.exploratory_cost_share (the name is historical; it does not say the work was exploration), naturally k-anon-safe because developer rows are not emitted in team-aggregation mode. The array is sorted by developer identifier, never by TIER; the ranked flag (#133) tells a client which rows clear the evidence floor. The dashboard keeps that order and never sorts the rows by TIER (#830); the v0.4.1 dashboard put ranked rows first, highest TIER first. cost_per_point (#239) is total_cost_usd / weighted_points -- the inverse-unit dual of tier (numerically 1000/tier); it is null on a zero-point row (#472) so "no accepted outcome" is not encoded as the most-efficient 0, while a zero-recorded-cost row (shown as "No recorded AI cost", often a capture gap rather than free work) keeps 0, meaning no recorded cost, not an efficiency reading. cost_per_point_ci_low/high are its nominal 95% self-relative bootstrap bounds (coverage unvalidated), the reciprocal (ends swapped) of the tier CI -- 0 for unranked rows. See docs/rubric.md.
• #1233 interval withholding (v0.6.1 wire-contract amendment). On /scores developer rows, developer detail, work-type developer rows and each developer compare side, the row's OWN attributed-cost share must be at least 0.5 for an interval. This uses the cost paired with resampled outcomes, divided by this row's total cost, after the same allocation/scaling as the bootstrap; its complement is fixedCostUSD, including cost on issues without outcomes and non-resampled repair cost. It is not the window-level data_quality.attributed_cost_share. Exactly 0.5 passes; a nonpositive total has no interval. The evidence floor is checked first: an unranked row always says withheld: below evidence floor, even when its attributed-cost share is also below 0.5. Withheld ci_low, ci_high, cost_per_point_ci_low/high remain present numeric 0, following the existing below-evidence-floor convention; they are neither null nor omitted. Compare sides have no cost-per-point bounds. Additive ci_note says withheld: row attributed-cost share below 50%, or withheld: below evidence floor; shown intervals carry the exact label excludes uncertainty from unattributed spend. ranked, the score and cost-per-point point estimate do not change. significant is false if either side's interval is withheld, even when both rows remain ranked. For months sealed after this change, team/division /scores windows always return data_quality.interval_status: "not_shown", without row shares, reasons or floor-dependent status; live /scores windows do too. These two diagnostics are /scores-only, not compare-window or /issues fields. Older sealed months omit both interval_status and partition_diagnostics; stored seal bytes never change.
• #1233 partition diagnostics (additive, v0.6.1). /scores carries data_quality.partition_diagnostics: developer mode gets {outcomes_per_issue: [{outcomes, issues}], weight_buckets: [{weight, outcomes, points}], outcome_n, capped_pr_count, capped_pr_count_share, capped_pr_points, capped_pr_points_share, points_per_pr, points_per_1000_usd, notice}. Issues are keyed by repository and issue ID across the window; distributions are sorted ascending. Buckets use raw size weight and effective scored points. The cap is weight 8, including quality-discounted outcomes. Cap shares use non-push PR outcomes (weight_source != "push"), including legacy PRs without a number, by count and by points; points_per_pr uses those PRs too. All scored outcomes and whole-window cost enter points per $1,000. Zero share/mean denominators are null; zero-cost TIER remains 0. The notice discloses same-issue and cross-issue partition sensitivity and that diagnostics apply no automatic penalties. Team/division /scores modes return the constant string not_shown for live windows and months sealed after this change, including suppressed or empty windows. Older sealed months omit the field; stored seal bytes never change.
• teamScoreJSON: team (omitempty), tier, weighted_points, total_cost_usd, actual_paid_usd, spend_leverage, coverage_pct, cost_per_point, ranked. No CI at team grain (the bootstrap is a per-developer signal, #133). ranked (#502) is the #133/#136 evidence floor on the aggregate's SUMMED inputs -- outcomes >= MinRankedOutcomes, spend >= MinRankedCostUSD, no zero-token outcome among the members. tier is unaffected by it: an unranked aggregate still carries its true quotient, so a consumer must gate the headline on ranked rather than expect a scrubbed number (#136). There is deliberately no team-level sample_n -- see the #502 changelog entry.

GET /api/v1/diagnostics/captured-dollars

• New ADDITIVE public v1 read endpoint (#972 / #1279). It carries the same stability promise as the other public v1 read routes: existing response fields retain their names, meanings, units and scopes; incompatible changes require the versioning/deprecation process above.
• Auth and modes: read scope (requireRead); developer mode only. Team and division modes return 403, without diagnostic counts or shares.
• Bounds: the same since, until (or before) and strict repo query bounds as /scores. Malformed dates, an upper bound at or before since, disallowed repository scopes (including unqualified), and unknown query parameters return 400. A diagnostic query failure returns 500 here alone.
• Release history: /scores never carried captured_dollar_diagnostics in any release; that field existed only on this unmerged branch. Adding this endpoint changes no released /scores wire contract.
• Response: receipt with share_label: "share of captured dollars", since (RFC3339), optional until (RFC3339; absent means open-ended), scope (fleet or the strict requested repo), sample_size (captured token-event count), captured_cost_usd, engine_enablement (engine → enabled, disabled or unknown), enablement_scope, buckets and main_checkout_worktree_share, stored_cwd_sample_size (events with stored cwd) and stored_cwd_cost_share (their share of captured dollars). Metadata availability does not establish historical working-directory evidence. The worktree share is captured dollars in unattributed:main whose stored cwd resolves to a main checkout with verified linked worktrees present now, divided by all captured dollars in scope. buckets[] has {engine, bucket, subagent_origin, sample_size, captured_cost_usd, share}; each share uses that same whole-window captured denominator, not the engine subtotal. Only unattributed buckets appear; attributed dollars remain in the denominator. Empty/zero-cost windows have zero shares. Engine uses capture source (jsonl → claude-code). subagent_origin is session-level: main_session (parent paths only), subagent (subagent paths only), mixed (both), or unknown (no stored evidence). Parent and subagent events sharing a session id cannot be split per event. The stored cwd is retained when all checkpoints agree; otherwise a single parent path supplies cwd, or cwd remains unknown. Current local engine enablement cannot establish historical or remote-shipper enablement. Paths/session ids are never emitted. Manual source=api costs are excluded. These are never shares of real spending.

Live checkpoint evidence, current engine enablement and on-disk worktree checks are excluded from /scores, its comparisons and report manifests, so they do not change verify-report's reproducible canonical body. Doctor reads this separate endpoint. Strict ?repo= reads use only the selected repository's inputs, including metadata joins. See the explanation and limitations.

GET /api/v1/scores/{developer}

• Scope: read. Success: 200 OK, developerDetailResponse.
• Blanket 404 in any anonymized (team/division) mode (#185, #270): it names one individual by construction; the 404 is returned for every path value, before any lookup, so it is not an existence oracle.
• Fields: developer, tier, weighted_points, total_cost_usd, actual_paid_usd, spend_leverage, coverage_pct, cost_per_point, sample_n, ci_low, ci_high, cost_per_point_ci_low, cost_per_point_ci_high, ranked, flagged_outcomes, issues. cost_per_point and its CI mirror developerScoreJSON (#239). issues is an array of {issue_id, weight, quality, pr_number (omitempty), zero_token}. Note: this endpoint's top-level object has no rubric/price_table stamp of its own -- read those from GET /api/v1/scores for the same window.
• Query: ?since=, ?until= (or ?before=), ?repo=. Any other parameter is a 400 -- see strict query-parameter validation.
• ?repo= (#590) applies the SAME strict scoping as /scores, including the unqualified exclusion, and narrows the issues array too -- a scoped detail must not list work done in another repository. Adds three top-level fields mirroring the /scores data_quality ones: repo_scope (omitempty), repo_scope_excluded (omitempty), spend_leverage_suppressed (omitempty). Under a scope actual_paid_usd and spend_leverage are suppressed to 0 and the suppression is declared -- read the flag, not the zero.

GET /api/v1/scores/compare

• Scope: read. Success: 200 OK, compareResponse (#277).

• Purpose: a before/after period comparison -- two half-open windows in, per-row deltas plus a CI-overlap significance flag out. In developer mode it reuses the SAME windowed scores computation as GET /scores, so a compared score matches /scores for the same window. It is an aggregate view like /scores; in anonymized (team/division) mode it compares sealed calendar months, refolding rows with the two-window intersection, so group rows can differ from each month's standalone /scores report.

• Developer-mode only: free-window queries (each window mirrors /scores' since/until grammar and validation, #276): ?since_a=, ?until_a= (window A = "before"); ?since_b=, ?until_b= (window B = "after"). Each since_ defaults to the start of the UTC day 90 days ago (#746, the same default /scores uses); each until_ is an optional exclusive upper bound that must be strictly after its since_ (400 otherwise). Each since_ is retention-checked (422 if it predates the retention horizon), not until_. Every delta is B - A.

• Team/division mode: use ?period_a=2026-05&period_b=2026-06 for two closed, sealed months. Give both parameters, with A earlier than B, or omit both for the two latest sealed months. An unsealed month returns 404; incompatible sealed configurations return 409. Reads never seal a month. Free bounds are refused with 400, even when they describe whole months or are empty. For the developer-mode example ?since_a=2026-05-01&until_a=2026-06-01&since_b=2026-06-01&until_b=2026-07-01, the exact error is:

  ?since_a=, ?until_a=, ?since_b=, ?until_b= not accepted for anonymised reports (#913): they are served per sealed calendar month, so two overlapping windows cannot be differenced to isolate one person's figures. Remove ?since_a=, ?until_a=, ?since_b=, ?until_b= and select two months with ?period_a=YYYY-MM and ?period_b=YYYY-MM (neither: the two latest sealed months)
  

• Any parameter outside the mode's allowlist is a 400 (#590) -- including ?repo=, which this endpoint does not implement. It is rejected rather than ignored precisely because it returns the same class of cost figure from the same shared windowed computation as /scores, so silently accepting-and-dropping it would reproduce the #590 defect one endpoint over. Scoped comparison is a legitimate future feature; being quietly unscoped is not a feature.

• Fields:

  • window_a, window_b ({since, until?, data_quality?}) -- each window's echoed bounds and its OWN data_quality block (#277): the zero-token / mixed_price_versions signal is per window (a mixed-version WARN can apply to one window and not the other), same shape and mode-dependent name-suppression as /scores' data_quality. Each block also carries the cost-horizon fields (cost_coverage_start, cost_coverage_safe_since, window_predates_cost_capture, and source_coverage_start when more than one source has recorded cost), checked against that window's own since; they are omitted when the store holds no cost. Sealed team/division comparisons omit cost_coverage_safe_since, as do the stored monthly bodies. The #351 coverage shares are a /scores-only surface; in an anonymized mode each block carries attribution_coverage as on /scores. until is omitted when the window is open-ended.
  • price_table ({version, effective_date, table_hash, file_hash}) -- always present active-table stamp (#233, extended by #713); per-window pricing mixes surface via each window's data_quality.mixed_price_versions (developer mode only).
  • mode (string) -- "developer" in developer mode; in team/division mode, echoes the level both months were sealed under ("team" or "division"). It tells a consumer whether developers or teams carries the rows (the same discriminator as /scores' aggregation).
  • developers (array of developerDeltaJSON) -- per-developer deltas in developer mode; an explicit empty array in any anonymized mode (#185, #270), never a named row. Each row: {developer, present_a, present_b, a, b, delta_tier, delta_weighted_points, delta_total_cost_usd, significant}. a/b are scoreSideJSON ({tier, weighted_points, total_cost_usd, actual_paid_usd, spend_leverage, coverage_pct, cost_per_point, sample_n, ci_low, ci_high, ranked}). cost_per_point (#239) is the same points-guarded total_cost_usd / weighted_points (null on a zero-point side, #472) /scores' developer rows and the team compare sides carry, added for contract parity; no self-relative cost_per_point CI on a side. Rows are the union of developers across both windows; a delta and significant are computed only when the developer is present in BOTH windows (0/false otherwise, never fabricated against an absent side).
  • teams (array of teamDeltaJSON, omitempty) -- populated only in an anonymized mode (team #185 / division #270): each row {team (omitempty), a, b, delta_tier, delta_weighted_points, delta_total_cost_usd, significant, ranked} where a/b are teamScoreJSON. k-anonymity is a two-window INTERSECTION (#277): a group is a named row only if it independently clears the k-floor in BOTH windows; a group sub-k in EITHER window (including one present in only one window) folds into the single other residual on BOTH sides, so a group's PRESENCE never differs across windows and no sub-k aggregate can be recovered from a delta. significant is always false here: group aggregates carry no bootstrap CI (an interval is a per-developer signal, #133). 🔴 Absent, with kanon_suppressed declared, when the comparison's other residual or EITHER window's own other bucket (the one /scores folds for that window alone) does not reach k (#864). The intersection folds into other a group that is sub-k in the other window, so without the per-window check a comparison's other or total minus that group's row from /scores or a second comparison was the window's own sub-k residual.
  • total (teamDeltaJSON, omitempty) -- name-free grand-rollup delta across every developer in each window. significant is always false. ⚠️ ABSENT in two distinct cases: both windows are empty, OR a sub-k residual was suppressed (#593) -- there the delta minus the named group deltas would reconstruct the hidden cohort. kanon_suppressed is what tells the two apart. Developer mode never suppresses, so there it is absent only for two empty windows.
  • kanon_suppressed (omitempty, #593) -- top-level, present when a sub-k residual was withheld from the comparison. Same shape as /scores' data_quality.kanon_suppressed: {developers, k_anonymity, withheld_total, withheld_cost_composition, withheld_teams, withheld_segment_reconciliation}. It sits at the top level because the two-window fold withholds a residual from BOTH sides or from neither; the residual is withheld when EITHER side is unsafe, and since #864 the whole comparison goes with it (withheld_teams is true).
    • developers counts people under #856's rule and may be 0, when the withheld group holds only uncounted identifiers. It is the largest count among the withheld residuals (the comparison's two sides and each window's own), a magnitude hint and not a union.
    • withheld_total is true. withheld_cost_composition and withheld_segment_reconciliation are always false here: compare ships neither sidecar, so none was withheld.
    • Never emitted in developer mode.
  • ranked (bool, on every teamDeltaJSON -- both teams[] rows and total) -- the derived ranking verdict of the comparison itself (#605): a.ranked && b.ranked, a boolean AND over the two sides' own #133/#136 verdicts and never a third floor. The rule it encodes is one sentence: anything derived from an unranked input is itself unranked. It is an AND rather than an OR because a ranked baseline beside an unranked selected window lets a reader reconstruct the withheld ratio exactly (selected = baseline + delta), and % change = delta/baseline is a pure function of the withheld baseline ratio. Always present, never omitempty: false and "an older server that never said" must stay distinguishable on the wire (the ambiguity behind #603). Consumers read this field rather than re-deriving the conjunction -- one producer, so the floor reaches every consumer instead of being re-implemented at each.

• Unvalidated descriptive bounds: Nominal 95% bounds. Coverage is unvalidated: in constructed tests where several outcomes share one issue, they covered the true value less often than 95%. They are descriptive resampling bounds and exclude uncertainty from unattributed spend, incorrect attribution and uncaptured usage. /scores, its work-type segments, developer detail and /scores/compare carry Tier-Bounds-Status: unvalidated_descriptive, Tier-Inference: not_established and a Tier-Bounds-Note header. Legacy ci_* field names remain for compatibility.

• Legacy non-overlap result: significant is retained, not a validated inference verdict. It is true only when a developer is present, above the evidence floor and (in v0.6.1, #1233) at or above the row's own 50% attributed-cost-share floor in both windows and the bounds do not overlap; touching ends overlap. Withheld bounds, an absent side or a below-floor side make it false; it is always false for groups. Neither value establishes an effect or a noise threshold. The dashboard shows “inference not established” and does not colour changes from this flag.

• Unblocks the dashboard dumbbell comparison (#278).

Seal disclosure (#1233)

Sealed report bytes and body_digest never change. /report_manifest adds seal_disclosure, and sealed /scores/compare includes that object on each window_a / window_b. It contains sealed_at (actual insertion time in UTC), configured_grace_seconds (nullable), grace_status (recorded or not_recorded), days_after_period_end, revert_windows_at_seal (withheld, open, closed, or not_recorded) and note. Future seals record their grace and whether any recorded outcome's 60-day revert window was still open, atomically at the actual insertion time. The note states that some windows were still open only for open.

Every non-developer seal level returns withheld, because outcome-dependent observations can identify a person in an anonymized cohort. This includes all production seals in team and division modes; developer mode seals the shared team view for org history while its developer reports remain live. Only developer-level records can return open (recorded as true at sealing), closed (recorded as false, or inferred for legacy records as below), or not_recorded (legacy status unknown).

Legacy grace is null / not_recorded, never the current configuration. Legacy window status for developer-level records is not_recorded unless the actual seal occurred at least 60 days after period end, when all nominal windows were closed; non-developer levels still return withheld. A short delay alone does not prove any particular outcome still had an open window. No historical report body, digest or config_digest is rewritten.

Sealed /scores exposes the same disclosure beside the stored bytes: Tier-Sealed-At, Tier-Report-Grace-Seconds (not_recorded for legacy seals), Tier-Sealed-Days-After-End, Tier-Revert-Windows-At-Seal and Tier-Seal-Note. The dashboard displays the selected month's own disclosure, and both months in a comparison. The default grace remains 14 days; it can leave 60-day revert windows open. Longer grace does not establish delivery completeness.

GET /api/v1/report_manifest

• Scope: read (satisfied by EITHER the viewer token or the write token). Success: 200 OK, reportManifestJSON.
• The (predicate, as-of) identity of the report GET /scores returns for the same window and scope (#715). A window predicate ALONE is an unstable identity: late JSONL ingestion adds rows carrying yesterday's ts that legitimately join "the same window", so two runs of the same query over the same [since, until) can return different numbers and both be correct.
• Query parameters: since (optional, defaults as on /scores), until (with the legacy before alias), repo. The allowlist is narrower than /scores': work_type and team are rejected with 400, not ignored, because neither changes any field below -- accepting them would let a caller believe they held a manifest for a filtered report.
• ?repo= is refused with 400 in any anonymized (team/division) mode (#185, #270), by the same shared guard /scores uses: this endpoint publishes per-repo ROW COUNTS over a caller-chosen window, and a cohort count is exactly the quantity a k-anonymity floor exists to protect.
• Top-level fields:

  • manifest_schema (string) -- the scheme tag, currently "tiermanifest1". It is the rollback seam, not decoration: it lets a consumer tell "produced by a DIFFERENT scheme" apart from "describes a different database state". Bumped when an existing field's MEANING changes; adding a field does not bump it.

  • since, until (omitempty), token_since (strings) and repo (string, omitempty) -- the predicate. The three timestamps are RFC3339 UTC instants, not calendar dates. An absent until means open-ended, which is a different report from one bounded at today's date, so it is never backfilled with a synthetic "now". ⚠️ The reason the instant is load-bearing MOVED with #746, it did not go away. It used to be that an omitted ?since= resolved to now - 90d carrying a time of day, so stamping a bare date would give two windows eight hours apart one identity. That case no longer arises from this server: the default is snapped to the start of its UTC day and every explicit bound already parses to midnight, so every bound this emitter publishes is midnight UTC. The field stays an instant because its type is shipped, and because the consumer side must keep handling instants a different producer -- a hand-written or pre-#746 manifest -- can carry.

  • ✅ Since #746 the default shape is re-runnable. A manifest requested with no window at all now carries a midnight-UTC since, which /scores can be re-queried with, so tierd verify-report re-runs it normally. Before #746 the default was the one shape that could not be fed to the verifier at all. ⚠️ Re-runnable is not "returns 0" — an open until means the re-run covers [since, ∞) as the database stands now, so later ingestion is a legitimate 1 (DIVERGED). Take the manifest and the /scores body on the same UTC day: each request resolves the default separately, and the two bounds differ by a full 24h across a midnight. 🔴 The refusal is still live and still correct for any OTHER producer. /scores accepts only whole-day bounds, so a manifest whose since is not midnight UTC -- hand-written, or emitted by a pre-#746 build -- has no query that reproduces its window, and verify-report exits 2 (could not check) rather than truncating the bound, because truncating would re-run a different window and compare its numbers against this manifest's.

  • ⚠️ token_since is since - 14d and is NOT decoration. The scoring path does not read token_events only inside [since, until): the #136 zero-token tripwire builds a per-outcome window [merge - AttributableWindow, merge], so an outcome near the lower edge is funded by events up to 14 days before since. watermarks.window therefore covers token_events over [token_since, until) and outcomes over [since, until) -- the two sides do not share a lower bound, and token_event_count is a count over the attribution band, legitimately larger than the report window alone suggests. A watermark bounded at since would hold still while a late-ingested row in that band cleared the tripwire and changed /scores.

  • aggregation (string) -- developer / team / division. Always present, unlike /scores, which omits it in developer mode: a manifest exists to be diffed, and a key that is absent in one mode makes "developer" and "the key was dropped" the same reading.

  • k (integer, omitempty) -- the k-anonymity cohort floor, emitted only in an anonymized mode, because that is the only mode in which any floor is applied. Publishing the configured integer in developer mode would assert a protection that is not in force.

  • price_table (object) -- version, effective_date, table_hash, file_hash (#713). ⚠️ source is deliberately absent. It is a local filesystem path; the 2026-08-28 ruling on the #713 review confines it to tierd score-log (a local CLI printing to the invoking operator's own terminal), because a served surface must not disclose the server's directory layout. table_hash already answers what reproducibility asks -- "are these the same PRICES" -- and answers it better than a path.

  • rubric (object) -- version, the weight rubric (#239).

  • tool_version (string), commit (string, omitempty) -- the binary. Not redundant with the two blocks above: Open()-time migrations rewrite token_events in place with no ledger row at all, so a binary upgrade is a report input that no watermark can see, and this is what makes it visible.

  • watermarks (object) -- the as-of half, split into two sub-objects because they are read over different predicates and carry different disclosure risk:

    • watermarks.window -- max_token_event_id, token_event_count, max_outcome_id, outcome_count. Windowed and repo-scoped. 🔴 OMITTED ENTIRELY in any anonymized (team/division) aggregation mode, with a top-level kanon_suppressed object declaring the withhold. These are unfloored counts of work over a caller-chosen window, and #593 established that narrowing ?since= alone -- with no ?repo= involved -- shrinks a cohort below the k-anonymity floor. /scores withholds teams and total for exactly those windows; publishing row counts there would hand back the activity volume of the one contributor /scores declined to name, sweepable day by day. The withhold is deliberately blunt (every anonymized request, not only sub-k windows): the precise alternative needs the real KAnonSuppression signal, which costs a full window load, and a cheaper approximation would be a second, divergent floor that errs toward disclosure.
    • watermarks.ledgers -- max_<ledger>_id and <ledger>_count for quality_history, reprice_row_audit, cost_correction_audit, repo_repair_row_audit, push_outcome_audit (#849) and correction_audit (#1235). Unwindowed and unscoped (see below), and present in every mode: install-wide and window-independent, so it carries no count of the caller's chosen population. Every key within a present sub-object is always present; a 0 is a real reading ("nothing here yet") and is never dropped.

  • events_digest, outcomes_digest (objects, omitempty) -- value and rows (#716, wired by #740; tierdig2 in #1235). value is "tierdig2:" plus 64 hex characters: a content identity over the ROWS the report was computed over. 🔴 This is the only pin that can see an in-place UPDATE, which a MAX(id)/COUNT(*) watermark pair structurally cannot -- a reprice, a fidelity flip or an edited merge_commit_sha inside an already-published window moves no id and no count. rows is the denominator that proves the digest was earned: an empty window yields a perfectly well-formed value, and only rows separates "this window genuinely holds nothing" from "this measured nothing", so the two are always published together.

  • ⚠️ The two digests do not cover the same window, for the same reason token_since exists. events_digest covers token_events over [token_since, until) -- the attribution band -- and outcomes_digest covers outcomes over [since, until). events_digest.rows therefore equals watermarks.window.token_event_count and outcomes_digest.rows equals outcome_count. Digesting both over [since, until) would leave a late-ingested band row outside the identity; digesting both over the band would make an outcome the report never read a false alarm.

  • 🔑 Both digests honour ?repo= (#747), and the scope is part of the hashed identity. A scoped manifest publishes digests covering only the rows that report read -- so another repository's ingestion cannot move them, and the two rows equalities above hold under a scope exactly as they do fleet-wide. Three consequences:

    • A scoped digest and a fleet-wide digest are different values even over identical rows; the predicate is hashed in so that a scope change reads as a change rather than as silent agreement. ⛔ Never compare one against the other.
    • Scoping is strict, matching a scoped /scores: rows carrying the reserved unqualified repository sentinel are excluded, and the under-count that causes is disclosed by /scores' data_quality block as repo_scope_excluded. ✅ That disclosure figure now has a pin of its own — the top-level repo_scope_excluded object below (#751). It is not covered by these digests and never will be: widening the predicate to reach the sentinel would over-attribute every repo-blind row in the fleet to whichever repository the caller named, which is exactly what #590 closed.
    • ?repo= is canonicalized (lowercased, .git and stray slashes stripped) before it reaches the digest, so ?repo=Acme/Tier.git and ?repo=acme/tier return the same value. manifest.repo echoes the canonical slug, never the caller's spelling.

  • digests_omitted (string, omitempty) -- present exactly when the two digests are absent, naming the reason. An undeclared absence would read as "this server publishes no digests", which is a different and false statement. One reason remains:

    • anonymized mode -- rows is an unfloored count of work over a caller-chosen window, the same quantity watermarks.window is withheld for (#593). kanon_suppressed.withheld_digests is true in this case.

    ⚠️ A second reason -- a repo-scoped manifest -- applied until #747, when the digest gained a repo predicate. The field is not removed: it is what separates "withheld, here is why" from "this server publishes none", and that distinction is independent of how many reasons exist.

  • repo_scope_excluded (object, omitempty) -- token_events, cost_micro, outcomes (#751). The repo-blind rows a strict ?repo= dropped: the pinned form of what /scores discloses under the same key in data_quality. 🔴 It exists because it is the one published figure the digests above structurally cannot cover. A scoped /scores still reads the unqualified sentinel rows in order to publish that disclosure, while a scoped digest excludes them by design and a scoped manifest carries no fleet-wide digest. Measured before this field: an in-place reprice of a repo-blind row moved repo_scope_excluded.cost_usd from 9 to 14 while the scoped digests and the scoped watermarks stayed byte-identical, and tierd verify-report printed REPRODUCED over changed served bytes.

    • Present on every scoped manifest, absent on every fleet-wide one. repo present ⟺ this object present. A fleet-wide report excluded nothing -- the sentinel rows sit inside its own digests -- so there is no such published figure to pin, and emitting an install-wide repo-blind cost for a request that named no scope would add disclosure rather than remove a gap.
    • ⚠️ It is emitted even when every count is zero, which deliberately differs from /scores, where the block is omitted on a clean window because there the absence is the signal to a human reader. Here it is a pin: an omit-when-clean pin is vacuous exactly when it matters most, because a window clean at publish time into which a sentinel row later lands would verify as NOT PINNED, and an absent check reading as a passing one is the defect the digests were added to close.
    • ⚠️ cost_micro, not cost_usd. /scores publishes dollars; the manifest pins the stored integer micro-dollars, because a pin is compared for equality and float equality over a JSON-round-tripped dollar figure can manufacture a divergence. cost_usd == cost_micro / 1_000_000.
    • ⚠️ token_events/cost_micro count the ATTRIBUTION BAND [token_since, until), while outcomes counts [since, until) -- the same asymmetry token_since exists for, because a scope can suppress a repo-blind row inside an outcome's 14-day look-back. A consumer recomputing over the narrower window compares two different populations.
    • It cannot appear in an anonymized mode: ?repo= is refused there, so a scoped manifest is always a developer-aggregation one.
    • What tierd verify-report prints -- four outcomes and a silent fifth: no line at all (fleet-wide, absent -- there is no pin to miss); NOT PINNED (scoped, absent -- a pre-#751 emitter or a hand-written file); NOT CHECKED (fleet-wide but present -- reported, never counted as agreement, because the value corresponds to no served number); UNCHANGED; and CHANGED, whose detail names which of the three moved. When token_since disagrees with the verifier's band, the token leg is not compared: NOT CHECKED, or CHANGED only if the outcome count moved. A run with such a withheld pin and nothing CHANGED exits 2, not 0. ⚠️ The presence rule above is an emitter rule -- the verifier tolerates a file that breaks it rather than refusing.

  • ⚠️ Cost, because this is a request path. The digests are two full-window scans. Measured (Apple M5 Max, 20,000 in-window token_events + 2,000 outcomes, 2026-08-29): the watermark read is 1.42--1.49 ms/op, the digests add 28.5--34.6 ms/op -- so this endpoint went from ~1.4 ms to ~30--36 ms, a ~20x increase scaling linearly with the window. That is affordable because a manifest is fetched once per published report. It is why the digests are on this endpoint and not on /scores, which already pays four full-window scans and is polled. ⚠️ #751 added a third read, and it was measured rather than assumed. The exclusion counts are two window aggregates whose repo = ? filter no index can serve here, so both touch the table for every in-window row. ⛔ Not because there is no repo index -- outcomes carries one with repo leading (idx_outcomes_push_daily_repo), unusable only because it is partial on source = 'push', which this query does not imply. The plans are pinned by a test rather than argued in prose. 🔑 Measured in ONE interleaved run (watermark, exclusion, digests per round), not appended to the two figures above -- which is why its watermark and digest legs read slightly differently from the #740 numbers, and why the ratios below are computed within that run rather than across the seam: watermark 1.44--1.78 ms/op, exclusion 2.98--4.56 ms/op, digests 28.7--36.5 ms/op (37--48% CPU idle across the rounds -- read as ceilings). That is two to three times the whole watermark read and +9.9% to +11.9% on the endpoint, and it is the same query a scoped /scores already runs for the same window.

  • kanon_suppressed (object, omitempty) -- withheld_window, withheld_digests, k_anonymity, aggregation, reason. Present only when a withhold happened. A manifest that went silently quiet would make "absent" and "this install has no rows" the same reading, which is the failure the /scores kanon_suppressed block exists to prevent. Both withheld_* flags are written explicitly rather than inferred from a missing key, so this object is a complete statement of what k-anonymity removed.

• Why five mutation ledgers and not one. outcomes.quality is mutated in place, so an as-of stamp keyed on token_events.id alone CANNOT bound a report -- an outcome's quality, a direct multiplier on every weighted point published, can change with no new row in either obvious sequence. The five append-only mutation ledgers are what make such a revision visible. Note also that token_events.id and outcomes.id are separate AUTOINCREMENT counters; neither bounds the other.
• The two windowed sequences are scoped to [since, until) and ?repo=; the five mutation ledgers are NOT. Their ts is the instant of the MUTATION, not of the row mutated, so a revision made today against a June outcome would be invisible to a June-windowed ledger read. Unwindowed is also the conservative direction: it can report a change that did not touch this window, never miss one that did.
• ⚠️ What equal manifests do and do not prove. They mean no input this structure watches has moved. They are not an attestation of byte-identical output. FIVE report inputs are uncovered, and the count is stated because an earlier draft said "two": period_membership and developer_alias are mutated in place with no transition log -- and a MAX(id)/COUNT(*) pair cannot see an in-place UPDATE at all, so covering them needs ledgers those tables do not have. actual_spend is not mutated in place: its rows are only inserted (InsertActualSpend), never updated, and removed only by erasure (EraseDeveloper); it is uncovered because nothing watches it. hierarchy_membership (#886), which selects team and division rows, is dated and append-only, so a write cannot move a window that ended before it, but it is not watermarked, so a window still open at the write can move unseen. An alias edit is dated the same way (#914). (developer_alias is the highest-leverage of them: it re-keys the entire cost-to-outcome join.) The fifth is Open()-time migrations, which rewrite token_events with no ledger row and are covered by the tool_version stamp rather than by a watermark. Read the manifest as "no row-level evidence I watch has changed", not as "this report is reproducible".
• Additive per the matrix above: a new endpoint is additive, not a compat break.

GET /api/v1/events

• Scope: read. Success: 200 OK. 403 in any anonymized (team/division) mode (#185, #270: raw per-developer rows are suppressed). Keyset-paginated bulk export of token_events.
• Query: ?since=, ?until=, ?limit= (rejected loudly above the store max), ?cursor= (opaque, echo the previous page's cursor).
• JSON (default): eventsExportResponse -- {next_cursor, events: [...]}. Each event: id, ts, developer, issue_id, model, input_tokens, output_tokens, cache_read_tokens, cache_write_5m_tokens, cache_write_1h_tokens, cost_micro, source, fidelity, idempotency_key, repo, session_id, price_version, host, billing_mode, billed_to, attribution_rule, pricing_basis, rate_snapshot, cache_write_evidence, issue_rule.
• CSV (Accept: text/csv): same fields in the append-only column order of eventsCSVHeader. Empty next_cursor (body and the X-Next-Cursor header) means the window is exhausted.
• CSV formula protection (#1095): all four bulk exports prefix a single quote (') to text cells beginning with =, +, -, @, tab or carriage return, following OWASP CSV-injection guidance. Numeric columns remain numeric (including negative values such as -1.5); JSON values are unchanged. Use JSON when the original text is required without the CSV safety prefix.
• issue_rule (#1296) is appended last in JSON and CSV, after all existing fields. NULL exports as legacy; a recorded extraction rule exports verbatim. legacy can include post-upgrade NULL rows: the singleton issue_rule_cutover records the UTC migration time and maximum outcome/event IDs at cutover (cutover details). The developer access export preserves the nullable stored value (JSON null for SQL NULL), including archived rows in outcome_exclusions.
• attribution_rule (#823) is an additive field appended after billed_to: the rule that assigned the row's issue_id. The values are branch, worktree-cwd, worktree-toolpath, carry, pr-number-at-insert or branch-at-merge (#1074: server-assigned, never client-sent; branch-at-merge is the merged PR's head-branch fill). A row with no rule recorded (every row stored before #823, and any row whose producer records none) exports as legacy, and any other stored value exports as unknown (exportAttributionRule). The DSAR export shows the stored value as stored: null where none was recorded, otherwise the stored text.

GET /api/v1/outcomes

• Scope: read. Success: 200 OK. 403 in any anonymized (team/division) mode (#185, #270). Same pagination/CSV contract as GET /events.
• JSON: outcomesExportResponse -- {next_cursor, outcomes: [...]}. Each outcome: id, ts, developer, issue_id, pr_number, weight, weight_source, quality, merge_commit_sha, additions, deletions, changed_files, source, work_type, work_type_source, repo, push_day, quality_status, issue_rule (Event 3 raw/projection fields, when enabled, precede issue_rule).
• CSV: the append-only outcomesCSVHeader order.
• issue_rule (#1296) is server-set from webhook/backfill extraction, appended last after every existing column, including conditional Event 3 fields. Explicit outcomes API issue IDs and pre-migration rows store NULL and export legacy; recorded rules export verbatim. The issue_rule_cutover ID boundaries above distinguish the pre-upgrade band from later NULL rows. Posting issue_rule to POST /api/v1/outcomes is rejected as an unknown field and stores nothing.
• quality_status (#1228) is appended after push_day in CSV; JSON omits it when empty. unknown means the outcome has an unresolved or unrecognized quality check. Empty does not establish observed quality. This diagnostic field does not change the numeric quality multiplier.
• push_day (#242) is the UTC calendar day a source='push' outcome aggregates to (part of the (repo, issue_id, push_day) dedup key), and "" for a PR outcome (NULL column), matching merge_commit_sha.

GET /api/v1/quality_events

• Scope: read. Success: 200 OK. 403 in any anonymized (team/division) mode (#185, #270: rows carry a per-developer developer column). Keyset-paginated bulk export of the append-only quality_events signal log (#242). Same ?since/?until/ ?limit/?cursor query, pagination, and content-negotiation contract as GET /events.
• JSON (default): qualityEventsExportResponse -- {next_cursor, quality_events: [...]}. Each row: id, outcome_id, developer, issue_id, event_type, source_ref, event_ts, recorded_at, reason, status, evidence, trigger_event.
• ⚠️ source_ref's value shape for CI rows changed in #687 (BREAKING) -- head_sha:run_attempt:workflow_id, was head_sha:run_attempt. Same column, different bytes; see the changelog entry. The identical change applies to source_ref on GET /api/v1/quality_history, which carries the CI ref through UpdateQualityForOutcome.
• CSV (Accept: text/csv): the append-only qualityEventsCSVHeader order; reason, status, and evidence (#1228) follow the original eight columns; trigger_event (#1230) is appended after evidence.
• revert_ambiguous records a checked but unresolved revert against each qualified candidate, with reason="ambiguous", status="unknown", and evidence=false. It neither changes numeric quality nor adds quality history. source_ref is the revert SHA; distinct SHAs, rather than candidate rows or delivery counts, count unresolved reverts. Resolved revert event types have status="observed" and evidence=true; unrecognized types fail closed as unknown/false. reason is empty on earlier rows.
• trigger_event (#1230) is the normalized CI workflow trigger: push, schedule, workflow_dispatch, merge_group, pull_request, pull_request_target, release, workflow_run, repository_dispatch, or other. Missing or unsupported new triggers are other. Legacy CI rows with unknown provenance and non-CI rows have JSON null and an empty CSV cell. Only CI rows with trigger_event="push" have status="observed" and evidence=true. Legacy CI rows with NULL provenance have status="CI trigger unknown" and evidence=false; known non-push CI rows have status="unknown" and evidence=false. These diagnostics do not themselves change the stored numeric quality.

GET /api/v1/quality_history

• Scope: read. Success: 200 OK. 403 in any anonymized (team/division) mode (#185, #270). Keyset-paginated bulk export of the append-only quality_history transition log (#242). Same pagination/CSV contract as GET /events.
• JSON: qualityHistoryExportResponse -- {next_cursor, quality_history: [...]}. Each row: id, outcome_id, developer, issue_id, old_quality, new_quality, reason, source_ref, ts.
• CSV: the append-only qualityHistoryCSVHeader order.
• Together the two quality exports make an outcome's multiplier re-derivable (quality == last new_quality) from a BI export, not just the erasure-scoped DSAR export.
• 🔴 source_ref's VALUE SHAPE changed for CI rows (#687) — BREAKING. The column set is unchanged, but "Change an existing CSV column's value shape" is Breaking on its own, and this is that. CI events are now head_sha:run_attempt:workflow_id; they were head_sha:run_attempt. Reverts are still the bare revert commit SHA. A consumer that splits and reads parts[0]/parts[1] is unaffected; one that asserts len(parts) == 2, or that treats a third component as impossible, breaks. See the changelog entry for the full rule, including what happens to rows written before #687.

GET /api/v1/fidelity

• Scope: read (satisfied by EITHER the viewer token or the write token). Success: 200 OK, fidelityResponse. 403 in any anonymized (team/division) mode (#185, #270, same posture as GET /events/GET /outcomes): the body names individual developers, which the anonymized modes suppress, and it cannot be k-anonymized while staying a per-developer capture report -- the 403 is returned before the store is touched.
• Per-canonical-developer capture-fidelity signals (#236): the rollout view for "which developers are (not) capturing, and at what quality." Raw token_events developer keys are canonicalized through developer_alias (#125) and merged, so a developer mid-rename is one row, not two. Takes no query parameters; the windows are fixed at 7d and 30d.
• Top-level fields (fidelityResponse):
  • now, since_7d, since_30d (strings) -- RFC3339 UTC stamps of the exact window bounds the counts below are measured over, so a reader never has to assume a server-local clock for what "7d"/"30d" meant for this response.
  • developers (array of developerFidelityJSON) -- one row per canonical developer, sorted by developer. An empty array [] on an empty DB (never null).
• developerFidelityJSON:
  • developer (string) -- canonical developer identifier.
  • event_count_7d, event_count_30d (integers) -- token_events counts over the 7d and 30d windows.
  • last_event_by_source (object, {source: RFC3339-UTC-string}) -- the most recent event timestamp per capture source over all history (not just the 30d window): the "is this source still delivering" signal. Always present (an empty object {} when the developer has no events), so a client can index it without a nil check; a source absent from the map has never delivered.
  • fidelity_levels (object, {level: 30d-count}) -- the 30d event count per fidelity level (realtime/daily/estimated). Always present ({} when empty); a developer with no realtime count is on a degraded capture path. Keys are the same fidelity closed set as elsewhere in this contract.
  • unknown_model_cost_share (number, 0..1) -- the fraction of the developer's 30d stored spend whose (host, model) has no exact entry in the current table (#267). 0 when 30d spend is zero. This existing read-time lookup does not establish whether the original dollars were guessed.
  • unknown_pricing_token_share (number, 0..1, always present; #1228) -- share of tokens with an unknown pricing basis or without an exact entry in the current price table. Computed at read time over the same 30d window: sum input, output, cache read, 5m cache write and 1h cache write tokens on qualifying rows, divided by those five classes on all rows. Zero-cost rows with tokens count; zero-token rows do not. Returns 0 with no 30d tokens. A row qualifies when its price_version is different from the active table version, its host-aware model lookup has no exact current entry, or its stored pricing_basis is missing, unrecognized, guessed, unavailable, or an aggregate approximation (including historical aggregates). token_derived and caller_authoritative are known bases; both still need the active version and an exact current table entry to avoid qualifying. Other versions (including the legacy 0 sentinel and higher override versions after a rollback) count as basis-unknown even when the model is listed exactly today; the registry retains identity, not historical rates. Alias merging sums token counts before dividing.
  • unknown_pricing_token_share_label (string, always present; #1228) -- exactly "share of tokens with an unknown pricing basis or without an exact entry in the current price table" (R-2026-10-14-17, D-32 C″).
  • cost_label (string, optional; #1228) -- "estimated cost" iff unknown_pricing_token_share > 0; omitted otherwise. On /fidelity this label refers only to the token-share test; the response has no dollar field for it to qualify. A guessed-cost row with zero tokens does not contribute to the share and therefore does not trigger this label.
• #1228 is an additive read-only diagnostic with the same mode/auth gating, no migration and no automatic repricing. An explicit audited tierd reprice updates the price basis, so an exact row can clear on the next read. Exact configured self-hosted estimates remain exact table entries; this share does not certify provider list rates, bound dollar error or establish capture completeness. It adds no headline-withholding threshold or /scores field. Local tierd score prints the same label and a token-weighted percentage for its Claude Code JSONL window, qualifying each affected developer/issue cost and total as estimated cost. It freshly prices the logs under the active table on every run, so it has no stored legacy price-version basis.
• Additive per the matrix above: a new endpoint is additive, not a compat break. It was added in #320 (behind #236), after this contract doc (#241) was written, hence the catalog backfill (#322).

GET /metrics

• Scope: metrics (#944). In team and division mode the read-only viewer token is rejected 403 with a body naming --metrics-token; with no metrics token configured, only the write token scrapes. Operator-only: security.md § The metrics token. Mounted at the root (/metrics, not /api/v1), and only when a metrics registry is wired (cmd/tierd); absent otherwise.
• Success: 200 OK, Prometheus text exposition (text/plain; version=0.0.4). Not a JSON contract; the additive-only rule applies at the level of metric/label names.

Open endpoints (probes)

GET /api/v1/version

Build identity of the running process (#638). Open (no token) and mounted in read-only mode, because the deployment hardest to identify by other means is the public demo, and the demo runs read-only.

{version: <string>, commit: <string, omitempty>, modified: <bool, omitempty>, go_version: <string, omitempty>, platform: <string>, price_table: {...}}

• commit is the build revision: ldflags-injected where available, otherwise the Go toolchain's vcs.revision stamp. Absent when neither exists.
• modified is a tri-state: absent means the binary carries no VCS stamps (the shipped container is built with .git excluded, so this is its normal state); false means stamped and clean. Absent does NOT mean clean.
• price_table here is {version, effective_date} and is provenance for the figures, not build identity — its version bumps only when prices change, so it can agree across a full release gap. It deliberately carries no content digests on this unauthenticated endpoint; read those from /scores or a report manifest instead. See content identity.

GET /api/v1/health

• Scope: open. Success: 200 OK, {"status": "ok"}.

GET /api/v1/healthz

• Scope: open. Readiness probe (#49). 200 when every subsystem is healthy, 503 when any subsystem is restarting/stopped; same JSON body in either case. As of #48 the body is extensible: {"watcher": <health.WatcherSnapshot>, "subsystems": {"<name>": {"healthy": <bool>, "detail": <object, omitempty>}}, "healthy": <bool>}.
  • subsystems is a map keyed by subsystem name (watcher, and future collectors). Each value is {healthy, detail} where detail is that subsystem's payload (for watcher, a WatcherSnapshot). New collectors append a key here — no consumer needs new per-subsystem code.
  • healthy (top level) is the aggregate: true iff every subsystem is healthy. It mirrors the 200/503 status code.
  • watcher (top level) is retained for backward compatibility and duplicates subsystems.watcher.detail; it is deprecated in favour of the subsystems map. Public watcher fields: status, last_error (omitempty), last_event_ts (omitempty), started_at (omitempty), next_retry_at (omitempty), restart_count, watch_add_failures, last_watch_add_error (omitempty). Nonempty errors are classes: last_error is watch_failed and last_watch_add_error is watch_add_failed. Full errors remain in logs. This route is outside auth, so the same redaction applies even when a valid viewer or admin token is supplied.
  • Do NOT wire a k8s liveness probe here.

GET /api/v1/livez

• Scope: open. Liveness probe (#49); always 200. Body livezResponse: {status: "alive", uptime_s: <int>, version: <string>, commit: <string, omitempty>}. commit was added additively by #638; it is absent on a binary carrying no build identity. version is the documented feature-detection signal.

Event 3 corrective scoring contract (#1235)

Event 3 is off by default. The API's WithScoringPolicy option accepts the scoring policy contract; its zero value selects legacy scoring. An enabled policy requires resolved state and event3-v2. These interfaces do not enable scoring; see Enable Event 3 scoring for operator configuration. Existing flag-off score bodies and values retain their legacy meaning.

Scores, detail, segments and comparison

Enabled /scores, developer detail and /scores/compare responses disclose correction_policy: {scoring_policy: "event3", correction_rule_version: "event3-v2", rubric_version: 2}. Legacy uses rubric 1. This stamp comes from scoring.ScoringPolicy.Stamp; readers must not infer policy from a size or quality value. Flag-off score responses retain their previous representation. Unknown or unresolved enabled policy refuses computation.

When enabled, developer score rows gain outcome_n, the raw outcome count used for activity and coverage. sample_n becomes the number of eligible growth observations used for ranking floors. A pure repair can receive allocated points while adding zero samples. Cross-author declarations awaiting confirmation use growth eligibility without moving either participant's contribution. Unknown growth remains explicitly unknown. Counts follow the same projection through rollups and folding; team/division responses continue to withhold unfloored counts and identifying relation evidence.

Headline, developer detail, work-type segments and comparison consume persisted whole-chain projections before partitioning by repository, window, work type, developer or historical team. Costs stay with the original cost records. Detail issues expose an enabled-policy projection object with the fields described below. Bootstrap resamples only eligible growth observations; excluded repairs' points and their cost shares are fixed terms. Pooled issue cost is split across raw outcomes before partitioning and counted once. tierd score remains the local cost-attribution command.

Raw evidence and subject access

POST /api/v1/outcomes preserves omitted/null diff stats separately from genuine zero stats; ordinary outcome fallback weight is unchanged. Corrects: references never invent issue attribution. The existing numeric outcome response/export columns remain compatible; nullable evidence fields disclose availability.

GET /api/v1/developer/{id}/export adds correction_declarations, corrective_relations, correction_audit, correction_assessments and correction_allocations arrays. Endpoint matching includes either party, aliases and reviewer evidence across the connected chain. DELETE /api/v1/developer/{id} adds corresponding keys under deleted, counting rows changed. Assessment and allocation counts measure rows scrubbed/frozen; subject declarations are deleted after connected text and links are scrubbed. Erasure removes endpoint identities, comparison SHAs and subject-bearing text before deleting outcomes, severs identifying indirect links, and retains numeric allocations. Any erased party freezes the allocation; the survivor's numbers are never redistributed. The reviewed-allocation schema upgrade ensures eraser compatibility; corrective evidence pins add no schema version.

Existing-outcome revert exclusion CLI (#1277)

tierd outcomes exclude-reverts [--dry-run] [--db PATH] [--repo owner/name] [--since DATE] [--out FILE] produces a deterministic version-1 JSON plan; --dry-run is the default. It opens the existing database read-only and refuses a schema mismatch. Candidates have repo, pr, outcome_id, merge_sha, evidence_source, head_ref, title, verdict (exclude|keep|unknown) and reason. Counts include total, exclude, keep, unknown. Approval uses lowercase SHA-256 hex of the raw plan file bytes (shasum -a 256 plan.json); the dry run prints this digest to stderr, outside the JSON plan. The plan has no embedded digest. Top-level fields in order are version, repo, since, candidates, counts; candidates sort by stored repository, PR, outcome id. The source is payload or api (including unavailable API fallback for missing stored identity). A supplied evidence merge SHA must match the stored SHA; API evidence must supply it. For a matching SHA, usable action=closed, merged=true payloads take precedence over later edits, then the newest usable payload without a SHA, then API fallback. API fallback uses the current title. Only API 404 becomes unknown; authentication/permission errors, exhausted retries and interruption abort without writing a plan. Incomplete evidence or a mismatched API merge identity remains unknown. Raw branch hashes and issue attribution never establish a revert.

tierd outcomes exclude-reverts --apply PLANFILE --actor OPERATOR --approved-digest SHA256 [--db PATH] requires recorded operator sign-off on that exact dry-run plan. Operators must review and approve each install's plan and must not run apply unattended. Actor/approval are self-asserted, not authentication. Apply requires the file to be byte-identical to the dry-run encoder's canonical re-encoding of the decoded plan (two-space indentation and a final newline); duplicate/case-variant keys, reformatted whitespace and unknown JSON fields are refused. It checks the raw-bytes approval digest, version and counts, and each row's evidence for self-consistency against the shared classifier, including consistency between reason and verdict. payload rows are re-verified against retained payloads before any exclusions are applied; missing or changed retained evidence requires a fresh dry run and approval. Apply accepts no filters or API/output flags and makes no API requests. Each exclude row is verified and moved through the existing exclusion mechanism atomically under its write lock. Earlier rows remain committed if a later row is stale or erased. Matching replay is a no-op. The existing audit row holds actor, time, approved raw plan digest and candidate evidence; no new schema or unique key is introduced. Exit status is 0 on success, 1 on invalid input or apply failure; success JSON contains plan_digest, applied, replayed, skipped and actor_identity. Sealed report bytes are unchanged. Historical unsealed manifests can mismatch after current outcomes are excluded. See the operator procedure.

Operator lifecycle

tierd corrections list|show|confirm|dispute|withdraw|settle --db PATH operates on local recorded evidence. Mutations use --relation ID --revision N --actor LOGIN --role ROLE; actor/role are self-asserted local input, not authentication. This installation's confirmer and settler is the operator. Confirmation requires an actor different from the declarer and reviewed sizing: --reviewed-original, --reviewed-own, --reviewed-before, --reviewed-after (or explicit --pure-repair), --scope, --rationale, --reviewer, --reviewed-at. Comparison identities use --comparison-base, --comparison-before, --comparison-after. Review time is RFC3339; weights are exact rational values.

Disputes and withdrawals require --reason. A dispute or withdrawal after confirmation retains the last allocation until operator settlement with --settlement uphold|re-assess|remove; re-assessment requires a reviewed sizing record. Revision checks reject stale decisions; replay of an identical audited action is idempotent. Confirmation never enables scoring. Distinct-root relations remain pending under D2; launch scoring makes no multi-root claim.

Outcome and evidence exports

GET /api/v1/outcomes retains the meaning and types of existing weight, quality, additions, deletions, changed_files and all existing CSV positions. JSON adds nullable raw_additions, raw_deletions, raw_changed_files and diff_stats_available. SQL NULL differs from a genuine numeric zero; pre-cutover API all-zero stats remain unavailable evidence. A persisted projection adds raw_weight, reviewed_own_weight, marginal_credit, credited_weight, projected_quality, allocated_points, ranking_eligibility, status, pending_reason, rule_version, provisional, disputed, frozen. Sizing/share/marginal fields retain exact rational strings. Quality and allocated points are numeric. allocated_points is final participant credit, consumed once; never reconstruct it by dividing and multiplying by quality. D1 preserves each follow-up's own quality. Frozen allocations survive endpoint erasure without redistribution.

The CSV prefix through push_day is unchanged. Append this tail in order:

raw_additions,raw_deletions,raw_changed_files,diff_stats_available,reviewed_own_weight,marginal_credit,credited_weight,projected_quality,allocated_points,ranking_eligibility,correction_status,correction_pending_reason,correction_rule_version,correction_provisional,correction_disputed,correction_frozen

GET /api/v1/corrections/{kind} adds read-scoped exports for relations, audit, assessments and allocations. Each supports the bulk export pagination, since/until, opaque cursor and Accept: text/csv contract, and returns {next_cursor, <kind>: [...]} in JSON. These exports window by recording time, while the manifest digest windows by endpoint dependency. Nullable endpoints and text reflect erasure; a missing endpoint is never a new identity. Free text passes through CSV formula protection. Team/division modes return 403 before any evidence query; identifying evidence is not_shown.

Digest and manifest verification

New digests use tierdig2: plus 64 hex characters. This is an explicit scheme change, including new domain frames for token events. Token frames retain 17 fields. Outcome frames increase from 11 to 16: the original 11, then nullable additions, deletions, changed files, merge occurrence, and the legacy stats availability bit. Nullable fields use n for NULL or v plus stored text; timestamps use raw stored bytes. No receipt-time fallback substitutes for merge occurrence evidence. Framing is an eight-byte big-endian byte length followed by UTF-8 payload, with fixed arity per row. Floats retain the exact canonical hexadecimal representation with negative zero normalized.

events_digest.rows still counts token rows in [token_since, until); outcomes_digest.rows still counts outcome rows in [since, until), under the same repository scope. Neither population changes. The additive corrections_digest is separately domain-separated and has {value, counts}; counts contains declarations, relations, audit, assessments, allocations, dependency_outcomes. Its graph starts with window outcomes and endpoint merge occurrence evidence, then closes over connected declarations, relations, audit, assessments, allocation chain versions and outcome evidence. It includes ancestors/children outside the window and dispositions recorded later. Independent repositories remain outside the selected dependency graph. Each table has its own domain and explicit ordered column list; NULL, integer, float and text have distinct frame tags. Erasure removes identifiers from the stored inputs; surviving frozen numeric allocations remain digestible.

tiermanifest1 is retained because all manifest changes are additive:

• scoring_policy, correction_rule_version, rubric_version pin the same scoring rule stamp. rubric.version agrees: legacy/legacy-v1/1 or event3/event3-v2/2.
• outcome_counts: {outcome_n, sample_n} pins raw and eligible counts separately.
• corrections_digest pins corrective evidence even while scoring is disabled.
• watermarks.ledgers.max_correction_audit_id, correction_audit_count and correction_projection_revision pin install-wide audit and projection state. They can move without a change in this window; the scoped digest identifies whether this window's evidence changed.

Watermarks, counts, raw outcome inputs and all digests use one read snapshot. TIER resolves the stored scoring policy in that same snapshot for each request; the policy stamp and eligible counts cannot use stale startup policy options. Manifest policy provenance uses only the top-level evidence fields above, and the projection revision uses only watermarks.ledgers.correction_projection_revision. The nested correction_policy receipt remains part of enabled score responses. Team/division manifests withhold outcome_counts and all three digests along with watermarks.window, declaring the withhold in kanon_suppressed and digests_omitted. TIER also withholds correction_projection_revision in these modes. Policy stamps and the remaining install-wide ledgers stay visible.

tierd verify-report recognizes rubrics 1 and 2 under their own pinned policies and passes that policy to the scoring handler for replay. A manifest without Event 3 fields uses legacy-v1; a rubric-2 manifest requires explicit policy pins. Unknown policies/rules, contradictory policy/rubric pins, unknown digest schemes and equal hashes with contradictory row counts are uncheckable (exit 2), never agreement. Other rubric versions report CHANGED under R-2026-10-14-20; the two rubric pins must still agree. An actual changed input gives exit 1. Old tierdig1 pins are recomputed with their original domains, 17/11 frames, column projections and scope, so an unchanged archived report verifies cleanly; values from different schemes are never compared as tampering. No scoring flag is enabled by verification. The current stored correction policy and install-wide corrective counters are informational; a live policy change cannot override the pinned replay policy or refute an unchanged report. The verifier checks the replayed score body's nested correction_policy receipt independently of the requested manifest policy. Sealed reports likewise recompute with their recorded policy, rule and rubric.

API changelog

• #1425 — personal-key custody (operator ruling E, 6a). Add-person now returns a claim code instead of a personal key. Direct personal issue and reissue through /org/keys are refused; personal revoke is root only. Adds claim redemption, claim issue/recovery, holder rotation, leave cancellation, audit/notices and device creator attribution. Claim codes are hash-only, single-use and expire after 72 hours. DSAR adds org_claims and viewer_notices arrays when present, excluding code hashes; legacy route access and existing empty shapes stay fixed.

• #1368 / #1375 -- sealed team/division levers (ADDITIVE fields, v0.6.3). GET /api/v1/scores?period=YYYY-MM adds the optional numeric fraction in [0,1] teams[].cache_read_share (cache reads / all input-side tokens). Every published group, including folded other, first needs k counted seats with both captured spend and merged work; failure withholds all groups' levers. The cache partition needs k contributors with cache reads and k without them, counting distinct cost contributors with positive input-side tokens (input + cache read + cache write), including bots and spend-only people. Zero-input contributors count on neither side; mixed cached and uncached input puts a contributor on the cache-read side. k is clamped to at least 3. Optional data_quality.team_levers_withheld is true when levers are withheld; data_quality.team_levers_withheld_reason is one of group_seats_below_k or category_seats_below_k. Withheld share keys are absent, never zero or null. Live windows, anonymized /scores/compare and org totals carry no levers. Previously sealed bodies remain immutable; pre-lever bodies are verified/recomputed without adding these fields or their notice.

• #1230 / #1302 -- CI trigger provenance (ADDITIVE field; BEHAVIOURAL evidence/status change). GET /api/v1/quality_events adds nullable JSON trigger_event and appends the CSV column after evidence. CI evidence is now push-only: legacy NULL CI rows return the new status CI trigger unknown with evidence=false; known non-push CI rows return unknown/false. Push CI and resolved revert rows remain observed/true. Numeric quality is a separate stored value.

• #972 / #1279 -- GET /api/v1/diagnostics/captured-dollars (ADDITIVE). New public v1 read endpoint with the same stability promise as the other v1 reads. Read scope, developer mode only (403 in team/division modes), with the same since / until / before / repo bounds as /scores. Live diagnostic evidence is separate from reproducible scores; no released /scores field is removed or changed.

Newest first. Every entry names the change, its classification, and the issue. Backfilled entries (#185, #187, #191, and the additive-column history) predate this discipline and are recorded here so the record is complete.

• #1235 -- Event 3 scoring contract (ADDITIVE fields/option/CLI/routes; POLICY-GATED semantic change). The contract adds WithScoringPolicy, outcome_n and the policy/rule/rubric stamp, plus assessment/allocation DSAR arrays and endpoint-aware scrub counts. It also adds audited corrective commands, enabled-policy SampleN and shared projected readers/bootstrap, detail projections, append-only outcome CSV fields and read-scoped corrective evidence exports. Flag-off scores keep legacy bytes. See the Event 3 contract for field names, actor limitations, count populations and anonymized suppression. Production enablement remains off by default and requires operator configuration.

• #1235 -- Event 3 evidence pins (DIGEST SCHEME CHANGE; ADDITIVE manifest). tierdig2 adds nullable stats, merge occurrence and availability to outcome frames (11 → 16), and a domain-separated corrective digest with typed counts over full connected dependencies. Existing digest row populations stay intact. tiermanifest1 adds policy/rule/rubric, raw/eligible counts and corrective audit/revision pins in one snapshot. The verifier replays the pinned policy, verifies tierdig1 with its old definition, and refuses unknown schemes rather than calling a scheme transition tampering. The digest and verifier changes ship together; no schema bump or production flag enablement.

• #1228 -- unresolved revert diagnostics (ADDITIVE export fields/type). GET /api/v1/quality_events adds reason, status, and evidence to JSON and appends them to CSV. revert_ambiguous is an unresolved check, never penalty or quality evidence. GET /api/v1/outcomes adds optional JSON quality_status and appends the CSV column; unknown is diagnostic and leaves numeric quality unchanged. See the endpoint schemas above.

• #1228 -- unknown-pricing token share on /fidelity (ADDITIVE response fields). GET /api/v1/fidelity adds per-developer unknown_pricing_token_share and unknown_pricing_token_share_label, both always present, plus optional cost_label ("estimated cost" iff unknown_pricing_token_share > 0). The share measures tokens with an unknown pricing basis or without an exact entry in the current price table over the 30d window; it is 0 with no 30d tokens.

• #1074 -- PR attribution at insert (ADDITIVE request fields/rule value). POST /api/v1/events accepts optional pr_number and branch_hash fields. At insert, an unattributed event in a real repository and an unsealed month resolves through exactly one real-issue outcome on (repo, pr_number) and records pr-number-at-insert, a server-assigned rule never client-sent.

• #1144 -- scoped ingestion (ADDITIVE auth/response; BREAKING collision behaviour). POST /api/v1/events also accepts the new ingest scope alongside write/admin. Its receipt gains the additive rejected_cross_developer count. Cross-developer idempotency-key collisions no longer merge token counts: they are rejected and counted in rejected_cross_developer.

• #1095 -- S03-3 requires an explicit paid amount (BREAKING request behaviour). POST /api/v1/actual_spend and POST /api/v1/org_actual_spend now return 400 when actual_paid_usd is omitted or null, instead of returning 201 and storing a $0 row. Clients must supply actual_paid_usd; an explicit 0 remains valid and returns 201.

• #1082 -- token-event cost ceiling (BREAKING request behaviour; ADDITIVE schema/metric). POST /api/v1/costs imports with cost_usd > $10,000 or any token field > 1e12 now return 400 instead of 2xx; split the import across rows. An identical keyed replay of a legacy over-ceiling cost remains an idempotent 201. POST /api/v1/events remains 2xx: over-ceiling events are stored with cost clamped to $10,000 and marked. New nullable token_events.cost_clamped records the mark, and tier_token_event_cost_clamps_total counts clamp attempts.

• #1095 -- healthz watcher errors are classes (BREAKING value change). Explicit exception to rule 3: raw error text exposed filesystem paths to unauthenticated callers. Keeping that text under the old fields while adding new fields, or waiting for /v2, would preserve the security exposure. Therefore last_error and last_watch_add_error keep their field names for compatibility, but their values become error classes in place; no new fields are added. This exception is limited to these two fields on /healthz. In both watcher and subsystems.watcher.detail, nonempty last_error is now watch_failed and nonempty last_watch_add_error is now watch_add_failed, replacing raw error text. Empty errors remain omitted. Full errors remain in logs; consumers parsing error text must use the classes instead. This applies to every caller, including authenticated callers. last_event_ts, started_at, and next_retry_at retain their existing values and omission rules.

• #1095 -- CSV formula-leading text is neutralised (BREAKING CSV value shape; security fix). The four bulk exports now prefix a single quote to text cells starting with =, +, -, @, tab or carriage return. Numeric columns, JSON output and CSV column order are unchanged.

• #1042 -- write bodies must end after exactly one JSON value (BREAKING request-side behaviour; no field changes). Every write endpoint that decodes a JSON body now refuses anything after its one value except whitespace: a second value, trailing garbage, or a stray ] or } is a 400 with the existing "request must contain exactly one JSON object" (or "array") message. Before, a stray ] or } ({...}]garbage, {...}}) was accepted and stored with a 2xx. A body whose value fits the size cap but whose trailing bytes do not is now a 400; on /events, /outcomes and the bulk /org_hierarchy import it carries the same "request body exceeds N bytes" message as an oversized value. Breaking: a client that sent such a body goes from 2xx to 400. Well-formed clients (the shipper, tierd hierarchy import, curl with one JSON value) are unaffected.

• #913 -- sealing waits for every configured source (ADDITIVE; schema version 6). A new stall_reason code, source_behind: the first owed month is held because a source tierd serve pulls from has not settled past its end. Serve records each source it starts in source_watermark and retires the rest; a source's successful pass advances its settled-through time only over coverage with no gap. A source certifies only data it recorded: a pass that skipped in-scope spend a later pass re-reads settles nothing, and spend it can never re-read (a damaged or failing log its cursor moved past, a skipped row, an excluded subagent call, a deleted log holding a call) is stored as lost, so every month the lost span touches stays held until tierd seal --skip. The 404 for a held month names each source and its settled-through time, the gap it cannot fetch, or the span it lost. sealable_at and next_seal_at keep their meaning: a held month reads as awaiting its seal, never as not sealable. Until serve has registered its sources on the database, every month is held. A month before a source's first recorded coverage never seals automatically; its 404 says so and names the remedy (arm a later month, or set active_since for subscription fees). tierd seal --arm refuses such a month; tierd seal --skip records it as a gap with category source_behind, once confirmed. The session watcher, webhooks, tierd ship and /costs pushes are covered by --report-grace only. The database moves to schema version 6, one-way: a version-5 tierd refuses it.

• #913 -- tierd serve seals and serves monthly reports (BREAKING in team/division mode). The sealed reads described below are now served. In team and division mode, /scores, /report_manifest and /scores/compare answer only from sealed calendar months. A request that was a live window (since/until/before, ?team=, ?work_type=, ?repo=, or the _a/_b bounds) is now a 400. Until the operator arms sealing (tierd seal --arm YYYY-MM|earliest, or seal_from), every read is a 404 beginning sealing not armed. A writable serve runs a seal pass at startup and then every hour; each pass seals every owed month whose grace lag (--report-grace, default 14 days) has ended, oldest first. A --read-only serve never seals: it serves the months a writable server sealed in the same database, and names a month that is overdue. Every team/division tierd serve builds its sealer; an anonymised server without one would answer the three reads with a 503 whose error says it has no sealer, never a live body. At startup serve logs report_grace, and it WARNs when the current aggregation, k or fold rule differs from the config the newest sealed month was sealed under, naming the first month the current config applies from. tierd verify-report still replays a live-window manifest over its window. Developer mode is unchanged. One-way: a sealed month is never recomputed after its seal, and the first seal pins the earliest month for good. The database is already at schema version 5, so an older tierd refuses it.

• #913 -- a sealed read names a stalled month (ADDITIVE to the sealed reads below). While sealing is stalled, the sealed manifest and every sealed 404 (including /scores/compare's) carry stalled_period (YYYY-MM), stall_reason and owed_since (the month's sealable_at), and the manifest's next_seal_at and the Tier-Next-Seal-At header are absent. Sealing is stalled at the first month owed after the newest sealed or gapped month when the last seal pass failed there, or, while no seal pass is running, when it is more than two seal passes past its sealable_at, so a restarted or read-only server still names it. stall_reason is a failure category code, never an error's text. The codes are sealFailures, sealFailureStorage, sealFailureInternal and sealUnreported in internal/api/seal.go: write_lock_busy, erase_raced, clock_behind, refold_mismatch, floor_moved, not_next, overlap, gapped, not_sealable, cancelled, storage, internal, and unreported, which means no seal pass has reported on the month while none is running, so check that tierd serve is running and not read-only. A code is never reassigned, and a later release may add codes, so treat an unknown code as an unnamed failure. All three fields are absent while nothing is stalled, and none appears on /healthz, /livez or /health. tierd doctor --server reads them from /report_manifest and reports a stalled month as a WARN, with the tierd seal --skip command only for a stalled_period that is exactly YYYY-MM. tierd seal --status --aggregation team --db ~/.tier/tier.db --server http://127.0.0.1:8080 prints the sealing state from the database, opened read-only, and asks --server for the reason; use the same flags, config file and environment as serve. tierd seal --help lists its exit codes.

• #913 -- permanent seal gaps (ADDITIVE; schema version 5). No endpoint changes yet. The database gains sealed_gap, an append-only record of a month the operator marks as never to be sealed, so the months after it seal. The database moves to schema version 5, one-way: a version-4 tierd refuses it.

• #913 -- sealed monthly reads (BREAKING in team/division mode; served from the tierd serve entry above). In team/division mode /scores and /report_manifest answer one sealed calendar month: ?period=YYYY-MM, or none for the latest sealed month (a grace raised later never hides a month already sealed). /scores returns the stored body byte for byte, so its sha256 equals the manifest's body_digest; the month and its markers ride in response headers, not a wrapper: Tier-Period, Tier-Sealed-At, Tier-Next-Seal-At, Tier-Earliest-Period and Tier-Latest-Period (the last three equal the manifest's next_seal_at, earliest_period and latest_period). The manifest (manifest_schema: tiersealedmanifest1) carries period, period_start, period_end, sealed_at, next_seal_at, earliest_period, latest_period, config (aggregation, period_size, k, fold_rule, digest), body_digest, tool_version, commit, and config_gap when the current config differs. A GET never writes: once the operator arms sealing, a background pass seals each month after its grace lag, permanently, oldest first, and a month it fails to seal holds back every later one. A sealed body always carries data_quality.attribution_coverage: "not_shown" and never cost_coverage_safe_since. A sealable month with no data is a 200 with the same top-level and data_quality keys as a k-suppressed month, except kanon_suppressed and attributed_outcome_share, which an empty month never carries, and the conditional quality signals (such as unjoined_developers or zero_token_outcome_count), which appear only when their condition holds, so a k-suppressed month can carry ones an empty month lacks. A month not sealed is a 404 with period, aggregation and error: while sealing is not armed, error begins sealing not armed; for a month sealable but not yet sealed it begins month is sealable but not yet sealed and, while the background pass is failing at that month or an earlier one, names that month and why; otherwise it says why the month is not sealable, and sealable_at is present when the month will become sealable. With nothing sealed yet, the default read's 404 names the latest sealable month, or the earliest when that is later. since/until/before, team, work_type and repo are 400s, and any other parameter is an unknown-parameter 400 listing period alone. Sealing is armed by the operator setting seal_from, a month; until then nothing is sealed. The earliest sealable month is the later of seal_from and the first full month after the cost horizon (a month starting exactly at the horizon counts as full), pinned by the first seal: older data imported after the first seal never appears in anonymised modes. /scores/compare compares two sealed months: ?period_a=YYYY-MM&period_b=YYYY-MM with period_a earlier, or neither for the two latest sealed months: the month the default /scores read serves and the month before it or, while that month is inside a raised grace lag, the latest sealed month before it. The rows are refolded at the months' sealed k from their stored fold inputs, never from a live window or from the two stored bodies, so a team is named only if it clears k in both months, and each month's own residual must reach k or the whole comparison is withheld. The body keeps the live shape; mode is the level both months were sealed under, each window's since/until are the month's bounds and its data_quality carries the live compare window's fields from the stored body, except cost_coverage_safe_since, which a sealed body omits; the two sides of total are the stored bodies' totals (a zero side for a month with no rows), so they equal /scores?period=; and price_table is the active table, as on the live read. The months ride in headers: Tier-Period-A, Tier-Period-B, Tier-Sealed-At-A, Tier-Sealed-At-B, plus Tier-Next-Seal-At, Tier-Earliest-Period and Tier-Latest-Period. A reversed or equal pair, one period alone, and any since/until/before/_a/_b bound are 400s naming ?period_a= and ?period_b=. A month not sealed is a 404 naming it, with the error and sealable_at of /scores?period= for that month; with neither period given, fewer than two sealed months is such a 404. Two months sealed under different configs, or under a fold rule this binary does not refold, are a 409 carrying period_a, period_b, config_a and config_b. Developer mode is unchanged.

• #823 -- the /events export names the rule that assigned each row's issue (ADDITIVE; one export column). GET /api/v1/events appends attribution_rule as the last JSON field and the last CSV column: branch, worktree-cwd, worktree-toolpath, carry, pr-number-at-insert or branch-at-merge (#1074: server-assigned, never client-sent); legacy where no rule was recorded (every row stored before #823); unknown for a stored value outside that set. The DSAR export (GET /developer/{id}/export) shows the stored value as stored: null where none was recorded. No field is retired; see GET /api/v1/events.

• #975 -- erasure follows retired canonical ids (ADDITIVE; schema version 4). DELETE /api/v1/developer/{id} adds deleted.canonical_id_history (always present), and deleted.sealed_person now also counts keys computed from a canonical id an alias edit retired, in periods sealed while the link was active. The database moves to schema version 4, one-way: a version-3 tierd refuses it.

• #823 -- POST /events accepts attribution_rule and the unattributed:foreign-repo bucket (ADDITIVE on the server). Both are new accepted inputs; every pre-#823 request is accepted unchanged. The new bucket can appear in data_quality.unattributed_buckets, and is not exploratory spend. An older tierd 400s either, so the server ships first.

• #913 -- erasure tombstones sealed person keys (ADDITIVE; schema version 3). DELETE /api/v1/developer/{id} adds deleted.sealed_person (always present: sealed person keys tombstoned, never deleted), and total_deleted includes it, so an erasure whose only effect is tombstoning returns 200 rather than 404. The database moves to schema version 3, one-way: a version-2 tierd refuses it.

• #864 -- anonymized modes publish one breakdown per install and window (BREAKING behaviour in anonymized modes; three additive fields). Before, a team/division response published the group rows beside a second and third breakdown of the same window -- the work-type segments and the cost composition -- and they differenced to a group below k even when every published row had k people: pooled team rows minus work-type totals recovered a 3-person group's $9.21, and a model one developer used published that developer's $4.44 in cost_composition.by_model. Now, in team and division mode only: ?work_type= on /scores is a 400; work_types (with its per-segment teams, aggregation and kanon_suppressed), segment_reconciliation, cost_composition, data_quality.unattributed_buckets, data_quality.exploratory_cost_share and data_quality.mixed_price_versions (on /scores and both /compare windows; price_table.version then names only the active table, and a floored warning is to return through a follow-up issue) are absent, and so is data_quality.attributed_cost_share; spend under the unattributed pseudo-developer is dropped from every figure, which narrows #856's "an uncounted identifier's figures stay summed" for pseudo-developers; and when the other bucket does not reach k under #856's counting rule and per-measure floor, the WHOLE response is withheld -- teams (named rows included) and total -- and declared in kanon_suppressed, whose withheld_cost_composition and withheld_segment_reconciliation are now false. /scores/compare withholds its whole comparison when its own residual or either window's own other bucket does not reach k. Fields (additive): kanon_suppressed.withheld_teams (always present in the object): true when the rows were withheld with the residual; data_quality.excludes_unattributed_spend and data_quality.attribution_coverage, both described under GET /api/v1/scores. Breaking: anonymized responses lose the keys above, and a response that used to carry named rows beside a withheld residual now carries none. No key leaves the schema developer mode reads, and developer mode is unchanged. No Deprecation/Sunset header is sent: the keys are withdrawn to stop a disclosure, which a sunset period would prolong. #937 (an audit that solves every published sum) is the route to bring a work-type or per-model view back to anonymized modes. Ships in the first tagged release after this merge.

• #944 -- the read token no longer scrapes /metrics in anonymized modes (BREAKING auth behaviour; one new credential; no schema bump). Two scrapes of /metrics a short interval apart difference into one person's spend and activity, below the k floor. Now: in team and division mode GET /metrics answers the read-only viewer token with 403 (body names --metrics-token) and accepts the new metrics token (--metrics-token, TIER_METRICS_TOKEN, @/path/to/file, or metrics_token in YAML) or the write token; with no metrics token configured, only the write token scrapes. The metrics token is refused 403 on every other route and on the proxies, and serve refuses to start when any two of the write, read and metrics tokens are equal. developer mode is unchanged, and with no token configured /metrics stays open in every mode. Breaking: a Prometheus job scraping an anonymized install with the read token gets 403; point it at the metrics token (security.md § The metrics token). The flag, env var and config key exist only from this release; an older binary refuses --metrics-token and a config with metrics_token at startup, so upgrade tierd with the metrics token set, then repoint Prometheus. #908 (splitting the token scopes) may later subsume the metrics token.

• #854 -- POST /costs refuses rows a running org poller already counts (BREAKING behaviour; one additive request field; one additive export column; no schema version bump). Before, a manual row for the provider of a running Anthropic Admin or OpenAI Usage poller was accepted 201, and when it was the polled org's usage it was counted twice: the poller brings the org's recorded usage up to the provider's total and never subtracts /costs rows. Now: such a row is refused 400 unless it declares "billed_to": "other"; see POST /api/v1/costs. The 201-to-400 change happens only on a server that runs that provider's poller; every other install behaves as before. A keyed retry of a row stored before the upgrade, sent without billed_to, now gets 400 on such a server. Field: billed_to (optional request field, additive; only "other"). ⚠️ Version skew: upgrade the server first. An older server rejects the unknown field with 400 (DisallowUnknownFields), so a client that sends billed_to to it fails on every row. An override: true request without billed_to still corrects a row that already owns its key, which is how a stored double count is fixed; one whose key owns no row is refused like any other. At startup tierd serve warns, per running poller, about undeclared manual rows on days that poller covered. How to list rows stored before the upgrade, by API or SQL, is under POST /api/v1/costs. Export: billed_to is appended to the GET /events JSON and CSV (empty when not declared) and added to token_events rows in GET /developer/{id}/export (null when not declared). No field is retired. Schema: the schema version is unchanged, because billed_to is an added column, so a binary older than #854 can still open the database. Running one against it admits undeclared manual rows again (it has no refusal), and the #854 startup warning will count them.

• #938 -- a push outcome's owner is ordered by GitHub's push time (behaviour fix; one additive export column; no schema version bump). A push outcome was re-owned to its earliest commit by commit time, which the committer sets, so a later push of a commit dated earlier the same UTC day took another developer's row. Now: the order is repository.pushed_at from the push payload, then commit time, then SHA. Entries stored before the upgrade and pre-ledger markers sort first, so no stored outcome changes owner. A push with no usable pushed_at is recorded but sorts after every push time and, among such pushes, by arrival. This holds only while no binary older than #938 writes to the database: the schema version did not change, so such a binary can still open a database a #938 binary has opened, and every entry it writes gets push_order 0 and keeps precedence permanently. Do not run a pre-#938 binary against that database. Export: each push_outcome_commits row in GET /developer/{id}/export gains push_order (integer, additive): the commit's earliest push time in Unix seconds, 9223372036854775807 for a push without one, and 0 for a pre-ledger marker or an entry stored before #938. Erasure is unchanged. Metrics: tier_push_missing_pushed_at_total counts commits recorded without a usable pushed_at. No field is retired.

• #856 -- the k-anonymity floor counts people, not identifiers (BREAKING behaviour in anonymized modes; one additive response field; one additive export key). Before, any identifier with spend or merged work filled a seat, so hand-entered /costs rows, push-only commit authors, identifiers nobody put on the roster, and bots could lift a group to k, and a five-person row whose cost was carried by one person published that person's exact cost. Now: the rule under data_quality.uncounted_active_ids applies to teams, every work_types[].teams, and each window of /scores/compare, with the per-measure floor on top. Field: data_quality.uncounted_active_ids (additive, omitempty, /scores only). kanon_suppressed gains no field; developers now counts people under the new rule. Export: GET /developer/{id}/export outcomes rows gain author_type (additive). Breaking: in anonymized modes a group or residual that was published may now be withheld, with total, cost_composition and segment_reconciliation (on /scores/compare, total) withheld alongside it as in #593. No field is retired, so no Deprecation/Sunset header is sent. Ships in the first tagged release after this merge.

• #914 -- alias edits are dated (BREAKING behaviour; no schema bump). Team and division rows now place each event by the dated membership of the identifier it was recorded under, not its canonical developer's. POST and DELETE /developer_alias and every org_hierarchy write append membership rows, dated by the server clock, for each identifier whose placement they change, so no alias edit moves an identifier's past between teams. Events under an alias from before it was added now stay in the team the identifier was in then (usually other). Both alias routes can now answer 409 (clock behind) and DELETE can answer 503. The upgrade gives each existing alias its person's dated history, so no past window changes. Both guarantees hold only while no binary older than #914 writes to the database: because the schema version did not change, a binary built from main between #912 and #914 can still open a database a #914 binary has opened, and its alias edits append no membership rows, which the one-time upgrade does not repair, so events under those aliases then place as unassigned. Do not run such a binary against that database; no released version is affected, since v0.5.0 and v0.5.1 were never tagged. Until #913's sealed periods ship, an alias merge or unmerge can still change whether a past team clears the k floor; #913 closes it.

• #849 -- a squash merge counts once whatever order its events arrive in (behaviour fix; additive export and manifest keys; no schema version bump). With push capture on, a squash merge whose push arrived before its pull_request was stored twice: a push outcome and the PR outcome. Now: every captured push commit is recorded in a per-commit ledger, and the PR outcome — from the webhook, tierd backfill or POST /api/v1/outcomes — removes its merge commit's contribution in the same transaction. A push outcome that held only that commit is deleted; one that holds other commits stays, and its developer and ts are re-derived from its earliest remaining commit (commit time, then SHA) — so a push outcome's owner can change after it was first written. Push outcomes written before the upgrade are never deleted. The push outcome keeps its (repo, issue, UTC day) grain, 0.5 weight and every export column. Export: GET /developer/{id}/export gains push_outcome_commits and push_outcome_audit arrays (additive); erasure clears the subject's rows in both and re-owns a push outcome that also holds another developer's commit. Manifest: watermarks.ledgers gains max_push_outcome_audit_id and push_outcome_audit_count (additive, tiermanifest1 unchanged); tierd verify-report reports them as push reconciliations. Metrics: tier_push_merge_commit_captures_total counts pushes that carry a Merge pull request #N commit beside captured commits (the #934 leak). No field is retired. Ships in the first tagged release after this merge.

• #886 -- team and division rows are dated (BREAKING behaviour; one additive export key; schema version 2). Before, every window was grouped by today's team map, so reading /scores, moving one developer and reading again showed that developer's figures in the difference of two team rows. Now: teams (team and division modes, including work_types[].teams), /scores/compare, team_rollups and ?team= group each event by the membership its developer held at the event's own time, from an append-only ledger dated by the server clock. team_rollups rows are per event, not per person: a developer who moved inside the window appears in two rows. Alias edits are dated too (#914, above). A developer whose only figure in a group is paid spend no longer counts toward its k floor. Requests: PUT/POST /org_hierarchy answer 409 when the server clock reads earlier than the developer's current membership began; valid_from and valid_to are refused 400 like any unknown field. Export: GET /developer/{id}/export gains a hierarchy_membership array (additive), without the stored written_by fingerprint. Breaking: past team rows change once on upgrade only for people first assigned after it (their earlier history stays in other), and a group padded by paid-only seats may now be withheld. The database moves to schema version 2, which an older tierd refuses to open; binaries older than #141 do not check the schema version, so the bump cannot stop them — back up before upgrading and never run them against an upgraded DB. No field is retired, so no Deprecation/Sunset header is sent. Ships in the first tagged release after this merge.

• #871 -- plain POST /costs refuses another identity's key (BREAKING status; no field changes). A keyed post whose cost_usd matched the stored row's was accepted with 201 whatever its identity, and MAX-merged its token counts into that row -- so a post reusing another developer's key raised their captured row's counts and wrote nothing for the caller. It now returns the override path's identity-mismatch 409 when the stored (developer, issue_id, model, source, fidelity) differs, and a same-identity re-post no longer changes the stored token counts on either path. Breaking: a client re-posting such a key goes from 201 to 409; its 201 never recorded its spend. The owner of a row can now get that 409 on a same-cost retry too: when the stored fidelity is a pre-#82 value outside daily/estimated (pre-#82 /costs accepted any fidelity string), or when the first post sent fidelity: "daily" and the retry omits it (omitted defaults to estimated). Nothing is written either way; the remedy is to resend with the stored fidelity, which for a pre-#82 value is not possible (see the pre-#82 note under POST /costs above).

• #919 -- erasure and export cover watcher checkpoints (ADDITIVE). DELETE /api/v1/developer/{id} adds deleted.watcher_checkpoint (rows tombstoned plus rows deleted), and total_deleted now includes it; GET /api/v1/developer/{id}/export adds a watcher_checkpoint array.

• #893 -- browser-shaped requests refused (BREAKING request-side behaviour; no field changes). Three refusals close cross-site and DNS-rebinding writes to a tierd the operator's own browser can reach. Content-Type: every POST, PUT and PATCH under /api/v1 answers 415 unless its media type is application/json, in token mode too. curl -d without -H 'Content-Type: application/json' sends a form type and now gets 415. Cross-origin: a request whose Sec-Fetch-Site is not same-origin or none (or, without that header, whose Origin host differs from Host) gets 403 on /api/ for every method, including a clicked link, and on every other path for any method but GET, HEAD and OPTIONS, so the provider proxies too (#903). Host: a tokenless tierd on loopback answers 403 to any request whose Host is not a loopback name or IP, except on /webhook/github. Breaking: a client that wrote with another Content-Type goes from 2xx to 415. The shipper, tierd hierarchy import, curl and SDK clients send no Origin or Sec-Fetch-Site and address the server by the name they dialled, so the two 403s do not reach them. Ships in the first tagged release after this merge.

• #853 -- the unattributed pseudo-developer no longer counts toward the k-floor (BREAKING behaviour in anonymized modes; no new field). A residual cohort of k-1 real developers plus the unattributed pseudo-developer (the org billing pollers' remainder) counted as k and was published, so a sub-k group of real people cleared the floor on the strength of spend no person is behind. Fix: only real people count toward the floor. That residual is now withheld, and withholding it takes total, cost_composition and segment_reconciliation with it (on /scores/compare, total alone -- it ships no sidecars), exactly as any #593 suppression does. (A residual of the pseudo-developer alone was already withheld; it now reports developers: 0 rather than 1.) Field: kanon_suppressed.developers now counts real people only and can be 0 -- the case where the only group withheld is the pseudo-developer's spend. The field keeps its name: it was always documented as a count of developers withheld, and the pseudo-developer is not one, so counting it was the defect, not the meaning. Applies to /scores (data_quality.kanon_suppressed), each work_types[] segment (work_types[].kanon_suppressed), and /scores/compare (top-level kanon_suppressed). Developer mode is unaffected. Breaking: in anonymized modes a window that previously returned total and its sidecars may now return them absent with kanon_suppressed set, and a consumer that assumed developers >= 1 must handle 0. No field is retired, so no Deprecation/Sunset header is sent. Ships in the first tagged release after this merge.

• #821 -- scores.team_rollups (additive; developer mode only). A top-level array that partitions total by org_hierarchy team, plus one unassigned: true row for developers with no team, so the rows' weighted_points and total_cost_usd sum to total's. It answers "where did the org's points and spend go, by team" without a ?team= request per team. Classification: additive -- a new omitempty response field; no existing field changes meaning. Why not teams: teams is frozen as the k-anonymized array of the anonymized modes, labelled by aggregation. Filling it in developer mode with unfloored rows would repurpose it in place, which rule 3 forbids, and would make aggregation absent beside a populated teams for the first time. Shape rules that are easy to get wrong: the mode rule alone decides presence -- developer mode, beside total; absent in team and division mode (an unfloored per-team rollup is the #593 differencing channel), and so under any k-anonymity suppression, which only those modes raise; rows in byte-wise ascending team-name order; not narrowed by ?team= or ?work_type=; not on work_types segments. Scope: the read-only viewer token now sees every team name and its totals in developer mode (ruling #821 = B); GET /org_hierarchy stays write-scoped. See the endpoint section.

• #824 -- exploratory_cost_share description corrected (documentation only). The value is unchanged, and so is the name, which is historical. The field description in this document, and the docs changed with it, no longer call this spend exploratory or planning overhead: it is spend recorded on main or master, which TIER could not link to an issue. Other places may still use the old wording until they are updated. Both data_quality.exploratory_cost_share and the per-developer exploratory_cost_share are affected. See the GET /scores field list.

• #751 -- report_manifest.repo_scope_excluded (additive). A scoped manifest now pins the repo-blind rows a strict ?repo= dropped -- token_events, cost_micro, outcomes -- which is the pinned form of what /scores discloses under the same key in data_quality. Why: that figure was the one published number a scoped manifest's own identities structurally could not cover. A scoped /scores reads the unqualified sentinel rows to publish it, while the #747 scoped digests exclude those rows by design (widening them would reintroduce the #590 over-attribution) and a scoped manifest carries no fleet-wide digest. Measured: an in-place reprice of a repo-blind row moved repo_scope_excluded.cost_usd from 9 to 14 while the scoped digests and watermarks were byte-identical, and tierd verify-report printed REPRODUCED over changed served bytes. Classification: additive -- a new omitempty response field. No manifest_schema bump: no existing field changed meaning, and an old consumer ignoring the key still reads every other field exactly as before. A scoped manifest without it verifies as NOT PINNED, never an error; a fleet-wide one prints no line at all, because a fleet-wide report excluded nothing and there is no pin to miss. Shape rules that are easy to get wrong: present on every scoped manifest including an all-zero one (an omit-when-clean pin is vacuous exactly when it matters), absent on every fleet-wide one, and denominated in micro-dollars rather than the dollars /scores publishes. See the endpoint section. ⚠️ This endpoint's earlier additions (#715, #740, #747) have no changelog entry of their own; they are recorded in the endpoint section above. Do not read their absence here as "nothing changed".

• #746 -- the DEFAULT ?since= window now opens at the start of its UTC day (BEHAVIOURAL, not opt-in; a request-parameter DEFAULT moved, no response field was renamed, removed or repurposed). When ?since= is omitted the lower bound was now - 90d carrying the current time of day; it is now that instant snapped BACKWARD to 00:00:00Z. One definition (api.defaultSince, called from parseSince's empty branch) feeds every windowed read: six call sites, NINE endpoints, because parseExportParams is a single call site serving four routes. /scores, /scores/{developer}, /scores/compare, /report_manifest, /org_actual_spend, and the bulk exports /events, /outcomes, /quality_events and /quality_history. Explicit bounds are untouched -- YYYY-MM-DD / YYYY-MM / YYYY already parse to midnight UTC. What moves: a default window is up to 24h WIDER, so it can include events timestamped between the UTC midnight that opens the window and the now - 90d instant the old bound started at. On a populated install that is a real change in the numbers. Measured in-process on the fixture in cmd/tierd/verifyreport_defaultwindow_test.go -- three $4 events (and their outcomes) at the window-opening midnight, alongside three $3 events deep inside the window: total.total_cost_usd 9 -> 21, plus a developer row the old bound excluded. Both figures are asserted by that test, so this entry cannot drift away from the fixture it cites. Classification, stated plainly because the obvious label is wrong: this is NOT rule 3. Rule 3 governs a RESPONSE FIELD whose number comes to mean something different, and its remedy is a new field name or a /v2. No response field changed meaning here -- since was always specified as the "echoed window lower bound (UTC calendar day)", and the snap is what makes that description literally true. What changed is the DEFAULT VALUE of a request parameter, which the rules did not previously cover; the table above now has a row for it, and this entry is its precedent. The obligation that does apply is announcement, which is what this entry is. Direction is not arbitrary: widening can only ever add spend that really occurred, where snapping forward would silently drop a partial day of cost out of a cost metric. Also worth knowing: an install whose FIRST captured event falls in that widened day will newly report window_predates_cost_capture on the default view -- honest (the window really does now predate capture), but new. And checkWindowRetention compares since against the retention horizon, so once #252 pruning is armed the no-parameters request becomes the shape most likely to trip its 422; it is inert today (SetRetentionHorizon has no non-test caller). One new sharp edge: the two-request workflow that builds a verifiable report (GET /report_manifest then GET /scores, merged) resolves the default SEPARATELY in each request. Before the snap the two bounds differed by the milliseconds between the calls -- always slightly, harmlessly. They are now byte-identical all day, but differ by a full 24h if a UTC midnight falls between the two calls. Take both requests on the same UTC day, or pass explicit bounds. Why it was worth a population change: /scores echoes since as a bare calendar day while /report_manifest publishes the honest instant, so a default report claimed "2026-05-31" for a window that opened at 2026-05-31T05:00:58Z -- and tierd verify-report refused that manifest with exit 2, because /scores has no query that reproduces a mid-day bound. The DEFAULT report shape was the one shape that could not be verified. The verifier's refusal is deliberately UNCHANGED and still fires for hand-written and pre-#746 manifests. Not affected: tierd score / ship / backfill keep their own unsnapped parseSince -- those feed JSONL scans, not a windowed store read, where a wider scan is merely redundant work.

• #687 -- source_ref's value shape for CI rows (BREAKING on GET /api/v1/quality_events and GET /api/v1/quality_history). CI quality events now encode head_sha:run_attempt:workflow_id; they encoded head_sha:run_attempt. No column was added, renamed or reordered, so the JSON and CSV shapes are untouched -- but the VALUE shape of an existing column changed, which the table above classifies as Breaking on its own. Rationale: flaky-rerun matching carried no workflow identity at all, so any successful workflow run on a merge commit within 30 minutes of any failing one neutralised the failure and a 0.7 outcome silently read 1.0. In a repo with CI + lint + docs + CodeQL on the default branch those finish seconds apart, and anyone with push rights could make it deterministic by adding one trivially-green workflow -- no webhook secret required. Breaking: a consumer re-deriving the multiplier must now pair a ci_fail_flaky with a ci_fail on the same head SHA AND the same workflow_id, not the same head SHA alone. A consumer that reads parts[0]/parts[1] positionally is unaffected; one that asserts exactly two components, or treats a third as impossible, breaks. Rows written before #687 keep the two-component form and are treated as carrying NO workflow identity: they pair only with each other, never with an identified row. That is what makes a pre-#687 outcome re-derive to the value it always had rather than being silently re-judged. Reverts are unchanged (the bare revert commit SHA).

• #638 -- GET /api/v1/version added, and commit added to /livez (ADDITIVE). A new open probe endpoint reporting build identity, plus one new omitempty field on an existing body. No existing field changed name, type or semantics, so a client parsing /livez today is unaffected. Rationale: the version string alone cannot identify a build -- a tagged release reports the same string however it was built -- so a deployment could not be asserted to be the build it was believed to be.

• #619 -- the reserved-sentinel ingest guard now covers developer (BREAKING on POST /costs, /events, /outcomes, /actual_spend, /developer_alias, PUT/POST /org_hierarchy; silent header drop on the proxy). #466 closed forgery of the unattributed sentinel on issue_id and deliberately left the developer half open. This closes it, with the same predicate rather than a lookalike, so the two columns cannot drift. Breaking: developer may no longer carry the sentinel family — the bare unattributed plus any unattributed:<reason> sub-bucket — on any of the six endpoints above. 400 on all of them, case-insensitively and after trimming whitespace. It was previously written silently. On POST /developer_alias the rule applies to both alias and canonical. Why the break was taken: this is the worse half of the #466 vector, and the only half that pays. TIER is points / (cost/1000). Forging issue_id moves a dollar between buckets inside the forger's own denominator and leaves the headline score unchanged; forging developer moves it out of that denominator entirely, onto the unattributed pseudo-developer, so the forger's cost falls and their score rises. It was also user-visible: segment_reconciliation.developers[] emitted a row whose developer was literally "unattributed". POST /developer_alias is included because an alias is a retroactive rename of the identity space — the score join resolves stored developers through it before aggregating — so without that guard the spend endpoints are bypassable in one hop. ⚠️ org_hierarchy was missed by the first pass of this work and added after review, which is worth recording because of why it was missed: it reads as org-structure admin rather than a spend write. It is not. upsertHierarchyTx also opens a period_membership seat backdated to 0000-01, and nothing downstream excludes the sentinel from a per-developer aggregate — so one authenticated write enrolling unattributed into a team drags the whole unattributed pool into that team's denominator. Every other surface here is self-dealing; that one is aimed outward. No allowlist anywhere, unlike issue_id: the /events allowlist exists because the JSONL collector legitimately ships the sentinel family as an issue_id on every session message it could not link to an issue. Nothing legitimately ships it as a developer: the two producers that assign it — the anthropicadmin / openaiusage org pollers, for aggregates that cannot honestly be split per person — write in-process via collector.Ingester and never cross an HTTP boundary, and the sources they carry are not shippable over /events in the first place. The proxy's own missing-header fallback is likewise server-side. So the strict rule costs no capture. Blast radius: a client that was forging. unknown — the real no-identity fallback collector.OSUsername() emits — is unaffected, as are ordinary identities that merely contain the word (unattributed-bot, not-unattributed). tierd ship --developer unattributed will now fail its batch; that invocation was always a forgery. Proxy (not an error, by design): a forged X-Tier-Developer is treated as a missing header rather than rejected — the proxy sits on the request path and must never fail a provider call over attribution metadata. The stored row is identical to the missing-header case; what changes is the counter. Also additive: tier_proxy_unattributed_total gains a developer-forged value on its header label, mirroring issue-forged. No existing series changes meaning — a forged header previously incremented no counter at all. This is the label to alert on: it is the only one of the five that indicates a client raising its own score.

• #466 -- scores.segment_reconciliation (additive) + the reserved-sentinel ingest guard (BREAKING on POST /costs, /outcomes, /events). Additive: a top-level segment_reconciliation block on GET /scores partitions the window's cost into outcome_linked / no_outcome / unattributed, each as both _usd and _cost_micro, with the exact partition invariant holding on the integers. kanon_suppressed gains withheld_segment_reconciliation. Purely additive: no existing field changes meaning, and the block is omitempty. Breaking: issue_id may no longer carry the reserved unattributed sentinel. POST /costs and POST /outcomes 400 on the whole family, case-insensitively and after trimming whitespace; POST /events allows exactly the collector's four canonical spellings and 400s everything else. It was previously written silently. Why the break was taken: the sentinel is server-assigned, and a client forging it moved its own dollars out of the no_outcome thrash signal and out of the attributed side of the #234 coverage split. Worse, a case variant classified DIFFERENTLY in SQL (LIKE, case-insensitive) and in Go (HasPrefix, case-sensitive), so one dollar was reported simultaneously as unattributed spend by cost_composition and as abandoned real-issue work by segment_reconciliation, in one response, against a named developer. The read side is now GLOB (case-sensitive) so the two engines agree on stored rows; ingest is deliberately WIDER than the read side so a variant never becomes a row at all. Blast radius: no legitimate producer sets the sentinel as an issue_id on these HTTP surfaces. The GitHub webhook derives ids via issueref, which can only emit #[1-9]\d* / ABC-123 shapes. The org pollers (anthropicadmin, openaiusage) DO assign the bare sentinel for aggregates they cannot split per developer — they are unaffected because they write in-process via collector.Ingester, never over /costs. The /events allowlist exists precisely because the JSONL collector assigns it too, and a 4xx there is terminal for the stateless shipper. ⚠️ Scope, stated precisely: this guard covered issue_id only. The same string is also the sentinel for the developer field; that half was closed separately by #619, below. Also additive: tier_proxy_unattributed_total gains an issue-forged value on its header label. No existing series changes meaning — a forged header previously incremented no counter at all, since the guard did not exist. Today's readers: none. This ships the DATA only; internal/dashboard does not render segment_reconciliation, so the segmented panel a reader actually looks at still shows outcome-linked cost alone. The UI pass is separate work.

• #668 -- three org-hierarchy routes answer write-lock contention as 503 instead of 500 (BREAKING status change). PUT /api/v1/org_hierarchy/{developer}, POST /api/v1/org_hierarchy and POST /api/v1/period_membership/{developer}/end now take the SQLite write lock before they write, bounded at the same 250ms the other request-path writers have used since #346/#598/#610. Contention on any of the three is therefore 503 + Retry-After: 1 instead of 500. Breaking, and recorded as such rather than filed under "a better error": a status code changes for an input a client can actually hit, and a client with a 500-is-fatal rule now sees 503. Retry the 503; do not retry the 400 or the 500. ⚠️ But the shape of this break differs from #610's, and the difference is worth stating because the obvious reading is wrong. #610 also shortened a wait, so contention it had previously waited out and completed began failing instead. That does NOT apply here. Measured: the DEFERRED read-then-write these three used to run did not wait at all -- SQLite runs no busy handler for a deadlock-prone upgrade, so it returned SQLITE_BUSY in ~65us and the handler answered 500. So these routes never completed under contention; they failed immediately with an unretryable error and said 500. No client loses a success it used to get. The change is 500 -> 503 on a request that failed either way, plus a Retry-After telling the client what to do about it. One route deserves its own note: POST /api/v1/period_membership/{developer}/end also returns 400 when period_end precedes the membership's start. Contention is classified BEFORE that check, so a transient lock conflict is never reported as incoherent input -- which would tell a client to fix a period_end that was perfectly valid. Why the change was made at all: it is the precondition for raising SetMaxOpenConns (#669). These sites' in-process atomicity came from the single connection, so raising the pool without converting them would have turned a latency defect into a correctness one -- an unretried SQLITE_BUSY_SNAPSHOT (517) race -- with no test failing.

• #610 -- POST /costs answers write-lock contention one way (BREAKING status change on the plain path). The plain, non-override half of the endpoint now takes the SQLite write lock before it writes, bounded at the same 250ms the override: true half has used since #346. Contention there is therefore 503 + Retry-After: 1 after ~250ms, where it was previously a 500 after the DSN's full 5000ms block with no Retry-After. Applies to keyed and unkeyed posts alike. Breaking, and recorded as such rather than filed under "a better error": a status code changes for an input that a client can actually hit, and a client with a 500-is-fatal rule now sees 503. The correct handling is the one the override path already documents -- retry the 503, do not retry the 409 or the 500. ⚠️ And the break is wider than the 500 -> 503 swap, so do not read it as error-text polish: the wait itself shrank from 5000ms to 250ms, so contention the endpoint previously waited out and completed as a 201 now returns 503 instead. Any client posting into a contended store sees more failures than before -- each of them fast, retryable, and carrying Retry-After. A client with no retry on /costs at all is the one that regresses, and it is the one that must change. Why the break was taken: one route answered the same transient condition two different ways depending on one request field, and no caller can reasonably retry one and not the other. The 500 was also the worse of the two answers -- it reads as a broken database, so an operator goes looking for corruption when another writer simply held the lock. And the 5000ms wait was never free: with a single write connection, a request that blocks that long stalls every other in-flight request behind it, so the endpoint was buying one client's 201 with every other client's latency. It is the same defect class #598 fixed across the store, here on the busiest write path. What does NOT change: the 201/200 status codes and bodies themselves, the #295 divergent-cost 409, the #346 override behaviour, and the 500 for a genuinely permanent store failure (read-only or full database -- deliberately NOT reported as 503). On 503 nothing was written: the insert runs in one all-or-nothing transaction that takes the lock before it writes.

• #605 -- ranked on every compare DELTA row (additive field). teamDeltaJSON -- the shape behind /scores/compare's teams[] rows and its name-free total -- now carries a DERIVED ranked: a.ranked && b.ranked, computed once server-side. The rule it encodes is one sentence: anything derived from an unranked input is itself unranked. Why an AND and not an OR: a ranked baseline beside an unranked selected window lets a reader reconstruct the withheld ratio exactly (selected = baseline + delta), and % change = delta/baseline is a pure function of the withheld baseline ratio -- it leaks directly rather than additively. The one-ranked-one-unranked case is precisely the one worth withholding, so it is the case the AND catches. Not omitempty: a false is the load-bearing value here, so omitting it would drop the verdict entirely rather than encode it. (Do not read this as a licence to feature-detect on field presence -- see the compatibility rules above; livez's version remains the supported mechanism.) Derived, with a single producer: consumers READ this field instead of re-deriving the conjunction. #502 added ranked to the aggregate and it reached only one of the org headline's three consumers, because the other two re-derived the quotient from raw sums rather than reading the struct (#605 fixed the compare view, #606 the CLI report). A rule re-implemented at each consumer drifts at each consumer. Today's readers: the dashboard's compare card gates its delta and % change on total.ranked. The teams[] rows carry the same derived field for contract uniformity -- one struct, one producer -- but the dashboard's team dumbbell reads the two sides' own a.ranked/b.ranked directly, so nothing consumes ranked on a teams[] row yet.

• #502 -- ranked on every group aggregate (additive field). teamScoreJSON -- the shape behind total, the ?team= filter, the k-anonymized teams array, each work_types segment, and both sides of /scores/compare -- now carries ranked, the #133/#136 evidence floor applied to the aggregate's SUMMED inputs (outcomes >= 3, spend >= $5.00, no zero-token outcome). It previously existed only on developerScoreJSON, so a group aggregate reached every consumer with no ranking verdict at all and was rendered as evidence by default. Not omitempty: a false is the load-bearing value, and omitting it makes "unranked" indistinguishable from "a server that never said". No field's meaning changes, and tier is NOT one of them: an unranked aggregate still carries its exact quotient (the #502 case ships tier: 2.8e8), per #136 -- the number is never altered, only its ranking authority revoked. Consumers must gate the headline on ranked; do not expect a scrubbed or floored number. Deliberately NOT accompanied by a team-level sample_n: that count is the missing denominator that keeps data_quality.attributed_outcome_share non-invertible in the anonymized modes. A boolean discloses a threshold crossing, not a count.

• #593 -- k-anonymity residual floor (BREAKING behaviour in anonymized modes; additive field). The residual other cohort was emitted with no k-floor, so an anonymized deployment published a sub-k cohort's exact figures -- reproduced at k=5 as one developer's TIER, cost, points and cost-per-point. Reachable by narrowing any axis; the ?repo= guard added in #590 closed only one of them. Fix: a sub-k residual is withheld, and total plus cost_composition are withheld with it -- necessary because total minus the named rows reconstructs the hidden cohort exactly. Applies to /scores, each work_types segment, and /scores/compare. Declared via the additive data_quality.kanon_suppressed. Breaking: in anonymized modes a response may now omit total and cost_composition, and visible rows no longer sum to the window. The previously documented "totals are preserved exactly" property is retired -- it is the property that made the disclosure recoverable. Developer mode is unaffected.

• #590 -- ?repo= scoping on the scores endpoints (additive fields) + strict query-parameter validation (BREAKING behaviour, deliberately). Two halves that must ship together. Additive: ?repo= on GET /scores and GET /scores/{developer}, plus the data_quality fields repo_scope, repo_scope_excluded and spend_leverage_suppressed (the last three mirrored as top-level fields on the developer detail). No existing field changes meaning. Breaking: all three scores endpoints now reject unrecognized query parameters with 400 instead of ignoring them. Classified as breaking and recorded as such rather than quietly filed under "additive" -- a client sending an extraneous parameter goes from 200 to 400. Why the break was taken: /scores previously accepted ?repo= and ignored it, returning a whole-installation aggregate indistinguishable from a scoped one. The filter alone would have left the trap one keystroke away (?repos=, ?Repo=), where a caller's assertion passes while asserting nothing. The governing invariant is that "could not scope" must never share a response shape with "scoped, and this is the result"; a silent wrong answer is worse than an error. Scoping semantics: strict equality. Rows carrying the unqualified sentinel are excluded, never folded in -- tolerant matching would attribute every repo-blind row in the installation to whichever single repository was named. Strictness can under-count, so it is disclosed (repo_scope_excluded) rather than left silent: a scoped figure over a window containing repo-blind rows is a lower bound. spend_leverage/actual_paid_usd are suppressed under a scope (actual spend has no repository and cannot be divided by one) and the suppression is declared. 🔴 What #593 does NOT close, stated plainly so nobody reads it as more than it is: it is a per-RESPONSE rule, and cross-request differencing remains open. Two separately k-safe windows -- neither suppressed, neither declaring anything -- still subtract to the cohort active only in the wider one, recovering points as well as cost. No per-response rule can close that; it is the query-composition problem and needs a different control (rate limiting, query logging, or a privacy budget). Treat anonymized aggregation as raising the cost of identifying an individual, not as a guarantee against a determined caller who can issue arbitrary windows.

• #277 -- GET /api/v1/scores/compare (additive: new endpoint). A before/after period comparison: two half-open windows (since_a/until_a, since_b/until_b) in, per-developer or per-group deltas plus a legacy raw, unvalidated non-overlap significant flag out. Read scope. Reuses the /scores windowed computation (extracted into a shared loadWindow), so a compared score matches /scores for the same window. Three invariants are enforced server-side (the reason it is an endpoint, not a client two-fetch): (1) anonymized-mode k-anonymity is a two-window INTERSECTION -- a group is named only if it clears the k-floor in BOTH windows, else it folds to other in both, so presence never differs across windows and no sub-k aggregate leaks through a delta; (2) the same anonymized guard as /scores -- never a named per-developer delta in team/division mode; (3) per-window data_quality. A new endpoint breaks no existing consumer. Unblocks the dashboard dumbbell (#278).

• #239 -- scores.cost_per_point + scores.rubric version stamp (additive). Added the inverse-unit cost_per_point (total_cost_usd / weighted_points, 0 on a zero-point row at #239; null since #472) and its self-relative bootstrap CI (cost_per_point_ci_low/high, the reciprocal of the tier CI, no second resample) to developerScoreJSON and developerDetailResponse; cost_per_point (no CI) to teamScoreJSON; and an always-present top-level rubric ({version}, scoring.RubricVersion) stamping which canonical weight-rubric produced the weighted_points, the weight-side analogue of price_table. Purpose: give the TIER number a MEANING without an absolute band. cost_per_point is the constant-dollar benchmarking/trend unit. What closes the generous-vs-strict labeling exploit is NORMATIVITY -- the single canonical rubric compiled into the binary, so everyone weights against the same calibration instead of house habits; the rubric version stamp is PROVENANCE, not the closer: it does not set the weights, it records WHICH rubric produced a weighted_points so two numbers can be trusted to share a matched rubric (and a mismatch surfaces as non-comparable AND visible instead of a silent category error). No absolute good/ok/poor band is defined anywhere -- comparison is self-relative and valid only within a matched rubric.version + price_table.version (see docs/rubric.md). Existing fields and the TIER formula are untouched; pinned consumers unbroken. (No cross-org comparison is planned.)

• #295 -- POST /costs divergent keyed re-post now 409 (bug-fix; narrowly breaking). Fixes silent financial data loss: after #233 a keyed re-post with the SAME idempotency_key but a CHANGED cost_usd was silently dropped (first-writer-wins) yet still returned 201, so a finance correction vanished with a success code. Such a divergent re-post now returns 409 Conflict with a JSON error body; the stored cost_micro remains immutable (#233) -- the 409 REJECTS the write, it never overwrites. Strictly scoped to the divergent case: an IDENTICAL re-post (same key, same cost) is unchanged -- still 201, still idempotent -- and an unkeyed post is unchanged. Divergence is judged on the stored INTEGER cost_micro, so an honest retry whose float/FX/rounding jitter rounds to the same micro value does NOT 409. Classified breaking only for a client that depended on the silent-drop-returns-201 behavior -- i.e. on losing its own correction. The correction path is the sanctioned audited override below (ruling C); a NEW idempotency_key is a second row that every spend read adds to the first (#860).

• #346 -- POST /costs sanctioned cost-correction override, ruling C (additive). The follow-up #295's changelog entry above named as a separate piece of work: override: true + required override_actor + override_reason lets a legitimate finance correction land on a divergent keyed re-post instead of 409ing, as a narrow, audited, single-column (cost_micro-only) UPDATE with an append-only cost_correction_audit row (old -> new, actor, reason) -- never a last-writer-wins upsert. Purely additive: every pre-#346 request (no override field) behaves identically to before, including the #295 409. See the full contract above, including the endpoint's stated trust model: the identity check closes the accidental key collision, not deliberate misattribution by a holder of the write token, and override_actor is a self-asserted claim.

• #351 -- scores.data_quality true-attribution-coverage + unjoined-developer flag (additive; presence-contract clarified). Added three data_quality fields so the headline /scores number is honest about how much of the window it actually covers: attributed_cost_share (fraction of window cost_micro joined to a real issue, not the unattributed sentinel), attributed_outcome_share (fraction of outcomes with matching token spend), and unjoined_developers (developers with cost but no outcomes, or outcomes but no cost -- the silent-TIER=0 identity mismatch; named in developer mode, name-free counts only in team-aggregation mode, #185). No existing field changed meaning or computation. coverage_pct is NOT touched and was NOT measuring attribution coverage: it is per-developer capture FIDELITY (realtime vs. estimated share of recorded spend) and correctly reads ~100% even when most spend is unattributed -- the mismatch the PM surfaced was a reading error, now documented, not a bug in coverage_pct. Presence-contract note: the two coverage shares are ALWAYS present when the window has the relevant data (spend / outcomes), so a non-empty window now ships a data_quality block even when nothing is flagged (previously the block was omitted unless a tripwire fired). A truly empty window still ships no key; a consumer that ignores unknown keys is unaffected. The dashboard trust strip keys only off the zero-token fields, so it is visually unchanged.

• #293 -- scores.data_quality.mixed_price_versions (additive). Added an omitempty [<int>] field to the data_quality block: the ascending distinct price_table versions that priced the window's token_events, present ONLY when more than one version is spanned. scores.price_table.version stamps a single active table, but promotions retain the original row basis (#1231), so a window legitimately mixes historical and active pricing; this WARN keeps the stamp from reading as false uniformity. Name-free (version integers only), so it carries identically in developer and team-aggregation mode. No existing field changed meaning; a consumer that ignores the key is unaffected.

• #242 -- push_day on the outcomes export + quality audit bulk exports (additive). Appended push_day as the trailing column of the GET /outcomes JSON and CSV (the UTC per-issue-per-day dedup key a source='push' row aggregates to; "" for a PR row) -- a pinned positional consumer is unbroken. Added two new read endpoints, GET /api/v1/quality_events and GET /api/v1/quality_history, reusing the #191 keyset-pagination / limit / Accept machinery and inheriting the #185 team-mode 403. Together they make an outcome's multiplier re-derivable (quality == last new_quality) from a BI export, not just the erasure-scoped DSAR export.

• #234 -- scores.cost_composition sidecar (additive). A whole-window, name-free breakdown of where spend went -- cost by normalized model, per-class token composition, attributed vs unattributed spend, and the two optimization levers (cache_read_share, premium_model_share). omitempty, so a window with no token spend ships no key. Pure sidecar: the TIER formula and every existing /scores field are untouched. Pinned consumers unbroken.

• #48 -- GET /api/v1/healthz extensible subsystem body (additive). Added a top-level subsystems map ({"<name>": {healthy, detail}}) and an aggregate healthy bool. The legacy top-level watcher block is retained (duplicates subsystems.watcher.detail) so pre-#48 consumers are unaffected; it is now deprecated in favour of the map. 200/503 semantics unchanged. Subsystems now register into a health.Registry instead of the handler hard-coding one key, so v1.5 collectors extend the body without a schema break.

• #236 -- GET /api/v1/fidelity endpoint added (additive). Per-canonical- developer capture-fidelity signals (now/since_7d/since_30d window stamps; per developer event_count_7d, event_count_30d, last_event_by_source, fidelity_levels, unknown_model_cost_share). Read-scoped; 403 in team-aggregation mode like the bulk exports. Shipped in #320 on a branch that predated this contract doc (#241); the catalog entry was backfilled in #322. A new endpoint changes no existing surface.

• #304 -- host + billing_mode columns (additive). Appended to the token_events JSON/CSV export. billing_mode (per_token|subscription|self_hosted_amortized) discriminates whether cost_micro is a canonical per-token figure or a derived/approximate one. Pinned consumers unbroken.

• #238 -- session_id column (additive). Appended to the token_events export (and accepted on POST /events). Opaque Claude Code session UUID; NULL for session-blind producers.

• #713 -- price_table.table_hash + price_table.file_hash (additive). Both are always present on /scores and /scores/compare (and in tierd score-log's JSON). They are deliberately absent from /api/v1/version, which is unauthenticated -- see content identity. A client that decodes price_table into a closed struct is unaffected (both are new keys); one that rejects unknown keys must be updated.

• #233 -- price_table stamp + price_version column (additive). scores.price_table ({version, effective_date}) is now always present; price_version was appended to the token_events export. The server became the single pricing authority (POST /events reprices; client cost_usd is a cross-check).

• #231 -- repo column (additive). Appended to BOTH exports and accepted as an optional field on POST /costs and POST /events. issue_id values were deliberately left unchanged so a consumer pinned to issue_id keeps reading the same value; the repository arrived in its own new column rather than changing an existing column's shape in place.

• #191 -- bulk exports added (additive). GET /api/v1/events and GET /api/v1/outcomes introduced (keyset-paginated, JSON default + CSV). Both return 403 in team-aggregation mode. New endpoints, no existing surface changed.

• #187 -- work-type segmentation; /scores top-level fields SEMANTICALLY DEMOTED. Added scores.work_types (the authoritative within-category comparison) and work_type/work_type_source columns on the outcomes export (additive). In the same change, the top-level developers/teams/total became a POOLED population summary that is explicitly NOT a cross-type ranking. The numbers stayed parseable while their meaning narrowed; that semantic change shipped without a version signal or deprecation header, and is the motivating defect for this contract (#241). Under the rule above it should have been announced via a changelog entry and the field doc comments (it now is); the new meaning correctly shipped under a new key (work_types) rather than repurposing the old fields.

• #270 -- division-aggregation mode + aggregation discriminator (additive field; new opt-in mode). Adds --aggregation division, a second ANONYMIZED level that rolls org_hierarchy up one step past team to division, reusing the identical k-anonymity floor and every suppression guard team mode has (the per-developer /scores/{developer} 404, the bulk-export/fidelity 403s). Its rows ride the SAME teams array as team mode; the new top-level aggregation string field (omitempty, absent in developer mode) says which level the rows are. Adding the field is additive and back-compatible; the mode itself is deploy-time and opt-in like #185. k-anonymity holds independently at each level because every level is a flat partition of the same developer set, so a sub-k team suppressed at team level is absorbed into a >= k division at division level, never re-exposed.

• #185 -- team-aggregation mode (behavioural, opt-in). When the server runs in AggregationTeam mode, GET /scores replaces named developers with k-anonymized teams and emits developers as an empty array, and GET /scores/{developer} blanket-404s. This is a deploy-time mode, not a wire-shape change to a given response, but it changes which fields are populated -- consumers must handle the empty-developers/teams shape. (The bulk exports landed later in #191 and inherit this policy, returning 403 in team mode; see that entry. Division mode #270 rides the same policy.)

• #136 -- data_quality block + zero_token/flagged_outcomes fields (additive). Zero-token-outcome tripwire surfaced on /scores and /scores/{developer}.

• #133 -- ranking fields (additive). sample_n, ci_low, ci_high, ranked added to per-developer rows; the array is not pre-sorted (at #133; the array has since been sorted by developer identifier -- see the /scores catalog).

• #55 -- cache_write_5m_tokens/cache_write_1h_tokens (additive); cache_write_tokens deprecated. The legacy single-bucket request field is accepted with a Warning: 299 header (the last use of the RFC 7234 precedent; new deprecations use the RFC 9745 Deprecation / RFC 8594 Sunset pair).

Changing the API

When you add a field, add it in the same PR to (1) the Go response struct in internal/api/, (2) this document's endpoint catalog, (3) the API changelog, and -- for the CSV exports -- (4) the relevant CSV header slice (eventsCSVHeader, outcomesCSVHeader, qualityEventsCSVHeader, qualityHistoryCSVHeader) and docs/how-it-works.md. When you deprecate or change a field's meaning, follow Announcing a deprecation: new field name (never repurpose), the RFC 9745 Deprecation / RFC 8594 Sunset headers, and a changelog entry.

Relationship to the ingestion seam contract

TIER's cross-service ingestion seam, tier-jsonl-ingestion (Claude Code session JSONL -> tier collector), is pinned by the JSON schema at docs/contracts/tier-jsonl-ingestion.schema.json. That seam is the external Claude Code producer format tier consumes; tier owns and publishes the seam contract even though the data flows inbound, because tier, not the producer, defines which fields it requires. This document, by contrast, governs the HTTP API tier itself PRODUCES. The /api/v1 REST surface is not yet pinned as its own formally versioned seam contract; that is a possible follow-up once an external consumer of the REST contract needs a stability guarantee.

Merged-PR attribution evidence (#1074)

Developer data exports include nullable outcome head_branch_hash, created_at and merged_at. Older rows retain NULL. These fields are additive in that export; the GET /api/v1/outcomes JSON/CSV contract and POST /api/v1/outcomes request are unchanged. Head refs are hashed using canonical repo + "\x00" + branch after stripping refs/heads/; default/unknown branches produce NULL, and raw head refs are not stored on outcomes. Missing PR-opened or merge evidence disables branch credit.

Root viewer declarations and settings (#1440, plan P13/P14)

Declared viewers can use their node or personal sign-in bearer/session on the existing coaching and single-developer score card routes in developer mode. Hierarchy placement alone grants no access. These authenticated cards add declared_viewers; legacy pair-credential card bytes retain their shape. The legacy DELETE /api/v1/developer/{id} contract and frozen legacy golden remain unchanged. New routes refuse legacy tokens and use the existing admin session, Origin/CSRF, rate limit, strict JSON and no-store boundary.

Settings use explicit flag > environment > config pins, then saved DB values, then defaults. Evaluation defaults off, shared ingest defaults warn, retention defaults 90 days (60–365). A whole-set invalid update is 400 and saves nothing. Retention lowering returns a preview and confirmation token before any save; the identical confirmed request applies the window for the next prune. Tokens are bound to the root credential, requested changes and previous settings, expire after ten minutes and are single-use. Read-only serve has no settings PUT. See identity access for request and response details.

The settings migration follows per-node sealed decisions (v22) at schema step v23, reuses subject notices and adds server_settings and nullable sealed_report.settings_json. In team/division mode and the developer-mode org sealer's team view, new seals record live settings values and sources through the existing immutable metadata path. These seals and body replay use that resolved snapshot for evaluation labels and contributor counts, including offline verify-report; current settings do not override a stamped seal. Old seals remain NULL and keep their existing replay rules. Binaries predating settings refuse v23; binaries predating graft refuse v25. Import apply advances the schema to v26; mapping-audit source redaction advances it to v27. This binary refuses any schema above v28 before migration.

Graft source, preview and apply (P34–P36)

Schema v25 adds consented graft staging and mapping erasure after per-node sealed decisions (v22), persisted settings (v23), and vendor mappings (v24).

These routes use Cache-Control: no-store and the identity rate limit. Legacy admin/read tokens cannot open them. Admin mutations require JSON and the existing Origin/session CSRF checks; scripts may use their scoped bearer credential.

The bundle contract is tier-import-bundle.schema.json. The source URL must be an HTTPS origin or its exact /api/v1/export/bundle URL, without user information, query, fragment, or another path. The company server fetches from whatever host root names and sends the export key to that host. A wrong host receives a live key that may be able to pull the named bundle from the real source before consumption or expiry. The fetch honours proxy environment variables via http.ProxyFromEnvironment (code: internal/api/graft.go, fetchImportBundle; internal/store/graft_source.go, graftExportIdentity). Choosing the host is a root-only trust decision: internal, loopback and link-local addresses are allowed; the URL checks do not limit network reachability. Redirects fail; the response is capped at 64 MiB (67,108,864 bytes) with a 30-second fetch timeout. A fetch timeout returns 400 with {"error":"import source timed out"}. The source export and destination fetch, decode, preview and apply share this fixed byte bound; it is not an event-count limit. The standard server write timeout remains 60 seconds. Oversized bundles return 413 with error, size_bytes and limit_bytes before any destination staging or imported rows. size_bytes is a lower bound when reading stops at the limit plus one byte; a declared Content-Length or source refusal is source-claimed. A destination also checks streamed bytes when Content-Length is absent. On a real HTTP transport, an understated Content-Length truncates the visible body; malformed or incomplete JSON returns 400 rather than a size refusal. Source 413 refusals relay only validated numeric size and limit fields, never remote error text. Bundles are never truncated to fit. A preview contains people, consented, name_free (aggregate row count), duplicate_events, left_behind, left_behind_rows, estimated_lock_seconds, estimated_lock_seconds_min, estimated_lock_seconds_max, memory_gb_for_64_mib, and clashes[{source_developer,existing}]. Event duplicates are checked by idempotency key, then by the shared content fingerprint, against local and incoming rows. A preview writes no usage rows and creates no people. A large import can use about 1.4 GB of memory for a 64 MiB bundle, holds the database writer during staging and apply, and grows the write-ahead log. The byte cap does not bound those costs to 64 MiB.

EXTREME — concurrency and data loss during company imports (#1488, ruling A‴). While an import applies, live events wait and aren't dropped. They can be lost if the process dies, including being killed for memory on a small server, if the 30-minute cap passes, or if the write fails after the wait; TIER flags a report when that may have happened. Lost proxy events can't be recovered.

The legacy estimated_lock_seconds midpoint remains for compatibility; use estimated_lock_seconds_min and estimated_lock_seconds_max for the range, and memory_gb_for_64_mib for the memory warning. The lock estimate is a range: about 20 seconds per 100,000 events on a fast machine, about 60 on one core, and slower servers can take many times longer. Allow about 1.4 GB of memory for a 64 MiB bundle; a 1 GB server may be killed for memory, losing live events in flight. The byte cap does not bound memory to 64 MiB.

During the source pull and apply, proxy inserts wait on an in-process signal without a database connection. JSON and SSE responses complete while capture continues afterward, retaining only the event and tracked by the same shutdown drain. Outside imports, the existing 90-second budget and roughly 250 ms lock tries are unchanged. After the signal clears, that normal budget restarts. Preview and apply clear the 60-second HTTP write deadline after root auth. On SIGTERM, closing active HTTP connections cancels an unfinished import; capture drains before the store closes.

Each source pull or apply durably records its own unique attempt before its lock. A failed record write refuses the operation. Every exit removes only its own record with a detached context, retrying for up to five seconds. Cleanup failures log only a sanitized error class. Both servers cover each source pull; the destination also covers preview and apply. A 503 before the pull starts does not consume the source export key. Startup treats any leftover record as a possible loss and sets the durable data_quality.live_capture_may_be_lost flag; read-only serving re-reads that warning for each report without writing it. Startup skips a flag write when its dates are already covered and warns with a sanitized error class if the writer is busy; serving continues. Exhaustion and final write failures also set the flag once a write is possible, increment tier_proxy_writes_total{provider,outcome="error"}, and log an ERROR without names, credentials or underlying error text. Failed flag writes retry within the same bounded budget; writable close flushes a pending warning.

The settings row stores the earliest and latest UTC dates when events may have been lost. A legacy boolean has an unknown first date, so it covers the past through its stored write date; a record without a usable date is treated conservatively through the date it is read. Only reports whose windows overlap those dates carry the boolean data_quality.live_capture_may_be_lost. Sealed months keep the warning stored with their body, including org reports, totals, compare and their CSV exports (the CSV column is live_capture_may_be_lost). Later live losses do not rewrite sealed months. The dashboard says: “TIER may have missed some AI costs in this period, because a server restart or an import interrupted recording.” There is no clear command: later periods outside the date range are unaffected.

At most 10,000 captures continue after responses at once. Above that limit a response waits for its capture, providing back-pressure without dropping events.

Webhooks keep today's 503 on write-lock contention and must be manually redelivered; GitHub does not automatically redeliver failures. Other routes, including POST /api/v1/costs, retain their documented 503 and Retry-After responses. The 64 MiB limit and all-or-nothing apply are unchanged.

The stored apply receipt includes lock_started_at (sampled after lock acquisition, before authorization) and lock_ended_at (the final receipt-write marker immediately before commit, rather than a post-commit observation). The dashboard displays these stored markers; older receipts may lack them. Receipt replays preserve these times. The 64 MiB limit and all-or-nothing apply are unchanged.

The mappings PUT has a dedicated 1 MiB (1,048,576-byte) request cap, enough for 1,000 clash mappings with ordinary identity labels. An oversized request returns 413 with {"error":"import mappings exceed 1048576-byte limit"}; malformed JSON still returns 400.

Matching IDs always require an explicit decision. map names an existing local identity; new must name an unused local identity. Mappings never imply a merge. The store's readiness prerequisite rechecks every clash and target against the current database; it refuses missing or conflicting mappings, including clashes introduced after preview. Apply calls that prerequisite inside its write transaction. An unmapped clash returns 409 and writes nothing.

Data-subject exports, erasure, and retention resolve held staged people and import_batch_people rows through the explicit mapping, or the source ID when unmapped. A colliding source name cannot export the held mapping or invalidate the mapped person's stage. Once staging is absent, source-named subjects can export source metadata with the mapping's target developer omitted, and erase that metadata. Erasing a source-only name in an id_mapped audit row nulls only source_developer; the target's audit row remains available in their export.

The dashboard's /import-source page exposes only the signed-in personal holder's consent, or root-only export issuance. Root also has /import for pulling a preview, saving explicit clash mappings and applying it. /api/v1/me includes import-source for personal and root principals and import for root only; node principals receive neither. These pages use the shared CSP, nosniff, no-store and session CSRF transport. The shown-once export key includes its expiry and clears on Hide, same-tab navigation and pagehide. The pasted key is cleared as soon as the preview request starts, including failed requests. Apply remains disabled until every clash has an explicit saved choice and renders the stored apply receipt returned by the API. No import state or key is saved in browser storage, URLs or history. The dashboard's map choice sends the preview's matched existing identity; only new accepts a typed target, initially <source_developer>-imported. A 409 after preview discards the batch and clashes and reopens the pull form; another preview requires a newly issued one-time source key.

Staged bundles expire after 24 hours; expired or erased stages cannot be applied. Applied batches retain a name-free receipt for idempotent retries. PUT mappings for an unknown batch returns the same 409 import preview expired or unavailable as an expired batch. The clock-driven cleanup runs at startup and every minute while serving. The consuming bundle GET is omitted from read-only serving. Consent GET remains a read without database writes. Graft table deletion counts appear only when rows were deleted. Erasure receipts always include the fixed erased_import_record notice; they never count record entries.

Apply returns batch_id, people, events, duplicate_events, conflicting_events, outcomes, skipped_events, skipped_outcomes, left_behind, left_behind_rows, estimated_lock_seconds, estimated_lock_seconds_min, estimated_lock_seconds_max, memory_gb_for_64_mib, and other. people is the number of named subjects processed; events and outcomes count inserted rows. Duplicate events are skipped by idempotency key, event UID, then content fingerprint; a reused key or UID increments conflicting_events only when a stored fingerprint exists and differs. A native row without a stored fingerprint cannot be compared. The existing row wins. Identity aliases discovered through fingerprints persist, so later bundles cannot evade dedup by changing an alias event's content. Outcomes deduplicate by (repo, issue_id, pr_number, ts, source) across all local developers and all people in the bundle; existing figures win even when the incoming weight or quality differs. Only source="push" uses the push path; any other source requires a PR number. A fresh pull of the same source content, with its current clashes explicitly mapped, at the same destination preserves the original receipt's batch ID and lock times without recreating erased named history. For that fresh batch, name-free totals are rechecked against the current destination k and sticky withholding, and its receipt records the resulting suppression. An exact retry of an already applied batch still returns its frozen receipt. Replay matching uses a content identity that excludes issued_at; the wire digest still covers issuance time and every other bundle field. Source identity, named rows, name-free totals, and left_behind remain part of the match. The same content at a different destination returns 409.

This protection covers content identities recorded by the corrected preview path. Previously applied batches whose staging was cleared retain only their old issuance-dependent digest; their original content identity cannot be backfilled from that digest. Retrying their original batch ID still returns its stored receipt; presenting the exact original bundle also preserves that receipt and records a stable identity for later fresh pulls. Pending previews created before this fix acquire their stable identity when applied. Changed content is a new import, subject to the erased-person record below. Erase at the source too when that source must stop supplying the person's history.

Apply refuses the entire bundle with 400 if an event or name-free total has a negative list cost or exceeds MaxTokenEventCostMicro (10,000,000,000 micro-dollars). Named events must use one of the contract-pinned v1 capture sources (jsonl, codex-rollout, opencode, muse) at realtime fidelity; poller, proxy, manual, unknown source and incompatible fidelity claims return 400. An unmapped source name that cannot be a local identity label returns 400 and must be explicitly mapped.

Rows before the permanent retention watermark are skipped as final, counted in skipped_events and skipped_outcomes, and never written. Remaining rows apply successfully; retries return the same receipt.

Named events retain source costs, price versions (including zero), pricing bases, and provenance. origin_server and import_batch_id distinguish them from local evidence; local repricing and token promotion cannot rewrite their source figures. New people have origin imported, receive no credentials or viewer declarations, and remain imported_unbound until an own-credential upload here. Explicitly mapped existing people retain their local placement and declarations. A mapped person with local history but no org-person row is registered as native at the destination, preserving native census eligibility. Imported spend remains Unknown until the subject has qualifying local evidence, then joins that subject in live identity totals and future seal populations. Imported rows never supply census evidence; existing sealed populations and apply receipts remain frozen. Local capture horizons and price-version coverage exclude imported rows.

Name-free totals are stored under the destination in external_totals, always as Other. Each other entry contains period_start, period_end, withheld, points, and list_cost_micro; both figures are null below the destination's k (at least three). Counts and identities are absent. Unrelated totals cannot supply cover to each other. Identical source-period totals are stored once; re-imports persist withholding and the highest threshold seen, so lowering k cannot release a previously withheld total. Changed or overlapping source periods, or redirecting them to another node, return 409 and roll back the entire apply. The stored receipt freezes the apply-time decision. These totals do not add local census contributors.

Bundle v1 exports only events accepted by the same predicate used by preview and apply: jsonl, codex-rollout, opencode, and muse at realtime, with nonnegative tokens and list cost no greater than 10,000,000,000 micro-dollars. Other events stay on the source. Non-push outcomes without a PR number also stay; push outcomes may have a null PR. Invalid transport figures stay on the source too. Negative or over-ceiling name-free cost totals are omitted, alongside other unsafe totals; they never disclose non-consenters in the retained-row report. Negative finite outcome points and name-free points retain their existing semantics. A new collector cannot widen v1's pinned sources without a contract bump. Preview refuses unacceptable claims before staging; apply retains the atomic refusal for forged or hand-built stages, including negative tokens.

The required digest-covered left_behind report has basis: "source-claimed" and a fixed ordered classes array. Its source classes are jsonl, codex-rollout, opencode, muse, proxy, anthropic-admin, openai-usage, cursor-admin, copilot-billing, api, other (unknown event sources), and outcomes (retained outcome rows, zero cost). Every class carries source_class, count, and signed net_cost_micro, including explicit zeros. It covers only active, non-departed consenters, with no per-person split. Missing, null, malformed, or overflowing reports are refused; absence never means zero. All counts and net cost additions are overflow-checked. Preview and the stored apply receipt carry the same report and left_behind_rows counter, separate from retention's skipped_events and skipped_outcomes. These are source claims, not destination usage or verified totals, and are never added to destination spend. The dashboard labels the retained-row total and class table as what the source reports in preview and completion, hides empty reports, and allows import. The source ledger is unchanged by pull: for active, non-departed consenters, event count and net cost reconcile to exported events plus retained events. Name-free SQL excludes active, non-departed consenters, including retained rows; the report accounts for those rows in the bundle while the source's ledger still includes them. Departed consenters remain excluded from named rows and the left_behind report, but their historical spend and outcomes join the name-free closed-month cohort under the existing k, contributor, dominance, and cost gates. Unsafe name-free cohorts remain omitted without a person-level refusal report.

Consent responses, consent notices, and bundle_pulled records carry the plain sentence: "Some rows stay on the source because bundle v1 exports only accepted events and outcomes." Imports are explicitly exempt from --people-cap-per-day because apply is root-only and audited; this does not change the cap for ordinary people creation. The existing staging and receipt JSON columns hold the report without an additional migration. The current database schema is v28.

The source records bundle_pulled when the one-shot snapshot is delivered. The company records import_applied; a new preview of identical content records an apply audit with replay_of_batch_id naming the original batch. Retrying an already applied batch returns its receipt without another audit. Explicit mapping saves record id_mapped. An audit failure rolls back apply, including people, usage, totals, and staging consumption. Apply is omitted from read-only serving.

Federation administration and transport (P26 + P27, EXTREME)

These routes work in every aggregation mode on a real serving instance. Legacy shared tokens grant no access. Administration uses the existing root/node bearer or cookie session boundary: cookie mutations retain exact Origin and CSRF checks; scripts may use bearer alone. All responses, including refusals, use Cache-Control: no-store. Credentials are limited to 60 requests/minute.

The v1 schema and the merged Go validator define the wire shape. At most 1 MiB and 31 closed periods may be pushed. Each accepted (server_id,period_start,period_end) is immutable. Under a later sequence, an identical period with the same digest is skipped; only new periods appear in accepted. Any other overlap with an accepted period returns 409 period_conflict, including shifted or spanning bounds. Adjacent periods are allowed. There is no provisional-revision arm. Exactly the last accepted sequence and the identical complete request bytes return the same 200; other old sequences return 409 replayed_seq. A batch either commits every new period and its replay state or commits nothing.

Missing/unknown tokens return 401 no_token/unknown_token. Revoked tokens, wrong credential kinds or another body's server id return 403 revoked_token/wrong_server; HTTP returns 403 not_https before credential lookup, including loopback and requests with missing or unknown tokens. Only TLS or a single X-Forwarded-Proto: https from a configured trusted peer satisfies HTTPS. Unknown contract major returns 400 bad_contract, invalid payloads 400 malformed, oversized bodies 413 too_large, and lockout or credential rate limit 429 rate_limited with Retry-After. Unknown tokens count toward IP lockout; known refused credentials are neutral. Logs retain no raw address, presented credential, credential-derived value or claimed server id. Refusals flush from bounded memory every minute and after HTTP drain, with a normal one-minute crash-loss window (longer during flush failures). Failed flushes are retried; detail is capped at 10,000 rows/90 days and overflow aggregates by hour/reason for 90 days. The worker prunes durable detail and hourly aggregates even when no new refusals are buffered.

Inventory status precedence is revoked, never, current, silent, then late. A server is current when its last period end reaches the UTC month boundary containing now minus the 14-day report grace. Otherwise, a server that has pushed is silent after more than seven days since its last push, or late.

Read-only serving omits push and management mutations and performs no refusal writes. GET inventory, refusals and own status remain reads. Federation adds allowed servers, immutable periods and bounded refusal detail/aggregates without a schema-version bump. The existing chain remains per-node sealed decisions at v22, persisted settings at v23 and vendor mappings at v24; federation adds no numbered step. Federation lifecycle actions are available to managing ancestors through the existing org audit route, alongside its claim rows. The frozen legacy route fixture is unchanged.

Sealed subtree report API (#1441, P18 + P19)

The additive GET /api/v1/org/report?node=&period=YYYY-MM route serves a stored per-node month. Root/node credentials are authorized to their current subtree; node defaults to the credential binding. The shared read token is explicitly accepted without contributor counts. Other legacy principals remain denied on these new routes. All existing legacy route shapes and sealed bodies remain unchanged. New schema step 22 adds per-node seals, fold decisions, read tallies and the nullable stored TTM body. Older seals retain null TTM bodies.

The JSON response contains node, period{start,end,label}, k, evaluation_mode: false, groups, other and caveat. Each group contains cell_id (dated slice), node_id (structural node), parent_id, level, level_name, name and withheld; a folded member can also have fold_id. Shown rows carry points, list_cost_usd, derived tier when cost is positive, and, for root/node credentials, bound_contributors. Withheld rows omit all figures and counts. other rows carry member_ids and the same withholding/figure rules. Historical cells whose parent is outside the authorized subtree expose no parent or external fold identifier.

GET /api/v1/org/report/compare and the compare=YYYY-MM parameter on report and CSV routes put months side by side, returning {compare:[...]} in JSON. There is exactly one period and up to twelve repeated compare values. Shared read-token reports retain mode granularity: team/developer allow the leaf level; division stops at each branch’s own legacy division node (level 1 for legacy depths, the leaf’s parent below level 2), using the same mapping as org_node_labels. Requests below that branch boundary return 404. Root/node authorization remains independent of mode. Only canonical calendar months are accepted; arbitrary bounds and aggregates return 400, and absent per-node seals return 404. A comparison never refolds, unwithholds or computes a multi-month total. Node keys are sealed-only in v0.7.0; they receive no month-to-date figures.

GET /api/v1/org/report.csv exports the same ordered rows with columns period,cell_id,node_id,parent_id,withheld,points,list_cost_usd,bound_contributors,fold_id,member_ids,name,level,tier,level_name,unplaced. Absent JSON figures/counts are blank CSV cells. Member IDs use semicolons. These routes are absent under --read-only. Responses are no-store and subtree audit failures return 503 after two failed minute flushes. Reads that cannot fit the bounded audit tally also return 503, without recording a partial comparison.

Root-level Unplaced cells carry unplaced: true and a reserved sentinel node ID, with no team name. Default root and shared reads without node= include them. The CSV unplaced column carries the same flag. These cells are omitted below the root and are never upstream named nodes. Their figures follow the same withholding rules as other cells.

A deterministic node failure permanently records an unavailable month with a CHECK-constrained cause: legacy, g_prime_refused, data_defect, no_tree or panic. The node savepoint rolls back, leaving zero org_seal_node and org_seal_fold rows. Database and I/O errors roll back the whole transaction so the month retries. Report, compare and CSV reads return the existing unavailable-month 404; callers must preserve a missing month rather than substitute zero. The legacy sealed body and legacy routes remain byte-identical.

Root credentials can read GET /api/v1/org/report/status for stored month status and cause. Node and shared read tokens cannot read causes. Federation receives a typed MISSING month and cause. Ordinary report, compare and CSV responses use one identical 404 for unavailable and never-sealed months. Re-sealing an unavailable month is not supported; adding it would require a separate decision and a table rebuild.

Federated nodes are opaque in this server’s seal: their shown rows omit figures and counts, never enter a fold, and contribute nothing to local ancestor totals. Ancestor totals remain equal to the local legacy Total; P30 adds federated totals separately. Empty local rows can be shown with zero local people and figures. Shared-token reads use the same IP lockout and 60-per-minute credential budget as root/node reads. Developer-mode tierd seal --arm, --status and --skip control the org sealer’s team view with max(k, 3).

The Organization page at /org and its /org.js script use the existing admin shell registration and return CSP, nosniff and no-store. The page selects one sealed calendar month and optionally a second month via the existing compare route. “Load month” submits the month form; setting a compare month opens “Compare groups”. Comparison labels must match the requested months. Branch rollup titles show the selected path. Currency uses en-US formatting and points and TIER use one decimal place. New groups default to the level directly below their parent. Its CSV link uses the same node and month parameters. It adds no API route or schema step. Shared-token access remains on the existing dashboard/API path; the Organization shell continues to require a root/node cookie session.

Vendor poller identity transport (#1476 part 2) adds no event wire fields or schema migration. Copilot seat IDs and Cursor emails are transient ingestion input; only root mappings can bind counted evidence. Mapping-specific delta keys add the opaque mapping ID, while unmapped and alias-only keys retain their existing format. Copilot credential probes also report seat permission failures; accept the App's updated organization GitHub Copilot Business: read permission. See identity access and collector installation and upgrade.

Live unmapped vendor users (#1476)

GET /api/v1/org/vendor-mappings/unmapped is a root-only admin route, classified with its vendor-mapping neighbours and using their authentication/read rate limits. Node, personal, other credential kinds and static tokens receive 403. Cookie/bearer ambiguity receives 400; foreign Origin receives 403. Unknown query parameters receive 400; invalid sessions receive 401; exhausted read budget receives 429; store contention receives 503. An in-memory per-vendor guard refuses overlapping fetches and enforces at least 60 seconds between fetch starts, including failed fetches, with 429 and Retry-After before upstream I/O. The GET remains mounted in read-only serving and never writes database state. Responses are private and no-store.

200 returns {users: [{vendor, vendor_user_id, login, suggestion}], messages: [], effective_from: "YYYY-MM-DD"}. effective_from is the next UTC day; suggestion is empty unless exactly one current roster person matches a normalized login or email through their ID or alias. Copilot IDs are numeric GitHub user IDs; Cursor IDs are normalized emails. Only active mappings suppress a vendor identity from the list. Ended or voided mappings may be mapped anew from the next UTC day.

A missing configuration, transport failure or unusable response yields that vendor's fixed unavailable message and no users from that vendor, still with status 200. Missing Copilot seat permission uses its fixed permission message. No upstream body or error text is exposed. Successful data from the other vendor can still be returned. Each vendor gets its own 20-second deadline, for at most 40 seconds of upstream fetching within the 60-second write timeout. CSV import uses the existing POST bulk route regardless of live-fetch availability, preserving its 201 success, 400 validation and 409 atomic-conflict semantics. CSV IDs are sent as raw trimmed text; the bulk endpoint alone normalizes and validates identities and normalized duplicates. Existing vendor-mapping route response bodies are unchanged.

Central totals and reporting coverage (#1458, P30 + P32)

The root/node sealed subtree JSON report also contains rollup{native,federated,whole,servers,caveat}. native ("Teams on this server") uses the selected node's stored local rollup, including its dated slices, without summing descendants. federated ("From federated servers") uses accepted periods in the reader's subtree. Each server entry identifies its opaque place and returns its accepted, count-free periods. These totals are reported by them, not re-checked here: central never reconstructs a server total from its groups or subtracts inside its subtree. Shared read-token reports carry no rollup key, retaining the base sealed report shape and mode granularity. They disclose neither federated totals nor server counts. Federated ancestor totals follow the dated tree at month end. Backfilled periods before a server's admission use its first place; later moves preserve the old ancestor total. Only current-scope servers expose details, so a new ancestor can read the moved server's accepted history without rewriting its own old rollup.

GET /api/v1/org/totals?node=&period=YYYY-MM returns this same rollup to root/node credentials. GET /api/v1/org/totals.csv uses the same query and writes three rows (native, federated, whole) with columns source,period,missing,withheld,points,list_cost_usd,through,servers_current,servers_total,label,tier. TIER is the ratio of total points to total list-price cost, never an average of scores. Missing or withheld figures are absent in JSON and blank in CSV, never zero. These routes accept exactly one month, no comparison or free window, and use the existing in-memory subtree read tally. They are absent under --read-only.

whole selects the latest common closed calendar month at or before the requested month; its period states which month its figures cover, and through is that month's final UTC date. It does not mix months or carry a late server's previous value into a newer month. Each included server must cover the entire identical month with accepted, contiguous, non-overlapping periods. A gap, overlap or period crossing the month boundary is missing. An unavailable local node month is missing as well. The whole rollup remains withheld if any component is withheld. servers_current and servers_total describe complete coverage of the requested month, including this server; revoked servers contribute accepted history but are excluded from both counts. A missing server month is skipped when revocation is at or before that month's start, in both federated and whole totals; accepted history is retained. The backward search stops when a required, placed, unrevoked server has no accepted period in or before the candidate month. Admitting a new federated server therefore blanks the whole-company figure until its accepted periods cover a complete calendar month that is also available on the other servers. Node readers see their selected subtree path as the combined total label; root readers retain "Whole company". Unavailable and never-sealed requested local months return the identical 404 per-node sealed month unavailable on report and totals routes.

GET /api/v1/org/coverage?node=[&month=YYYY-MM][&format=csv] accepts root/node credentials in every aggregation mode. Coverage uses the same in-memory D9 subtree tally and fail-closed behavior as report/totals reads, and is absent under --read-only. Other legacy credentials and personal/federation keys cannot open it. All responses are no-store; reads perform no database writes. Unknown, repeated or malformed query parameters return 400; an invisible target returns 404.

Without month, coverage reports the last seven days of local bound-upload receipts and live server status. Server status (current, late, silent, never, revoked) has precedence Revoked → Never → Current → Silent → Late. The expected horizon is the end boundary of the latest month whose end plus the shared 14-day default report grace has passed. Current means the last accepted period end reaches that horizon, regardless of push age. Otherwise, a push more than seven days ago is Silent; a more recent push is Late. Daily/weekly interval and UTC hour determine the reporter's next expected push, independently of other servers. servers includes schedule, last report, last period end, next expected time and contract version. With month, native group status describes receipts during that UTC calendar month; server status describes accepted periods overlapping that month, with reasons distinguishing never set up, no reports and stopped. Local receipt placement follows the dated membership/tree; a month that has not ended is refused with 400. Receipt queries bind their time window in SQL.

groups contains native node IDs and paths, status (reported, late or not_reported) and withheld. Shown rows include a reason when absent: never_set_up means no own personal/upload key was issued before the window's end for a person placed in the group at that horizon; no_reports means setup exists but there is no earlier qualifying receipt; stopped means an earlier receipt exists and none is in the window (late). This definition is shared by live and monthly modes; servers use their admission and accepted periods as setup and reporting evidence. Sub-k and complementary-withheld rows retain Reported / Not reported only: no reasons, contributor counts or upload timestamps. A shown group may include last_report_at as a UTC date, never an exact timestamp. last_period_end is the next UTC day boundary after that receipt date, and next_expected is that date's next daily receipt boundary. Both are dates and are absent when there is no qualifying receipt history. The full dated forest uses distinct own-credential contributors and complementary suppression at max(k,3); movers count on their first active slice. Monthly details require an available, shown stored node decision and use at least its sealed k. When there are no receipts in the selected month, that stored decision gates setup/stopped details; a higher configured k keeps those rows status-only. Unavailable, unsealed and withheld months remain status-only. No native group publishes a contributor count, including in sealed months. One bound upload makes a native group reporting; roster-only, shared, unbound, aliased-away and bot evidence do not count. Internal nodes report when their dated subtree reports. summary{groups_reporting,groups_total} counts native group statuses, including the selected native node, never people or servers. Servers appear separately, with reason (never_set_up, no_reports, stopped) when applicable. Monthly server metadata comes from accepted history for that month and earlier periods; revocation does not erase it.

Coverage's reporting-detail gate uses distinct reporting people per dated cell as its additive figures. Repeated receipts do not pad those figures. The same k, complementary suppression, equality, and dominance checks still apply; monthly detail also requires a released sealed group. A small group and its necessary complement retain status only, while safe siblings retain dates and reasons. Coverage releases no usage figures or contributor counts.

Coverage CSV contains group rows, server rows, and one summary row, with columns kind,node_id,path,status,reason,withheld,last_report_at,last_period_end,next_expected,contract_version,month,groups_reporting,groups_total. Withheld group detail cells remain blank; shown groups can carry reasons, report dates, period ends and next expected dates. Exact timestamps and configured schedules appear only on server rows. User-controlled labels and paths are formula-neutralized in CSV.

Federation and coverage dashboard pages (#1464, P31 + P33, MODERATE)

/federation, /upstream (Child server settings), and /coverage use the existing admin session shell, CSP, nosniff, and no-store headers. Root and node readers can view federation and coverage within their authorized subtree. Managing nodes can allow, revoke, or reissue a server token inside their branch; root can choose any native parent. Refused attempts are displayed only for root and top-level node readers; other readers see an empty table. Detail and hourly roll-up rows each have a separate display limit of 100, and roll-ups show their counts. Unknown-token refusals retain the federation reason label. The audit section uses the authorized audit inventory for root and managing nodes.

Allow/reissue tokens appear only in the transient shown-once result, with Copy and Hide. Same-tab navigation, pagehide, and session clearing erase the result; late responses cannot restore it after navigation. Mutations carry session CSRF and JSON, leaving exact-Origin enforcement to the existing API boundary. The 403/404 action message is “Your key cannot make this change.” Rate-limited changes use the approved Retry-After countdown and disable actions while waiting. Read failures use read copy and never display API error bodies. An unconfigured upstream read (503) shows the host-setup state with Save and Test connection disabled. Company totals reads returning 404 show None for each rollup, without a CSV link or a zero amount.

Root's page allowlist now includes /upstream, linked from Federation. The central HTTPS address is display-only. Saving sends only the schedule and an optional replacement token; leaving the paste empty retains the file. A paste is cleared immediately after submission and uses the existing atomic 0600 host file replacement. Host setup instructions remain linked even when saving is unavailable. The paste field uses autocomplete="one-time-code" outside the schedule form. Test connection uses the saved setup and reads central status only, without sending a report or changing push history. Its result distinguishes success, credential refusal, connection failure and an invalid upstream response, without treating these as session failures.

Both CSV anchors use download; downloading keeps the session shell visible. The Company totals panel and its reads are limited to root and top-level nodes. Coverage separates live server status from closed-month coverage and links to the API's CSV for the selected month and reader's branch. Server reasons retain never-set-up, no-reports, and stopped distinctions. Native group rows show only the status and the API-authorized date; withheld groups show status with a Withheld placeholder for the date, ignoring all other details. Federation's closed-month rollup uses the three approved source labels, its common horizon, and N of M current. Missing/unavailable totals display None and withheld totals Withheld; neither becomes a zero-dollar amount.

Child federation upstream (#1457, P28 + P29, EXTREME)

The child uses the existing tier-federation/v1 contract without a revision arm. Only sealed calendar node months are eligible, in every aggregation mode and in evaluation mode. Month-to-date and evaluation rows are never built for transport. Unavailable node months, for any cause, are MISSING: they have no period in the payload. The resulting gap is never represented as zero or an empty present period. Unplaced contributes only through its sealed root total, never as a named node or fold member. Federated nodes remain opaque. Dated and synthetic cell IDs become stable opaque UUIDs; all payloads pass the central's shared Go decoder.

Host configuration requires all three settings, with CLI > environment > YAML:

federation:
  central_url: https://central.example
  token_file: /var/lib/tier/upstream/token
  server_id: 11111111-1111-4111-8111-111111111111

The corresponding flags are --federation-central-url, --federation-token-file, --federation-server-id; environment variables are TIER_FEDERATION_CENTRAL_URL, TIER_FEDERATION_TOKEN_FILE, TIER_FEDERATION_SERVER_ID. There is no token-value flag, environment setting or YAML key. The central URL must be an HTTPS origin without credentials, query, fragment or path. The durable destination and server ID must match the host pins on restart; mismatches refuse startup to preserve pending retry identity. A refusal means this database already belongs to a different central URL or server ID: restore those host settings to resume the exact pending request. Moving the token file is allowed; only the destination and server ID are durable pins. To intentionally change either pin, keep the original database and its pending history with the original destination; provision a separate child database and server registration for the new destination. There is no in-place repin command.

All three routes require a root credential (bearer or the existing CSRF-protected browser session), return Cache-Control: no-store, and deny legacy tokens:

Without host configuration these routes return 503 after authorization. Read-only serving mounts only GET and starts no pusher. Synthetic demo never configures a pusher. The root-only Child server settings page is served at /upstream.

A paste atomically replaces the host token file with mode 0600. The file and its directory must be owned by tierd's user, the directory must not be group/other writable, and symlinks, hard links and nonregular token files are refused. The file is read again for each push, retry and connection test. Neither the token nor any credential-derived value enters responses, the database, audit or logs. A successful settings save records upstream_configured with interval, hour_utc and a boolean token_replaced, never any credential-derived value. Invalid pastes (empty after trimming, internal whitespace or more than 4096 input bytes) return 400 with the fixed message invalid upstream token; reads and writes both trim surrounding whitespace. The replacement is staged in a same-directory 0600 temporary file. Settings and audit commit before atomic rename; a database failure removes the temporary file and leaves the old token active. A rename failure returns an error after the settings and audit have committed; the temporary file is removed.

The minute worker honors the UTC hour and daily/weekly interval. Startup catches up when the configured hour has passed. Each tick sends at most 31 oldest closed months in a body capped at 1 MiB. A sealed federated node with NULL local figures remains opaque: its wire group is withheld with zero figures and no population counts, and the month can still be pushed. Sequence reservation and the exact pending body (including sent_at) commit in the additive federation_upstream table before network I/O. Upstream adds no schema-version bump: older schema-24 binaries ignore this additive table. Graft advances the schema to 25, followed by import apply at 26 and mapping-audit source redaction at 27; this binary refuses schema versions above 28. Every retry, including after cancellation or restart, uses those same bytes and sequence. Acknowledgements must match both the sequence and period list before advancing the cursor. A separate local scan watermark skips permanently missing node months without claiming that central accepted them. An available month with an unrepresentable tree stops the scan with last_error=unsupported_tree and the normal backoff; it cannot be skipped. Build failures, including invalid stored pending bytes, record last_error=build, back off and log a fixed ERROR message. Catch-up continues on subsequent ticks; once caught up, the next scheduled daily/weekly time applies. Failures retain the pending request and use exponential backoff from 30 seconds to one hour, checked each minute. A refused sequence or period is never rewritten automatically. HTTPS certificate validation is mandatory, redirects are refused, each request has a 15-second timeout, and response bodies are capped at 64 KiB. Shutdown cancels and joins the worker using serve's bounded writer drain.

Erased people and later imports (#1491, ruling A⁗)

TIER keeps this record so a completed erasure stays effective. Your organisation decides the legal basis with its counsel.

On an erasure request, if any identifier has an import trace, TIER stores one unlinked keyed hash for each canonical ID, alias and mapped source name. A batch row mapped to someone else is not a trace. If erasure deletes a mapping row whose target is someone else, it also records that source name; a wrong exclusion is reported and reversible. Applied-batch plaintext source-name rows for the erased mapped person are deleted. Retention ageing makes no entry and never deletes entries. The record holds no figures, timestamp or link between identifiers and uses its own HMAC domain. Hashes never appear in API output, logs, audit rows, receipts, previews or data-subject exports. Those compliance artifacts state the record's existence in fixed wording, without checking membership or counting entries.

The record is not anonymous: anyone holding the database could test a guessed identifier. It matches on the identifier alone, so the same identifier from any source is excluded, including a different person. Preview and apply leave a match behind, rechecking inside the apply transaction, with this report line naming nobody: “One or more people were left behind so a completed erasure stays effective.” The bundle is not refused; lookup failure refuses the import. A wrongly excluded person has to come forward because the report names nobody; root can release them. A different (renamed) identifier evades the record. A person erased here with no import trace is not recorded, except this clash case, so a later first import can recreate them. A staged copy can remain for 24 hours.

Entries are kept until root clears them or the database is deleted, with no timer. A clear removes only the named identifier; a returning person with several identifiers needs one clear each. Root states either “new consent” or “a different person with that identifier” (the API value is different person with that identifier). The response is identical whether or not an entry existed. Each clear is audited without the identifier, hash or entry count. An audited clear-all states “our counsel refused this record”. There is no dashboard control. Nothing in the release waits for counsel, and no Article is cited as the record's legal basis. The secret and entries share the database file. Entries do not survive a restore from an older backup that predates them: restoring it loses newer entries and undoes those erasures. Re-run erasures after a restore.

Schema 28 adds one table, erased_import_identifiers, after schema 27. Older binaries refuse it. erasure_notice is present in preview and completion only when someone is left behind by this record; it contains the fixed report line above. The excluded people require no mapping, and mapping saves skip them. erased_import_record in DSAR exports and both erase receipts is fixed text, independent of whether the subject is recorded. No count of entries is returned.

Both routes use the admin API's bearer or cookie/CSRF rules, are unavailable in read-only serving, refuse unknown fields and query parameters, and audit the fixed reason without the subject. Invalid reasons return 400; non-root callers are refused. Commands using a root bearer (replace the example identifier):

curl --fail-with-body -H "Authorization: Bearer $TIER_ROOT_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"identifier":"returning-person","reason":"new consent"}' \
  "$TIER_URL/api/v1/org/erased-imports/clear"
curl --fail-with-body -H "Authorization: Bearer $TIER_ROOT_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"reason":"our counsel refused this record"}' \
  "$TIER_URL/api/v1/org/erased-imports/clear-all"

Clearing allows new events to import. Identical source content still returns its old stored receipt and does not recreate anyone, including after a clear.