fix(geometry): limit NEW geometry images, grandfather the ones already stored

[jcschaff]

Fixes #2021 — a 61,920,000 pixel image terminated two prod api pods with
OutOfMemoryError because GeometrySpec.vetoableChange detected it and only logged.

The obvious fix would have been worse than the bug

Uncommenting the throw looks like a one-line change. It isn't:

XmlReader:2006   new Geometry(version, newimage)
  -> GeometrySpec(Version, VCImage)
    -> setImage()
      -> vetoableChange()          <- the veto fires here
    -> catch (PropertyVetoException e) { throw new RuntimeException(...) }

The veto also fires when deserializing saved geometries. Restoring enforcement at the
historical IMAGE_SIZE_LIMIT of 4,000,000 would have made every stored geometry above that size
fail to open, with a RuntimeException.

And 4,000,000 is small: 159³ in 3D, or 2000×2000 in 2D. That is almost certainly why the line
was commented out in 2017 rather than fixed — enforcing it rejects real models.

What this does instead

The enforced ceiling is separated from the historical constant:

	value	behaviour
IMAGE_SIZE_LIMIT	4,000,000	unchanged, kept for callers — now only warns
IMAGE_SIZE_LIMIT_DEFAULT	50,000,000	enforced, overridable via vcell.geometry.imageSizeLimit

50,000,000 is deliberately just below the size observed to kill a JVM, not an ideal value.
That is the property that makes this safe: anything it rejects would have crashed the JVM anyway,
so no geometry that opens today stops opening — while the case that took out two pods is now
refused with a message naming the actual size, the limit, and the property to raise.

Refusing one geometry beats killing a pod that is serving everyone.

The number should be lowered once someone surveys the image sizes actually present in the database;
it is a property precisely so that does not need a code change.

Tests

GeometrySpecImageSizeTest, 4 cases. The important one is the middle:

@Test
public void imageOverHistoricalLimitButUnderCeilingIsStillAccepted() {
    // 200^3 = 8,000,000 -- twice the historical limit, well under the ceiling.
    // Enforcing the historical value here would break saved models.

That is the regression guard against the naive fix, not against the original bug.

The suite was verified to detect the defect, not merely to pass. With the 2017 behaviour
restored:

imageOverTheCeilingIsVetoed:62
  Expected java.beans.PropertyVetoException to be thrown, but nothing was thrown.
Tests run: 4, Failures: 1

The other three still passed, confirming they do not depend on the veto.

Wider run

vcell-core Fast: 579 run, 0 failures, 8 errors — all MathOverrideRoundTripTest (×7) and
VCellDataTest (×1), the environmental failures docs/BUILDING.md documents for a worktree
without the Poetry environments installed. One of them reports the poetry deprecation as its own
cause. Nothing geometry-related failed; VCImageTest passed all 3.

Not included

The limit value itself needs a real answer, and this PR does not pretend to have one. 50 M is
"safely below the thing we watched explode." Someone with database access should check what sizes
exist, then set the property accordingly.

Fixes #2021

🤖 Generated with Claude Code

https://claude.ai/code/session_018kr8SbzXtwW3gMVUgMfDDt

[jcschaff]

Reworked after Jim's direction that existing geometries must keep loading and only new submissions should be limited. Force of that point: the 50 M ceiling in the first commit would have broken the very model from #2021 — BioModel 101963252 is 61,920,000 px and loads today. vetoableChange fires on deserialization, so any enforced ceiling there makes stored models unopenable.

Now: load path warns only; limits are enforced at ServerDocumentManager.saveGeometry / saveBioModel / saveMathModel, keyed on image.getKey() == null. Anything already in the database is grandfathered forever — which is what lets the limit sit at a value the api can actually serve.

The second limit is on regions, not pixel classes. I implemented the 16-class limit as discussed, then measured it and abandoned it. 256³ volume, one subvolume per concentric shell, regions only:

pixel classes	2	4	16	32	64	128
regions	2	4	16	32	64	14,050
peak	124MB	196MB	244MB	209MB	300MB	1,652MB

Memory is flat in pixel-class count — 64 subvolumes is unremarkable. The jump at 128 isn't the class count: those shells fall below one voxel thick and fragment, and it's the 14,050 regions that cost 1.65 GB. A 16-class limit would have rejected the cheap 64-subvolume case and still admitted a fragmented 2-class one — measured separately, a random 2-class image costs 2,111 MB at under 1 MP.

Region count is also the better test for "was this ever segmented", and it's free: the geometry already computed a RegionImage while parsing.

Also confirms your point that N binary passes wouldn't blow up — VCell's labelling already doesn't scale with class count.

Defaults: vcell.geometry.newImageSizeLimit 16,000,000 px, vcell.geometry.newImageRegionLimit 2,000. The size figure is about today's implementation (152 MB at 4.1 M px → 1,431 MB at 62.1 M, vs a 1000 MB heap), not about the science — raise it once the memory work lands.

[jcschaff]

Converted to draft. Superseded for now by the planning document in #2025, which records that this branch's approach was corrected twice: the original load-path veto would have made BioModel 101963252 — the model from the incident — impossible to open, and the pixel-class limit was measured to be the wrong quantity (memory is flat in class count; region count is the predictor). Both limits still in here are guesses calibrated against today's implementation. Decisions in #2025 first.