Move metrics to Prometheus client 1.x, upgrade common-utils to 5.0, and cut 3.5.0

[pambrose]

Summary

Cuts 3.5.0 (release date 2026-09-27): a monitoring and maintenance release.

• Prometheus Java client 1.x. common-utils 5 and prometheus-proxy 4.2 require it, and the metrics endpoint now serves the 1.x PrometheusRegistry, so anything still registered in the 0.x CollectorRegistry compiles, runs, and is never scraped. The JVM collectors from Export JVM metrics and capture a heap dump on OOM #129 now use JvmMetrics.builder().register(). All 30 recording sites move from labels(...) to labelValues(...).
• JVM metrics carry 1.x names: jvm_memory_used_bytes and jvm_classes_currently_loaded, not the 0.x names most published dashboards use. JvmMetricsTest asserts against the registry that is actually served.
• FileSystemSource.file() path fix. Since common-utils 4.x it resolves against pathPrefix itself, so Challenge prepending it too doubled the prefix: invisible for "./", fatal for "../" (the Python test content).
• Docs site builds with zensical alone. zensical.toml used Material's material.extensions.emoji path, which zensical only remaps in YAML configs, so uv run zensical build failed locally. CI masked it by also installing mkdocs-material; the config now names zensical.extensions.emoji and the workflow installs zensical alone.
• Dependencies: Gradle 9.7.1 → 9.8.0 · Kotlin 2.4.10 → 2.4.20 · common-utils 3.2.2 → 5.0.0 · prometheus-proxy 4.0.1 → 4.2.0 · Prometheus Java client 0.16.0 → 1.9.0 · Flyway 13.7.0 → 13.8.0 · kotlinter 5.6.0 → 5.7.0 · buildconfig 6.1.1 → 6.1.2 · zensical 0.0.63 → 0.0.65
• Docs: 3.5.0 entries in CHANGELOG.md, RELEASE_NOTES.md, and the website release notes; README.md, llms.txt, CLAUDE.md, and the server docs updated for JVM metrics, heap-dump reporting, local-run dumps, the Prometheus 1.x registry rule, and the zensical extension naming.

Breaking change

The public Metrics properties are now Prometheus 1.x types, which is source-breaking for anything that records to them from outside the library (labels(...) → labelValues(...)). readingbat-site does not use these APIs.

Test plan

• ./gradlew test lintKotlinMain lintKotlinTest detekt: 381 tests, 0 failures, 6 skipped; lint and detekt clean
• Docs site builds with uv run zensical build --clean (no mkdocs-material) and in an isolated zensical-only env matching CI; icon shortcodes render
• After deploy: startup log reports heap dumps enabled; :8083/metrics exposes jvm_memory_used_bytes

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 25.00000% with 24 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...src/main/kotlin/com/readingbat/server/Locations.kt	37.50%	5 Missing ⚠️
...otlin/com/readingbat/server/ws/ChallengeGroupWs.kt	0.00%	4 Missing ⚠️
...ain/kotlin/com/readingbat/server/ws/ChallengeWs.kt	0.00%	4 Missing ⚠️
.../kotlin/com/readingbat/server/ws/ClassSummaryWs.kt	0.00%	4 Missing ⚠️
...otlin/com/readingbat/server/ws/StudentSummaryWs.kt	0.00%	4 Missing ⚠️
.../src/main/kotlin/com/readingbat/dsl/GitHubUtils.kt	0.00%	1 Missing ⚠️
...n/kotlin/com/readingbat/dsl/challenge/Challenge.kt	66.66%	1 Missing ⚠️
...n/kotlin/com/readingbat/server/ReadingBatServer.kt	0.00%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!