u128 precision Phase 4: contract/schema change for the future precision-ceiling case (deferred)

[JSONbored]

Part of #2588. No action needed today — this is a forward-looking tracker, not active work. Do not implement anything against this issue unless the trigger condition below is actually met.

Context

A double (JSON number) is exact only up to 2^53 - 1, which at 1 TAO = 1e9 rao is ~9,007,199 TAO. Every _tao/_amount field in the API contract (schemas/components/05-subnets.schema.json, 06-health.schema.json — ~40 fields audited) is declared a plain number. Per-neuron/per-subnet/per-account fields never realistically approach this ceiling. The only fields whose plausible magnitude is in the same order as the ceiling are network-wide aggregates: total_stake_tao/total_emission_tao at the economics-summary/trend level, and alpha_fdv_tao (computed against the fixed 21,000,000 alpha cap).

Today's actual circulating/staked TAO is a few million — well under the ~9M ceiling. This only becomes a real concern as network-wide totals approach that boundary over the protocol's multi-year emission schedule.

Trigger condition

Revisit this issue when network-wide staked/emitted TAO (or the alpha FDV calculation) approaches within ~10-20% of the ~9,007,199 TAO exact-double boundary — check this periodically (e.g. alongside other roadmap/economics reviews), not on a fixed calendar date.

If/when triggered

This repo already has a precedent for exactly this situation: the chain-events pagination cursor (next_cursor in schemas/components/05-subnets.schema.json) is typed ["string", "null"] with a documented "Lossless ... cursor" description, specifically to avoid a JSON-number round-trip losing precision. Follow the same recipe:

1. Change the affected network-wide aggregate field(s) from number to a string type, explicitly documented as lossless (matching next_cursor's description style).
2. This IS a breaking contract change — requires npm run build + committing regenerated openapi.json/generated types in the same PR (per this repo's schema-change policy), plus a packages/client version bump for the client-SDK-sync gate.
3. Coordinate the client-side consumers (npm SDK, Python SDK, metagraphed-ui) for the type change before shipping, since existing consumers expecting a number would break on a naive type change.

Deliverables (only once triggered — not now)

• Confirm the trigger condition is actually met (real network-wide magnitude approaching the ceiling, not a hypothetical)
• Schema change to the specific affected field(s) only — do not blanket-convert every _tao field, most never approach the ceiling
• Regenerated OpenAPI/types + client SDK version bump
• Updated docs describing the string format and why

maintainer-only (owner)

[linear-code]

JSO-2540