feat(fspy): let the caller size the tracking channel

[wan9chi]

Motivation

The shared memory a tracked run reports its file accesses through is four gibibytes, fixed. Nothing could ask for a smaller channel, so no test could put a task in front of one too small to hold its records — and that path decides whether a run may be cached. It had no coverage at all.

What changes

VP_RUN_INTERNAL_FSPY_SHM_CAPACITY overrides the size, read next to the channel call that uses it and falling back to the same four gibibytes when unset. Nothing about a normal run moves. The variable is internal: it exists so a test can shrink the channel until a task overruns it, and nothing outside this repository should set it.

The read sits at the point of use rather than travelling there. A size threaded through Command would put a builder method, a public default constant and a lookup in the runner between the variable and its one consumer, and would drag every other caller — the benchmark launcher, the e2e tool, the examples, fspy's own tests — into a decision none of them want to make. It also keeps the whole thing behind one cfg: fspy::ipc is already cfg(not(target_env = "musl")), so the size lives behind the same gate as the channel it sizes.

The test

vtt stat-many <count> [name-length] stats generated names to be tracked, under distinct names so none can fold into a single record, and prints its last line afterwards to show the process outlived them. It absorbs stat_long_filename, which did the same thing along the other axis; the /dev/shm case that used it now says stat-many 1 1048576. The e2e case makes twenty thousand accesses under a 64 MiB channel, which holds every one, so the run caches like any other — that is what tells us the size arrived where it was meant to.

Record count is the lever rather than record size, because size cannot be pushed far enough on every platform. A path reaches the tracer on Windows through a UNICODE_STRING, whose length field is a u16, so no single record there exceeds 64 KiB however long a name the caller asks for — an earlier version of this case tried one 2 MiB path and Windows had room to spare for it.

The case skips musl, which has no preload: those builds collect through the seccomp supervisor, on the runner's own side of the boundary, so there is no shared-memory channel there to fill.

The case worth testing, a channel too small for the task, has to wait for #675. On this base a full channel aborts the task process, and the panic it prints carries a thread id, a toolchain path, a backtrace and a platform's own abort code, so there is nothing there that snapshots the same way twice. #675 makes that a skipped record and a reported reason instead, and updates this snapshot to show it.

Split out of #675.

🤖 Generated with Claude Code

[github-actions]

fspy benchmark

linux

dynamic/launch             change  +0.36%  [ -6.47% ..  +8.29%]  overhead   +53.04%
dynamic/access             change  +1.75%  [-14.43% .. +27.22%]  overhead    +6.68%
dynamic/access-relative    change  +1.13%  [-13.75% .. +24.55%]  overhead   +47.12%
static/launch              change  +0.71%  [ -8.18% .. +11.27%]  overhead  +141.32%
static/access              change  -1.73%  [-16.98% ..  +6.26%]  overhead  +824.99%
static/access-relative     change  +0.23%  [ -6.89% ..  +6.80%]  overhead +1154.04%

macos

dynamic/launch             change  -0.13%  [ -3.68% ..  +4.11%]  overhead  +228.99%
dynamic/access             change  -0.27%  [-13.40% .. +15.71%]  overhead    +4.79%
dynamic/access-relative    change  +2.03%  [-10.31% .. +29.14%]  overhead  +253.76%

windows

dynamic/launch             change  +0.13%  [ -3.24% ..  +3.46%]  overhead   +27.13%
dynamic/access             change  +0.00%  [ -1.28% ..  +1.12%]  overhead    +1.50%
dynamic/access-relative    change  +0.00%  [ -2.30% ..  +2.73%]  overhead    +2.02%