Web: no test measures that a large map delivery holds flat memory

[timohueser]

Current work — 2026-09-16

Prerequisite #1668 / PR #1672 is complete after independent adversarial review and green CI. The browser now carries the admitted storage mode from a matching estimate into the run. Required disk-backed input, output or scratch failures refuse the run before fallback buffering. Stale estimates cannot admit another selection. Actual worker-handler and component contracts cover these boundaries; they are not memory measurements.

The empirical requirement remains open. The earlier 2026-09-13 browser-worker experiment used 206.61 MiB of pinned input and 206.36 MiB output, with 50.56 MiB of WASM linear-memory capacity against a 130.8 MiB estimate at a 16 MiB sort budget. These are historical measurements of that configuration, not current-head memory acceptance. They do not measure JavaScript heap, browser RSS or UI-default memory, and they do not provide a registered regression gate.

The cache default has since changed in #1781 / #1792: 4 KiB input blocks and separate 64 KiB verification blocks. Exact output, refusal checks, memory accounting and pinned performance evidence support that change; they do not close this empirical memory requirement. Use the current configuration when measuring total browser memory. #1162 owns country-scale native/browser performance; #1420 owns large-map delivery and device acceptance.

---

Parent epic: #1449 (evidence gap named while closing section D's streaming-memory bullet)

The gap

Nothing in the repository measures that delivering a large map holds flat memory. The guarantee rests on a model.

Until 2026-07-31 it rested on a measurement. builder/app/src/lib/device/memory.test.ts drove the real sendCatalogMap pipeline over TOTAL = 300 * 1024 * 1024 bytes and watched the process heap; its header stated the claim it existed for:

The claim #903 refuses to take on faith: memory during a 300 MB map upload stays flat.

It was deleted in 026c8248 ("refactor(maps): cut over to the cell catalog", #1047), together with the sendCatalogMap path it drove. Nothing replaced the measurement, because the cell-catalog architecture answers the same question a different way:

• builder/app/src/lib/assemble/bridge.test.ts's estimateMemory group asserts that DACH fits the sunk path and is refused resident, that the engine is priced by the sort budget rather than the selection, and that the no-OPFS fallback honestly refuses a country.
• builder/app/src/components/coverage/DownloadStep.svelte.test.ts covers the mandatory preflight that consumes that estimate.

Both are arithmetic over the wasm estimator. They allocate nothing and run sub-millisecond.

Why that is not the same evidence

A modelled budget and an empirical heap measurement are different classes of evidence. The current tests prove that the estimator says the right thing and that the preflight obeys it. They cannot fail if the implementation buffers a whole map while the model says it should not — the estimator would still return its number, the preflight would still gate on it, and every assertion would still pass.

So the property "a large map delivery holds flat memory" is currently unasserted. That is a coverage question, not a cost question.

Why it is not part of TS4b

TS4b (#1502) is a cost-reduction slice. It closed the section-D bullet as no current subject — correctly, because the suite the bullet named is gone — and naming this gap was in its scope. Filling it is not: the pipeline the old test drove no longer exists, so a replacement is new test design against the assembler and the OPFS store, at a level (real browser, or a host harness with a real heap) that the epic's sections E and F are about. Folding new coverage into a slice whose success criterion is a smaller runtime is how a cost slice quietly becomes a feature slice.

What a replacement has to decide

1. Where it runs. happy-dom under vitest has no OPFS and no honest heap. A real-browser level (section E) or a Node harness driving the assembler directly are the two candidates.
2. What it watches. process.memoryUsage().heapUsed was the old probe and it is not available in a browser; performance.measureUserAgentSpecificMemory() is, behind cross-origin isolation.
3. What "flat" means. The old test asserted against a fixed ceiling over a fixed payload. The cell catalog's working set scales with the sort budget, so the claim needs restating before it can be measured.
4. What it costs. The old test moved 300 MiB in ~4 s. Section D's own policy says a large throughput or memory assertion belongs in a performance suite, not in the required per-PR tier.

Definition of done

A test at some level fails if a map delivery buffers materially more than the estimator says it will, and the registry entry that owns it declares the tier it runs in.

[timohueser]

Reviewed browser experiment — 2026-09-13

One baseline and one diagnostic comparison used the actual Chromium worker, sync OPFS input/output/scratch, and a 16 MiB sort budget. Independent adversarial review checked the saved harness, manifests, logs, memory capture and streamed output digests. No production cache setting changed.

Pinned inputs: 40 published Baden-Württemberg catalog objects, snapshot 2026-08-19, 216,642,112 bytes. Worker source: a4cfe85848c948cda2798971a545eac764cb1139. Generated WASM SHA-256: 33d37102f9049ab373a96fe0818e9f81370528e8cf5eefc2a519316c4552fb69. The generated package came from 2f623fb4; the relevant producer and assembler trees match. This is not a measurement of the later rain-band validation change.

Measurement	64 KiB baseline	512-byte comparison
WASM linear-memory capacity	50.5625 MiB	53.25 MiB
Estimated working memory	130.8 MiB	130.8 MiB
Input bytes read	101,569,457,776	98.76% fewer
Output verification read calls	30,325	1,768,750
Request through independent digest	16.503 s	14.967 s

Both outputs are 216,385,024 bytes with SHA-256 2262b1d3b95ee6d74efa310466232be9c288e49fc9c50029ec4f161318bcadff. Full verification passed: 97,758 chunks, 4,962,358 features, 903,794 navigation nodes and 1,176,117 edges. Material 4 MiB sort runs and 539 MB of scratch writes establish a real spilled navigation workload.

The wrapper captured the assembler's actual exported Memory before worker initialization, then read its fresh final buffer. WASM capacity only grows, so this bounds that worker's linear memory. It does not bound JavaScript heap, tab RSS, or the UI's 256 MiB sort-budget case. It is not a registered regression test or country-scale acceptance. The elapsed comparison is one diagnostic pair, not a controlled general benchmark.

Retain the shared 64 KiB default. The 512-byte option cuts input traffic but causes 58.33 times as many verification reads and 5.32% more WASM memory, for a 9.31% elapsed reduction. Further work must distinguish input and output access patterns. #1503 and #1162 remain open for their wider requirements. Small reproducible manifests, harness files, logs and results are retained in the session handoff artifact; no permanent harness or tuning sweep was added.