fix(scan): stop the Linux descriptor path leaking into metadata and size

[m4bard]

Summary

On Linux a registration lease's metadata path is a /proc/{pid}/fd/{fd} descriptor link rather than a path to the file, and two things read it as though it were one. The probe's audio-extension guard rejects a candidate whose public half has no extension, so the embedded-metadata pass never runs; and FileInfo on the link reports the length of the link, a constant 64 bytes, rather than of the file.

Fixes #818 and #821. Rebased onto 03958c15 as promised on #818 once #819 landed.

The mechanism was worked out jointly with @kevinroberts on that thread rather than by me alone. He reproduced it independently on unpatched canary, withdrew his own suggested validation case once it turned out not to exercise the pass it was meant to test, and rewrote the issue around the root cause. The second of those is the reason the check below varies which agreements break instead of asserting one construction.

Changes

Fixed

• AudiobookScanService.Metadata.cs passes new MetadataFileSource(pinnedMetadataFile.MetadataPath, candidate) instead of collapsing both halves onto the descriptor path. The read path stays the pinned generation; the public path keeps the real filename, so the guard sees an audio extension and ffprobe runs.
• AudiobookFileService gains ResolveRegisteredLength, which takes the length from the pinned handle rather than stat'ing the visible path, and both size sites use it. Leases that do not expose generation-bound reads fall back to the metadata path, which for those callers is the public path.

The pinning guarantee is unchanged in both cases. The length comes from the handle the lease already holds, so it never consults the visible path, which is the property the lease exists to provide.

Testing

Two existing tests needed to follow the read onto the two-part source. Both mocked only the single-path overload, so a strict mock saw no matching setup once the scan routed through MetadataFileSource, the extractor returned nothing, and every file read as unreadable.

ScanAsync_MetadataReplacementAndRestore_ReadsPinnedFileGeneration needed a decision rather than a swap. Its callback reads ReadPath, because the point of the test is that the scan sees the original generation while the visible file is swapped underneath it. It now also asserts PublicPath is still the candidate with its extension intact, and that assertion is load-bearing: collapsing both halves onto the descriptor path fails it with the real path expected and /proc/<pid>/fd/<fd> observed. That is this defect, in a unit test, where before it was only reachable through a running container.

Full suite: 3,029 passed, 0 failed, 125 skipped, which is the baseline on 03958c15 unchanged, since this modifies two existing tests rather than adding any.

Reproduced before and after against ghcr.io/listenarrs/listenarr:canary and a build of this branch, with a public check that varies which agreements are broken rather than asserting a single case:

construction	canary	patched
claimed by path attribution	claimed	claimed
filename no longer matches the title	claimed	claimed
folder no longer matches the record's title	claimed	claimed
neither folder nor filename matches	UNCLAIMED	claimed
only the embedded tags identify it	UNCLAIMED	claimed

Both agreements have to break before anything reaches the pass, which is why the two single-mismatch rows are controls rather than filler: each rescues the other, so a check that only broke the filename would never exercise the path it was written to test.

Size, same book, 40 files:

on disk          223,520 bytes across 40 files
canary            2,560 bytes across 40 files     (40 x 64)
this branch     223,520 bytes across 40 files

What this does not fix

Worth being explicit, since the branch touches the neighbourhood of three other issues.

#542 is untouched. The book-level total still reads "not set" on both builds. This corrects the per-file rows; whatever should sum them is a separate defect and I have not looked at it here.

#822 is only partly addressed, and not by this. #819 added an early return recording MetadataEnrichmentSkippedLimitedStorage, which covers the limited-storage case. A probe refusal on storage that passes the generation check still commits Completed with nothing recorded and no diagnostic. That is what the matrix rows above show as UNCLAIMED with no diagnostic, and it stays true after this change for any other reason a probe might refuse.

I verified #819's early return does not shadow this: it returns at :25 and the patched call is at :73, so on storage with durable generation proof execution still reaches it.

One question

This fixes two filed issues in one diff because they share a cause and a call path, and the size sites were always part of the same patch. If you would rather have them as two PRs, say so and I will split it. I would rather ask than guess, since the split is cheap now and awkward after review has started.

[m4bard]

I have cut this PR down. #901 covers half of what it was doing, and covers it better than I did.

This originally fixed two things behind the same /proc/{pid}/fd/{fd} link. The size, where FileInfo stats the link and reports its constant 64 bytes rather than the file's length. And the metadata read, where the probe's audio-extension guard rejects a candidate whose path has no extension, so ffprobe never runs at all.

#901 fixes the size. It opens the metadata path and takes the stream length unconditionally. Mine read the length through the lease's generation-bound stream and then fell back to FileInfo on the metadata path when the lease did not expose one, which on Linux is the original 64-byte bug again. That fallback was mine and it was a hole. #901 does not have it.

Worth adding that my size half had no test of its own here either. Both test files on this branch cover the scan boundary, not the size.

So the size change is gone and the two files it touched are back at canary. AudiobookFileService.cs and AudiobookFileService.PhysicalGeneration.cs are untouched by this PR now, which means it no longer shares a file with #901 or with #902. Whichever order they land in, neither has to resolve anything against the other.

What is left

One production change, in AudiobookScanService.Metadata.cs.

The scan passed the lease's metadata path as both the byte source and the media identity. Those are deliberately separate things: the lease exists to give stable byte access while the public path stays the file's real identity, and the single-path overload collapses the two. On Linux the metadata path is an extensionless /proc link, so the collapse makes the extension guard reject the candidate before ffprobe is reached. Passing the candidate as the identity alongside the metadata path as the byte source keeps the guard looking at the real filename.

That is a different symptom from a wrong size. A file with this problem has no embedded metadata read at all, rather than metadata plus a bad length, so #901 landing does not make it go away.

Checks

Full suite unfiltered: 3039 passed, 0 failed, 127 skipped, which is the canary baseline. Both builds clean at 0 warnings. The test changes here modify existing scan tests rather than adding new ones, so the count does not move.

Control: reverting AudiobookScanService.Metadata.cs to canary and keeping the tests fails 2 of the 29 scan tests. Restoring it goes green.

Test-merged against canary, against #901 and against #902: all three clean.

I have not compared my scan change against anything in #902 beyond the merge, so if it overlaps in intent rather than in text, say so and I will look again.