Add opt-in integer LAD inversion with shared-threshold rounding

[scottstanie]

Continuous LAD inversion can return fractional date ambiguities even when its edge observations are integer cycles. Independently rounding each date can increase the LAD objective. This adds invert_stack_l1_integer(A, ambiguities, max_iter=20), which runs the existing solver and selects the best shared-threshold rounding. It returns integer-valued date offsets and their actual residual in cycles.

The API accepts a connected, unweighted incidence graph shared by all pixels and explicitly rejects missing/nonintegral observations and disconnected inputs. Its guide shows how to construct cycle observations from consistent per-date wrapped anchors, check congruence, and reconstruct phase. The default raster workflow is unchanged; phase-anchor extraction and masked raster integration remain separate work.

For integer edge observations, shared-threshold rounding cannot increase the continuous objective, and rounding an exact continuous optimum gives an integer optimum. A fixed ADMM budget is not an optimality certificate. Stress testing found suboptimal 20-iteration results on arbitrary inconsistent networks; all 120 stress cases matched HiGHS at 200 iterations. The rounding kernel accumulates at most two cost changes per edge, avoiding a stack of candidate residuals.

Validation:

• 42 tests passed across the new integer suite and existing time-series suite, including exact LP comparisons, clean phase reconstruction, arbitrary edge orientations/references, tied thresholds, missing observations, and iteration budgets.
• Pre-commit passed.
• Warm CPU benchmark on this Apple Silicon machine: 22 dates / 60 pairs / 256×256 pixels took approximately 0.58 s for continuous LAD and 0.77 s for integer LAD (1.34×). A 100-date / 294-pair / 64×64 case took 0.14 s versus 0.33 s (2.37×). These include the public API's validation and transfers, exclude JIT compilation, and are not full-workflow timings. An ASV benchmark is included.

The 300-case initial probe and the 120-case stress benchmark are reproducible in the Sarlet ionosphere review experiments. Objective optimality is distinct from recovering the true unwrapped phase; acquisition-consistent errors and nonunique minimizers remain possible.