stdlib: complex numbers (#1043) and general eigenvalues (#1042)

[InauguralPhysicist]

Closes #1043
Closes #1042

Both found by the phugoid flight-simulator consumer, which hand-rolled five complex functions plus Faddeev-LeVerrier and Durand-Kerner to extract flight modes from a 4×4 state matrix.

What

lib/complex.eigs (new) — arithmetic (add/sub/mul/div/neg/conj/scale), mag/mag2/arg, to_polar/from_polar, eq_near, and poly_eval/poly_roots (Durand-Kerner). Complex numbers are [re, im] two-element lists — already what engineering.dft returns, so its output feeds these directly.

linalg.charpoly / linalg.eigenvalues — Faddeev-LeVerrier for any square n, and the full complex spectrum. linalg stopped at eigenvalues_2x2, which returns a silent null for any complex spectrum: a rotation matrix's perfectly ordinary ±i read as "no answer". That limitation is now documented at the function and asserted in the tests, so the contrast with the general path is recorded rather than left as a surprise.

The tests are direct unit checks, deliberately

A differential oracle is structurally blind to this arithmetic. phugoid measured a halved div surviving a full root-finding differential, because Durand-Kerner self-corrects under a scaled delta — a wrong step size still converges, just slower. So the discriminator is explicit: (1+i)/(2+0i) must be 0.5+0.5i, since a halved result still points the same direction.

Planted faults, all red:

plant	result
halved div (the one that beat the differential)	4 checks red
mul sign flip	11 red
conj implemented as neg	1 red
Faddeev-LeVerrier sign / no-divide / drops-last / unguarded non-square	10 / 5 / 1 / loud crash

The 4×4 eigenvalue case is graded by identities that tie the answer back to the matrix rather than the solver — sum of eigenvalues = mat_trace, product = mat_det, both independently tested — plus a residual check that each eigenvalue annihilates the characteristic polynomial.

Two things measured rather than assumed

• I had written that division by zero saturates at 1e308. It raises. That wrong claim was the stated justification for div's null guard, so it is rewritten to the real one: poly_roots depends on that null, because at a repeated root the Durand-Kerner denominator is exactly zero and an unguarded div makes every repeated root a crash. (z-1)^2 is in the tests.
• A first phase_spectrum test asserted the Nyquist bin's phase is +π and measured −π. The test was wrong: that bin's imaginary part is a negative zero, so atan2 takes the −π branch. Both denote the same angle and the sign is decided by the sign of a zero, so the test grades |angle| and complex.arg documents its range as atan2's [-π, π] with the caveat, rather than the tidier-looking (-π, π].

Adoption — what keeps this from being dead code

engineering.magnitude_spectrum and power_spectrum were complex.mag and complex.mag2, hand-rolled: the duplication #1043 describes, present in the stdlib itself. They now delegate, verified byte-identical across four signals. engineering.phase_spectrum is new — a spectrum has a phase as well as a magnitude, and it was absent because the arithmetic to express it did not exist.

dft's own O(N²) inner loop is left alone deliberately: routing each term through complex.mul would add call overhead for an identical result.

Note for the AOT

linalg and engineering are the first stdlib modules to import another. Every lib/*.eigs is installed together by the Makefile, so the dependency travels with them.

The AOT has no emit case for import and refuses loudly (AOT: cannot emit statement node 'import'), so adopting a stdlib module costs a consumer its AOT path. Not a regression — the gap predates this and applies to every module equally — but these raise its price, and the new transitive import means a fix must walk a module graph rather than a flat list. Filed as InauguralSystems/ouroboros#121.

Gates

• release suite 4119/4119
• ASan with detect_leaks=1 4108/4108, no leak tally
• doc_drift_check.sh clean — it caught the lib/ module count in docs/ARCHITECTURE.md

🤖 Generated with Claude Code

https://claude.ai/code/session_01Aj9b82JBb8WS3b8ExoV5Yt