feat(hf): card metadata + schema completeness v2 (audit follow-up)

[Flotapponnier]

Summary

Follow-up to the initial HF dataset release published at 14:37 UTC on 2026-06-22. Implements the 12 audit items.

Bumps SCHEMA_VERSION 1 -> 2. All changes are additive (no rename / no removal of existing columns except the rename sample_size -> bench_sample_size / provider_sample_size, which is the v2 break documented in the schema-versioning rationale of the publisher).

Checklist (12 audit items)

• 1. YAML frontmatter rewrite in dataset_template/README.md: task_categories -> time-series-forecasting + tabular-regression + other, task_ids added (univariate-time-series-forecasting), size_categories forward-looking (10K<n<100K, 100K<n<1M), enriched tags (21 entries including defi/solana/ethereum/hyperliquid/mev/observability/sla/mlcroissant/tabular/timeseries/monitoring), pretty_name, viewer, source_datasets, annotations_creators, language_creators, multilinguality.
• 2. higher_is_better in headlines: backfilled via the per-slug /api/stat fetches. run() now collects a {slug: higherIsBetter} map and passes it into build_headlines. Null when the per-slug fetch failed.
• 3. sample_size -> renamed: bench_sample_size (headlines) and provider_sample_size (providers). Schemas + tests updated.
• 4. dataset_info block under YAML frontmatter for all 4 configs with explicit feature dtypes (string / float64 / int64 / bool). Lets HF render the viewer without a full parquet introspection.
• 5. Data dictionary tables for every config in the README body (Data Fields, headlines / providers / timeseries / chain_leaders).
• 6. Canonical HF sections: README body restructured under ## Dataset Description / ## Dataset Structure / ## Dataset Creation / ## Considerations for Using the Data / ## Additional Information. Methodology / Update cadence / Schema stability / Provenance folded into the right H2s.
• 7. provider_type, provider_layer, provider_tag added to providers. Required surfacing them on /api/stat's rankings payload, which was a 6-line additive edit (src/app/api/stat/[slug]/route.ts).
• 8. BibTeX inline + DOI placeholder under Citation Information. CFF unchanged at the root.
• 9. chain_leaders table: schema JSON shipped, table written as a real (zero-row) parquet so downstream pipelines stabilize against the canonical shape today. Comment + README section explain it stays empty until /api/citable or /api/stat exposes bestPerChain / worstPerChain.
• 10. Timeseries 7d / 30d windows: publisher now fetches /api/series/<slug>?range={24h,7d,30d}. One row per (bench, provider, window, point_index). Falls back to the legacy sparkline for 24h when /api/series returned no data.
• 11. Tags enriched: covered by drop journal framing #1.
• 12. size_categories forward-looking: covered by drop journal framing #1.

Metrics, before vs after (live dry-run, snapshot 2026-06-22)

Table	Rows v1	Rows v2	Cols v1	Cols v2
headlines	26	26	19	20
providers	260	260	13	16
timeseries	~1,872 (26 * 72)	53,735	7	8
chain_leaders	n/a	0 (canonical empty)	n/a	11

The 30x growth in timeseries comes from emitting one row per provider per point across 3 windows instead of one aggregated row per point.

Trade-offs taken

• provider_type / provider_layer / provider_tag are null in today's dry-run because the prod API still serves the v1 /api/stat payload. They will be populated on the first snapshot after this PR ships (the route extension is additive and zero-risk).
• chain_leaders ships empty by design. Shipping the canonical 11-column schema with zero rows is friendlier to downstream consumers than withholding the table until the API change lands.
• 24h timeseries keeps a provider_slug = leader_slug fallback for benches without a /api/series payload. Documented under "Other Known Limitations" so consumers can filter on window in ('7d', '30d') for strictly per-provider trajectories.

Test plan

• cd scripts/hf_publisher && python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
• .venv/bin/python -m unittest test_publish -v (25 tests passing, was 15)
• .venv/bin/python publish.py --dry-run --out /tmp/ocb-hf-stage-v2 against prod (openchainbench.com), parquets inspected with pandas
• (post-merge) human review on HF dataset preview after the next scheduled cron run