feat(datasets): held-out validation split + runner gate (refs #259)

[openclaw-dv]

Summary

Adds the foundations for the held-out / private leaderboard cut tracked in #259:

• synthbench.datasets.split — make_split / is_held_out produce a deterministic, seeded partition over loaded items (sha256 of item_id + ":" + seed, order-independent). Default 25% held-out fraction; canonical pinned seed.
• CLI gate — synthbench run --held-out evaluates against the held-out cut. The flag requires SYNTHBENCH_HELD_OUT_AUTH to be set; the gate is enforced before any provider/dataset is loaded so a CI job missing the secret fails in <100ms.
• Per-dataset allow-list — runner-side filter applies only to pewtech (Pew ATP) and globalopinionqa, matching the scope in Held-out validation set + private leaderboard (Move 4 — integrity) #259. Other datasets behave exactly as before.
• Packaging gate — env-var lock (not MANIFEST exclude) because the raw eval data is downloaded at runtime by the dataset adapters and was never in the wheel to begin with. pyproject.toml carries a comment locking in that decision.
• Tests — tests/datasets/test_split.py covers determinism, seed sensitivity, order-independence, coverage tolerance, env-gate failure + success paths, and CLI integration. 13/13 pass; full suite 815 passed + 10 skipped, no regressions.
• Docs — docs/held-out.md covers the split mechanics, the contributor-verification sketch (score + cell counts, not raw items), the env-gate model, and a migration note for shipped leaderboard rows on Pew ATP / GlobalOpinionQA (semantics of default run shifts from "all" → "public" for those two datasets only; historical rows are not retroactively rescored).

Choice: env-gate vs MANIFEST-exclude

Picked env-gate. Reasoning in pyproject.toml + docs/held-out.md:

The raw data values are NOT in this package — dataset adapters download Pew ATP / GlobalOpinionQA at runtime into the user data dir. So there are no files to exclude from the wheel; the held-out items don't get distributed by pip install either way. The env-var lock (SYNTHBENCH_HELD_OUT_AUTH) is the meaningful gate, and it carries forward to the future shared-secret model where the periodic re-eval worker authenticates against the leaderboard server.

If we ever move raw data into the package (currently we don't), the MANIFEST exclude becomes relevant — the doc calls this out as the right escalation path.

What's TODO'd

Listed as follow-ups in docs/held-out.md:

• Server-side periodic re-eval cron.
• Trust-badge UI (✓/⚠/✗) on leaderboard rows.
• Δ-threshold calibration for red vs yellow (placeholder of 5% absolute borrowed from private_holdout.SPS_DIVERGENCE_THRESHOLD).
• Threading the partition through BenchmarkRunner so the CLI doesn't have to do an extra ds.load() pre-flight.
• The contributor-facing audit UI for "verify my score was computed correctly".

Backward-compat concerns

One semantic change worth highlighting on review:

For pewtech and globalopinionqa, the default behaviour of synthbench run now evaluates the public ~75% cut rather than 100%. Shipped leaderboard rows from before this PR were computed on the full set and remain valid as historical records, but new submissions on those two datasets are not directly comparable. The leaderboard UI should annotate the cutoff; the existing publish pipeline doesn't distinguish "all" vs "public" today, so this is a near-term follow-up. The other seven datasets are unchanged.

Closes the implementation half of #259.

Test plan

• pytest tests/datasets/test_split.py — 13/13 pass
• pytest tests/ (excluding adversarial) — 815 passed, 10 skipped, no regressions
• Smoke: from synthbench.datasets.split import make_split, is_held_out; ... round-trip
• Manual: synthbench run --held-out without env var should exit fast with a clear error pointing at Held-out validation set + private leaderboard (Move 4 — integrity) #259 (covered by test_cli_held_out_without_auth_exits_error)

Refs #259