fix: per-method recovery when stored samples fail model reconstruction (#1486)

[Jammy2211]

Summary

Stored results written before a model's constructor validation tightened can hold samples the current model rejects via the narrow FitException contract. Samples.instances and the 15 methods sharing the to_instance decorator materialized those samples with no recovery, raising from deep inside instance construction (#1486; the workspace half shipped as PyAutoLabs/autogalaxy_workspace#210).

to_instance now takes a per-method recovery policy: max_log_posterior substitutes the highest-posterior valid stored sample (mirroring the #1466 max_log_likelihood guard, via a shared _instance_from_next_valid_sample helper); from_sample_index and the marginalized methods raise a typed SamplesException chained to the rejection, since a marginalized vector has no stored sample to substitute. Samples.instances skips rejected samples with a warning, reusing valid_sample_instance_pairs (#1470).

API Changes

Reconstruction failures from to_instance-decorated methods (e.g. from_sample_index, median_pdf, values_at_sigma) now raise autofit.exc.SamplesException instead of letting ModelParameterException (a ValueError) escape; the original rejection is chained as __cause__. max_log_posterior recovers to the next valid stored sample instead of raising. Samples.instances skips unreconstructable stored samples instead of raising, so it can be shorter than sample_list.
See full details below.

Test Plan

• pytest test_autofit — 2011 passed, 16 skipped (full suite, in the task worktree)
• New unit tests: instances skips invalid samples; max_log_posterior next-valid recovery and all-invalid failure; from_sample_index and median_pdf raise SamplesException; non-FitException constructor errors still propagate unwrapped

Full API Changes (for automation & release notes)

Changed Behaviour

• Samples.instances — skips stored samples the current model rejects via FitException (warning logged) instead of raising; the list can be shorter than sample_list. Use valid_sample_instance_pairs when instances must stay paired with their samples/weights.
• Samples.max_log_posterior(as_instance=True) — when the stored best sample is rejected, recovers to the highest-posterior valid stored sample (warning logged) instead of raising; raises SamplesException only when no stored sample is valid.
• All other to_instance-decorated methods (from_sample_index, median_pdf, values_at_sigma, values_at_upper_sigma, values_at_lower_sigma, errors_at_sigma, errors_at_upper_sigma, errors_at_lower_sigma, error_magnitudes_at_sigma, offset_values_via_input_values, SamplesSummary.median_pdf, SamplesInterface.max_log_likelihood) — a FitException during instance materialization now surfaces as autofit.exc.SamplesException (plain Exception) chained to the rejection, instead of ModelParameterException (a ValueError). The as_instance=False and as_dict=True paths are unchanged.
• to_instance — now a decorator factory taking a recover policy: use @to_instance() or @to_instance(recover="next_valid"); bare @to_instance no longer works (internal decorator; no downstream PyAuto repo imports it).

Migration

• Before: try: samples.from_sample_index(i) except ValueError: ...
• After: try: samples.from_sample_index(i) except af.exc.SamplesException: ...

Generated by the PyAutoLabs agent workflow.