Add optional mapped scratch storage for flat ink inference

[Kotoro78]

In one sentence: Flat ink inference can use optional memory-mapped scratch storage to trade some host RAM for a shorter inference call, while keeping Zarr as the default.

Motivation: I've been evaluating the cost of running ink inference on complete public scroll surfaces. We compared scratch storage options on three PHerc0139 surfaces to see whether there was a useful saving without changing the model or its predictions. The gain is modest, but it may be useful when running repeated inference on a machine with spare RAM.

One real example: On the complete PHerc0139 w043 surface (6,120 × 8,120 output pixels), the recorded L4 comparison produced identical decoded predictions with default Zarr, uncompressed Zarr and mapped scratch.

Before: The complete inference call took a median 74.125 s with default Zarr, or 72.976 s with uncompressed Zarr.

After this PR: --scratch-backend memmap selects two mapped float32 accumulation planes. The historical mapped implementation took a median 69.707 s on that surface, with a 4.67% paired median reduction versus uncompressed Zarr and about 380 MiB more root RSS. The two other surfaces showed 4.42% and 5.00% reductions, with about 378–415 MiB more RSS. GPU memory use was unchanged.

Proof: Real-data observations, inputs/settings, pixel checks and validation records. There were three timed repeats per arm and surface; all 27 timed outputs matched exactly. These September 9 timings predate the final constructor/cleanup revision, which has not been rebenchmarked on L4. They are not new timings of today's main.

Why / where this is useful: Users running repeated flat inference with spare host RAM can choose this time/memory tradeoff. Scratch disk usage is 8 * height * width bytes. This is an integration of established memory mapping into this command, not a new inference algorithm.

• I personally verified that the example and proof above were produced by this PR on the stated data.

Details

The diff contains the optional backend and ten storage regression tests. Reads return copies because TIFF normalization modifies its input. Mappings close before temporary-directory removal, including initialization and encoding failures. Accumulation order, dtype, model calls and encoding are unchanged.

The publication base is 757f70c0140a4cfbbbd44975ef09558444b96980; its target source is unchanged from the reviewed baseline. The final standalone CPU checks on September 13 passed 25 baseline tests versus 44 candidate tests plus five subtests under Python 3.14.7 with both Zarr 2.18.7 and 3.3.0. The evidence includes the additional integration harness and distinguishes its synthetic correctness fixtures from the real-data performance comparison.

We also tested both arms with the separately authored PR1698 and PR1773, at the revisions pinned in the evidence: 74 baseline tests; 93 candidate tests plus five subtests, passing with both Zarr versions. Those fixes address inherited input-read and padding-normalization problems. Neither is included here, and this scratch change does not fix those problems.

All three measured surfaces belong to one scroll. No prediction-quality improvement, external adoption or speedup on untested hardware is claimed.

I have personally reviewed the code and the evidence. AI tools assisted with implementation, testing and this description.

[vercel]

@Kotoro78 is attempting to deploy a commit to the scroll Team on Vercel.

A member of the Team first needs to authorize it.