[lvcabral]

Closes #1252

Problem

cachefs: was emptied on every launch. Its buffer was allocated inside the app worker (BrsDevice.getCacheFS()), and both hosts throw that worker away on every run. On a device, cachefs keeps its contents until a reboot or until the space is needed.

Change

• The browser API (src/api/index.ts) and Node executeApp (src/node/host.ts) hosts now own the cachefs SharedArrayBuffer and pass it to each app worker as DeviceInfo.cacheFSBuffer. Task threads already mount the app's buffer, so they needed no change.
• One volume for all apps: the host keeps a single cachefs: volume that every app it runs shares, whatever its developer ID. It is replaced with an empty one only when cacheFSVolSize changes. Reloading the page or exiting the process acts as the reboot. This is a deliberate difference from a device, which keeps cachefs per developer ID (file-system.md). Switching developer ID on a device is rare, and hosts that give each app its own developer ID (e.g. brs-desktop's "Registry by App") would otherwise hide one app's cache from another.
• tmp: is still emptied on every launch.
• Browser integrators can't inject cacheFSBuffer (it's added to invalidKeys). Both hosts share one getCacheVolume helper in core/common.ts.
• Compaction on launch: on app launch, before any Task thread exists, BrsDevice calls FileSystem.compactCacheFS before mounting. It always clears a metadata write lock left by a worker that was hard-terminated mid-write. Without that, the next launch would block forever in Atomics.wait. zenfs SingleBuffer allocates by bumping and never reclaims space when a file is rewritten or deleted. So once that wasted data reaches a quarter of the volume, the volume is rebuilt from its live files, and only the used part of the buffer is zeroed. A fresh volume is not compacted at all. If the buffer can't be read, the volume starts empty, like a device eviction. Task threads only mount the volume, so they never reset it.
• Eviction when full: the same launch-time pass also rebuilds the volume when it is over 75% full. It evicts the least recently modified files (only then; reclaiming wasted space alone keeps every file) until it is back to half, which is how a device frees cache space. Kept files keep their modification times, so later launches evict in the right order. Eviction only happens at launch. While an app runs, a write that doesn't fit fails with ENOSPC, and the app sees false. Unreadable entries are dropped one by one instead of wiping the volume.
• Memory volumes (tmp:, cachefs:) use a MemoryVolume backend:
  • Space guard in the store: its SingleBuffer store rejects an allocation that doesn't fit (ENOSPC) before reserving any space. zenfs reserves space before copying the data, so one oversized write used to leave the volume unable to take any further write. Because the guard sits in the store, it covers every path: file writes, mkdir and the compaction restore. A rejected write leaves no file behind.
  • File name case: the volume keeps names as written and matches them regardless of case, as on a device. zenFS case folding now applies only to common:/pkg:. This replaces the per-thread original-case map, so names keep their case across threads and launches.
• Renames: a rename within the same volume is native, so a case-only rename (a.txt → A.txt) keeps the file instead of deleting it.
• brs-cli runs one app per process, so it still starts with an empty cachefs: on every run.

Device behavior

• Confirmed on a device: re-sideloading a dev channel does not clear cachefs. This matches the engine, where re-running an app keeps the volume for the session.

Tests

• test/node/host.test.js: two executeApp runs in one process. The second run, under a different developer ID, sees the cachefs: file, and tmp: is empty again.
• test/interpreter/FileSystem.reliability.test.js: files and directories survive a relaunch; a corrupted buffer mounts empty while common: still works; a stale write lock no longer hangs the next launch; rewriting a 400 KB file over 5 launches fits in a 1 MB volume; with five 180 KB files in a 1 MB volume, the next launch keeps only the newest two, and a launch after that evicts nothing more; a write too large for the volume leaves no file behind and later writes still work; reclaiming wasted space keeps files that fit; file name case survives a relaunch, lookups ignore case, and a case-only rename keeps the file. I checked that the last two fail without compaction: the launch hangs, and the write fails with "offset is out of bounds".
• npm run lint is clean. Full npm test passes: 238 files, 3185 tests.

Known limitations

• A file being written when the app is terminated can be left half-written.
• A full volume rejects writes that don't fit for the rest of that run. Space freed by deleting or rewriting files only comes back at the next launch. Evicting during a write, as a device does, would mean rebuilding the buffer while Task threads have it mounted. This is documented in docs/limitations.md.

Browser repro (issue example)

Ran markwpearce/brighterscript-game-engine examples/loading (Remote assets scene) in the example web app built from this branch:

1. First launch: every asset reports network (loaded in 3.1 s).
2. Home, then relaunch: every asset reports cache (0.17 s). There were no requests, which matches a device.
3. Page reload (the simulated reboot): every asset reports network again.

🤖 Generated with Claude Code

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud