docs(geometry): consolidate the geometry-memory incident, measurements and options

[jcschaff]

Planning document, deliberately not a fix.

The 2026-08-22 prod OOM produced three prototype branches in quick succession, and the understanding
changed three times while they were being written. That is the signal that this needs planning
rather than merging, so #2022, #2023 and #2024 are now drafts and this document is where
decisions should happen.

What it contains

• §1–2 what happened, and the root cause: Xmlproducer:1416 writes the complete <Geometry> —
  image included — inside every <SimulationContext>, so 11 applications means 11 decodes and
  ~680 MB of retained pixels against a 1000 MB heap.
• §3 every measurement, with the instrumentation that produced it — parse cost by sharing mode,
  RegionImage scaling, a heap class histogram, a comparison against scipy.ndimage.label /
  cv2.connectedComponents, the pixel-class experiment, and the prod duplicate-row queries.
• §4 what we got wrong. Four beliefs that were acted on and then disproved, two of which
  reached open PRs.
• §5 nine options, each with what it buys, what it costs, and what is unresolved.
• §6 the open questions that block implementation.

The correction that matters most

XML read does not rebuild surfaces. XmlReader:2086 assigns the parsed surface description to a
variable named dummy, which reads like the stored surfaces are thrown away — but the method
mutates the geometry it is passed and only the return value is discarded. So
getGeometricRegions() is non-null and precomputeAll skips updateAll() entirely.

The incident was eleven image decodes and eleven retained pixel arrays, not eleven surface
rebuilds. That matches both the measured 661 MB and the ~370 ms spacing of the prod warnings —
hex-decode-plus-inflate time, not the ~1.1 s a 62 MP RegionImage takes.

Also recorded: a pixel-class limit was implemented, measured and abandoned (memory is flat in
class count; region count is the predictor); enforcing the image-size veto on the load path would
have made BioModel 101963252 — the very model from the incident — impossible to open; and the first
duplicate-row query over-matched by 13×.

Two things that are ready to act on independently

• Prod has ~944 surplus image rows from same-save duplication, confirmed with a 1:1
  image-row-per-referencing-geometry signature, and still accruing (October 2025).
• The trigger is crawler traffic. A robots.txt or rate limit on the legacy api removes it
  without touching geometry code.

Not decided here

Both limits in the #2022 prototype (16 M px, 2,000 regions) are calibrated against today's
implementation, not against what the science needs. §6 lists the read-only queries that would
replace those guesses with data.

Supersedes docs/geometry-memory-notes.md from #2023.

Refs #2021, #2022, #2023, #2024

🤖 Generated with Claude Code

https://claude.ai/code/session_018kr8SbzXtwW3gMVUgMfDDt

[jcschaff]

Updated for §5.3b being built (b87d1ce026).

New §3.9 — the end-to-end check that §3.7's compression arithmetic actually changes the outcome.
11 images, 300³ each, 256 MB heap:

	result
soft cache OFF	OUT OF MEMORY after 9 of 11 images
soft cache ON	completed all 11

Heap drops 246 MB → 63 MB at image 10 as the collector reclaims, then 283 MB of pixels are re-read
on demand. The incident and its fix in one run.

§5.3b rewritten as built — #2026 (removes the second strong reference) and #2027 (the
SoftReference itself, stacked on it). Both open, neither merged.

I was deliberate about what the section does not claim, because the heading alone would overstate
it:

• VCImageUncompressed still has no compressed form, so the sampled image is still held
  strongly — derived rather than stored, so a different problem.
• The per-pixel path is unchanged. The loops that could see a compressed image were hoisted;
  getPixel(x,y,z) and isInside still fetch per call. Cold today, a problem only if either
  becomes hot.
• The label array is untouched — that is §5.3, and still the largest single retained object.

Also corrected two places in §3.8 that still read as open, added a state column to the branch table
now that drafts and open PRs are mixed, and expanded the repro commands to include
SoftPixelCacheDemo (it needs its own -Xmx, so it does not go through exec:java).

The sequencing question in §6 is still open — §5.3b and §5.1 are independent of each other and of
the format question in §5.2.