feat(accounts): give nominator_positions a live refresh lane and stop the confident zero

[JSONbored]

Summary

• /api/v1/accounts/{ss58}/positions served captured_at: 2026-08-02T01:38:22.670Z and could never advance: the ledger behind it was written by a lane on the retired box, the lakehouse holds the frozen 153,611-row export (feat(api): serve account positions and validator nominators from the lakehouse #9266 made it readable again), and nothing refreshed it.
• Worse than the staleness: an account that began delegating after that export got positions: 0, total_stake_alpha: 0. Four of five coldkeys sampled from a live /validators/{hotkey}/nominators response came back that way — all of them provably delegating right now. That is fix(explorer): /blocks/{n}/chain-events has no cold reader — empty for all 8.76M historical blocks #9260/fix(accounts): the account summary serves empty event aggregates while /events serves 100 for the same account #9263's failure shape, and worse here, because the payload carried a confident total rather than merely an empty list.
• This adds the live refresh lane on the pattern the neurons / subnet-hyperparams / account-identity lanes already use, its staleness alarm, and — not waiting on the lane — the correctness fix that stops the confident zero.

What Changed

The lane (write side)

• migrations/d1/0011_nominator_positions.sql — nominator_positions on D1, upserted on (coldkey, hotkey, netuid) with the usual captured_at <= excluded.captured_at staleness guard. The migration's column set and the writer's bound column list are asserted against each other in both directions, the same anti-drift guarantee 0007_neurons.sql has.
• src/nominator-positions-d1-write.ts — reuses src/neurons-d1-write.ts's statement building rather than restating it, so one place owns the bound-parameter arithmetic. The prune is per coldkey, not batch-wide: a full SubtensorModule::Alpha scan does not fit one request body, so a batch-wide sweep would delete the rows a sibling request just wrote. That is the exact analogue of neurons-sync's per-netuid prune, resting on the same poster contract.
• workers/data-api.ts's handleNominatorPositionsSync stops answering 503 hyperdrive binding unavailable and writes the batch to D1. The api-Worker proxy and the token gate already existed and are unchanged. share_fraction is range-checked, not merely finite-checked: it multiplies a hotkey's whole stake at serve time, so it is the one field here whose garbage would read as a plausible number instead of as an error.

D1's bound-parameter limit. Every statement this lane issues is chunked under the Workers-binding limit of 100 bound parameters per statement — not the 1,200 the wrangler d1 execute HTTP door allows. The tests assert the platform limit (params.length <= D1_BIND_PARAM_CAP) rather than a chunk count we chose, because the count grows with the network and the limit does not.

The alarm

• src/nominator-positions-staleness-watchdog.ts + NOMINATOR_POSITIONS_STALENESS_WATCHDOG_CRON = "8,38 * * * *", modelled on src/neurons-staleness-watchdog.ts. This gap existed because nothing noticed the writer was gone. An empty table alerts too — that is the state in which every positions read is still answering from the frozen export.
• Minutes 8/38 collide with no other cron in workers/config.ts and stay off the */5 raw-capture and */15 probe grids; a test asserts the string is unique across every *_CRON export and that wrangler.jsonc declares the trigger, since dispatch keys on the literal cron string.

Serving

Postgres → D1 hot → lakehouse cold → labelled empty, wired identically in REST, MCP (both call sites), and GraphQL so the three surfaces cannot disagree. The hot leg declines while its table is empty, so the cutover is a property of the data rather than of a deploy — there is no window in which a config value and the table disagree about which tier is real.

The correctness fix — it does not wait for the lane

• A zero from the lakehouse leg now reads two more facts: the ledger's own capture stamp, and this account's newest on-chain StakeAdded/StakeRemoved from chain.account_events (which is live). The stamp fills captured_at, so the age of a rowless answer is visible at all — previously it was null, which told a caller nothing. A stake event newer than the ledger contradicts the zero, and the payload now says so (degraded.reason: "snapshot_predates_stake_activity") instead of asserting it.
• When every tier declines, the card is unavailableAccountPositions (degraded.reason: "tier_unavailable", the same vocabulary the analytics routes' degraded header uses) rather than a bare zero.
• Both extra reads fire only on the zero path, in parallel with each other, and the ledger stamp is memoized per isolate (registered with the module-state registry) — it is identical for every caller and moves at most once per lane pass. A non-empty result pays for neither, asserted by a test.
• A failed cross-check never manufactures a degraded label: a lakehouse that cannot answer says nothing about whether the zero is real.

degraded is optional on the artifact, not nullable: its absence is the healthy case, so a consumer that ignores it reads exactly what it read before, and one that checks it can tell "delegates nothing" from "we cannot currently say".

Third commit — latestStakeEventAt sanitizes its own input. R2 SQL has no bound parameters, so every predicate in that module is interpolated and safeSs58Literal is the only thing between a request path and the warehouse. The function is exported, so "the one caller already validated it" was a property of today's code rather than of the function; it now re-validates internally (idempotent on an already-safe literal) and refuses anything else rather than escaping it, matching every other predicate builder in src/r2-sql.ts. Superagent flagged this on the first push and it was a fair call.

Second commit — the MCP chokepoint. markMcpTierDegraded overwrote any degraded a handler had already set, so the specific snapshot_predates_stake_activity reason would have been replaced by the generic tier_unavailable on every MCP call — making MCP the one surface unable to report why a zero is untrustworthy, while REST and GraphQL both could. Every one of those answers is degraded either way, so keeping the more specific reason never loses the signal that marker exists for.

Measured against production while writing this

Sampled coldkeys from live /validators/{hotkey}/nominators responses and asked the live route what they hold. Every one of them — including 5DM2txvjAfp4ASTWmnUvZX4iPNeou8RWPVbXYqtBGtSzvSGc, which has 45,006 stake events and staked as recently as today — comes back:

{"ss58":"…","captured_at":null,"position_count":0,"total_stake_alpha":0,"positions":[]}

captured_at: null with zero rows is the signature of every tier declining, not of an account that holds nothing — and today the route publishes it as a confident total with no header, no field, and nothing else to distinguish it. After this change that exact response carries degraded: {"reason": "tier_unavailable", …}.

To be explicit about what this PR does and does not do for that account: it does not make it return real positions on merge. The hot leg's table is empty until the poller Container posts its first batch, so the answer stays zero — but it stops being a confident zero, and the watchdog starts saying out loud that the lane has never run. Once the Container posts, the same account resolves through the D1 leg with a current captured_at, which is the half of #9273 that cannot be closed from this repo alone.

Registry Safety

• Links a tracked, currently-open issue (Closes #<n>) — required.
• No secrets, PATs, wallet data, private dashboards, private URLs, or validator-local state.
• Generated artifacts were produced by repo scripts, not hand-edited (npm run build; openapi.json, types.d.ts, packages/contract/index.d.ts regenerated and committed). public/metagraph/r2-manifest.json and schemas/index.json are not in the diff.
• R2-only/high-churn detail artifacts are not committed.
• Public API/OpenAPI/schema changes are intentional and documented — one new optional degraded object on AccountPositionsArtifact, declared in schemas-src/routes/account-positions.ts with per-field descriptions.

Validation

All run locally against this branch, rebased on origin/main@b6907b8c5:

• npm run lint · npm run format:check · npm run typecheck
• npm run validate — 129 native subnets, 3444 surfaces, 136 providers, 2037 candidates
• npm run validate:schemas · npm run validate:api (185 routes + 8 Postgres-tier) · npm run validate:openapi (185 + 24 feed + 70 network variants) · npm run validate:types · npm run validate:contract-drift
• npm run validate:mcp — 210 tools, lifecycle + both subscribe→notify round trips
• npm run validate:migrations · npm run validate:artifact-budgets · npm run validate:docs · npm run validate:intake · npm run validate:workflows · npm run validate:private-boundary
• npm run scan:public-safety
• npm run test:coverage — full suite green; statements 99.18%, branches 98.05%, lines 99.43%
• git diff --check
• apps/ui's three doc generators + packages/client / packages/ui-kit dist rebuilds all produce no drift

Patch coverage — diff ∩ v8's uncovered set, not a whole-file percentage:

File	Measured changed lines	Uncovered (line or branch)
src/account-nominator-positions.ts	11	0
src/nominator-positions-cold-tier.ts	24	0
src/nominator-positions-d1-write.ts	14	0
src/nominator-positions-hot-tier.ts	16	0
src/nominator-positions-staleness-watchdog.ts	20	0
workers/api.ts	4	0
workers/config.ts	1	0
workers/data-api.ts	44	0
src/mcp-server.ts	1	0
src/r2-sql.ts	1	0
src/graphql.ts · workers/request-handlers/entities.ts	0	0
Total	136	0 — 100.00%

New/changed test files: tests/nominator-positions-d1-write.test.ts, tests/data-api-nominator-positions-d1.test.ts (end-to-end through the real Worker fetch handler against a real SQLite database), tests/nominator-positions-staleness-watchdog.test.ts, tests/nominator-positions-hot-tier.test.ts, plus additions to tests/nominator-positions-cold-tier.test.ts and updates to the two existing tests whose premise this change moves (tests/data-api.test.ts's "answers 503" and tests/request-handlers-entities.test.ts's "D1 never queried").

Deployment note

The D1 migration is applied out-of-band with wrangler, as 0010 was. Until the poller Container starts POSTing to /api/v1/internal/nominator-positions-sync, the hot leg's table is empty, so it declines and the lakehouse leg keeps answering exactly as it does today — with the honest-zero labelling above, which is live immediately. The watchdog will alert on the empty table until the first batch lands, which is the correct signal.

Closes #9273

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Updated (UTC)
✅ Deployment successful! View logs	metagraphed-data-api	fb960fb	Aug 03 2026, 01:40 PM

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Updated (UTC)
✅ Deployment successful! View logs	metagraphed-registry-sync-api	fb960fb	Aug 03 2026, 01:40 PM

[superagent-security]

P2: SQL injection risk via string interpolation when parameterized queries are available

latestStakeEventAt interpolates coldkeyLiteral directly into an R2 SQL query string even though r2SqlQuery supports bound parameters.

Use r2SqlQuery bound parameters with ? placeholders instead of string interpolation for all query values.

AI prompt

Check if this security scanner issue is valid. If so, understand the root cause and fix it. If appropriate, update or add tests. Keep the change focused and preserve intended behavior.

<file name="src/nominator-positions-cold-tier.ts">
<violation number="1" location="src/nominator-positions-cold-tier.ts:219">
<priority>P2</priority>
<title>SQL injection risk via string interpolation when parameterized queries are available</title>
<evidence>The latestStakeEventAt function constructs an R2 SQL query by interpolating coldkeyLiteral, STAKE_ADDED_KIND, and STAKE_REMOVED_KIND into the query string:

  "SELECT MAX(observed_at) AS latest FROM chain.account_events" +
    ` WHERE coldkey = '${coldkeyLiteral}'` +
    ` AND event_kind IN ('${STAKE_ADDED_KIND}', '${STAKE_REMOVED_KIND}')`

While coldkeyLiteral is expected to be pre-sanitized via safeSs58Literal, the parameter name is a convention, not an enforcement. The r2SqlQuery helper used elsewhere in the same file already supports bound parameters via ? placeholders (see neuronStakeByHotkeys). Using string interpolation when parameterized queries are available creates a SQL injection risk if the function is ever called with an unsanitized value, or if the safeSs58Literal helper is bypassed.</evidence>
<recommendation>Replace the string interpolation with parameterized query placeholders:

  const rows = await r2SqlQuery(
    env,
    "SELECT MAX(observed_at) AS latest FROM chain.account_events" +
      " WHERE coldkey = ? AND event_kind IN (?, ?)",
    [coldkeyLiteral, STAKE_ADDED_KIND, STAKE_REMOVED_KIND],
  );

This eliminates the injection surface entirely and aligns with the pattern already used in neuronStakeByHotkeys.</recommendation>
</violation>
</file>

[superagent-security]

Superagent didn't find any vulnerabilities or security issues in this PR.