fix(geometry): stop GeometrySpec pinning the image's inflated pixel array

[jcschaff]

Removes the one blocker identified by the getPixels() audit (#2025 §3.8).

GeometrySpec cached getImage().getPixels() in a transient uncompressedPixels field, making it
a second strong reference to the very same array VCImageCompressed already caches. The
inflated pixels then stayed reachable for as long as the geometry did, whatever the image did with
its own copy — 62 MB pinned per geometry at the size that killed two prod api pods (#2021).

Why removing it is safe rather than a trade

The cache was redundant. VCImageCompressed.getPixels() already caches the inflated array, and
VCImageUncompressed.getPixels() returns its field directly. Delegating costs a virtual call and a
null check — not a re-inflate. The field only ever added a second reference.

And it fed a cold path. The audit established that the only caller reaching an ImageSubVolume
is getSubVolume(x,y,z), whose sole caller is curveSatisfyGeometryConstraints — 100 sampled
points per curve. The other call site, GeometrySpec:898, is a diagnostic that prints
"there was no subVolume defined". Nothing here runs per-pixel over a volume.

(That mattered because the audit's other finding was a thrash hazard on per-pixel access. It turns
out not to apply to this particular field.)

Tests assert reachability, not structure

So they still catch the problem if the reference reappears somewhere other than that field:

WeakReference<byte[]> watch = new WeakReference<>(pixels);
pixels = null;
image.nullifyUncompressedPixels();   // the image releases its own cache
collect();
assertTrue(watch.get() == null, "GeometrySpec must not hold a second reference ...");

theImagesOwnCacheStillPinsThePixels is the negative control for the control — it asserts the
array is not collectable while the image still caches it. Without that, a test which always passed
because nothing ever retained the array would look like a working fix.

Verified the suite detects the defect. With the old caching field restored:

geometrySpecDoesNotPinTheInflatedPixels
  GeometrySpec must not hold a second reference to the image's inflated pixels
  ==> expected: <null> but was: <[0, 1, 2, 0, 1, 2, ...]>
Tests run: 5, Failures: 1

The other four passed. That failure also exposed a usability problem worth fixing: assertNull
rendered the whole 64,000-byte array into the message — 375 KB of output burying the actual
assertion — so the two reachability assertions now use assertTrue on an explicit comparison.

A note on the diff

GeometrySpec.java is CRLF (1445 CRLF lines, no bare LF). My first edit went through Python's
text mode and silently rewrote every line ending, turning a 10-line change into a 2900-line diff.
Redone in binary mode; git diff --stat now reads 18 insertions / 7 deletions, which is what it
should have been.

Verification

• GeometrySpecPixelRetentionTest: 5/5.
• MathGen_IT: 1045 tests, 0 failures, 0 errors — 705 math-generation comparisons over real
  stored VCML. Re-run clean after the binary-mode patch; an earlier run was recompiled mid-flight
  and discarded rather than reported.
• vcell-core Fast: 580 run, 0 failures, 8 errors — the MathOverrideRoundTripTest /
  VCellDataTest errors docs/BUILDING.md documents for a worktree without the Poetry
  environments.

Relationship to the other branches

This stands on its own — it removes a redundant reference to a 62 MB array. It is also a
prerequisite for #2025 §5.3b: making VCImageCompressed.uncompressed a SoftReference would
do nothing while a second strong reference pinned the array regardless.

Unlike #2022 / #2023 / #2024, this one is small, self-contained, and does not depend on any of the
decisions still open in #2025.

Refs #2021, #2025

🤖 Generated with Claude Code

https://claude.ai/code/session_018kr8SbzXtwW3gMVUgMfDDt