feat: read title files from a read-only app0.zar (ZArchive) layer

[AlexOfTheForest]

What

Closes #4848. Adds an opt-in, read-only app0.zar (ZArchive) beside app0/. A path missing from app0/ is looked up in the archive case-insensitively; files on disk take precedence. Without an archive nothing changes.

• build: zstd v1.5.7 and ZArchive as submodules, built from source as static PIC libraries; their symbols are excluded from the .prx export table on Linux.
• libc: archive reader, archived-descriptor table with shared positions, and a guard in ResolvePath_nid_no_patch. Any call that does not read the archive throws NotImplemented for an archive-only path instead of returning ENOENT. opendir of a directory present on disk and in the archive, fdopen of an archived descriptor and chdir into the archive also throw. .. through an archive-only directory resolves.
• libkernel:
  • Open: sceKernelOpen/open give an archived file a read-only null-device descriptor.
  • Reads: read, pread, readv, preadv and AIO reads are served from the archive.
  • Other descriptor calls: lseek, fstat and FIONREAD are served from the archive. dup, dup2 and F_DUPFD share the position.
  • Path calls: sceKernelStat and sceKernelCheckReachability see archived paths.
  • Errors: opening for writing fails with EROFS, O_CREAT|O_EXCL with EEXIST, and O_DIRECTORY on a file with ENOTDIR. Opening an archived or merged directory throws until getdents can list it.
• Remaining gaps (fopen, access, mmap, record locks, directory listing) are recorded in docs/dev/debt/libc.md and libkernel.md; usage is in docs/user/USAGE.md.

Tested

Linux x86-64, GCC, full build with BUILD_TESTING=ON.

• New tests (all passing): guest_app_archive_{present,absent,damaged,invalid} and guest_kernel_app_archive_{archive,plain}. They cover:
  • reads that cross 64 KiB block boundaries, plus vectored, positioned and AIO reads;
  • seeks and end of file;
  • shared positions after dup, F_DUPFD and close, and dup2 over an archived descriptor;
  • stat/fstat, the error codes, the refusals, a damaged block and an invalid archive;
  • disk precedence and unchanged behaviour without an archive.
• Mutation check: removing the sceKernelRead hook makes the kernel test fail.
• Full ctest: only environment failures (UDP/TCP sockets unavailable in the sandbox; shm EACCES check while running as root).
• No title tested.

Checklist

• Based on current main; no other open PR implements the same functions
• One topic per PR; follow-ups go in a new PR
• No comments in code except technical debt
• Unimplemented paths throw (NotImplemented_nid_no_patch); silent stubs are listed under Silent stubs in their library's technical debt file
• No notes, investigation .md files or images added to the repository (attach them to this PR)
• New third-party code is a submodule built from source
• Generic behaviour, not specific to one title
• Depends on: none
• Unblocks: none
• GPUs tested: n/a
• AI-assisted: yes

[adriadam10]

Thanks for this, the layering and the tests are careful. One blocking issue before merge:

• An archived file is a real null-device descriptor (core/libs/prx/libkernel/File/src/ArchivedFile.cpp:23), and only read/seek/stat/FIONREAD/AIO/dup check for it. Every other descriptor call still runs on the null device: mmap_nid_postfix (DirectMemory/PosixMemory.cpp:92, takes the fd straight to the host mmap), fchmod, fchown, futimes, flock, ftruncate, fsync/fdatasync (File/src/Stdio.cpp ~288-311, 693, 736, 903, 913). They either succeed silently or fail with an unrelated errno, and fchmod/futimes act on the host's /dev/null. That contradicts "any call that does not read the archive throws NotImplemented" in the description and the exact-or-throw rule (titles commonly mmap their assets).
• Fix: for an archived descriptor these calls throw NotImplemented (as fdopen already does), and the debt line in docs/dev/debt/libkernel.md lists them. Add a test in GuestKernelAppArchive.cpp that calls each one on an archived fd.

Also note: the Windows paths (NUL placeholder, linking zarchive into libc) are not exercised by the PR CI, so the full Build dispatch will be the evidence for them.

[AlexOfTheForest]

Thanks for this, the layering and the tests are careful. One blocking issue before merge:

• An archived file is a real null-device descriptor (core/libs/prx/libkernel/File/src/ArchivedFile.cpp:23), and only read/seek/stat/FIONREAD/AIO/dup check for it. Every other descriptor call still runs on the null device: mmap_nid_postfix (DirectMemory/PosixMemory.cpp:92, takes the fd straight to the host mmap), fchmod, fchown, futimes, flock, ftruncate, fsync/fdatasync (File/src/Stdio.cpp ~288-311, 693, 736, 903, 913). They either succeed silently or fail with an unrelated errno, and fchmod/futimes act on the host's /dev/null. That contradicts "any call that does not read the archive throws NotImplemented" in the description and the exact-or-throw rule (titles commonly mmap their assets).
• Fix: for an archived descriptor these calls throw NotImplemented (as fdopen already does), and the debt line in docs/dev/debt/libkernel.md lists them. Add a test in GuestKernelAppArchive.cpp that calls each one on an archived fd.

Also note: the Windows paths (NUL placeholder, linking zarchive into libc) are not exercised by the PR CI, so the full Build dispatch will be the evidence for them.

Thanks for the review now it should be fixed

[adriadam10]

Rebased onto current main: the only real conflict was File/src/Stdio.cpp in TransferIovecs, where main added File::LockPositionedTransfer(d). Kept both, the archived read first and the lock after it. No other change to the PR. guest_app_archive* and guest_kernel_app_archive* pass on the rebased tree. Merging once the full Build (Windows) is green.