[trissim]

Critical cache checkpoint

Refs OpenHCSDev/openhcs#224 and OpenHCSDev/openhcs#206; extracted at the owner's explicit request from #16. This is the same implementation on recorded/current PolyStore main f94bbbe, not a competing runtime or compatibility path. Original Java-lifecycle and ROI work stays in16. Parent will pin this exact commit and owns review/merge/install.

Paired parent: OpenHCSDev/openhcs#228 at bf9aae4620585e98d10e469037ef98237884b4f8; its committed gitlink is this exact head c16b8fc99a07f17e92e5fbf46f312d73cc9c46d7.

Existing FijiArchiveDistribution owns POLYSTORE_IMAGEJ_CACHE_ROOT and decodes it once into the canonical distribution's constructor. Use the existing bundle parent /home/ts/.cache/polystore/imagej, not its hashed Fiji subdirectory. Unset preserves platformdirs behavior; invalid explicit roots fail. Separate XDG logs/caches stay separate; release/digest/overlay, archive verification and atomic materialization remain canonical.

Existing ImageJArchiveDownloadPolicy owns POLYSTORE_IMAGEJ_ALLOW_DOWNLOAD=true|false (unset retains its existing defaults). False rejects absent/invalid bundles before cache creation, lock/staging/removal or network, and rejects archive/overlay downloads before retries or temporary files. It still admits a valid existing bundle. No caller subclass/monkeypatch, symlink or shared-full-cache workaround required.

Actual evidence

• Current-main paired source: 36 passed in5.14s, peak driver RSS277712KiB, available RAM14.4GiB before/13.96GiB after.14 cache/policy cases +17 existing distribution cases +5 parent launch/progress/binding cases. Import paths verified under the new persistent source checkout, existing Python3.12 environment, OpenHCS imported before collection; no plugin/global-conftest bootstrap changes.
• Two fresh native Python processes against the actual existing859MiB bundle, separate XDG roots, production download policy false, identical native Fiji/Java paths, zero new cache entries/no JVM/no downloads. No override or fixture in this proof. Reproducer lives in paired parent scripts/verify_existing_imagej_bundle.py.
• Ruff and whitespace checks pass for touched child source/tests and parent tests/proof. Historical swap warning remains; no heavy lock/runtime/process/GUI takeover or installed source changes.

Focused architecture review

BOUND-1/2/6: external environment decoding belongs on the existing distribution/download-policy owners, not each consumer; canonical FIJI declaration projects constructor values once. MEMB-2/3: parent launch derives both key spellings from these owners; no duplicate default/filename/runtime registry. IMPL-12/13: extend the existing materializer/policy and parent progress binding, not a second cache or cold-start runner. New cache root requires one owner input, no BioFormats/viewer consumer edits; new download permission is decoded/enforced on the policy, not callers. Strict two-value environment decoding is boundary validation, not a missing runtime family. Scope is changed-source/catalog and behavioral checks, not a full NRA/native/global proof.

Remaining gates

Real installed stdio MCP inspection + concurrent discovery and heartbeat during actual Java preparation remains parent-owned and resource-gated. No claim of installed readiness or closure. Original16/206 combined result 141 passed/26 failed remains unresolved there; after-ROI profile did not run. Those preparation/ROI changes are not in this small checkpoint. Original uncertain science receipts/foreign handles untouched. No merge/install by this worker.