fix: rename progressPct to historicalSyncProgressPct in sync-progress API

[lgahdl]

Summary

• Rename progressPct → historicalSyncProgressPct in the GET /api/sync-progress response schema, endpoint implementation, route description, and test assertions

Motivation

The old name was ambiguous — progressPct: 100 while isComplete: false looked contradictory. The new name makes it self-documenting: it tracks historical block-fetch progress (eth_getLogs layer), not handler execution completion.

Test plan

• pnpm typecheck passes (verified locally)
• pnpm test passes — all 31 tests green (verified locally)

🤖 Generated with Claude Code

[lgahdl]

Documentation / CI review

docs/api-reference.md — example response and description still use progressPct. Must fix before merge.

Lines 56, 63, and 70 of docs/api-reference.md were not updated:

• Line 56: "progressPct": 42.9, in the example JSON block
• Line 63: "progressPct": 100.0, in the example JSON block
• Line 70: - `progressPct` is rounded to one decimal place (0–100).

All three should be changed to historicalSyncProgressPct. The PR updates the Zod schema, the endpoint implementation, the route description string, and the test assertions — but misses the hand-written example response and the bullet-point description in docs/api-reference.md. A consumer reading the docs will get a field name that does not match the actual API response.

OpenAPI/Swagger (routes.ts) description — updated correctly. The description: string on the route now references historicalSyncProgressPct. The Zod schema (ChainProgressSchema) also updated. The Swagger UI at /docs will show the correct name on next rebuild.

No other docs files affected. docs/deployment.md and docs/architecture.md do not reference this field by name.

Overall: One actionable item before merge — update the three occurrences of progressPct in docs/api-reference.md (lines 56, 63, 70) to historicalSyncProgressPct.

[lgahdl]

Review: Rename progressPct → historicalSyncProgressPct

The rename is complete across all four affected locations:

• src/api/schemas/sync-progress.ts — Zod field renamed
• src/api/endpoints/sync-progress.ts — handler assignment and local type annotation renamed
• src/api/routes.ts — OpenAPI description text updated
• tests/api/sync-progress.test.ts — local ChainProgress type and both assertions updated

No remaining references to progressPct found in src/ or tests/.

This PR is clean.

[yvesfracari]

historicalSyncProgressPct is not clear yet for me.

I would prefer something like historicalBlocksFetchedPct

[yvesfracari]

can't we add then a historicalBlocksProcessedPct as well?

[lgahdl]

Good call — renamed to historicalBlocksFetchedPct. Names exactly what it measures: eth_getLogs block-fetch progress (ponder_historical_completed_blocks + ponder_historical_cached_blocks / ponder_historical_total_blocks), not handler execution.

[lgahdl]

Looked into this — Ponder exposes ponder_indexing_completed_events (a running count of events handled) but no matching "total historical events" gauge, so there is no denominator to compute a percentage against. isComplete and isRealtime already cover the binary states; historicalBlocksFetchedPct is the useful proxy for sync depth. Happy to revisit if Ponder adds a total-events metric in a future version.