🤔 Why?
RemotePFS already compiles the complete virtual directory tree before activation, but it only performs one metadata warm-up pass. Host directory listing should not wait for the first read of each boot, FAT, allocation bitmap, or directory sector.
The current preload range is derived from eagerly stored metadata. FAT and allocation bitmap sectors are generated lazily, so they are not fully included in the warm-up set. There is also no bounded background refresher for the active generation.
This affects first-list latency and can reappear after nbdkit cache eviction. It is separate from file timestamp encoding in #1.
🔧 High-level plan
- Inventory all host-visible metadata for each immutable compiled generation: boot/GPT regions, up-case table, root and nested directory clusters, FAT sectors, and allocation bitmap sectors.
- Extend hot-range calculation to include lazily generated FAT and bitmap ranges without materializing giant metadata blobs in memory. Coalesce adjacent ranges and keep reads bounded.
- Preserve one complete preload pass before NBD/USB activation. A preload failure must prevent binding an incomplete generation.
- Add a bounded background metadata refresher that rereads the active generation's hot ranges through nbdkit at a controlled interval. Use a stop event and one worker per active generation.
- Stop and join the old refresher before reload, eject, shutdown, or generation replacement. Never mutate metadata or mappings in place while a host is attached.
- Keep metadata snapshots immutable. Source changes require a new compile and explicit activation, not an in-place rescan.
- Document metadata that exFAT cannot represent directly. File sizes already belong in stream entries; POSIX permissions, uid, and gid must not be invented as exFAT attributes.
✅ Acceptance criteria
- First host directory listing sees all boot, FAT, bitmap, up-case, and directory metadata already warmed.
- Lazy FAT and bitmap sectors are included in preload coverage without expanding a large FAT or bitmap into RAM.
- Background refresh runs at a bounded cadence and can be stopped promptly.
- Reload and shutdown leave no refresher thread or subprocess using old mapper state.
- Failed initial preload does not bind an incomplete USB generation.
- Active generation remains immutable while serving a host.
- Tests cover hot-range completeness, range coalescing, preload commands, worker cancellation, reload lifecycle, and failure handling.
- Live validation measures host listing latency before and after warming, while confirming file contents, sizes, read-only behavior, and exFAT integrity remain unchanged.
⚠️ Scope boundary
This issue covers metadata availability and cache warming. It does not add POSIX permission emulation, change source selection, or alter the read-only contract. Timestamp encoding remains tracked in #1.
🔗 Related issues
🤔 Why?
RemotePFS already compiles the complete virtual directory tree before activation, but it only performs one metadata warm-up pass. Host directory listing should not wait for the first read of each boot, FAT, allocation bitmap, or directory sector.
The current preload range is derived from eagerly stored metadata. FAT and allocation bitmap sectors are generated lazily, so they are not fully included in the warm-up set. There is also no bounded background refresher for the active generation.
This affects first-list latency and can reappear after nbdkit cache eviction. It is separate from file timestamp encoding in #1.
🔧 High-level plan
✅ Acceptance criteria
This issue covers metadata availability and cache warming. It does not add POSIX permission emulation, change source selection, or alter the read-only contract. Timestamp encoding remains tracked in #1.
🔗 Related issues