Artifact Retention

[jarinfrench]

This PR introduces a complete artifact-retention and structure-archival lifecycle for GBOpt, with support for both Genetic Algorithm and Monte Carlo minimizers. The implementation preserves the central invariant that cleanup must never make a checkpoint non-resumable, while scientifically retained and final results remain structurally reconstructable and sufficiently provenance-backed.

Summary of changes

• Added a new GBOpt.artifacts subpackage containing immutable artifact/retention types, scientific retention rules, retention policy configuration, provenance support, safe cleanup helpers, and the runtime artifact store.
• Added stable candidate identities that are independent of evaluator file paths.
• Added bounded scientific-retention rules including KeepBest, KeepRange, KeepDistinct, and KeepIf, with deterministic ranking, tie-breaking, validation, and policy signatures.
• Separated optimizer selection, scientific retention, and operational restart requirements through independent retention reasons and operational pins.
• Integrated artifact retention with the explicit-ownership GA and Monte Carlo minimizers.
• Generalized the optimizer-facing scalar evaluation value to an objective, while retaining compatibility with existing energy-oriented evaluator callbacks.
• Added built-in and user-provided candidate-property collection for scientific retention decisions.
• Added canonical retained-structure archives so scientifically retained candidates and final/best results do not require preservation of complete evaluator work directories.
• Preserved the current optimizer best as an operational BEST_RESULT pin rather than treating the objective as an implicit scientific-retention policy.
• Persisted retention state in checkpoints and added resume-time policy compatibility validation.
• Replaced restart-unnecessary historical full evaluations with lightweight summaries.
• Rebased reusable carryover evaluations onto checkpoint-owned population artifacts so old evaluator outputs no longer remain restart-critical.
• Added managed-root cleanup and evaluator-owned cleanup callbacks, with destructive operations restricted to explicitly managed artifacts.
• Made cleanup best-effort: deletion failures retain storage and report diagnostics rather than invalidating an otherwise valid checkpoint or optimizer transition.
• Added durable artifact provenance through an atomic current-state manifest and append-only history covering evaluation, retention changes, archive materialization and eviction, source pruning, and cleanup failures.
• Added generic run-level calculation provenance for calculator identity, source/software versions, potential hashes, evaluator configuration, result conventions, and other campaign-provided reproducibility metadata.
• Deferred destructive cleanup when required calculation provenance cannot be persisted, preserving the policy of leaking storage rather than destroying the only remaining calculation context.
• Added a separate bounded lifecycle for failed evaluations. Failed candidates remain outside the scientific RetentionCandidate model, but now receive lightweight failure provenance and may retain a configurable number of recent diagnostic artifacts before older failed work directories become eligible for cleanup.
• Consolidated common GA/MC archive preparation and committed-cleanup logic, path normalization, evaluation validation, and provenance event construction to reduce duplication while keeping ownership-specific behavior in the appropriate layer.
• Added restart regressions that exercise pruning followed by construction of a fresh minimizer and checkpoint resume, verifying that cleanup preserves deterministic continuation.
• Reviewed and modernized artifact-related tests to focus on GBOpt behavior and lifecycle invariants rather than Python implementation mechanics, including converting the Monte Carlo checkpoint tests to idiomatic pytest.

Overall, this change moves persistent storage growth away from scaling with the full optimization history and toward scaling with active checkpoint state plus a bounded set of scientifically meaningful retained results. Existing keep-all behavior remains available when artifact pruning is not enabled.

Closes/References

Closes #91
Depends on #60