[High] Documented checkpointing example fails verbatim against the public Study API

[gratus907]

Severity: High

The documented checkpointing usage example fails verbatim with its own parameters — the primary "run partway and save" contract advertised by docs/reference/checkpointing.md is unsatisfiable through the public Study API.

Reproduced

from typing_extensions import override
from variopt import IntegerSpace, Objective, Problem, Study
from variopt.algorithms.population import CSAOptimizer
from variopt.evaluators import SequentialEvaluator

class SquareObjective(Objective[int]):
    @override
    def evaluate(self, candidate: int) -> float:
        return float(candidate * candidate)

space = IntegerSpace(0, 20)
optimizer = CSAOptimizer.from_space_defaults(space=space, bank_capacity=8, random_state=0)
study = Study(
    problem=Problem(space=space, objective=SquareObjective()),
    run_method=optimizer,
    evaluator=SequentialEvaluator[int, int](),
)
result, state = study.optimize(max_evaluations=20)
optimizer.state_to_dict(state)
# ValueError: CSA checkpoints require generation runtime to be idle

Probing budgets 8/10/16/20/24/33/40 with bank_capacity=8 shows only the trivial initial-fill budget succeeds — any realistic "run partway and save" budget fails. There is no public API surface to reach or detect a safe checkpoint boundary from Study; existing tests (tests/csa/test_csa_checkpoint.py) only reach safe boundaries via an internal _advance_to_safe_boundary helper, never through Study.optimize.

Fix direction

Either have Study.optimize drain/commit the generation runtime to a safe boundary on return (so returned states are always checkpointable), or expose a public is_safe_checkpoint_boundary(state) predicate / stop_at_safe_boundary=True mode, and rewrite the doc example around whichever contract is chosen. Add a regression test that runs the documented flow verbatim.

[isty2e]

Closed by #46