Store a cloned snapshot of the ladder — full or prefix — with
UPGRADE-IF-LONGER semantics: an existing entry is replaced only when the
new snapshot carries MORE logical levels (never downgraded; the depth check uses
a non-counting peek so bookkeeping never perturbs the hit-rate stat).
Callers gate WHEN to store (the loaders store prefixes only while a
playback frame budget is active, or any time the ladder is complete —
storing every refinement pass would clone O(N²) bytes per slice).
MEASURES bytes before cloning and skips oversized snapshots entirely
(the LRU would silently reject them after an expensive copy). Shared by
all three progressive loaders.
opts.ladderDepth — the logical prefix depth when payload count differs
from level count (the Lines loader folds committed rungs cumulatively).
opts.scan — the caller is storing inside a sequential scan (dimension
playback; the loaders pass their per-pass frameBudgetMs !== null).
Forwarded to SliceCache.set to select scan-resistant (MRU-victim)
eviction, which keeps the loop-head prefix resident across cyclic loops.
opts.pin — the caller is the SlicePrefetcher storing a projected t+1
ladder; forwarded so the entry survives eviction until the foreground tick
restores it (see SliceCache.set).
OVERSIZED LADDERS: when the full snapshot exceeds the whole cache budget the
cache would reject it wholesale, leaving that slice permanently uncacheable
(it re-decodes on every visit). Instead we store the largest COARSE-FIRST
prefix that fits — the additive ladder is amplitude-ordered, so the coarse
levels are the cheapest to keep and give a usable partial revisit; only the
fine tail re-decodes. A one-time warning per node surfaces the shortfall
(deduped by the cache's markOversizedWarned, so it can't leak across
sessions or a dataset switch). Folded payloads cannot be trimmed safely
because payload count no longer identifies level count; those leave any
existing shorter entry intact. If the cumulative payload itself exceeds the
budget, the folded slice is not cached and re-decodes on every revisit.
Store a cloned snapshot of the ladder — full or prefix — with UPGRADE-IF-LONGER semantics: an existing entry is replaced only when the new snapshot carries MORE logical levels (never downgraded; the depth check uses a non-counting
peekso bookkeeping never perturbs the hit-rate stat). Callers gate WHEN to store (the loaders store prefixes only while a playback frame budget is active, or any time the ladder is complete — storing every refinement pass would clone O(N²) bytes per slice). MEASURES bytes before cloning and skips oversized snapshots entirely (the LRU would silently reject them after an expensive copy). Shared by all three progressive loaders.opts.ladderDepth— the logical prefix depth when payload count differs from level count (the Lines loader folds committed rungs cumulatively).opts.scan— the caller is storing inside a sequential scan (dimension playback; the loaders pass their per-passframeBudgetMs !== null). Forwarded toSliceCache.setto select scan-resistant (MRU-victim) eviction, which keeps the loop-head prefix resident across cyclic loops.opts.pin— the caller is the SlicePrefetcher storing a projected t+1 ladder; forwarded so the entry survives eviction until the foreground tick restores it (seeSliceCache.set).OVERSIZED LADDERS: when the full snapshot exceeds the whole cache budget the cache would reject it wholesale, leaving that slice permanently uncacheable (it re-decodes on every visit). Instead we store the largest COARSE-FIRST prefix that fits — the additive ladder is amplitude-ordered, so the coarse levels are the cheapest to keep and give a usable partial revisit; only the fine tail re-decodes. A one-time warning per node surfaces the shortfall (deduped by the cache's
markOversizedWarned, so it can't leak across sessions or a dataset switch). Folded payloads cannot be trimmed safely because payload count no longer identifies level count; those leave any existing shorter entry intact. If the cumulative payload itself exceeds the budget, the folded slice is not cached and re-decodes on every revisit.