Native image prewarming memory policy

本页保留当时的验证结论，不代表当前完整平台能力。当前状态见项目进展，运行时说明见JavaScriptCore。

The earlier image cache had a fixed 256 MiB resident target. Its encoded-byte and job-count limits did not account for decoded pixels, mip generation, completed GPU results, or memory used by the rest of the process.

Native windows now start with speculative preparation disabled. A dedicated sampler reads total/available system memory and the current process once per second, including while the window is idle or hidden. macOS uses the larger of RSS and physical footprint, and also checks OS memory pressure. This runs independently of the editor performance monitor and does no OS sampling on the render thread. Missing samples, samples older than three seconds, or failed monitor startup disable prewarming.

The policy reserves max(256 MiB, 10% RAM) for the OS/other applications and uses min(2 GiB, 25% RAM) as a whole-process policy target. Half of the smaller remaining system/process headroom can fund image work, bounded to 1/16 RAM and 512 MiB combined. That allowance is split between resident images (maximum 256 MiB) and preparation (maximum 256 MiB). For example, a 2 GiB machine with 1 GiB available and a 200 MiB process gets 64 MiB residency plus 64 MiB preparation. At 400 MiB available and 450 MiB process usage, each allowance falls to 12 MiB. Pressure or exhausted headroom sets both to zero.

Shrinks apply on the next sample: stop speculative admission, cancel queued/background work and evict inactive images. Active projection images remain pinned, including with a zero cache budget. Recovery requires three consecutive samples with more headroom, then increases each allowance by at most 32 MiB per sample. Budget generations let an unchanged script window rewarm evicted images. Sampler wake-ups perform idle cache maintenance without continuously rendering.

Before copying an encoded image into the worker, header inspection estimates encoded copies, codec/RGBA scratch, mip generation, GPU mip chains and queue staging. All asynchronous jobs together are bounded to a 512 MiB estimated preparation peak; speculative work must additionally fit the current preparation allowance and the combined allowance alongside resident images. Cancelled queued/running work stays charged until the worker drops it, and completed GPU results remain charged until adoption/release. Cancellation is checked again before GPU upload. The in-memory QPK Host shares immutable bytes for header inspection, avoiding an asset-sized copy before admission. Oversized deferred hints are not repeatedly read and do not starve smaller hints later in the window.

These are resource policy targets and conservative payload estimates, not a hard process-memory or driver-allocation cap. Existing active images, mounted QPKs, JavaScriptCore, audio, fonts and compositor resources keep their own lifecycles. OS accounting and GPU reclamation may lag. A single in-progress decoder cannot be interrupted mid-call; its reservation remains live until completion. No test deliberately exhausted the machine's memory.

Validation

• Combined Cargo regression: 906 WGPU renderer tests, 309 native app tests, 14 CLI tests and 89 native runtime tests passed with real-wgpu-noop, native-window, native audio and JavaScriptCore enabled. New tests cover system/process pressure, stale samples, recovery hysteresis, pinned images, peak admission, cancelled/finished reservations, shared Host bytes and unchanged-window recovery.
• A further focused regression passed and checks that a deferred large hint leaves the scheduler alive to visit smaller hints, then returns to idle.
• After tightening cancelled-result drop ordering, all 79 device tests passed again. Rust formatting checks passed for the new policy, preparation and scheduler code.
• Actual macOS memory sampling passed; Demo startup recorded 64 GiB total RAM, approximately 33.9 GiB available and a 37.5 MiB process sample before QPK initialization. This is a startup observation, not a peak-process measurement.
• Real Metal preparation, active-image retention, retired-image release and recovery are recorded in raw measurements. The benchmark also keeps an outgoing full-size image resident while preparing the next one. On Apple M5 Max / Metal, a 3840x2160 RGBA PNG kept a 42.19 MiB outgoing image resident while reserving 230.29 MiB for preparation. All three fixtures retained the active image at a zero budget, released image residency to zero after retirement, and successfully prewarmed again after recovery. These are texture payload/peak estimates, not measured whole-process peaks.
• Complete Demo E2E rebuilt the QPK and native app and reached the title. Logs confirmed the live memory policy and opening background preload. macOS again returned OccludedAfterRetry at the title checkpoint; full visible-window E2E and subjective transitions remain unverified. Capture: demo/dist/native/dev/e2e-checkpoints/title-menu.png. Unchanged TypeScript package builds were reused via the existing fast-rebuild option.
• git diff --check passed. Cross-platform Windows/Linux OS sampling was not exercised on this Mac.