Fix slow shader file watch on Windows

[jonstvns]

Shader watch: bulk directory scan and cached enumeration

Branch: shader-watch-bulk-scan in external/cute_framework, 6 commits on beebd946.

Problem

• cf_app_update calls cf_shader_watch every frame, throttled to every 16th.
• Each scan cost about 12.5 ms for a 21 file shader directory, on the render thread.
• Cost scaled linearly with file count: 221 files took about 128 ms per scan.
• Every over budget frame in a 2000 frame capture was exactly 16 frames after the previous one, with the simulation paused.

Why it was slow

The scan did three per file metadata queries, and on Windows those are expensive:

• CF_Path::is_directory() was a full PHYSFS_stat.
• fs_stat() was a second one, re-fetching data the first call already had.
• PHYSFS_enumerateFiles does a third one internally. It stats every entry through enumCallbackFilterSymLinks just to drop symlinks from the listing it returns. Confirmed with a counter compiled into PhysFS: 221 stats for a 221 entry enumerate.

Measured on this machine, same directory, 221 files:

operation	cost
bulk directory walk (FindFirstFileW)	1.1 us per entry
per file metadata query (GetFileAttributesExW)	62.6 us per entry

A 56x gap between reading metadata in bulk and reading it per file is the signature of a filesystem filter driver, most likely Defender. Machines without one will see much less dramatic numbers throughout.

What this changes

• Replaces the per file stats with one bulk directory walk per mount, FindFirstFileW on Windows and fdopendir plus fstatat on POSIX.
• Caches the PhysFS directory listing so the remaining hidden stat is only paid when the set of files actually changes.
• Revalidates that cache every scan against two cheap things: a counter bumped by cf_fs_mount and cf_fs_dismount, and one bulk walk per contributing mount reduced to a small signature. Writing to a file changes neither, so editing a shader never re-asks PhysFS.
• Holds the metadata proof across scans instead of re-running it every scan.
• Also watches .vert and .frag, so two file cf_make_shader pairs hot reload. The machinery already existed and the extension filter was rejecting them.
• Adopts files created after cf_shader_directory instead of tripping an assert.

Challenges

• PhysFS has to stay the authority on what exists. Several mounts can serve one directory and only PhysFS knows the merged result. Taking the file list from a walk would silently stop watching any file shadowed by a lower mount.
• Timestamps have to match PhysFS, not be correct. PhysFS on Windows round trips through local time rather than subtracting the epoch. A stored timestamp is compared against whatever the next scan produces, so a divergence would make a file look permanently changed or permanently unchanged.
• Symlink typing has to match too. FindFirstFileW reports the link where PhysFS reports the target, so reparse points are left out of the walk and stated the old way.
• Mapping a mount to its real directory is not exact. PHYSFS_getMountPoint turned out to be public, which makes the mapping right rather than a guess, but PHYSFS_setRoot has no getter. So the mapping stays a candidate that gets proven, and a directory whose contributors cannot all be seen is never cached.
• No periodic refresh. A timer would reintroduce exactly the recurring spike this removes, so staleness is detected from mount changes and per mount walks instead.
• Found a bug in Cute::String(start, end) along the way. It copies length bytes and then claims a length one longer without writing a terminator, so it leaves the string unterminated. Worked around locally, worth fixing separately.

Results

Cost of one scan, 21 files, nothing changed:

	scan cost	marginal cost per file
before	~12.5 ms	578 us
bulk walk instead of per file stats	2.5 ms	74 us
plus cached directory listing	0.58 ms	~3 us
plus cached proof and no per entry allocation	0.26 ms	~2 us

• About 48x cheaper per scan, and about 290x cheaper per file.
• The periodic over budget frames are gone entirely.
• What remains is two directory opens, about 0.1 ms each on this machine. One of them is a mount that has no such directory and has to be re-walked every scan to notice if it gains one.

Possible improvements

• Fix the hidden stat in PhysFS. WIN32_FIND_DATAW.dwFileAttributes already says whether an entry is a reparse point, and POSIX d_type carries DT_LNK. The symlink filter could skip the stat for the entries that plainly are not links. That would make PHYSFS_enumerateFiles fast for every PhysFS user with no behaviour change.
• PHYSFS_permitSymbolicLinks(1) removes the hidden stat today, taking enumerate from 81 us to 2.1 us per entry. Not done here: it is process wide, it drops PhysFS's symlink sandboxing, and it changes which files appear in a listing.
• Wall clock throttle instead of every 16th frame, so the scan rate stops rising with frame rate.
• GetFileInformationByHandleEx with FileFullDirectoryInfo fills a large buffer in one call and could trim the walk itself, though not the directory opens that now dominate.
• A Defender exclusion for the working tree, which is the largest single lever on this machine but helps nobody else.

Testing

Five cases in test/test_shader_directory.cpp, driven through cf_shader_on_changed, which both drops the frame throttle and gives a direct observable:

• a file created after startup is picked up rather than asserted on, and the cached listing notices it
• a deletion is not reported as a modification and does not crash
• a second mount serving the same directory contributes its files
• a mount point below the shader directory adds a virtual subdirectory that no walk can see, which only the mount counter can catch

Each case cleans up after itself. Without that the files survive in the build directory and are present at populate time on the next run, which makes the cases pass without exercising the path they are named for.

Verified by mutation rather than by going green:

mutation	result
cache ignores the per mount signatures	the two file appearance cases fail
cf_fs_mount stops bumping the counter	only the mount point case fails

Also checked: the POSIX branch compiles clean under Linux clang, and a debug mode (CF_SHADER_WATCH_VERIFY) that runs the PhysFS path alongside the native one and asserts they agree reports no divergence, including against a decoy directory, a shadowing mount, and a junction.

Not covered: .vert and .frag being in the watched set.