Integration review: preconditions, support-sized algorithms, and objective weighting

[timholy]

This branch is the result of a systematic integration review — reading the
package against the interfaces it depends on (LinearAlgebra, SparseArrays, JuMP,
Ipopt, Unitful, Documenter) and against its own documented contracts. It groups
into four themes, plus documentation.

Each commit is self-contained.

1. Preconditions that were assumed but never checked

The recurring failure mode: input that violates an unstated assumption produced a
plausible-looking wrong answer instead of an error.

• abs.(A) symmetry at the sym entry points. A symmetric cover reads one
  member of each index pair, so an asymmetric matrix silently yielded a cover of
  some unspecified symmetrization of itself. The check is on magnitudes (so a
  complex Hermitian passes) and allows ASYMMETRY_ULPS = 8, since a matrix
  symmetric in exact arithmetic lands a ULP or two off after ordinary
  floating-point work. Storage that makes the property structural is exempt;
  banded storage is not, and asymmetric banded input goes through the asymmetric
  cover family instead.
• Solver termination status. A solve that stopped for any reason other than
  success left the model holding a point that does not solve the problem posed,
  and the values were read out anyway. An asymmetric input makes the AbsLog{1}
  LP unbounded, and what came back was the base of a ray.
• The heuristic covers' penalty slot. Ignored is not unchecked — an
  unannotated slot accepted anything, so a wrong first argument silently produced
  a cover.
• Affine, context, and fixed Unitful units. An affine unit measures from a
  shifted origin, so no product a[i]*b[j] covers an entry in it. Such input was
  accepted and silently reduced to its underlying atom, leaving Unitful stricter
  than this extension.
• Axis agreement in cover_objective. Scales shorter than A previously
  scored a sub-grid without complaint.

2. Algorithms sized by the support rather than by the grid

The package documents the sparse path as the one to use when nnz ≪ n², but
five separate layers still scanned the full m×n grid. Each now reads the matrix
through foreach_support / foreach_support_sym, gathered once per call.

Layer	Before	After (n = 200/400/800, nnz ≈ 7n)
Soft-cover kernels (20 sweeps)	3.3 / 17.3 / 43.7 ms	0.16 / 0.40 / 0.81 ms
:leaveout initializer	3.5 / 11.8 / 44.8 ms	0.20 / 0.50 / 1.08 ms
Native AbsLog{2} (:lsqr, allocation)	1.13 / 3.47 / 12.0 MB	0.71 / 1.5 / 3.02 MB
JuMP/Ipopt model build (gather, n = 200→400)	0.31 → 1.22 MiB	0.119 → 0.269 MiB

The consistent shape of the win is that cost now doubles with nnz instead of
quadrupling with n. Supporting changes: a GroupedSupport compressed
neighbor-list type; shared _edge_list / _sym_edge_list / _degrees helpers in
the main package so both solver extensions use them; and an asymmetric
foreach_support for Symmetric/Hermitian over a sparse parent, without which
those types fell through to the generic full-grid scan.

cover_objective itself also reads through the traversal now, adding the
off-support entries back as a single count-weighted term — every entry outside
the support has r = 0 whatever the scales, so they share one penalty value.

3. One objective-weighting convention

The symmetric objective sums over the full grid: each off-diagonal pair counts
twice, each diagonal entry once. foreach_support_sym reports each pair once, so
a caller must supply w = (i == j) ? 1 : 2 itself. This is now documented on the
traversal and applied uniformly.

The bug it exposed: symcover_min!(::AbsLinear{1}) and (::AbsLinear{2}) in the
Ipopt extension summed over the i <= j triangle, which weights a diagonal entry
the same as an off-diagonal pair even though the pair stands for two entries of
A — effectively double-counting the diagonal. The two conventions have
different minimizers, so symcover_min was ranking its multistart candidates by
an objective none of them had minimized.

Most matrices do not distinguish the two: a binding constraint has zero residual
at the optimum, and a zero residual is weight-independent. The new tests pin a
matrix that does, and check the native and HiGHS solvers against reference models
whose constraints are imposed on the full grid explicitly.

4. Interface compliance and error quality

• scalar_type is a new public hook. cover_objective took its accumulator
  from a promotion of all three operands, which has no concrete result for
  dimensional element types. Since a cover requires
  unit(A[i,j]) == unit(a[i])*unit(b[j]), every ratio is dimensionless and the
  score is a plain number; the accumulator now comes from that scalar type. The
  Unitful extension supplies the method for matrices whose entries carry
  different units.
• Tolerances scale by eps of the element type. Float64-scaled literals were
  unreachable in Float32 — every descent ran to maxiter and multistart could
  never switch off its first candidate — and stopped far short of what a wider
  type resolves. At BigFloat, the alternating least squares now converges roughly
  thirteen digits further. Float64 thresholds are unchanged.
• Complex Hermitian sparse input reached symcover_min but fell back to the
  generic O(n²) getindex walk, since the traversal specialized only on the real
  case. Only abs of a stored value is ever read, so the real bound was never
  required.
• Mismatched scale element types surfaced as a MethodError naming an
  unexported internal; they are promoted internally now.
• An empty strategy menu reported "no strategy yields a starting cover of A",
  which describes a different failure. The asymmetric drivers already got this
  right.

5. Documentation

• Both Julia blocks in the manual called symcover_min on a non-square matrix and
  had never been run. They are jldoctest now, so CI keeps them honest.
• checkdocs=:public, so the extension hooks — marked public but not exported —
  are actually checked. Falls back to :exports on Julia 1.10, which lacks
  Base.ispublic.
• A worked example in the README, which had none.
• Ipopt added to the docs environment.

Compat

JuMP lower bound raised 1 → 1.15, for the unified nonlinear interface that
supersedes @NLobjective/@NLconstraint. The legacy macros cannot be mixed with
the unified ones, a hazard symcover_min!(::AbsLinear{1}) was already exposed to.
JuMP 1.15 supports Julia 1.6+, so the LTS is unaffected.