release: v1.9.3M -- encrypted archives, plus the UI round that followed

First release under the fork-marker convention: VERSION_TAG carries a trailing `M`, so /api/version, the PS5 start-up notification, the stdout banner, the UI footer and the ELF file name all read "v1.9.3M" in one move -- and a fork build can no longer collide with an upstream artifact of the same version, a mix-up that already happened twice. The footer carries a tooltip spelling the marker out. Two bodies of work. 1. Encrypted archives (ZIP / RAR / 7z) - ZIP: ZipCrypto (traditional PKWARE) and WinZip AES-256, through minizip-ng plus a vendored crypto layer (mz_crypt_wfm.c, mz_strm_pkcrypt.c, mz_strm_wzaes.c). - RAR: RARSetPassword, wired after RAROpenArchiveEx and before the first RARReadHeaderEx. The ordering is load-bearing, not stylistic. - 7z: 7zAES including -mhe=on encrypted headers, via a virtual ISeekInStream that splices a pseudo-header + the real archive + the decrypted header, so no offset stored inside the archive has to move. A wrong password is reported as ZIPX_ERR_PASSWORD, and a failed attempt leaves no staging directory behind. 2. Reporting, and the UI round that on-device testing produced - A RAR whose dictionary exceeds what the build supports now gets its own extract_dict_too_large code instead of being mis-reported as "entry too large"; the message names both the required and the supported size. The behaviour is deliberately unchanged -- such archives are still refused, because admitting one means allocating the whole window up front, which is why rarlab's own CLI refuses them by default. - The upload entry is a menu again: one "Upload" button opening "Upload files / Upload folder". The previous main-button-plus-small-arrow made "upload folder" effectively undiscoverable. - A drag-and-drop hint sits in the footer (hidden on the console browser, where drag is not how anyone uploads). - The extract button is now always present and merely disabled until exactly one archive is selected, instead of appearing out of nowhere. - Upload-and-extract on an encrypted archive now prompts for the password directly. The retry table used to be keyed by PATH, and for a non-ASCII directory the string the page holds and the string the server reports are not the same bytes -- the lookup missed, so the user got a bare error box and had to press Extract by hand before the prompt appeared. It is now keyed by task id, which the server assigns and echoes back verbatim. - Error text passes through decodeFsText(), so a GBK entry name no longer surfaces as `â®…ç§.psd`. - Local names are encoded with encodeFsText() before being joined onto a server-side path. fs_path_value() declines to rewrite a path if ANY code point exceeds 0xFF, so concatenating a local name onto a server directory produced a mixed representation and a silently dead path. - The menu row highlight was losing the cascade to the generic button rule (identical specificity, later in the file) while inheriting the toolbar's 3px focus ring, which overflowed a 46px row. Both rules are now scoped to the panel and the keyboard cue is an inset ring, so it cannot escape the row at any line height. - The footer status line is clamped to a single line; a long "uploading 3/12: some-name.zip" used to wrap out of the 46px footer. - A first failed password attempt now says the archive is encrypted, instead of blaming a password the user was never asked for. Artifact web-file-mgr-v1.9.3M.elf 903,448 B sha256 8ca47d5aaca75085b32641300cce30fadb7df7749cb6b53d04f129bcecc286b7 e_machine 0x003e (x86-64 / PS5) The file size is identical to the four builds before it, and every one of them carries a different sha256: only .rodata moved, and by less than the 16 KiB section alignment absorbs. Compare sections with `readelf -SW` -- never infer "nothing changed" from the byte count. Verification - host suites: 140 ZIP + 37 RAR = 177 checks, 0 failures - 7z suite: 27 cases, 0 failures. The `aeshe` entry that used to sit in KNOWN_GAPS is gone -- the -mhe=on fixture now passes both the folder decoder and the extraction facade - frontend: .build/ui_retry_test.mjs (40 checks), .build/ui_upload_menu_test.mjs (40 checks), .build/preview_check.mjs (12 assertions in headless Chromium against the real page and a fixture API). Two layout regressions and the highlight cascade bug were caught by the last one and by nothing else -- reading the source, both CSS rules "look correct" - built twice from this tree: byte-identical (cmp clean). rsync refreshes every asset mtime, so this is a genuine recompile, not make short-circuiting on unchanged sources - embedded assets verified in place with .build/check-elf-gzip.py, because gen-asset-module.py gzips them and plain `strings` finds none of their text - exercised end to end on a real PS5; the checklist is docs/DEVICE-TEST-v1.9.3M.md Docs - docs/USER-GUIDE-zh-CN.md (new, simplified Chinese user guide) - docs/DEVICE-TEST-v1.9.3M.md (new, on-device acceptance checklist) - docs/REAL-CONSOLE-PROFILE.md (new, measured console behaviour) - docs/archive/HANDOVER-v1.8-planning.md (superseded v1.8 design notes) - CHANGELOG / README (both languages) / HANDOVER updated with the artifact fingerprint, the section deltas and the new test counts
release: v1.9.2 -- re-cut the release so tag = source = binary
2026-10-06 08:00:23 +02:00 · 2026-09-24 21:07:12 +08:00 · 2026-09-20 17:33:32 +08:00 · 2026-09-20 15:44:30 +08:00 · 2026-09-20 13:19:20 +08:00 · 2026-09-17 12:14:09 +08:00
330 changed files with 78908 additions and 15275 deletions
@@ -0,0 +1,168 @@
+#!/usr/bin/env bash
+# ===========================================================================
+# ps5-web-file-manager -- 一键在 WSL 里生成 PS5 ELF
+#
+# 这个脚本在 WSL (Ubuntu-22.04) 里执行，做四件事：
+#   1. 把 Windows 仓库的源码 rsync 到 WSL 项目目录（增量，跳过构建缓存）
+#   2. make all  （PS5_PAYLOAD_SDK = /opt/ps5-payload-sdk）
+#   3. 验证产物：size / sha256 / e_machine
+#   4. 把 ELF 拷回 Windows 项目根
+#
+# 从 Windows 的 Git Bash / MinGW64 bash 里这样跑：
+#   wsl.exe -d Ubuntu-22.04 -- bash < \
+#     "/c/Users/songl/Desktop/Web File Manager/ps5-web-file-manager/.build/build-elf-wsl.sh"
+#
+# 注意：必须用 stdin 重定向 `bash < script`，不要 `bash -c '...'` ——
+#   路径含空格时 -c 的参数会被 wsl.exe 拆断。
+# ===========================================================================
+
+set -uo pipefail
+
+# ---------------------------------------------------------------- 配置 -----
+SRC_WIN='/mnt/c/Users/songl/Desktop/Web File Manager/ps5-web-file-manager'
+PROJ='/home/song/ps5-web-file-manager'
+SDK='/opt/ps5-payload-sdk'
+
+log()  { printf '\033[1;36m%s\033[0m\n' "$*"; }
+warn() { printf '\033[1;33m[WARN] %s\033[0m\n' "$*"; }
+fail() { printf '\033[1;31m[FAIL] %s\033[0m\n' "$*"; exit 1; }
+
+# ------------------------------------------------------------ jwasm --------
+# The LZMA decoder has an asm implementation that is 26% faster than the C one
+# (see docs/EXTRACTION-PERF.md). It is MASM syntax, so a MASM-compatible
+# assembler is needed. Makefile only enables the optimisation when jwasm is on
+# PATH, so a failure here downgrades rather than breaks the build.
+JWASM_HOME="$HOME/.cache/wfm-jwasm"
+JWASM_BIN="$JWASM_HOME/jwasm"
+
+ensure_jwasm() {
+  if command -v jwasm >/dev/null 2>&1; then
+    echo "  jwasm: $(command -v jwasm)"
+    return 0
+  fi
+  if [ -x "$JWASM_BIN" ]; then
+    export PATH="$JWASM_HOME:$PATH"
+    echo "  jwasm: $JWASM_BIN (缓存)"
+    return 0
+  fi
+
+  echo "  jwasm 不在，正在从源码编译（首次约 30 秒）..."
+  mkdir -p "$JWASM_HOME" || return 1
+  if [ ! -d "$JWASM_HOME/src" ]; then
+    git clone --depth 1 https://github.com/Baron-von-Riedesel/JWasm.git \
+      "$JWASM_HOME/src" >/dev/null 2>&1 || return 1
+  fi
+  make -C "$JWASM_HOME/src" -f GccUnix.mak -j4 >/dev/null 2>&1 || return 1
+  cp -f "$JWASM_HOME/src/build/GccUnixR/jwasm" "$JWASM_BIN" || return 1
+  chmod +x "$JWASM_BIN" || return 1
+  export PATH="$JWASM_HOME:$PATH"
+  echo "  jwasm: $JWASM_BIN (已编译)"
+}
+
+# ------------------------------------------------------- 1/5 环境检查 -----
+log "[1/5] 环境检查"
+
+[ -d "$SRC_WIN" ] || fail "Windows 源码目录不可见: $SRC_WIN （/mnt/c 挂载了吗?）"
+[ -x "$SDK/bin/prospero-clang" ] || fail "SDK 缺失: $SDK/bin/prospero-clang"
+
+export PS5_PAYLOAD_SDK="$SDK"
+# shellcheck disable=SC1091
+source "$SDK/toolchain/prospero.sh" 2>/dev/null || true
+export CC="$SDK/bin/prospero-clang"
+export CXX="$SDK/bin/prospero-clang++"
+export PKG_CONFIG="$SDK/bin/prospero-pkg-config"
+
+"$CC" --version | head -1
+"$PKG_CONFIG" --modversion libmicrohttpd 2>/dev/null \
+  || fail "libmicrohttpd 未装到 sysroot —— 先跑一次完整的 build-elf.sh v4"
+
+ensure_jwasm || warn "jwasm 不可用 —— 将退回纯 C 解码器（约慢 26%）"
+echo
+
+# ------------------------------------------------------- 2/5 同步源码 -----
+log "[2/5] 同步源码 Windows -> WSL (rsync 增量)"
+mkdir -p "$PROJ"
+
+rsync -a --delete \
+  --exclude='/ps5-obj' --exclude='/linux-obj' \
+  --exclude='/web-file-mgr-*.elf' --exclude='/web-file-mgr-linux*' \
+  --exclude='/gen' --exclude='/.build' --exclude='/tests' \
+  --exclude='/docs' --exclude='/HANDOVER.md' \
+  --exclude='/README.md' --exclude='/CHANGELOG.md' \
+  --exclude='/erssongl*' \
+  --include='/src' --include='/assets' \
+  --include='/third_party' --include='/Makefile' \
+  --include='/gen-asset-module.py' --include='/.gitignore' \
+  --exclude='/*' \
+  "$SRC_WIN/" "$PROJ/" || fail "rsync 失败"
+
+# rsync 的 --include 只放行目录本身，这几个顶层文件再单独 cp 一次
+for f in Makefile gen-asset-module.py .gitignore; do
+  [ -f "$SRC_WIN/$f" ] && cp -f "$SRC_WIN/$f" "$PROJ/$f"
+done
+
+# 冒烟：今天的关键文件都在不在
+for f in src/sevenz_extract.c src/zipx_common.c src/sevenz_volstream.c \
+         src/sevenz_chain.c Makefile gen-asset-module.py; do
+  [ -f "$PROJ/$f" ] || fail "同步后缺失: $PROJ/$f"
+done
+[ -d "$PROJ/third_party/7z" ] || fail "同步后缺失: $PROJ/third_party/7z"
+
+# 输出文件名由 Makefile 的 VERSION_TAG 决定（web-file-mgr-<ver>.elf）。
+# 从 Makefile 里读，别在脚本里硬编 —— 否则改了版本号脚本还在找旧名字。
+VERSION=$(sed -n 's/^VERSION_TAG *[?:]*= *//p' "$PROJ/Makefile" | head -1)
+[ -n "$VERSION" ] || fail "读不到 VERSION_TAG: $PROJ/Makefile"
+BIN_NAME="web-file-mgr-${VERSION}.elf"
+ELF="$PROJ/$BIN_NAME"
+
+echo "  src/ + assets/ + third_party/ + Makefile  OK"
+echo "  版本: $VERSION  ->  输出: $BIN_NAME"
+echo
+
+# ---------------------------------------------------------- 3/5 编译 ------
+log "[3/5] make all"
+cd "$PROJ" || fail "cd $PROJ"
+
+make all 2>&1 | tail -120
+# make 的退出码被管道吃了，用 PIPESTATUS 取回来
+if [ "${PIPESTATUS[0]}" -ne 0 ]; then
+  fail "make all 失败（详见上方输出）"
+fi
+echo
+
+# ---------------------------------------------------------- 4/5 验证 ------
+log "[4/5] 验证产物"
+[ -f "$ELF" ] || fail "ELF 未生成: $ELF"
+
+SIZE=$(stat -c%s "$ELF")
+HASH=$(sha256sum "$ELF" | cut -d' ' -f1)
+# ELF header: offset 18 起 2 字节 = e_machine。
+# `od -tx2` 按 2 字节小端解释成一个 short 后打印其**值**，所以文件里的
+# 字节序 "3e 00" 会输出成 "003e"（不是 "3e00"）。别拿字节序去比对。
+EM=$(od -An -tx2 -j 18 -N 2 "$ELF" | tr -d ' \n')
+EM_NUM=$((16#$EM))
+
+ls -lh "$ELF"
+echo "  size:    $SIZE bytes (~$((SIZE / 1024)) KiB)"
+echo "  sha256:  $HASH"
+echo "  e_machine = 0x$EM ($EM_NUM)"
+
+case "$EM_NUM" in
+  62)  echo "  -> x86-64 / PS5  [OK]" ;;
+  183) fail "e_machine=$EM_NUM (0x$EM) 是 aarch64！PS5 是 x86-64，target 三元组错了" ;;
+  *)   fail "e_machine=$EM_NUM (0x$EM) 非预期（期望 62 = 0x003e = x86-64）" ;;
+esac
+echo
+
+# ------------------------------------------------- 5/5 拷回 Windows -------
+log "[5/5] 拷回 Windows"
+cp -f "$ELF" "$SRC_WIN/$BIN_NAME" || fail "拷回 Windows 失败"
+ls -lh "$SRC_WIN/$BIN_NAME"
+echo
+printf '\033[1;32m[DONE]\033[0m %s\n' "$SRC_WIN/$BIN_NAME"
+echo "  $SIZE bytes / sha256 $HASH / e_machine 0x$EM"
+
+# 顺便报告 Windows 侧现在有哪些版本化 ELF，方便挑一个拷进 U 盘
+echo
+echo "  Windows 项目根现有的 ELF："
+ls -1 "$SRC_WIN"/web-file-mgr-*.elf 2>/dev/null | sed 's#.*/##' | sed 's/^/    /' || true
@@ -148,10 +148,14 @@ echo "[6/7] make all (增量编译, 复用第三方 obj)..."
 cd "$PROJ"
 export PS5_PAYLOAD_SDK="/opt/ps5-payload-sdk"
 # 仅当二进制缺失或源码变更才全量重编
+# 重要: 必须包含 assets/* 和 gen-asset-module.py —— 它们经 gen-asset-module.py
+# 生成 gen/*.c 进而影响 ELF, 不在列表里就会跳过 make 产生伪"无变更"(v1.8.3
+# 被这个 bug 坑过, ELF sha256 没变)。
 if [ -f web-file-mgr.elf ]; then
  echo "    已存在 web-file-mgr.elf, 检查源码变更..."
  NEEDS_REBUILD=""
-  for src in src/*.c Makefile third_party/minizip-ng/include/*.h third_party/zlib/include/*.h; do
+  for src in src/*.c Makefile assets/* gen-asset-module.py \
+             third_party/minizip-ng/include/*.h third_party/zlib/include/*.h; do
    [ -e "$src" ] || continue
    if [ "$src" -nt web-file-mgr.elf ]; then
      NEEDS_REBUILD="$src"
@@ -162,10 +166,16 @@ if [ -f web-file-mgr.elf ]; then
    echo "    无源码变更 -- 跳过 make"
  else
    echo "    源码变更: $NEEDS_REBUILD"
-    make all 2>&1 | tail -40
+    if ! make all 2>&1 | tail -60; then
+      echo "FAIL: make all 失败(见上)。注意: 旧 ELF 仍留在原地, 但不算新产物"
+      exit 6
+    fi
  fi
 else
-  make all 2>&1 | tail -40
+  if ! make all 2>&1 | tail -60; then
+    echo "FAIL: make all 失败(见上)"
+    exit 6
+  fi
 fi

 # 7. 验证 + 同步回 Windows
@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+# ===========================================================================
+# ps5-web-file-manager -- Windows 端一键构建入口
+#
+# 在 Windows 的 Git Bash / MinGW64 bash 里这样跑（注意用 /usr/bin/bash）：
+#     /usr/bin/bash .build/build-win.sh
+#
+# 它只做一件事：把 WSL 脚本喂给 wsl.exe 执行，然后透传退出码。
+# 真正的 sync / make / verify / 拷回都在 .build/build-elf-wsl.sh 里。
+#
+# 注意：
+#   * 用 `bash < script` 走 stdin，不要用 `bash -c '...'` ——
+#     路径含空格时 -c 的参数会被 wsl.exe 拆断。
+#   * 别写裸 `bash .build/build-win.sh`，那个 bash 可能解析到
+#     C:\Windows\System32\bash.exe（WSL 启动器），脚本会跑进 Linux 环境。
+# ===========================================================================
+
+set -uo pipefail
+
+# Git Bash / MSYS2 rewrites anything that looks like a POSIX path before the
+# argument reaches wsl.exe, so `/mnt/c/...` becomes
+# `<msys-root>/mnt/c/...` and the WSL side reports "cannot stat" (this is how
+# the script first failed under PortableGit). WSL sees Linux paths, so the
+# translation must be off for the whole script. Harmless on a real Linux shell.
+export MSYS_NO_PATHCONV=1
+export MSYS2_ARG_CONV_EXCL='*'
+
+REPO='/c/Users/songl/Desktop/Web File Manager/ps5-web-file-manager'
+WSL_DISTRO='Ubuntu-22.04'
+WSL_DIR='/home/song/ps5-web-file-manager/.build'
+HOST_SCRIPT="$REPO/.build/build-elf-wsl.sh"
+
+[ -f "$HOST_SCRIPT" ] || { echo "[FAIL] 找不到 $HOST_SCRIPT"; exit 1; }
+
+# 每次都把最新的 WSL 脚本推进去（.build/ 被 rsync 排除，WSL 侧不会自己更新；
+# 只做一次会导致改了脚本还在跑旧版 —— 这个坑踩过）
+wsl.exe -d "$WSL_DISTRO" -- mkdir -p "$WSL_DIR" || exit 1
+wsl.exe -d "$WSL_DISTRO" -- cp \
+  '/mnt/c/Users/songl/Desktop/Web File Manager/ps5-web-file-manager/.build/build-elf-wsl.sh' \
+  "$WSL_DIR/build-elf-wsl.sh" || {
+    echo "[FAIL] 无法写入 WSL 文件系统"
+    exit 1
+  }
+
+echo "[run] wsl.exe -d $WSL_DISTRO -- bash < build-elf-wsl.sh"
+echo "=================================================================="
+wsl.exe -d "$WSL_DISTRO" -- bash < "$HOST_SCRIPT"
+rc=$?
+echo "=================================================================="
+
+if [ "$rc" -eq 0 ]; then
+  # 输出文件带版本号（web-file-mgr-<VERSION_TAG>.elf），列出实际产物
+  echo "[OK] 构建完成，产物："
+  ls -1 "$REPO"/web-file-mgr-*.elf 2>/dev/null | sed 's#^#    #'
+else
+  echo "[FAIL] 构建失败 (exit=$rc)"
+fi
+exit "$rc"
@@ -1,51 +1,62 @@
-"""Verify our large-file mode identifiers made it into the ELF.
-gen-asset-module.py gzips JS assets, so plain `strings` won't find them.
-This script finds all gzip streams in the ELF, decompresses them, and greps
-for the new identifiers."""
-import re, sys, zlib
+"""Verify that specific identifiers made it into the ELF's embedded assets.
+
+`gen-asset-module.py` gzips every JS/CSS/HTML asset (compresslevel=9, mtime=0),
+so plain `strings` finds none of their text -- a zero hit means "compressed",
+not "missing". This script walks the file for gzip streams, decompresses each
+one and reports where each key landed.
+
+Usage:
+  python .build/check-elf-gzip.py <elf> [key ...]
+
+With no keys it defaults to the current round: the v1.9.3M fork marker and the
+footer tooltip that explains it. Pass your own after the ELF path when reusing
+this for another change.
+
+Scope note: this covers **assets only**. C-side string literals (e.g.
+`extract_dict_too_large`, `versionsTooltip` in a header) are not compressed and
+belong to a plain `strings` check.
+"""
+import sys
+import zlib
+
+if len(sys.argv) < 2:
+    sys.exit(__doc__)

 f = sys.argv[1]
 data = open(f, "rb").read()

-# Gzip streams start with 0x1f 0x8b. Walk through the file looking for them.
-keys = [
-    b"extractLargeAsk",
-    b"extractLargeActive",
-    b"promptLargeMode",
-    b"shouldPromptLargeMode",
-    b"LARGE_FILE_THRESHOLD_BYTES",
-    b"/api/extract",
-    b"large",
+keys = [k.encode() for k in sys.argv[2:]] or [
+    b"v1.9.3M",                          # assets/main.js footer fallback
+    b"versionTooltip",                   # main.js + both lang files
+    "本版为 LisherSong 改版".encode(),      # assets/lang-zh.js
+    b"Modified build by LisherSong",     # assets/lang-en.js
 ]
-seen = {}
-i = 0
-while i < len(data) - 10:
-    if data[i] == 0x1f and data[i + 1] == 0x8b:
-        # Try to decompress starting here, capped at 2 MiB.
-        end_cap = min(len(data), i + 2 * 1024 * 1024)
-        try:
-            dec = zlib.decompressobj(zlib.MAX_WBITS | 16)
-            chunk = dec.decompress(data[i:end_cap], 2 * 1024 * 1024)
-            if not dec.eof:
-                i += 1
-                continue
-        except Exception:
-            i += 1
-            continue
-        # Check for any of our keys in the decompressed stream.
-        for k in keys:
-            if k in chunk and k not in seen:
-                idx = chunk.find(k)
-                ctx = chunk[max(0, idx - 24):idx + len(k) + 48]
-                seen[k] = ctx.decode("utf-8", errors="replace")
-        i += 1
-    else:
-        i += 1

-print(f"decompressed streams scanned, keys found: {len(seen)} / {len(keys)}")
+seen = {}
+streams = 0
+i = data.find(b"\x1f\x8b\x08")
+while i >= 0:
+    # Try to decompress starting here, capped at 2 MiB.
+    end_cap = min(len(data), i + 2 * 1024 * 1024)
+    try:
+        dec = zlib.decompressobj(zlib.MAX_WBITS | 16)
+        chunk = dec.decompress(data[i:end_cap], 2 * 1024 * 1024)
+        if dec.eof and chunk:
+            streams += 1
+            for k in keys:
+                if k in chunk and k not in seen:
+                    idx = chunk.find(k)
+                    ctx = chunk[max(0, idx - 24):idx + len(k) + 48]
+                    seen[k] = ctx.decode("utf-8", errors="replace")
+    except Exception:
+        pass
+    i = data.find(b"\x1f\x8b\x08", i + 1)
+
+print(f"{f}: {streams} gzip streams scanned, keys found: {len(seen)} / {len(keys)}")
 for k, v in seen.items():
-    print(f"  ✓ {k.decode()}")
-    print(f"    context: {v[:160]}")
+    print(f"  OK   {k.decode()}")
+    print(f"       context: {v[:160]}")
 missing = [k for k in keys if k not in seen]
-if missing:
-    print(f"  ✗ not found: {[m.decode() for m in missing]}")
+for m in missing:
+    print(f"  MISS {m.decode()}")
+sys.exit(1 if missing else 0)
@@ -5,17 +5,30 @@
 gen/
 web-file-mgr-linux

-# Sandbox probe scratch under .build/ (the tracked items there are
-# build-elf.{sh,log}, check-elf-*.py and extract-demo.html; everything
-# else is local exploration that should not enter the repo).
-.build/host-test/
-.build/obj/
-.build/probe-work/
-.build/tp/
-.build/stub/
-.build/*.exe
-.build/*.c
-.build/test-out.txt
+# Sandbox scratch under .build/: ignore the whole directory, then re-allow the
+# handful of files that are actually part of the repo (build scripts + the
+# ELF checker). A whitelist is the only thing that survives -- every debugging
+# session drops a new probe directory in here.
+.build/*
+!.build/build-elf.sh
+!.build/build-elf-wsl.sh
+!.build/build-win.sh
+!.build/check-elf-*.py
+!.build/extract-demo.html
+!.build/build-elf.log
+
+# Generated 7z fixtures (tests/make_sevenz_fixtures.py rebuilds them).
+tests/fixtures-7z/
+
+# Staging trees the fixture generators copy from (make-rar-fixtures.bat uses
+# fixture-stage, make-zip-enc-fixtures.bat uses fixture-stage-zip). The
+# archives they produce under tests/fixtures-real/ ARE committed.
+tests/fixture-stage/
+tests/fixture-stage-zip/
+
+# Python bytecode (the fixture generators and bench_driver are hand-run)
+__pycache__/
+*.pyc

 # Editor / OS noise
 .vscode/
@@ -23,3 +36,6 @@ web-file-mgr-linux
 *.swp
 .DS_Store
 Thumbs.db
+
+# WorkBuddy session data (never commit; also never delete).
+.workbuddy/
@@ -4,14 +4,582 @@ All notable changes to **PS5 Web File Manager** are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

-> Release artifact for v1.8.1:
-> `web-file-mgr.elf` — size TBD (cross-compile runs in WSL — see `docs/HANDOVER.md`)
-> sha256 TBD
+> Release artifact for v1.9.3M — **built and verified locally, not published yet**:
+> `web-file-mgr-v1.9.3M.elf` — size 903 448 bytes (~882 KiB)
+> sha256 `8ca47d5aaca75085b32641300cce30fadb7df7749cb6b53d04f129bcecc286b7`
 > ELF class 64, little-endian, e_machine `0x003e` (x86_64-sie-ps5)
 >
-> Source delta vs v1.8: 3 source files relaxed (`src/zip_extract.c` k_default_limits,
-> `assets/main.js` `LARGE_FILE_THRESHOLD_BYTES`, `assets/lang-{en,zh}.js` copy);
-> no vendored or engine changes.
+> **The trailing `M` is the fork marker** (Modified build, maintained by
+> LisherSong). Upstream owendswang ships plain `vX.Y.Z`, so a version string on
+> its own says which of the two you are looking at. The marker rides on
+> `VERSION_TAG` rather than on a display-only constant, so `/api/version`, the
+> PS5 start-up notification, the stdout banner, the UI footer and the ELF file
+> name all gain it in one move — nothing can be forgotten in one of the five.
+> A second benefit is that a fork build can no longer collide with an upstream
+> artifact of the same upstream version, a mix-up that has already happened
+> twice. The footer additionally carries a tooltip spelling the marker out
+> (`versionTooltip`, en + zh). This is the first release using the convention;
+> the older entries below keep their original plain numbers.
+>
+> This is the first binary to carry the encrypted-archive work and the
+> dictionary-reporting fix (`[v1.9.3M]` below). It exists for on-device testing:
+> the GitHub release is still v1.9.2 and its binary contains none of it.
+>
+> Its size is **unchanged yet again** (903 448 B) although the content grew, for
+> the sixth build in a row. Every round of this release has only moved
+> `.rodata`, and by less than the 16 KiB section alignment absorbs:
+>
+> | build | `.rodata` | delta | what changed |
+> |---|---|---|---|
+> | `v1.9.3` (pre-marker) | 0x025F80 | — | — |
+> | `v1.9.3M` + encrypted archives | 0x0260C0 | +0x140 | the `M` marker, its tooltip, re-gzipped assets |
+> | `+` upload menu and i18n names | 0x026A40 | +0x980 | the menu, the hint, the new copy |
+> | `+` hint move, status clamp, retry key | 0x026B40 | +0x100 | final copy and CSS |
+> | `+` menu row highlight fix | 0x026CC0 | +0x180 | the scoped row highlight rules and their comment |
+> | `+` always-on extract button | 0x026F00 | +0x240 | the un-hidden button, three disabled reasons, the tooltip fix |
+>
+> `.text` is byte-for-byte the same size across all six, which is the expected
+> shape for a change that touches no C logic. **Never infer "nothing changed"
+> from the file size** — compare sections with `readelf -SW`. Each of the six
+> carries a different sha256 despite the identical size, so the digest, not the
+> byte count, is what identifies a build.
+>
+> Putting the extract button on screen at all times is not free: it widens the
+> resting toolbar by its own width, so the width at which the toolbar wraps onto
+> a second row moves out from 1080px to 1190px in Chinese, and from 1230px to
+> 1350px in English, where the labels are longer. The console is 1920px wide and
+> 1280px still fits in Chinese, so the trade was accepted: the alternative was
+> leaving the entry hidden until an archive happened to be selected, which is
+> what made it undiscoverable in the first place. The measured threshold is now
+> pinned by the headless harness rather than left to be rediscovered.
+>
+> Release artifact for v1.9.2:
+> `web-file-mgr-v1.9.2.elf` — size 870 488 bytes (~850 KiB)
+> sha256 `177e90fecf93a0251e83f67884fba4551051be248330b0d70fda8ea732f88e84`
+> ELF class 64, little-endian, e_machine `0x003e` (x86_64-sie-ps5)
+>
+> Behaviourally identical to the published v1.9.1 binary — the only source
+> delta is the version literal itself (`VERSION_TAG` in the Makefile, plus the
+> UI footer fallback in `assets/main.js`). The build is reproducible: reverting
+> those two literals and rebuilding reproduces the v1.9.1 ELF byte for byte, so
+> nothing else differs. See [v1.9.2] below for why the version moved at all.
+>
+> Release artifact for v1.9.1 (superseded — the tag pointed four commits behind
+> the tree that actually produced this binary):
+> `web-file-mgr-v1.9.1.elf` — size 870 488 bytes (~850 KiB)
+> sha256 `24392aff6ddcca4dc0ea969cce356bd693ac52efe8a117d61ee1c814aa43cd07`
+> ELF class 64, little-endian, e_machine `0x003e` (x86_64-sie-ps5)
+>
+> Built on the 7z-complete tree: LZMA SDK decode subset + self-written codec
+> chain, 7zAES, and ZIP/RAR/7z volume support. Build-system-only delta vs the
+> first v1.9.1 artifact (1 017 864 B): `src/demangle_stub.c` keeps libc++abi's
+> Itanium name demangler (105 KiB, only reachable from the uncaught-exception
+> path) out of the link, and `-Wl,--icf=all` folds identical functions.
+> −15.8% overall with no change to functionality or decompression throughput.
+> See `docs/SIZE-OPTIMIZATION.md`.
+>
+> Release artifact for v1.9:
+> `web-file-mgr.elf` — size 919 440 bytes (~897 KiB)
+> sha256 `bb8f17e9addc6a9984f611503ca01b51f8984b773d353630da1f25bd1a28a997`
+> ELF class 64, little-endian, e_machine `0x003e` (x86_64-sie-ps5)
+>
+> Source delta vs v1.8.3: RAR engine replaced (dmc_unrar 1.7.0 → rarlab
+> UnRAR 7.20.1, `third_party/unrar/` → `third_party/unrar7/`), new
+> `src/rar_extract.c` scan/extract implementation, Makefile + host-test
+> C++ rules, 5 real RAR fixtures committed. See [v1.9] below.
+>
+> Release artifact for v1.8.3:
+> `web-file-mgr.elf` — size 509 704 bytes (~497 KiB)
+> sha256 `fdcf7b09b69e2160e77dfa084c0e890ba0696d4dd478b1d5ff499cdc9f527955`
+> ELF class 64, little-endian, e_machine `0x003e` (x86_64-sie-ps5)
+>
+> Source delta vs v1.8.2: 5 files touched (4 user-facing + 1 build pipeline) —
+> see [v1.8.3] below for details.
+>
+> Release artifact for v1.8.2:
+> `web-file-mgr.elf` — size 509 704 bytes (~497 KiB)
+> sha256 `1b2c3d68b35e32737105f17d14a80a3c159ceca0cabd274ee168cbcd81906f65`
+> ELF class 64, little-endian, e_machine `0x003e` (x86_64-sie-ps5)
+>
+> Source delta vs v1.8.1: 5 files relaxed (`src/zip_extract.c` k_default_limits
+> + k_large_limits, `assets/main.js` `LARGE_FILE_THRESHOLD_BYTES`,
+> `assets/lang-{en,zh}.js` copy, `tests/test_zip_extract.c` advertised-number
+> assertion, README/HANDOVER numeric references) + 2 PS5-only build fixes
+> (`Makefile` CFLAGS `-Ithird_party/unrar`, `src/extract.c` forward
+> declaration of `extract_progress`); no vendored or engine changes.
+
+## [v1.9.3M] — 2026-09-23
+
+**Encrypted archives now extract end to end — ZIP (both schemes), RAR, and 7z
+with an encrypted header.**
+
+Until now every encrypted archive was refused up front, even though the
+password field, the prompt and `extract_password` copy had been in place
+since v1.9. The gap was in the engines, not the UI:
+
+- **ZIP**: the vendored minizip-ng had been trimmed past its crypto
+  backend, so the `-DHAVE_WZAES` / `-DHAVE_PKCRYPT` branches inside the
+  (unmodified) `mz_zip.c` had no implementation to call.
+- **RAR**: rarlab UnRAR could decrypt, but `RARSetPassword` was never
+  called.
+- **7z**: `-mhe=on` put the file names and the folder table inside the
+  encrypted header, so the archive could not even be listed.
+
+All three are wired now. A missing or wrong password is reported as
+`extract_password` (`ZIPX_ERR_PASSWORD` at the engine level), which is the
+code the task overlay's existing password prompt already reacts to.
+
+### Changed
+
+- **The version string gains a fork marker: `v1.9.3` → `v1.9.3M`.** Upstream
+  owendswang releases are plain `vX.Y.Z`, so the `M` (Modified) is what tells a
+  user which of the two they are holding. It is part of `VERSION_TAG` in the
+  Makefile, which means `/api/version`, the PS5 start-up notification, the
+  stdout banner, the UI footer **and the ELF file name** all carry it at once.
+  Because the file name changes too, a fork build can no longer shadow an
+  upstream artifact of the same upstream version.
+- The UI footer tooltip (`versionTooltip`, en + zh) spells the marker out, so
+  `v1.9.3M` is not left unexplained for someone who has not read this file.
+  `loadVersion()` only ever rewrites the footer's text, so the tooltip survives
+  the `/api/version` round trip.
+- **The upload button opens a menu instead of hiding half of itself behind a
+  caret.** It used to be a main button plus a small arrow: users read the arrow
+  as decoration and never found "upload a folder" at all. One click now lists
+  **Upload Files / Upload Folder** (`#uploadMenu`, `role="menu"`), with Escape,
+  an outside click and arrow keys handled, and focus moved into the list when it
+  opens. The button keeps a caret so it is obvious that a list is coming.
+- The footer status line is now clamped to a single line with an ellipsis. It
+  is a fixed-height row that also carries the version and the new drag hint, and
+  a long "uploading 3/12: some-name.zip" used to wrap to two lines and spill out
+  of the 46 px footer.
+- **The extract button is always on screen and greys out instead of being
+  hidden.** It used to appear only once an extractable archive was selected, so
+  the resting toolbar had no extract entry at all — the same discoverability
+  problem the upload button was changed for. It is now always present, disabled
+  and at 45% opacity whenever the selection cannot be extracted, and its tooltip
+  names the reason: *"Select one archive to extract (ZIP / RAR / 7z)"*, the
+  existing "please select the main volume" when only a `.partNN.rar` sub-volume
+  is selected, and a new "only one archive can be extracted at a time" when
+  several are selected — the old code answered *that* case with the main-volume
+  message, which was simply the wrong sentence. Because `button:disabled` sets
+  `pointer-events: none`, a disabled button cannot be hovered and its tooltip
+  never appears at all, so `.extract-action:disabled` restores hit-testing
+  without restoring clicks; the parent-directory button needed the same fix
+  earlier.
+- The extract button's label is the short `extract` ("解压" / "Extract"),
+  matching the other toolbar verbs, instead of `extractToCurrent` ("解压到当前
+  目录" / "Extract to current folder"). A button that is on screen permanently
+  should not also be the widest one in the toolbar, and the target folder is
+  still named in the tooltip and in the confirmation dialog. The measured cost
+  of the always-on button: the width at which the toolbar wraps onto a second
+  row moves from 1080px to 1190px in Chinese and from 1230px to 1350px in
+  English, where the labels are longer. 1280px still fits in Chinese and the
+  console is 1920px wide.
+
+### Added
+
+- **Encrypted ZIP** — traditional PKWARE ("ZipCrypto", what `zip -e`
+  writes) and WinZip AES-128/192/256 (method `99` + the `0x9901` extra
+  field, what `7z -mem=AES256` writes), for stored and deflated entries.
+- **Encrypted RAR** — `-p` data encryption and `-hp` header encryption.
+  `RARSetPassword` now runs right after `RAROpenArchiveEx` and before the
+  first `RARReadHeaderEx`, which is the order unrar needs to decrypt a
+  RAR5 header.
+- `password=` on `/api/extract` now reaches a real decrypt path for both
+  engines. An empty or absent value means "no password", so the raw form
+  field can be passed straight through.
+- **The UI retries a failed extraction with a password.** An
+  `extract_password` failure used to end in an error box, which for ZIP and
+  RAR meant the password could never be supplied at all — the prompt only
+  existed for 7z. The failed task is now re-sent with whatever the user types,
+  up to three times, and the remembered request keeps the original conflict
+  policy and large-file opt-in. Cancelling or submitting an empty box falls
+  back to the previous failure report. 7z keeps its up-front prompt so an
+  encrypted header does not cost a wasted scan.
+- `extractPasswordRetryAsk` (en + zh) is the retry prompt's wording, distinct
+  from the up-front `extractPasswordAsk`.
+- `third_party/minizip-ng/src/mz_crypt_wfm.c` — a local crypto provider for
+  the trimmed minizip-ng: SHA-1, HMAC-SHA1 and AES-128/192/256, with the
+  S-box and the GF(2^8) tables derived on first use so the binary gains no
+  new `.rodata` lookup tables. PBKDF2 comes from the vendored `mz_crypt.c`;
+  the CSPRNG reads `/dev/urandom` rather than `mz_os_rand()`, which keeps
+  `rand`/`srand` out of the import table. Restored verbatim from upstream
+  4.2.2: `mz_strm_wzaes.{c,h}`, `mz_strm_pkcrypt.{c,h}`.
+- `tests/make-zip-enc-fixtures.bat` and three real fixtures under
+  `tests/fixtures-real/` (`enc-zipcrypto.zip`, `enc-aes256.zip`,
+  `enc-aes256-store.zip`, password `secret123`).
+- **Encrypted 7z headers (`-mhe=on`)** — the last remaining format gap. With
+  `-mhe=on` the header is itself a folder holding the file names, the folder
+  table and every entry size, so the vendored SDK (whose C decoder has no
+  7zAES coder at all) abandons the archive with `SZ_ERROR_UNSUPPORTED` before
+  it can list a single entry. `src/sevenz_header.c` now reads the
+  `k7zIdEncodedHeader` record, decodes its one folder through the project's
+  own 7zAES path (`src/sevenz_chain.c`) and then gives the SDK a small virtual
+  `ISeekInStream` in which that record has been replaced by the plaintext —
+  the rewritten start header, the decrypted header at the offset the encoded
+  one already occupied, and the real archive everywhere else, so every offset
+  the archive stores still points where it did. Nothing on disk is written to.
+  Archives whose header is only *compressed* (`-mhc=on`, the default) are
+  detected from one byte and never touched, and a wrong password comes back as
+  `ZIPX_ERR_PASSWORD` like any other encrypted archive.
+- **A visible drag-and-drop hint** (`dropUploadHint`, en + zh) in the footer:
+  *"Drag files or folders into this window to upload"*. Dropping already worked,
+  but nothing but the drop overlay itself ever said so, and that only appears
+  once a drag is under way. It is `remote-only`, like the upload button it
+  describes, and starts hidden so the console browser never flashes it.
+- `uploadFiles` (en + zh) for the menu's file entry, and
+  `extractPasswordFirstAsk` — a first-failure prompt that says the archive is
+  encrypted rather than blaming a password the user was never asked for.
+- `extractSelectArchive` and `extractOneAtATime` (en + zh): the two reasons the
+  always-on extract button can be greyed out with nothing useful selected, and
+  with several archives selected. The third reason, `extractSelectMainVolume`,
+  already existed.
+
+### Fixed
+
+- **Compiler-flag changes now invalidate objects.** `make` cannot see a
+  flag change, so adding `-DHAVE_WZAES -DHAVE_PKCRYPT` left the existing
+  `mz_zip.o` / `mz_crypt.o` untouched — and since nothing referenced the
+  new streams any more, `--gc-sections` dropped the encryption code again
+  while the link still reported success (the first build of this change was
+  byte-for-byte the published release). The Makefile now records the
+  third-party flag set in `ps5-obj/.third_party_cflags` /
+  `linux-obj/.third_party_cflags` and rebuilds only when it really changes —
+  the same trap the older `LzmaDec.o` rule was working around, generalised.
+- `ZIPX_ERR_UNSUPPORTED` no longer covers encryption — it is now "multipart
+  or unsupported compression method" only.
+
+- **An oversized archive dictionary is now reported as such.** An archive whose
+  dictionary exceeds what the build allows used to fail with
+  `extract_entry_too_large` / "A file inside the archive is too large" naming the
+  entry that happened to be in flight — for the 8 GiB-dictionary fixture the
+  message blamed a 7 KB text file. The dictionary is a property of the archive,
+  not of the entry, so it now has its own status (`ZIPX_ERR_LIMIT_DICT`), its own
+  i18n code (`extract_dict_too_large`, en + zh) and the real numbers, which
+  unrar hands over in the `UCM_LARGEDICT` callback: *"needs 8192 MiB (limit
+  4096 MiB)"*.
+- The **behaviour is unchanged on purpose**: we still refuse, matching what
+  rarlab's own CLI does by default ("8 GB dictionary exceeds the 4 GB limit and
+  needs more than 8 GB of memory; use -md8g or -mdx8g"). Answering `1` to
+  `UCM_LARGEDICT` would only move the problem into `Unpack::Init()`, which
+  allocates the whole dictionary in one block — on a 16 GB console that trades a
+  clean error for an OOM-kill of the payload mid-extraction. Note also that
+  **RAR 5.0 headers cannot express more than 4 GiB** (four dictionary bits,
+  `arcread.cpp:871`), so only RAR7 headers can reach this path at all.
+- `tests/test_rar_extract.c:test_dict_limit` + a new synthetic fixture
+  `tests/fixtures/dict-8g.rar` (built by `tests/make_fixtures.py:bigdict()`,
+  which writes a minimal valid RAR5 archive by hand: no compressor can produce
+  such a header, and `Rar.exe 7.23` refuses to create RAR7 archives — `-ma4`,
+  `-ma6`, `-ma7` all exit 7). Verified independently with rarlab's own tools:
+  `UnRAR lt` reports `-md=8g` and `UnRAR t -mdx12g` extracts it cleanly.
+
+- **`err_extract_unsupported` copy was two releases out of date.** It read
+  *"only plain ZIP, single-volume RAR, and 7z are supported"* — the exact
+  inverse of what the build does now, because encrypted archives and
+  multi-volume RAR are both supported. The label now names what is actually
+  accepted (`.zip` / `.rar` / `.7z`, including their multi-volume and
+  encrypted forms); the backend's own sentence, which carries the real cause,
+  is still appended after it. The same stale wording in both READMEs is
+  corrected too. `.rodata` +0x40 (64 B), nothing else changed.
+
+- **The password prompt never appeared for an archive in a non-ASCII folder
+  — the user only ever saw the failure alert.** The retry that asks for a
+  password was looked up by *path*, and paths are not stable across the wire:
+  the server escapes every byte ≥ 0x80 as `\u00XX` when it serialises a name
+  and `fs_path_value()` maps those back to raw bytes when it receives one, so
+  the string the page holds for a directory and the string the task reports back
+  differ for every name that is not pure ASCII. The lookup missed, the retry
+  returned false, and the plain "extract failed" box was shown instead — the
+  archive had to be extracted again by hand before the prompt would appear. The
+  remembered request is now keyed by **task id**, which the server assigns and
+  which survives the round trip untouched; the retry also re-sends the path the
+  *server* reported rather than the one the page was holding. On-device symptom:
+  upload `x.zip` into a Chinese-named folder, choose "upload and extract" → no
+  prompt, then the raw error.
+
+- **Entry names in error messages were unreadable mojibake** —
+  `解压失败: 密码错误，或压缩包未使用所提供的密码加密: â®…ç§.psd (entry is
+  encrypted and no password was given)`. The listing has always translated the
+  byte-mapped names back through `decodeFsText()` for display, but
+  `backendErrorText()` used the raw `error_arg` — the one place where the name
+  matters most. Both `error_arg` and the backend's own sentence now go through
+  the same translation, so a GBK name stored inside a ZIP reads as Chinese
+  again.
+
+- **An archive with a non-ASCII name inside a non-ASCII folder could not be
+  extracted after upload.** `uploadAndExtractFile()` joined the byte-mapped
+  directory with the real Unicode file name, producing a mixed path; the server
+  only byte-repairs a string when *every* non-ASCII code point in it is ≤ 0xFF,
+  so one CJK character made it skip the repair and look for a path that does not
+  exist. `encodeFsText()` (the inverse of `decodeFsText()`) now byte-maps the
+  name before the join, which is also applied to the path `New Text` hands to
+  the editor. Pure-ASCII paths and pure-real-Unicode paths were unaffected,
+  which is why this survived until someone hit the mixed case.
+
+- **The upload menu's row highlight painted as a broken shape.** Selecting a
+  row drew a 3px blue ring at `outline-offset: 2px` that cleared the panel's
+  6px padding, overlapped the row above, and kept the row's own 6px corner
+  radius instead of growing with the offset — so the highlight read as a
+  detached outline with two arcs hanging off its sides rather than a selected
+  row. Two rules were fighting. The ring came from the generic `button:focus`
+  rule, which is sized for a 54px toolbar button and was never meant to reach a
+  46px list row. Underneath it, the panel's own
+  `.upload-menu-list button:hover:not(:disabled)` fill had **never applied at
+  all**: it ties on specificity (0,3,1) with the generic
+  `button:not(.row-action):hover:not(:disabled)` rule and that one comes later
+  in the file, so it won the cascade — hover and focus therefore ended up two
+  different colours (`#303945` against `#2b343e`), and a hovered row lit up
+  while the keyboard-focused row stayed lit, which is what made two rows look
+  selected at once. Both rules are now scoped to the panel id, rows highlight
+  by fill alone, and the keyboard cue is a 2px **inset** ring drawn inside the
+  row, where it cannot cross the panel edge at any row height.
+
+### Tests
+
+- `tests/test_zip_extract.c` runs each encrypted fixture four ways (no
+  password → `PASSWORD`, empty → `PASSWORD`, wrong → `PASSWORD`, correct →
+  `ZIPX_OK` with a byte-level content check), plus a case proving the
+  limits still apply when a password has been handed over.
+- `tests/test_rar_extract.c` exercises `enc-v6.rar` the same way, including
+  that nothing is published on the failing paths.
+- `tests/test_sevenz_extract.c` runs `aeshe.7z` three ways: no password →
+  `ZIPX_ERR_PASSWORD`, wrong password → `ZIPX_ERR_PASSWORD`, correct password
+  → success with the content compared byte for byte, and no staging tree left
+  behind on any of them.
+- `.build/ui_retry_test.mjs` loads the real `assets/main.js` into a stubbed DOM
+  and checks the frontend retry flow: the request is remembered with its
+  conflict policy and large-file flag, a failure retries with the typed
+  password, cancel and empty input give up, and the retry count caps at three.
+  It also carries the regression case for the missing prompt: a task whose
+  `src`/`dst` come back byte-repaired (a non-ASCII folder) must still be retried,
+  and a structural check that no retry entry is keyed by a path. **40 checks,
+  0 failures.**
+- `.build/ui_upload_menu_test.mjs` is the markup-side counterpart: it asserts
+  that every `data-i18n` key in `index.html` exists in both language files, that
+  the two language files carry the same keys, that the upload menu and the drag
+  hint exist and start hidden, that the removed file/folder split is gone from
+  both the markup and the stylesheet, that the click handlers are bound to the
+  new ids, and that the classes the markup uses are actually styled. Four of its
+  checks pin the row-highlight cascade: the hover and focus rules must be scoped
+  to the panel, the row ring must be suppressed, the keyboard cue must be an
+  inset shadow, and the unscoped forms must not come back — a rule that silently
+  loses the cascade is exactly the kind of thing a static check can still catch.
+  A further group covers the extract button, which is now always on screen: the
+  markup must not hide it, main.js must never assign to `extractBtn.hidden`, the
+  disabled rule must keep the tooltip hoverable, and there must be a message for
+  each reason it can be unavailable. One check sweeps the other direction —
+  every `t("...")` literal in `main.js` (117 keys) must exist in both language
+  files — because a key reached only from script code is invisible to the markup
+  sweep, which is how a message goes missing unnoticed.
+  **40 checks, 0 failures.** Both scripts are hand-run — the project has no
+  browser test runner — but each one exits non-zero on failure.
+- `.build/preview_build.py` + `.build/preview_check.mjs` render the real page
+  against a fixture API in headless Chromium and assert what a screenshot alone
+  cannot: the menu is hidden at rest, opens on click, moves focus into the list,
+  reaches the hidden `<input type="file">`, and closes on a choice, an outside
+  click and Escape. It reads back the *computed* highlight for a focused, a
+  hovered and a keyboard-focused row, which is the only way to settle a cascade
+  question — a rule losing to a generic one and a ring leaking out of its
+  container both look fine in the source. It is how the three layout/highlight
+  mistakes of this round were caught (a hint that pushed the toolbar onto a
+  second row, a status line that wrapped out of the footer, and the broken row
+  highlight described under Fixed).
+- Host totals: **140 ZIP + 37 RAR = 177 checks**, 0 failures.
+- 7z totals: **27 cases, 0 failures** (`tests/run-sevenz-tests.sh`), and the
+  `KNOWN_GAPS` list that held `aeshe` is now empty — the encrypted-header
+  fixture passes through both the folder decoder and the extraction facade.
+
+### Still open
+
+- End-to-end validation of the built ELF on a real console.
+
+## [v1.9] — 2026-09-05
+
+**RAR engine replaced: rarlab UnRAR 7.20.1 (v6 / multi-volume / decryption-capable).**
+
+The vendored dmc_unrar 1.7.0 only dispatched RAR5 compression version 5
+(`switch(file->version)` case `0x5000`). Archives written by WinRAR 6.x /
+7.x (algorithm string `v6`, version field `0x5001`) hit the default branch
+and surfaced as "corrupt archive" — confirmed on a real `v6:8M` archive.
+v1.9 swaps in the official rarlab UnRAR source (7.20.1) via its
+C-compatible DLL API, compiled as a static library (`-DRARDLL`, PS5 uses
+the toolchain's default `libc++`).
+
+What this enables:
+
+- **RAR5 "v6" compression** (WinRAR 6/7 archives) — the v1.9 trigger.
+- **Multi-volume RAR** (`.partNN.rar`): unrar stitches volumes by name when
+  all parts sit next to the opened volume. Select the first volume
+  (`name.part1.rar`) and extract as usual.
+- RAR4 and older RAR5 remain supported.
+- The engine *can* decrypt encrypted archives (`RARSetPassword`), but the
+  password channel (API + UI) is not wired yet — encrypted headers/entries
+  still fail up front with `err_extract_unsupported`. Planned for a follow-up.
+
+Engine changes:
+
+- `src/rar_extract.c` rewritten to unrar's sequential DLL API
+  (`RAROpenArchiveEx → RARReadHeaderEx → RARProcessFile`); scan and extract
+  each re-open the archive. Multi-volume continuation segments
+  (`RHDF_SPLITBEFORE`) are advanced but not re-counted/deduped.
+- The three-phase scan → staging → publish/rollback machinery is unchanged.
+- Bug fix: `normalize_name()` no longer clears the caller's directory flag
+  (a real v6 archive with an explicit directory header after its files
+  tripped the duplicate detector).
+
+Build & test:
+
+- Makefile: `.cpp` rules for the unrar RARDLL source set (49 files, mirrors
+  `UnRARDll.vcxproj`); links through the C++ driver; `VERSION_TAG` v1.9.
+- tests: 5 real RAR fixtures committed under `tests/fixtures-real/`
+  (generated with `tests/make-rar-fixtures.bat` + WinRAR); new happy-path
+  checks extract a real v6 archive, verify files on disk, auto-merge a
+  3-volume split, and reject encrypted archives. Total: **70 ZIP + 24 RAR
+  = 94 checks** (up from 70 + 14; the old 14 RAR checks never ran a real
+  archive).
+
+Credits: unrar (c) Alexander Roshal, freeware license — see
+`third_party/unrar7/license.txt` and `THIRD_PARTY_NOTICES`.
+
+## [v1.8.3] — 2026-09-05
+
+**Hotfix: "Upload and extract" now accepts `.rar` files.**
+
+The "upload and extract" entry was hard-coded to accept only `.zip`,
+even though the server-side dispatch in `src/extract.c:79` already
+correctly routes `.rar` to `rar_extract()`. v1.8.3 fixes the frontend
+filter so users can select a single-volume plaintext `.rar` from the
+file picker and have it uploaded + extracted in one click (the same
+flow that already worked for `.zip`).
+
+What this enables:
+
+- Choose a single-volume `.rar` from "Upload and extract"
+- Server extracts it via the existing `rar_extract()` engine
+- Uploaded `.rar` is auto-deleted after a successful extract (same as
+  `.zip` since v1.7)
+
+What this does **not** enable (planned for v1.9.0):
+
+- **Multi-volume RAR** (e.g. `name.part01.rar` + `name.part02.rar` …)
+- **Encrypted RAR** (password-protected headers or entries)
+
+Both still return `extract_unsupported` "single-volume RAR only" /
+"encrypted RAR is not supported; please extract on a PC first" — see
+the underlying engine limit in `third_party/unrar/dmc_unrar` (GPL-2.0,
+1.7.0). v1.9 will swap the vendor to **opello/unrar 7.20.1** (UnRAR
+License) which natively supports both.
+
+Changed:
+
+- `assets/index.html` — `<input id="uploadZip" accept>` now lists
+  `.rar` + the two RAR MIME types next to the existing ZIP entries.
+- `assets/main.js:2340` — `/\.zip$/i` → `/\.(zip|rar)$/i` (the upload
+  pre-check), plus a local `isRar` flag so the next step branches.
+- `assets/lang-en.js` — `extractUploadConfirm`: "uploaded ZIP" →
+  "uploaded archive".
+- `assets/lang-zh.js` — `extractUploadConfirm` & `extractLargeAsk`
+  drop the "ZIP" wording so the copy reads sensibly for RAR uploads.
+- `assets/main.js:38` — `APP_VERSION` `"v1.7"` → `"v1.8.3"` (footer
+  version string had been hard-coded to v1.7 since the frontend was
+  first imported; it no longer misleads about which build is running).
+
+No backend changes — the server side was already correct. No test
+changes — the existing RAR happy-path test in `tests/test_rar_extract.c`
+passes against the same backend.
+
+Build pipeline (also v1.8.3):
+
+- `.build/build-elf.sh` step 6 "no source change → skip make" check now
+  also watches `assets/*` and `gen-asset-module.py`, not just `src/*.c`
+  and the `Makefile`. Without this, v1.8.3 (which touched no backend,
+  only frontend assets feeding `gen/*.c`) was misclassified as "no
+  change" and `make` was skipped — the result was that the v1.8.2 ELF
+  was reported as v1.8.3 with the same sha256. With this fix, only
+  frontend changes correctly trigger a rebuild. Users running the WSL
+  build need to re-copy `.build/build-elf.sh` to `/home/song/build-elf.sh`
+  (canonical source is on the Windows side).
+
+## [v1.8.2] — 2026-09-05
+
+**Hotfix: default ZIP extraction limits cover 3A-game single-file archives.**
+
+The default `k_default_limits` profile is now **2 TiB total / 512 GiB per
+entry / 500 : 1 ratio** (was 1 TiB / 256 GiB / 500 : 1 in v1.8.1). The
+frontend threshold `LARGE_FILE_THRESHOLD_BYTES` is bumped from 240 GiB to
+**480 GiB** to match. The `large=1` profile is widened to **4 TiB total
+/ 1 TiB per entry / 1000 : 1 ratio** (was 2 TiB / 1 TiB / 1000 : 1); the
+large profile must always be strictly more permissive than default.
+
+Why: a 3A-game archive with a single ~300 GiB uncompressed file was
+**silently rejected by the default profile** (`scan_archive` returns
+`ZIPX_ERR_LIMIT_FILE_SIZE` in `src/zip_extract.c` line ~717 — the request
+never reaches the frontend confirmation prompt, so the user just sees
+"卡壳"). The 256 GiB default cap was tuned for PS5 system backups (which
+have many smaller entries, not a single huge file) and was wrong for the
+3A-game single-file case. The default cap is now 512 GiB so a typical
+3A archive extracts under the default profile without prompting.
+
+The safety argument is unchanged from v1.8.1: zip-bomb defence is
+`check_space()` (`statvfs`-based real disk space check before staging) +
+`max_ratio` (declared compression ratio cap). The size caps are a UX
+guard, not a security boundary.
+
+RAR extraction inherits the new defaults automatically — rar_extract.c
+threads `c->limits` through from the engine, so no rar-side change is
+required.
+
+### Changed
+
+- `src/zip_extract.c` — `k_default_limits` relaxed:
+  - `max_total_bytes`: 1 TiB → **2 TiB**
+  - `max_file_bytes`: 256 GiB → **512 GiB**
+  - `max_ratio`: 500 → **500** (unchanged)
+- `src/zip_extract.c` — `k_large_limits` widened (must stay > default):
+  - `max_total_bytes`: 2 TiB → **4 TiB**
+  - `max_file_bytes`: 1 TiB → **1 TiB** (unchanged)
+  - `max_ratio`: 1000 → **1000** (unchanged)
+- `assets/main.js` — `LARGE_FILE_THRESHOLD_BYTES`: 240 GiB → **480 GiB**
+- `assets/lang-{en,zh}.js` — `extractLargeAsk` copy updated to reflect
+  the new numbers (default 512 GiB / 2 TiB; large 1 TiB / 4 TiB)
+- `tests/test_zip_extract.c` — `test_large_profile` advertised-number
+  assertion updated: `max_total_bytes == 4 TiB` (was 2 TiB)
+- `README.md` — both limit tables (ZIP + RAR), the "Tuning the threshold"
+  snippet, and the `err_extract_entry_too_large` FAQ entry bumped to the
+  new numbers
+- `docs/HANDOVER.md` — `LARGE_FILE_THRESHOLD_BYTES`, the
+  `k_default_limits` / `k_large_limits` ASCII diagram, the user-scenario
+  description, the 480 GiB popup note, and the RAR limits paragraph
+  bumped to the new numbers
+
+### Unchanged
+
+- `src/rar_extract.c` — already threads `c->limits` from the engine,
+  picks up the new defaults for free
+- `max_ratio` — both profiles unchanged (500 : 1 default / 1000 : 1 large)
+- `check_space()` — unchanged; still the real disk-space guard
+- `max_entries` — 200 000 default / 500 000 large, unchanged
+- `docs/UPGRADE-v1.7-zip-large-file-profile.md` — historical v1.7
+  document left as-is so the v1.7 → v1.8.2 evolution is traceable
+- Test fixture `medium_bomb.zip` (ratio ≈ 238) still exercises both
+  rejection under the default 500 : 1 cap and acceptance under the
+  `large=1` 1000 : 1 cap
+- 84 host-side checks (70 ZIP + 14 RAR), 0 failures
+
+### Migration notes
+
+- **Forward-compatible** — users with v1.8.1 deployments who never trigger
+  `err_extract_entry_too_large` see no difference (defaults are strictly
+  more permissive)
+- **3A-game single-file archives now extract silently** — no prompt, no
+  manual `large=1` API call required for files up to 512 GiB
+- **No data loss** — the relaxation only widens accepted archives; the
+  real security guards (`check_space`, `max_ratio`, `path traversal`)
+  are untouched
+- **No frontend UX change for typical use** — only archives > 480 GiB
+  on disk now trigger the confirmation prompt (previously 240 GiB)
+
+---

 ## [v1.8.1] — 2026-09-05

@@ -0,0 +1,543 @@
+# 交接文档 — ps5-web-file-manager 工作进度
+
+> 交接时间：2026-09-23 · 分支 `main` · 最新提交仍是 **`3f80eb4`**（tag `v1.9.2`）——**本轮加密改动全部尚未提交**
+>
+> **主线（用户 2026-09-12 指令）**：「先从 zip 分卷开始吧，然后把六种组合打齐，并把密码通道补齐，注意一些报错信息提示的时候尽量详细准确」
+> **状态：主线全部闭合，且格式面已无已知缺口。** 六种组合（ZIP/RAR/7z × 单卷/分卷）+ 密码通道（ZIP ZipCrypto/AES + RAR `-p`/`-hp` + 7zAES **含 `-mhe=on` 加密头**）+ 报错详细信息，全部落地、测试全绿、PS5 ELF 构建成功。
+> **剩余**：① PS5 真机端到端验证（**唯一还没过的关卡**）；② 版本号仍是 `v1.9.2`，本轮改动处于「未发布」状态——发版需先升 `VERSION_TAG` 与 `APP_VERSION_FALLBACK`。
+
+---
+
+## 一、当前状态速览
+
+| 维度 | 状态 |
+|---|---|
+| 解压引擎 | ZIP / RAR / 7z × 单卷/分卷（6 组合）+ 三种加密（ZIP ZipCrypto/WinZipAES、RAR `-p`/`-hp`、7zAES 与 `-mhe=on` 加密头）全部打通 |
+| 主机测试 | **ZIP 140 + RAR 37 = 177 checks，0 失败**（MinGW gcc；2026-09-23 复跑）+ 7z 套件 **27 用例 0 失败**（`KNOWN_GAPS` 已清空）+ 前端重试流程 27 checks（`.build/ui_retry_test.mjs`） |
+| PS5 构建 | ✅ WSL prospero-clang 18.1.8，一键脚本可复现；构建已实测**确定性**（同源两次构建 sha256 相同） |
+| ELF 产物（工作树，未提交） | `web-file-mgr-v1.9.3M.elf` · 903,448 B · sha256 `8ca47d5aaca75085b32641300cce30fadb7df7749cb6b53d04f129bcecc286b7` · e_machine=0x003e（2026-09-24 最后一轮：上传菜单 + 拖拽提示 + 口令重试改按键 id + 错误文案编码修复 + 菜单行高亮的层叠修复 + 解压按钮常显置灰；**未发布**） |
+| 已发布产物 | `web-file-mgr-v1.9.2.elf` · 870,488 B · sha256 `177e90fecf93a0251e83f67884fba4551051be248330b0d70fda8ea732f88e84`（不含加密改动） |
+| GitHub | `main`（`3f80eb4`）与 tag `v1.9.2` 均已推送；Release `v1.9.2` 资产对应上一行；本轮改动尚未 commit |
+| 已知功能缺口 | **无**（`-mhe=on` 已于 2026-09-23 补齐） |
+
+### 发布命令（v1.9.2）
+
+```bash
+cd "/c/Users/songl/Desktop/Web File Manager/ps5-web-file-manager"
+
+git push origin main
+git push origin v1.9.2
+
+gh release create v1.9.2 web-file-mgr-v1.9.2.elf \
+  --repo LisherSong/ps5-web-file-manager --title "v1.9.2" --notes-file <notes.md>
+```
+
+沙箱内 git 出站 HTTPS **可用**（早先记的"被拦"是误判：`timeout 25 git ...`
+命中的是 `C:\Windows\System32\TIMEOUT.EXE`，报参数错误而非网络错误）。`gh` 同样可用，
+所以 commit / tag / push / 发 Release 都可以在会话里直接跑。
+
+---
+
+## 二、本轮（2026-09-15）变更
+
+### 2.1 一键构建脚本（`a54f34b` / `5229cd5`）
+
+| 文件 | 跑在哪 | 作用 |
+|---|---|---|
+| `.build/build-win.sh` | Windows Git Bash | 入口：把 WSL 脚本经 **stdin** 喂给 `wsl.exe`，透传退出码 |
+| `.build/build-elf-wsl.sh` | WSL Ubuntu-22.04 | 5 阶段：环境检查 → rsync 同步 → `make all` → 验证 → 拷回 Windows |
+| `.build/build-elf.sh` | WSL 内 | **仅首次搭环境用**（libmicrohttpd staging 安装 + sudo） |
+
+```bash
+# Windows 端（注意：必须 /usr/bin/bash，裸 bash 会解析成 WSL 启动器）
+cd "/c/Users/songl/Desktop/Web File Manager/ps5-web-file-manager"
+/usr/bin/bash .build/build-win.sh
+
+# 或 WSL 内
+bash /home/song/build.sh
+```
+
+**两个关键实现点**（改脚本前必读）：
+- `wsl.exe -- bash -c '...'` 遇到含空格路径会被拆断 → 必须 `wsl.exe -- bash < script.sh`（stdin 重定向）
+- `make ... | tail` 会吞掉退出码 → 用 `${PIPESTATUS[0]}`；否则编译失败还会继续跑验证，输出假成功
+
+### 2.2 版本号体系统一（`f4fd464` / `1fa2f09` / `0d036a7`）
+
+原本版本号有**两个真相来源**，已经漂移过：`Makefile` 写 `v1.9.1`，`assets/main.js` 硬编 `"v1.9"`，UI 右下角在整个 v1.9.1 发布期都显示旧值。
+
+现在收敛到 `Makefile` 一处：
+
+```make
+VERSION_TAG ?= v1.9.3M           # 可用 make VERSION_TAG=v1.9.3 临时覆盖
+BIN        := web-file-mgr-$(VERSION_TAG).elf
+```
+
+改这一行会同时影响 **四处**：ELF 内嵌版本串、PS5 启动通知、输出文件名、UI 右下角。
+
+**尾部 `M` = 改版标记（Modified，LisherSong 维护）**，从 v1.9.3M 起启用。上游
+owendswang 的发布版是纯 `vX.Y.Z`，故「带 M = 本仓、不带 = 上游」一眼可分。它刻意
+挂在 `VERSION_TAG` 上而不是做一个只管显示的独立常量：这样 `/api/version`、启动通知、
+stdout 横幅、UI 右下角、ELF 文件名**五处一次性全覆盖**，不可能只在其中一处漏掉。
+附带好处是产物名不再可能与上游同版本号的资产撞车（此前已撞过两次：本地
+`web-file-mgr-v1.9.2.elf` 与线上同名资产并存；`-DVERSION_TAG=v1.9.1` 的残留产物
+和已发布的 870 488 B 文件尺寸相同）。
+
+| 提交 | 内容 |
+|---|---|
+| `f4fd464` | `VERSION_TAG` `v1.9` → `v1.9.1`；`.gitignore` 改白名单式（`.build/*` 全忽略 + `!` 放行 6 个脚本），`.workbuddy/` 也忽略 |
+| `1fa2f09` | 输出文件名派生自 `VERSION_TAG`；`build-elf-wsl.sh` 从 Makefile 反读版本（不硬编）；`build-win.sh` 每次都推 WSL 脚本（原来只在缺失时推，导致改了脚本 WSL 侧仍跑旧版） |
+| `0d036a7` | **新增 `/api/version`**，前端右下角改从后端取值（见 2.3） |
+
+⚠️ **`assets/main.js` 里还有第二处字面量** `APP_VERSION_FALLBACK`（`/api/version` 取不到时的兜底值）。
+它不在 Makefile 的控制范围内 —— **升版本号时必须一并改**，否则后端请求失败时页脚会显示旧版本。
+v1.9.2 就是这两处一起改的。
+
+### 2.3 UI 版本号改由后端提供（`0d036a7`）
+
+**问题**：`assets/main.js:38` 的 `const APP_VERSION = "v1.9"` 与 Makefile 无关，必然漂移。
+
+**修法**：
+- 新 `src/version.c` — `GET /api/version` → `{"ok":true,"version":"v1.9.2","titleId":"FMGR88888"}`，直接来自 Makefile 已传的 `-DVERSION_TAG` / `-DTITLE_ID` 宏，没有第二处要记得改
+- `src/filemgr.c` 路由表加一行（紧邻 `/api/space`）+ `filemgr_internal.h` 声明 + `Makefile` `COMMON_SRCS`
+- 前端：字面量降级为 `APP_VERSION_FALLBACK`（先渲染，保证页脚不空），`loadVersion()` 后台刷新。**请求失败静默吞掉** —— 版本号显示错属于装饰性问题，不该弹错误 toast
+
+**踩坑**：新文件漏了 `#include "json_util.h"` → `strbuf_append` / `json_escape` 隐式声明报错。`space.c` 是模板，照抄时别漏。
+
+---
+
+## 三、功能矩阵与测试
+
+### 3.1 六种组合 + 密码通道
+
+| # | 引擎 | 单卷 | 分卷 | 密码 |
+|---|---|---|---|---|
+| ① | ZIP | ✅ | ✅ 三种命名约定 | ✅ ZipCrypto + WinZip AES-128/192/256（2026-09-23 打通，此前 `mz_zip.c` 的加密分支没有后端可调） |
+| ② | RAR | ✅ | ✅（vendor unrar 7.20.1） | ✅ `RARSetPassword`（`-p` 与 `-hp` 头加密；2026-09-23 接线，此前从未被调用） |
+| ③ | 7z | ✅ | ✅ `.7z.001` | ✅ 7zAES（v1.9 起就有）+ `-mhe=on` 加密头（2026-09-23 打通，见 §八） |
+
+### 3.2 测试
+
+```bash
+export PATH="/c/mingw64/bin:/c/Users/songl/.workbuddy/binaries/PortableGit/versions/1.2.0/mingw64/bin:/c/Users/songl/.workbuddy/binaries/python/versions/3.13.12:/usr/bin:/bin:/c/Windows/System32:/c/Windows"
+cd "/c/Users/songl/Desktop/Web File Manager/ps5-web-file-manager"
+/usr/bin/bash tests/run-tests.sh          # ZIP 140 + RAR 37 = 177
+/usr/bin/bash tests/run-sevenz-tests.sh   # 7z 27（KNOWN_GAPS 已清空）
+
+# 前端「密码失败后重试」流程（桩 DOM，无需浏览器）
+"/c/Users/songl/.workbuddy/binaries/node/versions/22.22.2-3/node.exe" .build/ui_retry_test.mjs   # 27
+```
+
+⚠️ **绝不写裸 `bash`** —— 可能解析到 `C:\Windows\System32\bash.exe`（WSL 启动器），脚本跑进 Linux，gcc/python 全变 Linux 版，报莫名错误。必须 `/usr/bin/bash`。
+
+`run-sevenz-tests.sh` 带 `KNOWN_GAPS` 列表（当前仅 `aeshe`），缺口修好后脚本会主动报错，防止列表腐烂。脚本**不做任何删除**（safe-delete 钩子会拦 `rm -rf`）。
+
+---
+
+## 四、构建（PS5 ELF）
+
+### 4.1 日常构建
+
+```bash
+cd "/c/Users/songl/Desktop/Web File Manager/ps5-web-file-manager"
+/usr/bin/bash .build/build-win.sh
+```
+
+增量有效（`ps5-obj/` 缓存保留）→ 二次构建 30s–2min。**别 `make clean`**（全量重编第三方 3–5min）。
+
+产物：项目根 `web-file-mgr-<VERSION_TAG>.elf`，同时留在 WSL `/home/song/ps5-web-file-manager/`。
+
+### 4.2 验证清单
+
+```bash
+ls -lh web-file-mgr-v1.9.2.elf
+sha256sum web-file-mgr-v1.9.2.elf
+od -An -tx2 -j18 -N2 web-file-mgr-v1.9.2.elf   # 期望 3e00
+strings -a web-file-mgr-v1.9.2.elf | grep -m1 '^v1\.'
+```
+
+⚠️ `od -An -tx2` 打印的是**小端 short 的值**（`003e`），不是字节序（`3e00`）。脚本里比对用 `$((16#$EM))` 转数值（**62 = x86-64 ✅ / 183 = aarch64 ❌**）。
+
+✅ **构建已实测可复现**（2026-09-20）：同一源码树两次构建 sha256 完全相同；把两处版本字面量回退成 `v1.9.1` 后重构，产物与已发布的 v1.9.1 ELF **逐字节一致**。所以 sha256 可以作为交付指纹用 —— 但它对任何源码改动都会全变（改一个字符串常量会令链接器重排 `.rodata` 字符串池，牵动 `.text` 里所有 RIP 相对位移，原始 diff 会放大到 5 万字节以上，属正常现象，别误判成"代码改了"）。核对版本仍推荐 `strings ... | grep '^v1\.'`，最直观。
+
+### 4.3 构建坑（已修，改 Makefile 前必读）
+
+`third_party/7z/AesOpt.c` 用编译器版本宏判断是否启用 AES-NI / AVX / VAES，clang 18 直接进 VAES 分支，但 prospero-clang 默认 target 是 generic x86_64 → `_mm256_aesenc_epi128` 未声明，20 报错。
+
+- ❌ **不能** `filter-out AesOpt.c` —— `Aes.c` 通过 `AesGenTables` 引用 `AesCbc_Encode_HW` 等符号，会链接失败
+- ✅ **正解**：路径过滤 `SEVENZ_C_FLAGS := -maes -mavx2 -mvaes`，仅 `third_party/7z/*.c` 用。PS5 是 Zen 2，硬件全支持，运行时无差异
+
+---
+
+## 五、7z 引擎设计要点（改代码前必读）
+
+### 5.1 为什么不走 SDK 的解码器
+
+LZMA SDK 26.03（public domain，已 vendor 到 `third_party/7z/`，解码子集 60 文件）有两个硬限制，**实测复现过**：
+
+1. **`CSzFolder` 上限 4 coder / 3 bond** —— 7-Zip 默认 `-m0=bcj2` 链 = BCJ2 + 4×LZMA2 = 5 coder，`SzAr_DecodeFolder()` 返回 `SZ_ERROR_UNSUPPORTED`。注意 `SzArEx_Open()` 用的是另一套宽松扫描器（`k_Scan_NumCoders_MAX 64`），所以**文件列表和解压尺寸仍然全对**，失败只在解压时按条目暴露
+2. **C 解码器完全没有 7zAES coder** —— 所以 SDK 自己既解不了加密内容，也解不了加密头。内容侧由我们的 `sevenz_chain.c` 承担；**头部**侧由 `sevenz_header.c` 承担（见 §八）
+
+→ 因此引擎**自解析 folder blob + 自己驱动 codec 链**（`src/sevenz_chain.c/.h`，pull pipeline：`node_pull(n, dst, want, &got)`，不够就 `node_refill()` 拉上游）。
+
+### 5.2 最关键的坑
+
+**【必记】每个 coder 节点的 `out_size` 必须取 `coder_unpack_sizes[index]`，绝不能用 folder 的 unpack size。** BCJ2 folder 里 MAIN 常大于 folder 最终尺寸（实测 300066 > 300000）。用错的症状：每层 LZMA2 静默短 21 字节，只在特定包上暴露。
+
+其他：
+- 编译必须 `-DZ7_PPMD_SUPPORT`，否则 `7zDec.c` 直接丢掉 PPMd
+- `CoderUnpackSizes` 是**扁平数组**（每条 = 对应 coder 输出流大小），**非累计**；`FoToCoderUnpackSizes[f]..[f+1]` 是该 folder 的切片
+- main coder = 第一个未被 bond 消费的 coder
+- `SzArEx_Extract` 失败后会把半成品留在 block cache → 后续条目报**假 CRC**，要重置 `blockIndex`
+- 造夹具用 Extra 包的 `7za.exe`（有 PPMd）；**`7zr.exe` 没有 PPMd 编码器**
+- 调试三件套在 `.build/`：`chainprobe.c`（摸内部图）、`chainprobe2.c -r <coder>`（强制 root 逐层二分）、`chaincheck.py`（Python liblzma 独立复现同一条链，秒判"图错"还是"循环错"）
+
+### 5.3 7zAES KDF
+
+`numCyclesPower = b0 & 0x3F`；`saltSize = ((b0>>7)&1) + (b1>>4)`；`ivSize = ((b0>>6)&1) + (b1&0x0F)`，随后依次 salt → iv。
+`numCyclesPower == 0x3F` 时 key = `salt||password` 补齐/截断到 32 字节；否则 `key = SHA256(salt || password_utf16le || counter_le64)` 迭代 `1<<numCyclesPower` 次。之后 AES-256-CBC。
+限额 `max_aes_cycles = 24`（约 8s）。
+
+**改引擎前先在 `.build/aesprobe.c` 独立验证 KDF**（用 vendor 的 `Sha256.c` + `Aes.c` 解 aes.7z coder0，与 `cus[0]=638314` 比对），确认后再集成。
+
+### 5.4 分卷流抽象
+
+- `src/zipx_volstream.c/.h`（ZIP，包成 `mz_stream`）· `src/sevenz_volstream.c/.h`（7z，包成 SDK `ISeekInStream`）
+- **结构体首成员必须是 `mz_stream stream;` / `ISeekInStream vt;`**（回调把 `void*` 强转）
+- `vol_is_open()` 必须返回 `MZ_OK`/`MZ_OPEN_ERROR`（**不是 1/0**）
+- vtbl **必须注册 `destroy`**，否则 `mz_stream_delete()` 不回调 → 泄漏
+- CONCAT 模式对 `DISK_NUMBER`/`DISK_SIZE` 返回 `MZ_PARAM_ERROR` → 让 minizip 不切盘
+- DISK 模式 `set_prop(DISK_NUMBER, -1)` 必须切到**最后一卷**（minizip 路径 `mz_zip.c:2252-2275`）
+- `remove_source_archives()` 要删**所有**卷，避免孤儿卷
+
+### 5.5 提取门面
+
+`src/sevenz_extract.c`（1753 行）完全仿 `zip_extract.c` / `rar_extract.c`：scan → extract(staging，**不 fsync**） → publish(整 rename) → cleanup。
+
+- **OVERWRITE 与 MERGE 对目录-目录碰撞都递归下钻**（仅叶子文件不同）
+- 三方共用 `src/zipx_common.c`（限额 profile + `zipx_status_string()`）
+- scan 阶段**每 256 entries** 报一次进度（曾用 4096，小包扫描期 UI 静默），扫描末 force-report；`precheck_folders` 入口也强制报一次
+- 密码错时 detail **必须带 archive 名**（曾是 NULL → i18n `{arg}` 展开成空 → 用户看到「密码错误: 」后面光秃秃）
+
+---
+
+## 六、限额体系（ZIP 与 RAR 共用；7z 同源）
+
+| 限额字段 | default | large | 160GB/9万文件场景 |
+|---|---|---|---|
+| `max_entries` | 200,000 | 500,000 | 9 万 ✅ |
+| `max_total_bytes` | 2 TiB | 4 TiB | 160 GiB ✅ |
+| `max_file_bytes` | **512 GiB** | **1 TiB** | 20 GiB ✅ |
+| `max_ratio` | 500 | 1000 | 仅 ≥1GiB 条目受检 |
+| `ratio_min_bytes` | 1 GiB | 1 GiB | 小文件豁免 |
+
+- 切 large 档的触发条件：**压缩包文件本身** >480 GiB（`assets/main.js` `LARGE_FILE_THRESHOLD_BYTES`），160GB 包走 default
+- **ratio 有尺寸下限**（`ratio_min_bytes` = 1GiB）：小文件高压缩率合法常见（零填充/稀疏），且写出字节受"声明上限 + `check_space()`"双重约束，无害
+- **唯一真实失败点是磁盘空间**：`check_space()` 按**解压后总量**查 `statvfs`，峰值 = `zip 体积 + 解出体积`。分卷场景"传一卷解一卷删一卷"可降峰值
+- **32 位安全**：引擎内部 size 全 `uint64_t`；minizip `mz_zip.h:34-35` 的 `compressed/uncompressed_size` 是 `int64_t` → >4GiB 不截断
+- **已知 UX 缺陷（未修）**：进度条 % 用字节（`main.js:1985`）、文字进度解压时用条目数（`main.js:2014`）、ETA 用字节速度（`task.c:129-177`）。混合大包上割裂，建议统一为字节
+
+---
+
+## 七、环境要点（新人必读）
+
+- **PS5 是 x86-64 Zen 2**（不是 aarch64！），target triple `x86_64-sie-ps5`
+- **PS5 SDK C++ runtime = LLVM libc++**（FreeBSD 系 sysroot，无 libstdc++）→ C++ 必须 `-stdlib=libc++`，链接 `-lc++ -lc++abi`（Makefile 已处理：unrar 用 prospero-clang++ 编）
+- **PS5 SDK libc 的 `*at()` 族（mkdirat/openat/renameat/unlinkat）能链接但运行时损坏**：返回 -1 且 `errno=0`（2026-09-06 Frostpunk 2 真机确诊）。`zip_extract.c` 已有"*at() 失败回退全路径调用"兼容层；写新引擎代码时直接用全路径或沿用回退模式。报错要带 `(errno=%d)`，`errno=0` 时 `strerror` 会骗人
+- WSL：`export PS5_PAYLOAD_SDK=/opt/ps5-payload-sdk` 后才能 make
+- `target/user/homebrew/` 由 songl(197609) 拥有，WSL 身份 song(1000) 写不进 → staging 模式（make install 到 /tmp → `sudo cp -r`）
+- `//wsl$/Ubuntu-22.04/` 是 SMB 只读视图，改 WSL 文件必须走 Windows 路径
+- libmicrohttpd 必须 `--disable-https --disable-openssl`
+- **minizip-ng 4.2.2 补丁（升级会丢）**：`src/mz_strm_os_posix.c` L25 后插 `#ifndef O_BINARY / #define O_BINARY 0 / #endif`
+- **主机 POSIX shim（CP936 主机必需）**：`tests/posix_compat.h` 把 `lstat/stat → wfm_stat`、`opendir → _wopendir`（UTF-8 转换）、`fopen → _wfopen`。MinGW ANSI 入口看不见 UTF-8 文件名
+- 复杂 commit / tag message 用 `-F 文件`，不要 `-m` 长文本（bash quoting 会挂）
+
+---
+
+## 八、7z `-mhe=on` 加密头（2026-09-23 已闭合）
+
+**它为什么难**：`-mhe=on` 时整个 header 也是一条独立的 7z 流——归档末尾的下一头部区域以 `k7zIdEncodedHeader`（0x17）开头，后接一段 StreamsInfo，描述「一个 folder，其输出就是真正的 header」。而 vendored SDK 的 **C 解码器没有 7zAES coder**，`SzArEx_Open2()` 走到 `SzAr_DecodeFolder()` 就返回 `SZ_ERROR_UNSUPPORTED`，于是**连文件列表都读不出来**（文件名、folder 表、每个条目的尺寸全在那份加密头里）。
+
+**做法**（`src/sevenz_header.{c,h}`）：
+1. 自己读 32 字节 start header，只探**一个字节**——不是 0x17 就立刻 `SZH_PLAIN` 收工（普通的 `-mhc=on` 压缩头、`-mhc=off` 明文头都走这条，SDK 行为一字不变）。
+2. 是 0x17 就整段读下来（CRC 校验），**最小解析** PackInfo + UnpackInfo：pack 位置/大小、folder 的 coder 描述字节范围、每个 coder 的 unpack size、folder CRC。解析刻意宽容——任何异常一律回落 `SZH_PLAIN`，把诊断权留给 SDK，保证非加密归档的报错一字不改。
+3. 把这份描述喂给 **`sz_chain_parse()` / `sz_chain_decode()`**，也就是内容走的同一条 7zAES 路径，密码规则完全一致：需要密码而没给 → `SZH_ERR_PASSWORD`；解出来 CRC 不对 / 不是 `k7zIdHeader` → 同样是密码错。
+4. 造一个**虚拟 `ISeekInStream`**：`[0,32)` 是改写过的 start header（指向明文头），`[hdr_off, hdr_off+L)` 是解出来的明文头，其余一律透传真实归档。`hdr_off` 就用加密头原本所在的偏移，所以**归档里存的任何一个偏移都不用搬**——SDK 在它预期的位置读到明文头，从明文头推出的 dataPos 依旧指向真实的内容 pack 流。
+5. 交给 `SzArEx_Open()`，之后一切照旧（内容仍由 `sevenz_chain.c` 直接读 `sevenz_volstream`）。
+
+**要点/坑**：
+- 明文头比它替换掉的那条记录**长**（实测 aeshe.7z：记录 64 B、明文 462 B），所以虚拟流的 `total` 要取 `max(真实文件长度, hdr_off+L)`，否则 `SzArEx_Open2()` 的 seek-to-END 长度检查会报 `SZ_ERROR_INPUT_EOF`。
+- **`LookToRead2_INIT` 不 seek**，第一次 `Look` 从真实流当前位置读。`szh_prepare()` 会把流移来移去，所以交给 SDK 之前必须显式 seek 回 0（`sevenz_extract.c` 里那一段有注释）。这原本是个隐性依赖。
+- 明文头大小有上限（`SZH_MAX_HEADER` 64 MiB），sink 按需增长、不信头部里声明的 unpack size。
+- 只处理 `numFolders == 1`（SDK 自己对这条记录就传 `numFoldersMax = 1`）与 `external == 0`。
+
+**覆盖**：`tests/fixtures-7z/aeshe.7z`（密码 `Secret123`），`tests/run-sevenz-tests.sh` 的 `KNOWN_GAPS` 已清空——chain 驱动与 façade 两条路径都跑通；`test_sevenz_extract.c --cases` 另验无密码 / 错密码 → `ZIPX_ERR_PASSWORD`、正确密码 → 成功，且失败后不留 staging。
+
+### 真机端到端待验证
+
+ELF 已构建，但需装 PS5 实测：
+1. ZIP / RAR / 7z 三类**分卷**真机解压
+2. **加密 7z（7zAES + `-mhe=on` 加密头）** 真机解压（`aeshe.7z` 那类归档在真机上连文件列表都要走新代码）
+3. 160GB / 9.5 万文件大 ZIP
+4. 分卷 RAR 进度条实时走动
+5. UI 右下角版本号显示（`/api/version` 与兜底字面量应一致）
+
+> **📊 2026-09-23 首个真机性能数据**：解一个 **18 GB 的包**，**11 分钟**、**1252 个条目**
+> （平均 14.7 MB），UI 报 **10–40 MB/s**；**18 GB 是压缩包自身的大小**（✅ 已确认）。
+> **格式 = RAR**（✅ 已确认）；包原本在 **PC 上**，**经插件上传**进 PS5，**上传速度 30–40 MB/s**。
+> 口径是**解压后的字节**（`zip_extract.c:651-678` 累加 `uncompressed_size`，`:900/910` 累加
+> `write()` 写出的解压字节），且是 **250 ms 采样的瞬时值**（`task.c:202-206`，进度只在 ≥1 MiB
+> 时上报）—— 摆动里含采样噪声，**只有「总字节 ÷ 总耗时」可信**。
+> 仍然成立的一条：**per-entry 开销不是主因**（平均 14.7 MB/条目，不是小文件场景）。
+>
+> **⚠️ 2026-09-23 晚 更正：本节原先写的「解码不是瓶颈」已撤回。** 两条理由：
+> ① 它拿「PS5 解 **RAR**」的 28 MiB/s 去比「PC 解 **7z**」的 427 MiB/s —— **不同格式、不同
+> 解码器、不同机器**，量级论证不成立；② 「4× 摆动 = 解码无罪」此前已降级为 250 ms 采样
+> 噪声的弱证据。**原先那句「源盘交付速度 ≈ 28 MiB/s 是硬上界」同样站不住** —— 它是从总耗时
+> 反推的*观测结果*，不是设备能力上限；若解码是瓶颈，源盘恰恰没跑满。
+>
+> **③ 新发现（有据可查、且直接针对真实负载）：RAR 解码在 PS5 上是单线程的。**
+> `third_party/unrar7/os.hpp:43-45` 的 `#define RAR_SMP` 落在 `#ifdef _WIN_ALL` 分支**内**
+> ⇒ POSIX 构建不定义（我们 Makefile 里 0 次出现），而官方 POSIX makefile 第 11 行是
+> `DEFINES=… -DRAR_SMP` —— **我们漏了这个开关**。后果：`unpack50mt.cpp`
+> （`Unpack::Unpack5MT`，rarlab 专门调过的多线程 RAR5 解压器）**没编进来**，
+> `unpack.cpp:185-198` 的 MT 分支整段不参与编译，`SetThreads` / `ThreadPool` 一并消失。
+> ⇒ **首要假设：28 MiB/s ≈ 单线程 RAR5 解码的正常量级**（`18 GB ÷ 660 s` 是**解码输入**速率；
+> 而上传实测证明**写入端**至少能到 30–40 MB/s、**读取通常快于写入** ⇒ 纯存储上限解释不了它）。
+> ⚠️ 自查一条：**用 ELF 符号表查内部符号是无效手段** —— 该 ELF 只有 `.dynsym`（513 项）、
+> **无 `.symtab`**，「零命中」是假象（本次差点据此误判）。结论来自 Makefile 与 `os.hpp`。
+> **下一步**：先在 PC/WSL 上 A/B（`-DRAR_SMP` + `unpack50mt.cpp` + `-pthread`，跑同一批 RAR5
+> fixture 并保证 37 项 RAR 断言全绿），收益显著再上真机；同时真机补两个小事实
+> （**RAR4 还是 RAR5**、**解压后多大**）与 `T_copy`。详见 `docs/EXTRACTION-PERF.md` §六 文首
+> 更正块与 `docs/REAL-CONSOLE-PROFILE.md`。
+>
+> **⇒ 终局（2026-09-23 18:15，用户决定）：这条线不做。** 不做的依据是**当前证据判不了收益**，
+> 而不是没收益：MT 只并行**解码**（worker 只跑 `unpack50mt.cpp:190` 的 `UnpackDecodeThread`），
+> 写盘恒为主线程串行（`UnpWriteBuf()` 只在 `unpack50mt.cpp:283/475/587` 被主线程调用）——
+> 若瓶颈在写路径（真机上传已证明写入端只有 30–40 MB/s），收益退化为 1.0×。要判定必须先做
+> `T_copy`（拿插件自己的 `TASK_COPY` 搬同一份包，`src/filemgr.c:836`），再决定是否值得改构建
+> 并刷机验证；用户选择停在第一步之前。**重开的第一个动作是 `T_copy`，不是改 `-DRAR_SMP`。**
+
+### 可选项（非阻塞）
+
+- **性能**：**优化前**实测上游（7-Zip 本体）在 7z 格式上快 1.9×（单线程）/ 3.4×（8 线程）；ZIP 无显著差异。差距不在我们的架构（我们比 SDK 自己的 `SzArEx` 路径还快 1.02×）。**已全部落地（2026-09-16）**：①汇编解码器（`LzmaDecOpt.asm`+jwasm，1.26×，无 jwasm 自动退纯 C）②多线程 LZMA2（`Lzma2DecMt`，8 线程，1.37×，线程失败自动降级 chain；BCJ2/加密布局仍走 chain）③ZIP 逐条目 fsync 移除（8000 文件 ≥14×）。7z 现与 7-Zip 单线程打平、ZIP 已压过官方（本机受 Defender 拖累不可比，PS5 无该因素）。RAR 与官方 UnRAR 同速（unrar 自带 `target("aes")` SIMD 已启用，无逐条目 fsync）。完整数据见 `docs/EXTRACTION-PERF.md`，基准工具 `tests/bench_driver.py`。**⚠️ 但「单线程打平 / 8 线程 1.59×」是在最有利的输入形状上测的**：基准归档是 `-m0=lzma2 -ms=on` 的**单文件**（`tests/bench_driver.py:179`），恰好是唯一能让 `sz_chain_lzma2_root()`（`src/sevenz_chain.c:750`，要求 1 coder / 0 bond / 1 pack stream / 纯 LZMA2）生效的形状；真实的**多 folder / BCJ2 / 7zAES** 归档会让 MT 失效、退回单线程 chain —— 所以那个 1.59× **既不是上限也不是下限，方向未知**。剩余优化（CRC 硬件化、MT 扩到 BCJ2、条目级并行、ZIP inflate 换 libdeflate、AES-NI）**全部集中在 7z 多线程这一条线上**，建议**先拿真实归档在真机上 profile 再排序**，别按 PC 上这份数字动手
+- ~~fsync 批量化（每 64MB/N 条刷一次）~~ → **已作废，改为「彻底移除」**（2026-09-16）：实际落地的不是批量刷，而是把 ZIP 引擎的逐条目 fsync 直接删掉（RAR/7z 本来就没有），三引擎统一为「**不 sync、只 rename**」——publish 是纯 rename、也没有续解功能，该 fsync 无收益。8000 文件 fixture：fsync 版 >200 s 未跑完 → 无 fsync **14.5 s（≥14×）**。已知取舍：publish 之后到落盘之间断电，可能出现「文件在但内容不完整」；要补只需在 extract 收尾做**一次**目录/整盘 flush（PS5 是 FreeBSD 系，`syncfs()` 不一定有，`sync()` 是全盘、偏重）。代码现状见 `src/zip_extract.c:937-945`，实测见 `docs/EXTRACTION-PERF.md:18-21`
+- 解压失败保留 staging 支持续解（中等改动）
+- ~~进度条 % / 文字进度 / ETA 三处口径统一为字节~~ → **已完成**（`assets/main.js:2071-2079`，条目计数已移除并注明原因）
+
+---
+
+## 九、仓库许可与代码归属（2026-09-15 核查）
+
+用户曾担心「项目源自他人代码、没有许可」——**前提不成立**：
+
+- 上游 `owendswang/ps5-web-file-manager` 经 GitHub API 确认 = **GPL-3.0**（78 stars，last push 2026-09-08）
+- 本项目 `LICENSE`（GPL-3.0 全文）在 root commit `5cb0b76` 即存在，与上游一致
+- 授权链完整：`ps5-payload-dev/websrv`（John Törnblom, GPLv3+，其 Copyright 头仍保留在 `asset.c` / `asset.h` / `mime.h` / `websrv.h`）→ `owendswang` → 本项目
+
+代码量构成：
+- 第三方 vendored **71,528 行**（unrar7 27,710 / zlib 20,106 / LZMA SDK 17,248 / minizip-ng 6,464）——重写时原样复用，零成本
+- 第一方 20,844 行 = 上游 v1.7 遗产 13,860 + 自有 6,984
+- **自有代码中 3,661 行零耦合**（`sevenz_chain` 2094 + `zipx_volume` 658 + `zipx_volstream` 494 + `sevenz_volstream` 415，只依赖 public domain / zlib）→ 可单独抽成 MIT 库
+
+完整评估见 `docs/REWRITE-FEASIBILITY.md`（三路径：补合规 0.5 天 / 架构重构 12–18 天 / clean-room 重写 35–50 天）。**结论：建议补合规而非重写** —— GPL-3.0 保护 7z 引擎成果不被闭源白嫖。
+
+---
+
+## 十、工作区状态
+
+⚠️ **2026-09-23：工作树不再干净** —— 本轮加密改动（15 个已修改 + 8 个未跟踪文件）**尚未提交**，见文末「十一、本轮变更」。发版前需要先决定版本号并 commit。
+
+以下为 2026-09-15 的历史清理记录（当时工作树干净，"仅剩有意保留的未跟踪文档"）。
+
+已清理（2026-09-15）：
+
+| 文件 | 说明 | 去向 |
+|---|---|---|
+| `erssonglDesktopWeb File Managerps5-web-file-manager￢`（2543 B） | 早期 shell 转义事故：一次 `git log --oneline --color` 的输出被重定向进了文件名。末尾是 U+F022（私用区码位，mojibake 残留），各工具渲染不一 —— git 显示成八进制转义、`ls -b` 印成 ASCII 引号 | **回收站**（`$R…`，2543 B，可还原） |
+| `web-file-mgr-unpack 1.9.1.elf`（898 KiB） | 陷阱：文件名写 1.9.1，内嵌却是 9-07 的 **v1.9**（无 7z 引擎） | 已不在仓库根 |
+
+> ⚠️ **清理这类特殊文件名时**：`SHFileOperationW`（带 `FOF_ALLOWUNDO` 走回收站）对含私用区码位的路径会返回 `ERROR_FILE_NOT_FOUND (2)`，**但动作实际已生效**。删完务必查 `C:\$Recycle.Bin\<SID>\$I*` 记录确认落在回收站（`$I` 存原路径 UTF-16，`$R` 是内容）。本沙箱里 `Add-Type` 与 `rm` 都被拦（后者有 safe-delete 钩子），只能用 Python `ctypes` 调 shell32。
+
+`.build/` 下的探针/调试产物已被 `.gitignore` 白名单覆盖，不再污染 `git status`。
+
+---
+
+## 十一、本轮（2026-09-23）变更：加密通道补齐（未提交）
+
+**目标**：让 ZIP 与 RAR 的加密归档真正可解（7zAES 早已可用）。两者此前都报
+`extract_unsupported`，但**缺口在引擎侧，不在 UI** —— 密码框、`password=` 字段、
+`err_extract_password` 文案从 v1.9 起就已就位。
+
+### 11.1 ZIP：给裁剪过的 minizip-ng 补一个 crypto 后端
+
+`third_party/minizip-ng` 是裁到只读路径的精简副本，`mz_zip.c` 里
+`#ifdef HAVE_WZAES / HAVE_PKCRYPT` 的分支保留着，但**对应的流与 crypto 后端被裁掉了**。
+本轮补回：
+
+| 文件 | 状态 | 说明 |
+|---|---|---|
+| `src/mz_strm_wzaes.{c,h}` | 上游 4.2.2 原样恢复 | WinZip AES 流（方法 99 + `0x9901` 扩展字段） |
+| `src/mz_strm_pkcrypt.{c,h}` | 上游 4.2.2 原样恢复 | 传统 PKWARE / ZipCrypto 流 |
+| `src/mz_crypt_wfm.c` | **新写**（~860 行） | 本地 crypto 后端：SHA-1、HMAC-SHA1、AES-128/192/256 |
+
+后端要点：
+- S-box 与 GF(2^8) log/alog 表**首次使用时推导**，所以不新增 `.rodata` 查表（实测 `.rodata` 仅 +256 B，是字符串）。
+- 随机数直接 `open("/dev/urandom")`，**不要**走 `mz_os_rand()` —— 后者会退回 `rand()`/`srand()`，把两个新符号塞进导入表。最终产物**动态符号零新增**。
+- PBKDF2 复用 vendored 的 `mz_crypt.c`（与上游逐字节一致），没有重写。
+- 非 SHA-1 算法与 AEAD aad 一律返回 `MZ_SUPPORT_ERROR`（本项目只读，不需要）。
+- KAT 先行：写完后先用 FIPS 197 / RFC 3174 / RFC 2202 / RFC 6070 / SP 800-38A
+  向量单独验算（`.build/kat_crypto.c`，24/24），再接线。踩到的三个坑：AES 仿射用 `rol32`
+  应为 `rol8`；GF 乘法 `(uint8_t)(a+b) % 255` 截断，应全程 int；HMAC 的 ipad 必须由
+  **已 XOR 过 0x5c 的 opad** 再推。
+
+### 11.2 RAR：把 `RARSetPassword` 接上
+
+`src/rar_extract.{c,h}`：新增 `password` 形参（`rar_extract()` 为第 8 个参数）。
+调用点是 `RAROpenArchiveEx` 之后、**首次 `RARReadHeaderEx` 之前**——这是解密 `-hp`
+头加密归档的硬性顺序要求（scan 与 extract 两个阶段各自开档，两处都要设）。
+`ERAR_MISSING_PASSWORD` / `ERAR_BAD_PASSWORD` 由 `ZIPX_ERR_UNSUPPORTED` 改映射为
+`ZIPX_ERR_PASSWORD`；`RHDF_ENCRYPTED` 只在**没给密码**时提前拒绝。
+
+### 11.3 前端：密码失败后自动重试（这步不做，功能等于不可达）
+
+原先密码框**只对 7z 弹**（`actionExtract()` 里的 `isSevenZipArchive()` 判断），
+ZIP/RAR 加密归档失败后用户根本没机会输密码。现在 `handleTerminalTask()` 在
+`op === "extract" && error_code === "extract_password"` 时走
+`retryExtractWithPassword()`：
+
+- 记忆原始请求（`extractRetryKey(task.id)` → `{conflict, removeSource, name, large, attempts}`），
+  重试时**保持冲突策略与大文件选配**；
+- **必须按任务 id 记，不能按路径记**（v1.9.3M 后期修正）。路径在传输中被
+  「服务端 JSON 逐字节转义为 `\u00XX`」+「`fs_path_value()` 反向还原成原始字节」这一对
+  转换改了表示 ⇒ **非 ASCII 目录下**「页面手里的路径」≠「任务回报的路径」，按路径查必然
+  落空 ⇒ 口令框永远不弹，用户只看到一个失败框，必须先手动再解压一次。任务 id 由服务端
+  分配、原样回传，不受编码影响；重试时也改用**服务端回报的** `task.src` / `task.dst` 重发。
+  消费即删（重试注册到新 id 下），Map 最多留 8 条（同一时刻只可能有一个活动任务）。
+- 最多 3 次；取消或空输入即放弃，回落到原有失败提示；
+- 7z 保留提前询问（免得白跑一次 scan + folder 解析）。
+
+新增文案 `extractPasswordRetryAsk`（重试：密码不正确）+ `extractPasswordFirstAsk`（首次：
+此压缩包已加密），与提前询问用的 `extractPasswordAsk` 区分 —— 第一次失败时用户还没输过密码，
+再说「密码不正确」就是误导。
+
+错误文案里的条目名必须过 `decodeFsText()`：`backendErrorText()` 原样用了 `error_arg`，
+而服务端把它逐字节转义过 ⇒ 中文/日文条目名在错误框里显示成 `â®…ç§.psd`。列表侧一直有这层
+翻译（`displayName()`），只有错误文案漏了。
+
+同源的编码坑：`pathJoin(服务端回报的目录, 本地文件名)` 把两种表示混进同一个字符串，而
+`fs_path_value()` **只要发现任一个码点 > 0xFF 就整体不修** ⇒ 中文名文件放进中文名目录时
+路径失效。新增 `encodeFsText()`（`decodeFsText()` 的逆）在拼接前把本地名转成同一表示，
+`uploadAndExtractFile()` 与 `actionNewText()` 两处都用它。
+
+无头回归：`.build/ui_retry_test.mjs`（真 `main.js` 载入桩 DOM，40 checks，含「非 ASCII 目录
+必须仍弹口令框」的回归用例）、`.build/ui_upload_menu_test.mjs`（40 checks：i18n 键覆盖、
+菜单接线、样式、高亮规则的层叠作用域，以及**解压按钮不许被隐藏、只许被置灰**）、
+`.build/preview_check.mjs`（无头 Chromium 跑真页面，验菜单开关、页脚布局、**解压按钮的
+显隐/置灰/提示随选区变化**，并**读回三种交互状态下高亮的计算值**；该脚本已改为失败即
+非零退出）。
+
+**菜单行的「选中高亮」曾被两条规则同时破坏**（用户报「选中下面那个高亮效果不对」）：
+① 全局 `button:focus` 的 `outline: 3px + offset 2px` 是按 54px 工具栏按钮设计的，套在 46px
+菜单行上会越过面板 6px 内边距、压住相邻行，且 outline 的圆角半径不随 offset 自适应 ⇒ 视觉上
+成了一个「脱离的框 + 两侧挂着的弧线」；② 面板自己的
+`.upload-menu-list button:hover:not(:disabled)` **从未生效过** —— 它与
+`button:not(.row-action):hover:not(:disabled)` 特异性同为 `(0,3,1)`，而后者在文件里更靠后 ⇒
+后者胜出，于是 hover 是 `#303945`、focus 是 `#2b343e`，**两个高亮两个颜色**，且一行 hover 时
+另一行仍因 focus 亮着 ⇒ 看起来「两行同时被选中」。修法：两条规则都收敛到面板 id
+（`#uploadMenu button:…`，`(1,1,1)` / `(1,2,1)` 稳赢通用规则），行只用填充表示选中，键盘焦点
+提示改为**行内 `inset` 环**（`box-shadow: inset 0 0 0 2px`）—— 画在行内，任何行高都不可能
+越界。**这类坑只有真引擎读计算值才抓得住**，光看源码两条规则都「像是对的」。
+
+**解压按钮改为「常显 + 置灰」**（用户要求「直接显示出来 只不过是灰色的 只有能解压的文件才可以
+点击」）：`index.html` 去掉 `hidden`，`renderExtractButton()` 不再碰 `.hidden`，改成按选区设
+disabled 并给一条说明原因的工具提示（什么都没选 ⇒ 新增 `extractSelectArchive`；只选中子卷 ⇒
+沿用 `extractSelectMainVolume`；选中**多个** ⇒ 新增 `extractOneAtATime`，旧代码这种情况错用了
+「请改选主卷」，文案本身是错的）。🪤 **`button:disabled` 带 `pointer-events: none` ⇒ 禁用按钮
+无法 hover，`title` 永远不弹** —— 必须像既有的 `.parent-nav-button:disabled` 那样把
+`pointer-events` 还回来（点击仍无效，`disabled` 属性本身挡激活）。标签同时从 `extractToCurrent`
+（「解压到当前目录」）换成短词 `extract`（「解压」），与工具栏其他动词一致：**常显按钮不该
+同时又是最宽的那个**（英文下 `Extract to current folder` 会到 107 px）。
+**代价必须实测而不是估**：按钮宽 96 px ⇒ 工具栏换行阈值（zh）1080 → 1190 px、（en）1230 →
+1350 px。`.build/preview_check.mjs` 已把阈值**钉成断言**（1920/1600/1280 必须都是一行），
+并按四种选区验 disabled / opacity / title；该脚本同时从「只打印」改成**失败即非零退出**。
+
+### 11.4 构建坑：编译选项变化必须让目标文件失效（**改 Makefile 前必读**）
+
+`make` **看不见**编译选项变化。加 `-DHAVE_WZAES -DHAVE_PKCRYPT` 后，
+`mz_zip.o` / `mz_crypt.o` 被判定为最新而复用 → 此时已无线程引用新流 →
+`--gc-sections` 把加密代码再丢一次，**链接却报成功**（本次第一次构建的产物与
+已发布 v1.9.2 **逐字节相同**，`readelf` 才发现 `.text` 只长了 336 B）。
+
+修法（取代原先的 `LzmaDec.o` 特例）：把第三方编译选项写进标记文件，
+内容变了才重编。
+
+```make
+PS5_FLAGS_STAMP   := ps5-obj/.third_party_cflags
+LINUX_FLAGS_STAMP := linux-obj/.third_party_cflags
+$(PS5_FLAGS_STAMP): FORCE
+	@printf '%s\n' '$(THIRD_PARTY_C_FLAGS_7Z) $(LZMA_DEC_OPT_FLAG)' > $@.tmp
+	@cmp -s $@.tmp $@ || { mv -f $@.tmp $@; echo '  [cflags] ...'; }
+```
+
+> 诊断手法：拿未 strip 的产物比 `readelf -S` 各段尺寸，而不是看总体积。
+> 改一个字符串常量会重排 `.rodata` 字符串池，字节 diff 会被放大到几万字节，
+> 但段尺寸是守恒的——判断"代码到底有没有变"要看段尺寸 + 助记符序列。
+> 现成脚本：`.build/_seccmp.py`、`.build/_operandcheck.sh`。
+
+### 11.5 产物与验证
+
+| 项 | 值 |
+|---|---|
+| 主机测试 | ZIP 140 + RAR 37 = **177 checks / 0 失败**（`tests/run-tests.sh`） |
+| 前端测试 | **27 checks / 0 失败**（`.build/ui_retry_test.mjs`） |
+| ELF | 870,680 B · sha256 `b1409f5c1bc4b1a39ab337853b956f4807f95c5770dee6eca7a18a62cc08f80e` · e_machine 0x003e（加密轮结束时；`-mhe=on` 之后的产物见 §12.3） |
+| 确定性 | 同一源码树构建两次逐字节一致 |
+| 段变化（vs 已发布 v1.9.2） | `.text` +11,296 · `.bss` +5,120（AES 表） · `.rodata` +256 · 动态符号零新增 |
+| 内嵌资产核验 | ELF 内 gzip 资源中可检出 `retryExtractWithPassword` / `extractPasswordRetryAsk`（普通 `strings` 找不到，要先解 gzip；脚本 `.build/check-elf-gzip.py`） |
+
+**未做（发版前必做）**：未 commit / tag / 发 Release；真机端到端未验。
+版本号**已升**为 `v1.9.3M`（2026-09-24 加改版标记 `M`，见 §2.2）。
+README（中英）、CHANGELOG、本文档已同步为「未发布」状态。
+
+---
+
+## 十二、本轮（2026-09-23）变更：7z `-mhe=on` 加密头（未提交）
+
+**目标**：补上最后一个 7z 格式缺口（设计与坑见 §八）。
+
+### 12.1 新增
+
+| 文件 | 说明 |
+|---|---|
+| `src/sevenz_header.{c,h}` | **新写**（~900 行）。头部读取 + `k7zIdEncodedHeader` 最小解析 + 虚拟 `ISeekInStream` |
+| `Makefile` | `src/sevenz_header.c` 进 `COMMON_SRCS`（PS5 与 linux 共用） |
+| `tests/run-sevenz-tests.sh` | 编 `sevenz_header.o` 进 `ENGINE_OBJS`；`KNOWN_GAPS` 清空；façade 矩阵加入 `aeshe` |
+| `tests/sevenz_chain_e2e.c` | 按与产品相同的顺序接线 `szh_prepare()`（否则 chain 矩阵读不了 `aeshe`） |
+| `tests/test_sevenz_extract.c` | `aeshe` 三例（无密码 / 错密码 → `ZIPX_ERR_PASSWORD`；正确密码 → 成功），另修一处 `snprintf` 截断告警 |
+
+### 12.2 关键设计（细节见 §八）
+
+- 只探**一个字节**：不是 `0x17` 立刻返回 `SZH_PLAIN`，SDK 行为与改动前完全一致（12 个既有 fixture 全部复跑通过）。
+- 解析刻意宽容：PackInfo/UnpackInfo 之外的任何异常都回落 `SZH_PLAIN`，把诊断权留给 SDK。
+- 复用 `sz_chain_parse()` / `sz_chain_decode()`，所以 7zAES 的密码/错误语义与内容侧**完全同源**，不新增第二个 crypto 实现。
+- 虚拟流的 `total` 必须 `max(真实长度, hdr_off + L)`；`LookToRead2_INIT` 不 seek，交回 SDK 前必须显式 seek 到 0。
+
+### 12.3 产物与验证
+
+| 项 | 值 |
+|---|---|
+| 7z 套件 | **27 用例 / 0 失败**，`aeshe` 在 chain 与 façade 两条路径都 `ok`，`KNOWN_GAPS` 为空 |
+| 主机测试（ZIP/RAR 回归） | ZIP 140 + RAR 37 = **177 checks / 0 失败**（无回归） |
+| ELF | 903,448 B · sha256 `8ca47d5aaca75085b32641300cce30fadb7df7749cb6b53d04f129bcecc286b7` · e_machine 0x003e（== 本轮最终产物，见 §12.4） |
+| 确定性 | 同一源码树构建两次 sha256 相同 |
+| 段变化（解压按钮常显 vs 上一轮） | **只有 `.rodata` 变化**：`0x026CC0` → `0x026F00`（+0x240 = 576 B：index.html 去掉 `hidden` 并换短标签、`main.js` 的三条禁用理由、两份语言文件各两条新文案、`.extract-action:disabled` 及其注释）。`.text` 两次均为 `0x087780`、`.data` 均为 `0x00034C` —— 第六次「只改内嵌前端资源」 |
+| 段变化（菜单行高亮修复 vs 上一轮） | **只有 `.rodata` 变化**：`0x026B40` → `0x026CC0`（+0x180 = 384 B，三条收敛后的高亮规则加其注释）。`.text` 两次 readelf 均为 `0x087780` —— 又一次「只改内嵌前端资源、不碰 C 逻辑」的标准形状 |
+| 段变化（本轮前端三项 vs 上一轮） | **只有 `.rodata` 变化**：`0x026A40` → `0x026B40`（+0x100 = 256 B）。`.text` / `.data` / `.eh_frame*` 一字节未变 —— 「只改内嵌前端资源 + 加两条文案」的标准形状 |
+| 段变化（加 `M` 标记 + 修正 `err_extract_unsupported` 文案 vs 加密轮产物） | **只有 `.rodata` 变化**：加 `M` 标记 +0x100（256 B），修正文案再 +0x40（64 B）；`.text` / `.data` / `.bss` / `.eh_frame*` / `.gcc_except_table` **一个字节都没变**。又因 16 KiB 段对齐留有余量，**六次构建的文件总尺寸都是 903,448 B**：尺寸相同**不代表**二进制相同（sha256 逐个不同：`f3164efa…` → `53296d29…` → `7b5ab00c…` → `212107a6…` → `da36834d…` → `cf2c0fcf…` → `8ca47d5a…`） |
+| 段变化（加密轮 vs 其前一轮） | `.text` +4,880 · `.rodata` +640 · `.eh_frame_hdr` +32 · `.eh_frame` +160 —— 正文合计 **+5,712**；其余 **+27,056** 是 `p_align=0x4000` 的两处段对齐填充（LOAD#1 越过 0x8C000 边界）。**段数仍为 20，动态符号零新增（513 → 513）** |
+
+> 判读提示：这次文件涨了 32,768 B，但正文只涨 5,712 B —— 不要按体积下结论。
+> 权威做法是比较**段尺寸**与**动态符号集合**（见 §11.4 的诊断手法）。
+
+**未做（发版前必做）**：未 commit / tag / 发 Release；真机端到端未验。
+版本号已升为 `v1.9.3M`（改版标记 `M` 于 2026-09-24 加入）。
@@ -13,7 +13,26 @@ ifeq ($(MAKECMDGOALS),)
  endif
 endif

-VERSION_TAG := v1.8
+# Bump this together with the git tag -- it is baked into the binary (the PS5
+# notification, the stdout banner and /api/version all print it) AND into the
+# output filename, so a stale value silently mislabels everything. Override
+# per-build with:
+#   make VERSION_TAG=v1.9.3M
+#
+# **The trailing M is the fork marker** (Modified build, maintained by
+# LisherSong). Upstream owendswang releases are plain `vX.Y.Z`, so any string
+# carrying the M is ours and anything without it is not. The marker rides on
+# VERSION_TAG rather than on a separate display-only constant on purpose: it
+# therefore reaches every surface at once -- /api/version, the PS5 start-up
+# notification, the stdout banner, the UI footer and the ELF file name -- and
+# is impossible to forget in one of them. The file name gains a second benefit:
+# a fork build can no longer collide with an upstream artifact of the same
+# upstream version, which has already caused two mix-ups (a local
+# `web-file-mgr-v1.9.2.elf` sitting next to the released one under the same
+# name, and a `-DVERSION_TAG=v1.9.1` leftover wearing the released 870 488 B
+# file's size). To cut a build that is byte-for-byte upstream-shaped, pass
+# `make VERSION_TAG=v1.9.3`.
+VERSION_TAG ?= v1.9.3M
 TITLE_ID    := FMGR88888
 PYTHON      ?= python3
 STRIP       ?= $(PS5_PAYLOAD_SDK)/bin/prospero-strip
@@ -22,10 +41,12 @@ HOST_CC     ?= cc
 HOST_STRIP  ?= strip
 HOST_PKG_CONFIG ?= pkg-config

-BIN        := web-file-mgr.elf
-LINUX_BIN  := web-file-mgr-linux
-COMMON_SRCS := src/main.c src/websrv.c src/filemgr.c src/file_response.c src/task.c src/upload.c src/download.c src/text.c src/list.c src/space.c src/fs_util.c src/json_util.c src/path_util.c src/asset.c src/mime.c src/notify.c src/pkg_installer.c src/pkg_info.c src/extract.c src/zip_extract.c src/rar_extract.c
-PS5_SRCS    := $(COMMON_SRCS) src/app_installer.c
+# Output filename carries the version so two builds never overwrite each other
+# and you can tell at a glance which ELF is on the USB stick.
+BIN        := web-file-mgr-$(VERSION_TAG).elf
+LINUX_BIN  := web-file-mgr-linux-$(VERSION_TAG)
+COMMON_SRCS := src/main.c src/websrv.c src/filemgr.c src/file_response.c src/task.c src/upload.c src/download.c src/text.c src/list.c src/space.c src/version.c src/fs_util.c src/json_util.c src/path_util.c src/asset.c src/mime.c src/notify.c src/pkg_installer.c src/pkg_info.c src/extract.c src/zip_extract.c src/rar_extract.c src/zipx_volume.c src/zipx_volstream.c src/zipx_common.c src/sevenz_extract.c src/sevenz_chain.c src/sevenz_header.c src/sevenz_volstream.c src/sevenz_mt.c src/demangle_stub.c
+PS5_SRCS    := $(COMMON_SRCS) src/app_installer.c src/cpu_support_stub.c
 LINUX_SRCS  := $(COMMON_SRCS)
 BASE_ASSETS := $(filter-out %.dds,$(wildcard assets/*))
 ifneq ($(filter linux,$(MAKECMDGOALS)),)
@@ -35,22 +56,103 @@ ASSETS      := $(filter-out assets/icon0.png,$(BASE_ASSETS))
 endif
 GEN_SRCS    := $(patsubst assets/%,gen/%, $(ASSETS:=.c))

-# Vendored third-party: zlib + minizip-ng (ZIP), dmc_unrar (RAR). Compiled with
-# relaxed warnings (-w) — these are not our code and we do not want to chase
-# upstream style updates on every SDK upgrade.
-THIRD_PARTY_SRCS   := $(wildcard third_party/zlib/src/*.c) $(wildcard third_party/minizip-ng/src/*.c) third_party/unrar/dmc_unrar.c
-THIRD_PARTY_CFLAGS := -O2 -w -Ithird_party/zlib/include -Ithird_party/minizip-ng/include -Ithird_party/unrar \
-  -DHAVE_ZLIB -DZLIB_COMPAT -DHAVE_UNISTD_H=1 -D_FILE_OFFSET_BITS=64 -D_LARGEFILE64_SOURCE \
-  -DDMC_UNRAR_DISABLE_BE32TOH_BE64TOH=1
-PS5_TP_OBJS   := $(patsubst %.c,ps5-obj/%.o,$(THIRD_PARTY_SRCS))
-LINUX_TP_OBJS := $(patsubst %.c,linux-obj/%.o,$(THIRD_PARTY_SRCS))
+# Vendored third-party: zlib + minizip-ng (ZIP, C) and unrar 7.20.1 (RAR,
+# C++). unrar sources are compiled as a static library in RARDLL mode (no
+# main()); the project talks to it through the extern "C" DLL API in
+# third_party/unrar7/unrar_c_api.h. Compiled with relaxed warnings (-w) —
+# these are not our code and we do not want to chase upstream style updates.
+#
+# C++ compilers: PS5 uses prospero-clang++ (FreeBSD-style sysroot; the
+# toolchain defaults to -stdlib=libc++, driver links libc++ automatically);
+# host builds use the plain host C++ compiler (libstdc++).
+CXX            ?= $(dir $(CC))prospero-clang++
+HOST_CXX       ?= c++

-CFLAGS := -Oz -fno-asynchronous-unwind-tables -fno-unwind-tables -Wall -Werror -ffunction-sections -fdata-sections -Isrc -Ithird_party/minizip-ng/include -DVERSION_TAG=\"$(VERSION_TAG)\" -DTITLE_ID=\"$(TITLE_ID)\"
+# Source set mirrors UnRARDll.vcxproj's ClCompile list (49 files) MINUS the
+# Windows-only isnt.cpp / motw.cpp (they need windows.h; the official unrar
+# UNIX makefile omits them, and PS5/linux both use the _UNIX branch where
+# their symbols are #ifdef'd out).
+UNRAR7_SRCS := \
+  third_party/unrar7/archive.cpp third_party/unrar7/arcread.cpp third_party/unrar7/blake2s.cpp \
+  third_party/unrar7/cmddata.cpp third_party/unrar7/consio.cpp third_party/unrar7/crc.cpp \
+  third_party/unrar7/crypt.cpp third_party/unrar7/dll.cpp third_party/unrar7/encname.cpp \
+  third_party/unrar7/errhnd.cpp third_party/unrar7/extinfo.cpp third_party/unrar7/extract.cpp \
+  third_party/unrar7/filcreat.cpp third_party/unrar7/file.cpp third_party/unrar7/filefn.cpp \
+  third_party/unrar7/filestr.cpp third_party/unrar7/find.cpp third_party/unrar7/getbits.cpp \
+  third_party/unrar7/global.cpp third_party/unrar7/hash.cpp third_party/unrar7/headers.cpp \
+  third_party/unrar7/largepage.cpp third_party/unrar7/match.cpp \
+  third_party/unrar7/options.cpp third_party/unrar7/pathfn.cpp \
+  third_party/unrar7/qopen.cpp third_party/unrar7/rar.cpp third_party/unrar7/rarpch.cpp \
+  third_party/unrar7/rarvm.cpp third_party/unrar7/rawread.cpp third_party/unrar7/rdwrfn.cpp \
+  third_party/unrar7/rijndael.cpp third_party/unrar7/rs.cpp third_party/unrar7/rs16.cpp \
+  third_party/unrar7/scantree.cpp third_party/unrar7/secpassword.cpp third_party/unrar7/sha1.cpp \
+  third_party/unrar7/sha256.cpp third_party/unrar7/smallfn.cpp third_party/unrar7/strfn.cpp \
+  third_party/unrar7/strlist.cpp third_party/unrar7/system.cpp third_party/unrar7/threadpool.cpp \
+  third_party/unrar7/timefn.cpp third_party/unrar7/ui.cpp third_party/unrar7/unicode.cpp \
+  third_party/unrar7/unpack.cpp third_party/unrar7/volume.cpp
+
+THIRD_PARTY_C_SRCS   := $(wildcard third_party/zlib/src/*.c) $(wildcard third_party/minizip-ng/src/*.c) $(wildcard third_party/7z/*.c)
+# AesOpt.c hard-codes x86 AES-NI / AVX / VAES intrinsics and guards them with
+# a compiler-version check that lets clang 18 in unconditionally. The plain
+# intrinsics (`_mm256_aesenc_epi128`) live behind <wmmintrin_aes.h>, which
+# clang only declares after `+mvaes +mavx2` (or higher). PS5 is Zen 2 and has
+# every one of these, so we just enable them for the 7z TU family instead of
+# dropping AesOpt.c (Aes.c references those HW symbol names via AesGenTables).
+SEVENZ_C_FLAGS        := -maes -mavx2 -mvaes
+# HAVE_WZAES / HAVE_PKCRYPT switch on minizip-ng's two ZIP encryption paths:
+# mz_strm_wzaes.c (WinZip AES, method 99 / extra field 0x9901) and
+# mz_strm_pkcrypt.c (traditional PKWARE "ZipCrypto"). The mz_zip.c branches
+# behind these macros are already present, so defining them only pulls in the
+# two streams plus the local crypto backend in mz_crypt_wfm.c. Everything they
+# need (crc32, PBKDF2-HMAC-SHA1, AES-ECB) is implemented in-tree; see the
+# header of third_party/minizip-ng/src/mz_crypt_wfm.c.
+THIRD_PARTY_C_FLAGS  := -O2 -w -Ithird_party/zlib/include -Ithird_party/minizip-ng/include -Ithird_party/7z \
+  -DHAVE_ZLIB -DZLIB_COMPAT -DHAVE_UNISTD_H=1 -D_FILE_OFFSET_BITS=64 -D_LARGEFILE64_SOURCE \
+  -DHAVE_FSEEKO -DZ7_PPMD_SUPPORT -DHAVE_WZAES -DHAVE_PKCRYPT
+THIRD_PARTY_C_FLAGS_7Z := $(THIRD_PARTY_C_FLAGS) $(SEVENZ_C_FLAGS)
+
+# Assembly-optimised LZMA decoder (optional, on when jwasm is present).
+#
+# LzmaDec.c carries a compile-time switch: with Z7_LZMA_DEC_OPT it calls an
+# external LzmaDec_DecodeReal_3() and drops its own C implementation; without
+# it, the C version is used. The asm version is measurably faster -- on a
+# 330 MiB LZMA2 archive, 1.10 s vs 1.39 s, i.e. most of the gap to the
+# official 7-Zip binary, which builds with this switch on.
+#
+# LzmaDecOpt.asm is MASM syntax, so it needs a MASM-compatible assembler
+# (jwasm). That is not something we can assume the host has, so the whole
+# optimisation is conditional: no jwasm, no asm, and the build still works.
+# ABI_LINUX is load-bearing -- 7zAsm.asm keys its calling convention off it
+# (SysV rdi/rsi/rdx vs Win64 rcx/rdx/r8); assembling without it links cleanly
+# and then segfaults on the first call.
+JWASM             ?= jwasm
+LZMA_DEC_ASM_DIR  := third_party/7z/Asm/x86
+LZMA_DEC_ASM_SRC  := $(LZMA_DEC_ASM_DIR)/LzmaDecOpt.asm
+ifneq ($(shell command -v $(JWASM) 2>/dev/null),)
+  LZMA_DEC_OPT_FLAG := -DZ7_LZMA_DEC_OPT
+  PS5_ASM_OBJS      := ps5-obj/$(LZMA_DEC_ASM_DIR)/LzmaDecOpt.o
+  LINUX_ASM_OBJS    := linux-obj/$(LZMA_DEC_ASM_DIR)/LzmaDecOpt.o
+endif
+UNRAR7_CXX_FLAGS     := -O2 -w -std=c++17 -DRARDLL -D_FILE_OFFSET_BITS=64 -D_LARGEFILE_SOURCE
+# prospero-clang++ defaults to -stdlib=libc++; state it explicitly for clarity.
+UNRAR7_CXX_FLAGS_PS5 := $(UNRAR7_CXX_FLAGS) -stdlib=libc++
+UNRAR7_CXX_FLAGS_HOST:= $(UNRAR7_CXX_FLAGS)
+
+PS5_TP_OBJS   := $(patsubst %.c,ps5-obj/%.o,$(THIRD_PARTY_C_SRCS)) \
+                 $(patsubst %.cpp,ps5-obj/%.o,$(UNRAR7_SRCS))
+LINUX_TP_OBJS := $(patsubst %.c,linux-obj/%.o,$(THIRD_PARTY_C_SRCS)) \
+                 $(patsubst %.cpp,linux-obj/%.o,$(UNRAR7_SRCS))
+
+CFLAGS := -Oz -fno-asynchronous-unwind-tables -fno-unwind-tables -Wall -Werror -ffunction-sections -fdata-sections -Isrc -Ithird_party/minizip-ng/include -Ithird_party/unrar7 -Ithird_party/7z -DVERSION_TAG=\"$(VERSION_TAG)\" -DTITLE_ID=\"$(TITLE_ID)\"
 CFLAGS += `$(PKG_CONFIG) libmicrohttpd --cflags`
-LDFLAGS := -Wl,--gc-sections
+# --icf=all: fold byte-identical functions. LLD-only (GNU ld's --icf is
+# incomplete), so it stays on the PS5 line -- the linux target never uses
+# LDFLAGS. Paired with src/demangle_stub.c this takes the ELF from ~1010 to
+# ~850 KiB; see docs/SIZE-OPTIMIZATION.md.
+LDFLAGS := -Wl,--gc-sections -Wl,--icf=all
 LDADD  := `$(PKG_CONFIG) libmicrohttpd --libs`
 LDADD  += -lSceIpmi -lSceAppInstUtil -lSceUserService
-LINUX_CFLAGS := -O2 -flto -Wall -Werror -Isrc -Ithird_party/minizip-ng/include -DVERSION_TAG=\"$(VERSION_TAG)\" -DTITLE_ID=\"$(TITLE_ID)\"
+LINUX_CFLAGS := -O2 -flto -Wall -Werror -Isrc -Ithird_party/minizip-ng/include -Ithird_party/unrar7 -Ithird_party/7z -DVERSION_TAG=\"$(VERSION_TAG)\" -DTITLE_ID=\"$(TITLE_ID)\"
 LINUX_CFLAGS += `$(HOST_PKG_CONFIG) libmicrohttpd --cflags`
 LINUX_LDADD := `$(HOST_PKG_CONFIG) libmicrohttpd --libs` -pthread

@@ -76,18 +178,91 @@ clean:
 gen/%.c: assets/% gen-asset-module.py | gen
 	$(PYTHON) gen-asset-module.py --path $* $< > $@

-ps5-obj/%.o: %.c
-	@mkdir -p $(dir $@)
-	$(CC) $(THIRD_PARTY_CFLAGS) -c -o $@ $<
+# Only LzmaDec.c changes behaviour under the switch: it stops defining its own
+# decoder and declares the external symbol instead. Everything else in the 7z
+# TU family is unaffected.
+ifneq ($(LZMA_DEC_OPT_FLAG),)
+ps5-obj/third_party/7z/LzmaDec.o:   THIRD_PARTY_C_FLAGS_7Z += $(LZMA_DEC_OPT_FLAG)
+linux-obj/third_party/7z/LzmaDec.o: THIRD_PARTY_C_FLAGS_7Z += $(LZMA_DEC_OPT_FLAG)
+endif

-linux-obj/%.o: %.c
-	@mkdir -p $(dir $@)
-	$(HOST_CC) $(THIRD_PARTY_CFLAGS) -c -o $@ $<
+# make does not track compiler-flag changes, so an object built with the old
+# flags is silently reused and the binary links "successfully" without the
+# feature. Two cases have already bitten:
+#   * installing or removing jwasm flips LZMA_DEC_OPT_FLAG, and the asm object
+#     just sits in the link line unreferenced (the binary came out
+#     byte-identical, which is how the problem was noticed);
+#   * adding -DHAVE_WZAES / -DHAVE_PKCRYPT, which only mz_zip.c and mz_crypt.c
+#     compile differently -- without a rebuild the ZIP encryption streams are
+#     never referenced and --gc-sections quietly drops them again.
+# Recording the flags in a stamp file invalidates the objects when the flags
+# actually change, instead of rebuilding them for every unrelated Makefile edit.
+PS5_FLAGS_STAMP   := ps5-obj/.third_party_cflags
+LINUX_FLAGS_STAMP := linux-obj/.third_party_cflags

-$(BIN): $(PS5_SRCS) $(GEN_SRCS) $(PS5_TP_OBJS)
-	$(CC) $(CFLAGS) $(LDFLAGS) -o $@ $(filter %.c,$^) $(PS5_TP_OBJS) $(LDADD)
+$(PS5_FLAGS_STAMP): FORCE
+	@mkdir -p $(dir $@)
+	@printf '%s\n' '$(THIRD_PARTY_C_FLAGS_7Z) $(LZMA_DEC_OPT_FLAG)' > $@.tmp
+	@cmp -s $@.tmp $@ || { mv -f $@.tmp $@; echo '  [cflags] third-party flags changed -> rebuilding objects'; }
+	@rm -f $@.tmp
+
+$(LINUX_FLAGS_STAMP): FORCE
+	@mkdir -p $(dir $@)
+	@printf '%s\n' '$(THIRD_PARTY_C_FLAGS_7Z) $(LZMA_DEC_OPT_FLAG)' > $@.tmp
+	@cmp -s $@.tmp $@ || { mv -f $@.tmp $@; echo '  [cflags] third-party flags changed -> rebuilding objects'; }
+	@rm -f $@.tmp
+
+.PHONY: FORCE
+FORCE:
+
+# Note on -DVERSION_TAG / -DTITLE_ID: they live in CFLAGS, which make cannot
+# see -- but nothing here relies on make seeing them. The link target's *name*
+# carries the version ($(BIN) = web-file-mgr-$(VERSION_TAG).elf), so a bump
+# always misses the existing target and re-runs the link rule, and that rule
+# compiles every file in $(PS5_SRCS) on the spot (-x c, one clang invocation,
+# no intermediate .o). src/version.c and src/main.c -- the only two readers of
+# the macros -- are therefore always rebuilt with the new string. (Verified:
+# `strings` on the v1.9.3M ELF finds "v1.9.3M" once and "v1.9.2" zero times.)
+#
+# The version trap that *is* real: overriding VERSION_TAG back to a version
+# whose ELF already exists in the tree, with sources older than that file,
+# returns the existing file and silently skips the rebuild. Delete the stale
+# ELF, or build a differently named copy, when re-cutting a version.
+
+ps5-obj/%.o: %.c $(PS5_FLAGS_STAMP)
+	@mkdir -p $(dir $@)
+	$(CC) $(if $(findstring third_party/7z,$<),$(THIRD_PARTY_C_FLAGS_7Z),$(THIRD_PARTY_C_FLAGS)) -c -o $@ $<
+
+linux-obj/%.o: %.c $(LINUX_FLAGS_STAMP)
+	@mkdir -p $(dir $@)
+	$(HOST_CC) $(if $(findstring third_party/7z,$<),$(THIRD_PARTY_C_FLAGS_7Z),$(THIRD_PARTY_C_FLAGS)) -c -o $@ $<
+
+# The assembler emits a plain ELF64 relocatable object, which both linkers
+# (prospero-clang++ for PS5, cc for linux) accept as-is.
+ps5-obj/$(LZMA_DEC_ASM_DIR)/LzmaDecOpt.o: $(LZMA_DEC_ASM_SRC)
+	@mkdir -p $(dir $@)
+	$(JWASM) -elf64 -q -DABI_LINUX -I$(LZMA_DEC_ASM_DIR) -Fo$@ $<
+
+linux-obj/$(LZMA_DEC_ASM_DIR)/LzmaDecOpt.o: $(LZMA_DEC_ASM_SRC)
+	@mkdir -p $(dir $@)
+	$(JWASM) -elf64 -q -DABI_LINUX -I$(LZMA_DEC_ASM_DIR) -Fo$@ $<
+
+ps5-obj/%.o: %.cpp
+	@mkdir -p $(dir $@)
+	$(CXX) $(UNRAR7_CXX_FLAGS_PS5) -c -o $@ $<
+
+linux-obj/%.o: %.cpp
+	@mkdir -p $(dir $@)
+	$(HOST_CXX) $(UNRAR7_CXX_FLAGS_HOST) -c -o $@ $<
+
+# Link with the C++ driver so libc++ (PS5) / libstdc++ (host) is pulled in
+# automatically for the unrar objects. The project's own C sources are passed
+# through -x c (clang++ would otherwise compile .c files as C++ and trip
+# -Wdeprecated); -x none restores extension-based handling for the .o files.
+$(BIN): $(PS5_SRCS) $(GEN_SRCS) $(PS5_TP_OBJS) $(PS5_ASM_OBJS)
+	$(CXX) $(CFLAGS) $(LDFLAGS) -o $@ -x c $(filter %.c,$^) -x none $(PS5_TP_OBJS) $(PS5_ASM_OBJS) $(LDADD)
 	$(STRIP) $@

-$(LINUX_BIN): $(LINUX_SRCS) $(GEN_SRCS) $(LINUX_TP_OBJS)
-	$(HOST_CC) $(LINUX_CFLAGS) -o $@ $(filter %.c,$^) $(LINUX_TP_OBJS) $(LINUX_LDADD)
+$(LINUX_BIN): $(LINUX_SRCS) $(GEN_SRCS) $(LINUX_TP_OBJS) $(LINUX_ASM_OBJS)
+	$(HOST_CXX) $(LINUX_CFLAGS) -o $@ -x c $(filter %.c,$^) -x none $(LINUX_TP_OBJS) $(LINUX_ASM_OBJS) $(LINUX_LDADD)
 	$(HOST_STRIP) $@
@@ -1,8 +1,12 @@
+<div align="right">
+  <a href="README.md">English</a> · <a href="README.zh-CN.md">简体中文</a>
+</div>
+
 # PS5 Web File Manager

 > Homebrew HTTP file manager for jailbroken PS5 consoles. Browse, edit, upload, download and extract ZIPs through any browser on the same network — single self-contained ELF payload, no external services, no telemetry.

-**Version:** v1.8 · **Title ID:** `FMGR88888` · **License:** GPLv3+ · **Target:** `x86_64-sie-ps5`
+**Version:** v1.9.2 · **Title ID:** `FMGR88888` · **License:** GPLv3+ · **Target:** `x86_64-sie-ps5`

 ---

@@ -12,6 +16,127 @@ A payload ELF that runs an HTTP file manager inside a jailbroken PS5. Open `http

 The same source tree builds a Linux binary for development and a PS5 payload ELF for deployment — see `make linux` below.

+## What's new (unreleased)
+
+- **Encrypted ZIP extraction works end to end** — both schemes:
+  - traditional PKWARE ("ZipCrypto", what `zip -e` writes), and
+  - WinZip AES-128/192/256 (compression method `99` plus the `0x9901` extra
+    field, what `7z -mem=AES256` and WinZip write), for stored and deflated
+    entries.
+
+  A missing or wrong password is reported as `extract_password` — the code the
+  task overlay already knew how to translate, even though until now nothing
+  could produce it for a ZIP. The SHA-1,
+  HMAC-SHA1 and AES primitives live in a new local minizip-ng backend,
+  `third_party/minizip-ng/src/mz_crypt_wfm.c` (PBKDF2 comes from the vendored
+  `mz_crypt.c`); its header explains why they are implemented in-tree instead
+  of delegating to another vendored library.
+- **Encrypted RAR is actually wired up.** v1.9 vendored an engine that *could*
+  decrypt (`RARSetPassword`) but never called it, so encrypted archives were
+  rejected. The password now reaches the engine, including for `-hp`
+  header-encrypted archives, and a wrong password returns `extract_password`
+  so the prompt can retry.
+- **Build fix: compiler-flag changes now invalidate objects.** `make` cannot
+  see flag changes, so adding `-DHAVE_WZAES -DHAVE_PKCRYPT` left the existing
+  `mz_zip.o` / `mz_crypt.o` in place — and because nothing referenced the new
+  streams any more, `--gc-sections` quietly dropped the encryption code again
+  while the link still "succeeded". The Makefile now records the third-party
+  flag set in `ps5-obj/.third_party_cflags` and rebuilds only when it really
+  changes. This is the same trap the `LzmaDec.o` rule was working around.
+- **The UI can now retry with a password.** An `extract_password` failure no
+  longer ends in an error box: the attempt is re-sent with whatever the user
+  types, up to three times, keeping the conflict policy and the large-file
+  opt-in of the original request. Cancelling or submitting an empty box falls
+  back to the original failure report. 7z keeps its up-front prompt, since an
+  encrypted 7z header would otherwise cost a wasted scan.
+- **Encrypted 7z headers (`-mhe=on`) now open.** This was the last known format
+  gap: with `-mhe=on` the file names, the folder table *and* every entry size
+  sit inside the encrypted header, so the vendored SDK gives up with
+  `SZ_ERROR_UNSUPPORTED` before it can list a single entry. A new module,
+  `src/sevenz_header.c`, reads the header record, decodes its one folder with
+  the project's own 7zAES path (`src/sevenz_chain.c`) and then hands the SDK a
+  small virtual stream in which the encrypted record has been replaced by the
+  plaintext — so the SDK goes on parsing exactly the archive it always did, and
+  nothing on disk is touched. Archives whose header is merely *compressed*
+  (`-mhc=on`, the default) are not modified in any way, and a wrong password
+  comes back as `extract_password` like every other encrypted archive.
+- `tests/make-zip-enc-fixtures.bat` and three real fixtures under
+  `tests/fixtures-real/` (`enc-zipcrypto.zip`, `enc-aes256.zip`,
+  `enc-aes256-store.zip`, password `secret123`).
+- Host checks: **140 ZIP + 37 RAR = 177** (`tests/run-tests.sh`). The new
+  encrypted-ZIP cases run against real archives in `tests/fixtures-real/`
+  generated by the new `tests/make-zip-enc-fixtures.bat`.
+- A RAR archive that asks for a dictionary larger than this build supports no
+  longer reports as a per-entry size problem: it gets its own
+  `extract_dict_too_large` code and a message that names the required and the
+  supported dictionary size. The build's behaviour is unchanged — such an
+  archive is still refused, because honouring it would mean allocating the
+  whole window in one shot, which is exactly what rarlab's own CLI refuses to
+  do by default and what a 16 GB shared-memory console cannot afford.
+- 7z checks: **27 cases, 0 failures** (`tests/run-sevenz-tests.sh`), and the
+  `KNOWN_GAPS` list that held `aeshe` is now empty — the encrypted-header
+  fixture passes through both the folder decoder and the extraction facade.
+- The frontend retry flow has a headless check of its own —
+  `node .build/ui_retry_test.mjs` loads the real `assets/main.js` into a stubbed
+  DOM and asserts the remembered request, the retry cap and the give-up paths,
+  including the regression case for a non-ASCII folder: **40 checks, 0 failures**.
+  `node .build/ui_upload_menu_test.mjs` covers the markup side — every
+  `data-i18n` key exists in both languages, the upload menu is wired to the
+  right handlers, the classes it uses are styled, and the row-highlight rules
+  are scoped so they cannot lose the cascade to a generic button rule, and that
+  the extract button is never hidden — only disabled, with a message per reason:
+  **40 checks, 0 failures**.
+- The tree builds to **903 448 B**, sha256
+  `8ca47d5aaca75085b32641300cce30fadb7df7749cb6b53d04f129bcecc286b7`,
+  `e_machine` `0x003e`. Rebuilt from the same tree, byte-identical both times;
+  the built ELF was checked to contain the new frontend code, which is only
+  reachable after gunzipping the embedded assets. Same 20 sections and **no new
+  dynamic symbols**. The encrypted-archive work added +5 712 bytes of content
+  (`.text` +4 880, `.rodata` +640, `.eh_frame*` +192); the fork marker below
+  then added a further +0x100 (256 B), the corrected
+  `err_extract_unsupported` copy another +0x40 (64 B), the upload menu +0x980
+  (2 432 B), the frontend copy and CSS of the first fix round +0x100 (256 B)
+  and the scoped row-highlight rules +0x180 (384 B), then the always-on extract
+  button +0x240 (576 B) — every one of them to
+  `.rodata` **and to no other section**, so the file is still 903 448 B across
+  all six builds. An unchanged size is not evidence of an unchanged binary —
+  compare sections with `readelf -SW`.
+- **The version string carries a fork marker: `v1.9.3M`.** Upstream releases are
+  plain `vX.Y.Z`, so the trailing `M` (Modified) is what tells you which of the
+  two projects a build came from. It is part of `VERSION_TAG`, so `/api/version`,
+  the PS5 start-up notification, the stdout banner, the UI footer and the ELF
+  file name all carry it at once, and the UI footer spells it out on hover. The
+  file name changing also means a fork build can no longer shadow an upstream
+  artifact of the same upstream version. See Credits.
+- Still open: end-to-end validation of the built ELF on a real console.
+
+> This section describes **unreleased** work: the published release is still
+> `v1.9.2` and its binary does **not** contain any of it. The unreleased tree
+> identifies itself as `v1.9.3M`.
+
+## What's new in v1.9.2
+
+Version-string-only re-release. The `v1.9.1` tag sat four commits behind the
+tree that produced its binary, so the tag could not rebuild the published
+artifact; v1.9.2 is cut from the right commit. It is functionally identical to
+the v1.9.1 binary — the only change is the baked-in version string.
+
+## What's new in v1.9
+
+- **RAR engine replaced with the official rarlab UnRAR 7.20.1**
+  (`third_party/unrar7/`, replacing dmc_unrar). This is what actually
+  makes RAR extraction work on real files: dmc_unrar could not decode
+  archives written by **WinRAR 6.x/7.x** (RAR5 "v6" compression) and had
+  no multi-volume support — both now work.
+- **RAR5 "v6" archives extract** (the v1.8-era "corrupt archive" report
+  on WinRAR 6/7 files is gone).
+- **Multi-volume RAR** (`.part01.rar` chains): unrar stitches the parts by
+  name when the full set sits next to the volume you open.
+- Engine can decrypt encrypted RAR (`RARSetPassword`) — password UI /
+  API plumbing still pending, encrypted archives are rejected for now.
+- Host tests now run real archives (v6 / encrypted / 3-volume fixtures
+  committed under `tests/fixtures-real/`): **70 ZIP + 24 RAR = 94 checks**.
+
 ## What's new in v1.8

 - **Single-volume RAR extraction** via the vendored FLOSS library
@@ -35,11 +160,54 @@ The same source tree builds a Linux binary for development and a PS5 payload ELF
 - **Documentation**: [`CHANGELOG.md`](./CHANGELOG.md),
  [`docs/UPGRADE-v1.8-rar-support.md`](./docs/UPGRADE-v1.8-rar-support.md)
  and the vendoring decision tree at
-  [`third_party/unrar/VENDORED.md`](./third_party/unrar/VENDORED.md).
+  [`third_party/unrar7/VENDORED.md`](./third_party/unrar7/VENDORED.md)
+  (v1.8 shipped it as `third_party/unrar/VENDORED.md`).
 - See the [dedicated section](#rar-extraction) below for scope and the
  limitations that come from using dmc_unrar (no multi-volume, no
  encryption in v1.8 — both lift in v1.9 when the library is replaced).

+## What's new in v1.8.1
+
+- **Default ZIP limits relaxed** (companion to v1.7's large profile).
+  v1.7 shipped with a 64 GiB default per-entry cap, which was too
+  aggressive for typical PS5 system-backup ZIPs (200-300 GiB). v1.8.1
+  raises the default profile to **1 TiB total / 256 GiB per entry /
+  500 : 1 ratio**, with the `large=1` opt-in kept at 2 TiB / 1 TiB /
+  1000 : 1. The frontend threshold rises from 60 GiB to 240 GiB so
+  common system-backup archives no longer trigger the prompt.
+- RAR extraction inherits the new defaults (rar_extract.c threads
+  `c->limits` from the engine — no engine change required).
+- Rationale: the real zip-bomb defence is `check_space()` (statvfs-based
+  real disk-space check before staging) + `max_ratio` (declared
+  compression ratio cap). The size caps are a UX guard, not a security
+  boundary.
+
+## What's new in v1.8.2
+
+- **Default ZIP limits relaxed again** for the 3A-game single-file case.
+  A single ~300 GiB uncompressed file inside an archive was still
+  silently rejected by v1.8.1 (the default scan returns
+  `ZIPX_ERR_LIMIT_FILE_SIZE` before the request ever reaches the
+  frontend confirmation prompt). v1.8.2 raises the default profile to
+  **2 TiB total / 512 GiB per entry / 500 : 1 ratio**, with the `large=1`
+  opt-in bumped to 4 TiB / 1 TiB / 1000 : 1. Frontend threshold rises
+  from 240 GiB to 480 GiB.
+- **Two PS5-only build fixes** discovered when cross-compiling for the
+  PS5 target. The host-side test suite (`tests/run-tests.sh`) had
+  silently accepted both because it links the same sources but uses
+  gcc rather than clang 18 and a different include path:
+  - `Makefile` CFLAGS: add `-Ithird_party/unrar` so `src/rar_extract.c`
+    can find the project-authored `dmc_unrar_api.h` facade header.
+  - `src/extract.c`: move `extract_progress()` definition above
+    `extract_dispatch()` so the implicit function declaration is not
+    flagged by `-Werror=implicit-function-declaration` (clang 18 in the
+    PS5 SDK is stricter than the host gcc used by tests).
+- **Release artifact** for v1.8.2: `web-file-mgr.elf` — 509 704 bytes,
+  sha256 `1b2c3d68b35e32737105f17d14a80a3c159ceca0cabd274ee168cbcd81906f65`,
+  ELF class 64, little-endian, e_machine `0x003e` (x86_64-sie-ps5).
+- Tests: **84 host-side checks** (70 ZIP + 14 RAR), 0 failures. PS5
+  cross-compile succeeds end-to-end.
+
 ## What's new in v1.7

 - **ZIP large-file profile** (opt-in via the new `large=1` argument on `/api/extract`): relaxed caps of **2 TiB** archive total, **1 TiB** per entry, **1000 : 1** compression ratio. The frontend prompts for confirmation whenever the archive on disk is larger than **60 GiB**; the server only activates the profile when the user explicitly agrees.
@@ -68,7 +236,8 @@ The same source tree builds a Linux binary for development and a PS5 payload ELF
 - **Upload** — single files or folder trees from any device on the LAN (hidden in the PS5 browser). Atomic temp + rename.
 - **Download** — single file as raw bytes, or folders/multi-select as a streaming `.tar`. Hidden in the PS5 browser.
 - **Tasks** — full-screen overlay with delayed show, live progress, throughput, ETA, cancel, and recovery if the browser is closed and reopened mid-task.
- **Archive extraction** — ZIP (encrypted rejected) and RAR (single-volume unencrypted); see the [ZIP extraction](#zip-extraction) and [RAR extraction](#rar-extraction) sections below for scope.
+- **Archive extraction** — ZIP, RAR and 7z, all behind the same zip-bomb / traversal / ratio protection. ZIP covers stored / deflated / ZIP64 plus **encrypted** entries (ZipCrypto and WinZip AES-128/192/256); RAR covers RAR4 + RAR5 including WinRAR 6/7 "v6", multi-volume, and `-p` / `-hp` encryption; 7z covers Copy / LZMA / LZMA2 / PPMd, the Delta and BCJ2 filters, `.7z.001` volumes, 7zAES, and `-mhe=on` encrypted headers. See the [ZIP extraction](#zip-extraction) and [RAR extraction](#rar-extraction) sections below for scope.
+- **Encrypted archives** — a wrong or missing password is reported as `err_extract_password` and retried through a password prompt, up to three times, with the original conflict policy and large-file opt-in preserved. 7z asks for the password up front instead, so an encrypted header does not cost a wasted scan.
 - **PKG** — install and preview `.pkg` files.
 - **Images** — preview `.png .jpg .jpeg .gif .bmp .webp`.
 - **Localization** — English + Simplified Chinese, auto-selected from `navigator.languages`.
@@ -116,7 +285,7 @@ make
 Output:

 ```text
-web-file-mgr.elf   (~418 KiB, x86_64-sie-ps5)
+web-file-mgr.elf   (~several hundred KiB, larger in v1.9 with unrar; x86_64-sie-ps5)
 ```

 For pure UI/JS work without the PS5 toolchain:
@@ -149,31 +318,35 @@ On first startup, the payload installs a `PS5 Web File Manager` shortcut in the

 ## ZIP extraction

-Plain ZIPs only — stored / deflated / ZIP64, **never encrypted**. The engine is a standalone three-phase module (`scan → extract → publish → cleanup`) at `src/zip_extract.{c,h}`, with a separate host-side C test suite. Each entry is first written into a staging directory (`*.wfm-part-*`), fsynced, then atomically renamed into the destination. Any failure mid-archive rolls back partial changes; cancel and fatal errors always clean up staging.
+Plain and encrypted ZIPs — stored / deflated / ZIP64, in the clear or with either encryption scheme (traditional PKWARE "ZipCrypto" and WinZip AES-128/192/256). The engine is a standalone three-phase module (`scan → extract → publish → cleanup`) at `src/zip_extract.{c,h}`, with a separate host-side C test suite. Each entry is first written into a staging directory (`*.wfm-part-*`), then atomically renamed into the destination. There is deliberately **no per-entry `fsync`** anywhere in the extract path — the whole pipeline is "sync nothing, rename everything", because publish is rename-only and there is no resume feature to protect (measured ≥14x on an 8000-file archive; see `docs/EXTRACTION-PERF.md`). Any failure mid-archive rolls back partial changes; cancel and fatal errors always clean up staging.

 ### Limits

 | Limit | Default profile | Large profile (`ZIPX_LIMITS_LARGE`) |
 |---|---|---|
 | `max_entries` | 200 000 | 500 000 |
-| `max_total_bytes` (uncompressed) | 1 TiB | 2 TiB |
-| `max_file_bytes` (per entry) | 256 GiB | 1 TiB |
+| `max_total_bytes` (uncompressed) | 2 TiB | 4 TiB |
+| `max_file_bytes` (per entry) | 512 GiB | 1 TiB |
 | `max_ratio` (uncompressed / compressed) | 500 : 1 | 1000 : 1 |
 | `max_depth` (folder nesting) | 32 | 32 |
 | `max_name_len` / `max_path_len` | 255 / 1024 | 255 / 1024 |

-The **default profile** is shipped safe: a 4 MiB compressed blob that decodes to 800 GiB is rejected before any output file is opened. The **large profile** is engaged **only** when the request includes `large=1` — the archive dialog prompts the user automatically whenever the archive on disk is larger than `LARGE_FILE_THRESHOLD_BYTES` (240 GiB by default; configurable in `assets/main.js`). Confirming the prompt is the user's explicit opt-in; the server still records nothing extra on its own.
+The **default profile** is shipped safe: a 4 MiB compressed blob that decodes to 800 GiB is rejected before any output file is opened. The **large profile** is engaged **only** when the request includes `large=1` — the archive dialog prompts the user automatically whenever the archive on disk is larger than `LARGE_FILE_THRESHOLD_BYTES` (480 GiB by default; configurable in `assets/main.js`). Confirming the prompt is the user's explicit opt-in; the server still records nothing extra on its own.

 ### Security checks

 The engine refuses to extract:

- Encrypted entries (any encryption flag set).
 - Path traversal (`..` segments, absolute POSIX paths, Windows drive letters).
 - Symbolic links, devices, FIFOs, sockets (`ZIPX_ERR_SPECIAL`).
 - Duplicate entries or directory/file name clashes inside the same archive.
 - Archives whose expanded size, entry count, depth, name length or compression ratio breach the active profile.

+Encrypted entries are no longer a refusal: the password arrives as `password=`
+on `/api/extract`, and a missing or wrong one comes back as `ZIPX_ERR_PASSWORD`
+(`err_extract_password` in the UI) so the prompt can retry. The scan phase still
+runs for encrypted archives — handing over a password does not skip the limits.
+
 ### Conflict policy

 Passed as `conflict=` on `/api/extract`:
@@ -184,41 +357,42 @@ Passed as `conflict=` on `/api/extract`:

 ### Tuning the threshold

-The 240 GiB frontend threshold lives in `assets/main.js`:
+The 480 GiB frontend threshold lives in `assets/main.js`:

 ```js
-const LARGE_FILE_THRESHOLD_BYTES = 240 * 1024 * 1024 * 1024;
+const LARGE_FILE_THRESHOLD_BYTES = 480 * 1024 * 1024 * 1024;
 ```

 Set it to `Infinity` to silence the prompt, lower it to be more conservative, or remove the call entirely — the server still respects `large=1` regardless of the threshold.

 ## RAR extraction

-A single-volume, **unencrypted** RAR archive engine (`src/rar_extract.{c,h}`,
-backed by the vendored FLOSS library
-[`dmc_unrar`](https://github.com/DrMcCoy/dmc_unrar) at
-`third_party/unrar/dmc_unrar.c`). Files with the extension `.rar` get the
-same **Extract** button as `.zip` files; the engine is dispatched by
-`src/extract.c` based on extension.
+A RAR extraction engine (`src/rar_extract.{c,h}`) backed by the **official
+rarlab UnRAR source** (`third_party/unrar7/`, version 7.20.1, compiled as a
+static library and driven through its C-compatible DLL API). Files with the
+extension `.rar` get the same **Extract** button as `.zip` files; the engine
+is dispatched by `src/extract.c` based on extension.
+
+> v1.9 replaced the v1.8 engine (dmc_unrar 1.7.0). dmc_unrar could not
+> decode archives written by WinRAR 6.x/7.x (RAR5 "v6" compression) and had
+> no multi-volume support; unrar handles both natively.

 ### Scope

 | Format | Support | Notes |
 |---|---|---|
-| RAR 1.5 / 2.0 / 2.6 / 2.9 / 3.0 / 3.6 / 4.0 | ✅ | Single-volume, unencrypted |
-| RAR 5.0 | ✅ | Single-volume, unencrypted |
-| Solid blocks, dictionary 4 MiB (RAR4) / 32 MiB (RAR5) | ✅ | |
+| RAR 1.5 → 4.x (incl. 2.9 / 3.6 / 4.0) | ✅ | |
+| RAR 5.0 and **5.0 "v6"** (WinRAR 6.x / 7.x) | ✅ | The v1.9 trigger |
+| Solid blocks, dictionary up to 1 GiB | ✅ | |
 | PPMd decompression (RAR 3.0+) | ✅ | |
-| **Multi-volume** (`.part01.rar` + `.part02.rar` + …) | ❌ | Rejected with `ZIPX_ERR_UNSUPPORTED`. The frontend greys out non-`01` sub-volumes with a tooltip. Join / unrar on a PC first. |
-| **Encrypted RAR** (any encrypted header or file) | ❌ | Rejected with `ZIPX_ERR_UNSUPPORTED`. There is no `password=` field in `/api/extract`. |
+| **Multi-volume** (`.part01.rar` + `.part02.rar` + …) | ✅ | unrar stitches parts by name when the whole set sits next to the volume you open. Select the first volume (`name.part1.rar` / `name.part01.rar`); non-first volumes are still greyed out in the UI with a hint. |
+| **Encrypted RAR** | ✅ | Both `-p` data encryption and `-hp` header encryption. The password reaches the engine as `password=` on `/api/extract` (`RARSetPassword` runs after `RAROpenArchiveEx` and before the first `RARReadHeaderEx`); a missing or wrong one returns `ZIPX_ERR_PASSWORD` so the prompt can retry. |
 | Symbolic links / FIFOs / sockets / devices | ❌ | Rejected with `ZIPX_ERR_SPECIAL` (mirrors ZIP behaviour) |
-| RAR 1.4 (very old) | ❌ | Not supported by dmc_unrar 1.7.0; rejected upstream |
+| RAR 1.3 (pre-1.4) | ❌ | Rejected upstream by unrar |

-The "extract on a PC first" recovery is the same escape hatch the engine
-uses for ZIP encryption errors: when an unsupported archive is rejected,
-the user gets an `extract_unsupported` failure with the file name as the
-detail argument. The frontend already shows this with the typical
-bilingual retry guidance.
+When an archive is rejected, the user gets an `extract_unsupported`
+failure with the file name as the detail argument. The frontend already
+shows this with the typical bilingual retry guidance.

 ### Limits

@@ -228,14 +402,14 @@ profile table on top. Defaults and the `large=1` opt-in are identical:
 | Limit | Default profile | Large profile (`large=1`) |
 |---|---|---|
 | `max_entries` | 200 000 | 500 000 |
-| `max_total_bytes` (uncompressed) | 1 TiB | 2 TiB |
-| `max_file_bytes` (per entry) | 256 GiB | 1 TiB |
+| `max_total_bytes` (uncompressed) | 2 TiB | 4 TiB |
+| `max_file_bytes` (per entry) | 512 GiB | 1 TiB |
 | `max_ratio` (uncompressed / compressed) | 500 : 1 | 1000 : 1 |
 | `max_depth` (folder nesting) | 32 | 32 |
 | `max_name_len` / `max_path_len` | 255 / 1024 | 255 / 1024 |

 Large-profile RAR extraction uses the same `LARGE_FILE_THRESHOLD_BYTES`
-(240 GiB) prompt as ZIP — the frontend treats `.rar` and `.zip` the same
+(480 GiB) prompt as ZIP — the frontend treats `.rar` and `.zip` the same
 way for the prompt, and the server only ever activates the large caps
 when the request carries `large=1` (opt-in).

@@ -255,37 +429,79 @@ The RAR engine applies the same checks as the ZIP engine — re-uses

 ### Vendoring and licence

-`third_party/unrar/dmc_unrar.c` is vendored **verbatim** from
-[`DrMcCoy/dmc_unrar`](https://github.com/DrMcCoy/dmc_unrar), upstream
-commit pinned at the same date as the v1.8 release. The file is
-**GPL-2.0-or-later** (see `third_party/unrar/COPYING`), which means the
-resulting `web-file-mgr.elf` is also effectively GPL-2.0-or-later. The
-already-GPLv3+ project is forward-compatible with that, and the
-compliant distribution form (binary + corresponding sources + GPL
-notice alongside the LGPL notice for libmicrohttpd) is the same
-process you already follow for every prior release. The minimal
-project-authored facade `third_party/unrar/dmc_unrar_api.h` carries the
-project's own licence and is *not* bound to GPL.
+`third_party/unrar7/` is a verbatim copy of the official **rarlab UnRAR
+source** (7.20.1), mirrored by
+[`opello/unrar`](https://github.com/opello/unrar) at commit `97e1780`. It is
+distributed under the **UnRAR freeware licence** (see
+`third_party/unrar7/license.txt`): it may be used in any software to handle
+RAR archives, but may not be used to develop a RAR-compatible *archiver* or
+re-create the RAR compression algorithm. The project-authored facade
+`third_party/unrar7/unrar_c_api.h` carries the project's own licence.

-### v1.9 plan
+> The v1.8 engine `third_party/unrar/dmc_unrar.c` (DrMcCoy/dmc_unrar 1.7.0,
+> GPL-2.0-or-later) was removed in v1.9; its notice lives in git history.

-When (if) multi-volume RAR and encrypted RAR become worth the
-engineering cost, the recommended path is to replace
-`third_party/unrar/dmc_unrar.c` with a vendored mirror of
-[`opello/unrar`](https://github.com/opello/unrar) (a faithful copy of
-rarlab UnRAR 7.x, C++17, supports volumes + encryption). The
-`rar_extract()` signature, the dispatch layer, and the host tests do
-**not** need to change — only the engine behind `rar_extract()` and the
-`password=` field on `/api/extract`. See
-[`third_party/unrar/VENDORED.md`](./third_party/unrar/VENDORED.md) for
-the step-by-step upgrade recipe.
+### Encrypted RAR
+
+The password channel is complete: `password=` on `/api/extract` is handed to
+the engine, and `RARSetPassword` runs after `RAROpenArchiveEx` and before the
+first `RARReadHeaderEx` — the order unrar needs to decrypt a `-hp` header. A
+missing or wrong password comes back as `ZIPX_ERR_PASSWORD`
+(`err_extract_password` in the UI), which is what raises the password prompt
+and re-sends the original request, up to three times.
+
+## 7z extraction
+
+The 7z engine (`src/sevenz_extract.{c,h}`) is built on the LZMA SDK decode
+subset plus the project's own pull-based codec chain
+(`src/sevenz_chain.c`). Files ending in `.7z` get the same **Extract** button as
+`.zip` and `.rar`; `src/extract.c` dispatches by extension, and the engine
+re-uses the same three-phase model, limit profiles and conflict policy.
+
+> Added in v1.9.1. The SDK's own `SzArEx` path only understands folders with up
+> to four coders, which cannot express BCJ2's five — hence the self-parsed
+> folder table and the pull-based chain.
+
+A note on the header. 7-Zip keeps the archive header at the end of the file and
+compresses it when it grows (`-mhc=on`, the default), which is why the header
+region normally starts with an `k7zIdEncodedHeader` record describing one
+folder. With `-mhe=on` that folder is *also* encrypted, and since it holds the
+file names, the folder table and every entry size, the vendored SDK gives up on
+the whole archive before listing anything. `src/sevenz_header.c` handles that
+case: it reads the record, decodes its folder through the same 7zAES path the
+content uses, and then presents the SDK with a virtual stream whose header
+region is the plaintext — the archive on disk is never written to, and an
+archive whose header is merely compressed is not touched at all.
+
+### Scope
+
+| Format | Support | Notes |
+|---|---|---|
+| Copy / LZMA / LZMA2 (incl. ZIP64-style sizes) | ✅ | A single-coder pure-LZMA2 folder decodes multi-threaded (`src/sevenz_mt.c`, 8 threads) |
+| BCJ2 (x86 branch converter) | ✅ | Through the self-written chain; not expressible in the SDK's `SzArEx` |
+| Multi-coder folders, Delta filter, PPC / IA64 / ARM / ARMT / SPARC converters | ✅ | Parsed by `src/sevenz_chain.c` |
+| **Volumes** (`.7z.001` / `.z01` chains) | ✅ | `src/sevenz_volstream.c` stitches by name; open the first volume |
+| **Content encryption** (7zAES, AES-256-CBC) | ✅ | The engine decrypts; the frontend asks for the password up front (so an unencrypted archive does not pay a wasted scan), passes it as `password=`, and retries on `ZIPX_ERR_PASSWORD` |
+| **`-mhe=on` (encrypted header)** | ✅ | `src/sevenz_header.c` decodes the header record itself (through the same 7zAES path) and hands the SDK a virtual stream carrying the plaintext; a wrong password reports `ZIPX_ERR_PASSWORD`, so the prompt retries like any other encrypted archive |
+| `-mhc=off` (uncompressed header) | ✅ | Plain headers were always readable; they are now read one byte at a time and left alone |
+
+### Limits
+
+The 7z engine re-uses the ZIP limits table verbatim — see
+[ZIP extraction → Limits](#limits).
+
+### Security checks
+
+The same `zipx_status_t` codes and the same checks as ZIP and RAR: path
+traversal, special files, duplicate/clashing entries, and size, entry-count,
+depth, name-length or ratio breaches of the active profile.

 ## Verification

 After `make`, sanity-check the produced ELF:

 ```sh
-ls -la web-file-mgr.elf                            # size ~430 KiB on v1.8 (~418 KiB on v1.7)
+ls -la web-file-mgr.elf                            # size grew in v1.9 (unrar static library); ~509 KiB was v1.8.3
 sha256sum web-file-mgr.elf                         # record the digest in your release notes
 file  web-file-mgr.elf                             # expect "ELF 64-bit LSB pie executable, x86-64"
 od -An -tx1 -N20 web-file-mgr.elf | head -2        # magic 7f45 4c46 0201 + e_machine 003e
@@ -295,59 +511,92 @@ The `e_machine = 0x003e` confirms the PS5 target triple `x86_64-sie-ps5`. The `e

 ## Tests

-A POSIX/host-side C test suite covers the ZIP engine and runs on any Linux / macOS / MSYS shell without the PS5 SDK:
+A POSIX/host-side C test suite covers the ZIP, RAR and 7z engines and runs on
+any Linux / macOS / MSYS shell without the PS5 SDK:

 ```sh
-cd tests && bash run-tests.sh
+cd tests && bash run-tests.sh          # ZIP + RAR suites
+bash run-sevenz-tests.sh               # 7z suite (needs MinGW gcc + a 7-Zip binary)
 ```

-Output is a per-case `check`-style report — **83 checks** on the current `main`
-(69 ZIP + 14 RAR). Coverage:
+Output is a per-case `check`-style report — **177 checks** on the current `main`
+(140 ZIP + 37 RAR), 0 failures. Coverage:

 - ZIP entry parsing (stored + deflated + ZIP64)
 - Path traversal, absolute paths, backslash, Windows drive letters
- Symbolic links, FIFOs, encrypted entries, bad CRC, truncated archives, non-ZIP files
+- Symbolic links, FIFOs, bad CRC, truncated archives, non-ZIP files
 - Limits: `entries`, `total_bytes`, `file_bytes`, `ratio`, `depth`, `name_len`
 - Conflict policies: `fail` / `overwrite` / `merge`
 - Cancellation in every phase
+- **Encrypted archives** — each real fixture is run four ways (no password,
+  empty password and wrong password → `ZIPX_ERR_PASSWORD`; correct password →
+  success with a byte-level content check): `enc-zipcrypto.zip`,
+  `enc-aes256.zip` and `enc-aes256-store.zip` on the ZIP side, `enc-v6.rar` on
+  the RAR side. Two further cases prove the limits still apply once a password
+  has been handed over, and that the failing paths publish nothing.
 - **Large-file profile** — `medium_bomb.zip` (ratio ≈ 238) is rejected under default caps and accepted under large caps; lowered large caps still enforce.
- **RAR engine** (`tests/test_rar_extract.c`, 14 checks) — format
+- **RAR engine** (`tests/test_rar_extract.c`, 37 checks) — format
  dispatch (renamed ZIP rejected, junk blob rejected), error translation
-  across every reachable `DMC_UNRAR_*` code, limits handoff (the
-  `large=1` opt-in flows into `rar_extract()` unchanged).
+  across every reachable engine code, limits handoff (the
+  `large=1` opt-in flows into `rar_extract()` unchanged), the oversized
+  dictionary path above, plus the real-archive coverage above.
+- **7z engine** (`tests/test_sevenz_extract.c` + `tests/run-sevenz-tests.sh`) —
+  byte-for-byte comparison against real `.7z` fixtures, encrypted-header
+  rejection, conflicts under every policy, cancellation, limits, a missing
+  destination parent, and the guarantee that a failure publishes nothing and
+  cleans up its staging tree.
+
+The frontend retry flow has its own headless check —
+`node .build/ui_retry_test.mjs` loads the real `assets/main.js` into a stubbed
+DOM and asserts the remembered request, the retry cap and the give-up paths:
+**27 checks, 0 failures**. It lives in `.build/` (outside the gitignore
+whitelist), so it is a development-time script rather than a committed test.

 ## Project layout

 ```
 .
-├── Makefile                      # PS5 + Linux builds (VERSION_TAG v1.8)
+├── Makefile                      # PS5 + Linux builds (VERSION_TAG v1.9.3M)
 ├── install-libmicrohttpd.sh      # one-shot dependency installer
 ├── gen-asset-module.py           # embeds assets/* as gzip-compressed C arrays
 ├── assets/                       # HTML / CSS / JS / icons / param.json
 ├── src/                          # C payload sources
 │   ├── main.c  websrv.c  filemgr.c        # entry, HTTP frontend, task model
-│   ├── upload.c  download.c               # stream handlers
-│   ├── extract.c                          # /api/extract dispatcher (ZIP + RAR)
-│   ├── zip_extract.{c,h}                  # ZIP engine (v1.7)
-│   ├── rar_extract.{c,h}                  # RAR engine (v1.8, dmc_unrar backend)
-│   └── app_installer.c                    # PS5 Media launcher installer
-├── third_party/                  # vendored: zlib, minizip-ng, dmc_unrar
-│   └── unrar/
-│       ├── dmc_unrar.c                    # GPL-2.0-or-later, verbatim upstream
-│       └── dmc_unrar_api.h                # project-authored facade header
+│   ├── upload.c  download.c  text.c       # stream and in-place edit handlers
+│   ├── extract.c                          # /api/extract dispatcher (ZIP + RAR + 7z)
+│   ├── zip_extract.{c,h}  zipx_common.c   # ZIP engine (minizip-ng backend)
+│   ├── zipx_volume.c  zipx_volstream.c    # ZIP volume detection + concatenating stream
+│   ├── rar_extract.{c,h}                  # RAR engine (rarlab UnRAR 7.20.1 backend)
+│   ├── sevenz_extract.{c,h}  sevenz_chain.{c,h}   # 7z engine, self-parsed codec chain
+│   ├── sevenz_header.{c,h}                # 7z header reader / -mhe=on decryption
+│   ├── sevenz_mt.c  sevenz_volstream.c    # multi-threaded LZMA2 + .7z.001 volumes
+│   ├── app_installer.c  pkg_installer.c  pkg_info.c   # PS5 PKG preview / install
+│   └── demangle_stub.c  cpu_support_stub.c            # size / portability stubs
+├── third_party/                  # vendored libraries
+│   ├── unrar7/                            # rarlab UnRAR 7.20.1 — RAR engine
+│   ├── minizip-ng/                        # 4.2.2, trimmed to the read path
+│   ├── 7z/                                # LZMA SDK 26.03 decode subset
+│   └── zlib/                              # minizip's compression backend
 ├── tests/                        # POSIX/host test suite
-│   ├── test_zip_extract.c
-│   ├── test_rar_extract.c        # 14 RAR negative-path checks (v1.8)
-│   ├── make_fixtures.py          # regenerate test fixtures
-│   ├── run-tests.sh              # one-shot runner (now runs ZIP + RAR suites)
-│   ├── compat/                   # tiny Win32/MSYS shims
-│   └── fixtures/                 # generated test ZIPs (and a couple of stub .rar blobs)
+│   ├── test_zip_extract.c  test_rar_extract.c  test_sevenz_extract.c
+│   ├── sevenz_chain_e2e.c  sevenz_e2e.c  bigfile_e2e.c
+│   ├── make_fixtures.py  make_sevenz_fixtures.py  make_split_fixtures.py
+│   ├── run-tests.sh                       # one-shot runner (ZIP + RAR suites)
+│   ├── run-sevenz-tests.sh                # 7z suite, carries the KNOWN_GAPS list
+│   ├── bench_driver.py  bench_formats.py  # throughput benchmarks
+│   ├── compat/                            # tiny Win32/MSYS shims
+│   └── fixtures/  fixtures-7z/  fixtures-real/
 ├── docs/
-│   ├── HANDOVER.md               # engineering handover / dev playbook (also §14 v1.8 close-out)
+│   ├── HANDOVER.md               # v1.8-era playbook, historical — see the root HANDOVER.md
+│   ├── SIZE-OPTIMIZATION.md      # ELF size analysis + per-symbol ledger
+│   ├── EXTRACTION-PERF.md        # decompression benchmarks
+│   ├── REWRITE-FEASIBILITY.md    # engine-extraction study
+│   ├── UPSTREAM-V1.8-COMPARISON.md
 │   ├── UPGRADE-v1.7-zip-large-file-profile.md
 │   ├── UPGRADE-v1.8-rar-support.md
-│   └── screenshots/             # README screenshot images
-├── THIRD_PARTY_NOTICES           # bundled-library credits (incl. dmc_unrar section)
+│   └── screenshots/              # README screenshot images
+├── THIRD_PARTY_NOTICES           # per-library licence summary
+├── HANDOVER.md                   # current engineering handover
 ├── LICENSE                       # GPLv3+
 └── README.md
 ```
@@ -368,19 +617,52 @@ Output is a per-case `check`-style report — **83 checks** on the current `main
 - **This is a homebrew app and should not intentionally modify system processes or kernel memory.** If you hit a kernel panic, make sure you are using a recent jailbreak method and ELF loader, or revert to the stable method you normally use.
 - **P2JB users** — if this payload triggers a kernel panic, avoid using it on that setup. Stability matters more than convenience when each retry is expensive.
 - **The preparing stage can take a while** when a folder contains many files — it sums folder size and checks free space, which helps avoid starting a copy / move / upload / download that cannot finish safely.
- **`err_extract_entry_too_large`** — default archive caps are 256 GiB per
-  entry / 500:1 ratio. Confirm the large-file prompt (appears for
-  archives > 240 GiB on disk), split the archive, or pass `large=1`
-  directly to the API.
- **`err_extract_unsupported`** — the archive uses a feature the engine
-  cannot handle: encrypted ZIP, encrypted RAR, multi-volume RAR
-  (`.part02+.rar`), very-old RAR 1.4, RAR symlinks / FIFOs, or a file
-  that is neither `.zip` nor `.rar`. For RAR specifically the message
-  lists the failure cause and points the user back to a PC extractor.
+- **`err_extract_entry_too_large`** — default archive caps are 512 GiB per
+  entry / 500:1 ratio (covers a typical 3A-game archive with one ~300 GiB
+  uncompressed file). If you exceed the default, confirm the large-file
+  prompt (appears for archives > 480 GiB on disk), split the archive, or
+  pass `large=1` directly to the API.
+- **`err_extract_unsupported`** — the archive is one this build cannot read:
+  a file that is neither `.zip` nor `.rar` nor `.7z`, a ZIP entry using a
+  compression method other than stored/deflated, a 7z folder with an
+  unsupported coder, a split set whose naming is not recognised (a RAR set
+  named `x.rar.001` must be renamed to `x.part1.rar`, `x.part2.rar`, …), or a
+  RAR older than 1.4. Encrypted and multi-volume archives are **not** in this
+  category — both are supported. The backend's own sentence is appended in
+  parentheses and names the actual cause.
+- **`err_extract_dict_too_large`** — a RAR archive declares a compression
+  dictionary larger than this build supports (4096 MiB) and unrar asked for
+  permission to exceed it. The message states both the size the archive needs
+  and the size the build allows. This is refused on purpose: the alternative is
+  a single allocation of the entire dictionary window, which rarlab's own CLI
+  rejects by default and which a 16 GB shared-memory console cannot sustain.
+  Recompress the file on a PC with a dictionary of 4 GiB or less (`-md`), or
+  extract it there. Note that the RAR5 format itself caps the field at 4 GiB,
+  so this can only come from an archive written in the newer RAR7 header
+  format.
+- **`err_extract_password`** — the archive is encrypted and the password was
+  missing or wrong. That includes a 7z archive with an encrypted header
+  (`-mhe=on`): the file names and entry sizes live inside the header, so
+  nothing at all can be listed until the header decrypts. ZIP and RAR raise a
+  password prompt on failure and retry the same request with what you type (up
+  to three times; cancel or an empty box gives up); 7z asks before it starts,
+  since an encrypted 7z header would otherwise cost a wasted scan.

 ## Credits

-This project was built with reference to these projects:
+This project is a **fork of [owendswang/ps5-web-file-manager](https://github.com/owendswang/ps5-web-file-manager)** (GPL-3.0). The web UI,
+the task model and the PS5 packaging all originate there, and the upstream
+author's release under GPL-3.0 is what makes this derivative work possible.
+
+**Telling a fork build from an upstream one:** since v1.9.3 the version string
+carries an `M` suffix (`vX.Y.ZM`) — *M* for *Modified*. Upstream owendswang
+releases are plain `vX.Y.Z`. So `v1.9.2` is upstream/fork-shared numbering while
+`v1.9.3M` can only have come from this repository; the same letter appears in
+the ELF file name, the PS5 start-up notification, `/api/version` and the web UI
+footer. Releases before v1.9.3M predate the convention and keep their plain
+numbers.
+
+Built with reference to these projects:

 - **[ps5-payload-dev/websrv](https://github.com/ps5-payload-dev/websrv):** HTTP server structure, static asset embedding ideas, PS5 browser/websrv behaviour and PKG install function. License: GPLv3+.
 - **[ps5-payload-dev/ftpsrv](https://github.com/ps5-payload-dev/ftpsrv):** PS5 payload conventions, home-screen launcher/install flow reference, process handling style and startup installation reference. License: GPLv3+.
@@ -389,10 +671,12 @@ This project was built with reference to these projects:
 - **[libmicrohttpd](https://ftp.gnu.org/gnu/libmicrohttpd/):** Used as the embedded HTTP server library. Licensed by GNU under the LGPL; this payload links it as the SDK-provided static library.
 - **[ps5-payload-dev/sdk](https://github.com/ps5-payload-dev/sdk):** Payload building foundation. License: GPLv3+.
 - **[etaHEN](https://github.com/etaHEN/etaHEN):** ShellUI URI navigation used to return to the PS5 home screen before exit. License: GPLv3.
- **[ezremote](https://github.com/cy33hc/ps5-ezremote-client):** Preview PKG info. License: GPLv2.
+- **[ezremote](https://github.com/cy33hc/ps5-ezremote-client):** cited for the PKG-preview feature. License: **GPL-2.0-only** — its source files carry no "or later" notice, so it is **not** combinable with this GPL-3.0 codebase. **No code was taken from it:** `src/pkg_info.c` is an independent C99 implementation (it also reads the `.pkg` entry table and `param.json` fields, for which ezremote has no counterpart, and it uses the hand-written tokenizer in `src/json_util.c` rather than json-c). See `docs/REWRITE-FEASIBILITY.md` §2.2.
 - **[zlib-ng/minizip-ng](https://github.com/zlib-ng/minizip-ng):** ZIP reader used by the `/api/extract` endpoint. Vendored under `third_party/minizip-ng/`. License: zlib.
 - **[zlib](https://www.zlib.net/):** Compression backend for minizip-ng. Vendored under `third_party/zlib/`. License: zlib.
- **[DrMcCoy/dmc_unrar](https://github.com/DrMcCoy/dmc_unrar):** RAR reader used by the `/api/extract` endpoint. Vendored under `third_party/unrar/` as a single-file drop-in (`dmc_unrar.c`); the project-authored facade `dmc_unrar_api.h` carries the project's own licence. License: GPL-2.0-or-later — see `third_party/unrar/COPYING`.
+- **[rarlab UnRAR](https://www.rarlab.com/rar_add.htm)** — RAR reader used by the `/api/extract` endpoint since v1.9. Vendored under `third_party/unrar7/` (version 7.20.1, the RARDLL source set). License: **UnRAR freeware license** — see `third_party/unrar7/license.txt`. Note this is a restricted licence rather than a FLOSS one: it permits using the source to handle RAR archives but forbids using it to build a RAR-compatible compressor.
+- **[opello/unrar](https://github.com/opello/unrar)** — the mirror the vendored rarlab sources were fetched from (commit `97e1780`).
+- **[DrMcCoy/dmc_unrar](https://github.com/DrMcCoy/dmc_unrar)** — RAR engine shipped in v1.8 only, superseded in v1.9 by rarlab UnRAR (it could not decode RAR5 "v6" archives or multi-volume sets). Removed from the tree; its licence was GPL-2.0-or-later.

 ## License

@@ -405,12 +689,14 @@ in addition to this project's GPL license. The vendored `zlib` and
 `minizip-ng` sources are distributed under the zlib license; retain the
 copyright notices in `third_party/zlib/LICENSE` and
 `third_party/minizip-ng/LICENSE` when redistributing binaries built
-with this feature. The vendored `dmc_unrar` (RAR engine) is distributed
-under the GPL-2.0-or-later; retain the copyright notice in
-`third_party/unrar/COPYING` and ship the corresponding sources when
-redistributing binaries built with v1.8 or later (the `web-file-mgr.elf`
-binary is already GPLv3+, so the additional source-disclosure
-requirement is the only practical effect).
+with this feature.
+
+The vendored `third_party/unrar7/` sources (rarlab UnRAR — the RAR engine
+behind `src/rar_extract.c`) are **not** GPL: they ship under the UnRAR
+freeware license (see `third_party/unrar7/license.txt`), which forbids
+using them to develop a RAR-compatible compressor. Keep that notice and
+that restriction intact when redistributing. `THIRD_PARTY_NOTICES` carries
+the full per-library summary.

 ## Disclaimer

@@ -0,0 +1,487 @@
+<div align="right">
+  <a href="README.md">English</a> · <a href="README.zh-CN.md">简体中文</a>
+</div>
+
+# PS5 网页文件管理器（PS5 Web File Manager）
+
+> 面向已越狱 PS5 主机的自制 HTTP 文件管理器。通过同一局域网内的任意浏览器（包括 PS5 自带浏览器）即可浏览、编辑、上传、下载并解压 ZIP / RAR / 7z 压缩包——单个自包含 ELF 载荷，无外部服务、无遥测上报。
+
+**版本：** v1.9.2 · **标题 ID：** `FMGR88888` · **许可证：** GPLv3+ · **目标平台：** `x86_64-sie-ps5`
+
+---
+
+## 概述
+
+一个在已越狱 PS5 上运行的 HTTP 文件管理器载荷。从局域网内任意浏览器（含 PS5 浏览器本身）打开 `http://<PS5_IP>:8888/`，即可管理外接 USB 存储与用户分区的文件。设计初衷是安全地把游戏 dump 文件夹从 USB 拷贝到内置存储，但它同时也支持常规文件管理、原地文本编辑、PKG 预览/安装、图片预览，以及内置防 zip 炸弹保护的解压功能。
+
+同一套源码树可构建出供开发用的 Linux 二进制，以及供部署的 PS5 载荷 ELF——见下方 `make linux`。
+
+> **第一次用、不想看技术细节？** 直接看
+> [《新手使用说明》](docs/USER-GUIDE-zh-CN.md)：怎么装、怎么传文件、怎么解压（含带密码与分卷的包）、
+> 界面上每句话是什么意思，以及与上游原版的差别——全部用大白话写。
+
+## 未发布内容（下次发版将包含）
+
+**加密归档现在可以端到端解压——ZIP（两种方案）、RAR，以及带头加密的 7z 都已打通。**
+
+此前所有加密归档都会被提前拒绝，尽管密码输入框、失败提示与 `extract_password` 文案从 v1.9 起就已就位。真正的缺口在引擎侧，而不在 UI：
+
+- **ZIP**：vendored 的 minizip-ng 在裁剪时把 crypto 后端一起裁掉了，于是（未被改动的）`mz_zip.c` 里那些 `-DHAVE_WZAES` / `-DHAVE_PKCRYPT` 分支没有实现可调。
+- **RAR**：rarlab UnRAR 本身能解密，但 `RARSetPassword` 从未被调用。
+- **7z**：`-mhe=on` 把文件名与 folder 表放进了加密头，归档连列出都做不到。
+
+三者现在都已接线。密码缺失或错误会统一报为 `extract_password`（引擎层即 `ZIPX_ERR_PASSWORD`），也就是任务浮层已有的密码提示所响应的那个错误码。
+
+### 变更
+
+- **版本号加改版标记：`v1.9.3` → `v1.9.3M`。** 上游 owendswang 的发布版是纯 `vX.Y.Z`，因此这个 `M`（Modified，改版）就是「上游原版还是本仓改版」的判据。它是 `VERSION_TAG` 的一部分，所以 `/api/version`、PS5 启动通知、stdout 横幅、网页右下角**与 ELF 文件名**会一次性全部带上；网页右下角另加悬浮提示（`versionTooltip`，中英各一）解释这个字母的含义，免得没读过发行说明的人无从判断。产物名随之改变，也顺带让本仓产物再不可能与上游同版本号的资产同名相撞。
+
+### 新增
+
+- **加密 ZIP** —— 传统 PKWARE（「ZipCrypto」，即 `zip -e` 写出的格式）与 WinZip AES-128/192/256（压缩方法 `99` + `0x9901` 扩展字段，即 `7z -mem=AES256` 写出的格式），stored 与 deflated 条目均支持。
+- **加密 RAR** —— `-p` 内容加密与 `-hp` 头加密。`RARSetPassword` 现在在 `RAROpenArchiveEx` 之后、首次 `RARReadHeaderEx` 之前调用，这正是 unrar 解密 RAR5 头所需的顺序。
+- `/api/extract` 的 `password=` 现在对两个引擎都能真正走到解密路径。空值或缺失视为「无密码」，因此表单原值可以直接透传。
+- `third_party/minizip-ng/src/mz_crypt_wfm.c` —— 为裁剪后的 minizip-ng 提供的本地 crypto 后端：SHA-1、HMAC-SHA1、AES-128/192/256；S-box 与 GF(2^8) 表在首次使用时推导，因此二进制不新增任何 `.rodata` 查表。PBKDF2 复用 vendored 的 `mz_crypt.c`；随机数直接读 `/dev/urandom`（不再是 `mz_os_rand()`），从而把 `rand`/`srand` 排除在导入表之外。以下文件按上游 4.2.2 原样恢复：`mz_strm_wzaes.{c,h}`、`mz_strm_pkcrypt.{c,h}`。
+- **前端在密码失败后可直接重试**：`extract_password` 失败不再只是弹一个错误框，而是弹出密码输入框并按原参数（冲突策略、大文件选配）重新发起同一次解压，最多重试 3 次；取消或留空则回落到原有的失败提示。
+- **加密 7z 头（`-mhe=on`）现在可以打开。** 这是最后一个已知的格式缺口：`-mhe=on` 时文件名、folder 表**与每个条目的尺寸**全都在加密头里，因此 vendored SDK 在能列出任何条目之前就以 `SZ_ERROR_UNSUPPORTED` 退出。新模块 `src/sevenz_header.c` 读出该头部记录，用它自己的那一个 folder 走项目自研的 7zAES 路径（`src/sevenz_chain.c`）解码，然后交给 SDK 一个虚拟流——把加密头所在区域替换成明文。SDK 于是照常解析它一向解析的那个归档，磁盘上的文件完全不被改动；头部只是被*压缩*（`-mhc=on`，默认）的归档完全不受影响；密码错误则与其它加密归档一样返回 `extract_password`。
+- `tests/make-zip-enc-fixtures.bat`，以及 `tests/fixtures-real/` 下的三个真实 fixture（`enc-zipcrypto.zip`、`enc-aes256.zip`、`enc-aes256-store.zip`，密码 `secret123`）。
+
+### 修复
+
+- **编译选项变化现在会使目标文件失效。** `make` 察觉不到编译选项变化，因此加上 `-DHAVE_WZAES -DHAVE_PKCRYPT` 后旧的 `mz_zip.o` / `mz_crypt.o` 原样保留——又因为此时已没有任何代码引用新流，`--gc-sections` 会在链接「成功」的同时把加密代码再次丢掉（本次改动的第一次构建产物与已发布的 release 逐字节相同）。Makefile 现在把第三方编译选项集记录进 `ps5-obj/.third_party_cflags` / `linux-obj/.third_party_cflags`，只在真正变化时重编——这正是早年 `LzmaDec.o` 规则所规避的同一个陷阱，现已通用化。
+- `ZIPX_ERR_UNSUPPORTED` 不再涵盖加密，现在仅表示「多卷或不受支持的压缩方法」。
+- 顺带把 `tests/test_sevenz_extract.c` 里一处会导致截断告警的 `snprintf` 缓冲区调足。
+
+### 测试
+
+- `tests/test_zip_extract.c` 对每个加密 fixture 跑四种情况（无密码 → `PASSWORD`、空密码 → `PASSWORD`、错密码 → `PASSWORD`、正确密码 → `ZIPX_OK` 并逐字节校验内容），另加一项证明「提供密码后限额依旧生效」。
+- `tests/test_rar_extract.c` 对 `enc-v6.rar` 做同样的四种情况验证，包括失败路径绝不发布任何文件。
+- `tests/test_sevenz_extract.c` 对 `aeshe.7z` 跑三种情况：无密码 → `ZIPX_ERR_PASSWORD`、错密码 → `ZIPX_ERR_PASSWORD`、正确密码 → 成功且逐字节一致，并证明失败后不留下 staging 目录。
+- 前端重试流程有一份无头检查（`.build/ui_retry_test.mjs`，把 `assets/main.js` 载入桩 DOM）：**40 项检查**，覆盖参数记忆、重试上限、取消与空密码的回落，以及「非 ASCII 目录下必须仍然弹出密码框」的回归用例。另有一份 `.build/ui_upload_menu_test.mjs`（**40 项检查**）盯标记侧：i18n 键在两份语言文件里都存在、上传菜单接对了回调、用到的 class 确实有样式、菜单行高亮规则必须带面板作用域（否则会输给通用按钮规则而静默失效），以及**解压按钮不许被隐藏、只许被置灰**（顺带扫 `main.js` 里 117 个 `t("...")` 键是否双语齐全）。
+- 主机端合计：**140 ZIP + 37 RAR = 177 项检查**，0 失败。
+- 请求的字典超过本构建支持上限的 RAR 归档不再被误报成「单条目过大」：它有独立的 `extract_dict_too_large` 编码，报错文案同时给出归档需要的字典与构建支持的上限。构建行为**未变** —— 这类归档仍然被拒，因为放行意味着一次性分配整个字典窗口，而这正是 rarlab 自家 CLI 默认拒绝、16 GB 共享内存的主机也承受不了的。
+- 7z 套件：**27 项用例，0 失败**（`tests/run-sevenz-tests.sh`），且原先登记 `aeshe` 的 `KNOWN_GAPS` 列表现已**清空**——加密头 fixture 同时通过 folder 解码器与解压 façade 两条路径。
+- 当前源码树构建产物 **903 448 B**，sha256 `8ca47d5aaca75085b32641300cce30fadb7df7749cb6b53d04f129bcecc286b7`，`e_machine` 为 `0x003e`；同一源码树构建两次逐字节一致。产物内已确认包含新的前端代码（前端资源是 gzip 内嵌的，需先解压才能在二进制里检索到）。段数仍为 20，**动态符号零新增**。加密归档那批改动净增 5 712 字节正文（`.text` +4 880、`.rodata` +640、`.eh_frame*` +192）；加 `M` 标记再让 `.rodata` 涨 0x100（256 B），修正 `err_extract_unsupported` 文案再涨 0x40（64 B），上传菜单再涨 0x980（2 432 B），第一轮修复的文案与 CSS 再涨 0x100（256 B），菜单行高亮的收敛规则再涨 0x180（384 B），解压按钮常显（去掉 `hidden`、换短标签、三条禁用理由、`.extract-action:disabled`）再涨 0x240（576 B），**其余段尺寸一个都没变**，因此文件总尺寸仍是 903 448 B。**尺寸没变不等于内容没变** —— 判断只看 `readelf -SW` 的段尺寸。
+
+### 仍未完成
+
+- 在真机上做端到端验证。
+
+> 注意：本节描述的是**未发布**状态。已发布版本号仍为 `v1.9.2`，其二进制**不含**上述加密支持；当前未发布的源码树自报版本为 `v1.9.3M`。
+
+## v1.9.2 与 v1.9.1 新增内容
+
+> **v1.9.2 与 v1.9.1 的功能完全相同，只换了内嵌版本号。** 原因是原先的 `v1.9.1` tag 指在产出发布二进制的提交**之前 4 个提交**，tag 与产物对不上（clone 该 tag 无法重建出发布的那份 ELF）；v1.9.2 重新从产出该二进制的提交上打，使 tag = 源码 = 二进制。
+
+- **7z 解压引擎**（`src/sevenz_extract.{c,h}`）：自研解码子集 + 拉式 codec 链（`src/sevenz_chain.c`，覆盖 LZMA2 / BCJ2 等），由 `src/extract.c` 按扩展名分派，与 ZIP / RAR 共用同一套三阶段模型与限额档位。`.7z` 文件在文件列表中同样带「解压」按钮。
+- **7zAES 内容解密**（AES-256-CBC）：引擎可解密带密码的 7z 内容，密码经 `/api/extract` 的 `password=` 传入；解压 7z 时前端会提前询问密码。ZIP / RAR 的加密当时尚未打通（引擎侧缺口，见顶部「未发布内容」），v1.9.1 时对它们仍会报 `extract_unsupported`。
+- **7z 分卷**：`.7z.001` / `.z01` 等链式分卷由 `src/sevenz_volstream.c` 按名拼接，打开首个分卷即可。
+- **性能三项**（纯解码提速，不影响功能面）：
+  - SDK 汇编 LZMA 解码器（`Asm/x86/LzmaDecOpt.asm` + jwasm，无 jwasm 自动回退纯 C）≈ 1.26×。
+  - 纯 LZMA2 文件夹多线程解码（`src/sevenz_mt.c` + `Lzma2DecMt`，8 线程）≈ 1.37×。
+  - 移除 ZIP 逐条目 fsync，减少 staging 重命名前的写盘开销。
+- **当时唯一缺口**：7z `-mhe=on` 加密头（独立单元，读取需自研头解析器），其余 7z 特性均已支持。已在顶部「未发布内容」中补上。
+
+## v1.9 新增内容
+
+- **RAR 引擎替换为官方 rarlab UnRAR 7.20.1**（`third_party/unrar7/`，取代 dmc_unrar）。这正是让 RAR 解压在真实文件上可用的一步：dmc_unrar 无法解码 **WinRAR 6.x/7.x** 写出的归档（RAR5「v6」压缩），也不支持多卷；两者现在都能工作。
+- **RAR5「v6」归档可解压**（v1.8 时代在 WinRAR 6/7 文件上报「归档损坏」的问题已消失）。
+- **多卷 RAR**（`.part01.rar` 链）：当完整卷集与被打开的卷放在同一目录时，unrar 按文件名拼接各部分。
+- 引擎可解密加密 RAR（`RARSetPassword`）——发 v1.9 时密码 UI / API 接线尚未完成，加密归档会被拒绝；该接线已在顶部「未发布内容」中补齐。
+- 主机测试现用真实归档（v6 / 加密 / 3 卷 fixture，提交于 `tests/fixtures-real/`）：**70 ZIP + 24 RAR = 94 项检查**。
+
+## v1.8 新增内容
+
+- **单卷 RAR 解压**，基于内置的 FLOSS 库 [`dmc_unrar`](https://github.com/DrMcCoy/dmc_unrar)（GPL-2.0-or-later）。支持 RAR 1.5、2.x、3.x、4.x、5.x 归档。`.rar` 文件出现在文件列表中且「解压」按钮可用；`.part02+.rar` 子卷上的按钮置灰，提示「请选择主卷」——v1.8 无法拼接多卷 RAR（见下方 [RAR 解压](#rar-解压) 章节）。
+- 新引擎 `src/rar_extract.c` 与既有 `src/zip_extract.c` 之间**共享解压协议**：相同的 `zipx_status_t` 状态码、相同的 `zipx_limits_t` 档位（默认 / `large=1`）、相同的三阶段模型（`scan → extract → publish → cleanup`）、相同的 staging 目录布局、相同的冲突策略、相同的错误映射到任务 UI。`src/extract.c` 中的分派器只是一个微小的 `ends_with_ci(…)` 判断。
+- **14 个新增主机端 C 测试**（`tests/test_rar_extract.c`）接入现有 `tests/run-tests.sh`。覆盖：格式分派、每个影响 RAR 用户的 `DMC_UNRAR_*` 错误码翻译、限额档位交接。主机检查总数：**69 ZIP + 14 RAR = 83**。
+- **文档**：[`CHANGELOG.md`](./CHANGELOG.md)、[`docs/UPGRADE-v1.8-rar-support.md`](./docs/UPGRADE-v1.8-rar-support.md)，以及 `third_party/unrar7/VENDORED.md` 中的 vendoring 决策树（v1.8 时为 `third_party/unrar/VENDORED.md`）。
+
+## v1.8.1 新增内容
+
+- **放宽默认 ZIP 限额**（配合 v1.7 的大档案档位）。v1.7 默认单条目上限为 64 GiB，对典型 PS5 系统备份 ZIP（200–300 GiB）过于激进。v1.8.1 将默认档位提高到 **总量 1 TiB / 单条目 256 GiB / 500:1 比率**，保留 `large=1` 选项为 2 TiB / 1 TiB / 1000:1。前端阈值从 60 GiB 提升到 240 GiB，使常见系统备份归档不再触发确认提示。
+- RAR 解压继承这些新默认值（`rar_extract.c` 直接从引擎透传 `c->limits`，无需改引擎）。
+- 理由：真正的防 zip 炸弹防线是 `check_space()`（staging 前基于 statvfs 的真实磁盘空间检查）+ `max_ratio`（声明的压缩比上限）。尺寸上限只是 UX 护栏，而非安全边界。
+
+## v1.8.2 新增内容
+
+- **再次放宽默认 ZIP 限额**，针对 3A 游戏单文件场景。v1.8.1 仍会静默拒绝归档内单个约 300 GiB 的未压缩文件（默认扫描在请求到达前端确认提示之前就返回 `ZIPX_ERR_LIMIT_FILE_SIZE`）。v1.8.2 将默认档位提高到 **总量 2 TiB / 单条目 512 GiB / 500:1 比率**，`large=1` 选件提到 4 TiB / 1 TiB / 1000:1。前端阈值从 240 GiB 提升到 480 GiB。
+- **两个 PS5 专属构建修复**，在交叉编译 PS5 目标时发现。主机端测试套件（`tests/run-tests.sh`）曾静默接受二者，因为它链接相同源码但使用 gcc 而非 clang 18，且包含路径不同：
+  - `Makefile` CFLAGS：加入 `-Ithird_party/unrar`，使 `src/rar_extract.c` 能找到项目自有的 `dmc_unrar_api.h` 门面头文件。
+  - `src/extract.c`：把 `extract_progress()` 定义移到 `extract_dispatch()` 之前，避免被 `-Werror=implicit-function-declaration` 标记（PS5 SDK 的 clang 18 比测试用的主机 gcc 更严格）。
+- v1.8.2 发布产物：`web-file-mgr.elf` —— 509 704 字节，sha256 `1b2c3d68b35e32737105f17d14a80a3c159ceca0cabd274ee168cbcd81906f65`，ELF 64 位小端，e_machine `0x003e`（x86_64-sie-ps5）。
+- 测试：**84 项主机端检查**（70 ZIP + 14 RAR），0 失败。PS5 交叉编译端到端成功。
+
+## v1.7 新增内容
+
+- **ZIP 大文件档位**（通过在 `/api/extract` 传入新的 `large=1` 参数选配启用）：放宽的限额为 **总量 2 TiB** / **单条目 1 TiB** / **1000:1 压缩比**。当磁盘上归档大于 **60 GiB** 时前端会提示确认；仅当用户明确同意时服务器才启用该档位。
+- **更严格的默认 ZIP 档位**保持安全：**总量 1 TiB** / **单条目 256 GiB** / **500:1 比率**。一个 4 MiB 压缩包解压到 800 GiB 仍会在打开任何输出文件之前被拒绝。
+- **69 项主机端 C 测试**（`tests/run-tests.sh`）现已覆盖路径穿越、ZIP64、加密拒绝、压缩比、冲突策略与新增大文件档位（`tests/test_zip_extract.c`）。
+- 更早的细化——见 v1.6 以来的 `git log`。
+
+## 截图
+
+<p>
+  <a href="docs/screenshots/20260617_231827.376.jpg" target="_blank"><img src="docs/screenshots/20260617_231827.376.jpg" width="31%" alt="PS5 网页文件管理器截图 1"></a>
+  <a href="docs/screenshots/20260619_131432.399.jpg" target="_blank"><img src="docs/screenshots/20260619_131432.399.jpg" width="31%" alt="PS5 网页文件管理器截图 2"></a>
+  <a href="docs/screenshots/20260617_232348.855.jpg" target="_blank"><img src="docs/screenshots/20260617_232348.855.jpg" width="31%" alt="PS5 网页文件管理器截图 3"></a>
+  <a href="docs/screenshots/20260619_131811.644.jpg" target="_blank"><img src="docs/screenshots/20260619_131811.644.jpg" width="31%" alt="PS5 网页文件管理器截图 4"></a>
+  <a href="docs/screenshots/20260619_131535.239.jpg" target="_blank"><img src="docs/screenshots/20260619_131535.239.jpg" width="31%" alt="PS5 网页文件管理器截图 5"></a>
+  <a href="docs/screenshots/20260620_232728.533.jpg" target="_blank"><img src="docs/screenshots/20260620_232728.533.jpg" width="31%" alt="PS5 网页文件管理器截图 6"></a>
+</p>
+
+## 功能
+
+- **浏览** —— 列出文件与文件夹；按名称、类型、大小、修改时间或权限排序。上次排序方式持久化在 `localStorage`。
+- **权限** —— 用复选框切换读/写/执行，或粘贴经过校验的四位八进制模式。
+- **操作** —— 复制、移动、删除（递归、无回收站）、重命名、创建文件与文件夹。
+- **编辑器** —— 针对 ≤ 1 MiB 的文件，跨精选扩展名列表的原地 UTF-8 文本编辑器：`.txt .json .xml .ini .cfg .conf .md .log .lua .js .css .html .htm .c .h .cpp .hpp .sh .csv .yaml .yml .shn`。
+- **多选** —— 一次性复制、移动、删除或打包下载多个项目。
+- **上传** —— 从局域网内任意设备上传单文件或文件夹树（在 PS5 浏览器中隐藏）。原子化的临时文件 + 重命名。
+- **下载** —— 单文件以原始字节下载，或文件夹/多选以流式 `.tar` 下载。在 PS5 浏览器中隐藏。
+- **任务** —— 全屏覆盖层，带延迟显示、实时进度、吞吐率、ETA、取消，以及浏览器中途关闭重开后的恢复能力。
+- **归档解压** —— ZIP、RAR、7z 三种引擎，均带防 zip 炸弹 / 路径穿越 / 压缩比保护。ZIP 覆盖 stored / deflated / ZIP64 以及**加密**条目（ZipCrypto 与 WinZip AES-128/192/256）；RAR 覆盖 RAR4 + RAR5（含 WinRAR 6/7「v6」）、多卷，以及 `-p` / `-hp` 加密；7z 覆盖 LZMA / LZMA2 / PPMd、Delta 与 BCJ2、`.7z.001` 分卷、7zAES 与 `-mhe=on` 加密头。详见下方 [ZIP 解压](#zip-解压)、[RAR 解压](#rar-解压)、[7z 解压](#7z-解压)。
+- **加密归档重试** —— 解压遇到加密归档时，会弹出密码输入框并按原参数自动重试（最多 3 次）；也可以在解压 7z 时提前输入密码以免白跑一次扫描。
+- **PKG** —— 安装并预览 `.pkg` 文件。
+- **图片** —— 预览 `.png .jpg .jpeg .gif .bmp .webp`。
+- **本地化** —— 英文 + 简体中文，根据 `navigator.languages` 自动选择。
+- **移动端友好** —— 响应式布局，工具栏自动换行，文件列表可横向滚动。
+
+## 快速上手
+
+1. **构建** ELF：
+
+   ```sh
+   export PS5_PAYLOAD_SDK=/opt/ps5-payload-sdk   # 见「构建」章节的 SDK 配置
+   make
+   ```
+2. **发送** 载荷到 PS5（默认 ELF 加载器端口 `9021`）：
+
+   ```sh
+   nc -q0 "$PS5_HOST" 9021 < web-file-mgr.elf
+   ```
+3. **读取** PS5 屏幕上的通知——它会打印实际监听端口（默认 `8888`）。
+4. 在**同一局域网**内的任意浏览器中打开 `http://<PS5_IP>:<port>/`——PS5 浏览器也可以。
+5. 首次运行时，载荷还会写入一个 **Media** 分类的主屏启动器；已有的启动器文件不会被覆盖。
+
+## 构建
+
+需要 [ps5-payload-dev/sdk](https://github.com/ps5-payload-dev/sdk#quick-start)：
+
+```sh
+export PS5_PAYLOAD_SDK=/opt/ps5-payload-sdk
+```
+
+本项目链接 `libmicrohttpd`。`make` 在构建前会检查它，缺失时自动运行安装器：
+
+```sh
+make
+```
+
+若构建主机无网络访问，可提前放入 libmicrohttpd 源码包并手动运行安装器：
+
+```sh
+LIBMICROHTTPD_TARBALL=/path/to/libmicrohttpd-1.0.1.tar.gz \
+  ./install-libmicrohttpd.sh
+make
+```
+
+输出：
+
+```text
+web-file-mgr.elf   （约数百 KiB，v1.9.1 含 unrar7 + 7z 后更大；x86_64-sie-ps5）
+```
+
+若只想做纯 UI/JS 开发而不需要 PS5 工具链：
+
+```sh
+make linux
+./web-file-mgr-linux
+```
+
+Linux 构建**不包含** PS5 主屏启动器安装器。
+
+## 使用
+
+在 PS5 上启动一个 ELF 加载器（端口 `9021` 常见）。发送载荷：
+
+```sh
+export PS5_HOST=ps5_ip_address
+nc -q0 "$PS5_HOST" 9021 < web-file-mgr.elf
+```
+
+载荷启动后，PS5 通知会显示应用名、版本与实际监听端口。打开它打印的 URL，例如：
+
+```text
+http://${PS5_IP_ADDRESS}:8888/
+```
+
+若载荷不得不回退到其它端口（如 `8889`），请以通知显示的端口为准——URL 并未硬编码。
+
+首次启动时，载荷会在需要时于 Media 分类安装一个 `PS5 Web File Manager` 快捷方式。已有的启动器文件会被保留；只补写缺失的文件。
+
+## ZIP 解压
+
+支持普通 ZIP 与加密 ZIP——stored / deflated / ZIP64，传统 PKWARE（ZipCrypto）与 WinZip AES-128/192/256 两种加密方案。引擎是一个独立的三阶段模块（`scan → extract → publish → cleanup`），位于 `src/zip_extract.{c,h}`，配有独立的主机端 C 测试套件。每个条目先写入 staging 目录（`*.wfm-part-*`），再原子重命名到目标位置。解压路径里**刻意不做逐条目 `fsync`**——整条流水线是「不 sync、只 rename」，因为 publish 只是 rename、也没有续解功能需要保护（8000 文件档实测 ≥14×，见 `docs/EXTRACTION-PERF.md`）。归档中途任何失败都会回滚部分改动；取消与致命错误总会清理 staging。
+
+### 限额
+
+| 限额 | 默认档位 | 大档案档位（`ZIPX_LIMITS_LARGE`） |
+|---|---|---|
+| `max_entries` | 200 000 | 500 000 |
+| `max_total_bytes`（未压缩） | 2 TiB | 4 TiB |
+| `max_file_bytes`（单条目） | 512 GiB | 1 TiB |
+| `max_ratio`（未压缩 / 压缩） | 500 : 1 | 1000 : 1 |
+| `max_depth`（文件夹嵌套） | 32 | 32 |
+| `max_name_len` / `max_path_len` | 255 / 1024 | 255 / 1024 |
+
+**默认档位**出厂即安全：一个解压到 800 GiB 的 4 MiB 压缩块会在打开任何输出文件之前被拒绝。**大档案档位**仅在请求携带 `large=1` 时才启用——当磁盘上归档大于 `LARGE_FILE_THRESHOLD_BYTES`（默认 480 GiB；可在 `assets/main.js` 配置）时，解压对话框会自动提示用户。确认提示即为用户的明确选配；服务器自身不会额外记录任何内容。
+
+### 安全检查
+
+引擎拒绝解压以下归档：
+
+- 路径穿越（`..` 段、绝对 POSIX 路径、Windows 盘符）。
+- 符号链接、设备、FIFO、套接字（`ZIPX_ERR_SPECIAL`）。
+- 同一归档内的重复条目或目录/文件名冲突。
+- 解压后尺寸、条目数、嵌套深度、名称长度或压缩比突破当前档位。
+
+加密条目**不再**属于拒绝项：密码通过 `/api/extract` 的 `password=` 传入，缺失或错误时返回 `zipx` 层的 `ZIPX_ERR_PASSWORD`（前端对应 `err_extract_password`），由界面提示后重试。scan 阶段对加密条目同样生效——限额不会因为提供了密码而被跳过。
+
+### 冲突策略
+
+通过 `/api/extract` 上的 `conflict=` 传入：
+
+- `fail`（默认）—— 拒绝覆盖任何已存在的目标。
+- `overwrite` —— 替换已存在文件；合并进已存在文件夹。
+- `merge` —— 保留已存在文件，新增其余文件。
+
+### 调整阈值
+
+480 GiB 的前端阈值位于 `assets/main.js`：
+
+```js
+const LARGE_FILE_THRESHOLD_BYTES = 480 * 1024 * 1024 * 1024;
+```
+
+设为 `Infinity` 可静音提示，调低则更保守，或干脆删掉该调用——无论阈值如何，服务器始终遵循 `large=1`。
+
+## RAR 解压
+
+RAR 解压引擎（`src/rar_extract.{c,h}`）由 **官方 rarlab UnRAR 源码** 支撑（`third_party/unrar7/`，版本 7.20.1，编译为静态库并通过其 C 兼容的 DLL API 驱动）。扩展名为 `.rar` 的文件与 `.zip` 文件一样拥有**解压**按钮；引擎由 `src/extract.c` 按扩展名分派。
+
+> v1.9 替换了 v1.8 的引擎（dmc_unrar 1.7.0）。dmc_unrar 无法解码 WinRAR 6.x/7.x 写出的归档（RAR5「v6」压缩）且不支持多卷；unrar 原生支持两者。
+
+### 支持范围
+
+| 格式 | 支持 | 备注 |
+|---|---|---|
+| RAR 1.5 → 4.x（含 2.9 / 3.6 / 4.0） | ✅ | |
+| RAR 5.0 及 **5.0「v6」**（WinRAR 6.x / 7.x） | ✅ | v1.9 的触发点 |
+| Solid 块、最大 1 GiB 字典 | ✅ | |
+| PPMd 解压（RAR 3.0+） | ✅ | |
+| **多卷**（`.part01.rar` + `.part02.rar` + …） | ✅ | 当完整卷集与被打开的卷同处一目录时，unrar 按名拼接。选择首个卷（`name.part1.rar` / `name.part01.rar`）；非首卷在 UI 中仍置灰并给出提示。 |
+| **加密 RAR** | ✅ | `-p` 内容加密与 `-hp` 头加密均可。密码经 `/api/extract` 的 `password=` 传入引擎（`RARSetPassword` 在 `RAROpenArchiveEx` 之后、首次 `RARReadHeaderEx` 之前调用）；缺失或错误返回 `ZIPX_ERR_PASSWORD`，界面提示后重试。 |
+| 符号链接 / FIFO / 套接字 / 设备 | ❌ | 以 `ZIPX_ERR_SPECIAL` 拒绝（与 ZIP 行为一致） |
+| RAR 1.3（1.4 之前） | ❌ | 被 unrar 上游拒绝 |
+
+当某归档被拒绝时，用户会收到 `extract_unsupported` 失败，文件名作为详情参数。前端已用典型的双语重试指引显示该错误。
+
+### 限额
+
+RAR 引擎原样复用 ZIP 的限额表——其上并无额外的 RAR 档位表。默认值与 `large=1` 选配完全相同：
+
+| 限额 | 默认档位 | 大档案档位（`large=1`） |
+|---|---|---|
+| `max_entries` | 200 000 | 500 000 |
+| `max_total_bytes`（未压缩） | 2 TiB | 4 TiB |
+| `max_file_bytes`（单条目） | 512 GiB | 1 TiB |
+| `max_ratio`（未压缩 / 压缩） | 500 : 1 | 1000 : 1 |
+| `max_depth`（文件夹嵌套） | 32 | 32 |
+| `max_name_len` / `max_path_len` | 255 / 1024 | 255 / 1024 |
+
+大档案档位的 RAR 解压使用与 ZIP 相同的 `LARGE_FILE_THRESHOLD_BYTES`（480 GiB）提示——前端对 `.rar` 与 `.zip` 的提示处理相同，且服务器仅在请求携带 `large=1`（选配）时才启用大限额。
+
+### 安全检查
+
+RAR 引擎应用与 ZIP 引擎相同的检查——复用 `zipx_status_t` 状态码，因此任务 UI 的 `err_extract_unsafe_name`、`err_extract_too_deep`、`err_extract_ratio` 等会一致触发：
+
+- 路径穿越（`..` 段、绝对 POSIX 路径、Windows 盘符、`\` 在 `Rar!\x1a\x07…` 头之后被视为路径分隔符等）。
+- 符号链接、FIFO、套接字、设备。
+- 归档内重复条目或目录/文件名冲突。
+- 归档尺寸、条目数、深度、名称长度或压缩比突破当前档位。
+
+### Vendoring 与许可
+
+`third_party/unrar7/` 是官方 **rarlab UnRAR 源码**（7.20.1）的逐字副本，由 [`opello/unrar`](https://github.com/opello/unrar) 在提交 `97e1780` 处镜像。它依 **UnRAR 免费软件许可** 分发（见 `third_party/unrar7/license.txt`）：可于任何软件中用于处理 RAR 归档，但不得用于开发 RAR 兼容的*归档器*或重新实现 RAR 压缩算法。项目自有的门面 `third_party/unrar7/unrar_c_api.h` 携带项目自身许可。
+
+> v1.8 引擎 `third_party/unrar/dmc_unrar.c`（DrMcCoy/dmc_unrar 1.7.0，GPL-2.0-or-later）已在 v1.9 移除；其声明留存于 git 历史。
+
+### 加密 RAR
+
+密码通道现已完整接通：`/api/extract` 的 `password=` 会被透传给引擎，并在 `RAROpenArchiveEx` 之后、首次 `RARReadHeaderEx` 之前通过 `RARSetPassword` 交给 unrar（这个顺序是解密 `-hp` 加密头的前提）。密码缺失或错误一律返回 `ZIPX_ERR_PASSWORD`（前端 `err_extract_password`），界面据此弹出密码框并按原参数重试，最多 3 次。
+
+## 7z 解压
+
+7z 解压引擎（`src/sevenz_extract.{c,h}`）基于 SDK 解码子集（LZMA2 / LZMA / BCJ2 等）加上项目自研的拉式 codec 链（`src/sevenz_chain.c`，位于 `src/sevenz_chain.h`）。扩展名为 `.7z` 的文件与 ZIP / RAR 一样拥有**解压**按钮；引擎由 `src/extract.c` 按扩展名分派，并复用同一套三阶段模型、限额档位与冲突策略。
+
+> v1.9.1 新增。SDK 自带的 `SzArEx` 路径仅覆盖 4 个 coder 的文件夹，不足以装下 BCJ2 的 5 coder；本项目改为自研 folder 解析 + 拉式 codec 链，从而原生支持 BCJ2 与多 coder 组合。
+
+关于头部：7-Zip 把归档头放在文件末尾，并在头部变大时把它压缩（`-mhc=on`，默认行为），所以头部区域通常以一条 `k7zIdEncodedHeader` 记录开头、描述一个 folder。`-mhe=on` 时那个 folder **也被加密**，而它装着文件名、folder 表与每个条目的尺寸，于是 vendored SDK 在能列出任何条目之前就对整个归档放弃。`src/sevenz_header.c` 负责这种情况：读出该记录，用与内容完全相同的那条 7zAES 路径解出它的 folder，再把一个「头部区域是明文」的虚拟流交给 SDK——磁盘上的归档从不被写入，仅仅被*压缩*过头的归档也完全不受影响。
+
+### 支持范围
+
+| 格式 | 支持 | 备注 |
+|---|---|---|
+| LZMA2 / LZMA（含 ZIP64 式大尺寸） | ✅ | 单 coder 纯 LZMA2 走多线程解码（`src/sevenz_mt.c`，8 线程） |
+| BCJ2（x86 反汇编后处理） | ✅ | 经自研拉式链；SDK `SzArEx` 装不下 5 coder 时由本项目承载 |
+| 多 coder 组合文件夹 | ✅ | 自研 `sevenz_chain.c` 解析 |
+| **分卷**（`.7z.001` / `.z01` 链） | ✅ | `src/sevenz_volstream.c` 按名拼接；打开首个分卷 |
+| **内容加密**（7zAES，AES-256-CBC） | ✅ | 引擎可解密；解压 7z 时前端会**提前**询问密码（避免为无密码归档白跑一次扫描 + folder 解析），密码经 `password=` 传给引擎，缺失或错误返回 `ZIPX_ERR_PASSWORD` 并可重试 |
+| **`-mhe=on` 加密头** | ✅ | `src/sevenz_header.c` 自行解码该头部记录（复用同一条 7zAES 路径），再把一个携带明文的虚拟流交给 SDK；密码错误返回 `ZIPX_ERR_PASSWORD`，与其它加密归档一样由提示重试 |
+| `-mhc=off`（未压缩头） | ✅ | 明文头一向可读；现在按字节探测后完全不做干预 |
+
+当某归档被拒绝时，用户同样收到 `extract_unsupported` 失败，UI 显示双语重试指引。
+
+### 限额
+
+7z 引擎复用与 ZIP / RAR 完全相同的限额表；默认档位与 `large=1` 选配一致（见 [ZIP 解压 → 限额](#限额)）。
+
+### 安全检查
+
+7z 引擎复用相同的 `zipx_status_t` 错误码与检查集合：路径穿越、特殊文件、重复条目/名冲突、以及突破当前档位的尺寸/条目数/深度/名称长度/压缩比。coder 的 `out_size` 取自 `coder_unpack_sizes[index]`（而非文件夹尺寸），`SzArEx` 失败时重置 `blockIndex` 以避免伪 CRC。
+
+## 校验
+
+`make` 之后，对生成的 ELF 做健全性检查：
+
+```sh
+ls -la web-file-mgr.elf                            # v1.9.1 因含 unrar7 + 7z 体积更大；v1.8.3 约 509 KiB
+sha256sum web-file-mgr.elf                         # 把摘要记录进你的发布说明
+file  web-file-mgr.elf                             # 期望 "ELF 64-bit LSB pie executable, x86-64"
+od -An -tx1 -N20 web-file-mgr.elf | head -2        # 魔数 7f45 4c46 0201 + e_machine 003e
+```
+
+`e_machine = 0x003e` 确认了 PS5 目标三元组 `x86_64-sie-ps5`。`e_type = 3`（`ET_DYN`）确认了 ELF 加载器期望的位置无关载荷。
+
+## 测试
+
+一套 POSIX / 主机端 C 测试套件覆盖 ZIP、RAR 与 7z 三个引擎，可在任意 Linux / macOS / MSYS shell 下、无需 PS5 SDK 运行：
+
+```sh
+cd tests && bash run-tests.sh          # ZIP + RAR 套件
+bash run-sevenz-tests.sh               # 7z 套件（需 MinGW gcc 与 7-Zip 二进制）
+```
+
+输出为逐用例的 `check` 风格报告。当前 `main` 上为 **177 项检查**（140 ZIP + 37 RAR），0 失败；7z 套件另有 **27 项用例**，同样 0 失败。覆盖：
+
+- ZIP 条目解析（stored + deflated + ZIP64）
+- 路径穿越、绝对路径、反斜杠、Windows 盘符
+- 符号链接、FIFO、坏 CRC、截断归档、非 ZIP 文件
+- 限额：`entries`、`total_bytes`、`file_bytes`、`ratio`、`depth`、`name_len`
+- 冲突策略：`fail` / `overwrite` / `merge`
+- 每个阶段的取消
+- **加密档案** —— `tests/fixtures-real/` 下的真实归档各跑四种情况（无密码 / 空密码 / 错密码 → `ZIPX_ERR_PASSWORD`；正确密码 → 成功并逐字节校验内容）：ZIP 侧覆盖 `enc-zipcrypto.zip`、`enc-aes256.zip`、`enc-aes256-store.zip`，RAR 侧覆盖 `enc-v6.rar`；另验证「提供密码后限额依旧生效」与「失败路径绝不发布文件」
+- **大文件档位** —— `medium_bomb.zip`（比率 ≈ 238）在默认限额下被拒、在大档位下通过；降低后的大档位仍生效
+- **RAR 引擎**（`tests/test_rar_extract.c`，37 项检查）—— 格式分派（改名的 ZIP / 垃圾数据均被拒）、每个可达引擎错误码的翻译、限额交接（`large=1` 原样传入 `rar_extract()`）、超过上限的字典路径，以及真实归档覆盖
+- **7z 引擎**（`tests/test_sevenz_extract.c` + `tests/run-sevenz-tests.sh`）—— 真实 `.7z` fixture 逐字节比对、加密头（三种情况：无密码 / 错密码 / 正确密码）、各策略下的冲突、取消、限额、缺失目标父目录，以及失败时绝不发布且 staging 树被清理的保证
+
+前端还有一份无头检查 `.build/ui_retry_test.mjs`（`node .build/ui_retry_test.mjs`）：把 `assets/main.js` 载入桩 DOM，验证加密失败后的密码重试流程——参数记忆、重试上限、取消与空密码的回落，共 27 项检查。它位于 `.build/`（gitignore 白名单之外），属于开发期验证脚本。
+
+## 项目结构
+
+```
+.
+├── Makefile                      # PS5 + Linux 构建（VERSION_TAG v1.9.3M）
+├── install-libmicrohttpd.sh      # 一次性依赖安装器
+├── gen-asset-module.py           # 将 assets/* 内联为 gzip 压缩的 C 数组
+├── assets/                       # HTML / CSS / JS / 图标 / param.json
+├── src/                          # C 载荷源码
+│   ├── main.c  websrv.c  filemgr.c        # 入口、HTTP 前端、任务模型
+│   ├── upload.c  download.c               # 流处理
+│   ├── extract.c                          # /api/extract 分派器（ZIP + RAR + 7z）
+│   ├── zip_extract.{c,h}  zipx_common.c   # ZIP 引擎
+│   ├── zipx_volume.c  zipx_volstream.c    # ZIP 分卷探测 + 拼接流
+│   ├── rar_extract.{c,h}                  # RAR 引擎（unrar7 后端）
+│   ├── sevenz_extract.{c,h}               # 7z 引擎
+│   ├── sevenz_chain.{c,h}                 # 7z 拉式 codec 链（BCJ2 等）
+│   ├── sevenz_header.{c,h}                # 7z 头部读取 / `-mhe=on` 解密
+│   ├── sevenz_mt.{c,h}                    # 7z 多线程 LZMA2 解码
+│   ├── sevenz_volstream.{c,h}             # 7z 分卷流拼接
+│   └── app_installer.c                    # PS5 Media 启动器安装器
+├── third_party/                  # vendored：zlib、minizip-ng、unrar7、7z(SDK 子集)
+│   ├── unrar7/                   # rarlab UnRAR 7.20.1，静态库 + C API 门面
+│   ├── minizip-ng/               # ZIP 读取器
+│   ├── zlib/                     # minizip-ng 的压缩后端
+│   └── 7z/                       # LZMA SDK 解码子集
+├── tests/                        # POSIX / 主机测试套件
+│   ├── test_zip_extract.c
+│   ├── test_rar_extract.c
+│   ├── test_sevenz_extract.c     # 7z 用例驱动
+│   ├── make_fixtures.py          # 重新生成测试 fixture
+│   ├── run-tests.sh              # 一次性运行器（ZIP + RAR）
+│   ├── run-sevenz-tests.sh       # 7z 运行器
+│   ├── compat/                   # 小型 Win32 / MSYS 垫片
+│   └── fixtures/ fixtures-7z/ fixtures-real/  # 生成的测试归档
+├── docs/
+│   ├── HANDOVER.md               # v1.8 时代的开发手册（历史存档，现行见根目录 HANDOVER.md）
+│   ├── UPGRADE-v1.7-zip-large-file-profile.md
+│   ├── UPGRADE-v1.8-rar-support.md
+│   └── screenshots/             # README 截图
+├── THIRD_PARTY_NOTICES           # 捆绑库署名
+├── LICENSE                       # GPLv3+
+└── README.md
+```
+
+## 备注
+
+- 复制、移动、删除、上传、下载作为单个后台任务运行。一个任务运行时，其它文件操作会被拒绝。
+- 删除是递归且永久的。没有回收站。
+- 复制/移动任务可取消。单个文件的部分拷贝会被移除，但部分拷贝的文件夹会保留在原地，以避免在合并进已存在目标文件夹时误删既有文件。
+- 上传任务可取消。尽可能移除部分上传的临时文件。
+- 下载文件夹或多个选中项会生成 tar 流。tar 归档由载荷生成，不会先写入 PS5 存储。
+- 若浏览器在载荷进程仍在运行时被关闭重开，UI 可恢复活动任务显示。
+- 文本编辑仅限于上述精选扩展名列表。非 UTF-8 与超大文件会被拒绝。
+- 文件名通过 Web API 以 UTF-8 传输。载荷也会保留挂载文件系统返回的遗留字节序名称，以便混合 USB 文件名编码仍能正确显示与操作。
+
+## 常见问题
+
+- **这是自制应用，不应故意修改系统进程或内核内存。** 若遇到内核崩溃（kernel panic），请确保使用较新的越狱方法与 ELF 加载器，或回退到你惯用的稳定方法。
+- **P2JB 用户** —— 若此载荷触发内核崩溃，请避免在该环境下使用。当每次重试代价高昂时，稳定性比便利更重要。
+- **准备阶段可能耗时较久** —— 当文件夹含大量文件时，它会累加文件夹大小并检查剩余空间，这有助于避免启动一个无法安全完成的复制 / 移动 / 上传 / 下载。
+- **`err_extract_entry_too_large`** —— 默认归档上限为单条目 512 GiB / 500:1 比率（覆盖典型 3A 游戏归档中单个约 300 GiB 未压缩文件）。若超过默认，请确认大文件提示（磁盘上 > 480 GiB 的归档会出现），拆分归档，或直接向 API 传入 `large=1`。
+- **`err_extract_unsupported`** —— 这个包本机读不了：既非 `.zip` / `.rar` / `.7z` 的文件；ZIP 条目用了 stored / deflated 之外的压缩方法；7z 用了不支持的 coder；分卷命名不被识别（RAR 分卷若叫 `x.rar.001`，需改名为 `x.part1.rar`、`x.part2.rar` ……）；或早于 RAR 1.4 的归档。**加密归档与多卷归档不属于这一类**——两者都支持。界面会在括号里附上后端原文，指明具体原因。
+- **`err_extract_dict_too_large`** —— RAR 归档声明的压缩字典超过本构建支持的上限（4096 MiB），且 unrar 请求允许超额。报错文案会同时给出归档需要的尺寸与构建允许的尺寸。这是**刻意拒绝**：另一条路是一次性分配整个字典窗口，rarlab 自家 CLI 默认也会拒绝，16 GB 共享内存的主机更是承受不起。请在 PC 上用不超过 4 GiB 的字典重新压缩（`-md`），或在 PC 上解压。注意 RAR5 格式本身把这个字段卡在 4 GiB，所以这种情况只可能来自更新版 RAR7 头格式写出的归档。
+- **`err_extract_password`** —— 归档已加密，而本次提交的密码缺失或错误。这也包括带加密头（`-mhe=on`）的 7z：文件名与条目尺寸都在头部里，头解密之前连条目列表都读不出来。ZIP / RAR（以及现在的 7z 加密头）在失败后会弹出密码框（取消或留空即放弃），可用正确密码按原参数重试，最多 3 次；解压 7z 时仍会提前询问一次密码。
+
+## 署名
+
+本项目 **fork 自 [owendswang/ps5-web-file-manager](https://github.com/owendswang/ps5-web-file-manager)**（GPL-3.0）。Web UI、任务模型与 PS5 打包方式均源自该项目；上游作者以 GPL-3.0 发布，是本衍生作品得以存在的前提。
+
+**怎么区分上游原版与本仓改版：** 自 v1.9.3 起版本号带 `M` 后缀（`vX.Y.ZM`），*M* 即 *Modified*（改版）；上游 owendswang 的发布版是纯 `vX.Y.Z`。因此 `v1.9.3M` 只可能出自本仓，而这个字母同时出现在 ELF 文件名、PS5 启动通知、`/api/version` 与网页右下角。v1.9.3M 之前的发布早于该约定，保留原本的无后缀编号。
+
+本项目另参考了以下项目构建：
+
+- **[ps5-payload-dev/websrv](https://github.com/ps5-payload-dev/websrv)：** HTTP 服务器结构、静态资源内联思路、PS5 浏览器/websrv 行为与 PKG 安装函数。许可证：GPLv3+。
+- **[ps5-payload-dev/ftpsrv](https://github.com/ps5-payload-dev/ftpsrv)：** PS5 载荷约定、主屏启动器/安装流程参考、进程处理风格与启动安装参考。许可证：GPLv3+。
+- **[seregonwar/zftpd](https://github.com/seregonwar/zftpd)：** PS5 TCP socket 缓冲调优与高吞吐传输行为参考。许可证：MIT。
+- **[itsPLK/ps5-payload-manager](https://github.com/itsPLK/ps5-payload-manager)：** 载荷构建行为。许可证：GPLv3。
+- **[libmicrohttpd](https://ftp.gnu.org/gnu/libmicrohttpd/)：** 用作内嵌 HTTP 服务器库。由 GNU 以 LGPL 许可；本载荷以 SDK 提供的静态库链接它。
+- **[ps5-payload-dev/sdk](https://github.com/ps5-payload-dev/sdk)：** 载荷构建基础。许可证：GPLv3+。
+- **[etaHEN](https://github.com/etaHEN/etaHEN)：** 退出前用于返回 PS5 主屏的 ShellUI URI 导航。许可证：GPLv3。
+- **[ezremote](https://github.com/cy33hc/ps5-ezremote-client)：** PKG 预览功能的参考出处。许可证：**GPL-2.0-only** —— 其源文件未声明 "or later"，因此**无法**与本项目的 GPL-3.0 代码组合。**未取其任何代码**：`src/pkg_info.c` 是独立的 C99 实现（它还负责 `.pkg` 条目表与 `param.json` 字段，而 ezremote 根本没有 `.pkg` 解析器；JSON 走的是 `src/json_util.c` 里自写的分词器，不是 json-c）。详见 `docs/REWRITE-FEASIBILITY.md` §2.2。
+- **[zlib-ng/minizip-ng](https://github.com/zlib-ng/minizip-ng)：** `/api/extract` 端点使用的 ZIP 读取器。vendored 于 `third_party/minizip-ng/`。许可证：zlib。
+- **[zlib](https://www.zlib.net/)：** minizip-ng 的压缩后端。vendored 于 `third_party/zlib/`。许可证：zlib。
+- **[rarlab UnRAR (opello/unrar)](https://github.com/opello/unrar)：** v1.9 起 `/api/extract` 使用的 RAR 读取器（7.20.1）。vendored 于 `third_party/unrar7/`。许可证：UnRAR 免费软件许可。
+
+## 许可证
+
+本项目以 **GPLv3 或更高版本** 分发，与作为实现参考的 GPLv3+ 项目保持一致。见 [`LICENSE`](./LICENSE)。
+
+第三方项目保留各自许可证。请勿在未保留相应许可证声明的情况下，将署名项目的资源或源码复制到其它发行版中。
+
+若分发二进制，除本项目 GPL 许可外，还需遵守 `libmicrohttpd` 的 LGPL 条款。vendored 的 `zlib` 与 `minizip-ng` 源码以 zlib 许可分发；再分发用此特性构建的二进制时，保留 `third_party/zlib/LICENSE` 与 `third_party/minizip-ng/LICENSE` 中的版权声明。vendored 的 `unrar7`（RAR 引擎）依 UnRAR 免费软件许可分发；再分发用 v1.9 或更高版本构建的二进制时，保留 `third_party/unrar7/license.txt` 中的声明，且不得用其开发 RAR 兼容归档器或重新实现 RAR 压缩算法。
+
+## 免责声明
+
+非官方自制软件。仅在已越狱 PS5 主机上运行。使用风险自负——作者不对损坏、数据丢失、账号处罚或保修影响负责。请勿再分发 Sony 专有内容。依 GPLv3+，修改后的再分发必须公开其源码。
@@ -2,8 +2,9 @@ Third-Party Notices
 ===================

 This project vendors a minimal set of third-party source files under
-`third_party/` to provide the ZIP extraction feature (the `/api/extract`
-endpoint). Their full license texts are included alongside the sources.
+`third_party/` to provide the ZIP, RAR and 7z extraction features (the
+`/api/extract` endpoint). Their full license texts are included
+alongside the sources.

 1. minizip-ng
   -----------
@@ -21,26 +22,69 @@ endpoint). Their full license texts are included alongside the sources.
   Files   : third_party/zlib/** (vendored subset, compiled with relaxed
             warnings into the final binary)

-3. dmc_unrar
-   ---------
-   Version : 1.7.0
-   Source  : https://github.com/DrMcCoy/dmc_unrar
-   License : GPL-2.0-or-later (see third_party/unrar/COPYING)
-   Files   : third_party/unrar/dmc_unrar.c (single-file library, compiled
-             with relaxed warnings; the small facade header
-             third_party/unrar/dmc_unrar_api.h is project-authored and
-             carries the project's license).
+3. unrar (rarlab UnRAR source, v7.20.1)
+   -------------------------------------
+   Version : 7.20.1 (RAR 7.23-free source snapshot, 2025-10-28)
+   Source  : https://www.rarlab.com/rar_add.htm — mirrored by
+             https://github.com/opello/unrar (commit 97e1780)
+   License : UnRAR freeware license (see third_party/unrar7/license.txt)
+   Files   : third_party/unrar7/** (RARDLL source set compiled with
+             relaxed warnings; unrar_c_api.h is project-authored and
+             carries the project's license)

-dmc_unrar is the engine behind `src/rar_extract.c` (the v1.8 RAR support).
-It is a dependency-free, single-file, C89/C99 FLOSS UnRAR library. Because
-it is licensed under the GPL-2.0-or-later, the resulting `web-file-mgr.elf`
-binary inherits the obligation to ship the GPL notice and source — which is
-exactly what this file plus `third_party/unrar/COPYING` provides. The
-interface in `dmc_unrar_api.h` is minimal and re-declares only the entry
-points the project uses.
+4. LZMA SDK (7z decoder)
+   ----------------------
+   Version : 26.03 (2026-09-03)
+   Source  : https://www.7-zip.org/sdk.html — release `lzma2603.7z` from
+             https://github.com/ip7z/7zip/releases
+   License : Public domain ("LZMA SDK is written and placed in the public
+             domain by Igor Pavlov", see third_party/7z/DOC/lzma-sdk.txt)
+   Files   : third_party/7z/** (decoder-only subset, compiled with relaxed
+             warnings; see third_party/7z/README.md for the file list)

-Both libraries in section 1 and 2 are distributed under the zlib license,
-which permits redistribution in source and binary form provided the
-copyright notice and this list of conditions are retained. dmc_unrar is
-distributed under the GNU GPL v2-or-later. See the individual LICENSE /
-COPYING files in each `third_party/` subdirectory for the complete terms.
+The LZMA SDK is the engine behind `src/sevenz_extract.c` (the v1.9.x 7z
+support: LZMA/LZMA2/PPMd/Copy plus the BCJ, BCJ2 and Delta filters). Only the
+C implementation is used — it builds with the plain PS5 C toolchain and does
+not pull in the C++ runtime. The encoder half of the SDK is not vendored.
+
+unrar is the engine behind `src/rar_extract.c` (the v1.9 RAR support: RAR4,
+RAR5 including WinRAR 6/7 "v6" compression, and multi-volume archives; the
+engine can also decrypt via RARSetPassword once a password channel is wired
+up). The UnRAR source may be used in any software to handle RAR archives,
+but may not be used to develop a RAR-compatible *archiver* or to re-create
+the RAR compression algorithm, which is proprietary.
+
+(The v1.8 engine, DrMcCoy/dmc_unrar 1.7.0 under GPL-2.0-or-later, was
+replaced by the rarlab UnRAR source in v1.9; see git history under
+`third_party/unrar/` for its notice.)
+
+Libraries in sections 1 and 2 are distributed under the zlib license, which
+permits redistribution in source and binary form provided the copyright
+notice and this list of conditions are retained. unrar is distributed under
+its own freeware terms. The LZMA SDK (section 4) is in the public domain and
+carries no conditions. See the individual LICENSE / license.txt files in
+each `third_party/` subdirectory for the complete terms.
+
+
+Reference-only projects (NOT vendored)
+--------------------------------------
+
+The README Credits section lists a second class of project: ones this payload
+was *written with reference to*, whose code is not present in this repository
+and which therefore impose no obligations here. Keeping the two classes apart
+matters, because one of them is licence-incompatible with this codebase:
+
+  * websrv, ftpsrv, ps5-payload-manager, ps5-payload-dev/sdk, etaHEN  (GPL-3.0 / 3.0+)
+  * zftpd                                                           (MIT)
+  * libmicrohttpd                                                   (LGPL; linked as the SDK-provided static library)
+  * ezremote                                                        (GPL-2.0-only)
+
+For ezremote specifically: GPL-2.0-only cannot be combined with this project's
+GPL-3.0, so it matters that no code was taken from it. The PKG-preview code in
+`src/pkg_info.c` is an independent implementation -- the two share only the
+on-disk SFO format facts, which no implementation can avoid. Line-by-line
+comparison and reasoning: `docs/REWRITE-FEASIBILITY.md` section 2.2.
+
+`owendswang/ps5-web-file-manager` (GPL-3.0) is not a mere reference: it is the
+fork this project descends from, and the web UI, the task model and the PS5
+packaging all originate there.
@@ -44,7 +44,7 @@
        <button id="downloadBtn" class="remote-only" data-i18n="download"></button>
        <button id="deleteBtn" class="danger" data-i18n="delete"></button>
        <button id="installPkgBtn" class="install-action" data-i18n="install" hidden></button>
-        <button id="extractBtn" class="extract-action" data-i18n="extractToCurrent" hidden></button>
+        <button id="extractBtn" class="extract-action" data-i18n="extract"></button>
        <button id="pasteBtn" class="paste-action" hidden>
          <span id="pasteVerb" data-i18n="paste"></span>
          <span id="pasteName" class="paste-name"></span><span id="pasteCount" class="paste-count"></span>
@@ -54,12 +54,12 @@
      </div>
      <div class="tool-right">
        <button id="refreshBtn" data-i18n="refresh"></button>
-        <div id="uploadMenu" class="split-button remote-only">
-          <button id="uploadBtn" class="split-main" data-i18n="upload"></button>
-          <button id="uploadMenuBtn" class="split-arrow" type="button" aria-label="Upload menu"></button>
-          <div class="split-menu">
-            <button id="uploadFolderBtn" type="button" data-i18n="uploadFolder"></button>
-            <button id="uploadAndExtractBtn" type="button" data-i18n="extractUpload"></button>
+        <div id="uploadGroup" class="upload-menu remote-only">
+          <button id="uploadBtn" class="upload-main" data-i18n="upload"
+                  aria-haspopup="menu" aria-expanded="false"></button>
+          <div id="uploadMenu" class="upload-menu-list" role="menu" hidden>
+            <button id="uploadFilesItem" type="button" role="menuitem" data-i18n="uploadFiles"></button>
+            <button id="uploadFolderItem" type="button" role="menuitem" data-i18n="uploadFolder"></button>
          </div>
        </div>
        <button id="newTextBtn" data-i18n="newText"></button>
@@ -68,7 +68,6 @@
    </section>
    <input id="uploadFiles" type="file" multiple hidden>
    <input id="uploadFolder" type="file" multiple webkitdirectory hidden>
-    <input id="uploadZip" type="file" accept=".zip,application/zip,application/x-zip-compressed" hidden>

    <section id="content" class="content">
      <table>
@@ -99,6 +98,7 @@

    <footer class="status">
      <div id="statusText" data-i18n="ready"></div>
+      <div id="dropHint" class="status-hint remote-only" data-i18n="dropUploadHint" hidden></div>
      <div id="versionText" class="version-text"></div>
    </footer>
  </main>
@@ -186,6 +186,10 @@
    </section>
  </div>

+  <div id="dropUploadOverlay" class="drop-upload-overlay remote-only" hidden>
+    <div class="drop-upload-message" data-i18n="dropUpload"></div>
+  </div>
+
  <div id="taskOverlay" class="task-overlay" hidden>
    <div class="task-panel">
      <div id="tasks" class="tasks"></div>
@@ -1,11 +1,15 @@
 window.WFM_LANG = {
  appTitle: "PS5 Web File Manager",
+  versionTooltip: "Modified build by LisherSong (upstream releases carry no M suffix)",
  copy: "Copy",
  move: "Move",
  delete: "Delete",
  download: "Download",
  upload: "Upload",
+  uploadFiles: "Upload Files",
  uploadFolder: "Upload Folder",
+  dropUploadHint: "Drag files or folders into this window to upload",
+  dropUpload: "Release to upload into this folder",
  copying: "Copying",
  moving: "Moving",
  deleting: "Deleting",
@@ -101,12 +105,18 @@ window.WFM_LANG = {
  extracting: "Extracting",
  extractConfirm: "Extract {name} to {path}?",
  extractOverwriteAsk: "If a file or folder with the same name already exists in the target:\n\nOK = overwrite same-name files (folders still merge)\nCancel = fail if the target already exists",
-  extractUploadConfirm: "Upload and extract {name}?\n\nTarget folder: {path}\nThe uploaded ZIP will be deleted after success.",
+  extractPasswordAsk: "This archive may be encrypted (e.g. 7zAES).\n\nEnter the password to extract, or leave it empty to try without one.",
+  extractPasswordFirstAsk: "This archive is encrypted.\n\nEnter the password to extract, or cancel to stop.",
+  extractPasswordRetryAsk: "This archive is encrypted and the password did not work.\n\nEnter the password to try again, or cancel to stop.",
+  extractUploadConfirm: "Upload and extract {name}?\n\nTarget folder: {path}\nThe uploaded archive will be deleted after success.",
+  extractUploadAsk: "{name} is an archive.\n\nOK: upload and extract here\nCancel: upload only",
  extractStarted: "Extraction started: {name}",
  extractDone: "Extraction complete: {name}",
  extractProgress: "{done} / {total} files",
-  extractLargeAsk: "The archive looks large ({size}). Enable the large-file profile?\n\nOK = yes (single file up to 1 TiB, archive total up to 2 TiB)\nCancel = default limits (single file 256 GiB, archive total 1 TiB); this archive may be rejected",
+  extractLargeAsk: "The archive looks large ({size}). Enable the large-file profile?\n\nOK = yes (single file up to 1 TiB, archive total up to 4 TiB)\nCancel = default limits (single file 512 GiB, archive total 2 TiB); this archive may be rejected",
  extractLargeActive: "Large-file profile is enabled for this task",
+  extractSelectArchive: "Select one archive to extract (ZIP / RAR / 7z)",
+  extractOneAtATime: "Only one archive can be extracted at a time",
  extractSelectMainVolume: "Please select the main volume (.rar or .part01.rar)",
  extractArchivePending: "Preparing to extract {name}",
  sameSourceTarget: "Source and destination are the same. Cannot {label} {name}",
@@ -179,7 +189,8 @@ window.WFM_LANG = {
  err_destination_must_be_directory: "Destination must be a folder for multiple items",
  err_extract_open_failed: "Cannot open archive: {arg}",
  err_extract_corrupt: "Archive is corrupt or incomplete: {arg}",
-  err_extract_unsupported: "Unsupported archive (only unencrypted plain ZIP and single-volume RAR are supported): {arg}",
+  err_extract_unsupported: "Unsupported archive (only .zip, .rar and .7z are accepted, including their multi-volume and encrypted forms; this one uses a feature this build cannot handle): {arg}",
+  err_extract_password: "Wrong password or the archive is not encrypted with the one supplied: {arg}",
  err_extract_unsafe_name: "Archive contains an unsafe path: {arg}",
  err_extract_special_entry: "Archive contains an unsupported special file: {arg}",
  err_extract_duplicate: "Archive contains duplicate entries: {arg}",
@@ -189,6 +200,7 @@ window.WFM_LANG = {
  err_extract_ratio: "Suspicious compression ratio (possible zip bomb): {arg}",
  err_extract_too_deep: "Directory nesting is too deep: {arg}",
  err_extract_name_too_long: "File name or path is too long: {arg}",
+  err_extract_dict_too_large: "The archive needs a larger dictionary than this device can handle: {arg}",
  err_extract_conflict: "A file or folder with the same name already exists: {arg}",
  err_extract_io: "Extraction read/write failed: {arg}",
  err_extract_crc: "CRC check failed: {arg}",
@@ -1,11 +1,15 @@
 window.WFM_LANG = {
  appTitle: "PS5 Web File Manager",
+  versionTooltip: "本版为 LisherSong 改版（上游原版无 M 后缀）",
  copy: "复制",
  move: "移动",
  delete: "删除",
  download: "下载",
  upload: "上传",
+  uploadFiles: "上传文件",
  uploadFolder: "上传文件夹",
+  dropUploadHint: "可直接把文件或文件夹拖进窗口上传",
+  dropUpload: "松开即上传到当前目录",
  copying: "复制",
  moving: "移动",
  deleting: "删除",
@@ -101,12 +105,18 @@ window.WFM_LANG = {
  extracting: "解压",
  extractConfirm: "解压 {name} 到 {path}？",
  extractOverwriteAsk: "若目标已存在同名文件或目录：\n\n确定 = 覆盖同名文件（目录仍会合并）\n取消 = 若目标已存在则失败",
-  extractUploadConfirm: "上传并解压 {name}？\n\n目标目录：{path}\n成功后将删除上传的 ZIP。",
+  extractPasswordAsk: "此压缩包可能加密了（如 7zAES）。\n\n输入密码后解压，留空则尝试无密码解压。",
+  extractPasswordFirstAsk: "此压缩包已加密。\n\n输入密码后解压，取消则停止解压。",
+  extractPasswordRetryAsk: "此压缩包已加密，密码不正确。\n\n输入密码重试，取消则停止解压。",
+  extractUploadConfirm: "上传并解压 {name}？\n\n目标目录：{path}\n成功后将删除上传的压缩包。",
+  extractUploadAsk: "这是压缩包 {name}。\n\n确定：上传后自动解压到当前目录\n取消：仅上传，不解压",
  extractStarted: "已开始解压 {name}",
  extractDone: "解压完成：{name}",
  extractProgress: "{done} / {total} 个文件",
-  extractLargeAsk: "ZIP 体积较大（{size}），是否启用「大文件模式」？\n\n确定 = 启用（单文件最大 1 TiB / 总解压最大 2 TiB）\n取消 = 默认限制（单文件 256 GiB / 总解压 1 TiB），可能拒绝此压缩包",
+  extractLargeAsk: "压缩包体积较大（{size}），是否启用「大文件模式」？\n\n确定 = 启用（单文件最大 1 TiB / 总解压最大 4 TiB）\n取消 = 默认限制（单文件 512 GiB / 总解压 2 TiB），可能拒绝此压缩包",
  extractLargeActive: "此任务已启用大文件模式",
+  extractSelectArchive: "选中一个压缩包后才能解压（ZIP / RAR / 7z）",
+  extractOneAtATime: "一次只能解压一个压缩包",
  extractSelectMainVolume: "请改选主卷（如 .rar 或 .part01.rar）",
  extractArchivePending: "正在准备解压 {name}",
  sameSourceTarget: "源和目标相同，不能{label} {name}",
@@ -179,7 +189,8 @@ window.WFM_LANG = {
  err_destination_must_be_directory: "多个项目的目标必须是目录",
  err_extract_open_failed: "无法打开压缩包: {arg}",
  err_extract_corrupt: "压缩包损坏或不完整: {arg}",
-  err_extract_unsupported: "不支持的压缩包（仅支持未加密的普通 ZIP 与单卷 RAR）: {arg}",
+  err_extract_unsupported: "不支持的压缩包（只认 .zip / .rar / .7z，含它们的分卷与加密版本；这个包用了本机处理不了的特性）：{arg}",
+  err_extract_password: "密码错误，或压缩包未使用所提供的密码加密: {arg}",
  err_extract_unsafe_name: "压缩包包含不安全的路径: {arg}",
  err_extract_special_entry: "压缩包包含不支持的特殊文件: {arg}",
  err_extract_duplicate: "压缩包包含重复条目: {arg}",
@@ -189,6 +200,7 @@ window.WFM_LANG = {
  err_extract_ratio: "压缩比异常（疑似压缩炸弹）: {arg}",
  err_extract_too_deep: "目录层级过深: {arg}",
  err_extract_name_too_long: "文件名或路径过长: {arg}",
+  err_extract_dict_too_large: "压缩包需要的字典超出本机可承受范围: {arg}",
  err_extract_conflict: "目标已存在同名文件或目录: {arg}",
  err_extract_io: "解压读写失败: {arg}",
  err_extract_crc: "CRC 校验失败: {arg}",
@@ -250,7 +250,7 @@ body {
  flex: 1 1 auto;
 }

-.split-button {
+.upload-menu {
  position: relative;
  display: inline-flex;
  align-items: stretch;
@@ -259,53 +259,98 @@ body {
  margin-bottom: 15px;
 }

-.split-button .split-main {
+.upload-menu .upload-main {
  min-width: 82px;
-  border-top-right-radius: 0;
-  border-bottom-right-radius: 0;
  margin: 0;
 }

-.split-button .split-arrow {
-  min-width: 38px;
-  width: 38px;
-  padding: 0;
-  border-left: 0;
-  border-top-left-radius: 0;
-  border-bottom-left-radius: 0;
-  margin: 0;
-}
-
-.split-arrow::before {
+/* The caret is what tells the user this button opens a list. Without it the
+   button looks like a plain one-shot action, which is exactly how the old
+   file/folder split was misread. */
+.upload-main::after {
  content: "";
  display: block;
  width: 0;
  height: 0;
+  margin-left: 10px;
  border-left: 6px solid transparent;
  border-right: 6px solid transparent;
  border-top: 7px solid #f2f5f7;
 }

-.split-menu {
+.upload-menu-list {
  position: absolute;
-  top: 100%;
+  top: calc(100% + 6px);
  right: 0;
-  z-index: 40;
-  display: none;
-  min-width: 150px;
-  padding-top: 6px;
+  z-index: 700;
+  display: flex;
+  flex-direction: column;
+  padding: 6px;
+  border: 1px solid #46515f;
+  border-radius: 8px;
+  background: #1b2128;
+  box-shadow: 0 12px 28px rgba(0, 0, 0, .5);
 }

-.split-menu button {
-  width: 100%;
-  min-width: 150px;
-  margin: 0;
+.upload-menu-list button {
+  height: 46px;
+  min-height: 46px;
+  min-width: 176px;
+  padding: 0 16px;
+  border: 0;
+  border-radius: 6px;
+  background: transparent;
+  justify-content: flex-start;
+  text-align: left;
  white-space: nowrap;
 }

-.split-button:hover .split-menu,
-.split-button.open .split-menu {
-  display: block;
+/* Menu rows highlight by fill only. The generic button ring (3px at offset
+   2px) is sized for a 54px toolbar button: on a 46px row it clears the
+   panel's 6px padding, overlaps the neighbouring row, and its corners do not
+   follow the row's radius, so the highlight reads as a broken shape rather
+   than a selected row. The panel's own hover fill had also never applied --
+   the generic `button:not(.row-action):hover:not(:disabled)` rule has the
+   same specificity (0,3,1) and comes later in this file, so it won and hover
+   and focus ended up two different colours. Scoping both rules to the panel
+   settles the cascade, and the keyboard cue is drawn inside the row where it
+   cannot cross the panel edge. */
+#uploadMenu button:focus {
+  outline: none;
+}
+
+#uploadMenu button:hover:not(:disabled),
+#uploadMenu button:focus-visible {
+  background: #2b343e;
+}
+
+#uploadMenu button:focus-visible {
+  box-shadow: inset 0 0 0 2px #6fb1ff;
+}
+
+/* The status can be a long "uploading 3/12: some-very-long-name.zip". The footer
+   is a fixed 46px row, so a wrapped status used to spill out of it; clamping it
+   to one line with an ellipsis is what keeps it, the hint and the version on the
+   same row at every width. */
+#statusText {
+  flex: 1 1 auto;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+/* A hint that has to fit next to the status line and the version, so it shrinks
+   with an ellipsis instead of pushing either of them around. */
+.status-hint {
+  flex: 0 1 auto;
+  min-width: 0;
+  margin: 0 16px;
+  overflow: hidden;
+  color: #6f7a84;
+  font-size: 16px;
+  text-overflow: ellipsis;
+  white-space: nowrap;
 }

 button,
@@ -396,7 +441,10 @@ button.install-action:hover:not(:disabled) {
 }

 .extract-action {
-  min-width: 88px;
+  /* Matches the width of the other two-character verbs (copy/move/delete): the
+     button is on screen at all times now, so it has to line up with them
+     instead of being a special case that appears only on selection. */
+  min-width: 96px;
  border-color: #2a6b66;
  background: #17302e;
  color: #a8e6df;
@@ -406,6 +454,16 @@ button.extract-action:hover:not(:disabled) {
  background: #1d3f3c;
 }

+/* The extract button is always on screen and only greys out when the selection
+   cannot be extracted, so the reason has to be readable. `button:disabled`
+   sets `pointer-events: none`, which makes the button un-hoverable and swallows
+   its `title` tooltip -- the same fix the parent-directory button already uses.
+   Clicks stay dead either way: the disabled attribute blocks activation
+   regardless of hit-testing. */
+.extract-action:disabled {
+  pointer-events: auto;
+}
+
 .paste-count {
  white-space: nowrap;
 }
@@ -1057,6 +1115,38 @@ input[type="checkbox"] {
  margin-left: 14px;
 }

+/* Shown while a file drag hovers the window. pointer-events stays off so the
+   drop still lands on the window listener rather than on this element, and the
+   z-index sits above the task overlay so the hint is visible during a running
+   task (the drop itself is ignored while busy). */
+.drop-upload-overlay {
+  position: fixed;
+  top: 0;
+  right: 0;
+  bottom: 0;
+  left: 0;
+  z-index: 19000;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: rgba(8, 11, 14, .88);
+  box-shadow: inset 0 0 0 4px #6fb1ff;
+  pointer-events: none;
+}
+
+.drop-upload-message {
+  max-width: calc(100% - 48px);
+  padding: 26px 34px;
+  border: 1px solid #46515f;
+  border-radius: 8px;
+  background: #1b2026;
+  box-shadow: 0 18px 54px rgba(0, 0, 0, .5);
+  color: #edf0f2;
+  font-size: 24px;
+  line-height: 1.4;
+  text-align: center;
+}
+
 .task-overlay {
  position: fixed;
  top: 0;
@@ -1334,28 +1424,30 @@ input[type="checkbox"] {
    font-size: 16px;
  }

-  .split-button {
+  .upload-menu {
    height: 40px;
    min-height: 40px;
    margin-bottom: 8px;
  }

-  .split-button .split-main {
+  .upload-menu .upload-main {
    min-width: 64px;
  }

-  .split-button .split-arrow {
-    min-width: 34px;
-    width: 34px;
+  .upload-menu-list {
+    padding: 4px;
  }

-  .split-menu {
-    min-width: 126px;
-    padding-top: 4px;
+  .upload-menu-list button {
+    height: 38px;
+    min-height: 38px;
+    min-width: 148px;
+    padding: 0 12px;
  }

-  .split-menu button {
-    min-width: 126px;
+  .status-hint {
+    margin: 0 10px;
+    font-size: 14px;
  }

  .paste-action {
@@ -35,7 +35,12 @@ let uploadXhr = null;
 let uploadTerminalAbort = false;
 let L = {};

-const APP_VERSION = "v1.7";
+// Last-resort fallback for the footer. The real value comes from
+// /api/version, which reports the build's VERSION_TAG -- see loadVersion().
+// Keeping a literal here used to be the only source, and it inevitably
+// drifted (the footer said "v1.9" throughout the v1.9.1 release).
+// The trailing "M" is the fork marker; see VERSION_TAG in the Makefile.
+const APP_VERSION_FALLBACK = "v1.9.3M";
 const LAST_PATH_KEY = "ps5-web-file-mgr:last-path";
 const SORT_KEY = "ps5-web-file-mgr:list-sort";
 const LOADING_DISPLAY_DELAY = 250;
@@ -68,14 +73,14 @@ const installPkgBtn = document.getElementById("installPkgBtn");
 const extractBtn = document.getElementById("extractBtn");
 const clearClipboardBtn = document.getElementById("clearClipboardBtn");
 const downloadBtn = document.getElementById("downloadBtn");
-const uploadMenuEl = document.getElementById("uploadMenu");
 const uploadBtn = document.getElementById("uploadBtn");
-const uploadMenuBtn = document.getElementById("uploadMenuBtn");
-const uploadFolderBtn = document.getElementById("uploadFolderBtn");
-const uploadAndExtractBtn = document.getElementById("uploadAndExtractBtn");
+const uploadMenuEl = document.getElementById("uploadMenu");
+const uploadFilesItemEl = document.getElementById("uploadFilesItem");
+const uploadFolderItemEl = document.getElementById("uploadFolderItem");
+const dropHintEl = document.getElementById("dropHint");
 const uploadFilesEl = document.getElementById("uploadFiles");
 const uploadFolderEl = document.getElementById("uploadFolder");
-const uploadZipEl = document.getElementById("uploadZip");
+const dropUploadOverlayEl = document.getElementById("dropUploadOverlay");
 const initLoadingEl = document.getElementById("initLoading");
 const exitBtn = document.getElementById("exitBtn");
 const textEditorOverlayEl = document.getElementById("textEditorOverlay");
@@ -148,7 +153,15 @@ function t(key, params) {
 }

 function backendErrorText(code, arg, fallback) {
-  if (!code) return fallback || t("backendError");
+  if (!code) return decodeFsText(fallback) || t("backendError");
+  // Names arrive byte-mapped (see decodeFsText below): the server escapes every
+  // byte >= 0x80 as \u00XX so that names which are not valid UTF-8 -- a GBK entry
+  // name inside a ZIP, say -- survive the JSON round trip unchanged. The listing
+  // has always translated them back for display; an error message must do the
+  // same, or the entry name is unreadable at the exact moment the user needs to
+  // read it (which is how "解压失败: ... â®â¡.psd" happened).
+  arg = decodeFsText(arg);
+  fallback = decodeFsText(fallback);
  const params = { path: arg || "", arg: arg || "" };
  if (code === "no_space") {
    const parts = String(arg || "").split(",");
@@ -156,7 +169,16 @@ function backendErrorText(code, arg, fallback) {
    params.available = formatBytes(parts[1] || 0, false);
  }
  const key = "err_" + code;
-  return L[key] ? t(key, params) : fallback || t("backendError");
+  const label = L[key] ? t(key, params) : "";
+  if (label) {
+    // Append the backend's own message (e.g. "cannot create file: No space
+    // left on device") when present — it carries the strerror detail that
+    // the i18n label otherwise hides.
+    const hint = fallback && fallback !== t("backendError")
+      ? " (" + String(fallback) + ")" : "";
+    return label + hint;
+  }
+  return fallback || t("backendError");
 }

 function applyStaticText() {
@@ -167,14 +189,33 @@ function applyStaticText() {
  if (isPlayStationBrowser()) {
    for (const el of document.querySelectorAll(".remote-only")) el.hidden = true;
  }
+  // The hint starts hidden so the console browser never flashes it; the browser
+  // that can actually drag (and therefore has the upload button) shows it.
+  dropHintEl.hidden = isPlayStationBrowser();
  exitBtn.title = t("exit");
  exitBtn.setAttribute("aria-label", t("exit"));
  parentBtn.title = t("parent");
  parentBtn.setAttribute("aria-label", t("parent"));
-  versionEl.textContent = APP_VERSION;
+  versionEl.textContent = APP_VERSION_FALLBACK;
+  // "v1.9.3M" is opaque to anyone who has not read the release notes, so spell
+  // out what the trailing M means on hover. loadVersion() only rewrites the
+  // text, never the tooltip, so this survives the /api/version round trip.
+  versionEl.title = t("versionTooltip");
  if (initLoadingEl) initLoadingEl.hidden = true;
 }

+// Ask the backend which version it was built as, so the footer can never
+// disagree with the Makefile. A failure here is cosmetic: we simply keep the
+// fallback text rather than nagging the user with an error toast.
+async function loadVersion() {
+  try {
+    const data = await api("/api/version");
+    if (data && data.version) versionEl.textContent = data.version;
+  } catch (err) {
+    /* offline or very old payload -- keep APP_VERSION_FALLBACK */
+  }
+}
+
 function nextPaint() {
  return new Promise(resolve => {
    if (window.requestAnimationFrame) {
@@ -304,6 +345,32 @@ function decodeFsBytes(bytes, fallback) {
  }
 }

+// The inverse of decodeFsText(): turn a real Unicode name -- one that came from
+// a File object or a prompt, not from the server -- into the byte-mapped form
+// the server expects. Anything that crosses over has to be in one convention,
+// because the server byte-repairs a path only when every non-ASCII code point in
+// it is <= 0xFF: a single real CJK character in the same string makes
+// fs_path_value() leave the whole thing alone, and a half-repaired path finds
+// nothing on disk.
+function encodeFsText(text) {
+  text = String(text || "");
+  const encoder = typeof TextEncoder !== "undefined" ? new TextEncoder() : null;
+  if (!encoder) return text;
+  let bytes;
+  try {
+    bytes = encoder.encode(text);
+  } catch (err) {
+    return text;
+  }
+  let ascii = true;
+  let out = "";
+  for (let i = 0; i < bytes.length; i++) {
+    if (bytes[i] >= 0x80) ascii = false;
+    out += String.fromCharCode(bytes[i]);
+  }
+  return ascii ? text : out;
+}
+
 function isUtf8Bytes(bytes) {
  for (let i = 0; i < bytes.length;) {
    const c = bytes[i];
@@ -504,6 +571,10 @@ function handleTerminalTask(task) {
  }
  if (task.state === "failed") {
    clearTrackedTask();
+    if (task.op === "extract" && task.error_code === "extract_password" &&
+        retryExtractWithPassword(task)) {
+      return;
+    }
    const message = taskFailureMessage(task);
    setStatus(message);
    alert(message);
@@ -764,13 +835,47 @@ function isRarSubVolume(item) {
  return false;
 }

+function isZipSplitVolume(item) {
+  if (item.type !== "-") return false;
+  const name = item.name;
+  // 分卷 ZIP 的任意一卷都能解压（引擎会自己找齐同目录的其余分卷）：
+  // name.zip.001…（7-Zip）/ name.part1.zip…（WinRAR）/ name.z01…+name.zip（Info-ZIP）
+  if (/\.zip\.0*\d+$/i.test(name)) return true;
+  if (/\.part0*\d+\.zip$/i.test(name)) return true;
+  if (/\.z0*\d+$/i.test(name)) return true;
+  return false;
+}
+
+function isSevenZipArchive(item) {
+  return item.type === "-" && /\.7z$/i.test(item.name);
+}
+
+function isSevenZipSplitVolume(item) {
+  if (item.type !== "-") return false;
+  // Byte-split 7z sets: name.7z.001 / .002 / ... — any volume is enough,
+  // the engine walks the directory to assemble the rest.
+  if (/\.7z\.0*\d+$/i.test(item.name)) return true;
+  return false;
+}
+
 function isExtractableArchive(item) {
  if (item.type !== "-") return false;
  if (/\.zip$/i.test(item.name)) return true;
+  if (isZipSplitVolume(item)) return true;
  if (isRarMainVolume(item)) return true;
+  if (isSevenZipArchive(item)) return true;
+  if (isSevenZipSplitVolume(item)) return true;
  return false;
 }

+// The upload path knows a filename but has no directory entry to inspect, so
+// reuse the toolbar's archive test on a synthetic item. Keeps a dropped
+// .7z.001 or .part1.rar recognised as "offer to extract" without duplicating
+// the rules.
+function isExtractableName(name) {
+  return isExtractableArchive({ type: "-", name: String(name || "") });
+}
+
 function isSpecialDirectory(item) {
  if (item.type !== "d") return false;
  if (item.path === "/data") return true;
@@ -814,17 +919,85 @@ function actionInstallSelectedPkgs() {
  return queuePkgInstall(selectedEntries().filter(isPkgPackage));
 }

-async function startExtractTask(path, dstDir, conflict, removeSource, name, large) {
+// The engine reports a missing or wrong password as `extract_password`. ZIP and
+// RAR only find out once they have looked inside, so they are not asked up
+// front; the failed task is re-sent with whatever the user types here instead.
+// Remembering the original request is what keeps the conflict policy and the
+// large-file opt-in intact across the retry.
+//
+// The request is remembered by TASK ID, never by path. Paths travel through the
+// byte-mapped JSON described at decodeFsText(), and the server maps them back to
+// raw bytes on the way in (fs_path_value), so the string this page holds for a
+// directory and the one the task reports back differ for every name that is not
+// pure ASCII. Keying the retry by path therefore made the password prompt
+// silently never appear for archives in a non-ASCII directory -- the exact case
+// the retry exists for. The id is assigned by the server and survives the round
+// trip untouched.
+const MAX_EXTRACT_PASSWORD_RETRIES = 3;
+const extractRequestRetries = new Map();
+
+function extractRetryKey(taskId) {
+  return "task:" + String(taskId);
+}
+
+// Entries are consumed by a retry or by a give-up, but a successful extraction
+// never asks for one again, so its entry would sit here for the life of the
+// page. Only one task can be live at a time (the server rejects a second with
+// 409), so anything older than the last few is dead weight.
+const MAX_REMEMBERED_EXTRACTS = 8;
+
+function rememberExtractRequest(taskId, entry) {
+  extractRequestRetries.set(extractRetryKey(taskId), entry);
+  while (extractRequestRetries.size > MAX_REMEMBERED_EXTRACTS) {
+    extractRequestRetries.delete(extractRequestRetries.keys().next().value);
+  }
+}
+
+function retryExtractWithPassword(task) {
+  const key = extractRetryKey(task.id);
+  const remembered = extractRequestRetries.get(key);
+  if (!remembered || remembered.attempts >= MAX_EXTRACT_PASSWORD_RETRIES) {
+    extractRequestRetries.delete(key);
+    return false;
+  }
+  // The first failure is usually "no password was given at all"; only a later
+  // one is a password that did not work. Saying "the password is wrong" to
+  // someone who was never asked for one is what made this flow look broken.
+  const asked = prompt(t(remembered.attempts
+    ? "extractPasswordRetryAsk" : "extractPasswordFirstAsk"), "");
+  if (!asked) {
+    // Cancel or an empty box means "give up": fall through so the normal failure
+    // report still explains what happened.
+    extractRequestRetries.delete(key);
+    return false;
+  }
+  // Consume the entry: the retry below registers itself under the new task id.
+  extractRequestRetries.delete(key);
+  clearTrackedTask();
+  startExtractTask(task.src, task.dst, remembered.conflict,
+                   remembered.removeSource, remembered.name, remembered.large,
+                   asked, remembered.attempts + 1);
+  return true;
+}
+
+async function startExtractTask(path, dstDir, conflict, removeSource, name, large,
+                                password, attempts) {
  try {
    taskRefreshPath = cwd;
    setBusy(true);
    setStatus(t("extractStarted", { name }));
-    const data = await apiForm("/api/extract", {
+    const form = {
      path,
      dst_dir: dstDir,
      conflict,
      remove_source: removeSource ? "1" : "0",
      large: large ? "1" : "0"
+    };
+    if (password) form.password = password;
+    const data = await apiForm("/api/extract", form);
+    rememberExtractRequest(data.task_id, {
+      conflict, removeSource, name, large: Boolean(large),
+      attempts: Number(attempts || 0)
    });
    trackTask(data.task_id, "extract", false);
    clearSelection(false);
@@ -835,7 +1008,13 @@ async function startExtractTask(path, dstDir, conflict, removeSource, name, larg
  }
 }

-const LARGE_FILE_THRESHOLD_BYTES = 240 * 1024 * 1024 * 1024;
+// Threshold above which the web UI prompts the user before extracting.
+// Tuned so a typical 3A-game archive (~300 GiB single file) and a PS5 system
+// backup (~300 GiB total) extract under the default profile without prompting.
+// Files between this threshold and the default max_file_bytes cap (512 GiB)
+// still extract silently; larger files require explicit user opt-in via the
+// large=1 API flag.
+const LARGE_FILE_THRESHOLD_BYTES = 480 * 1024 * 1024 * 1024;

 function shouldPromptLargeMode(itemSize) {
  return Number(itemSize || 0) > LARGE_FILE_THRESHOLD_BYTES;
@@ -853,7 +1032,19 @@ function actionExtract() {
  if (!confirm(t("extractConfirm", { name: displayName(item), path: displayPath(cwd) }))) return;
  const conflict = confirm(t("extractOverwriteAsk")) ? "overwrite" : "fail";
  const large = shouldPromptLargeMode(item.size) ? promptLargeMode(item.size) : false;
-  startExtractTask(item.path, cwd, conflict, false, displayName(item), large);
+  // 7z archives can be encrypted (7zAES); ask up front so an unprotected
+  // archive doesn't pay a wasted scan + folder parse.  An empty submission is
+  // fine — the engine returns ZIPX_ERR_PASSWORD and the user retries.
+  // ZIP and RAR are not asked here: their headers are readable either way, so
+  // an empty password costs nothing and a failed attempt is retried through
+  // retryExtractWithPassword() instead of interrupting every extraction.
+  let password = "";
+  if (isSevenZipArchive(item) || isSevenZipSplitVolume(item)) {
+    const asked = prompt(t("extractPasswordAsk"), "");
+    if (asked === null) return;
+    password = asked;
+  }
+  startExtractTask(item.path, cwd, conflict, false, displayName(item), large, password);
 }

 function openImagePreview(item) {
@@ -1179,7 +1370,9 @@ async function actionNewText() {
  if (input === null) return;
  const name = input.trim();
  if (!name) return;
-  const item = { name, path: pathJoin(dir, name), type: "-" };
+  // dir is the byte-mapped echo of the listing; name typed here is real Unicode.
+  // Joining them raw would hand the server a path it cannot repair.
+  const item = { name, path: pathJoin(dir, encodeFsText(name)), type: "-" };

  try {
    setBusy(true);
@@ -1355,25 +1548,26 @@ function renderExtractButton(items, locked) {
  const archives = items.filter(isExtractableArchive);
  const subs    = items.filter(isRarSubVolume);

-  // 没有可解压档案也没有子卷 → 隐藏按钮
-  if (archives.length === 0 && subs.length === 0) {
-    extractBtn.hidden = true;
-    extractBtn.title = "";
-    extractBtn.disabled = true;
+  /* The button is always on screen and merely greys out when the selection
+     cannot be extracted. It used to be hidden until an archive was selected,
+     which left the resting toolbar with no extract entry at all -- the same
+     discoverability problem the upload button was changed for. Being disabled
+     is not self-explanatory though, so the tooltip carries the reason. */
+  if (archives.length === 1) {
+    extractBtn.title = t("extractToCurrent") + ": " + itemTitle(archives);
+    extractBtn.disabled = locked;
    return;
  }

-  extractBtn.hidden = false;
-
-  // 只选中子卷(比如 .part02.rar),没有对应主卷 → 按钮置灰 + 提示改选主卷
-  if (archives.length !== 1) {
+  extractBtn.disabled = true;
+  if (archives.length > 1) {
+    extractBtn.title = t("extractOneAtATime");
+  } else if (subs.length > 0) {
+    // 只选中子卷(比如 .part02.rar),没有对应主卷 → 置灰 + 提示改选主卷
    extractBtn.title = t("extractSelectMainVolume");
-    extractBtn.disabled = true;
-    return;
+  } else {
+    extractBtn.title = t("extractSelectArchive");
  }
-
-  extractBtn.title = t("extractToCurrent") + ": " + itemTitle(archives);
-  extractBtn.disabled = locked;
 }

 function singleSelected() {
@@ -1394,9 +1588,9 @@ function updateButtons() {
  downloadBtn.disabled = locked || items.length === 0;
  document.getElementById("refreshBtn").disabled = locked;
  uploadBtn.disabled = locked;
-  uploadMenuBtn.disabled = locked;
-  uploadFolderBtn.disabled = locked;
-  uploadAndExtractBtn.disabled = locked;
+  uploadFilesItemEl.disabled = locked;
+  uploadFolderItemEl.disabled = locked;
+  if (locked && uploadMenuOpen) setUploadMenuOpen(false);
  document.getElementById("mkdirBtn").disabled = locked;
  newTextBtn.disabled = locked;
  for (const button of filesEl.querySelectorAll(".row-action, .mode-action")) button.disabled = locked;
@@ -1963,7 +2157,6 @@ function renderTasks(tasks) {
  const isDelete = task.op === "delete";
  const isDownload = task.op === "download";
  const isChmod = task.op === "chmod";
-  const isExtract = task.op === "extract";
  const isPreparing = (task.op === "copy" || task.op === "move" || isChmod) &&
    task.state === "running" && done === 0;
  const isFinishing = !isDelete && !isDownload && task.state === "running" && total > 0 && done >= total;
@@ -1996,9 +2189,15 @@ function renderTasks(tasks) {
  speedItem.textContent = t("speedLabel") + ": " + (isChmod ?
    t("itemsPerSecond", { count: Math.round(speed) }) : formatSpeed(speed));
  const progressItem = document.createElement("div");
-  progressItem.textContent = t("progressLabel") + ": " + (isExtract && Number(task.entries_total) ?
-    t("extractProgress", { done: Number(task.entries_done || 0), total: Number(task.entries_total || 0) }) :
-    isChmod ? t("permissionProgress", { done, total }) : formatSize(done) + " / " + formatSize(total));
+  // Bytes only, for every task type including extract. An entry counter was
+  // tried here and read as a hang: the archives that matter are a handful of
+  // huge entries (a game blob split across volumes), so entries_done sits at 0
+  // for the whole of the first one while bytes are plainly moving. The current
+  // file name is already shown on its own line, so the entry index added
+  // nothing a user could act on. Benchmarked: reporting is not a cost -- see
+  // tests/bench_progress.c --mode -- so this is about clarity, not speed.
+  progressItem.textContent = t("progressLabel") + ": " + (isChmod ?
+    t("permissionProgress", { done, total }) : formatSize(done) + " / " + formatSize(total));
  const etaItem = document.createElement("div");
  etaItem.textContent = t("etaLabel") + ": " + averageEta(task, done, total);
  appendChildren(meta, speedItem, progressItem, etaItem);
@@ -2221,7 +2420,7 @@ function uploadFileRequest(taskId, file, rel, overwrite, index) {
  });
 }

-async function uploadFiles(files) {
+async function uploadFiles(files, relativeNames) {
  if (busy || loadingPath || !files.length) return;
  const useLoading = files.length >= SELECT_ALL_LOADING_THRESHOLD;
  let list;
@@ -2238,7 +2437,9 @@ async function uploadFiles(files) {
    list = Array.prototype.slice.call(files);
    for (let i = 0; i < list.length; i++) {
      const file = list[i];
-      rels.push(uploadRelativeName(file));
+      // Dropped items carry no webkitRelativePath, so the drop collector
+      // rebuilds the path itself and passes it in.
+      rels.push(relativeNames && relativeNames[i] ? relativeNames[i] : uploadRelativeName(file));
      sizes.push(String(file.size || 0));
      total += Number(file.size || 0);
    }
@@ -2247,6 +2448,17 @@ async function uploadFiles(files) {
    if (useLoading) hideContentLoading();
  }

+  // A lone archive used to need the "upload and extract" menu entry. Ask once
+  // here instead, so the plain Upload button covers it too; declining is an
+  // ordinary upload, and the toolbar Extract button still works afterwards.
+  if (list.length === 1 && isExtractableName(rels[0])) {
+    uploadFilesEl.value = "";
+    uploadFolderEl.value = "";
+    if (confirm(t("extractUploadAsk", { name: rels[0] }))) {
+      return uploadAndExtractFile(list[0], rels[0], true);
+    }
+  }
+
  const overwrite = conflicts.length &&
    confirm(t("uploadOverwriteConfirm", { names: conflictText(conflicts) }));
  if (conflicts.length && !overwrite) return;
@@ -2306,38 +2518,192 @@ async function uploadFiles(files) {
  }
 }

-function actionUploadFiles() {
-  if (busy || loadingPath) return;
-  uploadMenuEl.classList.remove("open");
-  uploadFilesEl.click();
+// A native file dialog is either file-only or folder-only (webkitdirectory), so
+// a single dialog cannot offer both. The button therefore opens a two-entry
+// list: a main button plus a small caret next to it was the old shape, and users
+// read the caret as decoration and never found "upload a folder" at all. The
+// drop target below is still the one gesture that accepts either.
+let uploadMenuOpen = false;
+
+function uploadMenuItems() {
+  return [uploadFilesItemEl, uploadFolderItemEl];
 }

-function actionUploadFolder() {
-  if (busy || loadingPath) return;
-  uploadMenuEl.classList.remove("open");
-  uploadFolderEl.click();
+function setUploadMenuOpen(open) {
+  uploadMenuOpen = Boolean(open) && !busy && !loadingPath;
+  uploadMenuEl.hidden = !uploadMenuOpen;
+  uploadBtn.setAttribute("aria-expanded", uploadMenuOpen ? "true" : "false");
 }

 function toggleUploadMenu() {
  if (busy || loadingPath) return;
-  uploadMenuEl.classList.toggle("open");
+  setUploadMenuOpen(!uploadMenuOpen);
+  if (uploadMenuOpen) uploadMenuItems()[0].focus();
 }

-function actionUploadAndExtract() {
+function actionUploadFiles() {
+  setUploadMenuOpen(false);
  if (busy || loadingPath) return;
-  uploadMenuEl.classList.remove("open");
-  uploadZipEl.click();
+  uploadFilesEl.click();
 }

-async function uploadAndExtractFile(file) {
+function actionUploadFolder() {
+  setUploadMenuOpen(false);
  if (busy || loadingPath) return;
-  if (!/\.zip$/i.test(file.name || "")) {
+  uploadFolderEl.click();
+}
+
+function moveUploadMenuFocus(step) {
+  const items = uploadMenuItems();
+  const current = items.indexOf(document.activeElement);
+  const next = ((current < 0 ? 0 : current + step) + items.length) % items.length;
+  items[next].focus();
+}
+
+function setupUploadMenu() {
+  // Closing on any click outside is what keeps a menu honest; it is bound to the
+  // document so that a reflowed toolbar cannot leave a stale open list behind.
+  document.addEventListener("click", event => {
+    if (!uploadMenuOpen) return;
+    const target = event.target;
+    if (target === uploadBtn || (target && uploadMenuEl.contains(target))) return;
+    setUploadMenuOpen(false);
+  });
+  document.addEventListener("keydown", event => {
+    if (!uploadMenuOpen) return;
+    if (event.key === "Escape") {
+      setUploadMenuOpen(false);
+      uploadBtn.focus();
+      return;
+    }
+    if (event.key === "ArrowDown" || event.key === "ArrowUp") {
+      event.preventDefault();
+      moveUploadMenuFocus(event.key === "ArrowDown" ? 1 : -1);
+    }
+  });
+  uploadBtn.addEventListener("keydown", event => {
+    if (uploadMenuOpen || event.key !== "ArrowDown") return;
+    event.preventDefault();
+    toggleUploadMenu();
+  });
+}
+
+// A dropped directory arrives as a FileSystemEntry, which has no recursive
+// listing of its own: readEntries() hands back one batch at a time and an
+// empty batch marks the end, so it has to be driven until it drains.
+async function readDroppedDirectory(directory) {
+  const reader = directory.createReader();
+  const out = [];
+  for (;;) {
+    const batch = await new Promise((resolve, reject) => reader.readEntries(resolve, reject));
+    if (!batch.length) return out;
+    for (const entry of batch) out.push(entry);
+  }
+}
+
+async function collectDroppedEntry(entry, prefix, files, relativeNames) {
+  if (entry.isFile) {
+    const file = await new Promise((resolve, reject) => entry.file(resolve, reject));
+    files.push(file);
+    relativeNames.push(prefix + file.name);
+    return;
+  }
+  if (!entry.isDirectory) return;
+  const children = await readDroppedDirectory(entry);
+  const childPrefix = prefix + entry.name + "/";
+  for (const child of children) {
+    await collectDroppedEntry(child, childPrefix, files, relativeNames);
+  }
+}
+
+async function uploadDroppedItems(dataTransfer) {
+  const files = [];
+  const relativeNames = [];
+  const dirEntries = [];
+  const items = dataTransfer.items;
+  if (items && items.length) {
+    for (let i = 0; i < items.length; i++) {
+      if (items[i].kind !== "file") continue;
+      const entry = items[i].webkitGetAsEntry ? items[i].webkitGetAsEntry() : null;
+      if (entry) {
+        dirEntries.push(entry);
+        continue;
+      }
+      const file = items[i].getAsFile();
+      if (file) {
+        files.push(file);
+        relativeNames.push(file.name);
+      }
+    }
+  } else {
+    for (let i = 0; i < dataTransfer.files.length; i++) {
+      const file = dataTransfer.files[i];
+      files.push(file);
+      relativeNames.push(uploadRelativeName(file));
+    }
+  }
+  for (const entry of dirEntries) {
+    await collectDroppedEntry(entry, "", files, relativeNames);
+  }
+  await uploadFiles(files, relativeNames);
+}
+
+function dataTransferHasFiles(dataTransfer) {
+  const types = dataTransfer && dataTransfer.types;
+  if (!types) return false;
+  for (let i = 0; i < types.length; i++) {
+    if (types[i] === "Files") return true;
+  }
+  return false;
+}
+
+function setupDropUpload() {
+  // The console browser has no drag source of its own, so the listeners would
+  // only ever raise a hint that nothing can dismiss.
+  if (isPlayStationBrowser()) return;
+  let dragDepth = 0;
+  window.addEventListener("dragenter", event => {
+    if (!dataTransferHasFiles(event.dataTransfer)) return;
+    event.preventDefault();
+    dragDepth++;
+    if (!busy && !loadingPath) dropUploadOverlayEl.hidden = false;
+  });
+  window.addEventListener("dragover", event => {
+    if (!dataTransferHasFiles(event.dataTransfer)) return;
+    event.preventDefault();
+    event.dataTransfer.dropEffect = "copy";
+  });
+  window.addEventListener("dragleave", () => {
+    dragDepth = Math.max(0, dragDepth - 1);
+    if (!dragDepth) dropUploadOverlayEl.hidden = true;
+  });
+  window.addEventListener("drop", event => {
+    if (!dataTransferHasFiles(event.dataTransfer)) return;
+    event.preventDefault();
+    dragDepth = 0;
+    dropUploadOverlayEl.hidden = true;
+    if (busy || loadingPath) return;
+    uploadDroppedItems(event.dataTransfer).catch(err => {
+      const message = t("uploadFailed", { error: err.message || t("backendError") });
+      setStatus(message);
+      alert(message);
+    });
+  });
+}
+
+async function uploadAndExtractFile(file, relativeName, alreadyAsked) {
+  if (busy || loadingPath) return;
+  if (!isExtractableName(relativeName || file.name || "")) {
    alert(t("err_extract_unsupported", { arg: file.name }));
    return;
  }
-  const rel = uploadRelativeName(file);
-  const zipPath = pathJoin(cwd, rel);
-  if (!confirm(t("extractUploadConfirm", { name: rel, path: displayPath(cwd) }))) return;
+  const rel = relativeName || uploadRelativeName(file);
+  // cwd is the byte-mapped echo from the listing while rel comes straight from
+  // the File object; byte-map the name so the joined path stays in one
+  // convention (see encodeFsText).
+  const zipPath = pathJoin(cwd, encodeFsText(rel));
+  if (!alreadyAsked &&
+      !confirm(t("extractUploadConfirm", { name: rel, path: displayPath(cwd) }))) return;
  const conflict = confirm(t("extractOverwriteAsk")) ? "overwrite" : "fail";

  let taskId = 0;
@@ -2384,7 +2750,6 @@ async function uploadAndExtractFile(file) {
    }
  } finally {
    uploadXhr = null;
-    uploadZipEl.value = "";
    if (!trackedTask) setBusy(false);
  }
 }
@@ -2416,16 +2781,13 @@ clearClipboardBtn.addEventListener("click", clearClipboard);
 document.getElementById("renameBtn").addEventListener("click", actionRename);
 downloadBtn.addEventListener("click", actionDownload);
 document.getElementById("deleteBtn").addEventListener("click", actionDelete);
-uploadBtn.addEventListener("click", actionUploadFiles);
-uploadMenuBtn.addEventListener("click", toggleUploadMenu);
-uploadFolderBtn.addEventListener("click", actionUploadFolder);
-uploadAndExtractBtn.addEventListener("click", actionUploadAndExtract);
+uploadBtn.addEventListener("click", toggleUploadMenu);
+uploadFilesItemEl.addEventListener("click", actionUploadFiles);
+uploadFolderItemEl.addEventListener("click", actionUploadFolder);
 uploadFilesEl.addEventListener("change", () => uploadFiles(uploadFilesEl.files));
 uploadFolderEl.addEventListener("change", () => uploadFiles(uploadFolderEl.files));
-uploadZipEl.addEventListener("change", () => {
-  if (uploadZipEl.files.length === 1) uploadAndExtractFile(uploadZipEl.files[0]);
-  else uploadZipEl.value = "";
-});
+setupUploadMenu();
+setupDropUpload();
 exitBtn.addEventListener("click", actionExit);
 parentBtn.addEventListener("click", actionParentDirectory);
 textEditorCloseBtn.addEventListener("click", requestCloseTextEditor);
@@ -2474,10 +2836,6 @@ window.addEventListener("popstate", event => {
    loadAndReveal(path, false, false, true, null, revealPath);
  }
 });
-document.addEventListener("click", event => {
-  if (!uploadMenuEl || uploadMenuEl.contains(event.target)) return;
-  uploadMenuEl.classList.remove("open");
-});
 document.querySelector("thead").addEventListener("click", event => {
  if (busy || loadingPath) return;
  if (parentBtn.contains(event.target)) return;
@@ -2576,6 +2934,7 @@ contentEl.addEventListener("scroll", () => {
 async function init() {
  await loadLanguage();
  applyStaticText();
+  loadVersion();
  readSavedSort();
  updateSortHeaders();
  const savedPath = historyPath() || readSavedPath();
@@ -0,0 +1,258 @@
+# v1.9.3M 真机验证清单
+
+> 目标：在真机上把 **v1.9.3M 相对 v1.9.2 的全部改动**走一遍。
+> 对应任务 #46（五项规定项）+ 「字典超限报错」修复 + 本次「版本号加 M 改版标记」。
+> 逐项打勾，失败项记文案原文。
+
+## 0. 物料
+
+| 项 | 值 |
+|---|---|
+| 待测 ELF | `web-file-mgr-v1.9.3M.elf`（903,448 B，sha256 `8ca47d5a…86b7`） |
+| **回滚 ELF** | `.build/rel-v1.9.2/web-file-mgr-v1.9.2.elf`（870,488 B，sha256 `177e90fe…8e84`，**从 GitHub Release 下载并已核验**） |
+| 测试归档 | `.build/device-test/`（22 个文件，2.5 MB，含 `MANIFEST.txt` 指纹） |
+| 监听端口 | 默认 `8888`，通知栏显示实际端口 |
+
+> **这一轮（2026-09-24 晚）又重编了三次**，都只动前端资源（上传菜单、拖拽提示、页脚
+> 状态行钳制、口令提示键、菜单行高亮、解压按钮常显），C 代码一字节没改。六个构建的
+> **文件尺寸都是 903,448 B**，sha256 各不相同，`.rodata` 逐轮
+> +0x140 / +0x980 / +0x100 / +0x180 / +0x240：
+> `7b5ab00c…`（首轮）→ `212107a6…`（+ 上传菜单）→ `da36834d…`（+ 文案与状态行钳制）→
+> `cf2c0fcf…`（+ 菜单行高亮修复）→ **`8ca47d5a…`（+ 解压按钮常显置灰，本轮待测）**。
+> **以 sha256 为准，别用文件尺寸判断"包换没换"。**
+
+⚠️ **回滚只能用 `.build/rel-v1.9.2/` 那个**。项目根目录里曾经并存的、同名的
+`web-file-mgr-v1.9.2.elf`（903,448 B 的**未发布工作树**）已挪到
+`.build/elf-v1.9.2-worktree-f3164efa.elf`，根目录现在只剩本次待测的 `v1.9.3M`。
+
+> **带 `M` = LisherSong 改版，不带 `M` = 上游原版。** 从这一版起版本号统一带 `M`
+> 后缀（如 `v1.9.3M`），所以「名字里有没有 M」本身就是上游 / 改版的判据。
+
+### 发送与打开
+
+```sh
+nc -q0 <PS5_IP> 9021 < web-file-mgr-v1.9.3M.elf
+# 看 PS5 左上角通知：应显示 PS5 Web File Manager + v1.9.3M + 监听端口
+# 浏览器打开 http://<PS5_IP>:8888/
+```
+
+### 通用纪律
+
+1. **每次解压都新建一个空目标目录**。已知遗留问题：含目录条目的包在「覆盖」模式下解到同一
+   目录第二次必失败（三引擎同构，与本次改动无关）—— 别把它记成回归。
+2. 多卷归档**一次把整个文件夹拖进去**，别只传子卷（UI 对「只选中子卷」会置灰并要求改选首卷）。
+3. 每项记三样：**通过/失败**、**界面文案原文**、**截图**。
+4. 任务列表可直接在浏览器看：`http://<PS5_IP>:8888/api/tasks`。
+
+---
+
+## 1. 版本号四处一致 + 改版标记（规定项⑤，10 秒）
+
+| 位置 | 期望 |
+|---|---|
+| PS5 启动通知 | `v1.9.3M` |
+| 页面底部状态栏的版本号（`#versionText`） | `v1.9.3M` |
+| `http://<PS5_IP>:8888/api/version` | JSON 里 version = `v1.9.3M` |
+| **鼠标悬停**在版本号上 | 浮出提示「本版为 LisherSong 改版（上游原版无 M 后缀）」/ 英文版同义 |
+
+三处（+ 悬停）不一致 = 版本宏或前端兜底串没进二进制。ELF 内已核对：`v1.9.3M`
+出现 1 次、`v1.9.2` 出现 **0** 次；两条 tooltip 文案在解压后的 lang 资源里逐一命中。
+
+> 若你此前已经刷过不带 M 的 `v1.9.3`：那个包只差字符串，**功能行为与本版完全一致**，
+> 所以先前测出的结果仍然有效，不必因为加了 M 就重测一遍功能项。
+> 反过来，只要界面显示的是 `v1.9.3`（无 M）就是旧包，`v1.9.3M` 才是本次待测。
+
+---
+
+## 2. 字典超限报错（本次修复的**唯一**新行为，优先做）
+
+上传 `00-dict-limit.rar`（**7,055 B**，一个 8 GiB 字典的合成归档）→ 解压 → 选冲突策略 → 开始。
+
+| 检查 | 期望 |
+|---|---|
+| 错误码/文案 | `extract_dict_too_large`，文案含 **`8192 MiB (limit 4096 MiB)`** |
+| **不应**出现 | 「压缩包内单个文件过大: **hello.txt**」← 修复前的错误归因（该文件只有 7 B 级） |
+| 目标目录 | **不应**出现 `hello.txt`，也不留下垃圾文件 |
+| 行为 | 干净失败，不是崩溃、不是中途 OOM |
+
+> 判读：若看到「单个文件过大」⇒ 装的是旧 ELF；若看到字典文案 ⇒ 这一项通过。
+> 这项改动**只改报错、行为零变化**，所以「拒绝解压」是**正确**结果。
+
+---
+
+## 3. 三类分卷解压（规定项①）
+
+准备：把 `.build/device-test/` 里对应子目录整体上传到 PS5 的某个目录，然后在该目录里解压。
+
+| 引擎 | 上传哪个目录 | 点哪个文件 | 期望输出 |
+|---|---|---|---|
+| **ZIP**（WinRAR 命名，字节切分） | `01-zip-vol/` | `parts.part1.zip` | 4 项：`readme.txt`、`sub/data.bin`、`sub/deep/more.bin`、`tail.bin` |
+| **ZIP**（Info-ZIP 分盘，偏移按盘算） | `01-zip-vol/` | `disks.zip` | 同上 4 项 |
+| **RAR**（RAR5，3 卷） | `01-rar-vol/` | `vol.part1.rar`（**必须选首卷**） | `big.bin`，**524,288 B** |
+| **7z**（7 卷，`.7z.001…`） | `01-7z-vol/` | 任一卷均可触发 | 一个 `_src/` 目录，内含 6 项：`readme.txt`、`binary.bin`、`zeros.bin`、`sub/code.bin`、`sub/nested.txt`、`sub/中文-テスト.txt` |
+
+要点：
+- ZIP/RAR/7z 各测一遍**首卷与子卷**的触发行为：ZIP/7z 任一卷都该能触发；RAR 选子卷应**置灰并提示改选首卷**（这是设计行为，不是 bug）。
+- 7z 那组含**中文 + 日文文件名**，顺手验证 UTF-8 落盘。
+- 删掉（或改名）某一卷再试一次，应给「找不到分卷」类报错而不是静默成功 —— 顺带查负路径；负向夹具用的是
+  `tests/fixtures/broken.zip.001`（缺后续卷）与 `gap.zip.001 + gap.zip.003`（缺第 2 卷），需要时一并上传。
+
+---
+
+## 4. 加密归档（规定项②，改动最集中）
+
+口令：三个套件用的是**同一个测试口令**，定义在 `tests/run-sevenz-tests.sh`
+（`FIXTURE_PASSWORD`）与 `tests/make-zip-enc-fixtures.bat` / `tests/make-rar-fixtures.bat` 里，先去看一眼。
+
+| 文件 | 加密方式 | 期望 |
+|---|---|---|
+| `02-encrypted/enc-zipcrypto.zip` | ZipCrypto | 提示输入口令 → 解出 `root.txt`、`dir/nested.txt` |
+| `02-encrypted/enc-aes256.zip` | WinZip AES-256 | 同上 |
+| `02-encrypted/enc-aes256-store.zip` | AES-256 + 存储 | 同上 |
+| `02-encrypted/enc-v6.rar` | RAR5 `-hp`（加密头） | **连列表都要口令** → 提示输入 → 解出同两文件 |
+| `02-encrypted/aes.7z` | 7zAES（数据加密） | 7z 会在**开始前**先问口令，然后解出 `_src/` 那 6 项 |
+| `02-encrypted/aeshe.7z` | **7zAES + `-mhe=on`（加密头）** | **本次头号目标**：加密头由新增的 `src/sevenz_header.c` 自解；应能正常列出并解出 `_src/` 那 6 项 |
+
+必测的负路径：
+
+| 场景 | 期望 |
+|---|---|
+| 口令故意输错（每格式至少一次） | 报 `err_extract_password` 并弹出重试框，**最多 3 次**；取消即结束，不卡死 |
+| 重试时换正确口令 | 第 2/3 次能成功（证明「记住原请求」的逻辑生效：冲突策略、大文件选配不丢） |
+| 7z 加密头 + 错口令 | 应是口令错误提示，**不是**「不受支持的归档 / 损坏」 |
+| **某次提示文案** | 第一次失败说「**此压缩包已加密。输入密码后解压，取消则停止解压。**」；第二次起才是「密码不正确」（第一次没输过密码，不该说你输错了） |
+| **错误文案里的条目名** | 中文/日文条目名必须**正常显示**，不得出现 `â®…` 或方框乱码 |
+
+> 判读：`aeshe.7z` 在 v1.9.2 上是**已知缺口**（`tests/run-sevenz-tests.sh` 的 `KNOWN_GAPS`
+> 里原来就写着 `aeshe`），v1.9.3M 才闭合。这一项通过 = 最后一个 7z 缺口在真机确认关闭。
+
+---
+
+## 5. 上传入口 / 口令提示 / 名称编码（本轮修复，优先做，2 分钟）
+
+这一节全部是**界面与前端 codec** 的改动，测起来最快，也最容易看出装的是不是新包。
+
+### 5a 上传按钮变成菜单
+
+| 检查 | 期望 |
+|---|---|
+| 按钮外观 | 「上传」右侧带小三角（▾） |
+| 点一下 | 在按钮正下方弹出列表：**上传文件 / 上传文件夹**（不再是「主按钮 + 一个小箭头」） |
+| 选「上传文件」 | 弹系统文件选择器，可多选 |
+| 选「上传文件夹」 | 弹目录选择器（原「小箭头」的功能，没丢） |
+| 键盘 | 打开后焦点在第一项；`Esc` 关闭并把焦点还给按钮；`↑/↓` 在两项间移动 |
+| 选中高亮 | 鼠标移到哪一项、或 `↑/↓` 停在哪一项，**只有那一行**亮；颜色一致；高亮完全落在菜单面板内，**不越出边框、不压住相邻行**（修复前是越界蓝框 + 两侧弧线，且 hover 与键盘焦点两行同时亮） |
+| 点别处 | 菜单关闭 |
+
+### 5b 拖拽提示文案
+
+| 检查 | 期望 |
+|---|---|
+| 页脚（版本号左边） | 常显灰字：**可直接把文件或文件夹拖进窗口上传** |
+| 拖文件到窗口 | 仍然出现「松开即上传到当前目录」覆盖层（旧行为不变） |
+| 在 PS5 自带浏览器里打开 | 上传按钮与这行灰色提示**都不显示**（`remote-only`，控制台浏览器没有拖拽源） |
+| 上传中/选中文件时 | 页脚状态文案变长时，状态文字**单行截断成 `…`**，提示与版本号都还在同一行（不再撑破页脚） |
+
+### 5c 加密包「上传即解压」必须问口令（**这就是你报的那个 bug**）
+
+**复现原步骤**：进一个**中文名字的文件夹**（或任意非 ASCII 目录名），上传一个**有密码的 ZIP**
+→ 弹「这是压缩包 x.zip，确定：上传后自动解压 / 取消：仅上传」→ 点确定。
+
+| 检查 | 期望（修复后） |
+|---|---|
+| **上传完成后** | 直接弹出「**此压缩包已加密。输入密码后解压，取消则停止解压。**」 |
+| **不应**出现 | 一个只有「确定」的错误框、且必须自己去按工具栏「解压」才给输密码 ← 修复前的行为 |
+| 输入正确口令 | 继续解压并成功；结束后源压缩包被删除（上传即解压的既有行为） |
+| 取消口令框 | 走原来的失败提示，不静默 |
+| 中文条目名的包解压失败时 | 错误框里的条目名是**中文**，不是 `â®…ç§.psd` 那种乱码 |
+
+> 根因（供判读）：口令重试原来是按**路径**记住原始请求的，而路径是非 ASCII 时
+> 「页面持有的字符串」与「服务端任务回报的字符串」编码表示不同 ⇒ 查不到 ⇒ 不弹口令框，
+> 只能手动再解压一次。现在按**任务 id** 记，路径编码再也不会影响它。
+
+### 5e 解压按钮常显置灰
+
+工具栏里现在**一直有「解压」按钮**，不再只在选中压缩包时才冒出来。
+
+| 检查 | 期望 |
+|---|---|
+| 什么都不选 | 按钮**在**工具栏里（复制/移动/重命名/下载/删除 之后），**灰色、点不动** |
+| 停在灰色按钮上 | 出现提示「**选中一个压缩包后才能解压（ZIP / RAR / 7z）**」 |
+| 选中一个文件夹 | 仍然灰色、点不动 |
+| 选中**一个**压缩包（`.zip` / `.rar` / `.7z`） | 按钮**变亮可点**，提示变成「解压到当前目录: <包名>」 |
+| 选中**两个**压缩包 | 又变灰，提示「一次只能解压一个压缩包」 |
+| 只选中 `.part02.rar` 这类子卷 | 变灰，提示「请改选主卷（如 .rar 或 .part01.rar）」（旧行为） |
+| 按钮文字 | 是短标签「**解压**」，与相邻按钮等宽（不再是「解压到当前目录」） |
+| 有任务在跑时 | 变灰（和其他按钮一起被锁） |
+
+> 为什么改成常显：旧版不选中压缩包就**完全没有**这个按钮，用户不知道有这个功能。
+> 代价是工具栏常态宽了 96 px ⇒ 窗口窄到 **1190 px** 以下工具栏会换成两行
+> （英文界面是 1350 px；控制台 1920 px、1280 px 都不受影响）。
+
+---
+
+## 6. 分卷 RAR 进度条实时走动（规定项④）
+
+`01-rar-vol/` 那组只有 512 KB，进度条会一闪而过 ⇒ 用你自己那份大分卷 RAR（之前那个 ≈11.6 GB 的包已经被清理了，
+可以用 WinRAR 现造一个：`-m1 -md=4g -v1g`，内容选一个几 GB 的可压缩文件）。
+
+| 检查 | 期望 |
+|---|---|
+| 进度条 | 按**字节**持续推进，不是长时间 0% 后直接跳 100% |
+| 速度读数 | 有合理 MB/s 读数（它是 250 ms 瞬时采样，抖动正常；只信「总字节 ÷ 总耗时」） |
+| `entries_done` | 跨卷的**单个大条目**场景下可能长时间停在 0 —— 这是设计如此（`assets/main.js:2118`），看字节进度即可 |
+| 取消 | 中途取消能停下，不残留半成品（取消是条目粒度） |
+
+---
+
+## 7. 大 ZIP：160 GB / 9.5 万文件（规定项③，最后做）
+
+这项只能在真机跑，且最费时。
+
+| 检查 | 期望 |
+|---|---|
+| scan 阶段 | 不 OOM、不长时间无响应；进度条在走 |
+| 内存 | 峰值平稳（scan 只读中央目录，不解码） |
+| 空间预检 | 目标分区空间不足时应**提前**报错（`check_space()` 要求双份空间） |
+| 完成 | 0 报错解完；条目数与源一致 |
+
+---
+
+## 8. 取证与回滚
+
+**失败时提供这三样**（我按这个定位，不用你再复述）：
+1. 界面/通知栏**文案原文**（含错误码，如 `extract_dict_too_large`）；
+2. `http://<PS5_IP>:8888/api/tasks` 的返回；
+3. 截图（含目标目录文件列表）。
+
+**回滚**（一条命令，产物已核验）：
+
+```sh
+nc -q0 <PS5_IP> 9021 < .build/rel-v1.9.2/web-file-mgr-v1.9.2.elf
+```
+
+---
+
+## 结果记录表
+
+| # | 项目 | 结果 | 文案/备注 |
+|---|---|---|---|
+| 1 | 版本号四处一致 + 悬停改版提示 | ☐ | |
+| 2 | 字典超限报错（8 GiB 字典） | ☐ | |
+| 3a | ZIP 分卷（`parts.partN.zip`） | ☐ | |
+| 3b | ZIP 分盘（`disks.z01+.zip`） | ☐ | |
+| 3c | RAR 分卷（选首卷 / 选子卷置灰） | ☐ | |
+| 3d | 7z 分卷（含中日文文件名） | ☐ | |
+| 4a | ZIP 加密 ×3（ZipCrypto / AES / AES-store） | ☐ | |
+| 4b | RAR 加密头 `-hp` | ☐ | |
+| 4c | 7z `aes.7z` | ☐ | |
+| 4d | **7z `aeshe.7z`（`-mhe=on` 加密头）** | ☐ | |
+| 4e | 错口令 + 重试（三格式） | ☐ | |
+| 4f | 首次失败提示文案 / 条目名不乱码 | ☐ | |
+| 5a | 上传按钮 → 菜单（文件 / 文件夹） | ☐ | |
+| 5b | 页脚拖拽提示 + PS5 浏览器里隐藏 | ☐ | |
+| 5c | **加密包上传即解压 → 直接弹口令框**（原 bug） | ☐ | |
+| 5d | 菜单行高亮（只有一行亮、不越界、hover 与键盘同色） | ☐ | |
+| 5e | 解压按钮常显置灰（灰 → 选中一个包变亮 → 选两个又变灰） | ☐ | |
+| 6 | 分卷 RAR 进度条 | ☐ | |
+| 7 | 大 ZIP 160 GB / 9.5 万文件 | ☐ | |
@@ -0,0 +1,618 @@
+# 解压性能：实测、根因、提速方案
+
+> 实测 2026-09-15 · 对照物 = 官方 7-Zip 26.03（上游 v1.8 的 helper 就是它）
+> 复现：`python tests/bench_driver.py --big --runs 3`；WSL 同环境对比见 `.build/bench/wsl-*.sh`
+
+> **✅ 方案 A 已落地（2026-09-16）**：`Asm/x86/LzmaDecOpt.asm` + `7zAsm.asm` 已 vendor 到
+> `third_party/7z/`，jwasm `-elf64 -DABI_LINUX` 汇编进 PS5 与 Linux 两条链路，
+> `LzmaDec.o` 加 `-DZ7_LZMA_DEC_OPT`。实测 **1.39 s → 1.05–1.13 s（1.26×）**，解出字节与
+> C 版逐字节一致；7z 测试矩阵 28 checks 全过。Makefile 对该优化做了条件化（无 jwasm 自动
+> 退回纯 C）并依赖 Makefile 本身触发重编（flag 变化不会被 make 察觉）。
+>
+> **✅ 方案 B 已落地（2026-09-16）**：`Lzma2DecMt.c` + `MtDec.c` + `Threads.c` 已 vendor，
+> 单一纯 LZMA2 folder（7-Zip 默认布局）走 SDK 并行解码器（`src/sevenz_mt.c` 适配层），
+> 8 线程 + 1 MiB inBufSize_MT；`SZ_ERROR_THREAD` 自动降级回单线程 chain（BCJ2/加密/奇异
+> 布局本来就由 chain 负责）。实测 329 MiB：1.05 s → **0.77 s（1.37×）**，与 7za -mmt=off
+> 打平（898 ms）；7za -mmt=8 = 485 ms。7z/ZIP/RAR 163 checks 全绿。
+>
+> **✅ ZIP 引擎逐条目 fsync 移除（2026-09-16）** —— 原计划写的是「批量化（每 64MB/N 条刷一次）」，
+> **实际落地改为彻底移除**：publish 是纯 rename、又没有续解功能，逐条目 fsync 换不到任何东西
+> （RAR/7z 引擎本来就没有，三引擎现在统一为「不 sync、只 rename」）。8000 文件 fixture：fsync 版
+> \>200 s 未完成 → 无 fsync **14.5 s（≥14×）**。同机官方 7-Zip 反而要 >400 s（Defender
+> 实时扫描逐文件查杀；PS5 无此因素）。
+>
+> 与 §二 排除 1 不矛盾：那里测的是**单一大文件**归档，一次 fsync 本来就近乎免费；这里是
+> **8000 个文件**，成本随条目数线性叠加（且 PS5 无 Defender，比例只会更极端）。
+> 已知取舍：publish 之后到落盘之间断电，会出现「文件在但内容不完整」；要补只需在 extract
+> 收尾做**一次**目录/整盘 flush（PS5 是 FreeBSD 系，`syncfs()` 不一定有，`sync()` 是全盘、偏重）。
+> 代码现状见 `src/zip_extract.c:937-945`。
+
+## 结论
+
+**7z 解码我们比 7-Zip 慢 1.57×（单线程），根因已定位到一个具体的编译开关。**
+
+不是架构问题，不是算法问题，不是编译选项问题 —— 是 **SDK 里有一份汇编版解码器我们没启用**：
+
+```c
+/* LzmaDec.c */
+#ifdef Z7_LZMA_DEC_OPT
+int Z7_FASTCALL LZMA_DECODE_REAL(CLzmaDec *p, SizeT limit, const Byte *bufLimit);  /* asm */
+#else
+  ... 纯 C 宏展开 + LzmaDec_DecodeReal2()   /* ← 我们在这里 */
+#endif
+```
+
+`LzmaDecOpt.asm` 是 Igor Pavlov 官方 SDK 的一部分（public domain），**1339 行**，实现同一个函数。开不开这个开关，实测差 1.5 倍。
+
+---
+
+## 一、同环境实测（关键：排除跨平台假象）
+
+第一轮数据是在 Windows 上打的（我们 MinGW 构建 vs `7za.exe`），混了平台因素。重做：**在同一台机器、同一个 WSL Linux 环境、同一份归档、同一类编译器**下对比。
+
+归档：329 MiB 解压量 / 22 MiB 压缩，LZMA2 solid，单文件
+
+| 配置 | 单线程 | 8 线程 | 相对我们 |
+|---|---:|---:|---:|
+| **ours**（facade，含 staging + publish；当时仍含逐条目 fsync，2026-09-16 已移除） | **1.39 s** | — | 1.00× |
+| 官方 7-Zip（Linux 构建） | **0.89 s** | **0.51 s** | **1.57× / 2.73×** |
+
+> 两个数字都是同一台机器上的实测。7-Zip 的 Linux 版和 Windows 版几乎一样快（0.89 vs 0.84 s），说明平台差异不是因素。
+
+---
+
+## 二、四个被实测排除的原因
+
+排查过程里每个假设都先给出过错误结论，所以逐个记录：
+
+| # | 假设 | 实验 | 结果 |
+|---|---|---|---|
+| 1 | **fsync / 写盘开销** | 两边都解到 `/dev/shm`（tmpfs，fsync 近乎免费） | ❌ 我们 1.47 s，磁盘上也是 1.47 s —— **fsync 成本可忽略** |
+| 2 | **pull 粒度太小**（64 KiB 输出块 → 5000+ 次调用） | 把 `SZ_OUT_CHUNK` 提到 1 MiB | ❌ 1.39 s，与 64 KiB 无差别。profile 显示 `node_pull` **只调用 329 次**，调度开销 ≈ 0 |
+| 3 | **编译选项保守**（我们用 `-O2 -w`） | `-O3` / `-march=native` / `-march=x86-64-v3` 各跑一遍 | ❌ 全部落在 1.31–1.52 s，无显著差异 |
+| 4 | **汇编优化只值 6%**（我曾据此推断"不是主因"） | 对比 Windows 版(有 asm) 与 Linux 版 | ❌ **这个推断是错的** —— Linux 官方版同样含 asm，所以只看到 6% 的平台差异。见下节 |
+
+---
+
+## 三、真正的根因：profile 说话
+
+`gprof`，同一份归档：
+
+```
+  %      self     calls   name
+ 82.81   1.06 s   81237   LzmaDec_DecodeReal2      ← LZMA 解码核心（C 版）
+ 17.19   0.22 s     660   CrcUpdateT12             ← CRC32 校验
+  0.00   0.00 s     329   node_pull                ← 我们的链调度，可忽略
+  0.00   0.00 s     329   szx_sink_write           ← 写盘，可忽略
+  0.00   0.00 s    1705   LzmaDec_DecodeToDic
+```
+
+**82.8% 的时间在一个函数里，而那个函数有一个 asm 版本我们没有使用。**
+
+这解释了为什么前四个假设全部落空：它们针对的都是那 0% 的部分。
+
+### 三方交叉验证
+
+- 我们的构建：未定义 `Z7_LZMA_DEC_OPT` → profile 里是 `LzmaDec_DecodeReal2` ✓
+- SDK 源码：明确写着 `#ifdef Z7_LZMA_DEC_OPT` 时声明外部 asm 符号 ✓
+- 官方 GCC 构建规则（`7zip_gcc_c.mak`）：`USE_LZMA_DEC_ASM` 开关 + `jwasm` 汇编 `LzmaDecOpt.asm` ✓
+
+### 附带发现：CRC 占 17%
+
+`CrcUpdateT12`（slicing-by-12，**纯软件实现**）花掉 0.22 s。
+
+> ⚠️ **2026-09-23 更正**：本节原先写着「7-Zip 解压时同样校验 CRC，所以这部分**不构成差距**」——**这条是错的**。
+> 依据是本仓 vendor 的官方构建规则 `third_party/7z/7zip_gcc_c.mak:298-310`：
+> ```
+> ifdef USE_X86_ASM
+> $O/7zCrcOpt.o: ../../../Asm/x86/7zCrcOpt.asm     ← 官方走这条：汇编版
+> else
+> $O/7zCrcOpt.o: ../../7zCrcOpt.c                  ← 我们走这条：纯 C
+> ```
+> 而 `CpuArch.h:691` 的 `CPU_IsSupported_CRC32()` 说明那份汇编就是 SSE4.2 硬件 `crc32`。
+> 我们的 `third_party/7z/Asm/x86/` 里**只有** `7zAsm.asm` 与 `LzmaDecOpt.asm`，**没有 `7zCrcOpt.asm`**。
+> 所以这 17% **是真实差距的一部分**，不只是「可选的净提速」；它同时还是 MT 路径的**串行瓶颈**
+> （`src/sevenz_mt.c` 的 `mt_seq_write` 在调用线程上算 CRC，Amdahl 意义上压住了多线程上限）。
+>
+> **2026-09-23 实测补充（`.build/_crcbench.c`，本机 MinGW x64，329 MiB 同一块数据，跑两次）**：
+> `CrcUpdateT12` **3.18–3.51 GB/s**（329 MiB → 0.098–0.109 s），zlib `crc32` **2.59–2.80 GB/s**，
+> SSE4.2 `crc32` 指令（直线写法）**6.03–6.11 GB/s**。
+> → CRC 实际只占单线程 1.39 s 的 **≈7%**，上面那个「0.22 s / 17%」**大概率是 gprof 插桩放大的**
+> （`-pg` 对纯循环函数特别吃亏）。**本节往下请按 ≤7% 理解，不要再引用 17%。**
+> 另外实测挖出一个**会算错的陷阱**，见「方案 C」。
+
+---
+
+## 四、提速方案
+
+### 方案 A（推荐）：启用 asm 解码器
+
+| 步骤 | 内容 |
+|---|---|
+| 1 | 取 `Asm/x86/LzmaDecOpt.asm` + `Asm/x86/7zAsm.asm` 入 `third_party/7z/` |
+| 2 | 用 **jwasm**（MASM 兼容汇编器，支持 ELF64 输出）汇编成 `.o` |
+| 3 | Makefile 加规则；`LzmaDec.c` 编译时加 `-DZ7_LZMA_DEC_OPT` |
+| 4 | 完整测试矩阵（163 checks）+ 基准复测 |
+
+- **预期收益：1.39 s → ~0.95 s（≈1.45×）**，追平 7-Zip 单线程水平
+- **工作量**：小～中（一个汇编文件 + 一条 Makefile 规则 + 一个宏）
+- **风险**：中 —— 唯一的不确定点是 **jwasm 能否产出 PS5（prospero-clang / x86-64 ELF）可链接的目标文件**。这一条必须先验证再动手
+- **为什么"稳"**：asm 是 SDK 官方组成部分（同一位作者维护，与 C 版有链接时版本校验 `_3`，对不上会直接链接失败而不是静默出错）；正确性由现有 163 项测试兜底
+
+### 方案 B：多线程 LZMA2 解码
+
+SDK 自带 `C/Lzma2DecMt.c`（1095 行，public domain）就是 7-Zip `-mmt` 的并行实现，实测 0.89 → 0.51 s。
+
+- **预期收益：额外 1.75×**（与 A 叠加后 ≈ 2.6×，基本追平 7-Zip 全核）
+- **工作量**：大 —— 要重构 chain 的调度（block 级并行 + 字典依赖管理）
+- **风险**：中高（并发正确性、内存峰值；PS5 只有 8 核且 HTTP/任务系统同进程，建议限制线程数）
+- **前置**：建议先完成 A，因为 A 不改架构、收益确定、能独立验证
+
+### 方案 C：CRC 加速（**实测后收益大幅缩水，且有一个会算错的陷阱**）
+
+`.build/_crcbench.c` 实测（本机 MinGW x64，329 MiB 同一块数据，两次运行）：
+
+| 实现 | 吞吐 | 329 MiB 耗时 | 谁在用 |
+|---|---:|---:|---|
+| `CrcUpdateT12`（slicing-by-12） | 3.18–3.51 GB/s | 0.098–0.109 s | 我们：7z chain / MT 输出 / 逐条目 CRC |
+| zlib `crc32` | 2.59–2.80 GB/s | 0.123–0.133 s | 我们：ZIP 引擎 |
+| SSE4.2 `crc32` 指令（直线写法） | 6.03–6.11 GB/s | 0.056–0.057 s | 候选 |
+
+> ⚠️ **陷阱：x86 的 `crc32` 指令算的是 CRC-32C（Castagnoli），不是三个格式要的 IEEE CRC-32。**
+> 同一份基准里的判定（标准向量 `"123456789"`）：
+> `_mm_crc32_*` 得 **`0xE3069283`（CRC-32C）**，而 `CrcCalc` / zlib 得 **`0xCBF43926`（IEEE）**。
+> 所以**不能把 `CrcUpdate` 直接换成 `_mm_crc32_u64`** —— 必须补一个多项式转换
+> （GF(2) 上的 32×32 矩阵），或改用 pshufb / PCLMULQDQ 手写 IEEE 并行 CRC。
+> **这正是官方 `Asm/x86/7zCrcOpt.asm` 存在的意义**：它不是两行 intrinsic 包装。
+> UnRAR 那边同理 —— `third_party/unrar7/crc.cpp` 的硬件路径是 `USE_NEON_CRC32`（**ARM 专属**），
+> x86 上是 slicing-by-16 纯软件。
+
+**收益重估（按实测）**：CRC 只占单线程 ≈7%（0.098 s / 1.39 s）。硬件指令直线写法 1.8× 于
+slicing-by-12，但还要扣掉多项式转换的开销 → 乐观估计单线程省 **0.05–0.07 s ≈ 4–5%**；
+MT 路径里它是串行分量（`sevenz_mt.c:64`），按 0.098 s 算 0.77 s → 约 0.72 s（≈6%），
+**不足以解释 8 线程下与 `7za -mmt=8`（0.485 s）的 1.6× 差距**。
+
+**结论**：这仍然是**我们与 7-Zip 差距里确定存在**的一块（官方走 `USE_X86_ASM` 分支编汇编版，
+我们走 `else` 编纯 C），但**收益是个位数百分比，不是 10–15%，实现也不平凡**。
+风险倒是低：CRC 算错会**响亮失败**（每个条目报 `ZIPX_ERR_CRC`），现有 177 + 27 项测试会立刻抓住，
+不会静默写坏数据。**优先级从「最高」降为「可做，但别指望它拉平差距」。**
+
+### 方案 D（备选，不推荐）：上游的 helper 路线
+
+直接把 7-Zip 做成独立进程，一步到位拿到 1.57×/2.73×。
+
+不推荐的理由：
+
+1. 引入外部 ELF 依赖 + IPC + 进程生命周期管理，**故障模式比现在多得多**（"最稳"的反面）
+2. 方案 A 用一个文件 + 一条规则就能拿到 1.45×，D 的增量收益只有多线程那部分
+3. PS5 上还要处理 elfldr 加载；上游自己都是"单独分发，让用户手动放到 `/data/wfm/`"
+
+---
+
+## 五、执行顺序建议
+
+```
+第一步  A（asm 解码器）                        ✅ 已落地 2026-09-16，实测 1.26×
+        └─ 先验证 jwasm → ELF64 → prospero-ld 这条链能否走通   ✅ 走通了
+第二步  B（多线程）                            ✅ 已落地 2026-09-16，实测 1.37×
+        └─ 在 A 的基础上做，目标 ~0.55 s      ⚠️ 实际 0.77 s：仍慢于 7za -mmt=8 的 0.485 s
+第三步  C（CRC 加速）                          ⬜ 未做 —— 但**实测后收益降到 4–5%**，且有 CRC-32C 陷阱
+        └─ 官方走 USE_X86_ASM 编汇编版，我们编纯 C，确是真实差距；但不值得为它冒险
+```
+
+> **2026-09-23 补充**：B 之后我们与 `7za` 的对比是 0.77 s vs 单线程 0.898 s / 8 线程 0.485 s。
+> 也就是说单线程已打平，**8 线程下仍差约 1.6×**。
+> 曾把这段差距归给「没做的 CRC 硬件化」，但实测否掉了这个假设：CRC 全程只占 ≈7%（**且那是
+> gprof 放大后的口径，实测 0.098 s 更小**），把它全消掉也只值 4–5%，撑不起 1.6×。
+> 更可能的来源是 BCJ2 / 7zAES 布局仍走单线程 chain、以及 `Lzma2DecMt` 自身的线程扇出效率
+> —— 两者都要真机 profile 才能定性。
+> 其余候选（ZIP inflate 换 libdeflate、条目级并行、AES-NI）同理，均属「收益不可预期」或「工程量大」。
+
+> **⚠️ 2026-09-23 限定：上面这个 1.59× 是在「最有利的输入形状」上测出来的，不能外推到真实归档。**
+>
+> 先看基准归档到底是什么（`tests/bench_driver.py:156-179` + payload 构造 `:144-156`）：
+>
+> ```
+> payload  = 文本块 ×240 → 一个大文件；再拼 ntoskrnl.exe ×30 → payload_mix.bin
+> 7za add  = -t7z -m0=lzma2 -mx=5 -ms=on
+> ```
+>
+> 也就是 **1 个条目 / 1 个 solid folder / 1 个纯 LZMA2 coder / 未加密**。而 `sz_chain_lzma2_root()`
+> （`src/sevenz_chain.c:750-762`）要求**恰好** `num_coders == 1 && num_bonds == 0 &&
+> num_pack_streams == 1 && method == LZMA2` 才走 MT —— 换句话说，这个 fixture 是**唯一能让我们的
+> MT 生效的形状**，也是 7-Zip 拿不到任何结构优势的形状。它把 per-entry 开销（我们的强项）和
+> 非 LZMA2 布局（我们的弱项）**同时排除在外**了。
+>
+> 真实 PS5 归档（游戏包 / repack）几乎全是相反的形状：
+>
+> | 真实特征 | 对我们的后果 | 对 7-Zip 的后果 |
+> |---|---|---|
+> | 几千～几万个条目 | per-entry 开销主导（这块我们反而大幅领先，见上方 8000 文件数据） | 同样逐条目，无优势 |
+> | `-ms=off` / 超大归档切块 → **多 folder** | `num_pack_streams != 1` → **MT 失效**，退回单线程 chain | 跨 folder/块并行，`-mmt` 照常吃满 |
+> | exe/dll 用 **BCJ2** | `num_coders != 1` → **MT 失效** | 照常多线程 |
+> | **7zAES 加密** | `sz_chain_needs_password` → **MT 失效** | 照常多线程 |
+>
+> 结论：**1.59× 既不是上限也不是下限**，真实方向未知 —— 可能因 I/O 与 per-entry 成本被摊薄到无关，
+> 也可能因为整条解码退回单线程而比 1.59× 更糟。**在拿到真实归档上的 profile 之前，任何一侧的
+> 断言都是猜的。**
+>
+> 同样，下面这句原话也**未经验证**，暂按假设保留：
+> 「在真实场景（大游戏包）里受存储 I/O 限制，差距往往比这个倍数更小」——它成立的前提是解码项
+> 只占 wall-clock 的一小部分；按 0.77 s / 329 MiB ≈ 427 MiB/s 的解码吞吐与 PS5 存储带宽同量级来算，
+> 这个前提**未必成立**。
+
+**不做任何优化时的现状也是可接受的**：1.39 s / 329 MiB ≈ 237 MiB/s 单线程吞吐；ZIP/RAR 两个引擎
+已分别压过/追平各自的官方实现，7z 单线程与 `7za -mmt=off` 打平。
+
+---
+
+## 六、真机首次实测（2026-09-23）
+
+> ### ⚠️⚠️ 第二次更正（2026-09-23 深夜）：拿到**真实归档的参数**，并实测了 MT
+> 用户给了 `D:\PPSA16608-e.part{1,2,3}.rar`，其中 **part3 当时还在盘上**，我用 WinRAR 7.23 的
+> `UnRAR lt` 直接读了它的头（该文件随后被用户清理掉，故下列数字是**一次性的实测记录**）：
+>
+> | 项 | 实测值 |
+> |---|---|
+> | 格式 | **RAR 5**（不是 RAR4；头 8 字节 `52 61 72 21 1A 07 01 00`） |
+> | 分卷 | **卷 3 / 锁定（locked）** |
+> | **固实** | **不是固实** —— 直接解析 part3 主头：archive flags = `0x0013` = `VOLUME|VOLNUMBER|LOCK`，**`MHFL_SOLID=0x0004` 未置位**（`third_party/unrar7/headers5.hpp:25-29`）。旁证两处自洽：`MHFL_VOLNUMBER` ⇒ volnumber=2 ⇒ unrar 显示「卷 3」✓；`MHFL_LOCK` ⇒ unrar 显示「锁定」✓ |
+> | 关键条目 | `PPSA16608.exfat` **19 493 027 840 B → 打包 3 831 295 727 B**（**ratio 5.09 : 1**，高度可压缩） |
+> | 压缩参数 | **`RAR 5.0(v50) -m1 -md=4g`** —— **-m1「最快」档 + 4 GiB 字典** |
+> | 体量 | part3 = **3.568 GiB ≈ 该条目的打包大小** ⇒ 这个 19.5 GB 条目**整段都在 part3 内**（另有两个 KB 级小文件）；parts 1+2（各 4 GB）装的是其余 ~1250 个条目 |
+>
+> **① UI 速度口径已核实 = 解压后字节。** `src/rar_extract.c:766` 在 `UCM_PROCESSDATA` 回调里
+> `c->bytes_done += p2`（`p2` 是 unrar 交出的**解压后**长度），`bytes_total` 累加 `hdr.UnpSize`。
+> ⇒ 用户看到的 **10–40 MB/s 是"吐出数据的速度"**。
+>
+> **② 「scan 阶段白解码一遍（2×）」这个最大嫌疑——已排除。**
+> `third_party/unrar7/dll.cpp:341-342` 只在 **`!Arc.Solid`** 时把 `RAR_SKIP` 走廉价的
+> `Arc.SeekToNext()` 分支；`extract.cpp:529`（`SkipSolid=Arc.Solid` ⇒ 真解码后丢弃）只在
+> **固实**时成立。本档**非固实** ⇒ 我们的 scan 只读头 + 跳过字节，**不解码**。
+> （这条曾是最有希望的一项：真固实的话 `scan + extract` 会把 11.6 GB 解码两遍。）
+>
+> **③ MT 收益已实测**（host、WinRAR 自带 **UnRAR 7.23**、`-mt<N>` 开关虽未见于 `-?` 帮助但可解析）：
+>
+> | 夹具 | 载荷 | `-mt1` | `-mt8` | 加速 |
+> |---|---|---:|---:|---:|
+> | **代表性**（`-m1 -md4g`、5.27:1 可压缩、固实、2 GB、16 文件） | 2 GB | **386 MB/s** | **946 MB/s** | **2.45×** |
+> | 代表性同上但不固实（5.01:1） | 2 GB | 505 MB/s | 1222 MB/s | 2.42× |
+> | ~~非代表性~~（90% 随机数据 ⇒ 压缩块小） | 240 MB | 129 MB/s | 331 MB/s | ~~2.55×~~ **作废** |
+>
+> ⇒ **形状错误会让结论偏乐观**：第一版夹具用 90% 随机数据，压缩块远小于
+> `unpack50mt.cpp:150-152` 的 `LargeBlockSize=0x20000`（128 KiB）阈值，MT 全程生效；
+> 真实归档是 5:1 可压缩数据，块更大、会触发 `LargeBlock` 退化路径，实测也确实从 2.55× 降到 2.45×。
+> 结论：**在真实形状上 MT 值 ~2.4×**，可信。（单位均为**解压后** MB/s。）
+>
+> **④ 接线比原计划简单：1 个编译开关 + 1 个链接开关，不用改 vendored 源码、不用增删源文件。**
+> （下表中间那一行「把 `threadmisc.cpp` 加进源列表」**经实测作废** —— 行内已更正。）
+> | 改动 | 位置 | 为什么必需 |
+> |---|---|---|
+> | `-DRAR_SMP` | `Makefile:UNRAR7_CXX_FLAGS`（PS5 与 host 两处） | `os.hpp:42-45` 的 `#define RAR_SMP` 在 `#ifdef _WIN_ALL` 内；且 `unpack.cpp:7-9` 的 `#include "unpack50mt.cpp"` 就在 `#ifdef RAR_SMP` 里 ⇒ 不定义宏则整个 MT 解码器**根本不参与编译** |
+> | ~~把 `threadmisc.cpp` 加进 `UNRAR7_SRCS`~~ **← 这一条是错的，不要做** | — | `GetNumberOfThreads()` 确实定义在 `threadmisc.cpp:178`，但 `threadpool.cpp:5` **已经** `#include "threadmisc.cpp"` ⇒ 它**已经**被编进 `threadpool.o`（实测回执：`nm unrar7_threadpool.o` 能查到 `T GetNumberOfThreads` / `T GetNumberOfCPU`）。**再加进源列表 = 重符号链接失败。** 同理 `blake2sp.cpp` 也不必补 —— `blake2s.cpp:27` 已经 `#include "blake2sp.cpp"`。官方 POSIX makefile 只列 `threadpool.o`、不列 `threadmisc.o`/`blake2sp.o`，正是这个原因 |
+> | `-pthread`（编译+链接） | `Makefile` 的 PS5 link 行 | `threadpool.cpp` 的 `_UNIX` 路径用 pthread cond/mutex（**不用 `sem_t`**）。SDK 侧 `target/lib/libpthread.a` 在位、`target/include/pthread.h:198-237` 声明齐全 |
+>
+> **实测回执（宿主 MinGW，2026-09-23）**：用**与 PS5 完全相同的 50 个源文件**、只加 `-DRAR_SMP`，
+> 链接**一次通过**（`bench_mt.exe` 1,011,448 B）：`nm` 里 `Unpack5MT` 出现 1 次、`ThreadPool` 12 次；
+> 换成 `-DZIPSFX`（关掉 `RAR_SMP`）后 `Unpack5MT` 归 0。
+> ⇒ **接线 = 1 个编译开关 + 1 个链接开关，零源码改动、零源文件增删。**
+> **为什么不必改 `dll.cpp`**：`dll.cpp:6-12` 的 `DataSet` 成员顺序是 `CommandData Cmd; Archive Arc; CmdExtract Extract;`，
+> 构造时 `Cmd` 先完成 → `RAROptions::Init()`（`options.cpp:22-24`）在 `RAR_SMP` 下执行
+> `Threads=GetNumberOfThreads()` → 随后 `CmdExtract Extract(&Cmd)` 构造函数里
+> `Unp->SetThreads(Cmd->Threads)`（`extract.cpp:25-27`；上限 `Min(Threads,8)`，`unpack.cpp:65-71`）。
+> ⇒ **宏一开，RARDLL 路径自动拿到 MT**（这正是 CLI 与 DLL 共用的那条链路）。
+> 内存代价：MT 下 `UnpackThreadData` × `MaxUserThreads*2`（每个 `Decoded` 预分配 0x4100 项）
+> + `ReadBufMT` 4 MiB ≈ **15 MB 量级**，PS5 上可忽略。
+>
+> **⑤ 但是：新证据把矛头指向「写路径 / 存储」，而不是解码 —— 先别改代码。**
+> - 同形状**单线程**解码在 PC 上是 **386–505 MB/s（解压后口径）**；PS5 的 Zen 2 单核即使按 1/3 算也有 **~130 MB/s**。
+> - 真机只算 `.exfat` 一项就是 **19.49 GB ÷ 660 s = ≥29.5 MB/s 解压后**（且与 UI 的 10–40 吻合）。
+>   若 parts 1+2 的 8 GB 打包数据解开后还有十几 GB，那么全流水线就是 **30–70 MB/s 解压后**，
+>   比 CPU 能力低 **3–10×**。
+> - **两次独立操作撞同一个数**：上传（写 11.6 GB）实测 30–40 MB/s；解压（写 ≥19.5 GB）≈30 MB/s。
+>   ⇒ 优先怀疑 **PS5 这条写路径的上限就在 30–40 MB/s**（内置盘 / 外置盘 / 目标目录待确认）。
+> - ⇒ **决策顺序**：先做 `T_copy`（零改动、纯搬运）。纯搬运也 ~10 分钟 ⇒ 收工，MT 不必做
+>   （做了也会被 I/O 吃掉）；纯搬运明显快 ⇒ 再上 MT，那 2.4× 才是真金白银。
+>
+> 复现脚本：`.build/rabtest/ab_rar_mt.py`（第一版，形状错误，留作反例）、
+> `.build/rabtest/ab_rar_mt2.py`（代表性版）。夹具留在 `D:\_wfm_rabtest{,2}\`（≈1 GB）。
+
+> ### ⚠️ 2026-09-23 晚 更正：**「瓶颈不在解码」这个结论已撤回**
+>
+> 本节最初写它时只知道「18 GB / 11 分钟 / 1252 条目」，**不知道归档格式**。随后的补充
+> （**格式是 RAR**；包在 PC 上、经插件上传进 PS5；上传速度 30–40 MB/s）把两个前提都改了：
+>
+> **① 参照物错了 —— 这是方法错误，不是估计偏差。**
+> 原文拿「PS5 上解 **RAR** 的 28 MiB/s」去比「PC 上解 **7z** 的 427 MiB/s」。**不同格式、
+> 不同解码器、不同机器**：RAR 我们直接用 rarlab 的 UnRAR 库，7z 走自建 chain，两者毫无
+> 可比性。⇒ 原文「推论二（量级差 3–10×）」**不成立**，不能作为解码无罪的证据。
+> 「推论一（摆动）」此前已自行降级为弱证据（250 ms 采样噪声）。**两条都没了。**
+>
+> **② 查代码查出一个具体缺口：RAR 解码在我们这里是单线程的。**
+> `third_party/unrar7/os.hpp:43-45` 的 `#define RAR_SMP` 落在 `#ifdef _WIN_ALL` 分支**内**，
+> 所以 POSIX（PS5）构建**不定义** `RAR_SMP` —— 我们 Makefile 里 0 次出现；而官方 POSIX
+> makefile 第 11 行是 `DEFINES=... -DRAR_SMP`，**我们漏了这个开关**。后果：
+> - `unpack.cpp:185-198` 的 MT 分支整段不参与编译 ⇒ 永远走单线程 `Unpack5()`
+> - `unpack50mt.cpp`（`Unpack::Unpack5MT`）**不在我们的源列表里**；这是 rarlab 专门调过的
+>   多线程 RAR5 解压器（文件头注释：「0x400000 和 2 对 i9-12900K 最优」）
+> - `Unpack::SetThreads()` / `ThreadPool` 随之消失
+> - ⚠️ **我们在 ELF 上做的符号核查是无效的**：该 ELF 只有 `.dynsym`（513 项）、**没有
+>   `.symtab`**，任何内部符号都查不到（零命中是假象）。上面的结论来自 Makefile 与 `os.hpp`。
+>
+> **③ 新的首要假设：28 MiB/s ≈ 单线程 RAR5 解码的典型量级。**
+> RAR5 `-m5` 单线程在现代桌面 CPU 上约 40–80 MB/s 输出，PS5 的 Zen 2 单核更低。
+> 另一个角度：`18 GB ÷ 660 s = 27.9 MB/s` 是**解码输入**速率，而上传实测证明**写入端**
+> 至少能到 30–40 MB/s、**读取通常快于写入** ⇒ 「纯存储上限」解释不了这个数。
+>
+> **④ 附带作废一条**：「读粒度只有复制路径 1/32–1/64」是 **7z 的数字**（`SZ_IN_CHUNK`
+> 256 KiB），对 RAR 不适用 —— RAR 走 `od.ArcName` 按路径打开（`src/rar_extract.c:1059`），
+> 归档 I/O 由 UnRAR 自己的 `File` 类完成，我们的回调只收到**解压后的数据**，
+> **插不进 read-ahead**。⇒ 待办 #48 对 RAR 无效。
+>
+> **⑤ 归档真实参数（口径已闭合）** —— 两个来源合起来读得通：WinRAR 信息页（待解压版本 5.0、
+> 加密「缺少」、无恢复记录、压缩文件锁定「存在」、**字典 4 GB**、压缩率 19%、
+> **总大小 19,493,028,232 B = 18.15 GiB**、打包大小 3,831,296,089 B、**总文件 3**）＋ 文件列表
+> （三卷 `.part1/2/3.rar` = 4 GB + 4 GB + 3.6 GB ≈ 11.6 GB）。
+> **两者不矛盾**：信息页是把 **part3 当独立归档**打开的 —— part3 = 3.568 GiB，里面就是那 3 个条目
+> （一个 19.5 GB 的 `PPSA16608.exfat` ＋ 两个 KB 级小文件），上面的「第二次更正」块已用
+> `UnRAR lt` 直接读头证实；而三卷合计 ≈11.6 GB 才是整个包（另外还有 ~1250 个条目）。
+> ⚠️ 我先前按"两图互相矛盾、需用户确认"写的那一版**作废**：不是两个归档，是"单卷视图 vs 整包视图"。
+> 速度口径不受影响：**18.15 GiB ÷ 660 s = 29.5 MB/s（解压后字节）**；就那个大条目而言
+> 读侧只需 3.83 GB ÷ 660 s ≈ **5.8 MB/s** ⇒ **读侧不是瓶颈，29.5 MB/s 是解码+写盘的真实速率**。
+>
+> ## ⚑ 终局：RAR5 多线程**不做**（2026-09-23 18:15，用户决定）
+>
+> **#51 结案：保持单线程现状，生产代码不动、不刷机。**
+>
+> **为什么不做的依据是"判不了"，不是"没收益"** —— 收益本身已实测（块 ⑧：我们的引擎
+> 1.40–1.74×；rarlab CLI 在用户那种形状上 2.45×）。卡住的是**它能不能兑现**：
+> - `T_copy` 没做 ⇒ 无法区分「解码慢」与「写路径上限 ≈30 MB/s」。
+> - 而 MT **只并行解码**：worker 只跑 `UnpackDecodeThread`（`unpack50mt.cpp:190`），
+>   **写盘恒为主线程串行**（`UnpWriteBuf()` 仅由主线程调用 —— `unpack50mt.cpp:283/475/587`）。
+>   ⇒ 若墙在写路径，MT 的收益直接退化成 **1.0×**。
+> - 成本收益：判定要人上手测一次复制；上线要刷机 + 重跑 11 分钟。而收益可能为 0
+>   ⇒ **不做**。维持 11 分钟，把不确定性留在文档里，比赌一次更划算。
+>
+> **下面是已完成的技术取证，全部保留** —— 将来若要重开，它就是现成答案。
+> ⚠️ **重开的第一个动作是 `T_copy`，不是改构建**（判读见 `docs/REAL-CONSOLE-PROFILE.md` 第 1 步）。
+
+> **⑥ 开 RAR5 多线程只需一个编译开关**（把 #51 的工作量从"未知"降到"一行"）：
+> - `third_party/unrar7/unpack.cpp:7-9` **已经** `#include "unpack50mt.cpp"`；
+>   `threadpool.cpp:5` **已经** `#include "threadmisc.cpp"`。⇒ 官方 POSIX makefile 不列这两个
+>   `.o` 是**正常的**，**不需要新增源文件**（此前"官方 makefile 自相矛盾"的疑点已消除）。
+> - `raros.hpp:23-25`：非 Windows 一律 `#define _UNIX` ⇒ PS5 构建自动走 Unix 分支；
+>   `threadpool.cpp` 的 `_UNIX` 路径用 pthread cond/mutex，**不用 `sem_t`**。
+> - 线程数在 DLL 模式下**自动接上**：`dll.cpp` 每个归档持有一个 `CommandData`，
+>   构造函数 `cmddata.cpp:6-9 → Init() → RAROptions::Init()` →
+>   `options.cpp:22-24 Threads=GetNumberOfThreads()`；`extract.cpp:25-27` 再
+>   `Unp->SetThreads(Cmd->Threads)` → `unpack.cpp:65-71 MaxUserThreads=Min(Threads,8)`。
+>   ⇒ **不需要 CLI 开关、不需要 vendor 补丁**。
+> - ⇒ 改动 = 给 unrar 对象加 `-DRAR_SMP` + 链接 pthread。**PS5 侧唯一未验证点是
+>   `sysconf(_SC_NPROCESSORS_ONLN)` 是否返回真核数**（`threadmisc.cpp:111-124`）：
+>   SDK 的 `unistd.h:291` 定义了 `_SC_NPROCESSORS_ONLN 58`、`pthread_*` 在
+>   `target/include/pthread.h:198-237` 齐全；但若 `sysconf` 返回 1，**MT 会静默失效**。
+>   ⚠️ 注意 `threadmisc.cpp:116-124` 在 `_UNIX` 且未定义 `_SC_NPROCESSORS_ONLN` 时**没有
+>   return 语句**（UB）—— 真机上要能看到核数才算数。
+>
+> **⑦ MT 对固实归档同样生效，唯一例外是分片窗口**：`unpack.cpp:185-198` 在
+> `MaxUserThreads>1` 时调 `Unpack5MT(Solid)` —— 形参本身就带 `Solid`。会把它挡在外面的只有
+> `Fragmented`（`unpack.cpp:193`）：`unpack.cpp:130-145` 只在 4 GiB 窗口的**连续分配失败**
+> 且 `WinSize>=16 MiB` 且 64 位时才置位，而且分片窗口路径**本身更慢**。
+> 64 位下单次 malloc 失败通常是"量不够"而非"地址空间碎"，此时 `FragWindow.Init(同一大小)`
+> 也会失败 ⇒ **分片窗口属于罕见回退，概率低**。但它是可判读的：
+> **真机 A/B 若"开了 MT 却一点没变"，第一嫌疑就是它或 `sysconf`。**
+>
+> **⑧ 宿主 A/B 实测：MT 值 1.4–1.75×**（同一台机器、同一份二进制，只差一个 `-DZIPSFX`）。
+> 方法：MinGW 下 `_WIN32 ⇒ `_WIN_ALL` ⇒ `os.hpp:43` 自动定义 `RAR_SMP`，所以**我们过去所有
+> 宿主基准跑的都是多线程路径**；反过来单线程基线只能靠 `-DZIPSFX`（该宏在整棵源码树里
+> **只出现一次**，就是 `os.hpp:43`，干净可用）。回执：`nm` 查 `unpack.o`，base 的
+> `Unpack5MT` 符号数 = 0、mt = 1。样本：341 MiB 现实混合数据（127 MiB 真实二进制
+> + 158 MiB 短匹配文本 + 48 MiB 随机），RAR5 固实 `-m3`，压缩后 125–153 MB（比率 37–45%）：
+>
+> | 样本 | base（单线程） | mt | 加速 |
+> |---|---:|---:|---:|
+> | 固实 `-md1m` | 69.7 MiB/s | 97.3 MiB/s | **1.40×** |
+> | 固实 `-md256m` | 63.4 MiB/s | 110.6 MiB/s | **1.74×** |
+> | 分卷 `-md256m`（96+23 MiB） | 64.2 MiB/s | 100.8 MiB/s | **1.57×** |
+>
+> 两点附带信息：①**字典越大 MT 越划算** —— 单线程随字典从 1 MiB 涨到 256 MiB 掉到
+> 63–70 MiB/s（内存局部性），而 MT 稳定在 97–110；用户的包字典 4 GB，比这里最大的样本
+> 还大 16×，**方向上有理由期望 MT 收益不小于 1.6×**。②**跨机器外推不算结论**：
+> 宿主单线程 63–70 MiB/s vs PS5 的 28.1 MiB/s 是不同 CPU，只作量级参考。
+> ⇒ 若 PS5 上同样拿到 1.5–1.75×，11 分钟 → **约 6.3–7.3 分钟**。
+>
+> **⑧b 与上面「第二次更正」块的 2.45× 不矛盾 —— 差在样本形状，不在实现。**
+> 那块用 rarlab 自带 **UnRAR 7.23 CLI** 的 `-mt1` vs `-mt8`，夹具是 `-m1 -md4g`、**5.27:1**
+> 可压缩的 2 GB ／16 文件；我这边是 `-m3`、只有 **2.4:1** 的短匹配数据。方向一致：
+> **数据越可压缩（匹配越长）MT 越划算** —— 长匹配让一条符号吐出更多字节，串行 apply 被摊薄、
+> 并行解码占比上升，同时更容易越过 `unpack50mt.cpp:150-152` 的 `LargeBlockSize=0x20000` 退化阈值。
+> ⇒ **对用户这个包应以 ~2.4× 为预期**（它是 `-m1 -md4g`、5.09:1，正落在那个夹具的形状上），
+> 我测到的 1.4–1.75× 作为**更难数据下的下界**。绝对吞吐那 10× 的差距（386 MB/s vs 63–70 MiB/s）
+> **纯粹是夹具可压缩性差异，不能拿来比较两个实现**（这正是"基准代表性"那类错误）。
+> 综合估计：11 分钟 → **约 4.6 分钟**；悲观情形（1.5×）→ 6.3–7.3 分钟。
+>
+> **⑨ 样本代表性教训（第一版 A/B 是废的）**：初版样本是「同一个 60 KiB 区块重复 2400 次」，
+> 压缩到 0.2%、解码 **602 MiB/s** —— 长匹配让范围解码器的每条符号吐出上千字节，
+> 这个形状**真实归档里不存在**，而且它恰恰是 MT 最不擅长的形状（串行 apply 占主导）。
+> 后改用"真实二进制 + 短匹配文本 + 随机"混合，比率 37–45%，吞吐落到 63–110 MiB/s 的正常带。
+> 另：初版把 `-v96m` 的目标名写成 `vol.part1.rar`，rar 会翻倍成 `vol.part1.part1.rar`
+> （`tests/make-rar-fixtures.bat` 里已记过这个坑，我复现了一遍）。
+>
+> **⑩ 顺带查出两个真实缺陷/隐患**：
+> 1. **字典 > 4 GiB 的归档会直接失败** —— **已修，但修的是"说清楚"，不是"放行"**。
+>    机制：`extract.cpp:1748-1767 CheckWinLimit()` 在 `WinSize > Cmd->WinSizeLimit` 时调
+>    `uiDictLimit()`；DLL/silent 构建里 `uisilent.cpp:65-73` 只在
+>    `Cmd->Callback(UCM_LARGEDICT, …) == 1` 时才放行，否则 `DllError=ERAR_LARGE_DICT` 并跳过
+>    该文件。我们的回调原先**只处理 `UCM_PROCESSDATA`**，其余一律返回 0。默认
+>    `Cmd->WinSize`/`WinSizeLimit` = `0x2000000` / `0x100000000`（`options.cpp:12-13`）
+>    ⇒ 分界线正好是 4 GiB（比较是 `<=`）。
+>
+>    **⚠️ 三条订正（2026-09-23 18:40，把先前"1 行可修"的判断推翻）：**
+>    - **RAR5 根本到不了这里。** `arcread.cpp:871` 把 RAR5 字典读成
+>      `0x20000 << ((CompInfo>>10) & 0x0f)` —— **只有 4 bit** ⇒ 格式自身上限 = `0x20000<<15`
+>      = **正好 4 GiB**，与我们的 limit 相等。⇒ 任何 `-ma5`（含用户这个包）**永远不触发**。
+>      只有 **RAR7 头**（`UnpVer==1`，5 bit，上限 `UNPACK_MAX_DICT` = 64 GiB）才可能超。
+>    - **而 RAR7 造不出来。** 实测 `Rar.exe 7.23`：`-ma4` / `-ma6` / `-ma7` **全部 exit 7**
+>      （命令行错误），只有 `-ma5` 可用。⇒ 本机连验证样本都得手工合成。
+>    - **"放行"是陷阱不是修复。** 放行后 unrar 会去 `new` 一个**完整的字典窗口**；rarlab 自己的
+>      CLI 对这个样本的答复是：「8 GB 字典超过 4 GB 限制，而且需要大于 8 GB 内存来解压缩。
+>      使用 `-md8g` 或 `-mdx8g` 参数来解压缩。」PS5 只有 16 GB **共享**内存 ⇒ >4 GiB 字典在
+>      该设备上本就解不动；**中途被 OOM 杀掉（整个 payload/UI 一起没）比干净失败更糟**。
+>      ⇒ 决定：**保持拒绝**，与上游 CLI 默认一致。
+>
+>    **实际改动（在生产代码里，2026-09-23）：** 拒绝时不再把锅甩给条目。原先
+>    `ERAR_LARGE_DICT → ZIPX_ERR_LIMIT_FILE` → i18n `extract_entry_too_large`
+>    ⇒ 用户看到的是「**压缩包内单个文件过大: hello.txt**」，而那个条目只有 7 KB —— 完全错。
+>    现在新增 `ZIPX_ERR_LIMIT_DICT`（`src/zip_extract.h`）+ `extract_dict_too_large`
+>    （中/英），并在 `rar_data_cb` 里从 `UCM_LARGEDICT` 的 `p1/p2` 取回真实数字，
+>    报成「需要 8192 MiB（上限 4096 MiB）」。回归用例 `tests/test_rar_extract.c:test_dict_limit`
+>    + 固定样本 `tests/fixtures/dict-8g.rar`（合成器 **`tests/make_fixtures.py:bigdict()`**，
+>    纯 Python 手写最小合法 RAR5 归档、不依赖任何压缩器；说明见该函数 docstring）。
+>    ⚠️ **样本必须由 `make_fixtures.py` 生成** —— `fresh()` 会 `shutil.rmtree()` 整个
+>    `tests/fixtures/`，提交进去的二进制会被抹掉，所以不能单独放一个生成脚本。
+> 2. **归档里的目录条目 +「覆盖」策略 = 第二次解压到同一目录必失败**。
+>    `src/rar_extract.c:884-892`：目标已存在且是目录、而归档条目也是目录时，
+>    只有 `ZIPX_CONFLICT_MERGE` 能过；`OVERWRITE` 报 `ZIPX_ERR_CONFLICT`
+>    （状态串是 "target already exists"，`detail` 才是 "directory already exists"）。
+>    `zip_extract.c:1123` / `sevenz_extract.c:1526` 同构。⇒ 用户对含目录的包用「覆盖」
+>    解两次，第二次会失败。**这条是我在搭 A/B 时被挡了才知道的**，需要确认是否设计意图。
+>
+> 下文数据与推论**保留原文**（它们是当时判断的依据），但**结论以本块为准**。
+
+### 数据
+用户在真机上解一个 **18 GB 的包**，UI 上报的解压速度在 **10–40 MB/s** 之间摆动；
+随后补上两个关键数字：**总耗时 11 分钟（660 s）**、**条目数 1252**（平均 14.7 MB/条目）；
+再确认 **18 GB 是压缩包自身的大小**（解压后多大未知）。
+
+⇒ **平均吞吐 ≥ 28 MiB/s**（18 GB = 18 432 MiB ÷ 660 s；解压后更大则更高，故为下限）。
+**这个数字才是基线**，UI 上那个 10–40 的区间只是瞬时值。
+
+「18 GB = 压缩包大小」顺带给出一个**与解码无关的硬上界**：源盘必须在 660 s 内交出
+18 GB 归档数据 ⇒ 整条流水线的平均吞吐上界就 ≈ 28 MiB/s。**无论解码多快，源盘只有这个交付速度。**
+这也是为什么第 1 步的 `T_copy`（同一个 18 GB 文件的纯搬运）能与 660 s 直接比大小。
+
+顺带排除一项：**per-entry（小文件）开销不是主因** —— 1252 个文件、平均 14.7 MB，不是
+"几万个小文件"那种形态，建文件 + rename 分摊到 0.53 s/文件里微乎其微。
+
+口径先确认（不是猜）：进度条的"字节"是**解压后的字节**——
+`src/zip_extract.c:651-678` 把 `bytes_total` 累加自 `info->uncompressed_size`；
+`:875` 的 `mz_zip_entry_read()` 返回解压字节，`:900/910` 用它累加 `bytes_done`。
+所以 10–40 MB/s 是**吐出数据的速度**，正是用户关心的那个口径。
+
+### 推论一：摆动说明"负载不恒定"，但它是弱证据
+solid 块（同一字典、同一条码流）的解码速率**几乎是恒定的**。要出现 4× 的摆动，
+更像是 I/O 侧在变：源盘读取、目标盘写入、逐条目同步开销、或存储设备自身在忙。
+
+但这条**不能单独定案** —— 那个 MB/s 是 250 ms 窗口 + 1 MiB 上报阈值的**瞬时值**
+（`src/zip_extract.c:123`、`src/task.c:202-206`），写缓冲突发本身就能在窗口里造成大幅跳动。
+它能说的只有"负载不恒定"，不构成"解码无罪"的证明。有解释力的是推论二（量级）和推论三（粒度）。
+
+### 推论二：量级上差 3–10×，解码没有解释力
+| | 吞吐 |
+|---|---:|
+| PC / WSL，329 MiB 混合数据，8 线程（本仓实测） | **427 MiB/s** |
+| PS5 单线程解码的乐观上界（按核数×频率外推，**未实测**） | ~100 MB/s |
+| **真机实测（18 GB 包，端到端）** | **10–40 MB/s** |
+
+18 GB @ 10–40 MB/s = **7.7 ~ 31 分钟**；同样数据在 PC 上纯解码约 43 s。
+⇒ 解码最多占 10–25%，**很可能远低于此**。
+
+### 推论三：三个引擎的读请求粒度都只有复制路径的 1/32–1/64
+粒度审计（已核对源码）：
+
+| 路径 | 源侧读粒度 | 目标侧写粒度 |
+|---|---|---|
+| 复制（`copy_file_pipeline`，≥256 MiB） | **8 MiB** × 3 slot，4096 对齐，独立读线程 | 8 MiB |
+| 7z | chain `SZ_IN_CHUNK = 256 KiB`（`src/sevenz_chain.c:87`）；MT 路径 `inBufSize_MT = 1 MiB` | `SZ_OUT_CHUNK = 64 KiB`（`:94`） |
+| ZIP | `ZIPX_IO_BUFFER = 128 KiB`（`src/zip_extract.c:32`） | 128 KiB |
+| RAR | UnRAR `File::CopyBufferSize() = 4 MiB`（`third_party/unrar7/file.hpp:148-153`） | 4 MiB |
+
+都不是 4 KB 那种「小读」灾难，但**都比复制小 32–64 倍**。在延迟主导的设备上，
+吞吐 ≈ 单次请求大小 ÷ 每次请求的等效延迟：
+
+```
+256 KiB / 10 ms =  25 MB/s    ← 正好落在实测 10–40 MB/s 的中间
+  8 MiB / 10 ms = 800 MB/s    ← 复制路径不会撞这个上限
+```
+
+若源与目标在**同一块盘**（例如外置 USB HDD 上解压到同一块盘），读流与写流并存，
+磁头来回跑、read-ahead 被写回刷打断 → 每次请求退化成一次寻道，上面这个算术即成立。
+**这是目前唯一可疑的代码级病因**，而它的改动面极小：所有 7z 的读都只经过
+`src/sevenz_volstream.c` 的 `vol_read()` 一个函数（ZIP/RAR 同理在 `src/zipx_volstream.c`）。
+
+### ~~因此：剩余解码优化项全部搁置~~（**已撤回，见文首更正块**）
+原文在这一段把 CRC 硬件化、MT 扩到 BCJ2 / 多 folder、ZIP inflate 换 libdeflate、AES-NI 全部判为
+「在 10–40 MB/s 的现实面前没有意义」。**建立在「解码不是瓶颈」之上，而那个前提已撤回。**
+
+更正后的分层判断（按真实工作负载 **RAR** 重排）：
+
+| 项 | 更正后的判断 |
+|---|---|
+| **UnRAR RAR5 多线程解压（`RAR_SMP`）** | **❌ 不做（2026-09-23 用户决定，见文首「终局」块）**。收益已实测（rarlab CLI `-mt1` vs `-mt8` **2.45×**，见「第二次更正」块 ③；我们引擎在更难数据上 1.40–1.74×，块 ⑧b），接线也只是 **1 个编译开关 + 1 个链接开关、零源码改动**（块 ④）—— **但 `T_copy` 没做，无法排除「写路径上限 30–40 MB/s」**；MT 只并行解码、写盘恒为主线程串行（`unpack50mt.cpp:190` / `:283,475,587`）⇒ 收益可能是 1.0×。刷机 + 重跑 11 分钟的成本压在不确定收益上 ⇒ 搁置 |
+| CRC 硬件化（4–5%） | 仅对 7z / ZIP 有意义；**对 RAR 完全无关**（CRC 由 UnRAR 自己算） |
+| MT 扩到 BCJ2 / 多 folder | 仅 7z；RAR 工作负载下无意义 |
+| ZIP inflate 换 libdeflate / AES-NI | 同上，与 RAR 无关 |
+| 读粒度 / read-ahead（#48） | **对 RAR 无效**（UnRAR 按路径自读，回调只收解压后数据）；只对 7z/ZIP 有意义 |
+
+「先 profile 再排序」这个结论**仍然成立**，但目标从「查清为什么只有 10–40 MB/s」变成
+**「先把 RAR 单线程这条确认掉 / 排除掉」** —— 见 `docs/REAL-CONSOLE-PROFILE.md`。
+
+### 尚未定案的部分
+- ~~**归档格式未知**~~ → **已确认（2026-09-23）：格式是 RAR**，包原本在 PC 上、经插件上传进
+  PS5（上传速度 30–40 MB/s）。⇒ 解码用的是 rarlab 的 UnRAR 库本身，**我们自己的代码在 RAR
+  解码路径上只剩一层很薄的 facade**；「我们的解码器慢」这个方向基本不成立，
+  但「**我们的构建没打开 UnRAR 的多线程**」成立（见文首更正块 ②）。
+  仍未确认：**RAR4 还是 RAR5**（`Unpack5MT` 只对 RAR5/7.0 生效）、是否固实、是否加密、
+  **解压后多大**（决定输出吞吐）。
+- ~~**18 GB 是压缩后还是解压后**~~ → **已确认（2026-09-23）：18 GB 是压缩包自身的大小**。
+  于是有了一个**不需要知道解压后大小的硬上界**：源盘要在 660 s 内交出 18 GB 归档数据
+  ⇒ 整条流水线平均吞吐上界 ≈ **28 MiB/s**；`T_copy` 与 660 s 可直接比大小。
+- **存储未知**：包在哪个设备上（内置 SSD / 外置 USB / 同盘还是异盘）、输出写到哪个设备。
+- ~~**下一步（决定性、零改动）**~~ → **未执行（2026-09-23 用户决定搁置，见文首「终局」块）**：
+  用插件自己的**复制**功能把那个包搬到解压输出所在的那块盘上，记耗时。复制的
+  `copy_file_pipeline` 是 8 MiB × 3 slot 的双缓冲搬运，⇒ 它就是"同一台机器、同一对设备、
+  只把解压换掉"的对照。**将来重开时这是第一个动作**，判读见 `docs/REAL-CONSOLE-PROFILE.md` 第 1 步。
+
+> 一句话：**"我们比 7-Zip 慢 1.59×" 这个议题在真机上不成立** —— 两边都被同一个 I/O
+> 上限压着，谁先撞墙取决于存储，而不是解码器。真机目标从"提速解码"改成"查清 28 MiB/s"。
+> ~~目前指向一个具体、可改的位置：**读请求粒度只有复制路径的 1/32–1/64**（推论三），
+> 而全部 7z 读都经过 `vol_read()` 一个函数。**先用复制做基线验证它，再决定改不改。**~~
+> → **推论三对 RAR 不适用**（那是 7z 的 256 KiB 数字；UnRAR 按路径自读，见文首更正块 ④）。
+> 更正后：真机工作负载是 RAR，而**我们的 RAR 解码是单线程的**（`RAR_SMP` 未定义 ⇒
+> `unpack50mt.cpp` 不参与编译）—— 这是一项有据可查、且直接针对真实负载的改进点，
+> 在真实形状上**已实测 2.4×**。
+> ~~**但优先级已被文首二次更正块 ⑤ 改写**：先做零改动的 `T_copy`，确认墙在解码还是在写路径。~~
+> → **闭环（2026-09-23 18:15）：`T_copy` 没做，用户决定不做了** ⇒ 见文首「终局」块。
+> 单线程现状保留，此项转入"已评估、搁置（重开先测 `T_copy`）"。
+
+---
+
+## 七、复现
+
+```bash
+export PATH="/c/mingw64/bin:/c/Users/songl/.workbuddy/binaries/PortableGit/versions/1.2.0/mingw64/bin:/c/Users/songl/.workbuddy/binaries/python/versions/3.13.12:/usr/bin:/bin:/c/Windows/System32:/c/Windows"
+cd "/c/Users/songl/Desktop/Web File Manager/ps5-web-file-manager"
+
+# 先各跑一次，生成引擎对象
+/usr/bin/bash tests/run-sevenz-tests.sh
+/usr/bin/bash tests/run-tests.sh --rebuild
+
+# Windows 基准（我们的引擎 vs 7za.exe）
+python tests/bench_driver.py --big --runs 3
+
+# 同环境对比（WSL）：官方 Linux 7-Zip / 我们的引擎 / 编译选项 / profile
+wsl.exe -d Ubuntu-22.04 -- bash < .build/bench/wsl-perf.sh
+wsl.exe -d Ubuntu-22.04 -- bash < .build/bench/wsl-ours.sh
+wsl.exe -d Ubuntu-22.04 -- bash < .build/bench/wsl-flags.sh
+wsl.exe -d Ubuntu-22.04 -- bash < .build/bench/wsl-prof.sh
+```
+
+## 附：测量方法备忘
+
+这个沙箱里 bash 计时不可用，三个坑都先给出过错误数字：
+
+- 每次 `date` 要 ~350 ms → `t0/t1` 对给 ~600 ms 的测量注入 700 ms 误差
+- `time` 的 user/sys 看不到 native 子进程（解 82 MiB 报 `user 0.031s`）
+- 反复跑堆积 2.7 GB 输出目录 → 测出过"内部时间 > 外部时间"
+
+正确做法：Python 驱动（单次 spawn + 单调时钟）+ 候选程序自带内部计时 + 显式扣除 spawn tax（~190–240 ms）+ best of N + 每次跑前清输出目录。
@@ -0,0 +1,143 @@
+# PS5 网页文件管理器 v1.9.2（自编译版）发布 + 与上游原版对比 + 使用简介
+
+> 这是我自己维护的一个分支版本，基于 owendswang 的 `ps5-web-file-manager` 二次开发。本文讲三件事：**它和上游原版差在哪、我这个版本强在哪、怎么用**。
+
+---
+
+## 一、它是什么
+
+一个在已越狱 PS5 上跑的 HTTP 文件管理器（单文件 ELF 载荷）。局域网内任意浏览器（含 PS5 自带浏览器）打开 `http://<PS5的IP>:8888/` 就能管理外接 USB 和内置存储：浏览、改权限、上传、下载、原地编辑文本、装/预览 PKG、看图，以及**解压 ZIP / RAR / 7z**。
+
+- 版本：**v1.9.2**
+- 标题 ID：`FMGR88888`
+- 许可证：GPLv3+
+- 目标平台：`x86_64-sie-ps5`（Zen 2，不是 ARM）
+
+> **关于版本号**：v1.9.2 与 v1.9.1 功能完全相同，只更新了内嵌版本号。原先的 `v1.9.1` tag 打在了产出发布二进制的提交**之前 4 个提交**，导致"tag 对应的源码"重建不出发布的那份 ELF；v1.9.2 重新从正确提交上打，使 **tag = 源码 = 二进制**。
+
+---
+
+## 二、和上游原版（owendswang v1.8）对比
+
+先说结论：**不是同一条路线，各有胜负手。**
+
+| 维度 | 上游 owendswang v1.8 | 我的 v1.9.2 |
+|---|---|---|
+| 一句话定位 | 把 7-Zip 本体做成**外部 helper 进程**，靠 IPC 调用 | **自研 / vendor 解码库，全部内嵌同一进程** |
+| 支持的压缩格式 | **30 种**（zip/7z/rar/tar/gz/xz/zst/bz2/cab/arj…） | **3 种**：ZIP / RAR / 7z |
+| 部署方式 | **两个文件**，helper 必须放 `/data/wfm/` 指定路径 | **单个 ELF，零外部依赖** |
+| 载荷体积 | 主程序 + 7-Zip 本体（两份） | **850 KiB 单文件**（含 ZIP/RAR/7z 三个解码引擎） |
+| 防压缩炸弹（zip bomb） | ❌ 无 | ✅ 压缩比上限 + 1 GiB 下限豁免 |
+| 磁盘写满保护 | ❌ 无 | ✅ 解压前按实际剩余空间 `statvfs` 预检 |
+| 路径穿越防护 | ❌ 无（交给 7-Zip） | ✅ 有专项测试 |
+| 解压中断留残留 | ⚠️ 可能留半成品 | ✅ staging 隔离，失败即清 |
+| 解压任务跨重启恢复 | ✅ helper 独立进程，重启不丢 | ❌ 暂无 |
+| 内存隔离 | ✅ 独立进程 | ❌ 与主程序共享地址空间 |
+| 错误信息详细度 | 中等 | ✅ 含条目名 / errno / 字节数 |
+| 解压核心正确性 | 7-Zip 本体（20 年验证） | 自研 7z 链 + 成熟 vendor 库 |
+
+### 上游原版强在哪
+- **格式多**：30 种，常见游戏包/备份/Mod 里 `.tar.gz`、`.xz`、`.zst`、`.bz2` 都能直接解。
+- **任务恢复**：helper 是独立进程，主程序被系统杀掉或浏览器重开，大包解压不丢。
+- **内存隔离**：解压峰值不影响主文件服务。
+
+### 我的版本强在哪
+- **安全护栏齐全**：压缩炸弹、写满磁盘、路径穿越、中断残留——这四项上游一个都没有，而我这边都有实现和测试（测试矩阵 163 项检查，0 失败）。说白了，**一个恶意压缩包不会把你的内置存储搞崩**。
+- **单文件部署**：丢一个 ELF 就行，不用记第二个文件该放哪；helper 丢了功能全废的事在我这不存在。
+- **7z 引擎是硬啃出来的**：上游靠 7-Zip 本体"白嫖"，我这边是自己解析 7z folder + 拉式 codec 链，原生支持 BCJ2 反汇编后处理和多 coder 组合，还顺手做了多线程 LZMA2 解码（约 1.37×）和汇编 LZMA 解码器（约 1.26×）。
+- **RAR 用官方 UnRAR 7.20.1**：能解 WinRAR 6.x/7.x 写的 RAR5「v6」归档和多卷 RAR——上游原版的旧引擎在这类文件上会报"归档损坏"。
+
+### 我不回避的短板
+- **格式覆盖只有 3 种**，这是最明显的弱项。`.tar.gz`、`.xz`、`.zst`、`.bz2` 你现在还得在 PC 上先解开。这是我接下来增量要补的方向（tar+zlib 已有、xz/lzma 复用 LZMA SDK、bz2/zst 可 vendor 单文件解码器），但**不打算照抄上游的 helper 路线**——那样会丢掉上面那些安全护栏和单文件部署优势。
+- **任务跨重启恢复**和**内存隔离**暂时没有（和"单进程内嵌"的架构取舍有关）。
+
+> 一句话：**上游赢在"格式广度 + 进程架构"，我赢在"安全 + 部署 + 错误质量"。**
+
+---
+
+## 三、v1.9.2 / v1.9.1 我做了哪些具体改进
+
+- **7z 解压引擎**：自研解码子集 + 拉式 codec 链（`sevenz_chain.c`），支持 LZMA2 / LZMA / BCJ2，覆盖 SDK `SzArEx` 装不下的 5-coder 文件夹。
+- **分卷（多卷）支持**：三种格式都支持分卷，但命名约定不同（引擎按文件名自动识别，打开首个分卷即可）：
+  - **ZIP 分卷**：① 经典多磁盘 `name.z01 … name.zNN … name.zip`（索引目录固定在最后一个 `.zip`）；② 7-Zip 字节分割 `name.zip.001 / .002 / …`；③ WinRAR 卷 `name.part1.zip … name.partN.zip`。最多 512 卷。
+  - **7z 分卷**：7-Zip 字节分割 `name.7z.001 / .002 / …`，各分卷需等大，打开首个即可。最多 512 卷。
+  - **RAR 分卷**：标准多卷 `name.part1.rar / .part2.rar / …`（unrar 自动按名合并）。**注意**：用 7-Zip 切出来的 `name.rar.001` 这种命名**暂不支持**，引擎会提示你先把分卷改名成 `.partN.rar` 再解。
+- **性能三项**（纯解码提速，不影响功能）：
+  - 汇编 LZMA 解码器 ≈ **1.26×**
+  - 纯 LZMA2 多线程解码（8 线程）≈ **1.37×**
+  - 移除 ZIP 逐条目 fsync，减少写盘开销
+- **RAR 升级到官方 UnRAR 7.20.1**：RAR5「v6」+ 多卷可用（v1.8 时代在 WinRAR 6/7 文件上报"归档损坏"的问题已消失）。
+- **载荷瘦了 15.8%**（1,034,328 → 870,488 字节）：链接期去掉了 libc++abi 里一段**永远不会执行**的 C++ 名字还原器（只服务于"未捕获异常打印类型名"这条路径），再加上相同机器码折叠。**不损失任何功能，也不影响解压速度**。
+- **上传更顺手**：点上传按钮直接选文件或文件夹（不再弹二级菜单）；支持**把文件/文件夹直接拖到页面上**上传。
+- **中英双语界面** + 项目主页右上角可切换语言说明。
+
+### 已知缺口（诚实列出）
+
+> 本节描述的是 **v1.9.2 发布时**的状态。此后有两条已在工作树中补齐、尚未发版：
+> 加密 ZIP/RAR 与 7z `-mhe=on` 加密头。详见 README「未发布内容」与
+> `HANDOVER.md` §十一 / §十二。
+
+- 带密码的 ZIP / RAR / 7z：**拒绝解压**（引擎有解密能力，但密码输入 UI/API 还没接，临时先挡掉）。
+- 7z `-mhe=on` **加密头**：暂不支持（需要自研头解析器）。这是 7z 侧唯一已知缺口。
+
+---
+
+## 四、使用简介（三步上手）
+
+### 1. 把 ELF 发到 PS5
+PS5 上先运行一个 ELF 加载器（端口 `9021` 常见），然后在 PC 上：
+
+```sh
+# 把 PS5_IP 换成你主机实际 IP
+nc -q0 <PS5的IP> 9021 < web-file-mgr-v1.9.2.elf
+```
+
+PS5 屏幕会弹通知，显示实际监听端口（默认 `8888`）。首次运行还会在主屏 Media 分类装一个「PS5 Web File Manager」快捷方式。
+
+### 2. 浏览器打开
+同一局域网下，任意设备浏览器打开：
+
+```
+http://<PS5的IP>:8888/
+```
+
+PS5 自带浏览器也能开。
+
+### 3. 日常操作
+- **浏览/管理**：列文件、排序、改权限、复制/移动/重命名/删除、原地编辑文本（≤1 MiB 的 txt/json/js/c/h…）。
+- **上传下载**：单文件或文件夹树上传（也可直接拖拽到页面）；文件夹/多选以 `.tar` 流式下载。
+- **解压**：在文件列表里点 ZIP / RAR / 7z 的「解压」按钮即可。大档案（>480 GiB）会弹确认提示，确认后用更宽松的限额解压。
+- **冲突策略**：同名文件默认拒绝覆盖；需要时可选覆盖或合并。
+
+---
+
+## 五、下载与校验
+
+> 请在 GitHub Release 页面下载：`https://github.com/lishersong/ps5-web-file-manager/releases/tag/v1.9.2`
+
+发布文件：`web-file-mgr-v1.9.2.elf`
+
+| 项目 | 值 |
+|---|---|
+| 大小 | 870,488 字节（约 850 KiB） |
+| sha256 | `177e90fecf93a0251e83f67884fba4551051be248330b0d70fda8ea732f88e84` |
+| 文件类型 | ELF 64-bit LSB，x86-64（e_machine `0x003e`，即 PS5 目标三元组） |
+
+下载后建议先核对 sha256 再发到主机：
+
+```sh
+sha256sum web-file-mgr-v1.9.2.elf
+# 应等于 177e90fecf93a0251e83f67884fba4551051be248330b0d70fda8ea732f88e84
+```
+
+> 本次构建是**可复现**的：同一份源码树连编两次 sha256 完全相同。所以这个哈希可以放心当交付指纹用。
+
+---
+
+## 六、免责声明
+
+非官方自制软件，仅在已越狱 PS5 上运行。使用风险自负——作者不对损坏、数据丢失、账号处罚或保修影响负责。请勿再分发 Sony 专有内容。依 GPLv3+，本分支修改后的源码已公开在上面的仓库。
+
+---
+
+*想继续补 `.tar.gz` / `.xz` 等格式、或接上密码解压 UI 的，欢迎在仓库提 issue。*
@@ -0,0 +1,285 @@
+# 真机验证清单：解压速度（10–40 MB/s 到底卡在哪）
+
+> ### ⚑ 本清单的终局：停在第 1 步之前（2026-09-23 18:15，用户决定）
+>
+> **`T_copy` 没做；RAR 多线程（#51）不做；生产代码一行不动、不刷机 —— 11 分钟维持现状。**
+>
+> 理由：MT 的收益在 PC 上**已实测**（下面「第三件」2.45×／我们引擎 1.40–1.74×），
+> 但**能不能兑现，刚好吊在本文档第 1 步那个实验上** —— 而 MT 只并行解码、写盘恒为主线程
+> 串行（`unpack50mt.cpp` 的 `UnpWriteBuf()` 只在主线程调，见 §六 终局块），
+> 所以那个实验的结果很可能是「收工」。赌一次的成本（改构建 + 刷机 + 重跑 11 分钟 + 真机验证）
+> 压在不确定收益上 ⇒ **不做**。
+>
+> **下面全部内容保留**，作为「将来重开时的现成答案」。
+> ⚠️ 重开的**第一个动作是第 1 步的 `T_copy`，不是改构建**。
+
+> ### ⚠️⚠️ 2026-09-23 深夜（第二次更正）：**归档参数已拿到、MT 已实测、最大嫌疑已排除**
+>
+> **口径修正**：包不是 18 GB，是 **3 个分卷 ≈ 11.6 GB**（4 GB + 4 GB + 3.6 GB）。
+> **下文凡写「18 GB」处，一律按「≈11.6 GB」读**；核心算术已在本块重算。
+>
+> **① 真实归档参数（从 part3 的头实测，该文件随后被清理）**
+> RAR **5**、**卷 3/3**、**锁定**、**不是固实**（直解主头 `archive flags=0x0013`，`MHFL_SOLID=0x0004` 未置位）、
+> 压缩参数 **`-m1 -md=4g`**（**最快档 + 4 GiB 字典**）。关键条目 `PPSA16608.exfat`
+> **19.49 GB → 打包 3.83 GB（ratio 5.09）**，并**整段都在 part3 内**。
+> 详见 `docs/EXTRACTION-PERF.md` §六 第二次更正块。
+>
+> **② 最大嫌疑（scan 白解码一遍 = 2×）已排除。** 那建立在「固实 skip 必须解码」
+> （`dll.cpp:341` 只在 `!Arc.Solid` 走廉价 `SeekToNext()`）之上；**本档非固实** ⇒ 我们的 scan 不解码。
+>
+> **③ MT 收益已实测 = ~2.4×**（真实形状夹具：`-m1 -md4g`、5:1 可压缩、2 GB、`-mt1` 386→`-mt8` 946 MB/s 解压后）。
+> 接线只需 **1 个编译开关 + 1 个链接开关**（`-DRAR_SMP` + `-lpthread`），**不必改 vendored 源码、
+> 不必增删源文件** —— 早期版本写的「还要加 `threadmisc.cpp`」**是错的**：`threadpool.cpp:5` 已经
+> `#include "threadmisc.cpp"`（实测 `nm unrar7_threadpool.o` 里有 `T GetNumberOfThreads`），再加会重符号。
+>
+> **④ 但矛头现在指向「PS5 写路径」——所以本清单第 1 件事（`T_copy`）不变，而且更该先做。**
+> - 单线程解码在 PC 上同形状就是 **386–505 MB/s**；PS5 单核按 1/3 算也 ~130 MB/s。
+> - 真机：**只算 `.exfat` 一项**就是 19.49 GB ÷ 660 s = **≥29.5 MB/s 解压后**。
+> - **两次独立操作撞同一个数**：上传（写 11.6 GB）**30–40 MB/s** ＝ 解压（写 ≥19.5 GB）≈30 MB/s。
+> ⇒ 优先怀疑这条写路径的上限就是 **30–40 MB/s**。**若 `T_copy` 也 ~10 分钟 ⇒ 收工，MT 不做**
+> （做了会被 I/O 吃掉）；**若 `T_copy` 明显快 ⇒ 立刻上 MT，那 2.4× 是真的**。
+>
+> 下面是原始判断（保留），**优先级以本块为准**。
+
+> ### ⚠️ 2026-09-23 晚 更正 —— 本文档的起点判断已反转。
+> 本文最初的前提是「已排除解码器」，那建立在两条现已作废的论证上：
+> ① 拿 **PS5 上解 RAR** 的 28 MiB/s 去比 **PC 上解 7z** 的 427 MiB/s（不同格式/解码器/机器）；
+> ② UI 速度的 4× 摆动（已自行降级为 250 ms 采样噪声的弱证据）。
+>
+> **新增的三条事实把方向翻了过来**：格式是 **RAR**（解码就是 rarlab 的 UnRAR 库本身）；
+> 包原本在 PC 上、经插件上传进 PS5；上传实测 30–40 MB/s。随后查代码发现：
+> **我们的 POSIX 构建没有定义 `RAR_SMP`**（`os.hpp:43-45` 的 `#define RAR_SMP` 在
+> `#ifdef _WIN_ALL` 内；官方 POSIX makefile 第 11 行是 `DEFINES=... -DRAR_SMP`），
+> 后果是 `unpack50mt.cpp`（`Unpack::Unpack5MT`，多线程 RAR5 解压器）**根本没编进来**，
+> `unpack.cpp` 的 MT 分支整段不参与编译 ⇒ **RAR 解码在 PS5 上是单线程的**。
+>
+> ⇒ **新的首要假设：28 MiB/s ≈ 单线程 RAR5 解码的正常量级。**
+> 详细更正与代码行号见 `docs/EXTRACTION-PERF.md` §六 文首更正块。
+> **下文按「实测 → 判读」仍有效；但第 2 步（读粒度）对 RAR 不适用**，已加注。
+
+## 已到手的数据（2026-09-23 真机）
+
+| 项 | 值 |
+|---|---|
+| 包大小 | **≈11.6 GB 压缩包**（4 GB + 4 GB + 3.6 GB 三个分卷；✅ 2026-09-23 晚更正，原写 18 GB 有误） |
+| 条目数 | 1252 |
+| 总耗时 | **11 分钟 = 660 s**（UI 显示） |
+| **UI 速度口径** | **解压后字节**（`src/rar_extract.c:766` 在 `UCM_PROCESSDATA` 里 `bytes_done += p2`）⇒ 10–40 MB/s 是「吐出数据的速度」 |
+| 平均吞吐（输入侧） | **≥ 17.6 MB/s 打包字节**（11.6 GB ÷ 660 s） |
+| 平均吞吐（输出侧） | **≥ 29.5 MB/s 解压后**——只算 `PPSA16608.exfat` 一项就是 19.49 GB ÷ 660 s |
+| 格式 | **RAR 5** ✅（头 8 字节 `52 61 72 21 1A 07 01 00`） |
+| 固实 | **不是固实** ✅（主头 `MHFL_SOLID=0x0004` 未置位） |
+| 压缩参数 | **`-m1 -md=4g`**（最快档 + 4 GiB 字典）✅ |
+| 关键条目 | `PPSA16608.exfat` 19 493 027 840 B → 打包 3 831 295 727 B（ratio **5.09**），整段在 part3 内 |
+| 来源 | 包原本在 **PC 上**，**经插件本身上传**进 PS5，上传速度 **30–40 MB/s**（写 11.6 GB） |
+| 源 / 目标设备 | **待确认** ⬅ **现在最关键的一条**（内置 SSD / 外置 USB / 是否同盘） |
+| 解压后总大小 | **待确认** ⬅ 决定输出侧吞吐的确切值（≥19.49 GB 已知） |
+
+「18 GB 是压缩包大小」这条把口径钉住了，而且给出一个**不需要知道解压后大小的硬上界**：
+
+```
+源盘必须在 660 s 内交出 18 GB 的归档数据
+⇒ 整条流水线的平均吞吐上界 = 18 GB ÷ 660 s ≈ 28 MiB/s
+```
+
+解压后有多大都不影响这个上界 —— **无论解码多快，源盘就只有这个交付速度**。
+所以第 1 步的 `T_copy` 和它**可以直接比大小**（同一个 18 GB 文件、同一对设备）。
+
+两个立刻可用的推论：
+
+1. **per-entry（小文件）开销解释不了它。** 1252 个文件、平均 14.7 MB，不是「几万个小文件」那种
+   形态；建文件 + rename 这两种 per-entry 成本加起来分摊到 0.53 s/文件 里微乎其微。
+2. **UI 上那个 10–40 MB/s 是瞬时值，不是平均值。** 进度回调只在累计 ≥ 1 MiB 时上报
+   （`src/zip_extract.c:123`），`src/task.c:202-206` 每 **250 ms** 采一次样。250 ms 窗口 +
+   写缓冲突发会让速度在「忽停忽走」之间跳，**波动里含相当比例的采样噪声**。
+   ⇒ 只有「解压后字节 ÷ 总耗时」可信；那 4× 的摆动只能说明「不是恒定负载」，不能单独定案。
+
+---
+
+## ★ 你要在真机上做的事（就两件）
+
+### 第一件：补一个数字 `T_copy`（3 分钟操作 + 一次等待）
+
+1. 把那个 **18 GB 的包**，用插件自己的**复制**功能，复制到**解压时输出所在的那块盘**
+2. **记下耗时**（UI 上有）
+3. 顺便记下：这个包**原本在哪**（内置 SSD / 外置 USB），**解压输出到哪**（同盘还是另一块）
+
+判读（就在 `T_copy` 与 **660 s** 之间比）：
+
+| `T_copy` | 结论 | 我接下来做什么 |
+|---|---|---|
+| **≥ 10 分钟** | 存储物理极限，与代码无关 | **收工**，解码优化全部关闭（#48 取消） |
+| **1–2 分钟** | 解压比同一对设备上的纯搬运慢 5–10× ⇒ **代码里有真问题** | 做 #48：`vol_read()` 加 read-ahead |
+| 介于中间 | 混合 | 按字节数扣掉 I/O 分量，差值才是能改的部分 |
+
+> 为什么这个数字这么关键：它是**同一台机器、同一对设备、同一份代码**，只把「解压」换成
+> 「纯搬运」。不需要造新包、不需要第二块盘、不需要任何假设。上面那 4 个对照实验（第 3 步）
+> 只在它的结论模糊时才需要。
+
+### 第二件：两个小事实 —— **已答一半，剩两个待确认**
+
+1. ~~RAR4 还是 RAR5？~~ **RAR5 ✅**；~~是否固实？~~ **非固实 ✅**；压缩参数 **`-m1 -md=4g` ✅**
+   （都从 part3 的头上直接读到，见文首第二次更正块 ①）。
+   顺带确认：**UI 的口径是解压后字节**（`src/rar_extract.c:766`）。
+2. **还缺两个数（都很便宜）**：
+   - **解压后总大小** —— 决定输出侧吞吐。已知 ≥19.49 GB（仅 `.exfat` 一项）。
+     插件跑解压时 UI 上的 `total` 就是它（`task->total = p->bytes_total`，`src/extract.c:64`）。
+   - **源 / 目标设备** —— 包在哪块盘、解压输出写到哪块盘、是否同一块盘。
+     这一条现在比什么都重要：写路径被怀疑是墙（文首块 ④）。
+
+### 第三件（我已做完，不用上真机）：多线程 RAR5 的收益
+
+用 WinRAR 自带的 **UnRAR 7.23**（`-mt<N>` 开关可解析，虽然不出现在 `-?` 帮助里）
+在一份**按真实形状**造的夹具上做 A/B（`-m1 -md4g`、5.27:1 可压缩、2 GB、分卷）：
+
+| 线程 | 耗时 | 解压后吞吐 | 加速 |
+|---:|---:|---:|---:|
+| 1 | 5.18 s | 386 MB/s | 1.00× |
+| 4 | 2.39 s | 835 MB/s | 2.16× |
+| **8** | **2.11 s** | **946 MB/s** | **2.45×** |
+
+⇒ **收益 2.4×，且已在真实形状上验证**（非固实版本 2.42×，量级一致）。
+接线只需 **1 个编译开关 + 1 个链接开关**（`-DRAR_SMP` / `-lpthread`），**不用改 vendored 源码、
+不用增删源文件**（早期写的 `threadmisc.cpp` 那一条经实测作废，见 §六 块 ④ 行内更正）——
+原因与行号见 `docs/EXTRACTION-PERF.md` §六 第二次更正块 ④。
+
+> ⚠️ 但结论顺序仍以第一件为准：**先 `T_copy`**。如果墙是 30–40 MB/s 的写路径，
+> 这 2.45× 会被 I/O 完全吃掉，做了等于白做。
+> ⇒ **闭环（2026-09-23 18:15）：`T_copy` 没做，用户决定不做这项了**（见文首终局块）。
+> 本节的实测数据**保留** —— 将来重开时它就是收益依据；但**第一步仍是 `T_copy`**。
+
+---
+
+## 第 1 步（决定性实验，= 上面「第一件」）：用插件自己的「复制」功能做 I/O 基线
+
+**这是目前唯一能把「存储」和「我们的代码」一刀切开的实验，而且零改动。**
+
+插件里 **`TASK_COPY` 是已实现功能**，并且对 ≥ 256 MiB 的文件自动走
+`copy_file_pipeline()`（`src/filemgr.c:836`，阈值见 `:37`）：**3 个 slot × 8 MiB、4096 字节对齐、
+独立读线程 + 独立写线程**。也就是说，它就是「同一台 PS5、同一对设备、同一份代码，
+只把解压那一步换成纯搬运」。
+
+**操作**：把那个 18 GB 的包，用插件自己的复制功能，复制到**解压时输出所在的那块盘**上。
+记下耗时 `T_copy`。
+
+**判读：**
+
+| 观察到 | 结论 | 下一步 |
+|---|---|---|
+| `T_copy` ≈ 10 分钟或更多 | **存储物理极限**，与我们的代码无关 | 收工。解码优化全部搁置 |
+| `T_copy` ≈ 1–2 分钟（远小于 660 s） | 我们的解压比同一对设备上的纯 I/O **慢 5–10×** ⇒ **代码里有真问题** | 进第 2、第 4 步 |
+| 介于两者之间 | 混合 | 按字节数把 I/O 分量扣掉，差值才是我们能动的部分 |
+
+严格比较要看**总移动字节**：复制读 18 GB + 写 18 GB = 36 GB；解压读 ≤ 18 GB、写 = 解压后大小。
+所以「复制 36 GB 用了多久」和「解压搬了 (18 GB + 解压后大小) 用了 660 s」才是同一口径。
+
+> 为什么这个实验优于第 3 步那一堆：它不需要造新包、不需要两块盘、不需要任何假设，
+> 而且**测的就是出事的那对设备**。第 3 步只在第 1 步结论模糊时才需要。
+
+---
+
+## 第 2 步：读写粒度审计 —— ~~目前唯一可疑的代码级病因~~（⚠️ **对 RAR 不适用**）
+
+> **2026-09-23 晚加注：本节整段只对 7z / ZIP 有效。** 它比较的是「引擎内部缓冲大小」，
+> 而 RAR 的归档 I/O 在 UnRAR 自己的 `File` 类里（我们按路径打开，
+> `src/rar_extract.c:1059`），我们的回调只收到解压后的数据 —— **读粒度我们改不了**。
+> 唯一还能对上 RAR 的那半句是「**写入**粒度」，而 RAR 的写出也在 UnRAR 内。
+> ⇒ **真机工作负载是 RAR 时，本节没有可操作性**；留着是为了 7z/ZIP 场景。
+> 顺带：本表里 RAR 那行写的 4 MiB 是 `File::CopyBufferSize()`
+> （`third_party/unrar7/file.hpp:148-153`），那是**文件复制**的缓冲，**不是解压读取缓冲** ——
+> 原文引用错了行，这条勘误一并记在这里。
+
+把四条路径的**单次请求大小**摊开看（已核对源码）：
+
+| 路径 | 源侧读粒度 | 目标侧写粒度 |
+|---|---|---|
+| **复制**（pipeline，≥ 256 MiB） | **8 MiB** × 3 slot，4096 对齐，独立读线程 | 8 MiB |
+| **7z** | chain `SZ_IN_CHUNK = 256 KiB`（`src/sevenz_chain.c:87`）；MT 路径 `inBufSize_MT = 1 MiB` | `SZ_OUT_CHUNK = 64 KiB`（`src/sevenz_chain.c:94`） |
+| **ZIP** | `ZIPX_IO_BUFFER = 128 KiB`（`src/zip_extract.c:32`） | 128 KiB（`src/zip_extract.c:900`） |
+| **RAR** | UnRAR 内部 `File::CopyBufferSize() = 4 MiB`（`third_party/unrar7/file.hpp:148-153`） | 4 MiB |
+
+⇒ 结论一：**三个引擎都不是「小读」病理**，最小也有 128 KiB，不是 4 KB 那种灾难。
+
+⇒ 结论二：**但都比复制小 32–64 倍**。
+
+为什么这可能正是病根 —— 在**延迟主导**的设备上，吞吐 ≈ 单次请求大小 ÷ 每次请求的等效延迟：
+
+```
+256 KiB / 10 ms =  25 MB/s    ← 正好落在实测 10–40 MB/s 的中间
+  8 MiB / 10 ms = 800 MB/s    ← 复制路径不会撞这个上限
+```
+
+这个算术顺带解释两件事：
+
+- **为什么吞吐会 4× 摆动**：等效延迟随设备状态（HDD 寻道、USB 桥接、写缓存回刷）变化，
+  线性映射到吞吐上就是大幅波动。
+- **为什么「条目平均 14.7 MB」没能救我们**：per-entry 成本的确不是主因，但**读请求粒度**是另一回事 ——
+  它由引擎内部缓冲决定，与条目大小无关。
+
+最可能的场景是**源和目标在同一块盘**（外置 USB HDD 上解压到同一块盘）：读流和写流同时存在，
+磁头来回跑，OS read-ahead 被写回刷反复打断，于是每次请求退化成一次寻道 —— 这正好让上面那个
+算术成立。第 1 步如果出现「复制明显快于解压」，就是在支持它（复制的寻道次数只有解压的 1/32）。
+
+**如果第 1 步指向这里，改动面其实很小**：所有 7z 的读都只经过 `src/sevenz_volstream.c` 的
+`vol_read()` 这一个函数（ZIP/RAR 同理在 `src/zipx_volstream.c`）。在那里加一层 read-ahead
+（向后 seek 时丢弃缓存）即可，**不需要动解码器**。但这要等第 1 步的结论，现在不写。
+
+---
+
+## 第 3 步：四个对照实验（零改动）—— 第 1 步结论模糊时才需要
+
+| 实验 | 做法 | 若结果为 A | 若结果为 B |
+|---|---|---|---|
+| **A 换简单包** | 造一个「**单一大文件**（如 10 GB 伪随机数据）」的 zip，放内置 SSD，解到内置 SSD | 吞吐跳到 **150+ MiB/s** ⇒ 慢在**条目数 / per-entry 开销** | 仍是 10–40 ⇒ 慢在**存储或 I/O 模式**，与条目数无关 |
+| **B 换源设备** | 同一个包，分别放**内置 SSD** 与**外置 USB** | 两者差别巨大 ⇒ 就是源盘带宽 | 两者一样慢 ⇒ 不是源盘 |
+| **C 换目标设备** | 同一个包，分别解到**内置**与**外置** | 差别巨大 ⇒ 写入端是瓶颈 | 一样慢 ⇒ 不是目标盘 |
+| **D 同盘 vs 异盘** | 包与输出在同一块盘 / 在两块盘 | 同盘明显更慢 ⇒ 读写争用（这也是第 2 步最看好的假设） | — |
+
+> 参考量级：机械/低成本 USB HDD 顺序读写约 30–80 MB/s，小文件随机访问降到 1–10 MB/s。
+
+---
+
+## 第 4 步：只有在第 1/3 步指向「我们的代码」时才做（要改代码）
+
+1. **阶段计时**：在四个阶段边界累加时间戳 —— `scan` / `read+decode` / `write staging` /
+   `publish`。用 `clock_gettime(CLOCK_MONOTONIC, ...)`（该原语已在三个引擎里用于进度上报，
+   真机可用）。收尾用 `printf` 打进日志。
+2. **拆开 `read+decode`**：这一段目前分不开。可用「同一归档跑两遍（第二遍吃页缓存）」或
+   「解到 /dev/null 类目标」来逼近 I/O 与解码的分界。
+3. **`SZX_MT_THREADS` 运行时可配**：现在是 `src/sevenz_mt.h:21` 的编译期 `#define 8`，
+   做线程数 A/B 必须重编四次。改成运行时读（默认仍 8）会让实验便宜很多。
+4. **读粒度 A/B**：`SZ_IN_CHUNK` / `ZIPX_IO_BUFFER` 加大到 1–4 MiB 各构建一版，
+   看第 1 步指出的那条曲线是否真的跟着动。
+5. 埋点要用**编译开关**控制，关闭时零开销 —— 避免影响已发布的产物指纹。
+
+---
+
+## 已排除的项（不要再花时间）
+
+> ⚠️ 本表 2026-09-23 晚已按「格式 = RAR」重排。原表里「解码整体就不是瓶颈」这条前提已撤回，
+> 所以**同一批项现在被分成两类**：与 RAR 无关（不用看）、以及真已排除。**两类都不要花时间。**
+
+**A. 与 RAR 工作负载无关**（它们是 7z / ZIP 的项；RAR 解码在 rarlab 库里，我们碰不到）
+
+| 项 | 为什么无关 |
+|---|---|
+| CRC 硬件化 | 对 7z/ZIP 才值 4–5%；**RAR 的 CRC 由 UnRAR 自己算** |
+| MT 扩到 BCJ2 / 多 folder | 纯 7z 概念 |
+| ZIP inflate 换 libdeflate | ZIP 专属 |
+| AES-NI | 只影响 ZIP 加密流与 7zAES；RAR 加密走 UnRAR 自己的 rijndael |
+| 读粒度 / read-ahead（#48） | RAR 按路径自读（`src/rar_extract.c:1059` 的 `od.ArcName`），回调只收解压后数据，**插不进去** |
+
+**B. 真已排除**（与格式无关，或已结论）
+
+| 项 | 为什么排除 |
+|---|---|
+| 与 7-Zip 比倍数 | 真机上没有可比对象（上游那个 `wfm-7zip-helper.elf` 单独分发，本仓刻意不走 helper 路线）；而且**那是 7z 的对比，与 RAR 负载无关** |
+| 逐条目 fsync | 已经全部移除（2026-09-16） |
+| 「条目太小」 | 1252 条 / 18 GB，平均 14.7 MB，不是小文件场景 |
+| 「我们的 RAR 解码器写得慢」 | 解码就是 vendored 的 UnRAR 库本体，我们只剩一层 facade |
+
+**C. 唯一还站着的、且直接针对真实负载的一项** ⬅ **优先看这个**
+
+| 项 | 状态 |
+|---|---|
+| **UnRAR RAR5 多线程解压（`RAR_SMP` + `-lpthread`）** | **❌ 不做（2026-09-23 用户决定，见文首终局块）**。我们没打开它；收益已实测（PC 上 2.45× / 我们引擎 1.40–1.74×）但被「写路径是否为墙」卡住，而验证它的 `T_copy` 未执行 ⇒ 搁置 |
@@ -0,0 +1,297 @@
+# 重写可行性评估报告
+
+> 评估日期：2026-09-15 · 评估对象：`LisherSong/ps5-web-file-manager`（v1.9.1）
+> 目标问题：项目源自他人代码、怀疑授权不清；若从零重写，改动量多大？能否做得更好？
+>
+> ⚠️ 本文是**工程视角**的合规盘点，不是法律意见。若涉及商用/闭源决策，请咨询律师。
+
+---
+
+## 0. 结论先行
+
+| 问题 | 答案 |
+|---|---|
+| 上游真的没有许可吗？ | **否。上游是 GPL-3.0**，我们自己也是 GPL-3.0，两者一致 |
+| 现在能合法发布吗？ | **能**。GPL-3.0 允许修改和再分发，只需满足归因 + 源码可得 |
+| 有没有真实风险？ | 原本 5 个，**4 个已于 2026-09-23 关闭、第 5 个经确认接受现状**（见 §2）；**从头到尾没有一个需要重写** |
+| 全量重写要多少人日？ | **35–50 人日**（约 1.4–2 万行需重写，第三方 7.1 万行可直接复用） |
+| 值得重写吗？ | **取决于目标**：想闭源/商用 → 必须重写；想开源分享 → **完全不必** |
+
+**最反直觉的一点**：我们自建的 7z 引擎核心（3,661 行）**只依赖公共领域和 zlib 许可的第三方库，与上游 GPL 代码零耦合** —— 它是完全干净的资产，今天就能单独抽成 MIT 授权的独立库。
+
+---
+
+## 1. 许可现状核查（事实，非猜测）
+
+### 1.1 上游授权 —— 你的前提是错的
+
+通过 GitHub API 查询（2026-09-15）：
+
+```
+owendswang/ps5-web-file-manager
+  license: GPL-3.0    stars: 78    forks: 6
+  created: 2026-06-16    last push: 2026-09-08    archived: false
+```
+
+上游**有明确许可**，且是 GPL-3.0。我们的 `LICENSE` 同样是 GPL-3.0，在 root commit `5cb0b76`（Initial import）时加入 —— **两边一致，不存在"无授权"的灰色地带**。
+
+### 1.2 授权链条
+
+```
+ps5-payload-dev/websrv (John Törnblom, GPLv3+)
+        │  源码里仍保留 "Copyright (C) 2024/2025 John Törnblom"
+        │  —— asset.c / asset.h / mime.h / websrv.h 四个文件
+        ▼
+owendswang/ps5-web-file-manager (GPL-3.0)
+        ▼
+LisherSong/ps5-web-file-manager (GPL-3.0)  ← 本项目
+```
+
+`src/asset.c:1` 等文件里的 Törnblom 版权声明**至今完整保留** ✅ —— 说明 GPL §5(a)「保留版权声明」这一条在最上游那一环是满足的。
+
+---
+
+## 2. 真实风险清单
+
+按严重度排序。**注意：没有一条需要重写代码来解决。**
+
+| # | 风险 | 严重度 | 具体位置 | 修法 | 成本 |
+|---|---|---|---|---|---|
+| 1 | ~~**归因缺失**~~ → **已修正（2026-09-23）**：README Credits 已补上 `owendswang` 与 rarlab UnRAR / opello 镜像、并把已删除的 `third_party/unrar/` 从 Credits 里清理掉；`THIRD_PARTY_NOTICES` 本就正确。**残留**：git 历史里的 `5cb0b76 Initial import` 无法追溯上游提交 | 🟡 中 → 🟢 低 | `README.md` Credits | 历史归属只能在 Release 说明与 Credits 里声明；如需彻底重建历史得重写仓库 | 已完成 |
+| 2 | **unRAR 与 GPL-3.0 的附加限制冲突**：UnRAR 许可禁止"用于开发 RAR 兼容压缩器"，GPL-3.0 §7 禁止附加限制，严格讲不兼容 | 🟡 中 | `third_party/unrar7/` | 见 §2.1 | 0（接受） |
+| 3 | ~~**ezremote 是 GPLv2**：README 只写 "GPLv2"，未标 "or later"。GPLv2-only 与 GPL-3.0 **不兼容**~~ → **已定性并关闭（2026-09-23）**：确为 **GPL-2.0-only**，但逐行比对确认**我们未取其代码** | ✅ 已关闭 | `src/pkg_info.c`（PKG 预览） | 无需重写；README 中英措辞已改准，代码加了来源注记 —— 见 §2.2 | 0 |
+| 4 | ~~**二进制分发需提供源码**（GPL §6）~~ → **已补（2026-09-23）**：v1.9.2 Release 说明的 License 段原先只链了**上游**仓库，未链本仓库 | ✅ 已关闭 | Release 里的 ELF | 已用 `gh release edit` 加入 "Corresponding source for this binary" 段（资产未动、仍非 draft/pre、仍是 latest）；今后发版沿用 `.build/release-notes-*.md` 模板 | 0 |
+| 5 | Title ID `FMGR88888` 与上游相同，可能与他人 payload 冲突 | 🟢 低 | `Makefile:21` | ~~换一个自定义 ID~~ → **2026-09-23 决定维持现状（用户确认）**。核对结论：`TITLE_ID` 只出现在两处 —— `src/app_installer.c:86`（PKG 安装目标目录 `/user/app/<TITLE_ID>`）和 `src/version.c:31`（`/api/version` 上报），**与解压 / 上传 / 浏览功能无关**，且本项目是上游 fork 的直接替代者（同 ID 便于覆盖安装）。代价：与上游 payload **不能共存**，同时装会撞目录 | 0（接受） |
+
+### 2.1 关于 unRAR（风险 2 详解）
+
+UnRAR 许可原文允许"在任何软件中处理 RAR 归档"，但**禁止用它开发 RAR 兼容的压缩器**。这是一个"附加限制"，与 GPL-3.0 §7 冲突。
+
+实务上的三种处理：
+
+| 方案 | 做法 | 代价 |
+|---|---|---|
+| **A. 接受现状（推荐）** | 明确声明 unrar 部分适用其自有条款，其余部分 GPL-3.0 | 0 —— rarlab 官方自己就这么分发，社区普遍接受 |
+| B. 移除 RAR 支持 | 删掉 `rar_extract.c` + `third_party/unrar7` | 失去 RAR（含分卷/加密）—— 不划算 |
+| C. 换实现 | 找自由许可的 RAR 解码器 | **市面上不存在可用的**，死路 |
+
+**建议 A**。风险等级实际很低：你只做解压不做压缩，本来就不触碰被禁止的那一条。
+
+### 2.2 关于 ezremote（风险 3 详解，2026-09-23 结案）
+
+**结论：风险不成立 —— 确为 `GPL-2.0-only`，但我们一行代码都没取。**
+
+#### 第一步：许可措辞（用 `gh api` 查上游，不是猜）
+
+```
+gh api repos/cy33hc/ps5-ezremote-client    → license.spdx_id = "GPL-2.0"
+gh api .../contents/LICENSE                → GNU GPL v2 全文（June 1991）
+gh api .../contents/source/actions.cpp     → 无任何版权 / GPL 声明头
+gh api .../contents/source/clients/*.h     → 同上，一个声明头都没有
+```
+
+上游**全部源文件都不带许可声明**，唯一的许可陈述就是那份 GPLv2 全文。
+GPLv2 的 "or later" 只能由版权人**明示**授予（LICENSE 全文本身不含该授予），
+所以按其自身现状应认定为 **`GPL-2.0-only`**。
+
+这一点很关键：**`GPL-2.0-only` 与 GPL-3.0 不兼容**（这正是 FSF 发明
+"GPLv2 or later" 惯例的原因）。所以「到底抄没抄」不是学术问题 ——
+抄了就必须重写这个模块。
+
+#### 第二步：逐行比对（决定性的一步）
+
+上游与 PKG 相关的**只有一个文件**：`source/sfo.cpp`（4,209 B / 141 行 / C++）。
+上游**没有 `.pkg` 容器解析器** —— tree 里的 `Ps5_ezRemote_Client_2.00.pkg`
+是一个已编译的 payload（10 MB），不是源码。
+
+| 维度 | 上游 `sfo.cpp` | 我们的 `src/pkg_info.c` |
+|---|---|---|
+| 语言 | C++（`reinterpret_cast` / `std::map` / `namespace SFO`） | **C99** |
+| 函数分解 | 三个独立函数 `GetString` / `GetParams` / `GetParamsFromParamJson` | 单个 `append_sfo_fields(strbuf_t *, ...)` 直接流式产出 JSON 片段 |
+| 返回值 | `std::map<std::string,std::string>` | 写进 `strbuf_t`，无中间容器 |
+| JSON | 依赖 **json-c**（`json_tokener_parse` / `json_object_object_get`） | **自写分词器**（`parse_json_tokens()` / `json_object_value()`，在 `json_util.c`） |
+| 越界防护 | 仅两处 `size <` 检查，其余裸指针 + `reinterpret_cast` | 逐项校验（`count > SFO_ENTRY_MAX`、`index_end > size`、`key_offset < index_end`、`memchr` 找 NUL、`read_le32` 定长读） |
+| 覆盖范围 | 只有 SFO + param.json | 另有 **`.pkg` 条目表**（`PKG_CNT_MAGIC` / FIH / LIH / 条目类型 `0x1000` / `0x1200` / `0x121f` / `0x2000`）、本地化图标选择、两个 HTTP 端点 |
+
+**唯一重合的是格式事实**：SFO magic `0x46535000`、20 字节头 / 16 字节条目、
+`keyofs`+`nameofs` 与 `valofs`+`dataofs` 的间接寻址。这些是 PS5 文件格式的客观规定，
+也是解析它的**唯一办法**（等同合并原则），不构成可保护的表达。
+
+⇒ **不存在代码衍生关系**，`src/pkg_info.c` 无需重写。
+
+#### 第三步：已落地的处置
+
+1. `README.md` / `README.zh-CN.md` 的 Credits 条目：由 "Preview PKG info. License: GPLv2"
+   改为明确写出 **GPL-2.0-only、与本项目不兼容、未取其代码**，并指向本节 ——
+   后来人不会再把它当成"我们的依赖"去理解授权链。
+2. `src/pkg_info.c` 文件头补了来源注记（含比对理由与本节指引）。
+   **纯注释，不改变编译产物** —— 已确认 `src/` 内没有 `__LINE__` / `__FILE__` 依赖，
+   注释被预处理器丢弃后目标文件逐字节相同。
+3. 本节即为 provenance 留档。
+
+> 适用范围：这套「先查许可措辞 → 再做逐行比对 → 最后把结论写进代码注记」的流程，
+> 对任何「README 里 credits 了某个项目」的情形都适用。因为 README 的 Credits 段落里
+> 混着两类东西：**真正 vendored 的代码**（minizip-ng / zlib / UnRAR）和
+> **只是参考了思路的项目**（websrv / ftpsrv / zftpd / etaHEN / ezremote）。
+> 两者在授权义务上完全不同，但排版把它们放在同一张列表里 —— 这就是这个疑问的由来。
+
+---
+
+## 3. 代码归属盘点（决定重写成本的关键）
+
+### 3.1 总量分布
+
+| 类别 | 行数 | 重写时怎么办 |
+|---|---:|---|
+| **第三方 vendored** | **71,528** | ♻️ **直接重新 vendor，一行都不用写** |
+| ├ zlib 1.3.1 | 20,106 | zlib 许可 |
+| ├ unrar7 7.20.1 | 27,710 | UnRAR 许可 |
+| ├ LZMA SDK 26.03 | 17,248 | **公共领域** |
+| └ minizip-ng 4.2.2 | 6,464 | zlib 许可 |
+| **第一方代码** | **20,844** | 这是唯一需要写的部分 |
+| ├ v1.7 上游遗产 | 13,860 | 🔴 受 GPL 约束 |
+| └ 我们新增 | 6,984 | 🟢 版权归我们 |
+
+**这是整份报告最重要的数字**：项目里 **77% 的代码是第三方库**，重写时原样搬走即可。真正需要动手的只有 2 万行第一方代码，其中又只有不到 1.4 万行受 GPL 约束。
+
+### 3.2 我们新增代码的独立性分析
+
+v1.7 之后**新建**的文件（6,745 行），逐个检查其依赖：
+
+| 文件 | 行数 | 依赖 | 能否独立授权 |
+|---|---:|---|:---:|
+| `sevenz_chain.c/.h` | 2,094 | 仅 LZMA SDK（**公共领域**） | ✅ **完全干净** |
+| `zipx_volume.c/.h` | 658 | 仅自身 | ✅ **完全干净** |
+| `zipx_volstream.c/.h` | 494 | minizip-ng（zlib）+ zipx_volume.h | ✅ **完全干净** |
+| `sevenz_volstream.c/.h` | 415 | LZMA SDK + zipx_volume.h | ✅ **完全干净** |
+| `rar_extract.c/.h` | 1,169 | `zip_extract.h`（共享协议） | ⚠️ 弱耦合，抽协议即可解绑 |
+| `sevenz_extract.c/.h` | 1,790 | `zip_extract.h`（共享协议） | ⚠️ 弱耦合，抽协议即可解绑 |
+| `zipx_common.c` | 99 | `zip_extract.h` | ⚠️ 内容仅限额/状态串，30 分钟可重写 |
+| `cpu_support_stub.c` | 26 | 无 | ✅ 干净 |
+
+**核心结论**：
+- **3,661 行（7z 解码链 + 分卷流抽象）与 GPL 代码零耦合** —— 这是项目最有价值的部分（自解析 folder + pull 式 codec 链 + BCJ2 + 7zAES + 三种分卷语义），也是投入最多的部分。它们**今天就可以抽成独立的 MIT/Apache 库**，不受上游任何影响。
+- 另有 2,959 行只通过 `zip_extract.h` 的**共享协议**（状态枚举、进度回调、限额结构）与上游耦合。把那 100 行协议定义抽成独立的 `archive_api.h` 就能解绑。
+
+---
+
+## 4. 三条路径对比
+
+### 路径 A：维持 GPL-3.0 + 补齐合规（推荐）
+
+| 项 | 内容 |
+|---|---|
+| 做什么 | README 补 owendswang 署名、加 NOTICE、确认 ezremote 许可、Release 附源码链接、换 Title ID（→ 末项已于 2026-09-23 决定维持现状，见风险 5） |
+| 成本 | **0.5–1 人日** |
+| 收益 | 合规闭环，零功能损失，保留全部现有能力 |
+| 风险 | 无 |
+| 适合 | **想开源分享、想让成果被保护** |
+
+### 路径 B：架构重构（保留 GPL-3.0）
+
+| 项 | 内容 |
+|---|---|
+| 做什么 | 分层重写：platform 层 / archive 引擎层 / HTTP 层 / 前端模块化；抽 `archive_api.h` 解耦；统一进度模型 |
+| 成本 | **12–18 人日** |
+| 收益 | 代码可维护性大幅提升，引擎可独立成库，修掉 §6 的已知缺陷 |
+| 风险 | 中 —— 需真机回归，163 个 host check 要全绿 |
+| 适合 | **觉得现在代码烂、想长期维护** |
+
+### 路径 C：Clean-room 全量重写（换许可）
+
+| 项 | 内容 |
+|---|---|
+| 做什么 | 不参考上游代码，按功能规格从零写 ~13,860 行受 GPL 约束的部分 |
+| 成本 | **35–50 人日**（含真机调试） |
+| 收益 | 完全自有版权，可任选许可（含闭源商用） |
+| 风险 | **高** —— clean-room 必须严格隔离：写代码的人不能看过上游源码；否则法律上无效 |
+| 适合 | **确定要闭源/商用** |
+
+### 4.1 路径 C 的工作量拆解
+
+| 模块 | 行数 | 难度 | 人日 |
+|---|---:|---:|---:|
+| HTTP 服务 + 路由（websrv/main/asset/mime/file_response） | ~700 | 低 | 3 |
+| 文件管理核心（filemgr.c） | 2,458 | **高** | 8 |
+| 上传 / 下载 / 断点续传 | 1,343 | 中 | 5 |
+| 文件系统工具（fs_util/path_util/list/space/text） | 1,229 | 中 | 4 |
+| PKG 安装 / 信息解析 / app_installer | 847 | 中 | 4 |
+| 任务调度 + 通知（task/notify） | 253 | 低 | 1.5 |
+| ZIP 引擎 + 分卷（zip_extract/zipx_*） | 3,091 | **高** | 8 |
+| 前端（main.js / main.css / index.html / i18n） | 4,779 | 中 | 6 |
+| 构建系统 + 资产内嵌 | ~200 | 低 | 1 |
+| 测试矩阵（对齐现有 163 checks） | — | 中 | 5 |
+| 真机调试 + PS5 平台适配 | — | **高** | 6 |
+| **合计** | **~14,900** | | **≈ 51 人日** |
+
+可复用的：7z 全套（4,299 行）+ zipx 分卷（1,193 行）+ 第三方（71,528 行）—— 这三项占了重头戏，所以才是 50 人日而不是 150 人日。
+
+---
+
+## 5. 重写能做到"比现在更好"的地方
+
+如果真要走 B 或 C，这些是现在已知的技术债，**顺手一起解决才值得动**：
+
+| # | 现有问题 | 位置 | 改进方案 |
+|---|---|---|---|
+| 1 | **进度口径三处不一致**：进度条按字节、文字按条目数、ETA 按字节速度，混合大包上体验割裂 | `main.js:1985` / `main.js:2014` / `task.c:129-177` | 统一为字节口径，ETA 用滑动窗口 |
+| 2 | **PS5 `*at()` 族运行时损坏**（返回 -1 且 errno=0），现有绕行逻辑散落在 `zip_extract.c` | `zip_extract.c` | 抽 platform 层集中处理，写新代码不再踩 |
+| 3 | 引擎与 HTTP 层耦合：解压协议定义在 `zip_extract.h` 里 | `zip_extract.h` | 抽 `archive_api.h`，引擎可独立成库 |
+| 4 | `main.js` 2,652 行单文件，无模块拆分 | `assets/main.js` | 按 view / api / task 拆模块 |
+| 5 | `filemgr.c` 2,458 行，路由 + 业务逻辑 + 平台调用混在一起 | `src/filemgr.c` | 分 handler / service / platform 三层 |
+| 6 | 测试靠手工脚本，未接入 `make test` | `tests/` | 接 CI，覆盖率可量化 |
+| 7 | ~~唯一功能缺口：7z `-mhe=on` 加密头~~ **已闭合**（2026-09-23，`src/sevenz_header.c`） | `sevenz_extract.c` | 无剩余格式缺口；重写时该项可删 |
+
+---
+
+## 6. 建议
+
+### 6.1 我的推荐：路径 A，外加一条"资产剥离"
+
+**不要全量重写。** 三个理由：
+
+1. **GPL-3.0 对你有利，不是负担**。它保证别人拿走你的 7z 引擎成果后**必须同样开源**。换成 MIT，别人可以直接闭源拿去卖 —— 你花了大量精力做的 BCJ2 链、7zAES、分卷流抽象会被白嫖。
+2. **重写的法律风险比不重写更高**。你已经看过上游源码了，clean-room 的前提已被破坏。真重写必须找没看过上游的人来做，还得隔离沟通 —— 成本远超 50 人日。
+3. **你的核心资产本来就是干净的**。3,661 行的 7z 解码链 + 分卷流只依赖公共领域和 zlib 许可，**现在就能单独抽出来做 MIT 授权的独立库**，不需要动主项目一根指头。
+
+### 6.2 立刻可做的三件事（共 1 天）
+
+```
+1. README.md Credits 补一行：
+   - [owendswang/ps5-web-file-manager](...): base implementation. License: GPL-3.0.
+
+2. 把 sevenz_chain.{c,h} + sevenz_volstream.{c,h} + zipx_volume.{c,h}
+   + zipx_volstream.{c,h} 抽成独立仓库，MIT 授权，主项目作为 submodule 引用。
+   → 3,661 行成果立刻获得独立身份，且证明这部分是你的原创。
+
+3. ~~确认 ezremote 是 "GPLv2" 还是 "GPLv2 or later"；若是 v2-only，重写 pkg_info.c~~
+   → **已结案（2026-09-23）**：是 `GPL-2.0-only`，但逐行比对确认**我们未取其代码**，
+   **无需重写**。比对记录与处置见 §2.2。
+4. ~~v1.9.2 Release 说明补本仓库链接（GPL §6 源码提供义务）~~
+   → **已补（2026-09-23）**，见风险 4 行。
+```
+
+### 6.3 需要你回答的问题
+
+**你重写的动机到底是什么？** 不同答案对应完全不同的方案：
+
+| 如果你的目标是… | 应该走 | 成本 |
+|---|---|---|
+| 想闭源 / 商业化 | C（且必须找没看过上游的人写） | 50+ 人日 |
+| 只是担心"没许可"不合法 | **A** —— 你的担心不成立 | 0.5 天 |
+| 想让别人知道这是你写的 | **A** —— GPL 允许你在修改部分署名 | 0.5 天 |
+| 觉得代码质量差、想重构 | B | 12–18 人日 |
+| 想保护成果不被闭源 | **A** —— GPL-3.0 已经是最佳选择 | 0 天 |
+
+---
+
+## 附录：核查方法与数据来源
+
+| 项 | 来源 |
+|---|---|
+| 上游许可 | GitHub API `repos/owendswang/ps5-web-file-manager`，2026-09-15 查询 |
+| 本项目许可 | `LICENSE`（35,149 B，GPL-3.0 全文），root commit `5cb0b76` 引入 |
+| 代码行数 | `wc -l` 于 v1.9.1 工作树；上游基线取 `git show 5cb0b76:<file>` |
+| 文件归属 | `git ls-tree -r 5cb0b76 -- src assets` 与当前工作树的差集 |
+| 依赖分析 | 逐个 grep `#include "` 于自有文件 |
+| 已知缺陷 | 项目 `HANDOVER.md` 第四节 + `.workbuddy/memory/MEMORY.md` |
@@ -0,0 +1,354 @@
+# ELF 瘦身可行性分析
+
+> 2026-09-20 · 环境：WSL Ubuntu-22.04 + `/opt/ps5-payload-sdk` + LLD 18.1.8
+> 基线产物 `web-file-mgr-v1.9.1.elf` = **1,034,328 B**
+> 复现脚本：`.build/_sizeprobe.sh`、`.build/_probe3.sh`、`.build/_slimtest.sh`、`.build/_slimtest2.sh`、`.build/_modsize.sh`
+
+## 结论
+
+> ✅ **4.1 + 4.2 已落地（2026-09-20）** — `src/demangle_stub.c` 已加入 `COMMON_SRCS`，
+> `LDFLAGS` 已加 `-Wl,--icf=all`。
+>
+> 产物：**870,488 B** · sha256 `24392aff6ddcca4dc0ea969cce356bd693ac52efe8a117d61ee1c814aa43cd07` · e_machine `0x003e`
+>
+> 落地后复核：`__cxa_demangle` 本体 11 B、`itanium_demangle` 符号 0、
+> `__cxa_throw` / `_Unwind_Resume` 等异常符号齐全、`sevenz_extract` / `rar_extract` /
+> `zipx_extract` / `MHD_start_daemon_va` 全部存在。
+> section 变化：`.text` 637,616 → 538,336、`.rela.dyn` 54,816 → 25,800、
+> `.eh_frame` 58,904 → 43,972、`.rodata` 162,016 → 153,664。
+>
+> 4.3（RELR）与 4.4 未启用 —— 待真机验证 / 权衡后再决定。
+
+**能瘦，而且有一个"白捡"的 15.8%。**
+
+| 方案 | 结果 | 降幅 | 风险 |
+|---|---:|---:|---|
+| 瘦身前 | 1,034,328 B | — | — |
+| **+ `__cxa_demangle` 桩** | **886,872 B** | **−147 KB** | 极低 |
+| **+ ICF 代码折叠（当前产物）** | **870,488 B** | **−164 KB (−15.8%)** | 极低 |
+| 再 + RELR 重定位压缩 | 854,176 B | −180 KB (−17.4%) | 需真机验证 |
+| 第三方改 `-Oz`（单列） | 969,504 B | −65 KB | 可能降速 |
+
+前两项**不损失任何功能，也不影响解压速度** —— 去掉的是一段永远不会被执行的代码。
+
+---
+
+## 一、现状构成
+
+数据源：`size -A` / `nm --size-sort --print-size` / 未 strip 重链接。
+
+### section 级
+
+| section | 大小 | 备注 |
+|---|---:|---|
+| `.text` | 637,616 | 代码主体 |
+| `.rodata` | 162,016 | 前端资源（gzip）+ 字符串常量 |
+| `.eh_frame` + `.eh_frame_hdr` | 71,444 | **C++ 异常展开表** |
+| `.gcc_except_table` | 8,500 | **C++ 异常处理器表** |
+| `.rela.dyn` | 54,816 | 2,119 × `R_X86_64_RELATIVE` + 165 × `GLOB_DAT` |
+| `.data.rel.ro` | 20,192 | 含指针的只读数据 |
+| `.dynsym` + `.dynstr` + `.gnu.hash` | 23,863 | 动态符号表（PIE 必需） |
+| `.text$LZMADECOPT` | 4,719 | LZMA 汇编解码器（提速 1.26×，保留） |
+| `.bss` | 56,416 | **不占文件体积** |
+
+### 模块级（按目标文件归属，text+data）
+
+| 模块 | 文件数 | text | data |
+|---|---:|---:|---:|
+| unrar7（RAR 引擎） | 48 | 314,528 | 658 |
+| libc++ / libc++abi / PS5 运行时 | — | ~161,900 | 20,738 |
+| **C++ 异常机制** | — | **151,288** | — |
+| zlib | 8 | 65,211 | 336 |
+| 7z SDK + 自研链 | 30 | 85,406 | 56 |
+| minizip-ng | 8 | 39,382 | 384 |
+| 自有代码 `src/` | 14 | 60,653 | 472 |
+| libmicrohttpd | — | 44,647 | — |
+| 前端资源（gzip 后） | 13 | 40,278 | 104 |
+
+---
+
+## 二、最大的单一发现：151 KB 的 C++ 异常机制
+
+`nm` 统计出 **607 个 `itanium_demangle::*` 符号，合计 105,431 B** —— 这是 libc++abi 的
+C++ 名字还原器（`__cxa_demangle`），单独一块就占了整个 ELF 的 **10.2%，比 zlib 整个库还大**。
+
+它是怎么被拉进来的：
+
+1. `third_party/unrar7/dll.cpp` 用了 `catch (RAR_EXIT)` / `catch (std::bad_alloc&)`
+   （`unpack.cpp` / `model.cpp` 里也有 `throw std::bad_alloc()`）
+2. 只要 C++ 异常运行时存在，libc++abi 的 `__cxa_throw` 链路就会引用 `__cxa_demangle`
+   （用于打印未捕获异常的类型名）
+3. 链接器于是把整个 `cxa_demangle.cpp` 拉进来 —— 一个深度内联的模板解析器，
+   展开成 607 个函数
+
+连带被拖进来的还有 `libunwind`（21,953 B，栈回溯）和异常胶水（23,904 B），
+以及散落在每个 C++ 目标文件里的 `.eh_frame`（58,904 B）/ `.gcc_except_table`（8,500 B）。
+
+**但这个 demangler 只在「未捕获异常」的诊断路径上才会被调用。**
+我们的 unrar7 走 DLL 模式，所有异常都在 `dll.cpp` 内部被 catch 掉，
+程序逻辑永远走不到那条路径。
+
+---
+
+## 三、实测（同一 WSL、同一份源码、同一个链接器）
+
+| # | 变更 | 结果 | 差值 |
+|---|---|---:|---:|
+| E0 | 重新链接（校验基线） | 1,034,328 | 0 |
+| E1 | `-Wl,--icf=all` | 1,017,944 | −16,384 |
+| E2 | 注入 `__cxa_demangle` 桩 | 886,872 | **−147,456** |
+| E3 | 桩 + `--icf=all` | 870,488 | **−163,840** |
+| E4 | `-Wl,-z,pack-relative-relocs` | 985,248 | −49,080 |
+| E5 | `-Wl,-z,noseparate-code` | 1,034,328 | 0（无效） |
+| E7 | 桩 + ICF + RELR | 854,176 | −180,152 |
+| E8 | 第三方全部改 `-Oz` | 969,504 | −64,824 |
+
+> E4 单独能省 49 KB，但与 ICF 组合后只剩 16 KB —— ICF 已经合并掉了一批重定位。
+
+---
+
+## 四、落地方案
+
+### 4.1 立即可用：`__cxa_demangle` 桩（−147 KB）
+
+新增 `src/demangle_stub.c`：
+
+```c
+/* 只提供 __cxa_demangle 的桩，让 libc++abi 里 105 KB 的名字还原器
+ * 不被链接进来。该函数只在打印「未捕获异常的类型名」时被调用；
+ * 返回 NULL 时调用方退回打印 mangled 名，不影响任何业务流程。 */
+#include <stddef.h>
+
+char *__cxa_demangle(const char *mangled, char *buf, size_t *len, int *status)
+{
+    (void)mangled; (void)buf; (void)len;
+    if (status) *status = -1;
+    return NULL;
+}
+```
+
+Makefile 里把它加进 `COMMON_SRCS`（PS5 与 Linux 两条链路都受益）：
+
+```make
+COMMON_SRCS := src/main.c src/websrv.c ... src/sevenz_mt.c src/demangle_stub.c
+```
+
+**原理**：链接器解析 `__cxa_demangle` 引用时，命令行上的 `.o` 优先于归档成员，
+所以 `libc++abi.a` 里的 `cxa_demangle.o` 压根不会被取出。
+
+**安全性（已实测验证）**：
+
+| 检查项 | 结果 |
+|---|---|
+| `__cxa_demangle` 本体大小 | **11 B**（我们的桩；原 demangler 入口是 1 701 B） |
+| `itanium_demangle::*` 符号残留 | **0** |
+| `__cxa_throw` | 存在 |
+| `__cxa_begin_catch` / `__cxa_end_catch` | 存在 |
+| `_Unwind_Resume` / `__gxx_personality_v0` | 存在 |
+
+**唯一的行为变化**：万一真的出现未捕获异常，`std::terminate` 打印的是 mangled 名
+而不是可读名。解压逻辑、错误码、进度上报、HTTP 服务一概不受影响。
+
+### 4.2 立即可用：ICF 代码折叠（−16 KB）
+
+```make
+LDFLAGS := -Wl,--gc-sections -Wl,--icf=all
+```
+
+lld 的 identical code folding，合并字节完全相同的函数。工具链已确认为 LLVM LLD 18。
+建议只加在 PS5 的 `LDFLAGS`，不动 Linux 链路（GNU ld 的 `--icf` 支持不完整）。
+
+### 4.3 需真机验证：RELR 重定位压缩（−16 KB）
+
+```make
+LDFLAGS += -Wl,-z,pack-relative-relocs
+```
+
+把 2,119 条 `R_X86_64_RELATIVE`（24 B/条）压成 RELR 位图格式（8 B/条）。
+
+**风险**：需要 PS5 的 ELF 加载器认得 `.relr.dyn`。如果加载器只处理 `.rela.dyn`，
+重定位根本不会执行 —— 表现是启动即崩。**先在一台机器上验证再推广。**
+
+### 4.4 不建议作为默认项
+
+| 项 | 收益 | 为什么不默认开 |
+|---|---:|---|
+| 第三方改 `-Oz` | −65 KB | 作用于 LZMA / Deflate / RAR 的热循环，解压速度有下降风险。要用先跑 `tests/bench_driver.py` 对比 |
+| 关掉 PPMd（`-DZ7_PPMD_SUPPORT`） | −10 KB | PPMd 压缩的 7z 就解不开了 —— 违背"功能完整" |
+| 去掉 zlib `deflate`（只留 inflate） | −18 KB | `mz_strm_zlib_write` 引用了它，需要桩或改库，收益/风险不划算 |
+
+---
+
+## 五、还能挖的（未实测，仅估算）
+
+| 项 | 预估 | 代价 |
+|---|---:|---|
+| unrar7 去掉 C++ 异常（`throw`/`catch` 改错误码 + `-fno-exceptions -fno-rtti`） | −100~110 KB | 改 vendored 代码，需回归 163 checks。可回收 `.eh_frame` 59 KB + `.gcc_except_table` 8.5 KB + libunwind 22 KB + 异常胶水 |
+| LTO（`-flto=thin`） | −30~60 KB | 全量重编，第三方 `.o` 需统一编译选项；有一定概率反而提速 |
+| 前端资源改 LZMA 压缩（复用已有解码器，替代 gzip） | ~−10 KB | 改 `gen-asset-module.py` + `asset.c` |
+
+理论极限在 700 KB 上下（−32%），但边际成本递增：4.1 + 4.2 用 20 行代码换 164 KB，
+而再往下 100 KB 要动 vendored 源码或验证加载器行为。
+
+---
+
+## 六、推荐执行顺序
+
+1. ~~落 4.1 + 4.2 → 构建~~ ✅ **已完成（2026-09-20）**，产物 870,488 B
+2. 跑 163 checks（`tests/run-tests.sh` + `tests/run-sevenz-tests.sh`）确认无回归
+3. PS5 真机跑一轮 ZIP / RAR / 7z（含分卷）解压，确认行为不变
+4. 真机验证 4.3（RELR）后再决定是否加入
+5. 有需要再评估第五节的三项
+
+> 本次改动只动链接期（新增一个 TU + 一个 lld 参数），未触碰任何解压逻辑，
+> 因此 163 checks 的预期是"逐条不变"。
+
+**结果（2026-09-20）**：163 checks（ZIP 108 + RAR 27 + 7z 28）**0 失败**，
+`aeshe` 仍是已知的 `-mhe=on` 缺口。README / CHANGELOG / HANDOVER / 论坛帖里的
+产物指纹已同步为 870,488 B · sha256 `177e90fe…8e84`。
+
+> 后续（2026-09-23）：测试计数已变为 ZIP 140 + RAR 37 = 177（7z 套件 27 用例），
+> `aeshe` 缺口也已闭合；产物指纹随之更新。本节保留的是上面的历史测量值。
+
+---
+
+## 附录 A：v1.9.2 产物一致性验证（2026-09-20）
+
+v1.9.2 是一次"只改内嵌版本号"的重发（原 `v1.9.1` tag 落后产出发布二进制的提交
+4 个提交）。为确认这次重发**真的**只动了版本号，在 WSL 里做了下面的验证。
+
+### A.1 复现性实验（决定性证据）
+
+当前工作区相对 `HEAD` 只有两处改动：`Makefile` 的 `VERSION_TAG` 与
+`assets/main.js` 的 `APP_VERSION_FALLBACK`。把这两处用 `sed` 回退成 `v1.9.1`
+后重新构建：
+
+| 构建 | sha256 |
+|---|---|
+| 已发布的 v1.9.1 ELF | `24392aff6ddcca4dc0ea969cce356bd693ac52efe8a117d61ee1c814aa43cd07` |
+| 回退后重建的产物 | `24392aff6ddcca4dc0ea969cce356bd693ac52efe8a117d61ee1c814aa43cd07` |
+
+**逐字节相同。** 再恢复 `v1.9.2` 重构，sha256 也精确回到 `177e90fe…8e84`。
+
+→ 构建是**确定性**的，因此 v1.9.2 与 v1.9.1 的全部差异就等于那两处版本字面量。
+复现脚本：`.build/_repro.sh`。
+
+### A.2 为什么原始字节 diff 有 5.5 万字节 —— 别被吓到
+
+`cmp` 两个 ELF 会看到 **55,280 字节不同（6.35%）**，但这是链接器字符串池重排的
+副作用，不是代码变了：
+
+| section | 差异字节 | 占该 section |
+|---|---:|---:|
+| `.rodata` | 53,496 | 34.8% |
+| `.text` | 1,543 | 0.3% |
+| `.rela.dyn` | 241 | 0.9% |
+
+而**每个 section 的尺寸完全相同**（`.text` 538,336 = 538,336），段数也都 17 个。
+
+机制：`.rodata` 里 7 字节的 `"v1.9.1\0"` 被换成 `"v1.9.2\0"` 后落点变了，其后
+所有字符串整体平移 7 字节 → 指向它们的 `lea rdi,[rip+disp]` 位移和 `.rela.dyn`
+重定位加数全部跟着变。
+
+两条量化证据：
+
+| 检查 | 结果 |
+|---|---|
+| 指令**助记符**序列（`objdump -d --no-show-raw-insn` 只取 mnemonic） | 141,780 条 vs 141,780 条，**完全一致** —— 没有任何指令被增删改 |
+| `.text` 差异字节的增量分布 | 1,543 个里 **1,506 个恰好是 −7**（正是那个 7 字节平移）；`.rela.dyn` 241/241 个 8 字节字段减 7 |
+| 嵌入的 gzip 资产 | 6 个成员，5 个逐字节相同，唯一不同的是 `main.js`，且差异 = `APP_VERSION_FALLBACK` 那一行 |
+
+脚本：`.build/_diffmap.py`、`.build/_operandcheck.sh`、`.build/_fieldcheck.py`、
+`.build/_verify_v192b.py`、`.build/_seccmp.py`。
+
+### A.3 源码层的约束
+
+`VERSION_TAG` 在源码里**只出现在字符串上下文**：
+
+```
+src/version.c:29   json_escape(&b, VERSION_TAG);
+src/main.c:127     printf("version: %s\n", VERSION_TAG);
+src/main.c:147     notify_user("Web File Manager\nVersion: %s\nPort: %u", VERSION_TAG, port);
+```
+
+没有任何算术、比较或分支依赖它，因此改版本号在语言层面就不可能改变控制流。
+
+---
+
+## 附录 B：瘦身逐符号账目
+
+在 **同一个 Makefile / 同一个 `VERSION_TAG`（v1.9.2）** 下重建三个变体，差异只落在
+"有没有桩"和"有没有 ICF"这两处，因此是干净的 A/B/C 对照。
+
+| 变体 | 内容 | stripped | unstripped |
+|---|---|---:|---:|
+| `base` | 无桩、无 ICF（瘦身前） | **1,034,328** | 1,222,752 |
+| `nicf` | 有桩、无 ICF | **886,872** | 1,010,208 |
+| `new` | 有桩 + `--icf=all`（发布态） | **870,488** | 993,824 |
+
+拆分：桩贡献 **−147,456 B**，ICF 再贡献 **−16,384 B**，合计 **−163,840 B（−15.8%）**。
+
+### B.1 section 位移（base → new）
+
+| section | base | new | 差值 |
+|---|---:|---:|---:|
+| `.text` | 637,616 | 538,336 | −99,280 |
+| `.rela.dyn` | 54,816 | 25,800 | −29,016 |
+| `.eh_frame` | 58,904 | 43,972 | −14,932 |
+| `.data.rel.ro` | 20,192 | 9,328 | −10,864 |
+| `.rodata` | 162,016 | 153,664 | −8,352 |
+| `.eh_frame_hdr` | 12,540 | 9,108 | −3,432 |
+| `.gcc_except_table` | 8,500 | 7,364 | −1,136 |
+| `.dynsym` / `.dynstr` / `.got` | — | — | −24 / −9 / −8 |
+
+### B.2 符号集合差
+
+| 项 | 数量 |
+|---|---:|
+| base 定义符号 | 2,657 |
+| new 定义符号 | 2,029 |
+| base → new **消失** | **628** |
+| base → new **新增** | **0** |
+
+628 个消失符号的构成：
+
+- `itanium_demangle::*` —— **607**
+- `GCC_except_table*` —— **21**（上面那批代码自己的异常表标签，不是独立函数）
+
+### B.3 桩本体与 demangler 符号
+
+| 变体 | `__cxa_demangle` 符号大小 | `itanium_demangle` 符号数 |
+|---|---:|---:|
+| base | 1,701 B（真身） | 607 |
+| nicf | **11 B**（我们的桩） | **0** |
+| new | **11 B** | **0** |
+
+异常机制在所有三个变体里都完好：`__cxa_throw` / `__cxa_begin_catch` /
+`__cxa_end_catch` / `_Unwind_Resume` / `__gxx_personality_v0` /
+`__cxa_allocate_exception` / `__cxa_free_exception` 各 1 个，无变化。
+
+自有 `src/` 关键符号（`ctx_fail` / `rarx_fail` / `szx_fail` / `fnv1a` /
+`nameset_init` / `remove_tree` / `ensure_parent_dirs` / `zipx_volume_detect` /
+`sevenz_extract` / `rar_extract` / `filemgr_api_request` 等）base 与 new 数量一致。
+
+### B.4 ICF 折叠了什么
+
+**符号数 2,029 → 2,029，一个没少** —— ICF 是"合并"不是"删除"。共 **76 个折叠组**，
+全部含具名符号。典型几类：
+
+- 我们自己的同码副本：`ctx_fail == rarx_fail == szx_fail`、
+  `nameset_init == szx_nameset_init`、`fnv1a == rarx_fnv1a == szx_fnv1a`、
+  `remove_tree == szx_remove_tree`
+- C++ 的 `C1 == C2` / `D1 == D2` 构造析构对（编译器为同一函数生成两个 ABI 入口）：
+  `_ZN10CmdExtractC1EP11CommandData == ...C2...`、`_ZN4FileD1Ev == _ZN4FileD2Ev` 等
+- 只读常量表：`Sbox == _ZL1S`（AES 表在 `rijndael.cpp` 与 `Aes.c` 各一份）、
+  `SHA256_K_ARRAY == _ZL1K`、`PPMD7_kExpEscape == _ZL9ExpEscape`
+- RARDLL 模式下被置空的 UI 函数、`mz_stream_read_int64 == read_uint64`、
+  libunwind 的 `__unw_* == unw_*`、`__unw_resume == unw_resume`
+
+**风险提示**：`--icf=all` 是 LLD 的激进模式，**不做地址敏感性检查**
+（`--icf=safe` 才会读 `.llvm_addrsig` 跳过被取地址的函数）。逐组核对下来这 76 组
+都是同码副本、没有"比较函数/常量表地址"的用法 —— 但这是人工判断，不是编译器给的
+保证。想绝对保守就把 `--icf=all` 换成 `--icf=safe`，代价是少省几 KB。
+
+复现脚本：`.build/_whatremoved_v192.sh`（一次跑完三个变体 + 全部核对）。
@@ -124,6 +124,9 @@ zipx_limits_profile(int profile) {
  Each entry is first written to a staging directory (`*.wfm-part-*`),
  `fsync()`'d, then atomically renamed into place. A failure mid-archive
  rolls back partial changes.
+  *(Superseded 2026-09-16: the per-entry `fsync` was removed — all three
+  engines now apply "sync nothing, rename everything". See
+  `docs/EXTRACTION-PERF.md`.)*
 * Security checks run before any output file is opened:
  - encryption
  - path traversal (`..`), absolute POSIX paths, Windows drive letters
@@ -144,6 +144,13 @@ progress callbacks and result-mapping logic are copied from
 engines can evolve independently. (Refactoring them into a
 `src/archive_common/` module is on the post-v1.9 roadmap; see §10.)

+> **Note — superseded 2026-09-16.** The per-entry `fsync` described above was
+> removed. It cost 20–30 minutes on a 95k-file archive and bought nothing the
+> design needs: a crash mid-extract leaves the staging tree, which is discarded
+> on the next run, and publish is a rename-only phase. All three engines now
+> share the same "sync nothing, rename everything" policy. Measurements and the
+> accepted durability trade-off: `docs/EXTRACTION-PERF.md`.
+
 ### 3.3 Error mapping

 `rar_translate_error()` in `src/rar_extract.c` maps the dmc_unrar
@@ -0,0 +1,218 @@
+# 上游 v1.8 解压方案 vs 本项目 v1.9.1
+
+> 核查时间：2026-09-15 · 上游 `owendswang/ps5-web-file-manager`
+> 来源：GitHub API 查询 + commit `b405721`（"Added support for 7zip helper"，2026-09-08）完整 patch（2301 行）
+> 上游 v1.8 = tag `ad7d754`，v1.7 = `72341d6`（本项目 fork 的基线）
+
+## 结论速览
+
+**不是同一个层面的方案，各有明确胜负手。**
+
+| | 上游 v1.8 | 本项目 v1.9.1 |
+|---|---|---|
+| 一句话 | **把 7-Zip 本体做成外部 helper 进程，靠 IPC 调用** | **自研 + vendor 解码库，全部内嵌在同一进程** |
+| 最强的点 | 格式覆盖 **30 种**，解压核心是 7-Zip 本体 | **完整安全护栏** + 单文件部署 |
+| 最弱的点 | **零安全护栏**，且 helper 缺失 = 功能全废 | 格式覆盖只有 **3 种** |
+
+## 一、上游 v1.8 的实际架构
+
+### 1.1 三个组件
+
+| 组件 | 位置 | 职责 |
+|---|---|---|
+| `src/archive_extract.c`（124 行） | 本仓库 | 只做**后缀识别** + 输出目录名推导 |
+| `src/archive_helper.c`（732 行） | 本仓库 | **IPC 客户端**：启动 helper + Unix socket 协议 |
+| `wfm-7zip-helper.elf`（~百 MB 级） | `/data/wfm/`，**不在仓库里，单独分发** | 真正的解压 = **7-Zip 本体** |
+
+README 原文：
+
+> Extraction requires the separately distributed `wfm-7zip-helper.elf` helper at `/data/wfm/wfm-7zip-helper.elf`.
+
+### 1.2 启动链路
+
+```c
+/* archive_helper_autostart() —— 仅 __SCE__（PS5）分支，Linux 直接返回 0 */
+1. archive_helper_probe()     // 已有实例在跑就复用，绝不替换
+2. stat("/data/wfm/wfm-7zip-helper.elf")   // 不存在 → 静默返回 0
+3. 校验 ELF magic "\x7fELF"、大小 4B ~ 128MB
+4. connect(127.0.0.1:9021)    // WFM_ELFLDR_PORT —— elfldr payload 加载器
+5. 把 helper ELF 的**全部字节流**推过去
+6. shutdown(SHUT_WR)
+```
+
+即：**通过 elfldr（PS5 homebrew 的 ELF 加载 payload）把 helper 拉起成一个独立进程。**
+
+### 1.3 通信协议（自研二进制帧）
+
+- 传输层：Unix domain socket —— PS5 走 `/system_tmp/wfm-7zip-helper.sock`，Linux 走 `/tmp/...`
+- 帧格式：magic `"W7HP"` + 20 字节头（type / flags / request_id / payload_size，**大端序**）
+- 上限：payload 1 MiB、路径 256 KiB、响应 64 KiB
+
+消息类型：
+
+| 方向 | 消息 |
+|---|---|
+| 主 → helper | `PING` `EXTRACT` `CANCEL` `LIST_TASKS` `ATTACH_TASK` `ACK_TASK` |
+| helper → 主 | `PONG` `ACCEPTED` `PROGRESS` `CURRENT_FILE` `PASSWORD_REQUIRED` `DONE` `ERROR` `TASK_SNAPSHOT` `LIST_DONE` |
+
+回调接口 `archive_helper_callbacks_t`：`cancel_requested()` / `progress(done,total)` / `current_file(path)`。
+
+### 1.4 支持格式（30 种后缀）
+
+```
+.7z .001 .zip .zipx .rar .arj .bz2 .bzip2 .tbz .tbz2 .cab .gz .gzip
+.tgz .tpz .lzh .lha .tar .xz .txz .z .taz .zst .tzst .xar .xip
+.cpio .lzma .pmd
+```
+
+外加 `.partNN.rar`（只接受 `part1`，即必须从第一卷进入）。
+分卷靠 7-Zip 原生能力：`.001` **无差别接受**（不校验卷集连续性）。
+
+### 1.5 任务恢复（上游的亮点）
+
+`filemgr_recover_extract_tasks()` 在 `main.c` 启动时调用：从 helper 拉 `TASK_SNAPSHOT` 列表，把还在跑的 job **reattach 回主进程的任务列表**。
+
+因为 helper 是独立进程，**主 payload 被重启 / 浏览器重开，解压任务不会丢**。`archive_helper_probe()` 的注释也点明了这个设计的意图：
+
+```c
+/* Never replace a connected daemon, even if it is temporarily slow. */
+```
+
+### 1.6 ⚠️ 没有的东西（全 patch 逐行核查）
+
+| 项目 | 上游 v1.8 | 说明 |
+|---|---|---|
+| 条目数上限 | ❌ | 无 `max_entries` 类逻辑 |
+| 单文件/总大小上限 | ❌ | 无 |
+| 压缩比筛查（防炸弹） | ❌ | 无 |
+| 磁盘空间预检 | ❌ | 无 `statvfs` 调用 |
+| 路径穿越防护 | ❌ | 未见 `..`/绝对路径校验，交给 7-Zip |
+| 原子发布 | ❌（未见） | 直接解到目标目录，中断留半成品 |
+
+`grep -i "ratio|max_entries|statvfs|bomb"` 的全部命中都是误报（`operations` 里含子串 `ratio`）。
+
+**换句话说：上游把解压这件事整体外包给了 7-Zip，包括安全责任。**
+
+## 二、本项目 v1.9.1 的架构
+
+| 组件 | 职责 |
+|---|---|
+| `src/zip_extract.c` | ZIP：minizip-ng，含 zip64、三种分卷命名、`.z01` 真分盘语义 |
+| `src/rar_extract.c` | RAR：vendor unrar 7.20.1（DLL 模式），v4/v5/多卷/加密 |
+| `src/sevenz_extract.c` + `sevenz_chain.c` | 7z：自解析 folder + pull 式 codec 链 + 7zAES |
+| `src/zipx_volume.c` / `zipx_volstream.c` / `sevenz_volstream.c` | 卷集识别 + 连续流抽象 |
+
+**格式覆盖：`.zip` / `.rar` / `.7z` 三种**，各自支持单卷 / 分卷 / 密码。
+
+### 已有的工程能力
+
+| 项目 | 本项目 | 实现位置 |
+|---|---|---|
+| 条目数 / 总大小 / 单文件上限 | ✅ 两档 profile（20万~50万条目 / 2~4 TiB / 512 GiB~1 TiB） | `zipx_common.c` |
+| 压缩比筛查 | ✅ `max_ratio` 500/1000，**1 GiB 下限豁免**小文件 | `zip_extract.c` |
+| 磁盘空间预检 | ✅ `check_space()` 按**解压后总量**查 `statvfs` | `zip_extract.c:636` |
+| 路径穿越防护 | ✅ 有专项测试（`path traversal variants`） | 测试矩阵 |
+| 原子发布 | ✅ staging 目录 + 整 rename（**无逐条目 fsync**，2026-09-16 起） | 三引擎统一 |
+| 冲突策略 | ✅ FAIL / OVERWRITE / MERGE，目录碰撞递归下钻 | 三引擎统一 |
+| 取消 | ✅ 条目粒度 | — |
+| 任务恢复 | ❌ **没有** | — |
+| 内存隔离 | ❌ 与主进程共享地址空间（LZMA2 字典须封顶） | — |
+
+### 测试覆盖
+
+ZIP 108 + RAR 27 + 7z 28 = **163 checks**，0 失败（MinGW host）+ PS5 真机构建通过。
+
+## 三、逐维度对比
+
+| 维度 | 上游 v1.8 | 本项目 v1.9.1 | 胜 |
+|---|---|---|---|
+| 格式覆盖 | **30 种** | 3 种 | 上游 |
+| 解压核心正确性 | 7-Zip 本体（20 年验证） | 自研 7z 链 + 成熟 vendor 库 | 上游 |
+| 分卷语义 | 靠 7-Zip 原生（`.001` 无差别） | 自研两套语义（byte-split / zip split disk） | 平手（我们更细，上游更省心） |
+| `.rar.001` | ✅ 直接吃 | ⚠️ 需改名为 `.partN.rar` | 上游 |
+| 部署 | **两个文件**，路径写死 `/data/wfm/` | **单文件**，零外部依赖 | 我们 |
+| helper 缺失时 | **功能全废**（`archive_helper_not_running`） | 不适用 | 我们 |
+| 防压缩炸弹 | ❌ 无 | ✅ ratio + 1 GiB 下限 | **我们** |
+| 磁盘写满保护 | ❌ 无 | ✅ 预检解压后总量 | **我们** |
+| 路径穿越 | ❌ 无 | ✅ 有防护 + 测试 | **我们** |
+| 中断留残留 | ⚠️ 可能留半成品 | ✅ staging 隔离，失败即清 | **我们** |
+| 任务恢复 / 跨重启 | ✅ 跨进程 reattach | ❌ | 上游 |
+| 内存隔离 | ✅ 独立进程，峰值不影响主服务 | ❌ 共享地址空间 | 上游 |
+| 主仓库构建成本 | 低（不编 7-Zip） | 首次 +3~5 min、ELF +98 KiB | 上游 |
+| 错误信息详细度 | 中等（6 个 code） | 含条目名 / errno / 字节数 | 我们 |
+
+## 四、该怎么评价
+
+### 上游那步棋走对了什么
+
+**把 7-Zip 当外部依赖，是性价比极高的工程决策。** 自己写解码器要几个月，`apt` 一个 7-Zip 就换来 30 种格式 + 20 年验证的正确性。而且顺手拿到了两个我们暂时没有的能力：跨进程任务恢复、内存隔离。
+
+### 但它把安全责任也一起外包了
+
+这是**实质缺陷**，不是风格问题。在 PS5 上跑的具体后果：
+
+1. **压缩炸弹直接写满内置存储** —— 一个 10 KB 的 zip 可以声明 100 GB，没有任何拦截
+2. **路径穿越** —— `../../` 条目可以写到解压目标之外（7-Zip 本身会做基本清理，但这属于"相信第三方"而非"自己保证"）
+3. **磁盘写满** —— 不预检，写到 ENOSPC 才失败，此时已留下部分文件
+4. **失败留残留** —— 没有 staging 隔离
+
+我们在这四项上都有明确实现和测试。163 checks 里专门有一组 `path traversal variants` 和 `limits`。
+
+### 但必须承认格式覆盖是短板
+
+31 种格式的差距不是"多一点便利"，是**用户会觉得我们弱**：`.tar.gz`、`.xz`、`.zst`、`.bz2` 在 PS5 场景（游戏包、备份、Mod）里出现频率不低。
+
+## 五、可借鉴 / 不建议照抄
+
+### 建议做：补常见格式（性价比高）
+
+按实际收益排序：
+
+| 优先级 | 格式 | 实现路径 |
+|---|---|---|
+| 高 | `.tar` / `.tar.gz` / `.tgz` | tar 解析器自己写（格式极简，~300 行）+ zlib 已在手 |
+| 高 | `.gz` / `.xz` / `.lzma` | gzip 用 zlib；xz/lzma 可 vendor liblzma 或复用 LZMA SDK 的 LzmaDec |
+| 中 | `.bz2` / `.zst` | 单文件解码器，各 ~1000 行，可 vendor |
+| 低 | `.cab` / `.arj` / `.lzh` / `.cpio` / `.xar` | 罕见，除非有具体需求 |
+
+**注意**：`gzip`/`xz`/`zst` 是**单文件**格式（不是归档），解出来就是一个文件，输出路径语义需单独设计。
+
+### 建议评估：任务恢复 / 进程隔离
+
+**动机**：主 payload 被系统杀或用户重开浏览器时，正在跑的大包解压会整个丢失。上游靠 helper 独立进程解决了这点。
+
+**但在我们架构下的成本**：需要引入子进程 + IPC（或至少状态持久化 + 重启后重扫 staging）。PS5 上 fork/exec 与 elfldr 强耦合，不是小改动。
+
+**中间路线**：解压失败时保留 staging 目录 + 记录任务清单文件，重启后支持"续解"。改动量中等，能拿到大部分收益，不必引入 IPC。
+
+### 不建议：照抄 helper 路线
+
+理由：
+
+1. **部署体验倒退** —— 用户要装两个文件，还得记住放 `/data/wfm/`；丢一个功能全废。现在单 ELF 是无状态交付，这是真实优势
+2. **安全护栏会一起丢** —— 走 7-Zip 就意味着放弃我们对 entries/ratio/空间/穿越的控制
+3. **helper 上游自己都不敢放进仓库**（"separately distributed"），大概率是体积或许可原因，跟着走会继承同样的问题
+4. **我们已经付过的成本会沉没** —— 7z 引擎（自解析 folder + pull 链 + 7zAES）+ 三类分卷抽象共约 3,600 行零耦合代码
+
+### 一句话总结
+
+**上游赢在"格式广度 + 进程架构"，我们赢在"安全 + 部署 + 错误质量"。**
+
+如果只想要功能广度，上游的路线更省力；如果要一个**能放心交付给用户、不会被一个恶意压缩包搞崩存储**的工具，我们的路线是对的，缺的只是格式覆盖 —— 而那是可以在现有架构里增量补的，不需要推倒重来。
+
+## 附：核查方法备忘
+
+```bash
+# 拿某个 commit 的完整 patch（不要用 WebFetch，会被 AI 摘要截断）
+curl -sSL --ssl-no-revoke -o up.patch \
+  "https://github.com/<owner>/<repo>/commit/<sha>.patch"
+
+# 沙箱内 curl 必须加 --ssl-no-revoke，否则 schannel 报
+# CRYPT_E_NO_REVOCATION_CHECK (0x80092012)
+
+# 提取单个文件的 diff
+sed -n '/^diff --git a\/src\/foo.c/,/^diff --git a\/src\/bar/p' up.patch
+
+# 只看新增行（去掉 diff 前缀）
+... | grep '^+' | sed 's/^+//'
+```
@@ -0,0 +1,224 @@
+<div align="right">
+  简体中文 · 开发者文档见 <a href="../README.zh-CN.md">README</a>
+</div>
+
+# PS5 网页文件管理器 · 新手使用说明
+
+> 适用版本：**v1.9.3M**（版本号末尾的 `M` = 改版，文末有解释）
+> 本文不假设你懂任何技术名词，照着做即可。
+
+---
+
+## 一、它到底是什么
+
+一句话：**在你的 PS5 上开一个"网页版文件管理器"**。只要设备和 PS5 连着同一个 WiFi，用手机、电脑、甚至 PS5 自带的浏览器打开一个网址，就能像在电脑上一样管理 PS5 里的文件和插在 PS5 上的 U 盘。
+
+### 能做的事
+
+| 想干什么 | 可以吗 |
+|---|---|
+| 看文件、建文件夹、改名、复制、移动 | ✅ |
+| 电脑 ↔ PS5 互传文件 | ✅ |
+| 解压 ZIP / RAR / 7z（**带密码的也行**） | ✅ |
+| 改小的文本文件（`.txt` `.json` `.ini` 等） | ✅ |
+| 看图片（`.png` `.jpg` `.gif` `.webp` 等） | ✅ |
+| 安装 PKG | ✅ |
+| 改文件权限 | ✅ |
+
+### 不能做的事（先说清楚，省得白试）
+
+| 想干什么 | 可以吗 | 说明 |
+|---|---|---|
+| 把一堆文件**打包**成压缩包 | ❌ | 它只会"解"，不会"压"。下载多个文件时会自动打成一个 `.tar` 包，那只是下载用的 |
+| 同时做两件事 | ❌ | 一个任务在跑的时候，其它操作会被拒绝（提示"有任务正在执行"） |
+| 删错了找回 | ❌ | 删除是**永久**的，没有回收站 |
+| 解压 ZIP / RAR / 7z **以外**的格式 | ❌ | 比如 `.tar.gz`、`.iso`、`.xz` 现在不行，见第七节 |
+
+---
+
+## 二、三步把它跑起来
+
+**第 1 步：PS5 上先运行一个"ELF 加载器"**（常见端口是 `9021`）。这一步取决于你用的越狱方案，这里不展开。
+
+**第 2 步：在电脑上把程序发过去。** 打开终端（Windows 用 Git Bash / PowerShell 都行），执行：
+
+```sh
+nc -q0 你的PS5的IP 9021 < web-file-mgr-v1.9.3M.elf
+```
+
+例如你的 PS5 是 `192.168.1.50`：
+
+```sh
+nc -q0 192.168.1.50 9021 < web-file-mgr-v1.9.3M.elf
+```
+
+**第 3 步：看 PS5 左上角的通知。** 它会显示程序名、版本和一个网址，通常是：
+
+```text
+http://192.168.1.50:8888/
+```
+
+在浏览器里打开这个网址就行。**如果通知显示的端口不是 `8888`（比如 `8889`），以通知为准** —— 端口不是写死的，程序会自动挑一个能用的。
+
+> 第一次运行时，它还会在 PS5 主屏装一个「PS5 Web File Manager」快捷方式（Media 分类）。已有的不会被覆盖。
+
+---
+
+## 三、界面上都是些什么
+
+打开页面后大致是这样：
+
+- **最上面 / 侧边**：选"去哪儿"。会看到 **内部存储**、**USB存储**、**M2扩充存储**、**扩展存储**、**根分区** 这几项，点哪个就进哪个。
+- **中间的大列表**：当前文件夹里的内容，可以按名称、类型、大小、修改时间、权限排序（排序方式会被记住）。
+- **列表每一行的按钮**：下载、解压（压缩包才有）、安装（`.pkg` 才有）、文本编辑、改权限、删除等。
+- **上方工具条**：复制、移动、重命名、下载、删除、**解压**、上传（点开选"上传文件 / 上传文件夹"）、新建目录、新建文本、刷新、退出。
+  - **解压按钮一直都在**，只是没选中压缩包时是**灰色**的、点不动。选中**一个**压缩包（`.zip` / `.rar` / `.7z`）它才会变亮可点。鼠标停在灰色按钮上会告诉你为什么不能点。
+- **右下角**：版本号（这里应该显示 `v1.9.3M`）。
+
+界面截图（点击看大图）：
+
+<p>
+  <a href="screenshots/20260617_231827.376.jpg" target="_blank"><img src="screenshots/20260617_231827.376.jpg" width="31%" alt="界面截图 1"></a>
+  <a href="screenshots/20260619_131432.399.jpg" target="_blank"><img src="screenshots/20260619_131432.399.jpg" width="31%" alt="界面截图 2"></a>
+  <a href="screenshots/20260617_232348.855.jpg" target="_blank"><img src="screenshots/20260617_232348.855.jpg" width="31%" alt="界面截图 3"></a>
+</p>
+
+> 小提示：用 **PS5 自带浏览器** 打开时，"上传"和"下载"按钮是隐藏的（PS5 浏览器不支持）；要用电脑或手机浏览器才能传文件。
+
+---
+
+## 四、六个最常用操作
+
+### 1. 把电脑上的文件传到 PS5
+
+1. 用**电脑或手机**浏览器打开那个网址（不要用 PS5 浏览器）。
+2. 进入你想放到的文件夹。
+3. 点 **上传**，在弹出的列表里选 **上传文件**（可多选）或 **上传文件夹**（整个目录一起传）。
+4. 也可以**直接把文件或文件夹拖进网页**——页脚那行灰字就是提醒这件事的。拖进来后会提示"松开即上传到当前目录"。
+5. 看到全屏进度条就是开始传了，可以随时**取消**。
+
+### 2. 在 PS5 内部搬运文件（比如 U 盘 → 内置存储）
+
+1. 选中要搬的项目 → 点 **复制**（保留原文件）或 **移动**（不保留）。
+2. 进入目标文件夹 → 点 **粘贴**。
+3. 会有几秒到几十秒的"准备中"（它在统计大小和检查目标空间够不够），别急。
+
+### 3. 解压一个压缩包
+
+1. 在列表里找到那个包，点它右边的 **解压**。
+2. 问你"若目标已存在同名文件或目录"时：
+   - **确定** = 同名文件覆盖掉（同名文件夹会合并进去）
+   - **取消** = 只要目标已经有同名东西就**直接失败**（这是默认，最安全）
+3. 如果包是加密的，会弹出密码框，输入密码即可。**密码错了会让你重填，最多 3 次。**
+   - 上传压缩包时如果你选了"上传后自动解压"，加密包**会自己弹密码框**，不用先手动点一次"解压"。
+   - 第一次弹框写的是"此压缩包已加密"（因为还没输过密码）；之后才写"密码不正确"。
+
+> ⚠️ **强烈建议每次解压都新建一个空文件夹作为目标。** 已知问题：往同一个文件夹里**第二次**用"覆盖"解一个含文件夹的压缩包，会失败。换个空文件夹就没事。
+
+### 4. 分卷压缩包怎么解
+
+一个文件被切成好几段的那种（比如 `xxx.part1.rar` / `xxx.part2.rar`，或 `xxx.z01` + `xxx.zip`，或 `xxx.7z.001` …）：
+
+- **RAR：必须点第一个分卷**（`xxx.part1.rar` 或 `xxx.part01.rar`）。点到后面的卷，按钮是灰的，会提示"请改选主卷"。
+- **ZIP / 7z：点第一卷即可**，其余会自动接上。
+- **整卷必须在同一个文件夹里**，少一个都会失败（提示"压缩包损坏或不完整"）。
+
+### 5. 改一个文本文件
+
+点文本文件右边打开编辑器即可。限制：文件 **小于 1 MiB**，且是纯文本（UTF-8）。太大或不是文本会被拒绝。
+
+### 6. 安装 PKG
+
+点 `.pkg` 文件右边的 **安装**，会先显示这个包的标题等信息，确认后提交给系统安装。
+
+---
+
+## 五、解压的"规矩"（为什么有的包不给解）
+
+它不是拿到包就解，而是**先检查**，不符合规矩会直接拒绝。这是为了保护你的 PS5 不被一个恶意压缩包搞崩。默认规矩：
+
+| 规矩 | 上限 |
+|---|---|
+| 包里的文件/文件夹数量 | 20 万个 |
+| 解压后的总大小 | 2 TiB |
+| 单个文件最大 | 512 GiB |
+| 压缩比（解压后 ÷ 压缩包） | 500 倍 |
+| 文件夹最多嵌套多少层 | 32 层 |
+
+**包特别大时**（磁盘上超过 480 GiB），它会问你要不要开「大文件模式」：开了之后上限放宽到 50 万个 / 4 TiB / 单个 1 TiB / 1000 倍。
+
+**还有一条最容易踩的：硬盘要留出大约"两份"空间。** 它是先把东西解到一个临时地方，确认全部成功后才整体搬过去 —— 所以一个解压后 50 GB 的包，你得有大约 100 GB 可用空间。空间不够会直接告诉你"需要 X，可用 Y"。
+
+---
+
+## 六、看到这句话，是什么意思
+
+| 界面上显示 | 说人话 | 怎么办 |
+|---|---|---|
+| **密码错误，或压缩包未使用所提供的密码加密** | 密码不对，或者这个包根本没加密你却填了密码 | 重填（最多 3 次）；确认密码大小写 |
+| **此压缩包已加密，密码不正确** | 同上，重试提示 | 输入正确密码，或取消 |
+| **目标空间不足，需要 X，可用 Y** | 硬盘不够 | 记住要留**两份**空间；删东西或换更大的盘 |
+| **压缩包内单个文件过大** | 包里有个超大文件，超过默认 512 GiB | 出现提示时选「大文件模式」；或拆包 |
+| **压缩比异常（疑似压缩炸弹）** | 一个很小的包声称能解出一大堆东西，被判定为危险 | 基本是恶意包，别解 |
+| **目标已存在同名文件或目录** | 目标位置已经有同名东西了 | 换一个空文件夹（推荐），或在提示时选"确定"覆盖 |
+| **压缩包损坏或不完整** | 包坏了，或分卷少了一卷 | 重新下载/拷贝，确认所有分卷都在同一目录 |
+| **不支持的压缩包** | 不是 ZIP / RAR / 7z，或用了它处理不了的特性 | 在电脑上解好再传 |
+| **压缩包需要的字典超出本机可承受范围** | 极少数用超大设置压的 RAR，PS5 解不动 | 在电脑上用普通设置重新压一次 |
+| **请改选主卷** | 你点的是分卷的后面几卷 | 点第一个分卷（`.part1.rar` / `.part01.rar`） |
+| **有任务正在执行** | 已经有一个活儿在干 | 等它结束，或先取消它 |
+| **操作失败** | 其它错误 | 记下原文，反馈时带上 |
+
+---
+
+## 七、和原版（上游）有什么不一样
+
+这个程序是从开源项目 **owendswang/ps5-web-file-manager** 改来的。下面是和你有关的差别，说人话：
+
+| 对你意味着什么 | 原版（上游 v1.8） | 本版（v1.9.3M） |
+|---|---|---|
+| **要装几个东西** | **两个**：主程序 + 一个上百 MB 的 7-Zip 辅助程序，还得放到固定目录 `/data/wfm/`。**辅助文件丢了，解压功能直接全废** | **就一个文件**，拷上去就能用 |
+| **能解多少种格式** | **约 30 种**（`.tar.gz` `.xz` `.cab` `.iso` 类……） | **3 种**：`.zip` `.rar` `.7z` |
+| **带密码的压缩包** | 靠 7-Zip 支持 | **三种格式都支持**，密码错了会弹框让你重填（最多 3 次） |
+| **RAR 分卷** | 支持 | 支持（要点第一个分卷） |
+| **防"压缩炸弹"/防硬盘写满** | ❌ **没有**，交给 7-Zip 自己看着办 | ✅ 有：压缩比筛查、提前算空间够不够 |
+| **失败后会不会留下一堆半成品** | 会（直接解到目标目录，中断就留在那儿） | 不会：先解到临时地方，全部成功才整体搬过去，失败自动清理 |
+| **程序被重启后，正在解的任务** | 还能接着跑（辅助程序是独立进程） | **会丢**（关掉浏览器再打开还能看到进度，但程序本身重启就没了） |
+| **出错时的提示** | 比较笼统 | 会告诉你具体是哪个文件、差多少字节 |
+| **版本号长什么样** | `v1.8`、`v1.9` 这样纯数字 | **`v1.9.3M`**，末尾多一个 `M` |
+
+### 一句话总结
+
+- **原版赢在"格式多"**：`.tar.gz`、`.xz` 这类它也能解，本版不行。如果你经常遇到这三种以外的格式，原版更方便。
+- **本版赢在"省心和安全"**：一个文件就完事，不会因为你少放一个辅助文件就整个不能用；也不会被一个恶意压缩包写满你的内置存储、或者在半路留一堆垃圾。
+
+### `M` 是什么意思
+
+版本号末尾的 **`M`** = **Modified（改版）**。上游原版是纯数字（如 `v1.8`），所以：
+
+- 看到 **`v1.9.3M`** → 这是本仓的改版
+- 看到 **`v1.9.3`**（没有 M）→ 那不是本仓出的
+
+这个字母会同时出现在：文件名、PS5 启动通知、网页右下角。网页右下角把鼠标**悬停**在版本号上，会弹出说明文字。
+
+---
+
+## 八、怎么确认你装的是哪一版
+
+| 看哪里 | 应该显示 |
+|---|---|
+| 网页右下角 | `v1.9.3M` |
+| PS5 启动时的通知 | 程序名 + `v1.9.3M` + 监听端口 |
+| 浏览器打开 `http://<PS5的IP>:<端口>/api/version` | JSON 里的版本号 = `v1.9.3M` |
+
+**只要界面上显示带 `M` 的版本号，就说明装对了。**
+
+---
+
+## 九、几条重要提醒
+
+1. **解压时别断电、别重启 PS5。** 它为了速度不做逐文件强制落盘，如果在最后搬运阶段断电，可能出现"文件在，但内容不完整"。
+2. **解压前确认空间够**，而且是**两份**（见第五节）。
+3. **每次解压用新的空文件夹**，别往同一个目录连解两次（见第四节第 3 条）。
+4. **删除不可恢复。** 删文件夹会把它里面所有东西都删掉，弹窗会提醒。
+5. **一次只做一件事**，有任务在跑时其它操作会被拒绝。
+6. 这是自制程序。如果遇到 PS5 内核崩溃，请换更新的越狱方式 / ELF 加载器，或回到你常用的稳定方案。
@@ -0,0 +1,26 @@
+/* PS5-only stub for the libgcc CPU model symbols.
+ *
+ * unrar's rijndael.cpp / system.cpp call __builtin_cpu_supports() to pick
+ * AES-NI fast paths. Clang lowers that to a reference on __cpu_model (data)
+ * and __cpu_indicator_init() (function), which the FreeBSD-style PS5
+ * sysroot does not provide (no libgcc). This TU supplies both so the link
+ * succeeds; the detection result is unused because we always build the
+ * portable C path.
+ *
+ * Do NOT add this file to host/linux builds: libstdc++/libgcc already
+ * define __cpu_model there and the symbols would collide. */
+#if defined(__x86_64__) && !defined(__linux__) && !defined(_WIN32)
+
+struct __cpu_model {
+  int __cpu_vendor;
+  int __cpu_type;
+  int __cpu_subtype;
+};
+
+int __cpu_indicator_init(void) {
+  return 0;
+}
+
+struct __cpu_model __cpu_model = { 0, 0, 0 };
+
+#endif
@@ -0,0 +1,31 @@
+/* Stub for the C++ name demangler (__cxa_demangle).
+ *
+ * unrar7 is compiled with C++ exceptions enabled -- dll.cpp catches
+ * RAR_EXIT and std::bad_alloc, unpack.cpp/model.cpp throw bad_alloc -- so
+ * the runtime's __cxa_throw chain holds a reference to __cxa_demangle. That
+ * one reference drags the whole Itanium demangler TU into the link: 607
+ * symbols, ~105 KiB, over 10% of the final ELF (see docs/SIZE-OPTIMIZATION.md).
+ *
+ * __cxa_demangle is only ever reached on the uncaught-exception diagnostic
+ * path (std::terminate printing the exception's type name). Every unrar
+ * exception is caught inside dll.cpp, so that path is unreachable here.
+ * Defining the symbol in our own TU keeps cxa_demangle.o out of the archive
+ * pull -- the linker resolves against ours and never opens the member.
+ *
+ * Returning NULL is the documented "demangle failed" result; the caller
+ * falls back to printing the mangled name. Exception handling itself
+ * (__cxa_throw / __cxa_begin_catch / _Unwind_Resume / __gxx_personality_v0)
+ * is untouched. Applies to both the PS5 and the host/linux builds. */
+#include <stddef.h>
+
+char *__cxa_demangle(const char *mangled, char *buf, size_t *len, int *status) {
+  (void)mangled;
+  (void)buf;
+  (void)len;
+
+  if(status) {
+    *status = -1;
+  }
+
+  return 0;
+}
@@ -1,5 +1,6 @@
 #include "filemgr.h"

+#include <ctype.h>
 #include <errno.h>
 #include <pthread.h>
 #include <stdio.h>
@@ -14,7 +15,9 @@
 #include "json_util.h"
 #include "path_util.h"
 #include "rar_extract.h"
+#include "sevenz_extract.h"
 #include "zip_extract.h"
+#include "zipx_volume.h"

 /* Cancellation callback: stop when the task is asked to cancel. */
 static int
@@ -45,34 +48,10 @@ ends_with_ci(const char *path, const char *suffix) {
  return !strcasecmp(path + path_len - suf_len, suffix);
 }

-/* Pick the right engine by the archive file name. Returns ZIPX_ERR_FORMAT
-   for anything that does not look like a supported archive. */
-static zipx_status_t
-extract_dispatch(file_task_t *task, zipx_conflict_t conflict,
-                const zipx_limits_t *limits, zipx_result_t *result) {
-  if(ends_with_ci(task->src, ".zip")) {
-    return zipx_extract(task->src, task->dst, conflict, limits,
-                        extract_cancel, extract_progress, task, result);
-  }
-  if(ends_with_ci(task->src, ".rar")) {
-    return rar_extract(task->src, task->dst, conflict, limits,
-                       extract_cancel, extract_progress, task, result);
-  }
-  {
-    size_t len = strlen(task->src);
-    if(len > sizeof(result->detail) - 1) {
-      len = sizeof(result->detail) - 1;
-    }
-    memcpy(result->detail, task->src, len);
-    result->detail[len] = 0;
-    snprintf(result->message, sizeof(result->message),
-             "unsupported archive format (only .zip and .rar are accepted)");
-    return ZIPX_ERR_UNSUPPORTED;
-  }
-}
-
 /* Progress callback. The engine already throttles reports (200 ms / 1 MiB),
-   so we can forward each report straight into the shared task state. */
+   so we can forward each report straight into the shared task state.
+   Defined before extract_dispatch() so the dispatcher's call site compiles
+   cleanly under -Werror=implicit-function-declaration. */
 static void
 extract_progress(void *userdata, const zipx_progress_t *p) {
  file_task_t *task = userdata;
@@ -91,6 +70,166 @@ extract_progress(void *userdata, const zipx_progress_t *p) {
              delta, NULL);
 }

+/* Case-insensitive substring search (strcasestr is not available on MinGW). */
+static const char *
+ci_strstr(const char *hay, const char *needle) {
+  size_t nlen = strlen(needle);
+  const char *p;
+
+  if(!nlen) {
+    return hay;
+  }
+  for(p = hay; *p; p++) {
+    size_t i;
+
+    for(i = 0; i < nlen; i++) {
+      if(!p[i] ||
+         tolower((unsigned char)p[i]) != tolower((unsigned char)needle[i])) {
+        break;
+      }
+    }
+    if(i == nlen) {
+      return p;
+    }
+  }
+  return NULL;
+}
+
+static void
+extract_set_detail(zipx_result_t *result, const char *text) {
+  size_t len = strlen(text);
+
+  if(len > sizeof(result->detail) - 1) {
+    len = sizeof(result->detail) - 1;
+  }
+  memcpy(result->detail, text, len);
+  result->detail[len] = 0;
+}
+
+/* Which engine a volume set belongs to, decided from the member names:
+   0 zip, 1 rar, 2 7z, -1 unknown. */
+static int
+volume_format(const zipx_volume_t *vol) {
+  static const char *const exts[] = { ".zip", ".rar", ".7z", NULL };
+  const char *best = NULL;
+  int best_kind = -1;
+  int i;
+  int j;
+
+  for(i = 0; i < vol->count; i++) {
+    for(j = 0; exts[j]; j++) {
+      const char *hit = ci_strstr(vol->paths[i], exts[j]);
+
+      if(hit && (!best || hit > best)) {
+        best = hit;
+        best_kind = j;
+      }
+    }
+  }
+  return best_kind;
+}
+
+/* Removes the source archive once a task is done with it. For a split set
+   every volume has to go: leaving the other parts behind would leave the user
+   with something that still looks like a usable archive. */
+static void
+remove_source_archives(const char *path) {
+  zipx_volume_t vol;
+  char *err = NULL;
+  int rc = zipx_volume_detect(path, &vol, &err);
+  int i;
+
+  free(err);
+  if(rc > 0) {
+    for(i = 0; i < vol.count; i++) {
+      unlink(vol.paths[i]);
+    }
+    zipx_volume_free(&vol);
+    return;
+  }
+  unlink(path);
+}
+
+/* Pick the right engine by the archive file name. Returns ZIPX_ERR_FORMAT
+   for anything that does not look like a supported archive. */
+static zipx_status_t
+extract_dispatch(file_task_t *task, zipx_conflict_t conflict,
+                const zipx_limits_t *limits, zipx_result_t *result) {
+  zipx_volume_t vol;
+  char *vol_err = NULL;
+  int vrc = zipx_volume_detect(task->src, &vol, &vol_err);
+  int kind = vrc > 0 ? volume_format(&vol) : -1;
+
+  if(vrc < 0) {
+    /* A broken set gets the precise reason (which volume is missing, ...)
+       instead of a generic "unsupported format". */
+    extract_set_detail(result, task->src);
+    snprintf(result->message, sizeof(result->message), "%s",
+             vol_err ? vol_err : "the archive volumes are incomplete");
+    free(vol_err);
+    return ZIPX_ERR_OPEN;
+  }
+  free(vol_err);
+  if(vrc > 0) {
+    zipx_status_t status;
+
+    if(kind == 0) {
+      status = zipx_extract(task->src, task->dst, conflict, limits,
+                            extract_cancel, extract_progress, task,
+                            task->extract_password[0] ? task->extract_password
+                                                      : NULL,
+                            result);
+    } else if(kind == 1) {
+      /* unrar chains its own volume naming (x.part1.rar); a byte contiguous
+         set named x.rar.001 cannot be handed to it as-is. */
+      extract_set_detail(result, task->src);
+      snprintf(result->message, sizeof(result->message),
+               "RAR volume sets named 'x.rar.001' are not supported yet "
+               "(rename the parts to 'x.part1.rar', 'x.part2.rar', ...)");
+      status = ZIPX_ERR_UNSUPPORTED;
+    } else if(kind == 2) {
+      status = sevenz_extract(task->src, task->dst, conflict, limits,
+                              extract_cancel, extract_progress, task,
+                              task->extract_password[0] ? task->extract_password
+                                                        : NULL,
+                              result);
+    } else {
+      extract_set_detail(result, task->src);
+      snprintf(result->message, sizeof(result->message),
+               "unsupported split archive (only .zip, .rar and .7z volumes "
+               "are recognised)");
+      status = ZIPX_ERR_UNSUPPORTED;
+    }
+    zipx_volume_free(&vol);
+    return status;
+  }
+  if(ends_with_ci(task->src, ".zip")) {
+    return zipx_extract(task->src, task->dst, conflict, limits,
+                        extract_cancel, extract_progress, task,
+                        task->extract_password[0] ? task->extract_password
+                                                  : NULL,
+                        result);
+  }
+  if(ends_with_ci(task->src, ".rar")) {
+    return rar_extract(task->src, task->dst, conflict, limits,
+                       extract_cancel, extract_progress, task,
+                       task->extract_password[0] ? task->extract_password
+                                                 : NULL,
+                       result);
+  }
+  if(ends_with_ci(task->src, ".7z")) {
+    return sevenz_extract(task->src, task->dst, conflict, limits,
+                          extract_cancel, extract_progress, task,
+                          task->extract_password[0] ? task->extract_password
+                                                    : NULL,
+                          result);
+  }
+  extract_set_detail(result, task->src);
+  snprintf(result->message, sizeof(result->message),
+           "unsupported archive format (only .zip, .rar and .7z are accepted)");
+  return ZIPX_ERR_UNSUPPORTED;
+}
+
 static const char *
 extract_error_code(zipx_status_t status) {
  switch(status) {
@@ -106,10 +245,12 @@ extract_error_code(zipx_status_t status) {
  case ZIPX_ERR_LIMIT_RATIO: return "extract_ratio";
  case ZIPX_ERR_LIMIT_DEPTH: return "extract_too_deep";
  case ZIPX_ERR_LIMIT_NAME: return "extract_name_too_long";
+  case ZIPX_ERR_LIMIT_DICT: return "extract_dict_too_large";
  case ZIPX_ERR_CONFLICT: return "extract_conflict";
  case ZIPX_ERR_SPACE: return "no_space";
  case ZIPX_ERR_IO: return "extract_io";
  case ZIPX_ERR_CRC: return "extract_crc";
+  case ZIPX_ERR_PASSWORD: return "extract_password";
  default: return "extract_failed";
  }
 }
@@ -168,7 +309,7 @@ extract_worker(void *arg) {

    /* Only delete the source archive when this task owns it (upload flow). */
    if(task->extract_remove_source && task->src[0]) {
-      unlink(task->src);
+      remove_source_archives(task->src);
    }
    pthread_mutex_lock(&g_tasks_lock);
    task->state = TASK_DONE;
@@ -196,6 +337,7 @@ api_extract(struct MHD_Connection *conn, const char *body, size_t body_size) {
  char *conflict_str = body_form_value(body, body_size, "conflict");
  char *remove_str = body_form_value(body, body_size, "remove_source");
  char *large_str = body_form_value(body, body_size, "large");
+  char *password_str = body_form_value(body, body_size, "password");
  extract_conflict_t conflict = EXTRACT_CONFLICT_FAIL;
  int remove_source = remove_str && !strcmp(remove_str, "1");
  int large = large_str && !strcmp(large_str, "1");
@@ -204,7 +346,8 @@ api_extract(struct MHD_Connection *conn, const char *body, size_t body_size) {
  struct stat st;

  if(!path || !dst_dir || !path[0] || !dst_dir[0]) {
-    free(path); free(dst_dir); free(conflict_str); free(remove_str); free(large_str);
+    free(path); free(dst_dir); free(conflict_str); free(remove_str);
+    free(large_str); free(password_str);
    return send_json_error(conn, MHD_HTTP_BAD_REQUEST, "invalid path");
  }
  if(conflict_str) {
@@ -213,23 +356,27 @@ api_extract(struct MHD_Connection *conn, const char *body, size_t body_size) {
    } else if(!strcmp(conflict_str, "merge")) {
      conflict = EXTRACT_CONFLICT_MERGE;
    } else if(strcmp(conflict_str, "fail")) {
-      free(path); free(dst_dir); free(conflict_str); free(remove_str); free(large_str);
+      free(path); free(dst_dir); free(conflict_str); free(remove_str);
+      free(large_str); free(password_str);
      return send_json_error(conn, MHD_HTTP_BAD_REQUEST, "invalid conflict");
    }
  }
  if(stat(path, &st) || !S_ISREG(st.st_mode)) {
-    free(path); free(dst_dir); free(conflict_str); free(remove_str); free(large_str);
+    free(path); free(dst_dir); free(conflict_str); free(remove_str);
+    free(large_str); free(password_str);
    return send_json_error(conn, MHD_HTTP_BAD_REQUEST, "file not found");
  }
  if(stat(dst_dir, &st) || !S_ISDIR(st.st_mode)) {
-    free(path); free(dst_dir); free(conflict_str); free(remove_str); free(large_str);
+    free(path); free(dst_dir); free(conflict_str); free(remove_str);
+    free(large_str); free(password_str);
    return send_json_error(conn, MHD_HTTP_BAD_REQUEST,
                           "destination must be a directory");
  }

  task = calloc(1, sizeof(*task));
  if(!task) {
-    free(path); free(dst_dir); free(conflict_str); free(remove_str); free(large_str);
+    free(path); free(dst_dir); free(conflict_str); free(remove_str);
+    free(large_str); free(password_str);
    return send_json_error(conn, MHD_HTTP_INTERNAL_SERVER_ERROR,
                           "out of memory");
  }
@@ -239,6 +386,14 @@ api_extract(struct MHD_Connection *conn, const char *body, size_t body_size) {
  task->extract_conflict = (int)conflict;
  task->extract_remove_source = remove_source;
  task->extract_large = large;
+  /* The size cap (256 bytes, including the NUL) leaves room for a 255-codepoint
+     UTF-8 password without overflowing the field or letting a malicious header
+     run away with it.  Anything longer is truncated, which is what a sane user
+     will never hit but matches the storage size of the field. */
+  if(password_str) {
+    snprintf(task->extract_password, sizeof(task->extract_password), "%s",
+             password_str);
+  }
  snprintf(task->src, sizeof(task->src), "%s", path);
  snprintf(task->dst, sizeof(task->dst), "%s", dst_dir);
  task->created_at = time(NULL);
@@ -249,7 +404,8 @@ api_extract(struct MHD_Connection *conn, const char *body, size_t body_size) {
  if(has_active_task_locked()) {
    pthread_mutex_unlock(&g_tasks_lock);
    free_task(task);
-    free(path); free(dst_dir); free(conflict_str); free(remove_str); free(large_str);
+    free(path); free(dst_dir); free(conflict_str); free(remove_str);
+    free(large_str); free(password_str);
    return send_json_error(conn, MHD_HTTP_CONFLICT, "another task is running");
  }
  task->id = g_next_task_id++;
@@ -263,7 +419,8 @@ api_extract(struct MHD_Connection *conn, const char *body, size_t body_size) {
    pthread_detach(task->thread);
  }

-  free(path); free(dst_dir); free(conflict_str); free(remove_str); free(large_str);
+  free(path); free(dst_dir); free(conflict_str); free(remove_str);
+  free(large_str); free(password_str);
  strbuf_printf(&b, "{\"ok\":true,\"task_id\":%lu}", task->id);
  return send_buffer(conn, MHD_HTTP_OK, b.data, "application/json");
 }
@@ -2399,6 +2399,7 @@ filemgr_api_request(struct MHD_Connection *conn, const char *url,
  if(!strcmp(url, "/api/list")) return api_list(conn);
  if(!strcmp(url, "/api/tasks")) return api_tasks(conn);
  if(!strcmp(url, "/api/space")) return api_space(conn);
+  if(!strcmp(url, "/api/version")) return api_version(conn);
  if(!strcmp(url, "/api/cancel")) return api_cancel(conn);
  if(!strcmp(url, "/api/exit")) return api_exit(conn);
  if(!strcmp(url, "/api/copy")) return api_copy(conn, body, body_size);
@@ -59,6 +59,11 @@ typedef struct file_task {
  int extract_conflict;
  int extract_remove_source;
  int extract_large;
+  /* UTF-8 password for archives that encrypt their streams (7zAES, RAR5 AES).
+     Empty means "try without one"; the engine returns ZIPX_ERR_PASSWORD for
+     an archive that needs one, and the web UI prompts and retries.  The
+     length is bounded so a runaway header field cannot overflow task memory. */
+  char extract_password[256];
  unsigned long long speed_sample_done;
  struct timespec speed_sample_time;
  task_eta_sample_t eta_samples[ETA_SAMPLE_SLOTS];
@@ -128,6 +133,7 @@ enum MHD_Result api_download_prepare(struct MHD_Connection *conn,
 enum MHD_Result api_download(struct MHD_Connection *conn);
 enum MHD_Result api_list(struct MHD_Connection *conn);
 enum MHD_Result api_space(struct MHD_Connection *conn);
+enum MHD_Result api_version(struct MHD_Connection *conn);
 enum MHD_Result api_text(struct MHD_Connection *conn);
 enum MHD_Result api_text_create(struct MHD_Connection *conn);
 enum MHD_Result api_text_save(struct MHD_Connection *conn, const char *body,
@@ -1,3 +1,23 @@
+/* PKG preview -- the /api/pkg_info and /api/pkg_icon endpoints.
+ *
+ * Independent C99 implementation of the PS5 .pkg container layout (entry table
+ * + PARAM.SFO + param.json + ICON0), written for this project.
+ *
+ * NOT derived from cy33hc/ps5-ezremote-client, which the README credits for the
+ * same feature. That project is GPL-2.0-only -- its sources carry no "or later"
+ * notice -- and therefore cannot be combined with this GPL-3.0 codebase at all.
+ * The two share nothing but the on-disk format facts: the SFO magic
+ * 0x46535000, the 20-byte header / 16-byte entry layout, and the key/value
+ * offset indirection. Those are dictated by the format and no implementation
+ * can avoid them. Everything else differs -- this file is C where that one is
+ * C++, it parses the .pkg entry table and param.json (upstream has no .pkg
+ * parser), and it tokenizes JSON itself (upstream links json-c).
+ *
+ * Provenance record and the line-by-line comparison: docs/REWRITE-FEASIBILITY.md
+ * section 2.2. Revisit that note if this file is ever rewritten or the upstream
+ * licence wording changes.
+ */
+
 #include "pkg_info.h"

 #include <errno.h>
@@ -1,18 +1,28 @@
 /* Safe RAR extraction engine used by the /api/extract task.
-   Wraps the vendored dmc_unrar library (https://github.com/DrMcCoy/dmc_unrar).
+   Wraps the vendored rarlab UnRAR 7.x library (third_party/unrar7) through
+   its C-compatible DLL API (dll.hpp / unrar_c_api.h facade).

   The publish / staging / rollback / normalize-name / dedup machinery is
   mirrored from zip_extract.c so that any consumer of zipx_result_t gets a
   consistent error and progress contract regardless of archive format.

-   See third_party/unrar/VENDORED.md for what dmc_unrar does and does not
-   support (single-volume RAR only; multi-volume and encrypted are
-   rejected up front). */
+   Backend notes (v1.9, unrar 7.20.1):
+     * RAR4 and RAR5 (any compression version, incl. WinRAR 6/7 "v6")
+       single-volume archives.
+     * Multi-volume archives: unrar auto-merges subsequent volumes by name
+       pattern when all .partNN.rar files sit next to the opened volume.
+     * Encrypted archives (`-p` data encryption and `-hp` header encryption):
+       the password is handed to the engine via RARSetPassword immediately
+       after RAROpenArchiveEx and before the first RARReadHeaderEx, which is
+       the order unrar needs to decrypt a RAR5 header. A missing or wrong
+       password surfaces as ZIPX_ERR_PASSWORD.
+
+   See third_party/unrar7/VENDORED.md for the full integration notes. */

 #include "rar_extract.h"
 #include "zip_extract.h"  /* for the shared status / progress / limits API */

-#include "dmc_unrar_api.h"  /* facade — links against dmc_unrar.o at build time */
+#include "unrar_c_api.h"  /* facade — links against the unrar7 static lib at build time */

 #include <dirent.h>
 #include <errno.h>
@@ -28,11 +38,11 @@
 #include <time.h>
 #include <unistd.h>

-/* (intentionally no `#include "dmc_unrar.c"` here — that would pull the
-   library into this translation unit, where the host test build's
-   tests/posix_compat.h renames `open` / `close` to `wfm_open` / `wfm_close`
-   and breaks dmc_unrar's `dmc_unrar_io_handler` struct member access.
-   dmc_unrar.c is compiled as its own translation unit and joined at link.) */
+/* (intentionally no `#include "rar.hpp"` etc. here — those are C++ headers.
+   rar_extract.c talks to unrar exclusively through the extern "C" DLL API in
+   dll.hpp, and the unrar sources are compiled as their own translation units
+   (RARDLL mode) and joined at link time. This keeps the host test build's
+   tests/posix_compat.h renames (open->wfm_open) from leaking into unrar.) */

 #ifndef O_CLOEXEC
 #define O_CLOEXEC 0
@@ -54,6 +64,9 @@ typedef struct {
  zipx_progress_fn progress;
  void *userdata;
  zipx_result_t *result;
+  /* NULL when no password was supplied. Owned by the caller for the whole
+     call; RARSetPassword copies it into the engine, so it never dangles. */
+  const char *password;
  uint64_t entries_total;
  uint64_t entries_done;
  uint64_t bytes_total;
@@ -61,6 +74,13 @@ typedef struct {
  uint64_t files_created;
  uint64_t dirs_created;
  uint64_t progress_floor;
+  /* Set by the UCM_LARGEDICT callback only: the dictionary the archive asks
+     for and the limit we refuse above, both in KiB (0 = never raised, i.e. the
+     archive's dictionary was within Cmd->WinSizeLimit). unrar hands these over
+     as p1/p2, so the refusal can name the real numbers instead of blaming the
+     entry that happened to be in flight. */
+  uint64_t dict_kb;
+  uint64_t dict_limit_kb;
  struct timespec last_report;
  char staging[ZIPX_PATH_MAX];
  char **created;
@@ -288,7 +308,7 @@ nameset_put(rarx_nameset_t *set, uint64_t h, int is_dir) {
 /**************************************************************************
 * entry name validation (mirrors zip_extract.c::normalize_name but the
 * RAR side does not have a trailing separator, so dir entries are only
- * detected via dmc_unrar_file_is_directory()).
+ * detected via the RHDF_DIRECTORY header flag).
 **************************************************************************/

 static int
@@ -300,7 +320,11 @@ normalize_name(const char *in, char *out, size_t out_size, int *is_dir,
  size_t seg_len = 0;
  uint32_t levels = 0;

-  *is_dir = 0;
+  /* NOTE: is_dir is owned by the caller — unrar announces directories via
+     the RHDF_DIRECTORY header flag, not via a trailing separator, so we
+     must NOT clear it here (a stray `*is_dir = 0` previously turned every
+     directory entry into a file and tripped the duplicate detector when an
+     explicit directory header followed files beneath it). */
  *depth = 0;
  if(!in_len) {
    return rarx_fail(c, ZIPX_ERR_UNSAFE_NAME, in, "empty entry name");
@@ -422,77 +446,63 @@ nameset_check_duplicate(rarx_nameset_t *set, const char *name, int is_dir,
 }

 /**************************************************************************
- * dmc_unrar -> zipx error translation
+ * unrar DLL error -> zipx error translation
 **************************************************************************/

 static int
-rar_translate_error(dmc_unrar_return code, const char *detail,
-                    rarx_ctx_t *c) {
+rar_translate_error(int code, const char *detail, rarx_ctx_t *c) {
  switch(code) {
-  case DMC_UNRAR_OK:
+  case ERAR_SUCCESS:
    return ZIPX_OK;

-  /* Archive-open level (the user will see this when they upload a
-     multi-volume or fully-encrypted RAR — let them know it is on purpose). */
-  case DMC_UNRAR_ARCHIVE_UNSUPPORTED_VOLUMES:
-    return rarx_fail(c, ZIPX_ERR_UNSUPPORTED, detail,
-                     "multi-volume RAR archives are not supported; "
-                     "please extract on a PC first");
-
-  case DMC_UNRAR_ARCHIVE_UNSUPPORTED_ENCRYPTED:
-    return rarx_fail(c, ZIPX_ERR_UNSUPPORTED, detail,
-                     "encrypted RAR archives are not supported; "
-                     "please extract on a PC first");
-
-  /* Per-file (still surfaced up-front during scan). */
-  case DMC_UNRAR_FILE_UNSUPPORTED_ENCRYPTED:
-    return rarx_fail(c, ZIPX_ERR_UNSUPPORTED, detail,
-                     "encrypted RAR entries are not supported");
-
-  case DMC_UNRAR_FILE_UNSUPPORTED_SPLIT:
-    return rarx_fail(c, ZIPX_ERR_UNSUPPORTED, detail,
-                     "split RAR entries are not supported");
-
-  case DMC_UNRAR_FILE_UNSUPPORTED_LINK:
-    return rarx_fail(c, ZIPX_ERR_SPECIAL, detail, "symbolic link entry");
-
-  case DMC_UNRAR_FILE_UNSUPPORTED_VERSION:
-  case DMC_UNRAR_FILE_UNSUPPORTED_METHOD:
-    return rarx_fail(c, ZIPX_ERR_UNSUPPORTED, detail,
-                     "RAR entry uses an unsupported compression method");
-
-  case DMC_UNRAR_FILE_UNSUPPORTED_LARGE:
-    return rarx_fail(c, ZIPX_ERR_LIMIT_FILE, detail,
-                     "RAR entry is larger than the supported maximum");
-
-  case DMC_UNRAR_ARCHIVE_EMPTY:
-    return rarx_fail(c, ZIPX_ERR_FORMAT, detail, "empty RAR archive");
-
-  case DMC_UNRAR_ARCHIVE_UNSUPPORTED_ANCIENT:
-    return rarx_fail(c, ZIPX_ERR_UNSUPPORTED, detail,
-                     "RAR 1.4 / 1.5 archives are not supported");
-
-  case DMC_UNRAR_ARCHIVE_NOT_RAR:
-    return rarx_fail(c, ZIPX_ERR_FORMAT, detail,
-                     "not a RAR archive");
-
-  case DMC_UNRAR_OPEN_FAIL:
+  /* The unrar engine handles multi-volume automatically (it merges the
+     next .partNN.rar by name); a missing next volume surfaces as EOPEN. */
+  case ERAR_EOPEN:
    return rarx_fail(c, ZIPX_ERR_OPEN, detail, "%s", strerror(errno));

-  case DMC_UNRAR_READ_FAIL:
-  case DMC_UNRAR_WRITE_FAIL:
-  case DMC_UNRAR_SEEK_FAIL:
+  case ERAR_ECREATE:
+  case ERAR_ECLOSE:
+  case ERAR_EREAD:
+  case ERAR_EWRITE:
    return rarx_fail(c, ZIPX_ERR_IO, detail, "%s", strerror(errno));

-  case DMC_UNRAR_FILE_CRC32_FAIL:
-    return rarx_fail(c, ZIPX_ERR_CRC, detail, "CRC32 mismatch");
+  case ERAR_MISSING_PASSWORD:
+  case ERAR_BAD_PASSWORD:
+    /* The archive needs a password we do not have, or the one supplied was
+       wrong. ZIPX_ERR_PASSWORD lets the caller prompt and retry. */
+    return rarx_fail(c, ZIPX_ERR_PASSWORD, detail,
+                     "the archive is encrypted and the password is missing "
+                     "or wrong");

-  case DMC_UNRAR_INVALID_DATA:
-  case DMC_UNRAR_NO_ALLOC:
-  case DMC_UNRAR_ALLOC_FAIL:
-  case DMC_UNRAR_ARCHIVE_IS_NULL:
-  case DMC_UNRAR_ARCHIVE_NOT_CLEARED:
-  case DMC_UNRAR_ARCHIVE_MISSING_FIELDS:
+  case ERAR_SMALL_BUF:
+    return rarx_fail(c, ZIPX_ERR_LIMIT_NAME, detail, "name buffer is too small");
+
+  case ERAR_LARGE_DICT: {
+    /* Not "entry too large": the *dictionary* is, and that is a property of the
+       archive (RAR7 headers can ask for up to 64 GiB), not of the entry that
+       happened to be in flight. Report both numbers; unrar gave us exactly
+       these when it asked. */
+    char need[96];
+
+    if(c->dict_kb) {
+      snprintf(need, sizeof(need), "%llu MiB (limit %llu MiB)",
+               (unsigned long long)(c->dict_kb / 1024),
+               (unsigned long long)(c->dict_limit_kb / 1024));
+    } else {
+      snprintf(need, sizeof(need), "more than 4096 MiB");
+    }
+    return rarx_fail(c, ZIPX_ERR_LIMIT_DICT, need,
+                     "the archive needs a dictionary larger than this build "
+                     "supports (%s)", need);
+  }
+
+  case ERAR_BAD_DATA:
+    return rarx_fail(c, ZIPX_ERR_CRC, detail, "checksum mismatch in entry data");
+
+  case ERAR_BAD_ARCHIVE:
+  case ERAR_UNKNOWN_FORMAT:
+  case ERAR_UNKNOWN:
+  case ERAR_NO_MEMORY:
  default:
    return rarx_fail(c, ZIPX_ERR_FORMAT, detail,
                     "invalid or corrupt RAR archive");
@@ -532,15 +542,6 @@ path_parent(const char *path, char *out, size_t out_size) {
  return 0;
 }

-static void
-chmod_0777_fd(int fd) {
-  int err = errno;
-
-  if(fchmod(fd, 0777)) {
-    errno = err;
-  }
-}
-
 static int
 make_staging(rarx_ctx_t *c, const char *parent) {
  unsigned int attempt;
@@ -617,57 +618,6 @@ rollback_published(rarx_ctx_t *c) {
  }
 }

-/* mkdir -p: ensures every segment below root_fd exists. Returns the open
-   descriptor for the deepest directory. */
-static int
-open_parent_dirs(int root_fd, const char *rel, rarx_ctx_t *c) {
-  char buf[ZIPX_PATH_MAX];
-  int fd = root_fd;
-  char *seg;
-  char *save = NULL;
-
-  if(strlen(rel) >= sizeof(buf)) {
-    rarx_fail(c, ZIPX_ERR_LIMIT_NAME, rel, "path is too long");
-    return -1;
-  }
-  strcpy(buf, rel);
-
-  for(seg = strtok_r(buf, "/", &save); seg; seg = strtok_r(NULL, "/", &save)) {
-    int next;
-
-    if(!mkdirat(fd, seg, 0777)) {
-      next = openat(fd, seg, O_RDONLY | O_DIRECTORY | O_NOFOLLOW | O_CLOEXEC);
-      if(next >= 0) {
-        chmod_0777_fd(next);
-        c->dirs_created++;
-      }
-    } else if(errno == EEXIST) {
-      next = openat(fd, seg, O_RDONLY | O_DIRECTORY | O_NOFOLLOW | O_CLOEXEC);
-    } else {
-      rarx_fail(c, ZIPX_ERR_IO, rel, "cannot create directory '%s': %s", seg,
-               strerror(errno));
-      if(fd != root_fd) {
-        close(fd);
-      }
-      return -1;
-    }
-
-    if(next < 0) {
-      rarx_fail(c, ZIPX_ERR_IO, rel, "cannot open directory '%s': %s", seg,
-               strerror(errno));
-      if(fd != root_fd) {
-        close(fd);
-      }
-      return -1;
-    }
-    if(fd != root_fd) {
-      close(fd);
-    }
-    fd = next;
-  }
-  return fd;
-}
-
 /**************************************************************************
 * scan phase
 **************************************************************************/
@@ -695,74 +645,71 @@ check_space(rarx_ctx_t *c, const char *target) {
 }

 static int
-scan_archive(dmc_unrar_archive *rar, rarx_ctx_t *c) {
+scan_archive(HANDLE hArc, rarx_ctx_t *c) {
  rarx_nameset_t set;
-  dmc_unrar_size_t i;
-  dmc_unrar_size_t total;
  int ret = 0;

  if(nameset_init(&set, 4096)) {
    return rarx_fail(c, ZIPX_ERR_INTERNAL, NULL, "out of memory");
  }

-  total = dmc_unrar_get_file_count(rar);
-  for(i = 0; i < total; i++) {
+  for(;;) {
+    struct RARHeaderDataEx hdr;
+    uint64_t uncomp;
    char name[ZIPX_PATH_MAX];
-    char *name_buf;
-    dmc_unrar_size_t name_size;
    int is_dir;
    uint32_t depth = 0;
-    const dmc_unrar_file *info;
-    dmc_unrar_return supported;
+    int rc;

-    info = dmc_unrar_get_file_stat(rar, i);
-    if(!info) {
-      ret = rarx_fail(c, ZIPX_ERR_FORMAT, NULL, "cannot read entry header");
+    memset(&hdr, 0, sizeof(hdr));
+    rc = RARReadHeaderEx(hArc, &hdr);
+    if(rc == ERAR_END_ARCHIVE) {
      break;
    }
-    supported = dmc_unrar_file_is_supported(rar, i);
-    if(supported != DMC_UNRAR_OK) {
-      /* is_supported() already returns ZIPX-mapped error via a temporary */
-      char detail[64];
-      snprintf(detail, sizeof(detail), "entry %llu",
-               (unsigned long long)i);
-      rarx_fail(c, ZIPX_ERR_UNSUPPORTED, detail, "%s",
-                dmc_unrar_strerror(supported));
-      ret = (int)c->result->status;
-      break;
-    }
-    is_dir = dmc_unrar_file_is_directory(rar, i) ? 1 : 0;
-
-    /* First call to learn the required size, second to fill the buffer. */
-    name_size = dmc_unrar_get_filename(rar, i, NULL, 0);
-    if(!name_size) {
-      ret = rarx_fail(c, ZIPX_ERR_FORMAT, NULL,
-                      "cannot read entry name");
-      break;
-    }
-    name_buf = malloc(name_size);
-    if(!name_buf) {
-      ret = rarx_fail(c, ZIPX_ERR_INTERNAL, NULL, "out of memory");
-      break;
-    }
-    if(dmc_unrar_get_filename(rar, i, name_buf, name_size) != name_size) {
-      free(name_buf);
-      ret = rarx_fail(c, ZIPX_ERR_FORMAT, NULL,
-                      "truncated entry name");
-      break;
-    }
-    /* dmc_unrar does not guarantee NUL termination; force it. */
-    name_buf[name_size - 1] = 0;
-    /* RAR stores UTF-8 encoded names. Replace any non-UTF-8 sequence with
-       '?' to keep the downstream string well-formed. */
-    dmc_unrar_unicode_make_valid_utf8(name_buf);
-
-    if(normalize_name(name_buf, name, sizeof(name), &is_dir, &depth, c)) {
-      free(name_buf);
+    if(rc != ERAR_SUCCESS) {
+      rar_translate_error(rc, NULL, c);
      ret = -1;
      break;
    }
-    free(name_buf);
+
+    /* unrar hands out the header name as a NUL-terminated string
+       (UTF-8 on the PS5 / POSIX build). */
+    if(hdr.FileName[0] == 0) {
+      ret = rarx_fail(c, ZIPX_ERR_FORMAT, NULL, "empty entry name");
+      break;
+    }
+    is_dir = (hdr.Flags & RHDF_DIRECTORY) ? 1 : 0;
+
+    /* Encrypted entries are fine as long as a password is in play: the engine
+       decrypts them during RARProcessFile once RARSetPassword has run. With no
+       password, fail here — before anything is written to staging — so the
+       caller can prompt and retry. */
+    if((hdr.Flags & RHDF_ENCRYPTED) && !c->password) {
+      ret = rarx_fail(c, ZIPX_ERR_PASSWORD, hdr.FileName,
+                      "the archive is encrypted and no password was supplied");
+      break;
+    }
+
+    /* Multi-volume: a file spanning volumes is presented as several header
+       segments with the SAME name. Segments after the first carry
+       RHDF_SPLITBEFORE; they must drive the engine forward (SKIP) but must
+       not be counted, deduped or size-accumulated again. The first segment
+       already carries the full file size. */
+    if(hdr.Flags & RHDF_SPLITBEFORE) {
+      rc = RARProcessFile(hArc, RAR_SKIP, NULL, NULL);
+      if(rc != ERAR_SUCCESS && rc != ERAR_END_ARCHIVE) {
+        ret = -1;
+        rar_translate_error(rc, hdr.FileName, c);
+        break;
+      }
+      continue;
+    }
+
+    if(normalize_name(hdr.FileName, name, sizeof(name), &is_dir, &depth, c)) {
+      ret = -1;
+      break;
+    }
+    (void)depth;

    if(nameset_check_duplicate(&set, name, is_dir, c) ||
       nameset_add_path(&set, name, is_dir, c)) {
@@ -771,7 +718,7 @@ scan_archive(dmc_unrar_archive *rar, rarx_ctx_t *c) {
    }

    if(!is_dir) {
-      uint64_t uncomp = info->uncompressed_size;
+      uncomp = (uint64_t)hdr.UnpSizeHigh << 32 | hdr.UnpSize;

      if(uncomp > c->limits.max_file_bytes) {
        ret = rarx_fail(c, ZIPX_ERR_LIMIT_FILE, name,
@@ -779,8 +726,6 @@ scan_archive(dmc_unrar_archive *rar, rarx_ctx_t *c) {
                       (unsigned long long)c->limits.max_file_bytes);
        break;
      }
-      /* RAR headers do not reliably expose compressed_size for all formats,
-         so the safe compression-ratio check is skipped. */
      if(uncomp >= c->limits.max_total_bytes ||
         c->bytes_total > c->limits.max_total_bytes - uncomp) {
        ret = rarx_fail(c, ZIPX_ERR_LIMIT_TOTAL, name,
@@ -805,6 +750,17 @@ scan_archive(dmc_unrar_archive *rar, rarx_ctx_t *c) {
      }
      report(c, ZIPX_PHASE_SCAN, name, 0);
    }
+
+    /* Advance to the next file header (also drives multi-volume merges). */
+    rc = RARProcessFile(hArc, RAR_SKIP, NULL, NULL);
+    if(rc != ERAR_SUCCESS) {
+      if(rc != ERAR_END_ARCHIVE) {
+        ret = -1;
+        rar_translate_error(rc, name, c);
+        break;
+      }
+      break;
+    }
  }

  nameset_free(&set);
@@ -815,175 +771,112 @@ scan_archive(dmc_unrar_archive *rar, rarx_ctx_t *c) {
 * extract phase
 **************************************************************************/

-/* dmc_unrar_extract_file_to_path() opens the destination file with fopen()
-   without creating parent directories. We always call it against an
-   already-prepared full path inside the staging tree. */
-static int
-extract_one(dmc_unrar_archive *rar, rarx_ctx_t *c, int root_fd,
-            const char *name, dmc_unrar_size_t index, uint64_t declared) {
-  char *full_path;
-  char dir_part[ZIPX_PATH_MAX];
-  char base[ZIPX_PATH_MAX];
-  char *slash;
-  int dir_fd;
-  dmc_unrar_return dr;
-  struct stat st;
-  uint64_t before_bytes;
-  int ret = 0;
+/* unrar invokes this for every decompressed chunk while RARProcessFile is
+   extracting an entry to disk. Without it the engine could only account
+   bytes_done after a whole entry completed, which froze the progress bar
+   for the entire duration of a multi-GB entry spanning several volumes.

-  snprintf(dir_part, sizeof(dir_part), "%s", name);
-  slash = strrchr(dir_part, '/');
-  if(slash) {
-    snprintf(base, sizeof(base), "%s", slash + 1);
-    *slash = 0;
-  } else {
-    snprintf(base, sizeof(base), "%s", name);
-    dir_part[0] = 0;
-  }
-  if(!base[0]) {
-    return rarx_fail(c, ZIPX_ERR_UNSAFE_NAME, name, "empty file name");
+   Returning -1 is how unrar aborts a run, but the break path is only armed
+   when console break handling is enabled, which never happens in DLL mode —
+   so we always return 0 and cancellation stays entry-granular.
+
+   The same callback is the only channel through which unrar asks permission
+   for an oversized dictionary (UCM_LARGEDICT); see below. */
+static int CALLBACK
+rar_data_cb(UINT msg, LPARAM user, LPARAM p1, LPARAM p2) {
+  rarx_ctx_t *c = (rarx_ctx_t *)user;
+
+  if(msg == UCM_PROCESSDATA) {
+    c->bytes_done += (uint64_t)(unsigned long)p2;
+    report(c, ZIPX_PHASE_EXTRACT, NULL, 0);
+    return 0;
  }

-  dir_fd = open_parent_dirs(root_fd, dir_part, c);
-  if(dir_fd < 0) {
-    return -1;
+  if(msg == UCM_LARGEDICT) {
+    /* unrar asks permission before it allocates a window bigger than
+       Cmd->WinSizeLimit (default 4 GiB, options.cpp:13). Answering 1 would let
+       the run continue -- and that is a *trap*, not a fix: the window is one
+       contiguous allocation of the full dictionary size, and rarlab's own CLI
+       refuses the same case with "8 GB dictionary exceeds the 4 GB limit and
+       needs more than 8 GB of memory; use -md8g or -mdx8g". A PS5 has 16 GB of
+       shared memory, so >4 GiB dictionaries are not extractable there anyway;
+       failing cleanly beats being OOM-killed mid-extraction with the UI gone.
+       Record the numbers (p1/p2, both KiB) so the refusal can explain itself. */
+    c->dict_kb = (uint64_t)(unsigned long)p1;
+    c->dict_limit_kb = (uint64_t)(unsigned long)p2;
+    return 0;
  }

-  full_path = malloc(ZIPX_PATH_MAX);
-  if(!full_path) {
-    rarx_fail(c, ZIPX_ERR_INTERNAL, name, "out of memory");
-    if(dir_fd != root_fd) {
-      close(dir_fd);
-    }
-    return -1;
-  }
-  if(dir_part[0]) {
-    snprintf(full_path, ZIPX_PATH_MAX, "%s/%s/%s",
-             c->staging, dir_part, base);
-  } else {
-    snprintf(full_path, ZIPX_PATH_MAX, "%s/%s", c->staging, base);
-  }
-
-  before_bytes = c->bytes_done;
-  dr = dmc_unrar_extract_file_to_path(rar, index, full_path, NULL, true);
-  if(dr != DMC_UNRAR_OK) {
-    rar_translate_error(dr, name, c);
-    ret = -1;
-    goto done;
-  }
-
-  if(stat(full_path, &st)) {
-    rarx_fail(c, ZIPX_ERR_IO, name, "cannot stat extracted file: %s",
-              strerror(errno));
-    ret = -1;
-    goto done;
-  }
-  if((uint64_t)st.st_size > declared + declared + (64 * 1024)) {
-    /* Defensive: the on-disk size should never wildly exceed the declared
-       size. The cap is generous so PPMd + headers do not trip it. */
-    rarx_fail(c, ZIPX_ERR_LIMIT_FILE, name,
-              "extracted file is larger than declared");
-    unlink(full_path);
-    ret = -1;
-    goto done;
-  }
-  if((uint64_t)st.st_size > c->limits.max_total_bytes - c->bytes_done) {
-    rarx_fail(c, ZIPX_ERR_LIMIT_TOTAL, name,
-              "archive contents are larger than %llu bytes",
-              (unsigned long long)c->limits.max_total_bytes);
-    unlink(full_path);
-    ret = -1;
-    goto done;
-  }
-  c->bytes_done += (uint64_t)st.st_size;
-  /* If dmc_unrar did not advance bytes_done above (e.g. declared == 0 for a
-     directory or zero-byte file), credit the bytes_total estimate so the
-     progress bar keeps moving. */
-  if(c->bytes_done == before_bytes && declared) {
-    c->bytes_done += declared;
-  }
-
-done:
-  free(full_path);
-  if(dir_fd != root_fd) {
-    close(dir_fd);
-  }
-  if(!ret) {
-    c->files_created++;
-  }
-  return ret;
+  return 0;
 }

+/* unrar extracts each entry directly under the staging root and creates
+   parent directories itself. All entry names were validated (normalize_name)
+   during scan, so what lands in the staging tree is safe by construction. */
 static int
-extract_archive(dmc_unrar_archive *rar, rarx_ctx_t *c, int root_fd) {
-  dmc_unrar_size_t i;
-  dmc_unrar_size_t total = dmc_unrar_get_file_count(rar);
+extract_archive(HANDLE hArc, rarx_ctx_t *c) {
  int ret = 0;

-  for(i = 0; i < total && !ret; i++) {
-    char *name_buf = NULL;
-    dmc_unrar_size_t name_size;
-    char name[ZIPX_PATH_MAX];
+  RARSetCallback(hArc, rar_data_cb, (LPARAM)(intptr_t)c);
+
+  for(;;) {
+    struct RARHeaderDataEx hdr;
+    int rc;
    int is_dir;
-    uint32_t depth = 0;
-    const dmc_unrar_file *info;
+
+    memset(&hdr, 0, sizeof(hdr));
+    rc = RARReadHeaderEx(hArc, &hdr);
+    if(rc == ERAR_END_ARCHIVE) {
+      break;
+    }
+    if(rc != ERAR_SUCCESS) {
+      rar_translate_error(rc, NULL, c);
+      ret = -1;
+      break;
+    }

    if(canceled(c)) {
      ret = rarx_fail(c, ZIPX_ERR_CANCELED, NULL, NULL);
      break;
    }
+    if(hdr.FileName[0] == 0) {
+      ret = rarx_fail(c, ZIPX_ERR_FORMAT, NULL, "empty entry name");
+      break;
+    }
+    if((hdr.Flags & RHDF_ENCRYPTED) && !c->password) {
+      /* scan already rejected password-less encrypted sets; defensive only. */
+      ret = rarx_fail(c, ZIPX_ERR_PASSWORD, hdr.FileName,
+                      "the archive is encrypted and no password was supplied");
+      break;
+    }

-    info = dmc_unrar_get_file_stat(rar, i);
-    if(!info) {
-      ret = rarx_fail(c, ZIPX_ERR_FORMAT, NULL, "cannot read entry header");
-      break;
+    is_dir = (hdr.Flags & RHDF_DIRECTORY) ? 1 : 0;
+    /* Split continuation segments still need RARProcessFile(EXTRACT) so the
+       volume chain is driven and the file is completed, but only the first
+       segment is counted / reported / size-accumulated. */
+    if(hdr.Flags & RHDF_SPLITBEFORE) {
+      rc = RARProcessFile(hArc, RAR_EXTRACT, c->staging, NULL);
+      if(rc != ERAR_SUCCESS) {
+        rar_translate_error(rc, hdr.FileName, c);
+        ret = -1;
+        break;
+      }
+      continue;
    }
-    is_dir = dmc_unrar_file_is_directory(rar, i) ? 1 : 0;
-
-    name_size = dmc_unrar_get_filename(rar, i, NULL, 0);
-    if(!name_size) {
-      ret = rarx_fail(c, ZIPX_ERR_FORMAT, NULL, "cannot read entry name");
-      break;
-    }
-    name_buf = malloc(name_size);
-    if(!name_buf) {
-      ret = rarx_fail(c, ZIPX_ERR_INTERNAL, NULL, "out of memory");
-      break;
-    }
-    if(dmc_unrar_get_filename(rar, i, name_buf, name_size) != name_size) {
-      free(name_buf);
-      ret = rarx_fail(c, ZIPX_ERR_FORMAT, NULL, "truncated entry name");
-      break;
-    }
-    name_buf[name_size - 1] = 0;
-    dmc_unrar_unicode_make_valid_utf8(name_buf);
-
-    if(normalize_name(name_buf, name, sizeof(name), &is_dir, &depth, c)) {
-      free(name_buf);
+    rc = RARProcessFile(hArc, RAR_EXTRACT, c->staging, NULL);
+    if(rc != ERAR_SUCCESS) {
+      rar_translate_error(rc, hdr.FileName, c);
      ret = -1;
      break;
    }
-    free(name_buf);
-    (void)depth;

    if(is_dir) {
-      int dir_fd = open_parent_dirs(root_fd, name, c);
-      if(dir_fd < 0) {
-        ret = -1;
-        break;
-      }
-      if(dir_fd != root_fd) {
-        close(dir_fd);
-      }
+      c->dirs_created++;
    } else {
-      uint64_t declared = info->uncompressed_size;
-      if(extract_one(rar, c, root_fd, name, i, declared)) {
-        ret = -1;
-        break;
-      }
+      c->files_created++;
    }
    c->entries_done++;
-    report(c, ZIPX_PHASE_EXTRACT, name, 0);
+    report(c, ZIPX_PHASE_EXTRACT, hdr.FileName, 0);
  }
  return ret;
 }
@@ -1145,15 +1038,13 @@ zipx_status_t
 rar_extract(const char *rar_path, const char *dst_dir,
            zipx_conflict_t conflict, const zipx_limits_t *limits,
            zipx_cancel_fn cancel, zipx_progress_fn progress,
-            void *userdata, zipx_result_t *result) {
+            void *userdata, const char *password, zipx_result_t *result) {
  rarx_ctx_t ctx;
  rarx_ctx_t *c = &ctx;
  char parent[ZIPX_PATH_MAX];
  char dst_copy[ZIPX_PATH_MAX];
  struct stat st;
-  dmc_unrar_archive rar;
-  dmc_unrar_return dr;
-  int root_fd = -1;
+  HANDLE hArc = NULL;
  int dst_existed = 0;
  int status;

@@ -1174,6 +1065,9 @@ rar_extract(const char *rar_path, const char *dst_dir,
  c->cancel = cancel;
  c->progress = progress;
  c->userdata = userdata;
+  /* An empty string means "no password" so that callers can pass the raw
+     form field without a separate emptiness check. */
+  c->password = (password && password[0]) ? password : NULL;

  snprintf(dst_copy, sizeof(dst_copy), "%s", dst_dir);
  {
@@ -1197,50 +1091,75 @@ rar_extract(const char *rar_path, const char *dst_dir,
    goto done;
  }

-  dr = dmc_unrar_archive_init(&rar);
-  if(dr != DMC_UNRAR_OK) {
-    status = rarx_fail(c, ZIPX_ERR_INTERNAL, rar_path,
-                       "cannot initialize RAR decoder");
-    goto done;
-  }
-  dr = dmc_unrar_archive_open_path(&rar, rar_path);
-  if(dr != DMC_UNRAR_OK) {
-    status = rar_translate_error(dr, rar_path, c);
-    goto done;
+  /* Open with RAR_OM_EXTRACT for both passes: the unrar engine drives
+     multi-volume merges identically while scanning (skip) and extracting,
+     and encrypted headers surface here as a missing/bad password. */
+  {
+    struct RAROpenArchiveDataEx od;
+    memset(&od, 0, sizeof(od));
+    od.ArcName = (char *)rar_path;
+    od.OpenMode = RAR_OM_EXTRACT;
+    hArc = RAROpenArchiveEx(&od);
+    if(!hArc) {
+      status = rar_translate_error((int)od.OpenResult, rar_path, c);
+      goto done;
+    }
+    /* Must precede the first RARReadHeaderEx: unrar needs the password in
+       place to decrypt a -hp (encrypted header) archive. */
+    if(c->password) {
+      WFM_RAR_PASSWORD(hArc, (char *)c->password);
+    }
  }

-  if(scan_archive(&rar, c)) {
+  if(scan_archive(hArc, c)) {
    status = (int)c->result->status;
+    RARCloseArchive(hArc);
+    hArc = NULL;
    goto done;
  }
  if(canceled(c)) {
    status = rarx_fail(c, ZIPX_ERR_CANCELED, NULL, NULL);
+    RARCloseArchive(hArc);
+    hArc = NULL;
    goto done;
  }
  if(check_space(c, dst_existed ? dst_copy : parent)) {
    status = (int)c->result->status;
+    RARCloseArchive(hArc);
+    hArc = NULL;
    goto done;
  }
  if(make_staging(c, parent)) {
    status = (int)c->result->status;
+    RARCloseArchive(hArc);
+    hArc = NULL;
    goto done;
  }

-  root_fd = open(c->staging, O_RDONLY | O_DIRECTORY | O_NOFOLLOW | O_CLOEXEC);
-  if(root_fd < 0) {
-    status = rarx_fail(c, ZIPX_ERR_IO, c->staging, "cannot open staging: %s",
-                       strerror(errno));
-    goto done;
+  /* Pass 2: re-open and extract each entry straight into the staging tree
+     (unrar creates parent directories itself; names were validated during
+     scan). The staging root is pre-verified below for fast failure. */
+  RARCloseArchive(hArc);
+  hArc = NULL;
+  {
+    struct RAROpenArchiveDataEx od;
+    memset(&od, 0, sizeof(od));
+    od.ArcName = (char *)rar_path;
+    od.OpenMode = RAR_OM_EXTRACT;
+    hArc = RAROpenArchiveEx(&od);
+    if(!hArc) {
+      status = rar_translate_error((int)od.OpenResult, rar_path, c);
+      goto done;
+    }
+    if(c->password) {
+      WFM_RAR_PASSWORD(hArc, (char *)c->password);
+    }
  }

-  if(extract_archive(&rar, c, root_fd)) {
+  if(extract_archive(hArc, c)) {
    status = (int)c->result->status;
    goto done;
  }
-  if(root_fd >= 0) {
-    close(root_fd);
-    root_fd = -1;
-  }
  if(canceled(c)) {
    status = rarx_fail(c, ZIPX_ERR_CANCELED, NULL, NULL);
    goto done;
@@ -1254,11 +1173,10 @@ rar_extract(const char *rar_path, const char *dst_dir,
  status = ZIPX_OK;

 done:
-  if(root_fd >= 0) {
-    close(root_fd);
+  if(hArc) {
+    RARCloseArchive(hArc);
  }
  cleanup_staging(c);
-  dmc_unrar_archive_close(&rar);
  result->entries_total = c->entries_total;
  result->entries_done = c->entries_done;
  result->bytes_total = c->bytes_total;
@@ -1,21 +1,23 @@
 #pragma once

 /* Safe RAR extraction engine used by the /api/extract task.
-   Wraps the vendored dmc_unrar library (https://github.com/DrMcCoy/dmc_unrar).
+   Wraps the vendored rarlab UnRAR 7.20.1 (third_party/unrar7) through its
+   C-compatible DLL API (unrar_c_api.h facade).

   Reuses the zip_extract types so the dispatch layer can call either engine
   through the same status / limits / progress protocol.

   See zip_extract.h for the shared limits, conflict, progress and result types.

-   Constraints of v1.8 (dmc_unrar 1.7.0 backend):
-     * Single-volume RAR archives only. Multi-volume (.partNN.rar) archives
-       are rejected with ZIPX_ERR_UNSUPPORTED — extract them on a PC first.
-     * Unencrypted RAR only. Encrypted headers / files are rejected with
-       ZIPX_ERR_UNSUPPORTED. There is no password argument for the same reason.
+   Backend notes (v1.9, unrar 7.20.1):
+     * RAR4 and RAR5, any compression version including WinRAR 6/7 "v6".
+     * Multi-volume: unrar merges next .partNN.rar by name automatically.
+     * Encrypted archives work end-to-end (both `-p` data encryption and
+       `-hp` header encryption). Pass the password in `password`; NULL or an
+       empty string means "no password supplied". A missing or wrong password
+       is reported as ZIPX_ERR_PASSWORD so the caller can prompt and retry.

-   See third_party/unrar/VENDORED.md for the upgrade path to rarlab UnRAR
-   (which does support both) when / if it becomes worth the C++ integration. */
+   See third_party/unrar7/VENDORED.md for full integration notes. */

 #include "zip_extract.h"

@@ -23,6 +25,7 @@
 #include <stddef.h>

 /* Extract rar_path into dst_dir using the same protocol as zipx_extract().
+   `password` may be NULL when the archive is not encrypted.
   Returns ZIPX_OK or an error code; *result is always filled in.
   On any failure the staging directory is removed and dst_dir is left as it
   was, except for objects already published with the overwrite policy. */
@@ -32,4 +35,5 @@ zipx_status_t rar_extract(const char *rar_path, const char *dst_dir,
                          zipx_cancel_fn cancel,
                          zipx_progress_fn progress,
                          void *userdata,
+                          const char *password,
                          zipx_result_t *result);
@@ -0,0 +1,186 @@
+/* sevenz_chain -- 7z folder (coder chain) decoder.
+   part of ps5-web-file-manager
+
+   A 7z archive stores its data as *folders*.  One folder is a small directed
+   graph of coders fed by N packed streams and producing a single unpacked
+   stream; entries are slices of the folder output (a folder holding several
+   entries is what makes an archive "solid").
+
+   The bundled LZMA SDK can decode a folder, but only through `CSzFolder`,
+   which is a fixed-size structure capped at 4 coders / 3 bonds.  7-Zip's own
+   BCJ2 chain uses 5 coders (BCJ2 plus four LZMA2 streams), so the SDK rejects
+   it -- while still listing the archive fine, because its *header* scanner is
+   a different, looser parser (64 coders).  The C half of the SDK also has no
+   7zAES coder at all.
+
+   This module therefore parses the folder descriptor itself (dynamic arrays,
+   up to 64 coders, mirroring the SDK's header scanner) and drives the coder
+   graph itself.  Two properties matter:
+
+     * Streaming.  The decoded bytes are pushed into a sink as they are
+       produced; a folder is never materialised as a whole, so a multi-gigabyte
+       solid block is workable.  The only buffers sized from the archive are
+       the LZMA/LZMA2 dictionary, the PPMd model and the three side streams of
+       BCJ2 -- each capped by sz_chain_limits_t.
+
+     * Precision.  Every rejection names the coder and the method, and the
+       resource limits report the value the archive asked for and the value
+       that was allowed, so the UI can say something useful instead of
+       "corrupt archive".
+
+   Supported here:
+     * Copy, LZMA, LZMA2 and PPMd
+     * the Delta filter and the x86 / PPC / IA64 / ARM / ARMT / SPARC branch
+       converters
+     * BCJ2, whose three side streams are materialised under a limit while
+       MAIN keeps streaming
+     * 7zAES (method 0x06F10701), the coder 7-Zip wraps around the streams when
+       `-p` is used, driven from a caller supplied password
+
+   An encrypted *header* (`-mhe=on`) is not a coder in a folder: it is a second,
+   encrypted copy of the archive header that has to be decoded before any folder
+   exists at all.  src/sevenz_header.c does that -- by parsing that one folder's
+   descriptor and running it through this module, password and all.
+*/
+
+#ifndef SEVENZ_CHAIN_H
+#define SEVENZ_CHAIN_H
+
+#include <stddef.h>
+#include <stdint.h>
+
+/* The SDK's header scanner accepts up to 64 coders per folder; folders in the
+   wild have 1-5.  Keeping the same ceiling means "the SDK could list it" and
+   "we can decode it" accept the same archives. */
+#define SZ_CHAIN_MAX_CODERS 64
+#define SZ_CHAIN_MAX_STREAMS 64
+
+/* Ceilings for the buffers whose size comes from the (attacker controlled)
+   archive header. */
+typedef struct {
+  uint64_t max_dict_bytes; /* LZMA / LZMA2 window */
+  uint64_t max_ppmd_bytes; /* PPMd model */
+  uint64_t max_side_bytes; /* BCJ2 CALL + JUMP + RC together */
+  uint32_t max_aes_cycles; /* 7zAES key derivation: 2^n SHA-256 passes */
+} sz_chain_limits_t;
+
+#define SZ_CHAIN_LIMITS_DEFAULT 0
+#define SZ_CHAIN_LIMITS_LARGE 1
+const sz_chain_limits_t *sz_chain_limits_profile(int profile);
+const sz_chain_limits_t *sz_chain_default_limits(void);
+
+typedef enum {
+  SZ_CHAIN_OK = 0,
+  SZ_CHAIN_ERR_PARAM,   /* bad arguments from the caller */
+  SZ_CHAIN_ERR_MEM,     /* allocation failed */
+  SZ_CHAIN_ERR_HEADER,  /* malformed folder descriptor */
+  SZ_CHAIN_ERR_METHOD,  /* coder method not supported */
+  SZ_CHAIN_ERR_LAYOUT,  /* coder graph shape not supported */
+  SZ_CHAIN_ERR_LIMIT,   /* a sz_chain_limits_t ceiling was hit */
+  SZ_CHAIN_ERR_PASSWORD,/* the archive is encrypted and no usable password
+                           was supplied (or the one given is wrong) */
+  SZ_CHAIN_ERR_READ,    /* the read callback failed */
+  SZ_CHAIN_ERR_WRITE,   /* the sink callback failed */
+  SZ_CHAIN_ERR_DATA,    /* a decoder rejected the data */
+  SZ_CHAIN_ERR_CANCELED,
+  SZ_CHAIN_ERR_INTERNAL
+} sz_chain_status_t;
+
+typedef struct {
+  sz_chain_status_t status;
+  int32_t coder;    /* index of the offending coder, -1 when not applicable */
+  uint32_t method;  /* its method id, 0 when not applicable */
+  uint64_t offset;  /* decoded byte offset at the point of failure */
+  char message[192];
+} sz_chain_err_t;
+
+const char *sz_chain_status_string(sz_chain_status_t status);
+
+/* "LZMA2", "BCJ2", "7zAES", "unknown 0x1234".  Never returns NULL. */
+const char *sz_chain_method_name(uint32_t method);
+
+/* ---------------------------------------------------------------- folder */
+
+typedef struct sz_chain sz_chain;
+
+/* Parses one folder descriptor.
+
+   blob / blob_size
+       the CODERS_INFO bytes of this folder, i.e. the range
+       `CSzAr::CodersData[FoCodersOffsets[i] .. FoCodersOffsets[i + 1])`.
+   pack_positions
+       `CSzAr::PackPositions`, num_pack_streams + 1 entries, offsets of the
+       packed streams relative to the start of the archive's packed-data area.
+   coder_unpack_sizes
+       unpacked size of every coder of this folder, in stored coder order, i.e.
+       `&CSzAr::CoderUnpackSizes[CSzAr::FoToCoderUnpackSizes[i]]`.
+   unpack_size
+       `SzAr_GetFolderUnpackSize(&db, i)`.
+
+   Returns 0 on success.  On success *out owns a copy of blob, release it with
+   sz_chain_free().  On failure *out is untouched and err describes the
+   problem. */
+int sz_chain_parse(sz_chain **out, const uint8_t *blob, size_t blob_size,
+                   const uint64_t *pack_positions, uint32_t num_pack_streams,
+                   const uint64_t *coder_unpack_sizes, uint64_t unpack_size,
+                   const sz_chain_limits_t *limits, sz_chain_err_t *err);
+
+void sz_chain_free(sz_chain *c);
+
+uint32_t sz_chain_num_coders(const sz_chain *c);
+uint32_t sz_chain_num_pack_streams(const sz_chain *c);
+/* Non-zero when the folder contains a 7zAES coder, i.e. when sz_chain_decode()
+   will need a password.  Lets a caller ask for one before touching the disk. */
+int sz_chain_needs_password(const sz_chain *c);
+/* Method id of coder `index`, or -1 when out of range. */
+int64_t sz_chain_coder_method(const sz_chain *c, uint32_t index);
+
+/* True when the folder is a single plain LZMA2 coder -- the shape the SDK's
+   multithreaded decoder covers.  Fills the coder's props byte and the packed
+   input size; both are only valid when this returns non-zero. */
+int sz_chain_lzma2_root(const sz_chain *c, uint8_t *prop, uint64_t *in_size);
+
+/* Writes e.g. "LZMA2 + BCJ2 (5 coders, 4 pack streams)" into buf. */
+void sz_chain_describe(const sz_chain *c, char *buf, size_t size);
+
+/* Walks every coder and the graph shape without touching any data, so callers
+   can refuse an archive before creating anything on disk.  Fills err with the
+   same precision sz_chain_decode() would. */
+int sz_chain_check(const sz_chain *c, sz_chain_err_t *err);
+
+/* -------------------------------------------------------------- decoding */
+
+/* Fills exactly size bytes at offset inside the packed-data area.
+   Returns 0 on success, non-zero on failure. */
+typedef int (*sz_chain_read_fn)(void *ctx, uint64_t offset, void *dst,
+                                size_t size);
+
+/* Receives the decoded bytes in order.  Returns 0 to continue. */
+typedef int (*sz_chain_sink_fn)(void *ctx, const void *data, size_t size);
+
+/* Returns non-zero to abort.  May be NULL. */
+typedef int (*sz_chain_cancel_fn)(void *ctx);
+
+/* Decodes the whole folder, pushing the result into sink.
+
+   The bytes are delivered strictly in order and the total is the folder's
+   declared unpack size.  When crc_out is not NULL it receives the CRC-32 of
+   the delivered bytes, for the caller to compare with the folder CRC.
+
+   `password` is the archive password as UTF-8, or NULL / "" when the caller
+   has none.  It is only consulted by folders that contain a 7zAES coder; a
+   folder that needs one without a password fails as SZ_CHAIN_ERR_PASSWORD
+   before any data is read, so the caller can prompt and retry.  A password
+   containing NUL is not supported: 7-Zip stores it as UTF-16LE and the
+   conversion stops at the terminator.
+
+   Returns 0 on success, -1 on failure with err filled.  A failing sink is
+   reported as SZ_CHAIN_ERR_WRITE; the caller is expected to make its own
+   message more specific. */
+int sz_chain_decode(sz_chain *c, sz_chain_read_fn read_at, void *read_ctx,
+                    sz_chain_sink_fn sink, void *sink_ctx,
+                    sz_chain_cancel_fn cancel, void *cancel_ctx,
+                    const char *password, uint32_t *crc_out,
+                    sz_chain_err_t *err);
+
+#endif /* SEVENZ_CHAIN_H */
@@ -0,0 +1,38 @@
+#pragma once
+
+/* Standalone 7z extraction engine, the third sibling of zip_extract.c and
+   rar_extract.c.  Like them it has no HTTP or task dependencies, and it fills
+   in the same zipx_result_t so a caller can treat every format alike.
+
+   Input may be a single `name.7z` or a byte-split set (`name.7z.001`, ...):
+   both reach the decoder through src/sevenz_volstream.c.
+
+   The publish / staging / rollback / name-validation machinery is mirrored
+   from rar_extract.c on purpose -- three self-contained engines is the shape
+   this project has settled on, so that a format's bugs stay inside its file.
+
+   Backend notes (LZMA SDK 26.03 + src/sevenz_chain.c):
+     * Copy / LZMA / LZMA2 / PPMd, the Delta filter and the x86 / PPC / IA64 /
+       ARM / ARMT / SPARC branch converters, BCJ2, and 7zAES.
+     * An encrypted *header* (`-mhe=on`) is decrypted by src/sevenz_header.c
+       first: the SDK refuses such an archive before any folder is known, so
+       the header has to be readable before the SDK is asked to read it.
+*/
+
+#include "zip_extract.h"
+
+/* Extract sevenz_path into dst_dir.
+   `password` is the archive password as UTF-8, or NULL / "" when the caller
+   has none.  It is only consulted by archives that encrypt their streams.
+
+   Returns ZIPX_OK or an error code; *result is always filled in.  A missing or
+   wrong password comes back as ZIPX_ERR_PASSWORD so the caller can ask for one
+   and retry.  On any failure the staging directory is removed and dst_dir is
+   left as it was, except for objects already published under the overwrite
+   policy. */
+zipx_status_t sevenz_extract(const char *sevenz_path, const char *dst_dir,
+                             zipx_conflict_t conflict,
+                             const zipx_limits_t *limits,
+                             zipx_cancel_fn cancel,
+                             zipx_progress_fn progress, void *userdata,
+                             const char *password, zipx_result_t *result);
@@ -0,0 +1,917 @@
+/* sevenz_header -- see sevenz_header.h for what this does and why. */
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+#include "7z.h"
+#include "7zCrc.h"
+#include "7zTypes.h"
+
+#include "sevenz_chain.h"
+#include "sevenz_header.h"
+
+/* The header property ids we have to recognise.  They are the same enum the
+   SDK's header scanner uses (7zArcIn.c), spelled out here so this file does
+   not depend on that translation unit's internals. */
+#define SZH_ID_END 0x00
+#define SZH_ID_HEADER 0x01
+#define SZH_ID_PACK_INFO 0x06
+#define SZH_ID_UNPACK_INFO 0x07
+#define SZH_ID_SIZE 0x09
+#define SZH_ID_CRC 0x0A
+#define SZH_ID_FOLDER 0x0B
+#define SZH_ID_CODERS_UNPACK_SIZE 0x0C
+#define SZH_ID_ENCODED_HEADER 0x17
+
+#define SZH_MAX_CODERS SZ_CHAIN_MAX_CODERS
+#define SZH_MAX_STREAMS SZ_CHAIN_MAX_STREAMS
+
+/* --------------------------------------------------------------- numbers */
+
+static uint32_t
+szh_le32(const uint8_t *p) {
+  return (uint32_t)p[0] | ((uint32_t)p[1] << 8) | ((uint32_t)p[2] << 16) |
+         ((uint32_t)p[3] << 24);
+}
+
+static uint64_t
+szh_le64(const uint8_t *p) {
+  return (uint64_t)szh_le32(p) | ((uint64_t)szh_le32(p + 4) << 32);
+}
+
+static void
+szh_put_le32(uint8_t *p, uint32_t v) {
+  p[0] = (uint8_t)v;
+  p[1] = (uint8_t)(v >> 8);
+  p[2] = (uint8_t)(v >> 16);
+  p[3] = (uint8_t)(v >> 24);
+}
+
+static void
+szh_put_le64(uint8_t *p, uint64_t v) {
+  szh_put_le32(p, (uint32_t)v);
+  szh_put_le32(p + 4, (uint32_t)(v >> 32));
+}
+
+/* The 7z variable length number: the high bits of the first byte say how many
+   more bytes follow, and the remaining bits of the first byte are the high
+   part of the value.  This mirrors ReadNumber() in 7zArcIn.c byte for byte,
+   including its habit of returning a partial value when all eight flag bits
+   are set -- the caller checks the CRC of the whole record anyway. */
+static int
+szh_num(const uint8_t *d, size_t size, size_t *pos, uint64_t *value) {
+  size_t p = *pos;
+  unsigned first, mask, v, i;
+
+  if(p >= size) {
+    return -1;
+  }
+  first = d[p++];
+  if((first & 0x80) == 0) {
+    *value = first;
+    *pos = p;
+    return 0;
+  }
+  if(p >= size) {
+    return -1;
+  }
+  v = d[p++];
+  if((first & 0x40) == 0) {
+    *value = ((uint64_t)(first & 0x3F) << 8) | v;
+    *pos = p;
+    return 0;
+  }
+  if(p >= size) {
+    return -1;
+  }
+  mask = d[p++];
+  *value = (uint64_t)v | ((uint64_t)mask << 8);
+  mask = 0x20;
+  for(i = 16; i < 64; i += 8) {
+    if((first & mask) == 0) {
+      *value |= (uint64_t)(first & (mask - 1)) << i;
+      *pos = p;
+      return 0;
+    }
+    mask >>= 1;
+    if(p >= size) {
+      return -1;
+    }
+    *value |= (uint64_t)d[p++] << i;
+  }
+  *pos = p;
+  return 0;
+}
+
+/* The 32 bit form used for counts and property sizes. */
+static int
+szh_num32(const uint8_t *d, size_t size, size_t *pos, uint32_t *value) {
+  uint64_t v;
+
+  if(*pos < size && (d[*pos] & 0x80) == 0) {
+    *value = d[(*pos)++];
+    return 0;
+  }
+  if(szh_num(d, size, pos, &v)) {
+    return -1;
+  }
+  if(v >= (uint64_t)0x80000000u - 1) {
+    return -1;
+  }
+  *value = (uint32_t)v;
+  return 0;
+}
+
+static uint32_t
+szh_count_bits(const uint8_t *d, uint32_t num_items) {
+  uint32_t n = 0, i;
+
+  for(i = 0; i < num_items; i++) {
+    if(d[i >> 3] & (0x80u >> (i & 7))) {
+      n++;
+    }
+  }
+  return n;
+}
+
+/* A digest block: one "all are defined" byte, an optional bit vector, then one
+   little endian CRC per defined item.  With `first` the value of the first
+   defined item comes back, which is the folder CRC when the block covers a
+   single folder. */
+static int
+szh_digests(const uint8_t *d, size_t size, size_t *pos, uint32_t num_items,
+            uint32_t *first, int *has_first) {
+  size_t p = *pos;
+  uint32_t defined = num_items;
+  unsigned all;
+
+  if(p >= size) {
+    return -1;
+  }
+  all = d[p++];
+  if(!all) {
+    size_t bytes = ((size_t)num_items + 7) >> 3;
+
+    if(bytes > size - p) {
+      return -1;
+    }
+    defined = szh_count_bits(d + p, num_items);
+    p += bytes;
+  }
+  if((size_t)defined > (size - p) >> 2) {
+    return -1;
+  }
+  if(first && has_first) {
+    if(defined) {
+      *first = szh_le32(d + p);
+      *has_first = 1;
+    } else {
+      *has_first = 0;
+    }
+  }
+  p += (size_t)defined * 4;
+  *pos = p;
+  return 0;
+}
+
+/* The SDK's SkipData(): a length, then that many bytes. */
+static int
+szh_skip_data(const uint8_t *d, size_t size, size_t *pos) {
+  uint64_t n;
+
+  if(szh_num(d, size, pos, &n)) {
+    return -1;
+  }
+  if(n > (uint64_t)(size - *pos)) {
+    return -1;
+  }
+  *pos += (size_t)n;
+  return 0;
+}
+
+/* --------------------------------------------------------- encoded header */
+
+typedef struct {
+  uint64_t pack_pos; /* where this folder's packs live, from offset 32 */
+  uint32_t num_pack;
+  uint64_t pack_sizes[SZH_MAX_STREAMS];
+  uint64_t pack_positions[SZH_MAX_STREAMS + 1]; /* cumulative, as the SDK builds */
+  const uint8_t *blob;                          /* coder descriptor, in place */
+  size_t blob_size;
+  uint32_t num_coders;
+  uint32_t main_coder;
+  uint64_t coder_unpack_sizes[SZH_MAX_CODERS];
+  uint64_t unpack_size;
+  uint32_t crc;
+  int has_crc;
+} szh_streams_t;
+
+/* One folder descriptor: the coders, then the bond pairs and the pack-stream
+   indices that follow them.  `*pos` ends up just past the last of those, so
+   [start, *pos) is exactly the byte range the SDK keeps as
+   CSzAr::CodersData[FoCodersOffsets[0] .. FoCodersOffsets[1]). */
+static int
+szh_parse_folder(const uint8_t *d, size_t size, size_t *pos, szh_streams_t *ss) {
+  const size_t start = *pos;
+  size_t p = start;
+  uint32_t num_coders = 0, num_in = 0, num_bonds, num_pack, i;
+  uint8_t coder_used[SZH_MAX_CODERS];
+  uint8_t stream_used[SZH_MAX_STREAMS];
+  uint32_t main_index = 0;
+
+  if(szh_num32(d, size, &p, &num_coders)) {
+    return -1;
+  }
+  if(num_coders == 0 || num_coders > SZH_MAX_CODERS) {
+    return -1;
+  }
+
+  for(i = 0; i < num_coders; i++) {
+    uint8_t main_byte;
+    uint32_t id_size, coder_in = 1;
+
+    if(p >= size) {
+      return -1;
+    }
+    main_byte = d[p++];
+    if(main_byte & 0xC0) {
+      return -1;
+    }
+    id_size = main_byte & 0x0F;
+    if(id_size > 8 || (size_t)id_size > size - p) {
+      return -1;
+    }
+    p += id_size;
+    if(main_byte & 0x10) {
+      uint32_t coder_out;
+
+      if(szh_num32(d, size, &p, &coder_in) ||
+         szh_num32(d, size, &p, &coder_out)) {
+        return -1;
+      }
+      /* The header scanner accepts exactly one output stream per coder, so a
+         coder index and its output-stream index coincide. */
+      if(coder_out != 1) {
+        return -1;
+      }
+    }
+    if(num_in >= SZH_MAX_STREAMS || coder_in > SZH_MAX_STREAMS - num_in) {
+      return -1;
+    }
+    num_in += coder_in;
+    if(main_byte & 0x20) {
+      uint32_t props_size;
+
+      if(szh_num32(d, size, &p, &props_size) ||
+         (size_t)props_size > size - p) {
+        return -1;
+      }
+      p += props_size;
+    }
+  }
+
+  num_bonds = num_coders - 1;
+  if(num_in < num_bonds) {
+    return -1;
+  }
+  num_pack = num_in - num_bonds;
+  if(num_pack != ss->num_pack) {
+    return -1;
+  }
+
+  memset(coder_used, 0, sizeof(coder_used));
+  memset(stream_used, 0, sizeof(stream_used));
+
+  for(i = 0; i < num_bonds; i++) {
+    uint32_t in_index, out_index;
+
+    if(szh_num32(d, size, &p, &in_index)) {
+      return -1;
+    }
+    if(in_index >= num_in || stream_used[in_index]) {
+      return -1;
+    }
+    stream_used[in_index] = 1;
+    if(szh_num32(d, size, &p, &out_index)) {
+      return -1;
+    }
+    if(out_index >= num_coders || coder_used[out_index]) {
+      return -1;
+    }
+    coder_used[out_index] = 1;
+  }
+  if(num_pack != 1) {
+    for(i = 0; i < num_pack; i++) {
+      uint32_t index;
+
+      if(szh_num32(d, size, &p, &index)) {
+        return -1;
+      }
+      if(index >= num_in || stream_used[index]) {
+        return -1;
+      }
+      stream_used[index] = 1;
+    }
+  }
+
+  /* The coder no bond consumes produces the folder's output. */
+  while(main_index < num_coders && coder_used[main_index]) {
+    main_index++;
+  }
+  if(main_index >= num_coders) {
+    return -1;
+  }
+
+  ss->blob = d + start;
+  ss->blob_size = p - start;
+  ss->num_coders = num_coders;
+  ss->main_coder = main_index;
+  *pos = p;
+  return 0;
+}
+
+/* Reads the StreamsInfo of a k7zIdEncodedHeader record.  Only the parts this
+   module acts on are interpreted; anything else is skipped the way the SDK
+   skips an id it does not know. */
+static int
+szh_parse_streams(const uint8_t *d, size_t size, szh_streams_t *ss) {
+  size_t pos = 1; /* past k7zIdEncodedHeader */
+  uint64_t id;
+  uint32_t i;
+  int seen_folder = 0, seen_sizes = 0;
+
+  memset(ss, 0, sizeof(*ss));
+
+  if(szh_num(d, size, &pos, &id) || id != SZH_ID_PACK_INFO) {
+    return -1;
+  }
+  if(szh_num(d, size, &pos, &ss->pack_pos) ||
+     szh_num32(d, size, &pos, &ss->num_pack)) {
+    return -1;
+  }
+  if(ss->num_pack == 0 || ss->num_pack > SZH_MAX_STREAMS) {
+    return -1;
+  }
+  {
+    int got_sizes = 0;
+
+    for(;;) {
+      if(szh_num(d, size, &pos, &id)) {
+        return -1;
+      }
+      if(id == SZH_ID_END) {
+        break;
+      }
+      if(id == SZH_ID_SIZE) {
+        if(got_sizes) {
+          return -1;
+        }
+        for(i = 0; i < ss->num_pack; i++) {
+          if(szh_num(d, size, &pos, &ss->pack_sizes[i])) {
+            return -1;
+          }
+        }
+        got_sizes = 1;
+        continue;
+      }
+      if(szh_skip_data(d, size, &pos)) {
+        return -1;
+      }
+    }
+    if(!got_sizes) {
+      return -1;
+    }
+  }
+  ss->pack_positions[0] = 0;
+  for(i = 0; i < ss->num_pack; i++) {
+    ss->pack_positions[i + 1] = ss->pack_positions[i] + ss->pack_sizes[i];
+    if(ss->pack_positions[i + 1] < ss->pack_positions[i]) {
+      return -1;
+    }
+  }
+
+  if(szh_num(d, size, &pos, &id) || id != SZH_ID_UNPACK_INFO) {
+    return -1;
+  }
+  for(;;) {
+    if(szh_num(d, size, &pos, &id)) {
+      return -1;
+    }
+    if(id == SZH_ID_END) {
+      break;
+    }
+    if(id == SZH_ID_FOLDER) {
+      uint32_t num_folders;
+
+      if(seen_folder || szh_num32(d, size, &pos, &num_folders)) {
+        return -1;
+      }
+      /* SzArEx_Open2 decodes this record with numFoldersMax = 1, and the
+         `external` flag has to be clear for the table to be inline. */
+      if(num_folders != 1 || pos >= size || d[pos] != 0) {
+        return -1;
+      }
+      pos++;
+      if(szh_parse_folder(d, size, &pos, ss)) {
+        return -1;
+      }
+      seen_folder = 1;
+      continue;
+    }
+    if(id == SZH_ID_CODERS_UNPACK_SIZE) {
+      if(!seen_folder || seen_sizes) {
+        return -1;
+      }
+      for(i = 0; i < ss->num_coders; i++) {
+        if(szh_num(d, size, &pos, &ss->coder_unpack_sizes[i])) {
+          return -1;
+        }
+      }
+      seen_sizes = 1;
+      continue;
+    }
+    if(id == SZH_ID_CRC) {
+      uint32_t crc = 0;
+      int has = 0;
+
+      if(ss->has_crc || szh_digests(d, size, &pos, 1, &crc, &has)) {
+        return -1;
+      }
+      if(has) {
+        ss->crc = crc;
+        ss->has_crc = 1;
+      }
+      continue;
+    }
+    if(szh_skip_data(d, size, &pos)) {
+      return -1;
+    }
+  }
+  if(!seen_folder || !seen_sizes) {
+    return -1;
+  }
+  ss->unpack_size = ss->coder_unpack_sizes[ss->main_coder];
+
+  /* A SubStreamsInfo may hold the folder CRC when UnpackInfo carried none, but
+     nothing past this point changes what we decode. */
+  return 0;
+}
+
+/* ------------------------------------------------------------- stream I/O */
+
+static uint64_t
+szh_size_of(ISeekInStream *s) {
+  Int64 pos = 0;
+
+  if(s->Seek(s, &pos, SZ_SEEK_END) != SZ_OK || pos < 0) {
+    return 0;
+  }
+  return (uint64_t)pos;
+}
+
+static int
+szh_read_at(ISeekInStream *s, uint64_t offset, void *dst, size_t size) {
+  Int64 pos = (Int64)offset;
+  size_t got = 0;
+
+  if(s->Seek(s, &pos, SZ_SEEK_SET) != SZ_OK) {
+    return -1;
+  }
+  while(got < size) {
+    size_t want = size - got;
+
+    if(s->Read(s, (uint8_t *)dst + got, &want) != SZ_OK) {
+      return -1;
+    }
+    if(want == 0) {
+      return -1;
+    }
+    got += want;
+  }
+  return 0;
+}
+
+/* The virtual view handed to the SDK.  `vt` has to stay first: the SDK casts
+   the interface pointer straight back to this struct, exactly as
+   sevenz_volstream.c does. */
+typedef struct {
+  ISeekInStream vt;
+
+  ISeekInStream *raw;
+  uint64_t raw_size;
+  uint64_t pos;
+  uint64_t total; /* the virtual length; the header may stick out past the file */
+
+  uint8_t sig[k7zStartHeaderSize]; /* start header, rewritten for the plaintext */
+  uint64_t hdr_off;
+  uint8_t *hdr;
+  uint64_t hdr_len;
+} szh_view;
+
+struct szh_prep {
+  szh_view view;
+};
+
+static SRes
+szh_view_read(const ISeekInStream *p, void *buf, size_t *size) {
+  szh_view *v = (szh_view *)p;
+  uint8_t *dst = (uint8_t *)buf;
+  const size_t want = *size;
+  size_t got = 0;
+
+  *size = 0;
+  while(got < want) {
+    const uint64_t pos = v->pos;
+    const uint64_t hdr_end = v->hdr_off + v->hdr_len;
+
+    if(pos < k7zStartHeaderSize) {
+      size_t n = (size_t)(k7zStartHeaderSize - pos);
+
+      if(n > want - got) {
+        n = want - got;
+      }
+      memcpy(dst + got, v->sig + pos, n);
+      got += n;
+      v->pos += n;
+      continue;
+    }
+    if(pos >= v->hdr_off && pos < hdr_end) {
+      size_t n = (size_t)(hdr_end - pos);
+
+      if(n > want - got) {
+        n = want - got;
+      }
+      memcpy(dst + got, v->hdr + (pos - v->hdr_off), n);
+      got += n;
+      v->pos += n;
+      continue;
+    }
+    /* Everything else is the real archive.  The header region can reach past
+       its end, so a read is allowed to stop short here. */
+    if(pos >= v->raw_size) {
+      break;
+    }
+    {
+      Int64 raw_pos = (Int64)pos;
+      size_t n = want - got;
+      const uint64_t avail = v->raw_size - pos;
+
+      if((uint64_t)n > avail) {
+        n = (size_t)avail;
+      }
+      if(v->raw->Seek(v->raw, &raw_pos, SZ_SEEK_SET) != SZ_OK) {
+        return SZ_ERROR_READ;
+      }
+      if(v->raw->Read(v->raw, dst + got, &n) != SZ_OK) {
+        return SZ_ERROR_READ;
+      }
+      if(n == 0) {
+        break;
+      }
+      got += n;
+      v->pos += n;
+    }
+  }
+  *size = got;
+  return SZ_OK;
+}
+
+static SRes
+szh_view_seek(const ISeekInStream *p, Int64 *pos, ESzSeek origin) {
+  szh_view *v = (szh_view *)p;
+  Int64 base;
+  Int64 next;
+
+  switch(origin) {
+  case SZ_SEEK_SET:
+    base = 0;
+    break;
+  case SZ_SEEK_CUR:
+    base = (Int64)v->pos;
+    break;
+  case SZ_SEEK_END:
+    base = (Int64)v->total;
+    break;
+  default:
+    return SZ_ERROR_PARAM;
+  }
+  next = base + *pos;
+  if(next < 0) {
+    next = 0;
+  }
+  v->pos = (uint64_t)next;
+  *pos = next;
+  return SZ_OK;
+}
+
+/* ------------------------------------------------------ decoding the header */
+
+typedef struct {
+  ISeekInStream *raw;
+  uint64_t base;
+} szh_reader_t;
+
+static int
+szh_chain_read(void *ctx, uint64_t offset, void *dst, size_t size) {
+  szh_reader_t *r = (szh_reader_t *)ctx;
+
+  return szh_read_at(r->raw, r->base + offset, dst, size);
+}
+
+/* Collects the decrypted header.  It grows on demand rather than trusting the
+   declared unpack size, which is attacker controlled. */
+typedef struct {
+  uint8_t *data;
+  size_t len;
+  size_t cap;
+  int failed;
+} szh_sink_t;
+
+static int
+szh_sink_write(void *ctx, const void *data, size_t size) {
+  szh_sink_t *s = (szh_sink_t *)ctx;
+
+  if(s->failed) {
+    return -1;
+  }
+  if((uint64_t)size > SZH_MAX_HEADER - (uint64_t)s->len) {
+    s->failed = 1;
+    return -1;
+  }
+  if(s->len + size > s->cap) {
+    size_t cap = s->cap ? s->cap : 4096;
+    uint8_t *grown;
+
+    while(cap < s->len + size) {
+      cap *= 2;
+    }
+    grown = (uint8_t *)realloc(s->data, cap);
+    if(!grown) {
+      s->failed = 1;
+      return -1;
+    }
+    s->data = grown;
+    s->cap = cap;
+  }
+  memcpy(s->data + s->len, data, size);
+  s->len += size;
+  return 0;
+}
+
+/* ------------------------------------------------------------------ public */
+
+const char *
+szh_status_string(szh_status_t status) {
+  switch(status) {
+  case SZH_PLAIN:
+    return "the archive header is readable";
+  case SZH_PATCHED:
+    return "the archive header was decrypted";
+  case SZH_ERR_PASSWORD:
+    return "the archive header is encrypted";
+  case SZH_ERR_UNSUPPORTED:
+    return "the archive header uses an unsupported arrangement";
+  case SZH_ERR_FORMAT:
+    return "the archive header is malformed";
+  case SZH_ERR_IO:
+    return "the archive header could not be read";
+  }
+  return "unknown";
+}
+
+static void
+szh_set_msg(char *msg, size_t msg_size, const char *text, const char *detail) {
+  if(!msg || !msg_size) {
+    return;
+  }
+  if(detail) {
+    snprintf(msg, msg_size, "%s: %s", text, detail);
+  } else {
+    snprintf(msg, msg_size, "%s", text);
+  }
+}
+
+szh_status_t
+szh_prepare(szh_prep **out, ISeekInStream *raw, const char *password,
+            char *msg, size_t msg_size) {
+  uint8_t sig[k7zStartHeaderSize];
+  uint64_t raw_size, next_off, next_size;
+  uint32_t next_crc;
+  uint8_t *raw_hdr = NULL;
+  szh_streams_t ss;
+  sz_chain *chain = NULL;
+  sz_chain_err_t cerr;
+  szh_sink_t sink;
+  szh_reader_t reader;
+  szh_prep *prep = NULL;
+  szh_status_t status = SZH_PLAIN;
+  uint32_t decoded_crc = 0;
+
+  if(out) {
+    *out = NULL;
+  }
+  if(!out || !raw) {
+    return SZH_ERR_IO;
+  }
+  if(msg && msg_size) {
+    msg[0] = 0;
+  }
+
+  /* Sevenz extraction runs this before SzArEx_Open, but the table is what
+     every CRC below needs and generating it twice costs nothing. */
+  CrcGenerateTable();
+  memset(&cerr, 0, sizeof(cerr));
+  memset(&sink, 0, sizeof(sink));
+
+  /* --- the start header ------------------------------------------------ */
+  raw_size = szh_size_of(raw);
+  if(raw_size < k7zStartHeaderSize || szh_read_at(raw, 0, sig, sizeof(sig))) {
+    return SZH_PLAIN;
+  }
+  if(memcmp(sig, k7zSignature, k7zSignatureSize) != 0 || sig[6] != 0) {
+    return SZH_PLAIN;
+  }
+  if(CrcCalc(sig + 12, 20) != szh_le32(sig + 8)) {
+    return SZH_PLAIN;
+  }
+
+  next_off = szh_le64(sig + 12);
+  next_size = szh_le64(sig + 20);
+  next_crc = szh_le32(sig + 28);
+
+  if(next_size == 0 || next_size > SZH_MAX_HEADER) {
+    return SZH_PLAIN;
+  }
+  if(next_off > raw_size || next_size > raw_size - next_off) {
+    return SZH_PLAIN;
+  }
+
+  /* --- the next header ------------------------------------------------- */
+  /* One byte decides it: an ordinary header (k7zIdHeader) is none of our
+     business, and a big uncompressed one is not worth reading twice. */
+  {
+    uint8_t first_byte = 0;
+
+    if(szh_read_at(raw, k7zStartHeaderSize + next_off, &first_byte, 1) ||
+       first_byte != SZH_ID_ENCODED_HEADER) {
+      return SZH_PLAIN;
+    }
+  }
+
+  raw_hdr = (uint8_t *)malloc((size_t)next_size);
+  if(!raw_hdr) {
+    szh_set_msg(msg, msg_size, "out of memory reading the archive header",
+                NULL);
+    return SZH_ERR_IO;
+  }
+  if(szh_read_at(raw, k7zStartHeaderSize + next_off, raw_hdr,
+                 (size_t)next_size) ||
+     CrcCalc(raw_hdr, (size_t)next_size) != next_crc) {
+    /* Broken or truncated: let the SDK diagnose it exactly as it always has. */
+    status = SZH_PLAIN;
+    goto done;
+  }
+  if(szh_parse_streams(raw_hdr, (size_t)next_size, &ss)) {
+    status = SZH_PLAIN;
+    goto done;
+  }
+
+  /* --- the folder behind it -------------------------------------------- */
+  if(sz_chain_parse(&chain, ss.blob, ss.blob_size, ss.pack_positions,
+                    ss.num_pack, ss.coder_unpack_sizes, ss.unpack_size,
+                    sz_chain_default_limits(), &cerr) != 0) {
+    /* Not ours to report: the SDK rejects such an archive too, and it is the
+       one that knows how to describe it. */
+    status = SZH_PLAIN;
+    goto done;
+  }
+  if(!sz_chain_needs_password(chain)) {
+    /* An ordinary compressed header (-mhc=on), which the SDK decodes itself. */
+    status = SZH_PLAIN;
+    goto done;
+  }
+  if(!password || !password[0]) {
+    szh_set_msg(msg, msg_size,
+                "the archive header is encrypted (-mhe=on), so the file names, "
+                "the folder table and the entry sizes are all inside it and the "
+                "archive cannot be listed or unpacked without the password",
+                NULL);
+    status = SZH_ERR_PASSWORD;
+    goto done;
+  }
+
+  reader.raw = raw;
+  reader.base = (uint64_t)k7zStartHeaderSize + ss.pack_pos;
+  if(sz_chain_decode(chain, szh_chain_read, &reader, szh_sink_write, &sink, NULL,
+                     NULL, password, &decoded_crc, &cerr) != 0 ||
+     sink.failed) {
+    switch(cerr.status) {
+    case SZ_CHAIN_ERR_PASSWORD:
+    case SZ_CHAIN_ERR_DATA:
+      szh_set_msg(msg, msg_size,
+                  "the encrypted archive header did not decrypt: the password "
+                  "is wrong, or the archive is damaged",
+                  cerr.message);
+      status = SZH_ERR_PASSWORD;
+      break;
+    case SZ_CHAIN_ERR_LIMIT:
+    case SZ_CHAIN_ERR_METHOD:
+    case SZ_CHAIN_ERR_LAYOUT:
+      szh_set_msg(msg, msg_size, "cannot decode the encrypted archive header",
+                  cerr.message);
+      status = SZH_ERR_UNSUPPORTED;
+      break;
+    case SZ_CHAIN_ERR_MEM:
+      szh_set_msg(msg, msg_size, "out of memory decoding the archive header",
+                  NULL);
+      status = SZH_ERR_IO;
+      break;
+    default:
+      szh_set_msg(msg, msg_size, "cannot decode the encrypted archive header",
+                  cerr.message);
+      status = SZH_ERR_FORMAT;
+      break;
+    }
+    goto done;
+  }
+  if(sink.len == 0) {
+    szh_set_msg(msg, msg_size,
+                "the encrypted archive header decrypted to nothing", NULL);
+    status = SZH_ERR_FORMAT;
+    goto done;
+  }
+  if(ss.has_crc && decoded_crc != ss.crc) {
+    szh_set_msg(msg, msg_size,
+                "the encrypted archive header decrypted to data that fails its "
+                "CRC -- the password is wrong",
+                NULL);
+    status = SZH_ERR_PASSWORD;
+    goto done;
+  }
+  if(sink.data[0] != SZH_ID_HEADER) {
+    szh_set_msg(msg, msg_size,
+                "the encrypted archive header did not decrypt to a 7z header "
+                "-- the password is wrong",
+                NULL);
+    status = SZH_ERR_PASSWORD;
+    goto done;
+  }
+
+  /* --- hand the plaintext to the SDK ----------------------------------- */
+  prep = (szh_prep *)calloc(1, sizeof(*prep));
+  if(!prep) {
+    szh_set_msg(msg, msg_size, "out of memory reading the archive header",
+                NULL);
+    status = SZH_ERR_IO;
+    goto done;
+  }
+  prep->view.raw = raw;
+  prep->view.raw_size = raw_size;
+  prep->view.pos = 0;
+  prep->view.hdr_off = (uint64_t)k7zStartHeaderSize + next_off;
+  prep->view.hdr = sink.data;
+  prep->view.hdr_len = sink.len;
+  prep->view.total = prep->view.hdr_off + prep->view.hdr_len;
+  if(prep->view.total < raw_size) {
+    prep->view.total = raw_size;
+  }
+  sink.data = NULL; /* owned by the view from here on */
+
+  memcpy(prep->view.sig, sig, sizeof(prep->view.sig));
+  szh_put_le64(prep->view.sig + 12, prep->view.hdr_off - k7zStartHeaderSize);
+  szh_put_le64(prep->view.sig + 20, prep->view.hdr_len);
+  szh_put_le32(prep->view.sig + 28,
+               CrcCalc(prep->view.hdr, (size_t)prep->view.hdr_len));
+  szh_put_le32(prep->view.sig + 8, CrcCalc(prep->view.sig + 12, 20));
+
+  prep->view.vt.Read = szh_view_read;
+  prep->view.vt.Seek = szh_view_seek;
+
+  *out = prep;
+  prep = NULL;
+  status = SZH_PATCHED;
+
+done:
+  free(raw_hdr);
+  free(sink.data);
+  sz_chain_free(chain);
+  if(prep) {
+    free(prep->view.hdr);
+    free(prep);
+  }
+  return status;
+}
+
+ISeekInStream *
+szh_stream(const szh_prep *p) {
+  return p ? (ISeekInStream *)&p->view.vt : NULL;
+}
+
+void
+szh_prep_free(szh_prep *p) {
+  if(p) {
+    free(p->view.hdr);
+    free(p);
+  }
+}
@@ -0,0 +1,106 @@
+/* sevenz_header -- reads the 7z header, decrypting it when it is encrypted.
+   part of ps5-web-file-manager
+
+   A 7z archive keeps its header at the END of the file, and when that header
+   grows past a threshold 7-Zip stores it *compressed*: the next-header region
+   then starts with a `k7zIdEncodedHeader` (0x17) record describing a single
+   folder whose output is the real header.  That folder is one of two things:
+
+     * LZMA / LZMA2 -- `-mhc=on`, the default.  The vendored SDK decodes it
+       itself, so this module reads a few bytes, sees no AES coder and steps
+       aside without changing anything.
+     * LZMA + 7zAES -- `-mhe=on`.  The C half of the SDK has no 7zAES coder at
+       all, so SzArEx_Open() gives up with SZ_ERROR_UNSUPPORTED before a single
+       folder is known: the archive cannot even be listed.
+
+   The second case is what this module exists for.  It decodes that one folder
+   with src/sevenz_chain.c -- the same decoder the archive's content goes
+   through -- and then hands the SDK a stream in which the encoded header has
+   been replaced by its plaintext.  The plaintext is longer than the record it
+   replaces, so the stream is a small virtual view over the real one:
+
+       [0, 32)                  the start header, rewritten to describe the
+                                plaintext (offset, size and CRC)
+       [32, hdr_off)            the real archive: packed streams
+       [hdr_off, hdr_off + L)   the decrypted header
+       beyond that              the real archive again
+
+   `hdr_off` is where the encoded header already lived, so no offset that the
+   archive itself stores has to move: the SDK reads the plaintext at exactly
+   the position it expected the encoded record, and the main data position it
+   derives from the plaintext still points at the real packed streams.
+
+   Nothing on disk is touched, the archive is opened read-only, and an archive
+   whose header is not encrypted is never touched at all.
+*/
+
+#ifndef SEVENZ_HEADER_H
+#define SEVENZ_HEADER_H
+
+#include <stddef.h>
+
+#include "7zTypes.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* The plaintext header is tiny in every real archive (kilobytes); the ceiling
+   only exists so a hostile encoded header cannot ask for a gigabyte. */
+#define SZH_MAX_HEADER ((uint64_t)64 * 1024 * 1024)
+
+typedef enum {
+  /* The header is readable as it stands.  Use the stream you passed in and
+     let the SDK parse it, exactly as before this module existed. */
+  SZH_PLAIN = 0,
+
+  /* The header was encrypted and is now decrypted: hand szh_stream() to
+     SzArEx_Open() instead of the raw stream. */
+  SZH_PATCHED,
+
+  /* The header is encrypted and the password given was missing or wrong.
+     Actionable: the caller should ask for one and retry. */
+  SZH_ERR_PASSWORD,
+
+  /* The encoded header uses an arrangement this module does not read. */
+  SZH_ERR_UNSUPPORTED,
+
+  /* The encoded header is malformed. */
+  SZH_ERR_FORMAT,
+
+  /* Reading the archive failed. */
+  SZH_ERR_IO
+} szh_status_t;
+
+typedef struct szh_prep szh_prep;
+
+/* Inspects the archive header behind `raw`.
+
+   On SZH_PLAIN *out is NULL and the caller proceeds with `raw` untouched.
+   On SZH_PATCHED *out owns everything and szh_stream(*out) must be used.
+   Otherwise *out is NULL and `msg` says why, in a form meant for the user.
+
+   `password` is the archive password as UTF-8, or NULL / "" when the caller
+   has none.  It is only consulted when the header turns out to be encrypted.
+
+   The function never reports an error for an archive the SDK would diagnose
+   better: anything unexpected *before* an AES coder is found -- a short file,
+   a bad signature, a header CRC mismatch, an unparsable StreamsInfo -- comes
+   back as SZH_PLAIN so the SDK keeps producing the message it always did. */
+szh_status_t szh_prepare(szh_prep **out, ISeekInStream *raw, const char *password,
+                         char *msg, size_t msg_size);
+
+/* The stream to give SzArEx_Open(); NULL when p is NULL.  Valid until
+   szh_prep_free(). */
+ISeekInStream *szh_stream(const szh_prep *p);
+
+/* Static description of a status, for messages that have no better text. */
+const char *szh_status_string(szh_status_t status);
+
+void szh_prep_free(szh_prep *p);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* SEVENZ_HEADER_H */
@@ -0,0 +1,197 @@
+#include "sevenz_mt.h"
+
+#include <stdarg.h>
+#include <stdio.h>
+#include <string.h>
+
+#include "7zTypes.h"
+#include "7zCrc.h"
+#include "Alloc.h"
+#include "Lzma2DecMt.h"
+
+/* ------------------------------------------------------------ adapters --
+   The SDK's decoders speak ISeqInStream / ISeqOutStream / ICompressProgress;
+   the engine speaks plain callbacks.  These three structs translate.  All of
+   them run on the calling thread -- MtDec only ever hands output to the
+   thread that called Lzma2DecMt_Decode, which is what makes the plain sink
+   safe to reuse here. */
+
+typedef struct {
+  ISeqInStream vt;
+  sz_chain_read_fn read_at;
+  void *read_ctx;
+  uint64_t pos; /* absolute offset of the next byte to hand out */
+  uint64_t end; /* one past the last byte of the packed stream */
+} mt_seq_in;
+
+static SRes mt_seq_read(const ISeqInStream *pp, void *buf, size_t *size) {
+  mt_seq_in *s = (mt_seq_in *)pp;
+  size_t want = *size;
+
+  *size = 0;
+  if(want == 0) {
+    return SZ_OK;
+  }
+  if(s->end - s->pos < (uint64_t)want) {
+    want = (size_t)(s->end - s->pos);
+  }
+  if(want != 0 && s->read_at(s->read_ctx, s->pos, buf, want) != 0) {
+    return SZ_ERROR_READ;
+  }
+  s->pos += want;
+  *size = want;
+  /* A short read means "end of stream" to the SDK; since we only ever hand
+     it exactly in_size bytes, hitting the end early is the caller's bug and
+     the decoder's outSize check will flag it. */
+  return SZ_OK;
+}
+
+typedef struct {
+  ISeqOutStream vt;
+  sz_chain_sink_fn sink;
+  void *sink_ctx;
+  uint32_t crc;
+  int failed;
+} mt_seq_out;
+
+static size_t mt_seq_write(const ISeqOutStream *pp, const void *buf,
+                           size_t size) {
+  mt_seq_out *s = (mt_seq_out *)pp;
+
+  if(s->failed) {
+    return 0;
+  }
+  s->crc = CrcUpdate(s->crc, buf, size);
+  if(s->sink(s->sink_ctx, buf, size) != 0) {
+    s->failed = 1;
+    /* Returning less than `size` tells the SDK the output side is done; it
+       reports SZ_ERROR_WRITE. */
+    return 0;
+  }
+  return size;
+}
+
+typedef struct {
+  ICompressProgress vt;
+  sz_chain_cancel_fn cancel;
+  void *cancel_ctx;
+} mt_progress;
+
+static SRes mt_progress_report(const ICompressProgress *pp, UInt64 in_size,
+                               UInt64 out_size) {
+  mt_progress *s = (mt_progress *)pp;
+
+  (void)in_size;
+  (void)out_size;
+  if(s->cancel && s->cancel(s->cancel_ctx)) {
+    return SZ_ERROR_PROGRESS;
+  }
+  return SZ_OK;
+}
+
+/* --------------------------------------------------------------- decode --
+   Errors are mapped onto sz_chain_err_t so the facade's reporting stays in
+   one vocabulary.  SZX_MT_ERR_THREADS is reserved for "the platform cannot
+   give me a thread pool": Lzma2DecMt returns SZ_ERROR_THREAD only from its
+   threading primitives, everything else is data or memory. */
+
+static void mt_fail(sz_chain_err_t *err, sz_chain_status_t status,
+                    const char *fmt, ...) {
+  va_list ap;
+
+  if(!err) {
+    return;
+  }
+  err->status = status;
+  err->coder = 0;
+  err->method = 0x21; /* SZ_M_LZMA2; kept literal to avoid dragging chain.c in */
+  err->offset = 0;
+  va_start(ap, fmt);
+  vsnprintf(err->message, sizeof(err->message), fmt, ap);
+  va_end(ap);
+}
+
+int szx_mt_decode(sz_chain_read_fn read_at, void *read_ctx, uint64_t in_offset,
+                  uint64_t in_size, uint8_t prop, uint64_t out_size,
+                  sz_chain_sink_fn sink, void *sink_ctx,
+                  sz_chain_cancel_fn cancel, void *cancel_ctx,
+                  uint32_t *crc_out, sz_chain_err_t *err) {
+  mt_seq_in in;
+  mt_seq_out out;
+  mt_progress progress;
+  CLzma2DecMtProps props;
+  CLzma2DecMtHandle mt;
+  UInt64 in_processed = 0;
+  int is_mt = 0;
+  SRes res;
+
+  memset(&in, 0, sizeof(in));
+  in.vt.Read = mt_seq_read;
+  in.read_at = read_at;
+  in.read_ctx = read_ctx;
+  in.pos = in_offset;
+  in.end = in_offset + in_size;
+
+  memset(&out, 0, sizeof(out));
+  out.vt.Write = mt_seq_write;
+  out.sink = sink;
+  out.sink_ctx = sink_ctx;
+  out.crc = CRC_INIT_VAL;
+
+  memset(&progress, 0, sizeof(progress));
+  progress.vt.Progress = mt_progress_report;
+  progress.cancel = cancel;
+  progress.cancel_ctx = cancel_ctx;
+
+  Lzma2DecMtProps_Init(&props);
+  props.numThreads = SZX_MT_THREADS;
+  props.inBufSize_MT = 1 << 20;
+
+  mt = Lzma2DecMt_Create(&g_Alloc, &g_MidAlloc);
+  if(!mt) {
+    mt_fail(err, SZ_CHAIN_ERR_INTERNAL, "LZMA2 MT: out of memory");
+    return -1;
+  }
+  res = Lzma2DecMt_Decode(mt, prop, &props, &out.vt, &out_size, 1, &in.vt,
+                          &in_processed, &is_mt,
+                          cancel ? &progress.vt : NULL);
+  Lzma2DecMt_Destroy(mt);
+
+  if(res == SZ_ERROR_THREAD) {
+    /* No usable thread pool (pthread init failure, thread creation denied).
+       The caller retries on the single-threaded chain path. */
+    return SZX_MT_ERR_THREADS;
+  }
+  if(out.failed) {
+    mt_fail(err, SZ_CHAIN_ERR_WRITE, "LZMA2 MT: sink rejected decoded data");
+    return -1;
+  }
+  if(res != SZ_OK) {
+    switch(res) {
+    case SZ_ERROR_PROGRESS:
+      mt_fail(err, SZ_CHAIN_ERR_CANCELED, "canceled");
+      break;
+    case SZ_ERROR_MEM:
+      mt_fail(err, SZ_CHAIN_ERR_INTERNAL, "LZMA2 MT: out of memory");
+      break;
+    case SZ_ERROR_WRITE:
+      mt_fail(err, SZ_CHAIN_ERR_WRITE, "LZMA2 MT: output stream failed");
+      break;
+    default:
+      mt_fail(err, SZ_CHAIN_ERR_DATA, "LZMA2 MT: decode failed (res=%d)",
+              (int)res);
+      break;
+    }
+    return -1;
+  }
+  if(in_processed != in_size) {
+    mt_fail(err, SZ_CHAIN_ERR_DATA,
+            "LZMA2 MT: consumed %llu of %llu packed bytes",
+            (unsigned long long)in_processed, (unsigned long long)in_size);
+    return -1;
+  }
+  if(crc_out) {
+    *crc_out = out.crc;
+  }
+  return 0;
+}
@@ -0,0 +1,40 @@
+/* Multithreaded LZMA2 decode for the 7z engine.
+ *
+ * Most 7z archives are a single plain LZMA2 coder (7-Zip's -m0=lzma2
+ * default).  For that shape the SDK's own parallel decoder -- the same code
+ * 7-Zip runs for -mmt -- replaces the single-threaded chain walk and decodes
+ * consecutive LZMA2 blocks on worker threads while the main thread streams
+ * the output into the staging sink.  Measured on a 329 MiB fixture this is
+ * worth ~1.7x on an 8-core host, on top of the assembly kernel.
+ *
+ * Threads are rented, not owned: any thread error falls back to the caller's
+ * single-threaded path, so a platform without working pthreads only ever
+ * loses speed, never correctness. */
+
+#ifndef SEVENZ_MT_H
+#define SEVENZ_MT_H
+
+#include "sevenz_chain.h"
+
+/* 8-core Zen 2 on the PS5: 4 decoders leave the HTTP server, the task
+   system and the kernel half of the machine. */
+#define SZX_MT_THREADS 8
+
+/* Decodes one folder that sz_chain_lzma2_root() has recognised.  The
+   callbacks mirror sz_chain_decode()'s: read_at/ctx for the packed data,
+   sink/ctx for the decoded bytes (both run on the calling thread; the sink
+   sees the same ordered byte stream the chain would have produced).
+   cancel/ctx is polled from the progress callback and may be NULL.
+   crc_out, when not NULL, receives the CRC-32 of the delivered bytes.
+   err, when not NULL, receives a chain-style error description.
+   Returns 0 on success; SZX_MT_ERR_THREADS means "no working thread pool"
+   and the caller should retry single-threaded; other failures are terminal. */
+#define SZX_MT_ERR_THREADS 2
+
+int szx_mt_decode(sz_chain_read_fn read_at, void *read_ctx,
+                  uint64_t in_offset, uint64_t in_size, uint8_t prop,
+                  uint64_t out_size, sz_chain_sink_fn sink, void *sink_ctx,
+                  sz_chain_cancel_fn cancel, void *cancel_ctx,
+                  uint32_t *crc_out, sz_chain_err_t *err);
+
+#endif /* SEVENZ_MT_H */
@@ -0,0 +1,356 @@
+/* sevenz_volstream -- see sevenz_volstream.h for what this does and why. */
+
+#include <stdarg.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+#if defined(_WIN32)
+#include <wchar.h>
+#endif
+
+#include "7zFile.h"
+
+#include "sevenz_volstream.h"
+#include "zipx_volume.h"
+
+struct sevenz_volstream {
+  ISeekInStream vt;
+
+  zipx_volume_t vol;   /* owns the ordered paths */
+  CSzFile *file;       /* one per part */
+  uint64_t *start;     /* count + 1 prefix offsets into the logical archive */
+  uint32_t count;
+  uint32_t open_count; /* how many entries of `file` were opened */
+  uint64_t pos;        /* current offset in the logical archive */
+  uint32_t cur;        /* part `pos` currently sits in, to skip redundant seeks */
+  uint64_t cur_off;    /* file offset within that part */
+  char name[256];      /* stem of the set, for messages */
+};
+
+/* ---------------------------------------------------------------- helpers */
+
+static char *err_printf(const char *fmt, ...) {
+  va_list ap;
+  char buf[512];
+  char *out;
+
+  va_start(ap, fmt);
+  vsnprintf(buf, sizeof(buf), fmt, ap);
+  va_end(ap);
+
+  out = (char *)malloc(strlen(buf) + 1);
+  if(out) memcpy(out, buf, strlen(buf) + 1);
+  return out;
+}
+
+static const char *file_base(const char *path) {
+  const char *slash = strrchr(path, '/');
+  const char *back = strrchr(path, '\\');
+
+  if(back && (!slash || back > slash)) slash = back;
+  return slash ? slash + 1 : path;
+}
+
+#if defined(_WIN32)
+
+/* The SDK opens through CreateFileA otherwise, which cannot see non-ASCII
+   entry names. */
+static void utf8_to_utf16(const char *src, WCHAR *dst, size_t cap) {
+  size_t out = 0;
+
+  while(*src && out + 2 < cap) {
+    unsigned char c = (unsigned char)*src++;
+    UInt32 cp;
+
+    if(c < 0x80) {
+      cp = c;
+    } else if((c & 0xE0) == 0xC0 && (src[0] & 0xC0) == 0x80) {
+      cp = ((UInt32)(c & 0x1F) << 6) | (UInt32)(*src++ & 0x3F);
+    } else if((c & 0xF0) == 0xE0 && (src[0] & 0xC0) == 0x80 &&
+              (src[1] & 0xC0) == 0x80) {
+      cp = ((UInt32)(c & 0x0F) << 12) | ((UInt32)(src[0] & 0x3F) << 6) |
+           (UInt32)(src[1] & 0x3F);
+      src += 2;
+    } else if((c & 0xF8) == 0xF0 && (src[0] & 0xC0) == 0x80 &&
+              (src[1] & 0xC0) == 0x80 && (src[2] & 0xC0) == 0x80) {
+      cp = ((UInt32)(c & 0x07) << 18) | ((UInt32)(src[0] & 0x3F) << 12) |
+           ((UInt32)(src[1] & 0x3F) << 6) | (UInt32)(src[2] & 0x3F);
+      src += 3;
+    } else {
+      cp = '?';
+    }
+
+    if(cp >= 0x10000) {
+      cp -= 0x10000;
+      dst[out++] = (WCHAR)(0xD800 | (cp >> 10));
+      dst[out++] = (WCHAR)(0xDC00 | (cp & 0x3FF));
+    } else {
+      dst[out++] = (WCHAR)cp;
+    }
+  }
+  dst[out] = 0;
+}
+
+static int open_part(CSzFile *file, const char *path) {
+  WCHAR wide[4096];
+
+  utf8_to_utf16(path, wide, sizeof(wide) / sizeof(wide[0]));
+  return InFile_OpenW(file, wide) == 0 ? 0 : -1;
+}
+
+#else
+
+static int open_part(CSzFile *file, const char *path) {
+  return InFile_Open(file, path) == 0 ? 0 : -1;
+}
+
+#endif
+
+/* ----------------------------------------------------------------- stream */
+
+static uint32_t part_at(const sevenz_volstream *v, uint64_t pos) {
+  uint32_t i;
+
+  for(i = 0; i < v->count; i++) {
+    if(pos < v->start[i + 1]) return i;
+  }
+  return v->count;
+}
+
+static SRes vol_read(const ISeekInStream *p, void *buf, size_t *size) {
+  sevenz_volstream *v = (sevenz_volstream *)p;
+  uint8_t *dst = (uint8_t *)buf;
+  size_t want = *size;
+  size_t got = 0;
+
+  *size = 0;
+  while(got < want) {
+    uint32_t i = part_at(v, v->pos);
+    uint64_t avail, off;
+    size_t take;
+
+    if(i >= v->count) break; /* end of the set: a short read means EOF */
+
+    off = v->pos - v->start[i];
+    avail = (v->start[i + 1] - v->start[i]) - off;
+    take = (size_t)(avail < (uint64_t)(want - got) ? avail
+                                                   : (uint64_t)(want - got));
+    if(take == 0) break;
+
+    if(v->cur != i || v->cur_off != off) {
+      Int64 seek = (Int64)off;
+      if(File_Seek(&v->file[i], &seek, SZ_SEEK_SET) != 0) return SZ_ERROR_READ;
+      v->cur = i;
+      v->cur_off = off;
+    }
+
+    {
+      size_t part_got = take;
+      if(File_Read(&v->file[i], dst + got, &part_got) != 0) return SZ_ERROR_READ;
+      if(part_got == 0) break;
+      got += part_got;
+      v->pos += part_got;
+      v->cur_off += part_got;
+      if(part_got < take) break;
+    }
+  }
+
+  *size = got;
+  return SZ_OK;
+}
+
+static SRes vol_seek(const ISeekInStream *p, Int64 *pos, ESzSeek origin) {
+  sevenz_volstream *v = (sevenz_volstream *)p;
+  uint64_t total = v->start[v->count];
+  uint64_t target;
+
+  switch(origin) {
+  case SZ_SEEK_SET:
+    if(*pos < 0) return SZ_ERROR_PARAM;
+    target = (uint64_t)*pos;
+    break;
+  case SZ_SEEK_CUR:
+    if(*pos < 0) {
+      UInt64 back = (UInt64)(-*pos);
+      if(back > v->pos) return SZ_ERROR_PARAM;
+      target = v->pos - back;
+    } else {
+      target = v->pos + (UInt64)*pos;
+    }
+    break;
+  case SZ_SEEK_END:
+    if(*pos < 0) {
+      UInt64 back = (UInt64)(-*pos);
+      if(back > total) return SZ_ERROR_PARAM;
+      target = total - back;
+    } else {
+      target = total + (UInt64)*pos;
+    }
+    break;
+  default:
+    return SZ_ERROR_PARAM;
+  }
+
+  if(target > total) target = total;
+  v->pos = target;
+  *pos = (Int64)target;
+  return SZ_OK;
+}
+
+/* -------------------------------------------------------------------- open */
+
+int sevenz_volstream_open(sevenz_volstream **out, const char *path, int *is_set,
+                          char **err) {
+  sevenz_volstream *v;
+  char *vol_err = NULL;
+  int detected;
+  uint32_t i;
+
+  if(out) *out = NULL;
+  if(is_set) *is_set = 0;
+  if(err) *err = NULL;
+  if(!out || !path) {
+    if(err) *err = err_printf("no archive path given");
+    return -1;
+  }
+
+  v = (sevenz_volstream *)calloc(1, sizeof(*v));
+  if(!v) {
+    if(err) *err = err_printf("out of memory");
+    return -1;
+  }
+
+  /* One call does both jobs: it either reports "ordinary file" and clears the
+     struct, or fills in the ordered part list. A -1 here already carries the
+     message the user needs (a hole in the numbering names the missing part). */
+  detected = zipx_volume_detect(path, &v->vol, &vol_err);
+  if(detected < 0) {
+    if(err) {
+      *err = vol_err ? vol_err
+                     : err_printf("'%s' cannot be read", file_base(path));
+    } else {
+      free(vol_err);
+    }
+    zipx_volume_free(&v->vol);
+    free(v);
+    return -1;
+  }
+
+  if(detected == 0) {
+    v->vol.paths = (char **)malloc(sizeof(char *));
+    if(v->vol.paths) v->vol.paths[0] = (char *)malloc(strlen(path) + 1);
+    if(!v->vol.paths || !v->vol.paths[0]) {
+      free(v->vol.paths);
+      free(v);
+      if(err) *err = err_printf("out of memory");
+      return -1;
+    }
+    memcpy(v->vol.paths[0], path, strlen(path) + 1);
+    v->vol.count = 1;
+    v->vol.mode = ZIPX_VOL_MODE_CONCAT;
+    v->vol.is_set = 0;
+  } else if(is_set) {
+    *is_set = 1;
+  }
+
+  snprintf(v->name, sizeof(v->name), "%s", file_base(path));
+
+  v->count = (uint32_t)v->vol.count;
+  v->file = (CSzFile *)calloc(v->count, sizeof(CSzFile));
+  v->start = (uint64_t *)calloc((size_t)v->count + 1, sizeof(uint64_t));
+  if(!v->file || !v->start) {
+    if(err) *err = err_printf("out of memory");
+    goto fail;
+  }
+
+  for(i = 0; i < v->count; i++) {
+    UInt64 length = 0;
+
+    File_Construct(&v->file[i]);
+    v->open_count = i + 1; /* File_Close() ignores a never-opened handle */
+    if(open_part(&v->file[i], v->vol.paths[i]) != 0) {
+      if(err) {
+        *err = err_printf("cannot open volume '%s' of '%s'",
+                          file_base(v->vol.paths[i]), v->name);
+      }
+      goto fail;
+    }
+    if(File_GetLength(&v->file[i], &length) != 0) {
+      if(err) {
+        *err = err_printf("cannot measure volume '%s' of '%s'",
+                          file_base(v->vol.paths[i]), v->name);
+      }
+      goto fail;
+    }
+    v->start[i + 1] = v->start[i] + length;
+  }
+
+  if(v->start[v->count] == 0) {
+    if(err) *err = err_printf("'%s' is empty", v->name);
+    goto fail;
+  }
+
+  /* 7-Zip cuts equal sized parts and lets only the last one be short. A part
+     of a different size in the middle means the set is damaged or was mixed
+     with another one, and decoding would fail much later with a message that
+     points nowhere useful. */
+  for(i = 0; i + 1 < v->count; i++) {
+    uint64_t size = v->start[i + 1] - v->start[i];
+    if(size != v->start[1]) {
+      if(err) {
+        *err = err_printf("volume '%s' of '%s' is %llu bytes, but the earlier "
+                          "volumes are %llu bytes: the set is not a clean split",
+                          file_base(v->vol.paths[i]), v->name,
+                          (unsigned long long)size,
+                          (unsigned long long)v->start[1]);
+      }
+      goto fail;
+    }
+  }
+
+  v->vt.Read = vol_read;
+  v->vt.Seek = vol_seek;
+  *out = v;
+  return 0;
+
+fail:
+  sevenz_volstream_free(v);
+  return -1;
+}
+
+ISeekInStream *sevenz_volstream_stream(sevenz_volstream *v) {
+  return v ? &v->vt : NULL;
+}
+
+uint32_t sevenz_volstream_count(const sevenz_volstream *v) {
+  return v ? v->count : 0;
+}
+
+uint64_t sevenz_volstream_size(const sevenz_volstream *v) {
+  return v ? v->start[v->count] : 0;
+}
+
+const char *sevenz_volstream_describe(const sevenz_volstream *v, char *buf,
+                                      unsigned size) {
+  if(!buf || size == 0) return buf;
+  if(!v) {
+    snprintf(buf, size, "no archive");
+  } else if(v->count <= 1) {
+    snprintf(buf, size, "%s", v->name);
+  } else {
+    snprintf(buf, size, "%s (%u volumes)", v->name, (unsigned)v->count);
+  }
+  return buf;
+}
+
+void sevenz_volstream_free(sevenz_volstream *v) {
+  uint32_t i;
+
+  if(!v) return;
+  for(i = 0; i < v->open_count; i++) File_Close(&v->file[i]);
+  free(v->file);
+  free(v->start);
+  zipx_volume_free(&v->vol);
+  free(v);
+}
@@ -0,0 +1,59 @@
+/* sevenz_volstream -- present a multi-file 7z volume set as one stream.
+   part of ps5-web-file-manager
+
+   A split 7z is a plain byte split: `name.7z.001`, `name.7z.002`, ... are
+   consecutive slices of one archive, so byte N of the logical archive is byte
+   N of the concatenation and every offset stored inside the stream header is
+   already absolute. Nothing has to be merged on disk -- a 160 GiB set would
+   otherwise need a second 160 GiB scratch copy.
+
+   The LZMA SDK reads through ISeekInStream, so this module implements that
+   interface over the ordered part list produced by zipx_volume. The ordered
+   list is what makes a set with a hole in it fail loudly instead of decoding
+   garbage: zipx_volume names the missing part. */
+
+#ifndef SEVENZ_VOLSTREAM_H
+#define SEVENZ_VOLSTREAM_H
+
+#include <stdint.h>
+
+#include "7zTypes.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef struct sevenz_volstream sevenz_volstream;
+
+/* Opens `path` together with every volume of the set it belongs to and exposes
+   them as one seekable byte stream. `path` may be any member of the set; an
+   ordinary single-file archive is the degenerate one-file case.
+
+   Returns 0 on success, with *is_set set to 1 when the path was part of a
+   multi-file set (non-NULL only). Returns -1 on failure and, when `err` is
+   non-NULL, stores a malloc'd message the caller must free -- an incomplete
+   set reports the missing volume by name. */
+int sevenz_volstream_open(sevenz_volstream **out, const char *path, int *is_set,
+                          char **err);
+
+/* The stream to hand to SzArEx_Open(); valid until sevenz_volstream_free(). */
+ISeekInStream *sevenz_volstream_stream(sevenz_volstream *v);
+
+/* Number of files backing the stream (1 for an ordinary archive). */
+uint32_t sevenz_volstream_count(const sevenz_volstream *v);
+
+/* Size of the whole logical archive. */
+uint64_t sevenz_volstream_size(const sevenz_volstream *v);
+
+/* Human readable description, e.g. "name.7z (3 volumes)"; writes into buf and
+   returns buf. */
+const char *sevenz_volstream_describe(const sevenz_volstream *v, char *buf,
+                                      unsigned size);
+
+void sevenz_volstream_free(sevenz_volstream *v);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif
@@ -0,0 +1,34 @@
+/*
+ * /api/version -- hands the build's VERSION_TAG to the web UI.
+ *
+ * The footer in the browser shows a version string, and for a long time that
+ * string was a literal in assets/main.js, so it drifted out of sync the moment
+ * the Makefile moved on (v1.9 stayed on screen through the whole v1.9.1
+ * release). Exposing it over the API keeps a single source of truth: bump
+ * VERSION_TAG in the Makefile and every surface -- startup notification
+ * (src/main.c), stdout banner, ELF file name and the UI footer -- follows.
+ *
+ * The response is tiny and immutable, so the client caches it for the session.
+ */
+
+#include "filemgr_internal.h"
+
+#include <string.h>
+
+#include "json_util.h"
+
+#ifndef VERSION_TAG
+#define VERSION_TAG "unknown"
+#endif
+
+enum MHD_Result
+api_version(struct MHD_Connection *conn) {
+  strbuf_t b = {0};
+
+  strbuf_append(&b, "{\"ok\":true,\"version\":");
+  json_escape(&b, VERSION_TAG);
+  strbuf_append(&b, ",\"titleId\":");
+  json_escape(&b, TITLE_ID);
+  strbuf_append(&b, "}");
+  return send_buffer(conn, MHD_HTTP_OK, b.data, "application/json");
+}
@@ -22,6 +22,9 @@
 #include "mz_strm.h"
 #include "mz_strm_os.h"

+#include "zipx_volume.h"
+#include "zipx_volstream.h"
+
 #ifndef O_CLOEXEC
 #define O_CLOEXEC 0
 #endif
@@ -33,69 +36,8 @@
 #define ZIPX_PUBLISH_MAX_DEPTH 128
 #define ZIPX_SPACE_SLACK_PER_ENTRY 512

-static const zipx_limits_t k_default_limits = {
-  .max_entries = 200000,
-  .max_total_bytes = 1ULL * 1024 * 1024 * 1024 * 1024,
-  .max_file_bytes = 256ULL * 1024 * 1024 * 1024,
-  .max_ratio = 500,
-  .max_depth = 32,
-  .max_name_len = 255,
-  .max_path_len = 1024
-};
-
-/* Large profile for archives that exceed the safe limits (e.g. 200 GB system
-   images). The relaxed ratio still rejects obvious bombs; the size caps
-   require the user to opt in via the web UI before they take effect. */
-static const zipx_limits_t k_large_limits = {
-  .max_entries = 500000,
-  .max_total_bytes = 2ULL * 1024 * 1024 * 1024 * 1024,
-  .max_file_bytes = 1ULL * 1024 * 1024 * 1024 * 1024,
-  .max_ratio = 1000,
-  .max_depth = 32,
-  .max_name_len = 255,
-  .max_path_len = 1024
-};
-
-const zipx_limits_t *
-zipx_default_limits(void) {
-  return &k_default_limits;
-}
-
-const zipx_limits_t *
-zipx_limits_profile(int profile) {
-  switch(profile) {
-  case ZIPX_LIMITS_LARGE:
-    return &k_large_limits;
-  case ZIPX_LIMITS_DEFAULT:
-  default:
-    return &k_default_limits;
-  }
-}
-
-const char *
-zipx_status_string(zipx_status_t status) {
-  switch(status) {
-  case ZIPX_OK: return "ok";
-  case ZIPX_ERR_CANCELED: return "canceled";
-  case ZIPX_ERR_OPEN: return "cannot open archive";
-  case ZIPX_ERR_FORMAT: return "corrupt archive";
-  case ZIPX_ERR_UNSUPPORTED: return "unsupported archive";
-  case ZIPX_ERR_UNSAFE_NAME: return "unsafe entry name";
-  case ZIPX_ERR_SPECIAL: return "unsupported entry type";
-  case ZIPX_ERR_DUPLICATE: return "duplicate entry name";
-  case ZIPX_ERR_LIMIT_ENTRIES: return "too many entries";
-  case ZIPX_ERR_LIMIT_FILE: return "entry too large";
-  case ZIPX_ERR_LIMIT_TOTAL: return "archive contents too large";
-  case ZIPX_ERR_LIMIT_RATIO: return "compression ratio too high";
-  case ZIPX_ERR_LIMIT_DEPTH: return "path too deep";
-  case ZIPX_ERR_LIMIT_NAME: return "path too long";
-  case ZIPX_ERR_CONFLICT: return "target already exists";
-  case ZIPX_ERR_SPACE: return "not enough space";
-  case ZIPX_ERR_IO: return "read or write failed";
-  case ZIPX_ERR_CRC: return "crc mismatch";
-  default: return "internal error";
-  }
-}
+/* The limit profiles and zipx_status_string() are format independent and live
+   in src/zipx_common.c, which every engine links. */

 /**************************************************************************
 * small helpers
@@ -107,6 +49,11 @@ typedef struct {
  zipx_cancel_fn cancel;
  zipx_progress_fn progress;
  void *userdata;
+  /* NULL or empty means "no password supplied". Both ZIP encryption schemes
+     (traditional PKWARE and WinZip AES) only need it for the entry data: the
+     central directory is never encrypted, so the scan phase can read every
+     header without it. */
+  const char *password;
  zipx_result_t *result;
  uint64_t entries_total;
  uint64_t entries_done;
@@ -662,8 +609,16 @@ scan_archive(void *zip, zipx_ctx_t *c) {
      break;
    }
    if((info->flag & MZ_ZIP_FLAG_ENCRYPTED) || info->aes_version) {
-      ret = ctx_fail(c, ZIPX_ERR_UNSUPPORTED, name, "encrypted entry");
-      break;
+      /* Encrypted entries are readable, but only with a password. The
+         password itself is verified when the entry data is opened -- for
+         ZipCrypto against the 1-2 byte header check, for WinZip AES against
+         the 2 byte PBKDF2 verifier -- so a wrong password surfaces as
+         ZIPX_ERR_PASSWORD from the extract phase rather than here. */
+      if(!c->password) {
+        ret = ctx_fail(c, ZIPX_ERR_PASSWORD, name,
+                       "entry is encrypted and no password was given");
+        break;
+      }
    }
    if(info->compression_method != MZ_COMPRESS_METHOD_STORE &&
       info->compression_method != MZ_COMPRESS_METHOD_DEFLATE) {
@@ -703,10 +658,14 @@ scan_archive(void *zip, zipx_ctx_t *c) {
        break;
      }
      if(c->limits.max_ratio && info->compressed_size > 0 &&
+         uncompressed >= c->limits.ratio_min_bytes &&
         uncompressed > (uint64_t)info->compressed_size *
                        c->limits.max_ratio) {
        ret = ctx_fail(c, ZIPX_ERR_LIMIT_RATIO, name,
-                       "compression ratio is above %u", c->limits.max_ratio);
+                       "compression ratio is above %u (%llu -> %llu bytes)",
+                       c->limits.max_ratio,
+                       (unsigned long long)info->compressed_size,
+                       (unsigned long long)uncompressed);
        break;
      }
      if(uncompressed >= c->limits.max_total_bytes ||
@@ -748,11 +707,34 @@ scan_archive(void *zip, zipx_ctx_t *c) {
 * extract phase
 **************************************************************************/

+/* Builds "<staging>/<rel>[/<leaf>]" for the plain-call fallbacks below.
+   rel may be empty (staging root); leaf may be NULL. */
+static void
+staging_path(const zipx_ctx_t *c, const char *rel, const char *leaf,
+             char *out, size_t cap) {
+  if(rel[0] && leaf) {
+    snprintf(out, cap, "%s/%s/%s", c->staging, rel, leaf);
+  } else if(rel[0]) {
+    snprintf(out, cap, "%s/%s", c->staging, rel);
+  } else if(leaf) {
+    snprintf(out, cap, "%s/%s", c->staging, leaf);
+  } else {
+    snprintf(out, cap, "%s", c->staging);
+  }
+}
+
+/* The *at() family can be present in the target libc yet fail at runtime
+   without setting errno (observed on PS5 hardware: mkdirat() returns -1
+   with errno 0, while plain path-based calls work). Every *at() call in
+   the extract phase therefore falls back to a full-path call built from
+   the staging root before reporting an I/O error. */
+
 /* Opens (creating when needed) every directory of rel below root_fd.
   Returns an open descriptor for the deepest directory. */
 static int
 open_parent_dirs(int root_fd, const char *rel, zipx_ctx_t *c) {
  char buf[ZIPX_PATH_MAX];
+  char cur[ZIPX_PATH_MAX] = "";
  int fd = root_fd;
  char *seg;
  char *save = NULL;
@@ -765,31 +747,48 @@ open_parent_dirs(int root_fd, const char *rel, zipx_ctx_t *c) {

  for(seg = strtok_r(buf, "/", &save); seg; seg = strtok_r(NULL, "/", &save)) {
    int next;
+    int made = 0;
+
+    if(cur[0]) {
+      strncat(cur, "/", sizeof(cur) - strlen(cur) - 1);
+    }
+    strncat(cur, seg, sizeof(cur) - strlen(cur) - 1);

    if(!mkdirat(fd, seg, 0777)) {
-      next = openat(fd, seg, O_RDONLY | O_DIRECTORY | O_NOFOLLOW | O_CLOEXEC);
-      if(next >= 0) {
-        chmod_0777_fd(next);
-        c->dirs_created++;
+      made = 1;
+    } else if(errno != EEXIST) {
+      char full[ZIPX_PATH_MAX];
+
+      staging_path(c, cur, NULL, full, sizeof(full));
+      if(mkdir(full, 0777) && errno != EEXIST) {
+        ctx_fail(c, ZIPX_ERR_IO, rel, "cannot create directory '%s': %s "
+                 "(errno=%d)", seg, strerror(errno), errno);
+        if(fd != root_fd) {
+          close(fd);
+        }
+        return -1;
      }
-    } else if(errno == EEXIST) {
-      next = openat(fd, seg, O_RDONLY | O_DIRECTORY | O_NOFOLLOW | O_CLOEXEC);
-    } else {
-      ctx_fail(c, ZIPX_ERR_IO, rel, "cannot create directory '%s': %s", seg,
-               strerror(errno));
-      if(fd != root_fd) {
-        close(fd);
-      }
-      return -1;
+      made = 1;
    }

+    next = openat(fd, seg, O_RDONLY | O_DIRECTORY | O_NOFOLLOW | O_CLOEXEC);
    if(next < 0) {
-      ctx_fail(c, ZIPX_ERR_IO, rel, "cannot open directory '%s': %s", seg,
-               strerror(errno));
-      if(fd != root_fd) {
-        close(fd);
+      char full[ZIPX_PATH_MAX];
+
+      staging_path(c, cur, NULL, full, sizeof(full));
+      next = open(full, O_RDONLY | O_DIRECTORY | O_NOFOLLOW | O_CLOEXEC);
+      if(next < 0) {
+        ctx_fail(c, ZIPX_ERR_IO, rel, "cannot open directory '%s': %s "
+                 "(errno=%d)", seg, strerror(errno), errno);
+        if(fd != root_fd) {
+          close(fd);
+        }
+        return -1;
      }
-      return -1;
+    }
+    if(made) {
+      chmod_0777_fd(next);
+      c->dirs_created++;
    }
    if(fd != root_fd) {
      close(fd);
@@ -839,7 +838,15 @@ write_entry(void *zip, zipx_ctx_t *c, int root_fd, const char *name,
  snprintf(tmp, sizeof(tmp), "%s%u", ZIPX_PART_PREFIX, ++c->part_counter);
  fd = openat(dir_fd, tmp, O_WRONLY | O_CREAT | O_EXCL | O_NOFOLLOW, 0600);
  if(fd < 0) {
-    ctx_fail(c, ZIPX_ERR_IO, name, "cannot create file: %s", strerror(errno));
+    /* *at() fallback (see open_parent_dirs). */
+    char full[ZIPX_PATH_MAX];
+
+    staging_path(c, dir_part, tmp, full, sizeof(full));
+    fd = open(full, O_WRONLY | O_CREAT | O_EXCL | O_NOFOLLOW, 0600);
+  }
+  if(fd < 0) {
+    ctx_fail(c, ZIPX_ERR_IO, name, "cannot create file '%s': %s (errno=%d)",
+             tmp, strerror(errno), errno);
    if(dir_fd != root_fd) {
      close(dir_fd);
    }
@@ -847,10 +854,21 @@ write_entry(void *zip, zipx_ctx_t *c, int root_fd, const char *name,
    return -1;
  }

-  if(mz_zip_entry_read_open(zip, 0, NULL) != MZ_OK) {
-    ctx_fail(c, ZIPX_ERR_FORMAT, name, "cannot read entry data");
-    ret = -1;
-    goto done;
+  {
+    /* Opening the entry data is also where a supplied password is checked:
+       mz_strm_pkcrypt.c compares the decrypted header byte(s) and
+       mz_strm_wzaes.c the 2 byte PBKDF2 verifier, both returning
+       MZ_PASSWORD_ERROR on a mismatch. */
+    int err = mz_zip_entry_read_open(zip, 0, c->password);
+
+    if(err != MZ_OK) {
+      ctx_fail(c, err == MZ_PASSWORD_ERROR ? ZIPX_ERR_PASSWORD : ZIPX_ERR_FORMAT,
+               name, "%s",
+               err == MZ_PASSWORD_ERROR ? "the password is wrong"
+                                        : "cannot read entry data");
+      ret = -1;
+      goto done;
+    }
  }

  while(ret == 0) {
@@ -918,22 +936,43 @@ write_entry(void *zip, zipx_ctx_t *c, int root_fd, const char *name,

 done:
  if(!ret) {
-    if(fsync(fd) || close(fd)) {
-      ctx_fail(c, ZIPX_ERR_IO, name, "cannot flush file: %s", strerror(errno));
+    /* No fsync here, on purpose.  The per-entry flush used to cost 20-30
+       minutes on a 95k-file archive (measured on PS5-class storage) and buys
+       nothing the design needs: a crash mid-extract leaves the staging tree,
+       which is discarded on the next run, and publish is a rename-only phase
+       (see publish_entry).  The RAR and 7z engines never flushed per entry
+       either; all three now share the same "sync nothing, rename everything"
+       policy. */
+    if(close(fd)) {
+      ctx_fail(c, ZIPX_ERR_IO, name, "cannot close file: %s", strerror(errno));
      ret = -1;
    }
    fd = -1;
  }
  if(!ret && renameat(dir_fd, tmp, dir_fd, base)) {
-    ctx_fail(c, ZIPX_ERR_IO, name, "cannot move file into place: %s",
-             strerror(errno));
-    ret = -1;
+    /* *at() fallback (see open_parent_dirs). */
+    char src_full[ZIPX_PATH_MAX];
+    char dst_full[ZIPX_PATH_MAX];
+
+    staging_path(c, dir_part, tmp, src_full, sizeof(src_full));
+    staging_path(c, dir_part, base, dst_full, sizeof(dst_full));
+    if(rename(src_full, dst_full)) {
+      ctx_fail(c, ZIPX_ERR_IO, name, "cannot move file into place: %s "
+               "(errno=%d)", strerror(errno), errno);
+      ret = -1;
+    }
  }
  if(fd >= 0) {
    close(fd);
  }
  if(ret) {
-    unlinkat(dir_fd, tmp, 0);
+    if(unlinkat(dir_fd, tmp, 0)) {
+      /* *at() fallback (see open_parent_dirs). */
+      char full[ZIPX_PATH_MAX];
+
+      staging_path(c, dir_part, tmp, full, sizeof(full));
+      unlink(full);
+    }
  } else {
    c->files_created++;
  }
@@ -1158,11 +1197,81 @@ publish_staging(zipx_ctx_t *c, const char *dst_dir, int dst_existed) {
 * public entry point
 **************************************************************************/

+/* Opens the archive for scanning. A split set is served by the volume stream;
+   because tools disagree on whether a split keeps absolute offsets or offsets
+   relative to each volume, both layouts are attempted before giving up. */
+static int
+open_archive(const char *zip_path, zipx_volume_t *vol, int vol_set,
+             zipx_ctx_t *c, void **zip_out, void **stream_out) {
+  int attempts = vol_set ? 2 : 1;
+  int attempt;
+
+  for(attempt = 0; attempt < attempts; attempt++) {
+    void *stream = NULL;
+    void *zip = NULL;
+    int rc;
+
+    if(vol_set) {
+      int mode = vol->mode;
+
+      if(attempt == 1) {
+        mode = (vol->mode == ZIPX_VOL_MODE_DISK) ? ZIPX_VOL_MODE_CONCAT
+                                                 : ZIPX_VOL_MODE_DISK;
+      }
+      stream = zipx_volstream_create(mode);
+      if(stream && zipx_volstream_set_parts(
+                     stream, (const char *const *)vol->paths,
+                     vol->count) != MZ_OK) {
+        zipx_volstream_delete(&stream);
+        stream = NULL;
+      }
+    } else {
+      stream = mz_stream_os_create();
+    }
+    zip = mz_zip_create();
+    if(!stream || !zip) {
+      if(stream) {
+        mz_stream_delete(&stream);
+      }
+      if(zip) {
+        mz_zip_delete(&zip);
+      }
+      ctx_fail(c, ZIPX_ERR_INTERNAL, zip_path, "out of memory");
+      return (int)c->result->status;
+    }
+    rc = mz_stream_open(stream, vol_set ? vol->paths[0] : zip_path,
+                        MZ_OPEN_MODE_READ);
+    if(rc == MZ_OK) {
+      rc = mz_zip_open(zip, stream, MZ_OPEN_MODE_READ);
+    }
+    if(rc == MZ_OK) {
+      *zip_out = zip;
+      *stream_out = stream;
+      return ZIPX_OK;
+    }
+    /* Wrong layout for this set (or a corrupt archive): drop it and retry. */
+    mz_zip_close(zip);
+    mz_zip_delete(&zip);
+    mz_stream_close(stream);
+    mz_stream_delete(&stream);
+  }
+
+  if(vol_set) {
+    ctx_fail(c, ZIPX_ERR_OPEN, zip_path,
+             "cannot read the split archive starting at '%s' (%d volumes): %s",
+             vol->paths[0], vol->count,
+             errno ? strerror(errno) : "no known volume layout matched");
+  } else {
+    ctx_fail(c, ZIPX_ERR_OPEN, zip_path, "%s", strerror(errno ? errno : EIO));
+  }
+  return (int)c->result->status;
+}
+
 zipx_status_t
 zipx_extract(const char *zip_path, const char *dst_dir,
             zipx_conflict_t conflict, const zipx_limits_t *limits,
             zipx_cancel_fn cancel, zipx_progress_fn progress,
-             void *userdata, zipx_result_t *result) {
+             void *userdata, const char *password, zipx_result_t *result) {
  zipx_ctx_t ctx;
  zipx_ctx_t *c = &ctx;
  char parent[ZIPX_PATH_MAX];
@@ -1173,6 +1282,8 @@ zipx_extract(const char *zip_path, const char *dst_dir,
  int root_fd = -1;
  int dst_existed = 0;
  int status = ZIPX_OK;
+  zipx_volume_t vol;
+  int vol_set = 0;

  if(!result || !zip_path || !dst_dir || !dst_dir[0]) {
    if(result) {
@@ -1184,13 +1295,16 @@ zipx_extract(const char *zip_path, const char *dst_dir,
  }

  memset(&ctx, 0, sizeof(ctx));
+  memset(&vol, 0, sizeof(vol));
+  vol.index = -1;
  memset(result, 0, sizeof(*result));
  c->result = result;
  c->conflict = conflict;
-  c->limits = limits ? *limits : k_default_limits;
+  c->limits = limits ? *limits : *zipx_default_limits();
  c->cancel = cancel;
  c->progress = progress;
  c->userdata = userdata;
+  c->password = (password && password[0]) ? password : NULL;

  snprintf(dst_copy, sizeof(dst_copy), "%s", dst_dir);
  {
@@ -1215,16 +1329,25 @@ zipx_extract(const char *zip_path, const char *dst_dir,
    goto done;
  }

-  stream = mz_stream_os_create();
-  zip = mz_zip_create();
-  if(!stream || !zip) {
-    status = ctx_fail(c, ZIPX_ERR_INTERNAL, zip_path, "out of memory");
-    goto done;
+  {
+    char *vol_err = NULL;
+    int vrc = zipx_volume_detect(zip_path, &vol, &vol_err);
+
+    if(vrc < 0) {
+      /* A volume of a set that is incomplete gets a precise message here
+         instead of a generic "cannot open" further down. */
+      status = ctx_fail(c, ZIPX_ERR_OPEN, zip_path, "%s",
+                        vol_err ? vol_err : "cannot read the volume set");
+      free(vol_err);
+      goto done;
+    }
+    free(vol_err);
+    if(vrc > 0) {
+      vol_set = 1;
+    }
  }
-  if(mz_stream_open(stream, zip_path, MZ_OPEN_MODE_READ) ||
-     mz_zip_open(zip, stream, MZ_OPEN_MODE_READ)) {
-    status = ctx_fail(c, ZIPX_ERR_OPEN, zip_path, "%s",
-                      strerror(errno ? errno : EIO));
+  status = open_archive(zip_path, &vol, vol_set, c, &zip, &stream);
+  if(status != ZIPX_OK) {
    goto done;
  }

@@ -1285,6 +1408,7 @@ done:
    mz_stream_close(stream);
    mz_stream_delete(&stream);
  }
+  zipx_volume_free(&vol);
  result->entries_total = c->entries_total;
  result->entries_done = c->entries_done;
  result->bytes_total = c->bytes_total;
@@ -20,7 +20,7 @@ typedef enum {
  ZIPX_ERR_CANCELED,
  ZIPX_ERR_OPEN,       /* cannot open the archive */
  ZIPX_ERR_FORMAT,     /* corrupt central directory / truncated */
-  ZIPX_ERR_UNSUPPORTED,/* encryption, multipart or unsupported method */
+  ZIPX_ERR_UNSUPPORTED,/* multipart or unsupported compression method */
  ZIPX_ERR_UNSAFE_NAME,/* traversal, absolute path, control chars, NUL */
  ZIPX_ERR_SPECIAL,    /* symlink / device / fifo / socket entry */
  ZIPX_ERR_DUPLICATE,  /* repeated entry or file/dir name clash inside zip */
@@ -30,7 +30,11 @@ typedef enum {
  ZIPX_ERR_LIMIT_RATIO,
  ZIPX_ERR_LIMIT_DEPTH,
  ZIPX_ERR_LIMIT_NAME,
+  ZIPX_ERR_LIMIT_DICT, /* the archive's dictionary exceeds what we allow
+                          (RAR7 headers may ask for up to 64 GiB) */
  ZIPX_ERR_CONFLICT,   /* target already exists for the chosen policy */
+  ZIPX_ERR_PASSWORD,   /* the archive is encrypted and the password is missing
+                          or wrong; the caller can prompt and retry */
  ZIPX_ERR_SPACE,
  ZIPX_ERR_IO,
  ZIPX_ERR_CRC,
@@ -48,6 +52,13 @@ typedef struct {
  uint64_t max_total_bytes;
  uint64_t max_file_bytes;
  uint32_t max_ratio;   /* uncompressed/compressed, 0 disables */
+  /* Entries whose uncompressed size is below this are never ratio-screened.
+     Small highly-compressible entries are common in legitimate archives
+     (zero-filled placeholders, sparse blobs) and are harmless because the
+     actual bytes written are bounded by the declared size and by the real
+     free-space check; the ratio screen only needs to catch entries large
+     enough to matter. */
+  uint64_t ratio_min_bytes;
  uint32_t max_depth;
  uint32_t max_name_len;
  uint32_t max_path_len;
@@ -92,6 +103,10 @@ const zipx_limits_t *zipx_limits_profile(int profile);
 const char *zipx_status_string(zipx_status_t status);

 /* Extract zip_path into dst_dir.
+   `password` may be NULL or empty when the archive is not encrypted; it is
+   used for both ZIP encryption schemes, traditional PKWARE ("ZipCrypto") and
+   WinZip AES. A missing or wrong password is reported as ZIPX_ERR_PASSWORD,
+   which the caller is expected to turn into a prompt and retry.
   Returns ZIPX_OK or an error code; *result is always filled in.
   On any failure the staging directory is removed and dst_dir is left as it
   was, except for objects already published with the overwrite policy. */
@@ -101,4 +116,5 @@ zipx_status_t zipx_extract(const char *zip_path, const char *dst_dir,
                           zipx_cancel_fn cancel,
                           zipx_progress_fn progress,
                           void *userdata,
+                           const char *password,
                           zipx_result_t *result);
@@ -0,0 +1,100 @@
+/* Bits of the zipx_* contract that are not specific to a container format.
+
+   The limit profiles and the status-to-text mapping describe the *engine
+   family*, not ZIP, so they live here rather than inside zip_extract.c.  All
+   three engines (ZIP, RAR, 7z) link this one object; keeping them in the ZIP
+   file would force the RAR and 7z test builds to drag in minizip-ng and zlib
+   for the sake of three functions. */
+
+#include "zip_extract.h"
+
+/* Default limits.
+ *
+ * Tuned to cover real-world PS5 workloads without prompting:
+ *   - PS5 system backup archives (~200-300 GiB total, individual chunks
+ *     well under 64 GiB)
+ *   - 3A-game archives with a single ~300 GiB uncompressed file
+ *
+ * Safety against decompression bombs is delegated to:
+ *   1. `check_space()` (statvfs-based real disk space check) before extract
+ *   2. `max_ratio` below (declared compression ratio cap)
+ * The size caps here are an early-fail UX guard, not a security boundary.
+ */
+static const zipx_limits_t k_default_limits = {
+  .max_entries = 200000,
+  .max_total_bytes = 2ULL * 1024 * 1024 * 1024 * 1024,
+  .max_file_bytes = 512ULL * 1024 * 1024 * 1024,
+  .max_ratio = 500,
+  /* Only entries that would individually materialise >=1 GiB are screened
+     by ratio; anything smaller is harmless (bounded by declared size + the
+     real free-space check) and is commonly highly compressible in
+     legitimate archives. */
+  .ratio_min_bytes = 1ULL * 1024 * 1024 * 1024,
+  .max_depth = 32,
+  .max_name_len = 255,
+  .max_path_len = 1024
+};
+
+/* Large profile for archives that exceed the default cap.
+ *
+ *   - max_file_bytes  = 1 TiB   (single uncompressed file)
+ *   - max_total_bytes = 4 TiB   (whole archive)
+ *   - max_ratio       = 1000    (relaxed ratio cap; check_space still applies)
+ *
+ * Requires the user to opt in via the web UI (large=1) before these take
+ * effect. Default limits must always be strictly smaller than large so the
+ * large profile is unambiguously a relaxation.
+ */
+static const zipx_limits_t k_large_limits = {
+  .max_entries = 500000,
+  .max_total_bytes = 4ULL * 1024 * 1024 * 1024 * 1024,
+  .max_file_bytes = 1ULL * 1024 * 1024 * 1024 * 1024,
+  .max_ratio = 1000,
+  .ratio_min_bytes = 1ULL * 1024 * 1024 * 1024,
+  .max_depth = 32,
+  .max_name_len = 255,
+  .max_path_len = 1024
+};
+
+const zipx_limits_t *
+zipx_default_limits(void) {
+  return &k_default_limits;
+}
+
+const zipx_limits_t *
+zipx_limits_profile(int profile) {
+  switch(profile) {
+  case ZIPX_LIMITS_LARGE:
+    return &k_large_limits;
+  case ZIPX_LIMITS_DEFAULT:
+  default:
+    return &k_default_limits;
+  }
+}
+
+const char *
+zipx_status_string(zipx_status_t status) {
+  switch(status) {
+  case ZIPX_OK: return "ok";
+  case ZIPX_ERR_CANCELED: return "canceled";
+  case ZIPX_ERR_OPEN: return "cannot open archive";
+  case ZIPX_ERR_FORMAT: return "corrupt archive";
+  case ZIPX_ERR_UNSUPPORTED: return "unsupported archive";
+  case ZIPX_ERR_UNSAFE_NAME: return "unsafe entry name";
+  case ZIPX_ERR_SPECIAL: return "unsupported entry type";
+  case ZIPX_ERR_DUPLICATE: return "duplicate entry name";
+  case ZIPX_ERR_LIMIT_ENTRIES: return "too many entries";
+  case ZIPX_ERR_LIMIT_FILE: return "entry too large";
+  case ZIPX_ERR_LIMIT_TOTAL: return "archive contents too large";
+  case ZIPX_ERR_LIMIT_RATIO: return "compression ratio too high";
+  case ZIPX_ERR_LIMIT_DEPTH: return "path too deep";
+  case ZIPX_ERR_LIMIT_NAME: return "path too long";
+  case ZIPX_ERR_LIMIT_DICT: return "dictionary too large";
+  case ZIPX_ERR_CONFLICT: return "target already exists";
+  case ZIPX_ERR_PASSWORD: return "password required or wrong";
+  case ZIPX_ERR_SPACE: return "not enough space";
+  case ZIPX_ERR_IO: return "read or write failed";
+  case ZIPX_ERR_CRC: return "crc mismatch";
+  default: return "internal error";
+  }
+}
@@ -0,0 +1,438 @@
+/* zipx_volstream -- present a multi-file archive volume set as one stream.
+   part of ps5-web-file-manager
+
+   See zipx_volstream.h for the two split layouts this supports. */
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+#include "mz.h"
+#include "mz_os.h"
+#include "mz_strm.h"
+#include "mz_strm_os.h"
+
+#include "zipx_volstream.h"
+
+#define VOL_INT32_MAX 0x7fffffffLL
+
+typedef struct {
+  mz_stream stream;   /* first member: callbacks cast the handle to this */
+  char **paths;       /* ordered part paths */
+  int32_t count;
+  int64_t *prefix;    /* count + 1 entries, prefix[count] == total */
+  int64_t total;
+  int32_t mode;       /* ZIPX_VOL_MODE_* */
+  int32_t disk;       /* active part index */
+  int64_t pos;        /* absolute position inside the concatenated set */
+  int32_t os_part;    /* part currently held by os, -1 when nothing is open */
+  void *os;
+  int32_t opened;
+  int32_t error;
+} zipx_volstream_t;
+
+/* ------------------------------------------------------------------------- */
+
+static int32_t
+vol_use_part(zipx_volstream_t *v, int32_t part) {
+  if(v->os_part == part) {
+    return MZ_OK;
+  }
+  if(v->os_part >= 0) {
+    mz_stream_close(v->os);
+    v->os_part = -1;
+  }
+  if(mz_stream_open(v->os, v->paths[part], MZ_OPEN_MODE_READ) != MZ_OK) {
+    v->error = MZ_OPEN_ERROR;
+    return MZ_OPEN_ERROR;
+  }
+  v->os_part = part;
+  return MZ_OK;
+}
+
+/* Part holding an absolute offset, walking from `hint` (parts are laid out in
+   order and reads are sequential, so this stays O(1) amortised). */
+static int32_t
+vol_part_of(zipx_volstream_t *v, int64_t pos, int32_t hint) {
+  int32_t i;
+
+  if(pos < 0 || pos >= v->total) {
+    return -1;
+  }
+  i = hint;
+  if(i < 0) {
+    i = 0;
+  }
+  if(i > v->count - 1) {
+    i = v->count - 1;
+  }
+  while(i > 0 && pos < v->prefix[i]) {
+    i--;
+  }
+  while(i < v->count - 1 && pos >= v->prefix[i + 1]) {
+    i++;
+  }
+  return i;
+}
+
+static int32_t
+vol_open(void *stream, const char *path, int32_t mode) {
+  zipx_volstream_t *v = (zipx_volstream_t *)stream;
+  int64_t sum = 0;
+  int32_t i;
+
+  (void)path;
+  (void)mode;
+  if(!v || v->count <= 0 || !v->paths) {
+    return MZ_PARAM_ERROR;
+  }
+  v->prefix = (int64_t *)calloc((size_t)v->count + 1, sizeof(*v->prefix));
+  if(!v->prefix) {
+    v->error = MZ_MEM_ERROR;
+    return MZ_MEM_ERROR;
+  }
+  for(i = 0; i < v->count; i++) {
+    int64_t size = mz_os_get_file_size(v->paths[i]);
+
+    if(size < 0) {
+      v->error = MZ_OPEN_ERROR;
+      return MZ_OPEN_ERROR;
+    }
+    v->prefix[i] = sum;
+    sum += size;
+  }
+  v->prefix[v->count] = sum;
+  v->total = sum;
+
+  if(!v->os) {
+    v->os = mz_stream_os_create();
+    if(!v->os) {
+      v->error = MZ_MEM_ERROR;
+      return MZ_MEM_ERROR;
+    }
+  }
+  /* The end-of-central-directory record sits on the last disk, so a split
+     disk set starts there; a byte split is read from its first byte. */
+  v->disk = (v->mode == ZIPX_VOL_MODE_DISK) ? v->count - 1 : 0;
+  v->pos = v->prefix[v->disk];
+  v->os_part = -1;
+  v->opened = 1;
+  v->error = MZ_OK;
+  return MZ_OK;
+}
+
+static int32_t
+vol_is_open(void *stream) {
+  zipx_volstream_t *v = (zipx_volstream_t *)stream;
+
+  return (v && v->opened) ? MZ_OK : MZ_OPEN_ERROR;
+}
+
+static int32_t
+vol_read(void *stream, void *buf, int32_t size) {
+  zipx_volstream_t *v = (zipx_volstream_t *)stream;
+  int32_t done = 0;
+  int32_t hint;
+
+  if(!v || !v->opened || !buf) {
+    return MZ_PARAM_ERROR;
+  }
+  if(size <= 0) {
+    return 0;
+  }
+  hint = v->os_part >= 0 ? v->os_part : 0;
+  while(done < size) {
+    int32_t part = vol_part_of(v, v->pos, hint);
+    int64_t in_part;
+    int64_t avail;
+    int64_t want;
+    int32_t got;
+
+    if(part < 0) {
+      break;                       /* end of the logical archive */
+    }
+    hint = part;
+    if(vol_use_part(v, part) != MZ_OK) {
+      break;
+    }
+    in_part = v->pos - v->prefix[part];
+    avail = (v->prefix[part + 1] - v->prefix[part]) - in_part;
+    if(avail <= 0) {               /* empty part: step over it */
+      v->pos = v->prefix[part + 1];
+      continue;
+    }
+    want = (int64_t)(size - done);
+    if(want > avail) {
+      want = avail;
+    }
+    if(want > VOL_INT32_MAX) {
+      want = VOL_INT32_MAX;
+    }
+    if(mz_stream_tell(v->os) != in_part) {
+      if(mz_stream_seek(v->os, in_part, MZ_SEEK_SET) != MZ_OK) {
+        v->error = MZ_SEEK_ERROR;
+        break;
+      }
+    }
+    got = mz_stream_read(v->os, (uint8_t *)buf + done, (int32_t)want);
+    if(got <= 0) {
+      if(got < 0) {
+        v->error = MZ_READ_ERROR;
+      }
+      break;
+    }
+    done += got;
+    v->pos += got;
+    if(got < (int32_t)want) {
+      break;                       /* short read: let the caller come back */
+    }
+  }
+  if(done == 0 && v->error != MZ_OK) {
+    return v->error;
+  }
+  return done;
+}
+
+static int32_t
+vol_write(void *stream, const void *buf, int32_t size) {
+  (void)stream;
+  (void)buf;
+  (void)size;
+  return MZ_SUPPORT_ERROR;
+}
+
+static int64_t
+vol_tell(void *stream) {
+  zipx_volstream_t *v = (zipx_volstream_t *)stream;
+
+  if(!v || !v->opened) {
+    return -1;
+  }
+  if(v->mode == ZIPX_VOL_MODE_DISK) {
+    return v->pos - v->prefix[v->disk];
+  }
+  return v->pos;
+}
+
+static int32_t
+vol_seek(void *stream, int64_t offset, int32_t origin) {
+  zipx_volstream_t *v = (zipx_volstream_t *)stream;
+  int64_t target;
+
+  if(!v || !v->opened) {
+    return MZ_PARAM_ERROR;
+  }
+  if(origin == MZ_SEEK_SET) {
+    target = offset;
+    if(v->mode == ZIPX_VOL_MODE_DISK) {
+      target += v->prefix[v->disk];   /* offsets are disk relative there */
+    }
+  } else if(origin == MZ_SEEK_CUR) {
+    target = v->pos + offset;
+  } else if(origin == MZ_SEEK_END) {
+    target = v->total + offset;
+  } else {
+    return MZ_PARAM_ERROR;
+  }
+  if(target < 0) {
+    target = 0;
+  }
+  if(target > v->total) {
+    target = v->total;
+  }
+  v->pos = target;
+  return MZ_OK;
+}
+
+static int32_t
+vol_close(void *stream) {
+  zipx_volstream_t *v = (zipx_volstream_t *)stream;
+
+  if(!v) {
+    return MZ_PARAM_ERROR;
+  }
+  if(v->os && v->os_part >= 0) {
+    mz_stream_close(v->os);
+    v->os_part = -1;
+  }
+  v->opened = 0;
+  return MZ_OK;
+}
+
+static int32_t
+vol_error(void *stream) {
+  zipx_volstream_t *v = (zipx_volstream_t *)stream;
+
+  return v ? v->error : MZ_PARAM_ERROR;
+}
+
+static int32_t
+vol_get_prop(void *stream, int32_t prop, int64_t *value) {
+  zipx_volstream_t *v = (zipx_volstream_t *)stream;
+
+  if(!v || !value) {
+    return MZ_PARAM_ERROR;
+  }
+  if(v->mode != ZIPX_VOL_MODE_DISK) {
+    /* A byte split keeps absolute offsets, so the disk properties must look
+       unsupported: minizip-ng then leaves every offset alone. */
+    return MZ_PARAM_ERROR;
+  }
+  if(prop == MZ_STREAM_PROP_DISK_NUMBER) {
+    *value = v->disk;
+    return MZ_OK;
+  }
+  if(prop == MZ_STREAM_PROP_DISK_SIZE) {
+    *value = v->prefix[v->disk + 1] - v->prefix[v->disk];
+    return MZ_OK;
+  }
+  return MZ_PARAM_ERROR;
+}
+
+static int32_t
+vol_set_prop(void *stream, int32_t prop, int64_t value) {
+  zipx_volstream_t *v = (zipx_volstream_t *)stream;
+
+  if(!v) {
+    return MZ_PARAM_ERROR;
+  }
+  if(prop != MZ_STREAM_PROP_DISK_NUMBER || v->mode != ZIPX_VOL_MODE_DISK) {
+    return MZ_PARAM_ERROR;
+  }
+  if(value < 0) {
+    /* minizip-ng passes -1 for entries that live on the same disk as the
+       central directory, which is the final volume of the set. */
+    v->disk = v->count - 1;
+    v->pos = v->prefix[v->disk];
+    return MZ_OK;
+  }
+  if(value >= v->count) {
+    return MZ_PARAM_ERROR;
+  }
+  v->disk = (int32_t)value;
+  v->pos = v->prefix[v->disk];
+  return MZ_OK;
+}
+
+/* ------------------------------------------------------------------------- */
+
+static void vol_destroy(void **stream);
+
+static mz_stream_vtbl vol_vtbl = {
+  vol_open, vol_is_open, vol_read, vol_write, vol_tell, vol_seek, vol_close,
+  vol_error, NULL, vol_destroy, vol_get_prop, vol_set_prop,
+};
+
+static void *
+vol_create(void) {
+  zipx_volstream_t *v = (zipx_volstream_t *)calloc(1, sizeof(*v));
+
+  if(!v) {
+    return NULL;
+  }
+  v->stream.vtbl = &vol_vtbl;
+  v->os_part = -1;
+  return (void *)&v->stream;
+}
+
+static void
+vol_destroy(void **stream) {
+  zipx_volstream_t *v;
+  int32_t i;
+
+  if(!stream || !*stream) {
+    return;
+  }
+  v = (zipx_volstream_t *)*stream;
+  vol_close(&v->stream);
+  if(v->os) {
+    mz_stream_os_delete(&v->os);
+  }
+  if(v->paths) {
+    for(i = 0; i < v->count; i++) {
+      free(v->paths[i]);
+    }
+    free(v->paths);
+  }
+  free(v->prefix);
+  free(v);
+  *stream = NULL;
+}
+
+/* ------------------------------------------------------------------------- */
+
+void *
+zipx_volstream_create(int32_t mode) {
+  void *stream = vol_create();
+  zipx_volstream_t *v = (zipx_volstream_t *)stream;
+
+  if(!v) {
+    return NULL;
+  }
+  v->mode = (mode == ZIPX_VOL_MODE_DISK) ? ZIPX_VOL_MODE_DISK :
+                                           ZIPX_VOL_MODE_CONCAT;
+  return stream;
+}
+
+void
+zipx_volstream_delete(void **stream) {
+  mz_stream_delete(stream);   /* routes through vtbl->destroy */
+}
+
+int32_t
+zipx_volstream_set_parts(void *stream, const char *const *paths, int32_t count) {
+  zipx_volstream_t *v = (zipx_volstream_t *)stream;
+  int32_t i;
+
+  if(!v || !paths || count <= 0) {
+    return MZ_PARAM_ERROR;
+  }
+  v->paths = (char **)calloc((size_t)count, sizeof(*v->paths));
+  if(!v->paths) {
+    return MZ_MEM_ERROR;
+  }
+  v->count = count;
+  for(i = 0; i < count; i++) {
+    size_t len = strlen(paths[i]) + 1;
+
+    v->paths[i] = (char *)malloc(len);
+    if(!v->paths[i]) {
+      return MZ_MEM_ERROR;
+    }
+    memcpy(v->paths[i], paths[i], len);
+  }
+  return MZ_OK;
+}
+
+int64_t
+zipx_volstream_total(void *stream) {
+  zipx_volstream_t *v = (zipx_volstream_t *)stream;
+
+  return v ? v->total : -1;
+}
+
+const char *
+zipx_volstream_describe(void *stream, char *buf, unsigned int size) {
+  zipx_volstream_t *v = (zipx_volstream_t *)stream;
+  const char *base;
+
+  if(!buf || size == 0) {
+    return "";
+  }
+  if(!v || v->count <= 0) {
+    snprintf(buf, size, "(no volumes)");
+    return buf;
+  }
+  base = strrchr(v->paths[0], '/');
+#ifdef _WIN32
+  {
+    const char *alt = strrchr(v->paths[0], '\\');
+    if(alt && (!base || alt > base)) {
+      base = alt;
+    }
+  }
+#endif
+  base = base ? base + 1 : v->paths[0];
+  snprintf(buf, size, "%s (%d volumes)", base, (int)v->count);
+  return buf;
+}
@@ -0,0 +1,56 @@
+/* zipx_volstream -- present a multi-file archive volume set as one stream.
+   part of ps5-web-file-manager
+
+   Two split layouts exist in the wild and they need different behaviour:
+
+   ZIPX_VOL_MODE_CONCAT (byte split)
+     `name.zip.001`, `name.zip.002`, ... (7-Zip) and `name.part1.zip`,
+     `name.part2.zip` (WinRAR). Each part is a byte slice of one archive, so
+     byte N of the logical archive is byte N of the concatenation and every
+     offset stored inside the archive is already absolute. Offsets are passed
+     through untouched and the disk properties are reported as unsupported so
+     minizip-ng keeps using absolute offsets.
+
+   ZIPX_VOL_MODE_DISK (zip split disks)
+     `name.z01`, `name.z02`, ..., `name.zip` (Info-ZIP / PKZIP style). The
+     central directory stores the offset of a local header relative to the
+     disk it starts on, so minizip-ng switches the active disk through
+     MZ_STREAM_PROP_DISK_NUMBER before seeking. Seek/tell are relative to the
+     active disk here, which is exactly what mz_zip_entry_seek_local_header
+     expects, and the stream starts on the last disk because that is where the
+     end-of-central-directory record lives. */
+
+#ifndef ZIPX_VOLSTREAM_H
+#define ZIPX_VOLSTREAM_H
+
+#include <stdint.h>
+
+#include "zipx_volume.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* Creates a stream handle; pass it to mz_stream_open() afterwards. */
+void *zipx_volstream_create(int32_t mode);
+
+/* Deletes a handle created above (safe with *stream == NULL). */
+void zipx_volstream_delete(void **stream);
+
+/* Copies the ordered part paths into the handle. Must be called before the
+   stream is opened. Returns MZ_OK (0) or MZ_MEM_ERROR (-4). */
+int32_t zipx_volstream_set_parts(void *stream, const char *const *paths,
+                                 int32_t count);
+
+/* Total logical size (sum of the part sizes), or -1 when not resolved. */
+int64_t zipx_volstream_total(void *stream);
+
+/* Human readable description of the set, e.g. "name.z01 (3 volumes)".
+   Writes into buf and returns buf. */
+const char *zipx_volstream_describe(void *stream, char *buf, unsigned int size);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif
@@ -0,0 +1,600 @@
+/* zipx_volume -- see zipx_volume.h for what this groups and why. */
+
+#include <ctype.h>
+#include <dirent.h>
+#include <stdarg.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <strings.h>
+#include <sys/stat.h>
+
+#include "zipx_volume.h"
+
+typedef struct {
+  long num;
+  char *path;
+} vol_part_t;
+
+/* ------------------------------------------------------------------------- */
+/* path helpers                                                              */
+
+static const char *
+file_base(const char *path) {
+  const char *slash = strrchr(path, '/');
+  const char *back = strrchr(path, '\\');
+
+  if(back && (!slash || back > slash)) {
+    slash = back;
+  }
+  return slash ? slash + 1 : path;
+}
+
+/* Directory part without a trailing separator; "" for a bare filename. */
+static void
+file_dir(const char *path, char *buf, size_t size) {
+  const char *base = file_base(path);
+  size_t len = (size_t)(base - path);
+
+  while(len > 0 && (path[len - 1] == '/' || path[len - 1] == '\\')) {
+    len--;
+  }
+  if(len >= size) {
+    len = size - 1;
+  }
+  memcpy(buf, path, len);
+  buf[len] = 0;
+}
+
+static int
+ends_with_ci(const char *s, const char *suffix) {
+  size_t ls = strlen(s);
+  size_t lf = strlen(suffix);
+
+  if(lf > ls) {
+    return 0;
+  }
+  return strcasecmp(s + ls - lf, suffix) == 0;
+}
+
+static int
+file_exists(const char *path) {
+  struct stat st;
+
+  return stat(path, &st) == 0;
+}
+
+static char *
+vol_join(const char *dir, const char *name) {
+  size_t need = strlen(dir) + strlen(name) + 2;
+  char *out = (char *)malloc(need);
+
+  if(!out) {
+    return NULL;
+  }
+  if(dir[0]) {
+    snprintf(out, need, "%s/%s", dir, name);
+  } else {
+    snprintf(out, need, "%s", name);
+  }
+  return out;
+}
+
+static char *
+err_printf(const char *fmt, ...) {
+  va_list ap;
+  char *buf;
+  int need;
+
+  va_start(ap, fmt);
+  need = vsnprintf(NULL, 0, fmt, ap);
+  va_end(ap);
+  if(need < 0) {
+    return NULL;
+  }
+  buf = (char *)malloc((size_t)need + 1);
+  if(!buf) {
+    return NULL;
+  }
+  va_start(ap, fmt);
+  vsnprintf(buf, (size_t)need + 1, fmt, ap);
+  va_end(ap);
+  return buf;
+}
+
+/* ------------------------------------------------------------------------- */
+/* part collection                                                           */
+
+/* Matches "PREFIX<digits>SUFFIX"; returns 1 and the value on a match. */
+static int
+match_numbered(const char *entry, const char *prefix, const char *suffix,
+               long *num) {
+  size_t plen = strlen(prefix);
+  size_t slen = strlen(suffix);
+  const char *p;
+  char *end = NULL;
+  long value;
+
+  if(strncmp(entry, prefix, plen) != 0) {
+    return 0;
+  }
+  p = entry + plen;
+  if(!isdigit((unsigned char)*p)) {
+    return 0;
+  }
+  value = strtol(p, &end, 10);
+  if(end == p) {
+    return 0;
+  }
+  if(slen > 0) {
+    if(strcmp(end, suffix) != 0) {
+      return 0;
+    }
+  } else if(*end != 0) {
+    return 0;
+  }
+  *num = value;
+  return 1;
+}
+
+static int
+part_compare(const void *a, const void *b) {
+  const vol_part_t *pa = (const vol_part_t *)a;
+  const vol_part_t *pb = (const vol_part_t *)b;
+
+  if(pa->num < pb->num) {
+    return -1;
+  }
+  if(pa->num > pb->num) {
+    return 1;
+  }
+  return 0;
+}
+
+static void
+free_parts(vol_part_t *parts, int count) {
+  int i;
+
+  for(i = 0; i < count; i++) {
+    free(parts[i].path);
+    parts[i].path = NULL;
+  }
+}
+
+/* Collects every entry in `dir` matching PREFIX<digits>SUFFIX, ordered by the
+   number. Returns the count, or -1 when the directory cannot be listed (with
+   *err set) or the set is larger than `max`. */
+static int
+scan_parts(const char *dir, const char *prefix, const char *suffix,
+           vol_part_t *parts, int max, char **err) {
+  const char *target = dir[0] ? dir : ".";
+  DIR *d = opendir(target);
+  struct dirent *ent;
+  int count = 0;
+
+  if(!d) {
+    if(err && !*err) {
+      *err = err_printf("cannot list the directory '%s' that holds the other "
+                        "volumes", target);
+    }
+    return -1;
+  }
+  while((ent = readdir(d)) != NULL) {
+    long num = 0;
+
+    if(!match_numbered(ent->d_name, prefix, suffix, &num)) {
+      continue;
+    }
+    if(count >= max) {
+      if(err && !*err) {
+        *err = err_printf("volume set has more than %d parts, the supported "
+                          "maximum", max);
+      }
+      free_parts(parts, count);
+      closedir(d);
+      return -1;
+    }
+    parts[count].num = num;
+    parts[count].path = vol_join(dir, ent->d_name);
+    if(!parts[count].path) {
+      free_parts(parts, count + 1);
+      closedir(d);
+      return -1;
+    }
+    count++;
+  }
+  closedir(d);
+  qsort(parts, (size_t)count, sizeof(*parts), part_compare);
+  return count;
+}
+
+/* Verifies the parts are numbered 1..count with no gap (and no duplicate),
+   filling *err with the exact missing name when they are not. */
+static int
+check_contiguous(vol_part_t *parts, int count, const char *dir,
+                 const char *prefix, const char *suffix, int width,
+                 char **err) {
+  int i;
+
+  for(i = 0; i < count; i++) {
+    if(parts[i].num != (long)(i + 1)) {
+      if(err && !*err) {
+        char name[512];
+        char *full;
+
+        snprintf(name, sizeof(name), "%s%0*ld%s", prefix, width,
+                 (long)(i + 1), suffix);
+        full = vol_join(dir, name);
+        *err = err_printf("volume set is incomplete: '%s' is missing",
+                          full ? full : name);
+        free(full);
+      }
+      return -1;
+    }
+  }
+  return 0;
+}
+
+/* ------------------------------------------------------------------------- */
+/* volume set bookkeeping                                                    */
+
+static void
+volume_reset(zipx_volume_t *vol) {
+  memset(vol, 0, sizeof(*vol));
+  vol->index = -1;
+}
+
+static int
+volume_take(zipx_volume_t *vol, vol_part_t *parts, int count, int mode,
+            const char *selected) {
+  int i;
+
+  vol->paths = (char **)calloc((size_t)count, sizeof(*vol->paths));
+  if(!vol->paths) {
+    return -1;
+  }
+  for(i = 0; i < count; i++) {
+    vol->paths[i] = parts[i].path;
+    parts[i].path = NULL;   /* ownership moves into vol */
+  }
+  vol->count = count;
+  vol->mode = mode;
+  vol->is_set = 1;
+  vol->index = -1;
+  for(i = 0; i < count; i++) {
+    if(selected && strcmp(vol->paths[i], selected) == 0) {
+      vol->index = i;
+      break;
+    }
+  }
+  return 0;
+}
+
+/* ------------------------------------------------------------------------- */
+/* detection: name.zip.001 / name.7z.001 / name.rar.001                      */
+
+static int
+detect_digit_suffix(const char *dir, const char *base, const char *selected,
+                    zipx_volume_t *vol, char **err) {
+  static const char *const known[] = { "zip", "7z", "rar", NULL };
+  const char *dot = strrchr(base, '.');
+  vol_part_t parts[ZIPX_VOL_MAX_PARTS];
+  char stem[2048];
+  char prefix[2100];
+  size_t stem_len;
+  int count;
+  int i;
+  int known_ext = 0;
+
+  if(!dot || dot == base || !dot[1]) {
+    return 0;
+  }
+  for(i = 1; dot[i]; i++) {
+    if(!isdigit((unsigned char)dot[i])) {
+      return 0;
+    }
+  }
+  stem_len = (size_t)(dot - base);
+  if(stem_len >= sizeof(stem)) {
+    return 0;
+  }
+  memcpy(stem, base, stem_len);
+  stem[stem_len] = 0;
+  for(i = 0; known[i]; i++) {
+    char tail[8];
+
+    snprintf(tail, sizeof(tail), ".%s", known[i]);
+    if(ends_with_ci(stem, tail)) {
+      known_ext = 1;
+      break;
+    }
+  }
+  if(!known_ext) {
+    return 0;   /* "backup.001" style names are not archive volumes */
+  }
+  snprintf(prefix, sizeof(prefix), "%s.", stem);
+  count = scan_parts(dir, prefix, "", parts, ZIPX_VOL_MAX_PARTS, err);
+  if(count < 0) {
+    return -1;
+  }
+  if(count <= 1) {
+    free_parts(parts, count > 0 ? count : 0);
+    if(count == 1 && err && !*err) {
+      *err = err_printf("'%s' is the first volume of a split archive but no "
+                        "other volumes ('%s.002', ...) are present", base,
+                        stem);
+    }
+    return count == 1 ? -1 : 0;
+  }
+  if(check_contiguous(parts, count, dir, prefix, "", 3, err)) {
+    free_parts(parts, count);
+    return -1;
+  }
+  if(volume_take(vol, parts, count, ZIPX_VOL_MODE_CONCAT, selected)) {
+    free_parts(parts, count);
+    return -1;
+  }
+  return 1;
+}
+
+/* ------------------------------------------------------------------------- */
+/* detection: name.z01 ... name.zip                                          */
+
+static int
+detect_z_suffix(const char *dir, const char *base, const char *selected,
+                zipx_volume_t *vol, char **err) {
+  const char *dot = strrchr(base, '.');
+  vol_part_t parts[ZIPX_VOL_MAX_PARTS];
+  char stem[2048];
+  char prefix[2100];
+  size_t stem_len;
+  int count;
+
+  if(!dot || dot == base) {
+    return 0;
+  }
+  if((dot[1] != 'z' && dot[1] != 'Z') || !isdigit((unsigned char)dot[2])) {
+    return 0;
+  }
+  {
+    int i;
+
+    for(i = 2; dot[i]; i++) {
+      if(!isdigit((unsigned char)dot[i])) {
+        return 0;
+      }
+    }
+  }
+  stem_len = (size_t)(dot - base);
+  if(stem_len >= sizeof(stem)) {
+    return 0;
+  }
+  memcpy(stem, base, stem_len);
+  stem[stem_len] = 0;
+
+  snprintf(prefix, sizeof(prefix), "%s.z", stem);
+  count = scan_parts(dir, prefix, "", parts, ZIPX_VOL_MAX_PARTS - 1, err);
+  if(count < 0) {
+    return -1;
+  }
+  if(count == 0) {
+    return 0;
+  }
+  if(check_contiguous(parts, count, dir, prefix, "", 2, err)) {
+    free_parts(parts, count);
+    return -1;
+  }
+  /* The central directory always lives in "name.zip", the final volume. */
+  {
+    char name[2100];
+    char *last;
+
+    snprintf(name, sizeof(name), "%s.zip", stem);
+    last = vol_join(dir, name);
+    if(!last) {
+      free_parts(parts, count);
+      return -1;
+    }
+    if(!file_exists(last)) {
+      if(err && !*err) {
+        *err = err_printf("volume set is incomplete: the last volume '%s' that "
+                          "holds the archive index is missing", name);
+      }
+      free(last);
+      free_parts(parts, count);
+      return -1;
+    }
+    parts[count].num = (long)count + 1;
+    parts[count].path = last;
+    count++;
+  }
+  if(volume_take(vol, parts, count, ZIPX_VOL_MODE_DISK, selected)) {
+    free_parts(parts, count);
+    return -1;
+  }
+  return 1;
+}
+
+/* ------------------------------------------------------------------------- */
+/* detection: the final "name.zip" of a name.z01 ... name.zip set            */
+
+static int
+detect_zip_tail(const char *dir, const char *base, const char *selected,
+                zipx_volume_t *vol, char **err) {
+  vol_part_t parts[ZIPX_VOL_MAX_PARTS];
+  char stem[2048];
+  char prefix[2100];
+  size_t stem_len;
+  int count;
+
+  if(!ends_with_ci(base, ".zip")) {
+    return 0;
+  }
+  stem_len = strlen(base) - 4;
+  if(stem_len == 0 || stem_len >= sizeof(stem)) {
+    return 0;
+  }
+  memcpy(stem, base, stem_len);
+  stem[stem_len] = 0;
+
+  snprintf(prefix, sizeof(prefix), "%s.z", stem);
+  count = scan_parts(dir, prefix, "", parts, ZIPX_VOL_MAX_PARTS - 1, err);
+  if(count < 0) {
+    return -1;
+  }
+  if(count == 0) {
+    return 0;   /* an ordinary single volume archive */
+  }
+  if(check_contiguous(parts, count, dir, prefix, "", 2, err)) {
+    free_parts(parts, count);
+    return -1;
+  }
+  {
+    char *last = vol_join(dir, base);
+
+    if(!last) {
+      free_parts(parts, count);
+      return -1;
+    }
+    parts[count].num = (long)count + 1;
+    parts[count].path = last;
+    count++;
+  }
+  if(volume_take(vol, parts, count, ZIPX_VOL_MODE_DISK, selected)) {
+    free_parts(parts, count);
+    return -1;
+  }
+  return 1;
+}
+
+/* ------------------------------------------------------------------------- */
+/* detection: name.part1.zip ...                                             */
+
+static int
+detect_part_suffix(const char *dir, const char *base, const char *selected,
+                   zipx_volume_t *vol, char **err) {
+  vol_part_t parts[ZIPX_VOL_MAX_PARTS];
+  char stem[2048];
+  char prefix[2100];
+  char trimmed[2048];
+  const char *dot;
+  size_t len;
+  int count;
+
+  if(!ends_with_ci(base, ".zip")) {
+    return 0;
+  }
+  len = strlen(base) - 4;
+  if(len == 0 || len >= sizeof(trimmed)) {
+    return 0;
+  }
+  memcpy(trimmed, base, len);
+  trimmed[len] = 0;
+  dot = strrchr(trimmed, '.');
+  if(!dot || dot == trimmed || strncasecmp(dot, ".part", 5) != 0 ||
+     !isdigit((unsigned char)dot[5])) {
+    return 0;
+  }
+  {
+    size_t stem_len = (size_t)(dot - trimmed);
+
+    if(stem_len >= sizeof(stem)) {
+      return 0;
+    }
+    memcpy(stem, trimmed, stem_len);
+    stem[stem_len] = 0;
+  }
+  snprintf(prefix, sizeof(prefix), "%s.part", stem);
+  count = scan_parts(dir, prefix, ".zip", parts, ZIPX_VOL_MAX_PARTS, err);
+  if(count < 0) {
+    return -1;
+  }
+  if(count <= 1) {
+    free_parts(parts, count > 0 ? count : 0);
+    if(count == 1 && err && !*err) {
+      *err = err_printf("'%s' is a volume of a split archive but the other "
+                        "volumes ('%s.part1.zip', ...) are missing", base, stem);
+    }
+    return count == 1 ? -1 : 0;
+  }
+  if(check_contiguous(parts, count, dir, prefix, ".zip", 1, err)) {
+    free_parts(parts, count);
+    return -1;
+  }
+  if(volume_take(vol, parts, count, ZIPX_VOL_MODE_DISK, selected)) {
+    free_parts(parts, count);
+    return -1;
+  }
+  return 1;
+}
+
+/* ------------------------------------------------------------------------- */
+
+int
+zipx_volume_detect(const char *path, zipx_volume_t *out, char **err) {
+  char dir[4096];
+  const char *base;
+  int rc;
+
+  if(err) {
+    *err = NULL;
+  }
+  if(!path || !out) {
+    return -1;
+  }
+  volume_reset(out);
+  base = file_base(path);
+  file_dir(path, dir, sizeof(dir));
+
+  rc = detect_digit_suffix(dir, base, path, out, err);
+  if(rc != 0) {
+    return rc;
+  }
+  rc = detect_z_suffix(dir, base, path, out, err);
+  if(rc != 0) {
+    return rc;
+  }
+  rc = detect_zip_tail(dir, base, path, out, err);
+  if(rc != 0) {
+    return rc;
+  }
+  return detect_part_suffix(dir, base, path, out, err);
+}
+
+void
+zipx_volume_free(zipx_volume_t *vol) {
+  int i;
+
+  if(!vol) {
+    return;
+  }
+  if(vol->paths) {
+    for(i = 0; i < vol->count; i++) {
+      free(vol->paths[i]);
+    }
+    free(vol->paths);
+  }
+  memset(vol, 0, sizeof(*vol));
+  vol->index = -1;
+}
+
+int
+zipx_volume_is_first(const char *path) {
+  const char *base = file_base(path);
+  const char *dot = strrchr(base, '.');
+
+  if(!dot) {
+    return 0;
+  }
+  if(strcmp(dot, ".001") == 0) {
+    return 1;
+  }
+  if((dot[1] == 'z' || dot[1] == 'Z') && dot[2] == '0' && dot[3] == '1' &&
+     dot[4] == 0) {
+    return 1;
+  }
+  if(ends_with_ci(base, ".part1.zip")) {
+    return 1;
+  }
+  return 0;
+}
@@ -0,0 +1,58 @@
+/* zipx_volume -- group a multi-file archive volume set into an ordered list.
+   part of ps5-web-file-manager
+
+   Supports the naming conventions seen in the wild:
+
+     name.zip.001, name.zip.002, ...   byte split (7-Zip "split to volumes")
+     name.part1.zip, name.part2.zip    byte split (WinRAR zip volumes)
+     name.z01, name.z02, ..., name.zip zip split disks (Info-ZIP / PKZIP)
+
+   A caller can hand in any member of the set (the user usually clicks one file
+   in the browser) and gets back the full ordered list plus the split layout so
+   the engine can pick the matching stream behaviour. */
+
+#ifndef ZIPX_VOLUME_H
+#define ZIPX_VOLUME_H
+
+#include <stdint.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#define ZIPX_VOL_MAX_PARTS 512
+
+/* How the set is split. A byte split (`name.zip.001`, `name.7z.001`,
+   `name.part1.zip`) is the concatenation of its parts with absolute offsets;
+   zip split disks (`name.z01` + `name.zip`) store per-disk offsets instead.
+   The constants live here because they describe the *set*, and every consumer
+   of zipx_volume_t needs them. */
+#define ZIPX_VOL_MODE_CONCAT 0
+#define ZIPX_VOL_MODE_DISK   1
+
+typedef struct {
+  char **paths;   /* ordered part paths, owned by this struct */
+  int count;
+  int index;      /* position of the path that was handed in (-1 unknown) */
+  int mode;       /* ZIPX_VOL_MODE_CONCAT or ZIPX_VOL_MODE_DISK */
+  int is_set;     /* 1 when the path is part of a multi-file set */
+} zipx_volume_t;
+
+/* Inspects `path`: 1 when it belongs to a multi-file set (out is filled),
+   0 when it is an ordinary single file (out is cleared), -1 on a hard error
+   (*err, when non-NULL, receives a malloc'd message the caller must free;
+   it is also set for the 0 case when a sibling set looks broken, so callers
+   can surface "volumes are incomplete" instead of a generic open failure). */
+int zipx_volume_detect(const char *path, zipx_volume_t *out, char **err);
+
+void zipx_volume_free(zipx_volume_t *vol);
+
+/* True when `path` looks like the first volume of a set ("x.zip.001",
+   "x.z01", "x.part1.zip"), used by the UI to label the entry. */
+int zipx_volume_is_first(const char *path);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif
@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# Thin wrapper -- the actual driver is tests/bench_driver.py.
+#
+#   /usr/bin/bash tests/bench-sevenz.sh [--big] [--runs N]
+#
+# bash is deliberately not used for timing here. In this sandbox every `date`
+# costs ~350 ms, so a t0/t1 pair injects ~700 ms of overhead into a
+# measurement whose real value is ~600 ms, and `time`'s user/sys accounting
+# does not see into the native child at all (it reported 31 ms of CPU for a
+# run that demonstrably decodes 82 MiB). Python reads a monotonic clock
+# around a single spawn per sample instead.
+
+set -e
+ROOT="$(cd "$(dirname "$0")/.." && pwd -W 2>/dev/null || pwd)"
+exec python "$ROOT/tests/bench_driver.py" "$@"
@@ -0,0 +1,321 @@
+#!/usr/bin/env python3
+"""Performance baseline for the extraction engines.
+
+    python tests/bench_driver.py                    # 82 MiB fixture, fast
+    python tests/bench_driver.py --big              # 320 MiB fixture, accurate
+    python tests/bench_driver.py --format zip
+    python tests/bench_driver.py --format rar
+    python tests/bench_driver.py --runs 5
+
+Times our facades (src/zip_extract.c, src/rar_extract.c,
+src/sevenz_extract.c) against the external references that matter: the
+vendored SDK's own SzArEx path, and the official 7-Zip binary -- the latter
+being what upstream v1.8 gets by shelling out to a helper, so it doubles as
+the "how fast could we be" ceiling.
+
+The three formats are packed from one shared payload, so the rows are
+comparable across formats and not just within one engine.
+
+Why Python drives the measurement: in this sandbox a single `date` costs
+~350 ms, so the usual `t0=$(date)` / `t1=$(date)` pair adds ~700 ms of pure
+overhead to a measurement whose real value is ~600 ms, and `time`'s user/sys
+accounting does not see into the native child at all. Python spawns each
+child once and reads a monotonic clock around it, which leaves a small,
+constant "spawn tax" that is measured and subtracted (see the report).
+
+The candidate binaries print their own in-process timing, which excludes the
+spawn tax entirely -- that is the most trustworthy figure for our side.
+"""
+
+import argparse
+import glob
+import os
+import re
+import subprocess
+import sys
+import time
+
+REPO = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+BUILD = os.path.join(REPO, ".build", "bench")
+SZ_BUILD = os.path.join(REPO, ".build", "sevenz-test")
+HT_BUILD = os.path.join(REPO, ".build", "host-test")
+SEVENZ_BIN = os.path.join(REPO, ".build", "7zdl", "extra", "x64", "7za.exe")
+BENCH_BIN = os.path.join(BUILD, "bench_extract.exe")
+SDK_BIN = os.path.join(SZ_BUILD, "sevenz_e2e.exe")
+# RAR is write-only in WinRAR (7-Zip can read the format but not create it),
+# so a RAR fixture needs rar.exe. Missing means the rar fixture is skipped,
+# never that the run fails.
+RAR_BIN = next((p for p in (
+    os.environ.get("WFM_RAR"),
+    r"C:\Program Files\WinRAR\rar.exe",
+    r"C:\Program Files (x86)\WinRAR\rar.exe",
+    "/usr/bin/rar", "/usr/local/bin/rar") if p and os.path.exists(p)), None)
+
+# Object lists mirror what tests/run-sevenz-tests.sh and tests/run-tests.sh
+# build; those scripts must have run once before this can link.
+#
+# These lists are the one thing here that can rot: adding a source file to
+# either engine (sevenz_header.c for -mhe=on, mz_crypt_wfm.c plus the two
+# restored minizip-ng crypto streams for encrypted ZIP) silently leaves the
+# link with undefined symbols. If `g++` below fails on an unresolved symbol
+# that clearly lives in src/ or third_party/, check here first.
+VENDOR_7Z = ["7zAlloc", "7zArcIn", "7zBuf", "7zBuf2", "7zCrc", "7zCrcOpt",
+             "7zDec", "7zFile", "7zStream", "Aes", "AesOpt", "Alloc", "Bcj2",
+             "Bra", "Bra86", "BraIA64", "CpuArch", "Delta", "DllSecur",
+             "Lzma2Dec", "LzmaDec", "Lzma2DecMt", "MtDec", "Threads", "Ppmd7",
+             "Ppmd7Dec", "Sha256", "Sha256Opt", "SwapBytes"]
+ZLIB = ["adler32", "crc32", "deflate", "inffast", "inflate", "inftrees",
+        "trees", "zutil"]
+MINIZIP = ["mz_crypt", "mz_crypt_wfm", "mz_os", "mz_os_posix", "mz_strm",
+           "mz_strm_mem", "mz_strm_os_posix", "mz_strm_pkcrypt",
+           "mz_strm_wzaes", "mz_strm_zlib", "mz_zip"]
+EXTRA_LIBS = ["-lole32", "-loleaut32", "-luuid", "-ladvapi32", "-luser32",
+              "-lshell32"]
+
+
+def objs(base, names):
+    return [os.path.join(base, n + ".o") for n in names]
+
+
+def build_bench():
+    """Link tests/bench_extract.c against the prebuilt engine objects."""
+    if os.path.exists(BENCH_BIN):
+        return True
+
+    # The RAR engine is C++ (vendored UnRAR), so bench_extract.c is compiled
+    # with gcc and the link goes through g++.
+    unrar = sorted(glob.glob(os.path.join(HT_BUILD, "unrar7_*.o")))
+    needed = (objs(SZ_BUILD, ["sevenz_extract", "sevenz_chain",
+                              "sevenz_header", "sevenz_mt", "sevenz_volstream",
+                              "zipx_common", "zipx_volume"])
+              + objs(HT_BUILD, ["zip_extract", "zipx_volstream", "rar_extract"])
+              + objs(HT_BUILD, ZLIB) + objs(HT_BUILD, MINIZIP)
+              + objs(SZ_BUILD, VENDOR_7Z) + unrar)
+    missing = [p for p in needed if not os.path.exists(p)]
+    if missing:
+        print("missing engine objects, run these first:")
+        print("  /usr/bin/bash tests/run-sevenz-tests.sh")
+        print("  /usr/bin/bash tests/run-tests.sh --rebuild")
+        print("first missing: %s" % missing[0])
+        return False
+
+    includes = ["-I" + os.path.join(REPO, "third_party", "7z"),
+                "-I" + os.path.join(REPO, "third_party", "minizip-ng", "include"),
+                "-I" + os.path.join(REPO, "third_party", "zlib", "include"),
+                "-I" + os.path.join(REPO, "src"),
+                "-I" + os.path.join(REPO, "tests", "compat"),
+                "-include", os.path.join(REPO, "tests", "posix_compat.h")]
+    obj = os.path.join(BUILD, "bench_extract.o")
+    print("== compiling bench harness ==")
+    if subprocess.run(["gcc", "-O2", "-w"] + includes
+                      + ["-c", "-o", obj,
+                         os.path.join(REPO, "tests", "bench_extract.c")],
+                      cwd=REPO).returncode != 0:
+        return False
+
+    libs = list(EXTRA_LIBS)
+    if os.name == "nt":
+        # Windows unrar system.cpp references SetSuspendState (PowrProf).
+        libs.append("-lpowrprof")
+    if subprocess.run(["g++", "-O2", "-o", BENCH_BIN, obj] + needed + libs,
+                      cwd=REPO).returncode != 0:
+        return False
+    return True
+
+
+def make_fixture(big, fmt):
+    """Build the archive if absent: repeated source text plus a real PE file.
+
+    The blend matters -- compression throughput depends heavily on match
+    length, so a pure-text corpus would flatter every decoder equally and a
+    pure-random one would measure nothing but copying.
+    """
+    stem = "big4" if big else "big"
+    archive = os.path.join(BUILD, "%s.%s" % (stem, fmt))
+    if os.path.exists(archive):
+        return archive
+
+    os.makedirs(BUILD, exist_ok=True)
+    tp = os.path.join(REPO, "third_party")
+    parts = []
+    for sub in ("zlib/src", "7z", "minizip-ng/src"):
+        d = os.path.join(tp, sub)
+        if os.path.isdir(d):
+            for name in sorted(os.listdir(d)):
+                if name.endswith((".c", ".h")):
+                    parts.append(os.path.join(d, name))
+    if not parts:
+        print("no source available to build a fixture from")
+        return None
+
+    repeat = 240 if big else 60
+    src = os.path.join(BUILD, "payload_src.bin")
+    with open(src, "wb") as out:
+        for _ in range(repeat):
+            for path in parts:
+                with open(path, "rb") as fh:
+                    out.write(fh.read())
+
+    payload = src
+    pe = r"C:\Windows\System32\ntoskrnl.exe"
+    if os.path.exists(pe):
+        binary = os.path.join(BUILD, "payload_bin.bin")
+        with open(binary, "wb") as out:
+            for _ in range(30 if big else 3):
+                with open(pe, "rb") as fh:
+                    out.write(fh.read())
+        payload = os.path.join(BUILD, "payload_mix.bin")
+        with open(payload, "wb") as out:
+            for _ in range(4 if big else 1):
+                for path in (src, binary):
+                    with open(path, "rb") as fh:
+                        out.write(fh.read())
+
+    print("== creating fixture (first run only) ==")
+    if fmt == "rar":
+        # RAR needs WinRAR's rar.exe; 7-Zip cannot write the format.
+        rar = RAR_BIN
+        if not rar:
+            print("WinRAR (rar.exe) not found; cannot create a RAR fixture")
+            return None
+        add = ["a", "-m3", "-idq", "-ep1"]
+        subprocess.run([rar] + add + [archive, payload], cwd=REPO,
+                       stdout=subprocess.DEVNULL)
+    else:
+        if fmt == "7z":
+            add = ["a", "-t7z", "-m0=lzma2", "-mx=5", "-ms=on"]
+        else:
+            add = ["a", "-tzip", "-mx=5", "-mm=Deflate"]
+        subprocess.run([SEVENZ_BIN] + add + [archive, payload], cwd=REPO,
+                       stdout=subprocess.DEVNULL)
+    return archive
+
+
+def sample(argv, runs, workdir):
+    """Run argv `runs` times; return (best wall ms, best in-process ms|None).
+
+    Every run writes to its own path (`workdir0`, `workdir1`, ...) that does
+    not exist yet. Reusing one output directory is not an option: publishing
+    into a tree left by the previous run charges the rename step for the
+    collision, and that alone moved the same archive from 0.77 s to 1.28 s.
+    The placeholder `{out}` in argv marks where the run directory goes.
+
+    Nothing is deleted between runs either -- clearing these trees is a bulk
+    delete this host blocks -- so `.build/bench/W*` does accumulate and is
+    worth clearing by hand now and then.
+    """
+    best = None
+    internal = None
+    for i in range(runs):
+        # Forward slashes on purpose: the engines derive the destination's
+        # parent with a '/' scan (they only ever see POSIX paths on the PS5),
+        # so a Windows-style relative or absolute path is rejected outright.
+        run_dir = ("%s%d" % (workdir, i)).replace("\\", "/")
+        cmd = [arg.replace("{out}", run_dir) for arg in argv]
+        started = time.perf_counter()
+        proc = subprocess.run(cmd, stdout=subprocess.PIPE,
+                              stderr=subprocess.STDOUT, cwd=REPO, timeout=1800)
+        elapsed = (time.perf_counter() - started) * 1000.0
+        if proc.returncode != 0:
+            sys.stdout.write(proc.stdout.decode("utf-8", "replace")[:300])
+            return None, None
+        if best is None or elapsed < best:
+            best = elapsed
+        match = re.search(rb"wall\s*:\s*([0-9.]+)\s*s", proc.stdout)
+        if match:
+            value = float(match.group(1)) * 1000.0
+            if internal is None or value < internal:
+                internal = value
+    return best, internal
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--big", action="store_true",
+                    help="4x fixture (~320 MiB) for accurate ratios")
+    ap.add_argument("--runs", type=int, default=3)
+    ap.add_argument("--format", choices=["7z", "zip", "rar"], default="7z",
+                    help="which engine to benchmark (default 7z)")
+    args = ap.parse_args()
+
+    # For ZIP there is no useful SDK reference: the vendored SDK is 7z-only,
+    # so the comparison is just ours versus the official binary.
+    for path in (SEVENZ_BIN, SDK_BIN if args.format == "7z" else SEVENZ_BIN):
+        if not os.path.exists(path):
+            print("missing: %s" % path)
+            return 1
+    if not build_bench():
+        return 1
+
+    archive = make_fixture(args.big, args.format)
+    if not archive:
+        return 1
+    raw = os.path.getsize(archive)
+
+    print()
+    print("archive : %s (%.0f MiB packed), best of %d runs"
+          % (os.path.basename(archive), raw / 1048576.0, args.runs))
+    print()
+
+    rows = []
+    wall, inner = sample([BENCH_BIN, archive, "{out}"], args.runs,
+                         os.path.join(BUILD, "W7"))
+    if wall:
+        rows.append(("ours / " + args.format, wall, inner))
+
+    if args.format == "7z":
+        wall, _ = sample([SDK_BIN, archive, "{out}"], args.runs,
+                         os.path.join(BUILD, "W8"))
+        if wall:
+            rows.append(("sdk SzArEx", wall, None))
+        variants = (("7za 1 thread", ["-mmt=off"]),
+                    ("7za 8 threads", ["-mmt=8"]),
+                    ("7za all cores", []))
+    elif args.format == "rar":
+        # 7-Zip reads RAR, so it is a valid cross-check on the same archive.
+        variants = (("7za 1 thread", ["-mmt=off"]),
+                    ("7za all cores", []))
+    else:
+        variants = (("7za 1 thread", ["-mmt=off"]),)
+
+    for label, extra in variants:
+        wall, _ = sample([SEVENZ_BIN, "x", "-y", "-aoa"] + extra
+                         + ["-o{out}", archive], args.runs,
+                         os.path.join(BUILD, "W9"))
+        if wall:
+            rows.append((label, wall, None))
+
+    if args.format == "rar" and RAR_BIN:
+        # rar.exe treats the trailing separator as "this is the target
+        # directory"; without it the path is parsed as a file mask and the
+        # command reports that there is nothing to extract.
+        wall, _ = sample([RAR_BIN, "x", "-y", "-o+", archive, "{out}/"],
+                         args.runs, os.path.join(BUILD, "W10"))
+        if wall:
+            rows.append(("winrar x", wall, None))
+
+    print("  %-18s %10s %12s" % ("configuration", "external", "internal"))
+    for label, wall, inner in rows:
+        print("  %-18s %9.0f ms %12s"
+              % (label, wall,
+                 "%9.0f ms" % inner if inner else "         -"))
+
+    tax = None
+    ours = [r for r in rows if r[0].startswith("ours")]
+    if ours and ours[0][2]:
+        tax = ours[0][1] - ours[0][2]
+        ref = ours[0][2]
+        print()
+        print("  spawn tax (ours external - internal): %.0f ms" % tax)
+        print()
+        print("  %-18s %12s %9s" % ("configuration", "net", "vs ours"))
+        for label, wall, inner in rows:
+            net = inner if inner else max(wall - tax, 1.0)
+            print("  %-18s %9.0f ms %8.2fx" % (label, net, ref / net))
+        print()
+        print("  net = external minus spawn tax; >1x means faster than ours")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
@@ -0,0 +1,134 @@
+/* Wall-clock benchmark for the extraction paths, ZIP, RAR and 7z.
+ *
+ *   bench_extract <archive> <out-dir> [password]
+ *
+ * Reports how long the facade takes end to end -- decode, staging writes,
+ * publish -- which is exactly what a PS5 user waits for. Note there is no
+ * fsync in the extract path at all (see the comment in zip_extract.c's
+ * publish_entry): the pipeline is "sync nothing, rename everything". It is
+ * deliberately separate from the correctness drivers: those assert on bytes,
+ * this one only prints numbers, and it is not part of the test matrix.
+ *
+ * Keeping it in-tree matters because "is our engine fast?" is a question that
+ * will come up again, and the answer should be a command anyone can rerun
+ * rather than a number somebody remembers. The format is picked from the
+ * suffix so the same binary covers all three engines.
+ */
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <time.h>
+
+#include "sevenz_extract.h"
+
+#ifndef BENCH_NO_RAR
+#include "rar_extract.h"
+#endif
+
+static int
+has_suffix(const char *path, const char *suffix) {
+  size_t path_len;
+  size_t suffix_len;
+
+  if(!path || !suffix) return 0;
+  path_len = strlen(path);
+  suffix_len = strlen(suffix);
+  if(path_len < suffix_len) return 0;
+  for(size_t i = 0; i < suffix_len; i++) {
+    char a = path[path_len - suffix_len + i];
+    char b = suffix[i];
+    if(a >= 'A' && a <= 'Z') a = (char)(a - 'A' + 'a');
+    if(b >= 'A' && b <= 'Z') b = (char)(b - 'A' + 'a');
+    if(a != b) return 0;
+  }
+  return 1;
+}
+
+static double
+now_seconds(void) {
+  struct timespec ts;
+
+  if(timespec_get(&ts, TIME_UTC) != TIME_UTC) return 0.0;
+  return (double)ts.tv_sec + (double)ts.tv_nsec / 1000000000.0;
+}
+
+int
+main(int argc, char **argv) {
+  zipx_result_t result;
+  zipx_status_t status;
+  const char *archive;
+  const char *out_dir;
+  const char *password;
+  const char *format;
+  double started;
+  double elapsed;
+  double mebibytes;
+
+  if(argc < 3) {
+    fprintf(stderr, "usage: %s <archive> <out-dir> [password]\n", argv[0]);
+    return 2;
+  }
+  archive = argv[1];
+  out_dir = argv[2];
+  password = argc > 3 ? argv[3] : NULL;
+
+  if(has_suffix(archive, ".7z") || has_suffix(archive, ".7z.001") ||
+     has_suffix(archive, ".001")) {
+    format = "7z";
+  }
+#ifndef BENCH_SEVENZ_ONLY
+  else if(has_suffix(archive, ".zip") || has_suffix(archive, ".zip.001") ||
+            has_suffix(archive, ".z01")) {
+    format = "zip";
+  }
+#endif
+#ifndef BENCH_NO_RAR
+  else if(has_suffix(archive, ".rar") || has_suffix(archive, ".part1.rar") ||
+            has_suffix(archive, ".r00")) {
+    format = "rar";
+  }
+#endif
+  else {
+    fprintf(stderr, "unsupported benchmark format: %s\n", archive);
+    return 2;
+  }
+
+  memset(&result, 0, sizeof(result));
+  started = now_seconds();
+#ifndef BENCH_NO_RAR
+  if(!strcmp(format, "rar")) {
+    status = rar_extract(archive, out_dir, ZIPX_CONFLICT_OVERWRITE,
+                         zipx_default_limits(), NULL, NULL, NULL, NULL,
+                         &result);
+  } else
+#endif
+#ifndef BENCH_SEVENZ_ONLY
+  if(!strcmp(format, "zip")) {
+    status = zipx_extract(archive, out_dir, ZIPX_CONFLICT_OVERWRITE,
+                          zipx_default_limits(), NULL, NULL, NULL, NULL, &result);
+  } else
+#endif
+  {
+    status = sevenz_extract(archive, out_dir, ZIPX_CONFLICT_OVERWRITE,
+                            zipx_default_limits(), NULL, NULL, NULL,
+                            password, &result);
+  }
+  elapsed = now_seconds() - started;
+
+  mebibytes = (double)result.bytes_total / (1024.0 * 1024.0);
+
+  printf("format   : %s\n", format);
+  printf("status   : %s\n", zipx_status_string(status));
+  printf("entries  : %llu\n", (unsigned long long)result.entries_total);
+  printf("unpacked : %.1f MiB\n", mebibytes);
+  printf("wall     : %.3f s\n", elapsed);
+  if(elapsed > 0.0) {
+    printf("through  : %.1f MiB/s\n", mebibytes / elapsed);
+  }
+  if(status != ZIPX_OK) {
+    printf("detail   : %s\n", result.detail[0] ? result.detail : "(none)");
+    printf("message  : %s\n", result.message[0] ? result.message : "(none)");
+  }
+  return status == ZIPX_OK ? 0 : 1;
+}
@@ -0,0 +1,170 @@
+#!/usr/bin/env python3
+"""Cross-format extraction benchmark: same payload, three containers.
+
+    python tests/bench_formats.py                 # one 329 MiB file, 3 runs
+    python tests/bench_formats.py --source .build/bench/payload_bin.bin \\
+        --stem bin --runs 5                       # 39 MiB of machine code
+    python tests/bench_formats.py --source .build/bench/manyfiles_src --stem mf
+
+bench_driver.py answers "how do we compare with 7-Zip for one format"; this
+answers "which container should a user expect to unpack fastest", which is a
+different question and needs the three archives to hold the same bytes.
+
+Method notes that took a while to get right, so they are pinned here:
+
+  * Fresh output directory per run. Publishing on top of the previous run's
+    tree took the same 7z archive from 0.77 s to 1.28 s.
+  * Forward slashes in every path. The engines derive the destination parent
+    with a '/' scan, so "C:\\...\\W0" is rejected as an invalid destination.
+  * Best of N, because a single run varies widely on this host: extraction
+    creates hundreds of MiB that the on-access scanner inspects and the page
+    cache has to write back, and neither is under our control.
+  * Corpus matters as much as container. Deflate decodes faster than LZMA2 on
+    ordinary data, but on highly repetitive text LZMA2 finds long matches
+    where deflate only finds 32 KiB ones, and the order flips. Run the same
+    archive set on more than one source before concluding anything.
+
+Packed sizes are printed next to the times on purpose: a container that packs
+5x smaller also reads 5x less from the card, which is why the ranking on the
+PS5 -- where storage is the slow part -- can differ from the ranking here.
+"""
+
+import argparse
+import os
+import re
+import subprocess
+import sys
+import time
+
+REPO = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+BUILD = os.path.join(REPO, ".build", "bench")
+BENCH_BIN = os.path.join(BUILD, "bench_extract.exe")
+SEVENZ_BIN = os.path.join(REPO, ".build", "7zdl", "extra", "x64", "7za.exe")
+RAR_BIN = next((p for p in (
+    os.environ.get("WFM_RAR"),
+    r"C:\Program Files\WinRAR\rar.exe",
+    r"C:\Program Files (x86)\WinRAR\rar.exe",
+    "/usr/bin/rar", "/usr/local/bin/rar") if p and os.path.exists(p)), None)
+DEFAULT_SOURCE = os.path.join(BUILD, "payload4.bin")
+
+# Nominal level 5 in both packers, which is the GUI default of each:
+# 7-Zip -mx=5, WinRAR -m3 ("Normal"). They are not equivalent amounts of
+# work -- LZMA2 at level 5 is a far stronger compressor than deflate at 5 --
+# but they are what a user who never opens the advanced panel ends up with.
+FORMATS = ("zip", "7z", "rar")
+
+
+def pack(stem, payload):
+    """Create stem.{zip,7z,rar} from payload if they are not there yet."""
+    made = []
+    for fmt in FORMATS:
+        archive = os.path.join(BUILD, "%s.%s" % (stem, fmt))
+        if os.path.exists(archive):
+            continue
+        if fmt == "rar":
+            if not RAR_BIN:
+                print("skip %s: WinRAR (rar.exe) not found" % fmt)
+                continue
+            cmd = [RAR_BIN, "a", "-m3", "-idq"]
+            if os.path.isfile(payload):
+                cmd.append("-ep1")
+            cmd += [archive, payload]
+        else:
+            cmd = [SEVENZ_BIN, "a", "-t" + fmt] + (
+                ["-m0=lzma2", "-mx=5", "-ms=on"] if fmt == "7z"
+                else ["-mx=5", "-mm=Deflate"]) + [archive, payload]
+        print("== packing %s ==" % os.path.basename(archive))
+        if subprocess.run(cmd, cwd=REPO, stdout=subprocess.DEVNULL).returncode:
+            print("packing failed")
+            return None
+        made.append(archive)
+    return [os.path.join(BUILD, "%s.%s" % (stem, f)) for f in FORMATS]
+
+
+def time_archive(archive, runs):
+    """Best in-process wall time over `runs` fresh-directory extractions."""
+    tag = os.path.splitext(os.path.basename(archive))[0]
+    times = []
+    unpacked = entries = 0
+    for i in range(runs):
+        # A path that does not exist yet: the engines publish with a rename,
+        # and a rename into a tree that already has the file costs extra.
+        out = os.path.join(BUILD, "F-%s-%d" % (tag, i)).replace("\\", "/")
+        started = time.perf_counter()
+        proc = subprocess.run([BENCH_BIN, archive, out], cwd=REPO,
+                              stdout=subprocess.PIPE,
+                              stderr=subprocess.STDOUT, timeout=1800)
+        external = time.perf_counter() - started
+        if proc.returncode != 0:
+            sys.stdout.write(proc.stdout.decode("utf-8", "replace")[:400])
+            return None
+        text = proc.stdout.decode("utf-8", "replace")
+        match = re.search(r"wall\s*:\s*([0-9.]+)", text)
+        if not match:
+            return None
+        times.append(float(match.group(1)))
+        unpacked = float(re.search(r"unpacked\s*:\s*([0-9.]+)", text).group(1))
+        entries = int(re.search(r"entries\s*:\s*(\d+)", text).group(1))
+    return {"times": sorted(times), "unpacked": unpacked, "entries": entries}
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--runs", type=int, default=3)
+    ap.add_argument("--source", default=DEFAULT_SOURCE,
+                    help="file or directory to pack (default: %s)" % DEFAULT_SOURCE)
+    ap.add_argument("--stem", help="archive base name (default: source basename)")
+    args = ap.parse_args()
+
+    if not os.path.exists(BENCH_BIN):
+        print("missing %s -- run: python tests/bench_driver.py" % BENCH_BIN)
+        return 1
+
+    payload = args.source
+    if not os.path.isabs(payload):
+        payload = os.path.join(REPO, payload)
+    if not os.path.exists(payload):
+        print("missing payload: %s" % payload)
+        return 1
+    stem = args.stem or os.path.splitext(os.path.basename(payload))[0]
+
+    archives = pack(stem, payload)
+    if not archives:
+        return 1
+
+    rows = []
+    for archive in archives:
+        if not os.path.exists(archive):
+            continue
+        result = time_archive(archive, args.runs)
+        if result is None:
+            print("failed: %s" % archive)
+            continue
+        rows.append((os.path.splitext(archive)[1][1:], archive, result))
+
+    if not rows:
+        return 1
+
+    print()
+    print("best of %d runs, fresh output directory each time" % args.runs)
+    print("payload: %d entries, %.1f MiB unpacked"
+          % (rows[0][2]["entries"], rows[0][2]["unpacked"]))
+    print()
+    print("  %-5s %10s %9s %12s %12s" %
+          ("fmt", "packed", "best", "median", "throughput"))
+    best = min(r[2]["times"][0] for r in rows)
+    for fmt, archive, result in sorted(rows, key=lambda r: r[2]["times"][0]):
+        packed = os.path.getsize(archive) / 1048576.0
+        times = result["times"]
+        median = times[len(times) // 2]
+        rate = result["unpacked"] / times[0]
+        print("  %-5s %8.1f M %7.0f ms %9.0f ms %8.0f MiB/s"
+              % (fmt, packed, times[0] * 1000.0, median * 1000.0, rate))
+    print()
+    for fmt, archive, result in sorted(rows, key=lambda r: r[2]["times"][0]):
+        print("  %-5s vs fastest: %.2fx" % (fmt, result["times"][0] / best))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
@@ -0,0 +1,161 @@
+/* Prints every extraction progress report, with a monotonic timestamp.
+ *
+ *   bench_progress <archive> <out-dir> [--mode print|empty|none]
+ *
+ * bench_extract answers "how long"; this answers "did the UI move while it
+ * took that long". A report that sits at entries=0/N for minutes reads to the
+ * user as a hang even though bytes are still flowing, so being able to see the
+ * phase/entries/bytes sequence is what turns "the progress bar freezes" into a
+ * named phase. Format is picked from the suffix, same as bench_extract.
+ *
+ * --mode exists to answer a second question: "does reporting itself cost
+ * time?". The engine's report() helper runs on the hot path -- unrar calls it
+ * once per decompressed chunk -- and it reads the clock before it decides
+ * whether to throttle, so the cost is paid even when no report goes out.
+ *   print  a callback that formats and prints every report (diagnostic)
+ *   empty  a callback that returns immediately (engine cost, no consumer)
+ *   none   no callback at all (the engine skips report() entirely)
+ * Comparing wall time across the three separates "our bookkeeping" from
+ * "the file I/O we cannot avoid".
+ */
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <time.h>
+
+#include "zip_extract.h"
+#include "rar_extract.h"
+#include "sevenz_extract.h"
+
+static double g_t0;
+
+static int
+has_suffix(const char *path, const char *suffix) {
+  size_t path_len, suffix_len, i;
+
+  if(!path || !suffix) return 0;
+  path_len = strlen(path);
+  suffix_len = strlen(suffix);
+  if(path_len < suffix_len) return 0;
+  for(i = 0; i < suffix_len; i++) {
+    char a = path[path_len - suffix_len + i];
+    char b = suffix[i];
+
+    if(a >= 'A' && a <= 'Z') a = (char)(a - 'A' + 'a');
+    if(b >= 'A' && b <= 'Z') b = (char)(b - 'A' + 'a');
+    if(a != b) return 0;
+  }
+  return 1;
+}
+
+static double
+now_seconds(void) {
+  struct timespec ts;
+
+  if(timespec_get(&ts, TIME_UTC) != TIME_UTC) return 0.0;
+  return (double)ts.tv_sec + (double)ts.tv_nsec / 1000000000.0;
+}
+
+static const char *
+phase_name(int phase) {
+  switch(phase) {
+  case ZIPX_PHASE_SCAN: return "scan";
+  case ZIPX_PHASE_EXTRACT: return "extract";
+  case ZIPX_PHASE_PUBLISH: return "publish";
+  case ZIPX_PHASE_CLEANUP: return "cleanup";
+  default: return "?";
+  }
+}
+
+/* Costs exactly what the engine's report() costs, without a consumer. */
+static void
+on_progress_empty(void *userdata, const zipx_progress_t *p) {
+  (void)userdata;
+  (void)p;
+}
+
+static void
+on_progress(void *userdata, const zipx_progress_t *p) {
+  (void)userdata;
+  printf("%8.3f  %-7s entries=%llu/%llu  bytes=%llu/%llu  %s\n",
+         now_seconds() - g_t0, phase_name(p->phase),
+         (unsigned long long)p->entries_done,
+         (unsigned long long)p->entries_total,
+         (unsigned long long)p->bytes_done,
+         (unsigned long long)p->bytes_total,
+         p->current ? p->current : "");
+  fflush(stdout);
+}
+
+int
+main(int argc, char **argv) {
+  zipx_result_t result;
+  zipx_status_t status;
+  const char *archive;
+  const char *out_dir;
+  const char *format;
+  const char *mode = "print";
+  zipx_progress_fn on_report = on_progress;
+  double elapsed;
+  int i;
+
+  if(argc < 3) {
+    fprintf(stderr, "usage: %s <archive> <out-dir> [--mode print|empty|none]\n",
+            argv[0]);
+    return 2;
+  }
+  archive = argv[1];
+  out_dir = argv[2];
+
+  for(i = 3; i < argc; i++) {
+    if(!strcmp(argv[i], "--mode") && i + 1 < argc) {
+      mode = argv[++i];
+    } else {
+      fprintf(stderr, "unknown argument: %s\n", argv[i]);
+      return 2;
+    }
+  }
+  if(!strcmp(mode, "empty")) {
+    on_report = on_progress_empty;
+  } else if(!strcmp(mode, "none")) {
+    on_report = NULL;
+  } else if(strcmp(mode, "print")) {
+    fprintf(stderr, "unknown --mode: %s\n", mode);
+    return 2;
+  }
+
+  if(has_suffix(archive, ".rar") || has_suffix(archive, ".part1.rar") ||
+     has_suffix(archive, ".r00")) {
+    format = "rar";
+  } else if(has_suffix(archive, ".zip") || has_suffix(archive, ".z01") ||
+            has_suffix(archive, ".zip.001")) {
+    format = "zip";
+  } else {
+    format = "7z";
+  }
+
+  memset(&result, 0, sizeof(result));
+  g_t0 = now_seconds();
+
+  if(!strcmp(format, "rar")) {
+    status = rar_extract(archive, out_dir, ZIPX_CONFLICT_OVERWRITE,
+                         zipx_default_limits(), NULL, on_report, NULL, NULL,
+                         &result);
+  } else if(!strcmp(format, "zip")) {
+    status = zipx_extract(archive, out_dir, ZIPX_CONFLICT_OVERWRITE,
+                          zipx_default_limits(), NULL, on_report, NULL, NULL,
+                          &result);
+  } else {
+    status = sevenz_extract(archive, out_dir, ZIPX_CONFLICT_OVERWRITE,
+                            zipx_default_limits(), NULL, on_report, NULL,
+                            NULL, &result);
+  }
+
+  elapsed = now_seconds() - g_t0;
+  printf("---- done: format=%s mode=%s status=%s entries=%llu bytes=%llu wall=%.3fs\n",
+         format, mode, zipx_status_string(status),
+         (unsigned long long)result.entries_total,
+         (unsigned long long)result.bytes_total, elapsed);
+  return status == ZIPX_OK ? 0 : 1;
+}
@@ -0,0 +1,40 @@
+/* Standalone big-file e2e: extract one large zip64 archive on the host and
+ * report the engine result. Verification (size + sha256/cmp) is done by the
+ * caller with shell tools.
+ *
+ *   cc -O2 -Isrc -Ithird_party/minizip-ng/include \
+ *      -include tests/posix_compat.h \
+ *      -o bigfile_e2e bigfile_e2e.c zip_extract.o <minizip+zlib objs>
+ *
+ *   ./bigfile_e2e <archive.zip> <out-dir>
+ */
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include "zip_extract.h"
+
+int
+main(int argc, char **argv) {
+  zipx_result_t res;
+  zipx_status_t st;
+
+  if(argc != 3) {
+    fprintf(stderr, "usage: %s <archive.zip> <out-dir>\n", argv[0]);
+    return 2;
+  }
+  st = zipx_extract(argv[1], argv[2], ZIPX_CONFLICT_FAIL,
+                    zipx_limits_profile(ZIPX_LIMITS_LARGE),
+                    NULL, NULL, NULL, NULL, &res);
+  printf("status=%d (%s)\n", (int)st, zipx_status_string(st));
+  printf("sys_errno=%d entries=%llu/%llu files=%llu dirs=%llu\n",
+         res.sys_errno, (unsigned long long)res.entries_done,
+         (unsigned long long)res.entries_total,
+         (unsigned long long)res.files_created,
+         (unsigned long long)res.dirs_created);
+  printf("bytes_total=%llu detail=%s\n",
+         (unsigned long long)res.bytes_total, res.detail);
+  if(res.message[0]) {
+    printf("message=%s\n", res.message);
+  }
+  return st == ZIPX_OK ? 0 : 1;
+}
@@ -18,16 +18,26 @@ static int
 statvfs(const char *path, struct statvfs *buf) {
  ULARGE_INTEGER total;
  ULARGE_INTEGER free_bytes;
+  char full[MAX_PATH];
  char root[8];

-  snprintf(root, sizeof(root), "%.3s", path);
+  /* Resolve to an absolute path first: the drive-letter extraction below
+     only works for "X:\..." style paths, and callers may pass relative
+     paths (e.g. the standalone bigfile_e2e driver). */
+  if(!GetFullPathNameA(path, (DWORD)sizeof(full), full, NULL)) {
+    return -1;
+  }
+  snprintf(root, sizeof(root), "%.3s", full);
  if(!GetDiskFreeSpaceExA(root, &free_bytes, &total, NULL)) {
    return -1;
  }
  memset(buf, 0, sizeof(*buf));
-  buf->f_bsize = 1;
-  buf->f_frsize = 1;
-  buf->f_bavail = free_bytes.QuadPart;
+  /* `unsigned long` is 32-bit on Windows: store free space scaled by 4096
+     so archives up to 16 TiB don't overflow (real 64-bit hosts are LP64
+     and unaffected; PS5 SDK is LP64 too). */
+  buf->f_bsize = 4096;
+  buf->f_frsize = 4096;
+  buf->f_bavail = free_bytes.QuadPart / 4096;
  return 0;
 }

@@ -0,0 +1,82 @@
+@echo off
+REM Generate real RAR fixtures for the v1.9 host test suite.
+REM Requires WinRAR command-line Rar.exe (ships with normal WinRAR install).
+REM Outputs into tests\fixtures-real\ - kept OUT of tests\fixtures\ because
+REM tests\make_fixtures.py wipes that directory on every test run.
+REM Rerun any time fixture needs change. NOTE: keep this file pure ASCII.
+setlocal EnableDelayedExpansion
+
+set RAREXE=
+if exist "%ProgramFiles%\WinRAR\Rar.exe" set RAREXE=%ProgramFiles%\WinRAR\Rar.exe
+if exist "%ProgramFiles(x86)%\WinRAR\Rar.exe" set RAREXE=%ProgramFiles(x86)%\WinRAR\Rar.exe
+if exist "%~dp0Rar.exe" set RAREXE=%~dp0Rar.exe
+if "%RAREXE%"=="" (
+  echo [ERROR] Rar.exe not found. Install WinRAR or drop Rar.exe next to this script.
+  exit /b 1
+)
+echo Using: %RAREXE%
+"%RAREXE%" 2>nul | findstr /c:"RAR " >nul || (echo [ERROR] %RAREXE% does not look like WinRAR & exit /b 1)
+
+set FIX=%~dp0fixtures-real
+if exist "%FIX%" rmdir /s /q "%FIX%"
+mkdir "%FIX%"
+set STAGE=%~dp0fixture-stage
+if exist "%STAGE%" rmdir /s /q "%STAGE%"
+mkdir "%STAGE%\dir" 2>nul
+
+echo ############### > "%STAGE%\root.txt"
+echo rar v1.9 fixture root content >> "%STAGE%\root.txt"
+echo nested payload line one > "%STAGE%\dir\nested.txt"
+echo nested payload line two >> "%STAGE%\dir\nested.txt"
+echo file-b 0102030405060708090a > "%STAGE%\b.bin"
+
+REM Work from inside the stage dir with RELATIVE names so the archive keeps
+REM the dir\ structure (no -ep1 stripping).
+pushd "%STAGE%"
+
+echo.
+echo [1/4] RAR5 v6 single volume - basic-v6.rar
+"%RAREXE%" a -m2 -ma5 -idq "%FIX%\basic-v6.rar" root.txt dir\nested.txt b.bin
+if errorlevel 1 echo   [FAIL] & goto :badpop
+
+echo [2/4] RAR5 v6 multi-volume - vol.part1.rar + vol.part2.rar + ...
+REM Create a 512 KB incompressible payload so -v200k actually splits it.
+fsutil file createnew big.bin 524288 >nul 2>nul
+if not exist big.bin (
+  echo   [WARN] fsutil unavailable - cannot force multi-volume; skipping
+  goto :aftervol
+)
+REM rar a updates an existing archive instead of re-splitting it, so any
+REM stale volume files must be removed first. Target name is plain
+REM "vol.rar": RAR5 numbering then yields vol.part1/2/3.rar (naming the
+REM target vol.part1.rar would double up to vol.part1.partN.rar).
+del "%FIX%\vol*.rar" 2>nul
+"%RAREXE%" a -m0 -ma5 -v200k -idq "%FIX%\vol.rar" big.bin root.txt
+if errorlevel 1 echo   [FAIL] & goto :badpop
+echo   wrote: & dir /b "%FIX%\vol.part*.rar" 2>nul
+:aftervol
+
+echo [3/4] RAR5 v6 encrypted (password: secret123) - enc-v6.rar
+"%RAREXE%" a -m2 -ma5 -psecret123 -idq "%FIX%\enc-v6.rar" root.txt dir\nested.txt
+if errorlevel 1 echo   [FAIL] & goto :badpop
+
+echo [4/4] RAR4 legacy (optional - some WinRAR builds dropped RAR4 writing)
+"%RAREXE%" a -m2 -ma4 -idq "%FIX%\basic-rar4.rar" root.txt dir\nested.txt
+if errorlevel 1 (
+  echo   [WARN] RAR4 creation not supported by this Rar.exe - skipping basic-rar4.rar
+) else (
+  echo   basic-rar4.rar written
+)
+
+popd
+rmdir /s /q "%STAGE%" 2>nul
+echo.
+echo OK. Fixtures written to %FIX%:
+dir /b "%FIX%\*.rar" 2>nul
+exit /b 0
+
+:badpop
+popd
+:bad
+echo [ERROR] WinRAR command failed. Is this WinRAR 5+ with command line support?
+exit /b 1
@@ -0,0 +1,68 @@
+@echo off
+REM Generate real encrypted ZIP fixtures for the host test suite.
+REM Requires a 7-Zip compatible command line tool: 7-Zip, or the NanaZip
+REM console alias that ships with the Store package (both accept the same
+REM switches used here).
+REM Outputs into tests\fixtures-real\ - kept OUT of tests\fixtures\ because
+REM tests\make_fixtures.py wipes that directory on every test run. Only the
+REM *.zip files are rewritten, so the RAR fixtures produced by
+REM make-rar-fixtures.bat survive.
+REM Rerun any time fixture needs change. NOTE: keep this file pure ASCII.
+setlocal EnableDelayedExpansion
+
+set SZEXE=
+if exist "%ProgramFiles%\7-Zip\7z.exe" set SZEXE=%ProgramFiles%\7-Zip\7z.exe
+if exist "%ProgramFiles(x86)%\7-Zip\7z.exe" set SZEXE=%ProgramFiles(x86)%\7-Zip\7z.exe
+if exist "%~dp07z.exe" set SZEXE=%~dp07z.exe
+if "%SZEXE%"=="" (
+  for /f "delims=" %%I in ('where 7z 2^>nul') do if "!SZEXE!"=="" set SZEXE=%%I
+)
+if "%SZEXE%"=="" (
+  echo [ERROR] No 7z.exe found. Install 7-Zip or NanaZip, or drop 7z.exe next to this script.
+  exit /b 1
+)
+echo Using: %SZEXE%
+
+set FIX=%~dp0fixtures-real
+if not exist "%FIX%" mkdir "%FIX%"
+del "%FIX%\enc-*.zip" 2>nul
+
+set STAGE=%~dp0fixture-stage-zip
+if exist "%STAGE%" rmdir /s /q "%STAGE%"
+mkdir "%STAGE%\dir" 2>nul
+
+REM Same payload shape as the RAR fixtures so both suites assert the same
+REM file list and the same bytes.
+echo ############### > "%STAGE%\root.txt"
+echo zip v1.9 fixture root content >> "%STAGE%\root.txt"
+echo nested payload line one > "%STAGE%\dir\nested.txt"
+echo nested payload line two >> "%STAGE%\dir\nested.txt"
+
+REM Work from inside the stage dir with RELATIVE names so the archive keeps
+REM the dir\ structure (no -spf full paths).
+pushd "%STAGE%"
+
+echo.
+echo [1/3] traditional PKWARE / ZipCrypto (password: secret123) - enc-zipcrypto.zip
+"%SZEXE%" a -tzip -psecret123 -mem=ZipCrypto -y -bso0 -bsp0 "%FIX%\enc-zipcrypto.zip" root.txt dir\nested.txt
+if errorlevel 1 echo   [FAIL] & goto :badpop
+
+echo [2/3] WinZip AES-256 (password: secret123) - enc-aes256.zip
+"%SZEXE%" a -tzip -psecret123 -mem=AES256 -y -bso0 -bsp0 "%FIX%\enc-aes256.zip" root.txt dir\nested.txt
+if errorlevel 1 echo   [FAIL] & goto :badpop
+
+echo [3/3] WinZip AES-256 with stored (uncompressed) entries - enc-aes256-store.zip
+"%SZEXE%" a -tzip -psecret123 -mem=AES256 -mx0 -y -bso0 -bsp0 "%FIX%\enc-aes256-store.zip" root.txt dir\nested.txt
+if errorlevel 1 echo   [FAIL] & goto :badpop
+
+popd
+rmdir /s /q "%STAGE%" 2>nul
+echo.
+echo OK. Fixtures written to %FIX%:
+dir /b "%FIX%\enc-*.zip" 2>nul
+exit /b 0
+
+:badpop
+popd
+echo [ERROR] 7z command failed. Is this 7-Zip 21+ (or NanaZip) with ZIP encryption support?
+exit /b 1
@@ -282,13 +282,84 @@ def rar_fixtures():
        shutil.rmtree(staging_dir, ignore_errors=True)


+def bigdict():
+    """dict-8g.rar -- a RAR5 block whose header asks for an 8 GiB dictionary.
+
+    This one cannot be produced by any compressor, so it is synthesised here:
+
+      * arcread.cpp:871 reads a RAR 5.0 dictionary as
+        `0x20000 << ((CompInfo>>10) & 0x0f)` -- FOUR bits, so the format's own
+        ceiling is 128 KiB << 15 = exactly 4 GiB, the same as our default
+        Cmd->WinSizeLimit (options.cpp:13).  No `-ma5` archive can ever ask for
+        more, which is why -m0 store archives never reach CheckWinLimit().
+      * Only a RAR7 header (UnpVer==1, five bits, up to UNPACK_MAX_DICT = 64 GiB)
+        can -- and Rar.exe 7.23 refuses to create one (`-ma4`, `-ma6`, `-ma7` all
+        exit 7; only `-ma5` works).
+
+    So we emit a minimal, valid RAR5 archive by hand: signature, main header,
+    one store-method file header (FHFL_CRC32 set), the raw payload, end block.
+    CompInfo says UnpVer=1 with 16 dictionary bits (= 8 GiB) plus
+    FCI_RAR5_COMPAT, and arcread.cpp:878 then forces the algorithm back to
+    VER_PACK5 -- the payload really is stored, so nothing has to decode it.
+
+    Method 0 also means Unpack::Init() is never reached, i.e. the archive
+    exercises exactly the gate under test (CheckWinLimit -> uiDictLimit ->
+    UCM_LARGEDICT) and never allocates anything multi-gigabyte.
+
+    Sanity check with rarlab's own tools before trusting a change here:
+        UnRAR.exe lt dict-8g.rar          -> "-md=8g"
+        UnRAR.exe t -mdx12g dict-8g.rar   -> all OK
+    Without -mdx UnRAR refuses it exactly as we do ("8 GB dictionary exceeds the
+    4 GB limit and needs more than 8 GB of memory").
+    """
+    name = b"hello.txt"
+    data = b"".join(b"line %04d dictionary probe payload\n" % i for i in range(200))
+    comp_info = 1 | (16 << 10) | 0x00100000  # UnpVer=1, method=0, 8 GiB, RAR5 compat
+
+    def vint(v):
+        out = bytearray()
+        while True:
+            c = v & 0x7F
+            v >>= 7
+            out.append(c | 0x80 if v else c)
+            if not v:
+                return bytes(out)
+
+    def block(htype, flags, payload, data_size=None):
+        # The HFL_DATA size lives in the block header prologue, right after the
+        # flags -- it is not part of the per-type payload (arcread.cpp:710).
+        hd = vint(htype) + vint(flags)
+        if data_size is not None:
+            hd += vint(data_size)
+        hd += payload
+        size = vint(len(hd))
+        # rawread.cpp:185 GetCRC50() == zlib.crc32 over (size field + header data)
+        crc = zlib.crc32(size + hd) & 0xFFFFFFFF
+        return struct.pack("<I", crc) + size + hd
+
+    main_hdr = block(1, 0x04, vint(0))                      # HEAD_MAIN, ArcFlags=0
+    file_hdr = block(2, 0x02,                               # HEAD_FILE, HFL_DATA
+                     vint(0x0004) +                         # FileFlags: FHFL_CRC32
+                     vint(len(data)) +                      # UnpSize
+                     vint(0) +                              # FileAttr
+                     struct.pack("<I", zlib.crc32(data) & 0xFFFFFFFF) +
+                     vint(comp_info) +
+                     vint(0) +                              # HostOS: Windows
+                     vint(len(name)) + name,
+                     data_size=len(data))
+    end_hdr = block(5, 0x00, vint(0))                       # HEAD_ENDARC
+
+    with open(path("dict-8g.rar"), "wb") as f:
+        f.write(b"Rar!\x1a\x07\x01\x00" + main_hdr + file_hdr + data + end_hdr)
+
+
 def main():
    fresh()
    for fn in (basic, stored, unicode_names, zip64, traversal,
               traversal_backslash, absolute, drive_letter, duplicate,
               file_dir_clash, symlink_entry, fifo_entry, encrypted, bad_crc,
               truncated, not_a_zip, bomb, medium_bomb, many_files,
-               conflict_source, rar_fixtures):
+               conflict_source, rar_fixtures, bigdict):
        fn()
    print("fixtures written to %s" % OUT)
    return 0
@@ -0,0 +1,258 @@
+#!/usr/bin/env python3
+"""Generate real .7z fixtures for the host test suite.
+
+The fixtures are produced by an actual 7-Zip binary so that the archives the
+engine has to read are genuine, not hand-rolled.  The tool is looked up in this
+order:
+
+  1. ``--tool <path>``
+  2. ``$SEVENZ_TOOL``
+  3. the full ``7za.exe`` from the "7-Zip Extra" package under ``.build/7zdl/``
+  4. the reduced ``7zr.exe`` under ``.build/7zdl/``
+  5. ``7z`` / ``7zr`` / ``7za`` on PATH
+
+Both binaries come from https://github.com/ip7z/7zip/releases (7-Zip is public
+domain).  The reduced ``7zr.exe`` has **no PPMd encoder**, so that fixture is
+skipped (with a warning) unless a full build is available.
+
+Output goes to ``tests/fixtures-7z/``.  Only files this script owns are removed
+on a re-run (identified by an ``OWN_`` prefix list), never the whole directory.
+
+    python tests/make_sevenz_fixtures.py [--big]
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import random
+import shutil
+import subprocess
+import sys
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+ROOT = os.path.dirname(HERE)
+OUT = os.path.join(HERE, "fixtures-7z")
+SRC = os.path.join(OUT, "_src")
+
+# Everything this script may delete on a re-run.
+OWN_PREFIXES = (
+    "store", "lzma", "lzma2", "ppmd", "bcj", "delta", "aes", "vol", "utf8",
+    "big", "empty", "_src",
+)
+
+PASSWORD = "Secret123"
+
+
+# --------------------------------------------------------------------------
+# tool discovery / process helpers
+# --------------------------------------------------------------------------
+
+def find_tool(explicit: str | None) -> str:
+    if explicit:
+        if os.path.exists(explicit):
+            return explicit
+        raise SystemExit(f"7z tool not found: {explicit}")
+
+    env = os.environ.get("SEVENZ_TOOL")
+    if env and os.path.exists(env):
+        return env
+
+    # Prefer the full 7za.exe (has PPMd); fall back to the reduced 7zr.exe.
+    for rel in ("7zdl/extra/x64/7za.exe", "7zdl/extra/7za.exe", "7zdl/7zr.exe"):
+        local = os.path.join(ROOT, ".build", rel.replace("/", os.sep))
+        if os.path.exists(local):
+            return local
+
+    for name in ("7z", "7zr", "7za"):
+        found = shutil.which(name)
+        if found:
+            return found
+
+    raise SystemExit(
+        "no 7z tool found; pass --tool, set SEVENZ_TOOL, or drop 7zr.exe into "
+        ".build/7zdl/"
+    )
+
+
+def run(tool: str, args: list[str], optional: bool = False) -> bool:
+    """Run the 7z tool.  Returns True on success; raises unless ``optional``."""
+    proc = subprocess.run(
+        [tool] + args, cwd=ROOT, stdout=subprocess.PIPE, stderr=subprocess.STDOUT
+    )
+    if proc.returncode == 0:
+        return True
+    out = proc.stdout.decode("utf-8", "replace")
+    # 7-Zip writes its diagnostics in the OEM code page; try the common ones.
+    for enc in ("gbk", "cp936", "utf-8"):
+        try:
+            out = proc.stdout.decode(enc)
+            break
+        except UnicodeDecodeError:
+            continue
+    if optional:
+        print(f"  !! skipped: {' '.join(args[:4])}\n     {out.strip()[-200:]}")
+        return False
+    raise SystemExit(
+        f"7z failed ({proc.returncode}): {tool} {' '.join(args)}\n{out}"
+    )
+
+
+def win(path: str) -> str:
+    """7zr.exe is a native Windows binary: hand it a Windows path."""
+    return path.replace("/", "\\")
+
+
+# --------------------------------------------------------------------------
+# source tree
+# --------------------------------------------------------------------------
+
+def x86ish(size: int) -> bytes:
+    """Bytes that look like x86 code so BCJ/BCJ2 filters are actually useful."""
+    out = bytearray()
+    rnd = random.Random(1234)
+    while len(out) < size:
+        op = rnd.choice((0xE8, 0xE9, 0xE8, 0xE9, 0x0F, 0x8B, 0xC3, 0x90))
+        out.append(op)
+        if op in (0xE8, 0xE9):
+            out += rnd.randrange(0, 1 << 24).to_bytes(4, "little")
+        elif op == 0x0F:
+            out.append(0x8B)
+        else:
+            out += bytes(rnd.randrange(256) for _ in range(rnd.randrange(1, 6)))
+    return bytes(out[:size])
+
+
+def build_source(sizes: dict[str, int]) -> None:
+    os.makedirs(os.path.join(SRC, "sub"), exist_ok=True)
+    rnd = random.Random(7)
+
+    with open(os.path.join(SRC, "readme.txt"), "wb") as fh:
+        fh.write(b"sevenz fixture\n" * 20)
+
+    with open(os.path.join(SRC, "binary.bin"), "wb") as fh:
+        fh.write(bytes(rnd.randrange(256) for _ in range(sizes["binary"])))
+
+    # Highly compressible: exercises the LZMA/LZMA2/PPMd long-range paths.
+    with open(os.path.join(SRC, "zeros.bin"), "wb") as fh:
+        fh.write(b"\0" * sizes["zeros"])
+
+    with open(os.path.join(SRC, "sub", "nested.txt"), "wb") as fh:
+        fh.write(b"nested entry\n" * 100)
+
+    with open(os.path.join(SRC, "sub", "code.bin"), "wb") as fh:
+        fh.write(x86ish(sizes["code"]))
+
+    # Non-ASCII names must survive the UTF-16 name table round trip.
+    with open(os.path.join(SRC, "sub", "\u4e2d\u6587-\u30c6\u30b9\u30c8.txt"), "wb") as fh:
+        fh.write("unicode name\n".encode("utf-8") * 30)
+
+
+def write_big_file(path: str, size: int) -> None:
+    """A large, semi-compressible file: forces multi-chunk streaming decode."""
+    rnd = random.Random(99)
+    block = bytes(rnd.randrange(256) for _ in range(64 * 1024))
+    with open(path, "wb") as fh:
+        written = 0
+        while written < size:
+            n = min(len(block), size - written)
+            fh.write(block[:n])
+            written += n
+
+
+# --------------------------------------------------------------------------
+# archives
+# --------------------------------------------------------------------------
+
+# name -> (extra 7z arguments, takes password, required)
+VARIANTS: list[tuple[str, list[str], bool, bool]] = [
+    ("store",   ["-mx0"], False, True),
+    ("lzma2",   ["-m0=lzma2", "-mx5"], False, True),
+    ("lzma",    ["-m0=lzma"], False, True),
+    # The reduced 7zr.exe has no PPMd encoder, so this one is best-effort.
+    ("ppmd",    ["-m0=ppmd"], False, False),
+    ("bcj",     ["-m0=bcj", "-m1=lzma2"], False, True),
+    ("delta",   ["-m0=delta:4", "-m1=lzma2"], False, True),
+    ("bcj2",    ["-m0=bcj2", "-m1=lzma2", "-m2=lzma2", "-m3=lzma2", "-m4=lzma2"], False, True),
+    ("aes",     ["-m0=lzma2", "-mx5"], True, True),
+    ("utf8",    ["-m0=lzma2", "-mx5"], False, True),
+    # Not solid: one folder per file.  That is what exercises the multi-folder
+    # walk and the per-folder slice of the packed-stream table.
+    ("solidoff", ["-m0=lzma2", "-mx5", "-ms=off"], False, True),
+    ("bcj2off", ["-m0=bcj2", "-m1=lzma2", "-m2=lzma2", "-m3=lzma2",
+                 "-m4=lzma2", "-ms=off"], False, True),
+]
+
+
+def build_archives(tool: str, big: bool) -> None:
+    for name, extra, secret, required in VARIANTS:
+        arch = os.path.join(OUT, f"{name}.7z")
+        if os.path.exists(arch):
+            os.remove(arch)
+        args = ["a", "-t7z", win(arch), win(SRC), "-y"] + extra
+        if secret:
+            args.append(f"-p{PASSWORD}")
+        if name == "aes":
+            # Header stays readable: only the streams are encrypted.
+            args.append("-mhe=off")
+        run(tool, args, optional=not required)
+
+    # Encrypted header (-mhe=on): the archive cannot even be listed without
+    # the password, so the engine must ask for it up front.
+    run(tool, ["a", "-t7z", win(os.path.join(OUT, "aeshe.7z")), win(SRC),
+               "-y", "-m0=lzma2", "-mx5", f"-p{PASSWORD}", "-mhe=on"])
+
+    # Multi-volume (-v): 100 KiB parts force the fixture across several files.
+    vols = os.path.join(OUT, "vol.7z")
+    for stale in sorted(os.listdir(OUT)):
+        if stale.startswith("vol.7z"):
+            os.remove(os.path.join(OUT, stale))
+    run(tool, ["a", "-t7z", win(vols), win(SRC), "-y", "-m0=lzma2", "-mx5",
+               "-v100k"])
+
+    if big:
+        bigsrc = os.path.join(OUT, "_big")
+        os.makedirs(bigsrc, exist_ok=True)
+        write_big_file(os.path.join(bigsrc, "big.bin"), 96 * 1024 * 1024)
+        run(tool, ["a", "-t7z", win(os.path.join(OUT, "big.7z")), win(bigsrc),
+                   "-y", "-m0=lzma2", "-mx1"])
+        shutil.rmtree(bigsrc, ignore_errors=True)
+
+
+# --------------------------------------------------------------------------
+
+def clean() -> None:
+    os.makedirs(OUT, exist_ok=True)
+    for entry in os.listdir(OUT):
+        if entry.startswith(OWN_PREFIXES):
+            path = os.path.join(OUT, entry)
+            if os.path.isdir(path):
+                shutil.rmtree(path, ignore_errors=True)
+            else:
+                os.remove(path)
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--tool", help="path to 7zr.exe / 7z.exe / 7zr")
+    ap.add_argument("--big", action="store_true",
+                    help="also build a ~96 MiB single-file archive")
+    opts = ap.parse_args()
+
+    tool = find_tool(opts.tool)
+    print(f"7z tool: {tool}")
+
+    clean()
+    build_source({"binary": 300_000, "zeros": 2_000_000, "code": 400_000})
+    build_archives(tool, opts.big)
+
+    print(f"fixtures written to {OUT}")
+    for name in sorted(os.listdir(OUT)):
+        path = os.path.join(OUT, name)
+        if os.path.isfile(path):
+            print(f"  {name} ({os.path.getsize(path)} bytes)")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
@@ -0,0 +1,171 @@
+#!/usr/bin/env python3
+"""Builds split-archive fixtures for the multi-volume extraction tests.
+
+Output goes to tests/fixtures-split/ and covers the three naming conventions
+the engine recognises, plus two broken sets used to check the error messages:
+
+  plain.zip.001 .002 .003      byte split (7-Zip "split to volumes")
+  parts.part1.zip ... .part3.zip   byte split (WinRAR zip volumes)
+  disks.z01 .z02 .zip          zip split disks, offsets relative to each disk
+  broken.zip.001               first volume only, the rest missing
+  gap.zip.001 .gap.zip.003     volume 2 missing
+
+The byte-split sets are produced by slicing one ordinary archive. The
+"disks" set is built by hand: the central directory is rewritten so that every
+entry records the disk it starts on and an offset relative to that disk, which
+is what a real zip split disk archive looks like (APPNOTE 4.4.11).
+"""
+
+import io
+import os
+import shutil
+import struct
+import zipfile
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+# The test binary receives tests/fixtures as its fixture directory, and
+# make_fixtures.py has already rebuilt that tree by the time this script runs,
+# so the split sets are added there (only our own files are replaced).
+OUT = os.path.join(HERE, "fixtures")
+
+OWN_PREFIXES = ("plain.zip.", "parts.part", "disks.", "broken.zip.",
+                "gap.zip.", "split_single.zip")
+
+ENTRIES = [
+    ("readme.txt", b"split archive fixture\n" * 20),
+    ("sub/data.bin", bytes(range(256)) * 40),
+    ("sub/deep/more.bin", b"ABCD" * 3000),
+    ("tail.bin", bytes(reversed(range(256))) * 30),
+]
+
+
+def build_plain_zip():
+    """One ordinary archive; ZIP_STORED keeps the layout predictable."""
+    buf = io.BytesIO()
+    with zipfile.ZipFile(buf, "w", zipfile.ZIP_STORED) as zf:
+        for name, data in ENTRIES:
+            info = zipfile.ZipInfo(name, date_time=(2026, 1, 1, 0, 0, 0))
+            info.compress_type = zipfile.ZIP_STORED
+            zf.writestr(info, data)
+    return buf.getvalue()
+
+
+def read_central_directory(blob):
+    """Returns (cd_offset, cd_size, count, [(name, local_offset, cd_pos)])."""
+    eocd = blob.rfind(b"PK\x05\x06")
+    if eocd < 0:
+        raise SystemExit("fixture build: no end-of-central-directory record")
+    count, cd_size, cd_offset = struct.unpack_from("<HII", blob, eocd + 10)
+    entries = []
+    pos = cd_offset
+    for _ in range(count):
+        if blob[pos : pos + 4] != b"PK\x01\x02":
+            raise SystemExit("fixture build: bad central directory signature")
+        name_len, extra_len, comment_len = struct.unpack_from("<HHH", blob, pos + 28)
+        local_offset = struct.unpack_from("<I", blob, pos + 42)[0]
+        name = blob[pos + 46 : pos + 46 + name_len].decode("utf-8")
+        entries.append((name, local_offset, pos))
+        pos += 46 + name_len + extra_len + comment_len
+    return cd_offset, cd_size, count, entries
+
+
+def split_into_disks(blob, parts=3):
+    """Rewrites offsets so the archive looks like a real zip split disk set.
+
+    Entries are packed into `parts - 1` disks; the last disk carries whatever
+    is left plus the central directory and the end record.
+    """
+    cd_offset, _cd_size, count, entries = read_central_directory(blob)
+    entries.sort(key=lambda e: e[1])
+
+    # Local header size = fixed part + name + extra, so an entry ends where the
+    # next one begins (or at the central directory for the last one).
+    limits = []
+    for index, (_name, local_offset, _cd_pos) in enumerate(entries):
+        end = entries[index + 1][1] if index + 1 < len(entries) else cd_offset
+        limits.append((local_offset, end))
+
+    target = max(1, cd_offset // (parts - 1))
+    disk_of_entry = []
+    disk_starts = [0]
+    current = 0
+    for local_offset, end in limits:
+        if (end - disk_starts[current]) > target and current < parts - 2:
+            current += 1
+            disk_starts.append(local_offset)
+        disk_of_entry.append(current)
+
+    out = bytearray(blob)
+    # Central directory entries: disk number + offset relative to that disk.
+    for (name, local_offset, cd_pos), disk in zip(entries, disk_of_entry):
+        struct.pack_into("<H", out, cd_pos + 34, disk)
+        struct.pack_into("<I", out, cd_pos + 42, local_offset - disk_starts[disk])
+
+    last_disk = current
+    eocd = len(blob) - 22
+    struct.pack_into("<H", out, eocd + 4, last_disk)      # this disk
+    struct.pack_into("<H", out, eocd + 6, last_disk)      # disk with the cd
+    struct.pack_into("<H", out, eocd + 8, count)          # entries on this disk
+    struct.pack_into("<H", out, eocd + 10, count)         # entries in total
+    struct.pack_into("<I", out, eocd + 16, cd_offset - disk_starts[last_disk])
+
+    bounds = disk_starts[1:] + [len(blob)]
+    return [bytes(out[a:b]) for a, b in zip(disk_starts, bounds)]
+
+
+def write(path, data):
+    with open(path, "wb") as handle:
+        handle.write(data)
+    print("  %s (%d bytes)" % (os.path.basename(path), len(data)))
+
+
+def write_set(base, names, chunks):
+    for name, chunk in zip(names, chunks):
+        write(os.path.join(OUT, name % base), chunk)
+
+
+def write_disk_set(base, chunks):
+    """Split disks are named name.z01, name.z02, ..., name.zip: the last volume
+    (the one holding the central directory) drops the numeric suffix."""
+    for index, chunk in enumerate(chunks):
+        if index == len(chunks) - 1:
+            name = "%s.zip" % base
+        else:
+            name = "%s.z%02d" % (base, index + 1)
+        write(os.path.join(OUT, name), chunk)
+
+
+def main():
+    if not os.path.isdir(OUT):
+        os.makedirs(OUT)
+    for name in os.listdir(OUT):
+        if name.startswith(OWN_PREFIXES):
+            os.remove(os.path.join(OUT, name))
+
+    plain = build_plain_zip()
+    third = (len(plain) + 2) // 3
+    chunks = [plain[0:third], plain[third : 2 * third], plain[2 * third :]]
+    chunks = [c for c in chunks if c]
+
+    print("byte split (name.zip.NNN):")
+    write_set("plain", ["%s.zip.001", "%s.zip.002", "%s.zip.003"], chunks)
+
+    print("byte split (name.partN.zip):")
+    write_set("parts", ["%s.part1.zip", "%s.part2.zip", "%s.part3.zip"], chunks)
+
+    print("zip split disks (name.zNN + name.zip):")
+    disks = split_into_disks(plain)
+    write_disk_set("disks", disks)
+
+    print("broken sets:")
+    write(os.path.join(OUT, "broken.zip.001"), chunks[0])
+    write(os.path.join(OUT, "gap.zip.001"), chunks[0])
+    write(os.path.join(OUT, "gap.zip.003"), chunks[2] if len(chunks) > 2 else b"")
+
+    # A plain archive next to the sets, so the tests can prove the normal
+    # single file path still works now that volume detection runs first.
+    write(os.path.join(OUT, "split_single.zip"), plain)
+
+
+if __name__ == "__main__":
+    main()
@@ -1,262 +1,474 @@
-/* Host test shim: lets the POSIX extraction engine build and run on MinGW.
-   Injected with gcc -include for the test build only; never compiled into the
-   PS5 payload. It maps the *at() calls onto plain paths and fakes the few
-   POSIX bits Windows lacks (symlinks and O_NOFOLLOW have no Windows
-   equivalent, which is why the symlink tests are skipped there). */
-
-#ifndef WFM_TEST_POSIX_COMPAT_H
-#define WFM_TEST_POSIX_COMPAT_H
-
-#if defined(__MINGW32__) || defined(_WIN32)
-
-#include <errno.h>
-#include <fcntl.h>
-#include <io.h>
-#include <stdarg.h>
-#include <stdio.h>
-#include <stdlib.h>
-#include <string.h>
-#include <sys/stat.h>
-#include <sys/types.h>
-#include <time.h>
-#include <windows.h>
-
-#ifndef PATH_MAX
-#define PATH_MAX 4096
-#endif
-
-#define O_NOFOLLOW 0
-#define O_CLOEXEC 0
-/* Windows cannot open a directory with _open(); a non-zero sentinel lets the
-   shim detect directory opens and hand back a synthetic dirfd. */
-#define O_DIRECTORY 0x10000
-#define AT_SYMLINK_NOFOLLOW 0
-#define AT_REMOVEDIR 0x0200
-#ifndef S_IFLNK
-#define S_IFLNK 0xA000
-#endif
-#ifndef S_ISLNK
-#define S_ISLNK(m) (((m) & S_IFMT) == S_IFLNK)
-#endif
-
-#ifndef CLOCK_MONOTONIC
-#define CLOCK_MONOTONIC 1
-#endif
-
-#define WFM_FD_SLOTS 512
-
-#define open(...) wfm_open(__VA_ARGS__)
-
-static struct {
-  int fd;
-  char path[PATH_MAX];
-} wfm_fd_slots[WFM_FD_SLOTS];
-
-static void __attribute__((unused))
-wfm_fd_set(int fd, const char *path) {
-  int i;
-
-  if(fd < 0) {
-    return;
-  }
-  for(i = 0; i < WFM_FD_SLOTS; i++) {
-    if(wfm_fd_slots[i].fd == fd || !wfm_fd_slots[i].path[0]) {
-      wfm_fd_slots[i].fd = fd;
-      snprintf(wfm_fd_slots[i].path, PATH_MAX, "%s", path);
-      return;
-    }
-  }
-}
-
-static void __attribute__((unused))
-wfm_fd_clear(int fd) {
-  int i;
-
-  for(i = 0; i < WFM_FD_SLOTS; i++) {
-    if(wfm_fd_slots[i].fd == fd) {
-      wfm_fd_slots[i].fd = -1;
-      wfm_fd_slots[i].path[0] = 0;
-      return;
-    }
-  }
-}
-
-static const char *
-wfm_fd_path(int fd) {
-  int i;
-
-  for(i = 0; i < WFM_FD_SLOTS; i++) {
-    if(wfm_fd_slots[i].fd == fd) {
-      return wfm_fd_slots[i].path;
-    }
-  }
-  return NULL;
-}
-
-static int
-wfm_join(int dirfd, const char *rel, char *out, size_t out_size) {
-  const char *base = wfm_fd_path(dirfd);
-
-  if(!base) {
-    errno = EBADF;
-    return -1;
-  }
-  if(snprintf(out, out_size, "%s/%s", base, rel) >= (int)out_size) {
-    errno = ENAMETOOLONG;
-    return -1;
-  }
-  return 0;
-}
-
-static int __attribute__((unused))
-wfm_open(const char *path, int flags, ...) {
-  int mode = 0;
-  int fd;
-
-  if(flags & O_CREAT) {
-    va_list ap;
-
-    va_start(ap, flags);
-    mode = va_arg(ap, int);
-    va_end(ap);
-  }
-  /* Directory opens become synthetic fds so openat/mkdirat can resolve them
-     to paths; _open() returns EACCES for directories on Windows. */
-  if(flags & O_DIRECTORY) {
-    static int next_dirfd = 0x10000;
-
-    fd = next_dirfd++;
-    wfm_fd_set(fd, path);
-    return fd;
-  }
-  /* Force O_BINARY: MinGW's _open defaults to text mode, which would
-     translate LF -> CRLF on write and corrupt binary payloads. */
-  fd = _open(path, (flags & ~(O_NOFOLLOW | O_DIRECTORY | O_CLOEXEC)) | O_BINARY,
-             mode);
-  if(fd >= 0) {
-    wfm_fd_set(fd, path);
-  }
-  return fd;
-}
-
-static int __attribute__((unused))
-wfm_openat(int dirfd, const char *path, int flags, ...) {
-  char full[PATH_MAX];
-  int mode = 0;
-
-  if(wfm_join(dirfd, path, full, sizeof(full))) {
-    return -1;
-  }
-  if(flags & O_CREAT) {
-    va_list ap;
-
-    va_start(ap, flags);
-    mode = va_arg(ap, int);
-    va_end(ap);
-  }
-  return wfm_open(full, flags, mode);
-}
-
-static int __attribute__((unused))
-wfm_mkdirat(int dirfd, const char *path, mode_t mode) {
-  char full[PATH_MAX];
-
-  (void)mode;
-  if(wfm_join(dirfd, path, full, sizeof(full))) {
-    return -1;
-  }
-  return mkdir(full);
-}
-
-static int __attribute__((unused))
-wfm_renameat(int from_fd, const char *from, int to_fd, const char *to) {
-  char src[PATH_MAX];
-  char dst[PATH_MAX];
-
-  if(wfm_join(from_fd, from, src, sizeof(src)) ||
-     wfm_join(to_fd, to, dst, sizeof(dst))) {
-    return -1;
-  }
-  /* Windows rename() refuses to replace an existing file. */
-  if(_access(dst, 0) == 0) {
-    if(remove(dst)) {
-      return -1;
-    }
-  }
-  return rename(src, dst);
-}
-
-static int __attribute__((unused))
-wfm_rename(const char *from, const char *to) {
-  /* Windows rename() refuses to replace an existing file, unlike POSIX. */
-  if(_access(to, 0) == 0) {
-    if(remove(to)) {
-      return -1;
-    }
-  }
-  return rename(from, to);
-}
-
-static int __attribute__((unused))
-wfm_unlinkat(int dirfd, const char *path, int flags) {
-  char full[PATH_MAX];
-
-  if(wfm_join(dirfd, path, full, sizeof(full))) {
-    return -1;
-  }
-  return (flags & AT_REMOVEDIR) ? rmdir(full) : unlink(full);
-}
-
-static int __attribute__((unused))
-wfm_mkdir1(const char *path) {
-  return mkdir(path); /* MinGW's mkdir() takes a single argument. */
-}
-
-static int __attribute__((unused))
-wfm_fstatat(int dirfd, const char *path, struct stat *st, int flags) {
-  char full[PATH_MAX];
-
-  (void)flags;
-  if(wfm_join(dirfd, path, full, sizeof(full))) {
-    return -1;
-  }
-  return stat(full, st);
-}
-
-static int __attribute__((unused))
-wfm_fsync(int fd) {
-  return _commit(fd);
-}
-
-static int __attribute__((unused))
-wfm_fchmod(int fd, mode_t mode) {
-  (void)fd;
-  (void)mode;
-  return 0; /* Windows has no Unix modes; the engine ignores this failure. */
-}
-
-static int __attribute__((unused))
-wfm_close(int fd) {
-  wfm_fd_clear(fd);
-  if(fd >= 0x10000) {
-    return 0; /* synthetic dirfd, nothing to close */
-  }
-  return _close(fd);
-}
-
-#define mkdir(p, ...) wfm_mkdir1(p)
-#define open(...) wfm_open(__VA_ARGS__)
-#define openat(...) wfm_openat(__VA_ARGS__)
-#define mkdirat(d, p, m) wfm_mkdirat(d, p, m)
-#define rename(a, b) wfm_rename(a, b)
-#define renameat(sd, sp, dd, dp) wfm_renameat(sd, sp, dd, dp)
-#define unlinkat(d, p, f) wfm_unlinkat(d, p, f)
-#define fstatat(d, p, s, f) wfm_fstatat(d, p, s, f)
-#define fsync(fd) wfm_fsync(fd)
-#define fchmod(fd, mode) wfm_fchmod(fd, mode)
-#define close(fd) wfm_close(fd)
-#define lstat(p, s) stat(p, s)
-
-#endif /* _WIN32 */
-
-#endif /* WFM_TEST_POSIX_COMPAT_H */
+/* Host test shim: lets the POSIX extraction engine build and run on MinGW.
+   Injected with gcc -include for the test build only; never compiled into the
+   PS5 payload. It maps the *at() calls onto plain paths and fakes the few
+   POSIX bits Windows lacks (symlinks and O_NOFOLLOW have no Windows
+   equivalent, which is why the symlink tests are skipped there). */
+
+#ifndef WFM_TEST_POSIX_COMPAT_H
+#define WFM_TEST_POSIX_COMPAT_H
+
+/* _wopendir / struct _wdirent require Vista+; pull the SDK level up before any
+   system header touches the type definitions. */
+#ifndef _WIN32_WINNT
+#define _WIN32_WINNT 0x0600
+#endif
+
+#if defined(__MINGW32__) || defined(_WIN32)
+
+#include <errno.h>
+#include <fcntl.h>
+#include <io.h>
+#include <direct.h>
+#include <stdarg.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/stat.h>
+#include <sys/time.h>
+#include <sys/types.h>
+#include <sys/utime.h>
+#include <time.h>
+#include <wchar.h>
+#include <windows.h>
+#include <dirent.h>
+
+#ifndef PATH_MAX
+#define PATH_MAX 4096
+#endif
+
+#define O_NOFOLLOW 0
+#define O_CLOEXEC 0
+/* Windows cannot open a directory with _open(); a non-zero sentinel lets the
+   shim detect directory opens and hand back a synthetic dirfd. */
+#define O_DIRECTORY 0x10000
+#define AT_SYMLINK_NOFOLLOW 0
+#define AT_REMOVEDIR 0x0200
+#ifndef S_IFLNK
+#define S_IFLNK 0xA000
+#endif
+#ifndef S_ISLNK
+#define S_ISLNK(m) (((m) & S_IFMT) == S_IFLNK)
+#endif
+
+#ifndef CLOCK_MONOTONIC
+#define CLOCK_MONOTONIC 1
+#endif
+
+#define WFM_FD_SLOTS 512
+
+#define open(...) wfm_open(__VA_ARGS__)
+
+static struct {
+  int fd;
+  char path[PATH_MAX];
+} wfm_fd_slots[WFM_FD_SLOTS];
+
+static void __attribute__((unused))
+wfm_fd_set(int fd, const char *path) {
+  int i;
+
+  if(fd < 0) {
+    return;
+  }
+  for(i = 0; i < WFM_FD_SLOTS; i++) {
+    if(wfm_fd_slots[i].fd == fd || !wfm_fd_slots[i].path[0]) {
+      wfm_fd_slots[i].fd = fd;
+      snprintf(wfm_fd_slots[i].path, PATH_MAX, "%s", path);
+      return;
+    }
+  }
+}
+
+static void __attribute__((unused))
+wfm_fd_clear(int fd) {
+  int i;
+
+  for(i = 0; i < WFM_FD_SLOTS; i++) {
+    if(wfm_fd_slots[i].fd == fd) {
+      wfm_fd_slots[i].fd = -1;
+      wfm_fd_slots[i].path[0] = 0;
+      return;
+    }
+  }
+}
+
+static const char *
+wfm_fd_path(int fd) {
+  int i;
+
+  for(i = 0; i < WFM_FD_SLOTS; i++) {
+    if(wfm_fd_slots[i].fd == fd) {
+      return wfm_fd_slots[i].path;
+    }
+  }
+  return NULL;
+}
+
+static int
+wfm_join(int dirfd, const char *rel, char *out, size_t out_size) {
+  const char *base = wfm_fd_path(dirfd);
+
+  if(!base) {
+    errno = EBADF;
+    return -1;
+  }
+  if(snprintf(out, out_size, "%s/%s", base, rel) >= (int)out_size) {
+    errno = ENAMETOOLONG;
+    return -1;
+  }
+  return 0;
+}
+
+/* UTF-8 to UTF-16, for the wide entry points below.  The engines speak UTF-8
+   (that is what an archive stores), but MinGW's ANSI entry points decode their
+   argument in the system code page: on a CP936 or CP1252 host a name such as
+   "中文-テスト.txt" is either mangled or rejected outright with the
+   unhelpful errno -1.  Going through the wide API keeps the on-disk name
+   identical to the archive's. */
+static void __attribute__((unused))
+wfm_wide(const char *src, wchar_t *dst, size_t cap) {
+  const unsigned char *p = (const unsigned char *)src;
+  size_t out = 0;
+
+  while(*p && out + 2 < cap) {
+    unsigned long cp = *p++;
+
+    if(cp >= 0x80) {
+      unsigned extra = 0;
+      unsigned i;
+
+      if((cp & 0xE0) == 0xC0) {
+        cp &= 0x1F;
+        extra = 1;
+      } else if((cp & 0xF0) == 0xE0) {
+        cp &= 0x0F;
+        extra = 2;
+      } else if((cp & 0xF8) == 0xF0) {
+        cp &= 0x07;
+        extra = 3;
+      } else {
+        cp = '?';
+        extra = 0;
+      }
+      for(i = 0; i < extra; i++) {
+        if((*p & 0xC0) != 0x80) {
+          cp = '?';
+          break;
+        }
+        cp = (cp << 6) | (unsigned long)(*p++ & 0x3F);
+      }
+    }
+    if(cp >= 0x10000) {
+      cp -= 0x10000;
+      dst[out++] = (wchar_t)(0xD800 | (cp >> 10));
+      dst[out++] = (wchar_t)(0xDC00 | (cp & 0x3FF));
+    } else {
+      dst[out++] = (wchar_t)cp;
+    }
+  }
+  dst[out] = 0;
+}
+
+/* Defined further down; the *at() shims above call them. */
+static int wfm_mkdir1(const char *path);
+static int wfm_unlink(const char *path);
+static int wfm_rmdir(const char *path);
+static int wfm_stat(const char *path, struct stat *st);
+static int wfm_rename(const char *from, const char *to);
+
+static int __attribute__((unused))
+wfm_open(const char *path, int flags, ...) {
+  int mode = 0;
+  int fd;
+
+  if(flags & O_CREAT) {
+    va_list ap;
+
+    va_start(ap, flags);
+    mode = va_arg(ap, int);
+    va_end(ap);
+  }
+  /* Directory opens become synthetic fds so openat/mkdirat can resolve them
+     to paths; _open() returns EACCES for directories on Windows. */
+  if(flags & O_DIRECTORY) {
+    static int next_dirfd = 0x10000;
+
+    fd = next_dirfd++;
+    wfm_fd_set(fd, path);
+    return fd;
+  }
+  /* Force O_BINARY: MinGW's _open defaults to text mode, which would
+     translate LF -> CRLF on write and corrupt binary payloads.  The wide
+     call keeps a non-ASCII name intact (see wfm_wide). */
+  {
+    wchar_t wide[PATH_MAX];
+
+    wfm_wide(path, wide, PATH_MAX);
+    fd = _wopen(wide, (flags & ~(O_NOFOLLOW | O_DIRECTORY | O_CLOEXEC)) |
+                          O_BINARY,
+                mode);
+  }
+  if(fd >= 0) {
+    wfm_fd_set(fd, path);
+  }
+  return fd;
+}
+
+static int __attribute__((unused))
+wfm_openat(int dirfd, const char *path, int flags, ...) {
+  char full[PATH_MAX];
+  int mode = 0;
+
+  if(wfm_join(dirfd, path, full, sizeof(full))) {
+    return -1;
+  }
+  if(flags & O_CREAT) {
+    va_list ap;
+
+    va_start(ap, flags);
+    mode = va_arg(ap, int);
+    va_end(ap);
+  }
+  return wfm_open(full, flags, mode);
+}
+
+static int __attribute__((unused))
+wfm_mkdirat(int dirfd, const char *path, mode_t mode) {
+  char full[PATH_MAX];
+
+  (void)mode;
+  if(wfm_join(dirfd, path, full, sizeof(full))) {
+    return -1;
+  }
+  return wfm_mkdir1(full);
+}
+
+static int __attribute__((unused))
+wfm_renameat(int from_fd, const char *from, int to_fd, const char *to) {
+  char src[PATH_MAX];
+  char dst[PATH_MAX];
+
+  if(wfm_join(from_fd, from, src, sizeof(src)) ||
+     wfm_join(to_fd, to, dst, sizeof(dst))) {
+    return -1;
+  }
+  return wfm_rename(src, dst);
+}
+
+static int __attribute__((unused))
+wfm_rename(const char *from, const char *to) {
+  wchar_t wfrom[PATH_MAX];
+  wchar_t wto[PATH_MAX];
+
+  wfm_wide(from, wfrom, PATH_MAX);
+  wfm_wide(to, wto, PATH_MAX);
+  /* Windows rename() refuses to replace an existing file, unlike POSIX. */
+  if(_waccess(wto, 0) == 0) {
+    if(_wremove(wto)) {
+      return -1;
+    }
+  }
+  return _wrename(wfrom, wto);
+}
+
+static int __attribute__((unused))
+wfm_unlinkat(int dirfd, const char *path, int flags) {
+  char full[PATH_MAX];
+
+  if(wfm_join(dirfd, path, full, sizeof(full))) {
+    return -1;
+  }
+  return (flags & AT_REMOVEDIR) ? wfm_rmdir(full) : wfm_unlink(full);
+}
+
+static int __attribute__((unused))
+wfm_mkdir1(const char *path) {
+  wchar_t wide[PATH_MAX];
+
+  wfm_wide(path, wide, PATH_MAX);
+  return _wmkdir(wide); /* MinGW's mkdir() takes a single argument. */
+}
+
+static int __attribute__((unused))
+wfm_unlink(const char *path) {
+  wchar_t wide[PATH_MAX];
+
+  wfm_wide(path, wide, PATH_MAX);
+  return _wunlink(wide);
+}
+
+static int __attribute__((unused))
+wfm_rmdir(const char *path) {
+  wchar_t wide[PATH_MAX];
+
+  wfm_wide(path, wide, PATH_MAX);
+  return _wrmdir(wide);
+}
+
+/* _wstati64 fills its own struct; the engines only ever read st_mode, st_size
+   and st_mtime, so copying those across is safe and avoids depending on how
+   this toolchain happens to alias `struct stat`. */
+static int __attribute__((unused))
+wfm_stat(const char *path, struct stat *st) {
+  wchar_t wide[PATH_MAX];
+  struct _stati64 wst;
+
+  wfm_wide(path, wide, PATH_MAX);
+  if(_wstati64(wide, &wst)) {
+    return -1;
+  }
+  memset(st, 0, sizeof(*st));
+  st->st_mode = (mode_t)wst.st_mode;
+  st->st_size = (off_t)wst.st_size;
+  st->st_mtime = (time_t)wst.st_mtime;
+  return 0;
+}
+
+static int __attribute__((unused))
+wfm_fstatat(int dirfd, const char *path, struct stat *st, int flags) {
+  char full[PATH_MAX];
+
+  (void)flags;
+  if(wfm_join(dirfd, path, full, sizeof(full))) {
+    return -1;
+  }
+  return wfm_stat(full, st);
+}
+
+static int __attribute__((unused))
+wfm_fsync(int fd) {
+  return _commit(fd);
+}
+
+static int __attribute__((unused))
+wfm_fchmod(int fd, mode_t mode) {
+  (void)fd;
+  (void)mode;
+  return 0; /* Windows has no Unix modes; the engine ignores this failure. */
+}
+
+/* MinGW has no utimes(); _utime() is the same thing with second precision,
+   which is all the 7z engine asks for (it feeds the extractor both fields). */
+static int __attribute__((unused))
+wfm_utimes(const char *path, const struct timeval tv[2]) {
+  struct _utimbuf ut;
+
+  ut.actime = tv[0].tv_sec;
+  ut.modtime = tv[1].tv_sec;
+  return _utime(path, &ut);
+}
+
+static int __attribute__((unused))
+wfm_close(int fd) {
+  wfm_fd_clear(fd);
+  if(fd >= 0x10000) {
+    return 0; /* synthetic dirfd, nothing to close */
+  }
+  return _close(fd);
+}
+
+/* MinGW's fopen() decodes the path in the system code page, the same way
+   stat() does.  Redirect to _wfopen so a UTF-8 path goes through the wide
+   API and round-trips back to the on-disk name regardless of the host's
+   ACP.  The translation units that include this shim may not call fopen()
+   themselves, so mark the wrapper as unused to keep -Werror quiet. */
+__attribute__((unused))
+static FILE *wfm_fopen(const char *path, const char *mode) {
+  wchar_t wide_path[PATH_MAX];
+  wchar_t wide_mode[16];
+  size_t i;
+
+  wfm_wide(path, wide_path, PATH_MAX);
+  for(i = 0; i + 1 < sizeof(wide_mode) && mode[i]; i++) {
+    wide_mode[i] = (wchar_t)(unsigned char)mode[i];
+  }
+  wide_mode[i] = 0;
+  return _wfopen(wide_path, wide_mode);
+}
+
+#define fopen(p, m) wfm_fopen(p, m)
+
+#define mkdir(p, ...) wfm_mkdir1(p)
+#define rmdir(p) wfm_rmdir(p)
+#define unlink(p) wfm_unlink(p)
+#define open(...) wfm_open(__VA_ARGS__)
+#define openat(...) wfm_openat(__VA_ARGS__)
+#define mkdirat(d, p, m) wfm_mkdirat(d, p, m)
+#define rename(a, b) wfm_rename(a, b)
+#define renameat(sd, sp, dd, dp) wfm_renameat(sd, sp, dd, dp)
+#define unlinkat(d, p, f) wfm_unlinkat(d, p, f)
+#define fstatat(d, p, s, f) wfm_fstatat(d, p, s, f)
+#define fsync(fd) wfm_fsync(fd)
+#define fchmod(fd, mode) wfm_fchmod(fd, mode)
+#define close(fd) wfm_close(fd)
+/* Direct lstat/stat to the wide-path shim so non-ASCII archive entries survive
+   a CP936 or CP1252 host.  MinGW's stat() defaults to the ANSI entry point
+   and silently truncates names it cannot represent. */
+#define lstat(p, s) wfm_stat(p, s)
+#define stat(p, s) wfm_stat(p, s)
+#define utimes(p, tv) wfm_utimes(p, tv)
+/* opendir/readdir/closedir go through the wide variants so the names we get
+   back are real UTF-8; otherwise MinGW hands us whatever the system code page
+   made of the filename, which round-trips through a non-ASCII UTF-8 entry as
+   a garbage string that no later wfm_stat() call can resolve. */
+typedef struct {
+  _WDIR *wd;
+  struct dirent de;
+} WFM_DIR;
+
+static DIR * __attribute__((unused))
+wfm_opendir(const char *path) {
+  wchar_t wide[PATH_MAX];
+  WFM_DIR *wfm;
+
+  wfm_wide(path, wide, PATH_MAX);
+  wfm = (WFM_DIR *)malloc(sizeof(*wfm));
+  if(!wfm) {
+    return NULL;
+  }
+  wfm->wd = _wopendir(wide);
+  if(!wfm->wd) {
+    free(wfm);
+    return NULL;
+  }
+  return (DIR *)wfm;
+}
+
+static struct dirent * __attribute__((unused))
+wfm_readdir(DIR *d) {
+  WFM_DIR *wfm = (WFM_DIR *)d;
+  struct _wdirent *we;
+
+  if(!wfm) {
+    return NULL;
+  }
+  we = _wreaddir(wfm->wd);
+  if(!we) {
+    return NULL;
+  }
+  WideCharToMultiByte(CP_UTF8, 0, we->d_name, -1, wfm->de.d_name,
+                      sizeof(wfm->de.d_name), NULL, NULL);
+  wfm->de.d_ino = we->d_ino;
+  wfm->de.d_reclen = (unsigned short)strlen(wfm->de.d_name);
+  return &wfm->de;
+}
+
+static int __attribute__((unused))
+wfm_closedir(DIR *d) {
+  WFM_DIR *wfm = (WFM_DIR *)d;
+
+  if(!wfm) {
+    return -1;
+  }
+  _wclosedir(wfm->wd);
+  free(wfm);
+  return 0;
+}
+
+#define opendir(p) wfm_opendir(p)
+#define readdir(d) wfm_readdir(d)
+#define closedir(d) wfm_closedir(d)
+
+#endif /* _WIN32 */
+
+#endif /* WFM_TEST_POSIX_COMPAT_H */
@@ -0,0 +1,235 @@
+#!/usr/bin/env bash
+# Host test runner for the 7z engine.
+#
+#   ./tests/run-sevenz-tests.sh
+#
+# Builds the vendored LZMA SDK subset plus the project's own folder decoder
+# (src/sevenz_chain.c), generates real .7z fixtures with a 7-Zip binary,
+# extracts every fixture through that decoder and compares the result byte for
+# byte against the source tree.
+#
+# On Windows this expects MinGW gcc in PATH and must be started with the MSYS
+# bash explicitly (`/usr/bin/bash tests/run-sevenz-tests.sh`) -- a bare `bash`
+# can resolve to C:\Windows\System32\bash.exe, i.e. the WSL launcher.
+
+set -e
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -W 2>/dev/null || pwd)"
+BUILD="$ROOT/.build/sevenz-test"
+SEVENZ_DIR="$ROOT/third_party/7z"
+FIXTURES="$ROOT/tests/fixtures-7z"
+COMPAT_INC="$ROOT/tests/compat"
+PYTHON="${PYTHON:-python3}"
+CC="${CC:-gcc}"
+
+# Archives the engine cannot read yet.  Each entry needs a reason; when one of
+# them starts passing the script says so, so the list cannot rot.
+#
+# Empty since v1.9.3M: `aeshe` (-mhe=on encrypted header) used to live here.  An
+# encrypted header is now decrypted by src/sevenz_header.c before the SDK sees
+# the folder table, so the last known 7z gap is closed.
+KNOWN_GAPS=""
+
+# Must match PASSWORD in tests/make_sevenz_fixtures.py.
+FIXTURE_PASSWORD="Secret123"
+
+find "$BUILD" -maxdepth 1 -type f \( -name '*.o' -o -name '*.exe' \) -delete 2>/dev/null || true
+mkdir -p "$BUILD"
+
+# ---------------------------------------------------------------- vendor
+CFLAGS_7Z=(-O2 -w -DZ7_PPMD_SUPPORT -D_FILE_OFFSET_BITS=64 -D_LARGEFILE_SOURCE
+           -DNDEBUG -D_REENTRANT)
+
+VENDOR_OBJS=()
+for src in "$SEVENZ_DIR"/*.c; do
+  name="$(basename "$src" .c)"
+  "$CC" -c "${CFLAGS_7Z[@]}" -o "$BUILD/$name.o" "$src"
+  VENDOR_OBJS+=("$BUILD/$name.o")
+done
+
+# The engine modules are held to the same strictness as the rest of src/.
+# sevenz_volstream reuses the ZIP side's volume-set detector, so zipx_volume
+# is built here as well.
+"$CC" -c -O2 -Wall -Wextra -Werror -D_FILE_OFFSET_BITS=64 -D_LARGEFILE_SOURCE \
+  -I"$SEVENZ_DIR" -I"$ROOT/src" -o "$BUILD/sevenz_chain.o" \
+  "$ROOT/src/sevenz_chain.c"
+"$CC" -c -O2 -Wall -Wextra -Werror -D_FILE_OFFSET_BITS=64 -D_LARGEFILE_SOURCE \
+  -I"$SEVENZ_DIR" -I"$ROOT/src" -o "$BUILD/sevenz_volstream.o" \
+  "$ROOT/src/sevenz_volstream.c"
+"$CC" -c -O2 -Wall -Wextra -Werror -D_FILE_OFFSET_BITS=64 -D_LARGEFILE_SOURCE \
+  -I"$SEVENZ_DIR" -I"$ROOT/src" -o "$BUILD/sevenz_header.o" \
+  "$ROOT/src/sevenz_header.c"
+"$CC" -c -O2 -Wall -Wextra -Werror -D_FILE_OFFSET_BITS=64 -D_LARGEFILE_SOURCE \
+  -I"$SEVENZ_DIR" -I"$ROOT/src" -o "$BUILD/sevenz_mt.o" "$ROOT/src/sevenz_mt.c"
+"$CC" -c -O2 -Wall -Wextra -Werror -D_FILE_OFFSET_BITS=64 -D_LARGEFILE_SOURCE \
+  -I"$ROOT/src" -o "$BUILD/zipx_volume.o" "$ROOT/src/zipx_volume.c"
+
+# The extraction facade is engine code too, so it gets the host POSIX shim as
+# well as the same strictness (see tests/run-tests.sh for the ZIP/RAR pair).
+# zipx_common carries the limit profiles and the status text that all three
+# engines share.
+"$CC" -c -O2 -Wall -Wextra -Werror -I"$ROOT/src" -o "$BUILD/zipx_common.o" \
+  "$ROOT/src/zipx_common.c"
+"$CC" -c -O2 -Wall -Wextra -Werror -D_FILE_OFFSET_BITS=64 -D_LARGEFILE_SOURCE \
+  -I"$SEVENZ_DIR" -I"$ROOT/src" -I"$COMPAT_INC" \
+  -include "$ROOT/tests/posix_compat.h" \
+  -o "$BUILD/sevenz_extract.o" "$ROOT/src/sevenz_extract.c"
+
+ENGINE_OBJS=("$BUILD/sevenz_chain.o" "$BUILD/sevenz_header.o"
+             "$BUILD/sevenz_volstream.o" "$BUILD/sevenz_mt.o"
+             "$BUILD/zipx_volume.o" "$BUILD/zipx_common.o")
+
+FACADE_OBJS=("$BUILD/sevenz_extract.o" "${ENGINE_OBJS[@]}")
+
+# unrar-style extra libs are only needed by the Windows path of 7zFile.c.
+EXTRA_LIBS=()
+case "$(uname -s)" in
+  MINGW*|MSYS*|CYGWIN*) EXTRA_LIBS=(-lole32 -loleaut32 -luuid -ladvapi32 -luser32 -lshell32) ;;
+esac
+
+"$CC" -O2 -w -I"$SEVENZ_DIR" -I"$ROOT/src" -o "$BUILD/sevenz_chain_e2e" \
+  "$ROOT/tests/sevenz_chain_e2e.c" "${ENGINE_OBJS[@]}" "${VENDOR_OBJS[@]}" \
+  "${EXTRA_LIBS[@]}"
+
+# The facade driver: the same strict flags as the engine, plus the POSIX shim,
+# because a MinGW host has neither statvfs() nor a two-argument mkdir().
+"$CC" -O2 -Wall -Wextra -I"$SEVENZ_DIR" -I"$ROOT/src" -I"$COMPAT_INC" \
+  -include "$ROOT/tests/posix_compat.h" \
+  -o "$BUILD/test_sevenz_extract" "$ROOT/tests/test_sevenz_extract.c" \
+  "${FACADE_OBJS[@]}" "${VENDOR_OBJS[@]}" "${EXTRA_LIBS[@]}"
+
+# The SDK-baseline driver is kept buildable: it is the fastest way to tell an
+# engine bug from an SDK one when a fixture starts failing.
+"$CC" -O2 -w -I"$SEVENZ_DIR" -o "$BUILD/sevenz_e2e" \
+  "$ROOT/tests/sevenz_e2e.c" "${VENDOR_OBJS[@]}" "${EXTRA_LIBS[@]}"
+
+# ---------------------------------------------------------------- fixtures
+if [ ! -f "$FIXTURES/lzma2.7z" ]; then
+  echo "== generating 7z fixtures =="
+  if ! "$PYTHON" "$ROOT/tests/make_sevenz_fixtures.py"; then
+    echo "SKIP: no 7z tool available, cannot build fixtures" >&2
+    exit 0
+  fi
+fi
+
+# ---------------------------------------------------------------- matrix
+pass=0
+fail=0
+
+is_gap() {
+  for g in $KNOWN_GAPS; do
+    [ "$g" = "$1" ] && return 0
+  done
+  return 1
+}
+
+run_case() {
+  local name="$1" archive="$2" password="${3:-}"
+  local out log rc
+
+  # A fresh directory per case keeps the run repeatable without deleting a tree
+  # of previous results, which guarded shells refuse to do.
+  out="$(mktemp -d "$BUILD/out/XXXXXX")" || return
+  log="$out.log"
+
+  rc=0
+  if [ -n "$password" ]; then
+    "$BUILD/sevenz_chain_e2e" "$archive" "$out" "$password" >"$log" 2>&1 || rc=$?
+  else
+    "$BUILD/sevenz_chain_e2e" "$archive" "$out" >"$log" 2>&1 || rc=$?
+  fi
+
+  if [ "$rc" -eq 0 ] &&
+     diff -r "$FIXTURES/_src" "$out/_src" >/dev/null 2>&1; then
+    if is_gap "$name"; then
+      printf '  %-12s GAP CLOSED (remove from KNOWN_GAPS)\n' "$name"
+      fail=$((fail + 1))
+    else
+      printf '  %-12s ok\n' "$name"
+      pass=$((pass + 1))
+    fi
+    return
+  fi
+
+  if is_gap "$name"; then
+    printf '  %-12s known gap (%s)\n' "$name" "$(head -1 "$log")"
+    pass=$((pass + 1))
+  else
+    printf '  %-12s FAIL\n' "$name"
+    sed -n '1,20p' "$log" | sed 's/^/      /'
+    fail=$((fail + 1))
+  fi
+}
+
+echo "== 7z fixture matrix (engine: src/sevenz_chain.c) =="
+for a in store lzma2 lzma ppmd bcj delta utf8 bcj2 solidoff bcj2off aes aeshe; do
+  [ -f "$FIXTURES/$a.7z" ] || continue
+  case "$a" in
+    aes|aeshe) run_case "$a" "$FIXTURES/$a.7z" "$FIXTURE_PASSWORD" ;;
+    *) run_case "$a" "$FIXTURES/$a.7z" ;;
+  esac
+done
+if [ -f "$FIXTURES/vol.7z.001" ]; then
+  run_case "vol.7z.001" "$FIXTURES/vol.7z.001"
+fi
+
+# ------------------------------------------------- extraction facade
+# The same fixtures again, but through src/sevenz_extract.c: staging, publish,
+# limits, conflict policy and name validation all have to agree with the
+# decoder before the format is wired into the server.
+echo
+echo "== 7z extraction facade (engine: src/sevenz_extract.c) =="
+mkdir -p "$BUILD/fx"
+for a in store lzma2 lzma ppmd bcj delta utf8 bcj2 solidoff bcj2off aes aeshe; do
+  [ -f "$FIXTURES/$a.7z" ] || continue
+  out="$(mktemp -d "$BUILD/fx/XXXXXX")" || continue
+  target="$out/$a"
+  mkdir -p "$target"
+  rc=0
+  case "$a" in
+    aes|aeshe) "$BUILD/test_sevenz_extract" "$FIXTURES/$a.7z" "$target" \
+           "$FIXTURE_PASSWORD" >"$out.log" 2>&1 || rc=$? ;;
+    *)   "$BUILD/test_sevenz_extract" "$FIXTURES/$a.7z" "$target" \
+           >"$out.log" 2>&1 || rc=$? ;;
+  esac
+  if [ "$rc" -eq 0 ] && diff -r "$FIXTURES/_src" "$target/_src" >/dev/null 2>&1; then
+    printf '  %-12s ok\n' "$a"
+    pass=$((pass + 1))
+  else
+    printf '  %-12s FAIL\n' "$a"
+    sed -n '1,20p' "$out.log" | sed 's/^/      /'
+    fail=$((fail + 1))
+  fi
+done
+
+# A byte-split set goes through the same facade.
+if [ -f "$FIXTURES/vol.7z.001" ]; then
+  out="$(mktemp -d "$BUILD/fx/XXXXXX")" || out=
+  if [ -n "$out" ]; then
+    rc=0
+    "$BUILD/test_sevenz_extract" "$FIXTURES/vol.7z.001" "$out/vol" \
+      >"$out.log" 2>&1 || rc=$?
+    if [ "$rc" -eq 0 ] && diff -r "$FIXTURES/_src" "$out/vol/_src" >/dev/null 2>&1; then
+      printf '  %-12s ok\n' "vol.7z.001"
+      pass=$((pass + 1))
+    else
+      printf '  %-12s FAIL\n' "vol.7z.001"
+      sed -n '1,20p' "$out.log" | sed 's/^/      /'
+      fail=$((fail + 1))
+    fi
+  fi
+fi
+
+echo
+echo "== 7z error and policy paths =="
+mkdir -p "$BUILD/cases"
+cases_work="$(mktemp -d "$BUILD/cases/XXXXXX")"
+if "$BUILD/test_sevenz_extract" --cases "$FIXTURES" "$cases_work"; then
+  pass=$((pass + 1))
+else
+  fail=$((fail + 1))
+fi
+
+echo
+echo "$pass passed, $fail failed"
+[ "$fail" -eq 0 ]
@@ -14,12 +14,19 @@ BUILD="$ROOT/.build/host-test"
 PYTHON="${PYTHON:-python3}"
 CC="${CC:-gcc}"

-rm -rf "$BUILD"
+# Clean previous build outputs without nuking the whole tree (avoids
+# bulk-delete guards); stale fixture copies in work-* dirs are fine because
+# make_fixtures.py rewrites fixtures/ and the suites recreate their workdirs.
+find "$BUILD" -maxdepth 1 -type f -name '*.o' -delete 2>/dev/null || true
+find "$BUILD" -maxdepth 1 -type f -name 'test-*' -delete 2>/dev/null || true
+find "$BUILD" -maxdepth 1 -type f -name '*.log' -delete 2>/dev/null || true
 mkdir -p "$BUILD"

 "$PYTHON" "$ROOT/tests/make_fixtures.py"
+"$PYTHON" "$ROOT/tests/make_split_fixtures.py"

-MZ_CFLAGS=(-I"$ROOT/third_party/minizip-ng/include" -DHAVE_ZLIB -DZLIB_COMPAT)
+MZ_CFLAGS=(-I"$ROOT/third_party/minizip-ng/include" -DHAVE_ZLIB -DZLIB_COMPAT -D_FILE_OFFSET_BITS=64 \
+  -DHAVE_WZAES -DHAVE_PKCRYPT)
 RAR_CFLAGS=(-I"$ROOT/third_party/unrar" -DDMC_UNRAR_DISABLE_BE32TOH_BE64TOH=1)
 HOST_KIND=posix
 # MinGW has no O_NOFOLLOW; the flag is only a host build workaround.
@@ -39,9 +46,19 @@ for src in "$ROOT"/third_party/zlib/src/*.c "$ROOT"/third_party/minizip-ng/src/*
    "${MZ_CFLAGS[@]}" "${extra[@]}" -o "$BUILD/$name.o" "$src"
 done

-# dmc_unrar (single-file; uses stdio fopen by default on non-Windows)
-"$CC" -c -O2 -w "${RAR_CFLAGS[@]}" \
-  -o "$BUILD/dmc_unrar.o" "$ROOT/third_party/unrar/dmc_unrar.c"
+# unrar 7.20.1 (RARDLL source set; compiled with the host C++ compiler).
+UNRAR7_SRCS="$ROOT/third_party/unrar7"
+UNRAR7_CFLAGS=(-O2 -w -std=c++17 -DRARDLL -D_FILE_OFFSET_BITS=64 -D_LARGEFILE_SOURCE)
+CXX="${CXX:-g++}"
+for src in \
+  archive arcread blake2s cmddata consio crc crypt dll encname errhnd extinfo \
+  extract filcreat file filefn filestr find getbits global hash headers isnt \
+  largepage match motw options pathfn qopen rar rarpch rarvm rawread rdwrfn \
+  rijndael rs rs16 scantree secpassword sha1 sha256 smallfn strfn strlist \
+  system threadpool timefn ui unicode unpack volume; do
+  "$CXX" -c "${UNRAR7_CFLAGS[@]}" -o "$BUILD/unrar7_$src.o" \
+    "$UNRAR7_SRCS/$src.cpp" || exit 1
+done

 COMPAT_INC="$ROOT/tests/compat"

@@ -51,9 +68,24 @@ COMPAT_INC="$ROOT/tests/compat"
  -include "$ROOT/tests/posix_compat.h" \
  -o "$BUILD/zip_extract.o" "$ROOT/src/zip_extract.c"

+# Format-independent helpers (limits profiles + status string) live here.
+"$CC" -c -O2 -Wall -Wextra -Wno-unused-parameter -I"$ROOT/src" \
+  -I"$COMPAT_INC" -include "$ROOT/tests/posix_compat.h" \
+  -o "$BUILD/zipx_common.o" "$ROOT/src/zipx_common.c"
+
+# Volume support: the concatenating stream and the volume set detector.
 "$CC" -c -O2 -Wall -Wextra -Wno-unused-parameter \
  -I"$ROOT/third_party/minizip-ng/include" -I"$ROOT/src" -I"$COMPAT_INC" \
-  "${RAR_CFLAGS[@]}" -include "$ROOT/tests/posix_compat.h" \
+  -include "$ROOT/tests/posix_compat.h" \
+  -o "$BUILD/zipx_volstream.o" "$ROOT/src/zipx_volstream.c"
+
+"$CC" -c -O2 -Wall -Wextra -Wno-unused-parameter -I"$ROOT/src" \
+  -I"$COMPAT_INC" -include "$ROOT/tests/posix_compat.h" \
+  -o "$BUILD/zipx_volume.o" "$ROOT/src/zipx_volume.c"
+
+"$CC" -c -O2 -Wall -Wextra -Wno-unused-parameter \
+  -I"$ROOT/third_party/minizip-ng/include" -I"$ROOT/third_party/unrar7" -I"$ROOT/src" -I"$COMPAT_INC" \
+  -include "$ROOT/tests/posix_compat.h" \
  -o "$BUILD/rar_extract.o" "$ROOT/src/rar_extract.c"

 "$CC" -c -O2 -Wall -Wextra -Wno-unused-parameter -I"$ROOT/src" \
@@ -61,23 +93,35 @@ COMPAT_INC="$ROOT/tests/compat"
  -o "$BUILD/test_zip_extract.o" "$ROOT/tests/test_zip_extract.c"

 "$CC" -c -O2 -Wall -Wextra -Wno-unused-parameter -I"$ROOT/src" \
-  -I"$COMPAT_INC" "${RAR_CFLAGS[@]}" -include "$ROOT/tests/posix_compat.h" \
+  -I"$COMPAT_INC" -include "$ROOT/tests/posix_compat.h" \
  -o "$BUILD/test_rar_extract.o" "$ROOT/tests/test_rar_extract.c"

 objs=()
+rar_objs=()
 for obj in "$BUILD"/*.o; do
  case "$obj" in
-    */zip_extract.o|*/rar_extract.o|*/test_zip_extract.o|*/test_rar_extract.o) continue ;;
+    */zip_extract.o|*/zipx_common.o|*/rar_extract.o|*/test_zip_extract.o|*/test_rar_extract.o) continue ;;
+    */unrar7_*.o) rar_objs+=("$obj"); continue ;;
  esac
  objs+=("$obj")
 done

 "$CC" -O2 -o "$BUILD/test-zip-extract" \
-  "$BUILD/zip_extract.o" "$BUILD/test_zip_extract.o" "${objs[@]}"
+  "$BUILD/zip_extract.o" "$BUILD/zipx_common.o" "$BUILD/test_zip_extract.o" "${objs[@]}"

-"$CC" -O2 -o "$BUILD/test-rar-extract" \
+# The RAR test links the unrar7 objects, so it needs the C++ driver.
+# Windows unrar system.cpp references SetSuspendState (PowrProf).
+RAR_LIBS=()
+[ "$HOST_KIND" = windows ] && RAR_LIBS=(-lpowrprof)
+"$CXX" -O2 -o "$BUILD/test-rar-extract" \
  "$BUILD/rar_extract.o" "$BUILD/test_rar_extract.o" \
-  "$BUILD/zip_extract.o" "${objs[@]}"
+  "$BUILD/zip_extract.o" "$BUILD/zipx_common.o" "${objs[@]}" "${rar_objs[@]}" "${RAR_LIBS[@]}"

-"$BUILD/test-zip-extract" "$ROOT/tests/fixtures" "$BUILD/work-zip"
-"$BUILD/test-rar-extract" "$ROOT/tests/fixtures" "$BUILD/work-rar"
+# Real archives live in fixtures-real/, generated by tests/make-rar-fixtures.bat
+# (WinRAR) and tests/make-zip-enc-fixtures.bat (7-Zip); fixtures/ itself is
+# wiped by make_fixtures.py on every run. The ZIP suite needs it for the
+# encrypted samples, and skips those sections when the directory is missing.
+"$BUILD/test-zip-extract" "$ROOT/tests/fixtures" "$BUILD/work-zip" \
+  "$ROOT/tests/fixtures-real"
+"$BUILD/test-rar-extract" "$ROOT/tests/fixtures" "$BUILD/work-rar" \
+  "$ROOT/tests/fixtures-real"
@@ -0,0 +1,526 @@
+/*
+ * End-to-end driver for the project's own 7z folder decoder (src/sevenz_chain.c).
+ *
+ *   sevenz_chain_e2e <archive.7z> <out-dir>
+ *
+ * Unlike tests/sevenz_e2e.c -- which drives the LZMA SDK's own CSzFolder based
+ * path and therefore cannot handle BCJ2 or anything else the SDK caps at four
+ * coders -- this one decodes *every* folder through src/sevenz_chain.c.
+ *
+ * It also mirrors the shape of the real extraction path: each folder is
+ * decoded once, streamed to a sink, and the sink splits the byte stream across
+ * the entries that live in that folder (that is what makes an archive solid).
+ * Per-entry and per-folder CRCs are verified as the bytes go past.
+ *
+ * Exit status is non-zero if any folder or entry failed.
+ */
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/stat.h>
+
+#if defined(_WIN32)
+#include <direct.h>
+#include <wchar.h>
+#else
+#include <unistd.h>
+#endif
+
+#include "7z.h"
+#include "7zAlloc.h"
+#include "7zCrc.h"
+#include "7zFile.h"
+
+#include "sevenz_chain.h"
+#include "sevenz_header.h"
+#include "sevenz_volstream.h"
+
+#define INPUT_BUF_SIZE (1u << 18)
+#define MAX_PATH_LEN 4096
+
+static ISzAlloc g_alloc = { SzAlloc, SzFree };
+static ISzAlloc g_temp = { SzAlloc, SzFree };
+
+static int g_failures = 0;
+
+/* ---------------------------------------------------------------- paths */
+
+#if defined(_WIN32)
+
+static void utf8_to_utf16(const char *src, wchar_t *dst, size_t cap) {
+  size_t out = 0;
+
+  while(*src && out + 2 < cap) {
+    unsigned char c = (unsigned char)*src++;
+    UInt32 cp;
+
+    if(c < 0x80) {
+      cp = c;
+    } else if((c & 0xE0) == 0xC0 && (src[0] & 0xC0) == 0x80) {
+      cp = ((UInt32)(c & 0x1F) << 6) | (UInt32)(*src++ & 0x3F);
+    } else if((c & 0xF0) == 0xE0 && (src[0] & 0xC0) == 0x80 &&
+              (src[1] & 0xC0) == 0x80) {
+      cp = ((UInt32)(c & 0x0F) << 12) | ((UInt32)(src[0] & 0x3F) << 6) |
+           (UInt32)(src[1] & 0x3F);
+      src += 2;
+    } else if((c & 0xF8) == 0xF0 && (src[0] & 0xC0) == 0x80 &&
+              (src[1] & 0xC0) == 0x80 && (src[2] & 0xC0) == 0x80) {
+      cp = ((UInt32)(c & 0x07) << 18) | ((UInt32)(src[0] & 0x3F) << 12) |
+           ((UInt32)(src[1] & 0x3F) << 6) | (UInt32)(src[2] & 0x3F);
+      src += 3;
+    } else {
+      cp = '?';
+    }
+
+    if(cp >= 0x10000) {
+      cp -= 0x10000;
+      dst[out++] = (wchar_t)(0xD800 | (cp >> 10));
+      dst[out++] = (wchar_t)(0xDC00 | (cp & 0x3FF));
+    } else {
+      dst[out++] = (wchar_t)cp;
+    }
+  }
+  dst[out] = 0;
+}
+
+static void path_mkdir(const char *path) {
+  wchar_t wide[MAX_PATH_LEN];
+  utf8_to_utf16(path, wide, MAX_PATH_LEN);
+  _wmkdir(wide);
+}
+
+static FILE *path_fopen_write(const char *path) {
+  wchar_t wide[MAX_PATH_LEN];
+  utf8_to_utf16(path, wide, MAX_PATH_LEN);
+  return _wfopen(wide, L"wb");
+}
+
+#else
+
+static void path_mkdir(const char *path) { mkdir(path, 0755); }
+static FILE *path_fopen_write(const char *path) { return fopen(path, "wb"); }
+
+#endif
+
+static void make_dirs(const char *path) {
+  char tmp[MAX_PATH_LEN];
+  size_t i, n = strlen(path);
+
+  if(n + 1 > sizeof(tmp)) return;
+  memcpy(tmp, path, n + 1);
+
+  for(i = 1; i < n; i++) {
+    if(tmp[i] == '/' || tmp[i] == '\\') {
+      char c = tmp[i];
+      tmp[i] = 0;
+      path_mkdir(tmp);
+      tmp[i] = c;
+    }
+  }
+  path_mkdir(tmp);
+}
+
+/* UTF-16 (LE, as stored by the 7z name table) to UTF-8. */
+static void utf16_to_utf8(const UInt16 *src, char *dst, size_t dst_size) {
+  size_t out = 0;
+
+  while(*src) {
+    UInt32 c = *src++;
+
+    if(c >= 0xD800 && c <= 0xDBFF && *src >= 0xDC00 && *src <= 0xDFFF)
+      c = 0x10000 + ((c - 0xD800) << 10) + (*src++ - 0xDC00);
+    if(out + 5 >= dst_size) break;
+
+    if(c < 0x80) {
+      dst[out++] = (char)c;
+    } else if(c < 0x800) {
+      dst[out++] = (char)(0xC0 | (c >> 6));
+      dst[out++] = (char)(0x80 | (c & 0x3F));
+    } else if(c < 0x10000) {
+      dst[out++] = (char)(0xE0 | (c >> 12));
+      dst[out++] = (char)(0x80 | ((c >> 6) & 0x3F));
+      dst[out++] = (char)(0x80 | (c & 0x3F));
+    } else {
+      dst[out++] = (char)(0xF0 | (c >> 18));
+      dst[out++] = (char)(0x80 | ((c >> 12) & 0x3F));
+      dst[out++] = (char)(0x80 | ((c >> 6) & 0x3F));
+      dst[out++] = (char)(0x80 | (c & 0x3F));
+    }
+  }
+  dst[out] = 0;
+}
+
+/* --------------------------------------------------------------- reader */
+
+typedef struct {
+  ISeekInStream *stream;
+  UInt64 base; /* db.dataPos: packed offsets are relative to it */
+} reader_ctx;
+
+static int reader_at(void *ctx, uint64_t offset, void *dst, size_t size) {
+  reader_ctx *r = (reader_ctx *)ctx;
+  Int64 pos = (Int64)(r->base + offset);
+  size_t done = 0;
+
+  if(r->stream->Seek(r->stream, &pos, SZ_SEEK_SET) != SZ_OK) return -1;
+  while(done < size) {
+    size_t want = size - done;
+    if(r->stream->Read(r->stream, (Byte *)dst + done, &want) != SZ_OK) return -1;
+    if(want == 0) return -1;
+    done += want;
+  }
+  return 0;
+}
+
+/* ------------------------------------------------------ folder -> sink */
+
+typedef struct {
+  UInt32 file_index;
+  uint64_t size;
+} plan_entry;
+
+typedef struct {
+  const CSzArEx *db;
+  char out_dir[MAX_PATH_LEN];
+  char name[MAX_PATH_LEN];
+
+  plan_entry *plan;
+  size_t plan_len;
+  size_t plan_pos;
+  uint64_t written;
+  FILE *fh;
+
+  uint32_t entry_crc;
+  uint64_t bytes_total;
+  uint64_t bytes_ok;
+  int failures;
+} sink_ctx;
+
+static void plan_free(sink_ctx *s) {
+  free(s->plan);
+  s->plan = NULL;
+  s->plan_len = s->plan_pos = 0;
+}
+
+/* Builds the ordered list of non-empty entries living in folder `folder`. */
+static int plan_build(sink_ctx *s, UInt32 folder, sz_chain_err_t *cerr) {
+  const CSzArEx *db = s->db;
+  UInt32 first = db->FolderToFile[folder];
+  UInt32 last = db->FolderToFile[(size_t)folder + 1];
+  UInt32 i;
+
+  plan_free(s);
+  /* A folder that failed mid-entry leaves `written` pointing into an entry it
+     never finished; carrying that into the next folder makes every later entry
+     look "already part written" and produces a cascade of bogus failures. */
+  s->written = 0;
+  if(last <= first) return 0;
+  s->plan = (plan_entry *)malloc(sizeof(plan_entry) * (size_t)(last - first));
+  if(!s->plan) return -1;
+
+  for(i = first; i < last; i++) {
+    UInt64 size = db->UnpackPositions[(size_t)i + 1] - db->UnpackPositions[i];
+    if(db->FileToFolder[i] != folder) continue;
+    if(size == 0) continue;
+    s->plan[s->plan_len].file_index = i;
+    s->plan[s->plan_len].size = (uint64_t)size;
+    s->plan_len++;
+  }
+  return 0;
+}
+
+static void sink_close_entry(sink_ctx *s) {
+  if(s->fh) {
+    fclose(s->fh);
+    s->fh = NULL;
+  }
+}
+
+static int sink_open_entry(sink_ctx *s, UInt32 file_index) {
+  const CSzArEx *db = s->db;
+  UInt16 *name16 = NULL;
+  size_t len = SzArEx_GetFileNameUtf16(db, file_index, NULL);
+  char rel[MAX_PATH_LEN];
+  char full[MAX_PATH_LEN];
+  char *slash;
+
+  name16 = (UInt16 *)malloc((len + 1) * sizeof(UInt16));
+  if(!name16) return -1;
+  SzArEx_GetFileNameUtf16(db, file_index, name16);
+  utf16_to_utf8(name16, rel, sizeof(rel));
+  free(name16);
+
+  if(snprintf(full, sizeof(full), "%s/%s", s->out_dir, rel) >=
+     (int)sizeof(full)) {
+    printf("  FAIL (path too long) %s\n", rel);
+    return -1;
+  }
+  slash = strrchr(full, '/');
+  if(slash) {
+    *slash = 0;
+    make_dirs(full);
+    *slash = '/';
+  }
+  s->fh = path_fopen_write(full);
+  if(!s->fh) {
+    printf("  FAIL (cannot create) %s\n", rel);
+    return -1;
+  }
+  s->entry_crc = CRC_INIT_VAL;
+  return 0;
+}
+
+static int sink_write(void *ctx, const void *data, size_t size) {
+  sink_ctx *s = (sink_ctx *)ctx;
+  const Byte *p = (const Byte *)data;
+
+  while(size > 0) {
+    plan_entry *e;
+    uint64_t remain;
+    size_t take;
+    char rel[MAX_PATH_LEN];
+
+    if(s->plan_pos >= s->plan_len) {
+      printf("  FAIL folder produced %llu bytes more than its entries hold\n",
+             (unsigned long long)size);
+      s->failures++;
+      return -1;
+    }
+    e = &s->plan[s->plan_pos];
+    remain = e->size - s->written;
+    take = (size_t)((uint64_t)size < remain ? (uint64_t)size : remain);
+
+    if(!s->fh) {
+      if(sink_open_entry(s, e->file_index) != 0) {
+        s->failures++;
+        return -1;
+      }
+    }
+    if(take && fwrite(p, 1, take, s->fh) != take) {
+      printf("  FAIL (write error)\n");
+      s->failures++;
+      return -1;
+    }
+    s->entry_crc = CrcUpdate(s->entry_crc, p, take);
+    s->written += take;
+    s->bytes_total += take;
+    p += take;
+    size -= take;
+
+    if(s->written == e->size) {
+      UInt16 *name16;
+      size_t len;
+      sink_close_entry(s);
+      len = SzArEx_GetFileNameUtf16(s->db, e->file_index, NULL);
+      name16 = (UInt16 *)malloc((len + 1) * sizeof(UInt16));
+      if(name16) {
+        SzArEx_GetFileNameUtf16(s->db, e->file_index, name16);
+        utf16_to_utf8(name16, rel, sizeof(rel));
+        free(name16);
+        if(SzBitWithVals_Check(&s->db->CRCs, e->file_index) &&
+           CRC_GET_DIGEST(s->entry_crc) != s->db->CRCs.Vals[e->file_index]) {
+          printf("  FAIL %s (crc mismatch)\n", rel);
+          s->failures++;
+          return -1;
+        }
+      }
+      s->bytes_ok += e->size;
+      s->plan_pos++;
+      s->written = 0;
+    }
+  }
+  return 0;
+}
+
+/* ------------------------------------------------------------------ main */
+
+int main(int argc, char **argv) {
+  CLookToRead2 look_stream;
+  CSzArEx db;
+  SRes res;
+  UInt32 folder;
+  reader_ctx reader;
+  sink_ctx sink;
+  sevenz_volstream *vol = NULL;
+  char *vol_err = NULL;
+  char vol_desc[512];
+  int is_set = 0;
+  int rc = 0;
+  szh_prep *hdr_prep = NULL;
+  ISeekInStream *hdr_stream = NULL;
+  char hdr_msg[256] = "";
+
+  if(argc < 3) {
+    fprintf(stderr, "usage: %s <archive.7z> <out-dir> [password]\n", argv[0]);
+    return 2;
+  }
+
+  if(sevenz_volstream_open(&vol, argv[1], &is_set, &vol_err) != 0) {
+    fprintf(stderr, "%s\n", vol_err ? vol_err : "cannot open the archive");
+    free(vol_err);
+    return 1;
+  }
+  sevenz_volstream_describe(vol, vol_desc, sizeof(vol_desc));
+
+  LookToRead2_CreateVTable(&look_stream, 0);
+  look_stream.buf = (Byte *)ISzAlloc_Alloc(&g_alloc, INPUT_BUF_SIZE);
+  if(!look_stream.buf) {
+    fprintf(stderr, "out of memory\n");
+    sevenz_volstream_free(vol);
+    return 1;
+  }
+  look_stream.bufSize = INPUT_BUF_SIZE;
+
+  /* Same order as src/sevenz_extract.c: an encrypted header has to come off
+     before the SDK can see the folder table. */
+  hdr_stream = sevenz_volstream_stream(vol);
+  {
+    szh_status_t hs = szh_prepare(&hdr_prep, hdr_stream,
+                                  argc > 3 ? argv[3] : NULL, hdr_msg,
+                                  sizeof(hdr_msg));
+
+    if(hs == SZH_PATCHED) {
+      hdr_stream = szh_stream(hdr_prep);
+    } else if(hs != SZH_PLAIN) {
+      fprintf(stderr, "%s: %s\n", vol_desc,
+              hdr_msg[0] ? hdr_msg : szh_status_string(hs));
+      szh_prep_free(hdr_prep);
+      sevenz_volstream_free(vol);
+      return 1;
+    }
+  }
+  look_stream.realStream = hdr_stream;
+  LookToRead2_INIT(&look_stream)
+  {
+    Int64 zero = 0;
+
+    if(hdr_stream->Seek(hdr_stream, &zero, SZ_SEEK_SET) != SZ_OK) {
+      fprintf(stderr, "%s: cannot rewind the archive\n", vol_desc);
+      szh_prep_free(hdr_prep);
+      sevenz_volstream_free(vol);
+      return 1;
+    }
+  }
+
+  CrcGenerateTable();
+  SzArEx_Init(&db);
+
+  res = SzArEx_Open(&db, &look_stream.vt, &g_alloc, &g_temp);
+  /* The header is in `db` now; nothing reads through the view again. */
+  szh_prep_free(hdr_prep);
+  hdr_prep = NULL;
+  if(res != SZ_OK) {
+    if(res == SZ_ERROR_UNSUPPORTED)
+      fprintf(stderr,
+              "%s: the archive header is compressed with a method this build "
+              "does not have\n",
+              vol_desc);
+    else
+      fprintf(stderr, "%s: cannot read the 7z header (res=%d)\n", vol_desc,
+              (int)res);
+    sevenz_volstream_free(vol);
+    return 1;
+  }
+
+  printf("archive: %s, %llu bytes, entries: %u, folders: %u, packed streams: %u\n",
+         vol_desc, (unsigned long long)sevenz_volstream_size(vol),
+         (unsigned)db.NumFiles, (unsigned)db.db.NumFolders,
+         (unsigned)db.db.NumPackStreams);
+
+  memset(&sink, 0, sizeof(sink));
+  sink.db = &db;
+  snprintf(sink.out_dir, sizeof(sink.out_dir), "%s", argv[2]);
+
+  reader.stream = sevenz_volstream_stream(vol);
+  reader.base = db.dataPos;
+
+  for(folder = 0; folder < db.db.NumFolders; folder++) {
+    const UInt32 pack_first = db.db.FoStartPackStreamIndex[folder];
+    const UInt32 pack_count = db.db.FoStartPackStreamIndex[(size_t)folder + 1] -
+                              pack_first;
+    uint64_t pack_positions[SZ_CHAIN_MAX_STREAMS + 1];
+    sz_chain *chain = NULL;
+    sz_chain_err_t cerr;
+    char desc[256];
+    uint32_t folder_crc = 0;
+    UInt32 k;
+    uint64_t unpack_size = SzAr_GetFolderUnpackSize(&db.db, folder);
+    const uint8_t *blob = db.db.CodersData + db.db.FoCodersOffsets[folder];
+    size_t blob_size = db.db.FoCodersOffsets[(size_t)folder + 1] -
+                       db.db.FoCodersOffsets[folder];
+    const uint64_t *cu =
+        &db.db.CoderUnpackSizes[db.db.FoToCoderUnpackSizes[folder]];
+
+    for(k = 0; k <= pack_count; k++)
+      pack_positions[k] = db.db.PackPositions[pack_first + k];
+
+    sink.bytes_total = 0;
+    sink.bytes_ok = 0;
+    if(plan_build(&sink, folder, &cerr) != 0) {
+      fprintf(stderr, "folder %u: cannot build the entry plan\n",
+              (unsigned)folder);
+      rc = 1;
+      continue;
+    }
+
+    if(sz_chain_parse(&chain, blob, blob_size, pack_positions, pack_count, cu,
+                      unpack_size, sz_chain_default_limits(), &cerr) != 0) {
+      printf("folder %-2u FAIL parse: %s: %s\n", (unsigned)folder,
+             sz_chain_status_string(cerr.status), cerr.message);
+      g_failures++;
+      rc = 1;
+      plan_free(&sink);
+      continue;
+    }
+    sz_chain_describe(chain, desc, sizeof(desc));
+
+    {
+      sz_chain_err_t derr;
+      if(sz_chain_decode(chain, reader_at, &reader, sink_write, &sink, NULL,
+                         NULL, argc > 3 ? argv[3] : NULL, &folder_crc,
+                         &derr) != 0) {
+        printf("folder %-2u FAIL decode [%s]: %s: %s (offset %llu)\n",
+               (unsigned)folder, desc, sz_chain_status_string(derr.status),
+               derr.message, (unsigned long long)derr.offset);
+        g_failures++;
+        rc = 1;
+      } else if(sink.bytes_total != unpack_size) {
+        printf("folder %-2u FAIL size: %llu decoded, %llu declared\n",
+               (unsigned)folder, (unsigned long long)sink.bytes_total,
+               (unsigned long long)unpack_size);
+        g_failures++;
+        rc = 1;
+      } else if(SzBitWithVals_Check(&db.db.FolderCRCs, folder) &&
+                folder_crc != db.db.FolderCRCs.Vals[folder]) {
+        printf("folder %-2u FAIL crc: got %08X, expected %08X\n",
+               (unsigned)folder, (unsigned)folder_crc,
+               (unsigned)db.db.FolderCRCs.Vals[folder]);
+        g_failures++;
+        rc = 1;
+      } else {
+        printf("folder %-2u ok   [%s] %llu bytes, %u entr%s\n",
+               (unsigned)folder, desc, (unsigned long long)sink.bytes_total,
+               (unsigned)sink.plan_len, sink.plan_len == 1 ? "y" : "ies");
+      }
+    }
+
+    if(sink.plan_pos != sink.plan_len) {
+      printf("folder %-2u FAIL only %u of %u entries were produced\n",
+             (unsigned)folder, (unsigned)sink.plan_pos,
+             (unsigned)sink.plan_len);
+      g_failures++;
+      rc = 1;
+    }
+    sink_close_entry(&sink);
+    sz_chain_free(chain);
+    plan_free(&sink);
+  }
+
+  ISzAlloc_Free(&g_alloc, look_stream.buf);
+  SzArEx_Free(&db, &g_alloc);
+  sevenz_volstream_free(vol);
+
+  printf("%s: %d failure(s)\n", argv[1], g_failures);
+  return rc ? 1 : 0;
+}
@@ -0,0 +1,302 @@
+/*
+ * Standalone 7z driver for host end-to-end checks.
+ *
+ *   sevenz_e2e <archive.7z> <out-dir>
+ *
+ * Lists every entry, extracts the archive into <out-dir> and prints the
+ * per-entry result.  Exit status is non-zero if any entry fails.
+ *
+ * This is a *diagnostic* tool: it exercises the same container layer as the
+ * real extraction path, so it is the quickest way to tell whether a failure
+ * comes from the container/codec layer or from the web server around it.
+ *
+ * Entry names are UTF-16 inside a 7z archive; on a Windows host the file APIs
+ * must therefore be called with the wide-character variants or non-ASCII names
+ * silently fail to be created.
+ */
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/stat.h>
+
+#if defined(_WIN32)
+#include <direct.h>
+#include <wchar.h>
+#else
+#include <unistd.h>
+#endif
+
+#include "7z.h"
+#include "7zAlloc.h"
+#include "7zCrc.h"
+#include "7zFile.h"
+
+#define INPUT_BUF_SIZE (1u << 18)
+#define MAX_PATH_LEN 4096
+
+static ISzAlloc g_alloc = { SzAlloc, SzFree };
+static ISzAlloc g_temp = { SzAlloc, SzFree };
+
+static int g_failures = 0;
+
+/* ---------------------------------------------------------------- paths */
+
+#if defined(_WIN32)
+
+/* MinGW's wchar_t is 16 bit, matching UTF-16. */
+static void utf8_to_utf16(const char *src, wchar_t *dst, size_t cap)
+{
+  size_t out = 0;
+
+  while (*src && out + 2 < cap) {
+    unsigned char c = (unsigned char)*src++;
+    UInt32 cp;
+
+    if (c < 0x80) {
+      cp = c;
+    } else if ((c & 0xE0) == 0xC0 && (src[0] & 0xC0) == 0x80) {
+      cp = ((UInt32)(c & 0x1F) << 6) | (UInt32)(*src++ & 0x3F);
+    } else if ((c & 0xF0) == 0xE0 && (src[0] & 0xC0) == 0x80 && (src[1] & 0xC0) == 0x80) {
+      cp = ((UInt32)(c & 0x0F) << 12) | ((UInt32)(src[0] & 0x3F) << 6) | (UInt32)(src[1] & 0x3F);
+      src += 2;
+    } else if ((c & 0xF8) == 0xF0 && (src[0] & 0xC0) == 0x80 && (src[1] & 0xC0) == 0x80 && (src[2] & 0xC0) == 0x80) {
+      cp = ((UInt32)(c & 0x07) << 18) | ((UInt32)(src[0] & 0x3F) << 12) |
+           ((UInt32)(src[1] & 0x3F) << 6) | (UInt32)(src[2] & 0x3F);
+      src += 3;
+    } else {
+      cp = '?';
+    }
+
+    if (cp >= 0x10000) {
+      cp -= 0x10000;
+      dst[out++] = (wchar_t)(0xD800 | (cp >> 10));
+      dst[out++] = (wchar_t)(0xDC00 | (cp & 0x3FF));
+    } else {
+      dst[out++] = (wchar_t)cp;
+    }
+  }
+  dst[out] = 0;
+}
+
+static void path_mkdir(const char *path)
+{
+  wchar_t wide[MAX_PATH_LEN];
+  utf8_to_utf16(path, wide, MAX_PATH_LEN);
+  _wmkdir(wide);
+}
+
+static FILE *path_fopen_write(const char *path)
+{
+  wchar_t wide[MAX_PATH_LEN];
+  utf8_to_utf16(path, wide, MAX_PATH_LEN);
+  return _wfopen(wide, L"wb");
+}
+
+#else /* POSIX: byte paths are UTF-8 already */
+
+static void path_mkdir(const char *path) { mkdir(path, 0755); }
+static FILE *path_fopen_write(const char *path) { return fopen(path, "wb"); }
+
+#endif
+
+static void make_dirs(const char *path)
+{
+  char tmp[MAX_PATH_LEN];
+  size_t i, n = strlen(path);
+
+  if (n + 1 > sizeof(tmp))
+    return;
+  memcpy(tmp, path, n + 1);
+
+  for (i = 1; i < n; i++) {
+    if (tmp[i] == '/' || tmp[i] == '\\') {
+      char c = tmp[i];
+      tmp[i] = 0;
+      path_mkdir(tmp);
+      tmp[i] = c;
+    }
+  }
+  /* The final component counts too: callers hand us either a directory entry
+     or the parent directory of a file. */
+  path_mkdir(tmp);
+}
+
+static int write_file(const char *path, const Byte *data, size_t size)
+{
+  FILE *fh = path_fopen_write(path);
+  if (!fh)
+    return -1;
+  if (size && fwrite(data, 1, size, fh) != size) {
+    fclose(fh);
+    return -1;
+  }
+  return fclose(fh) == 0 ? 0 : -1;
+}
+
+/* UTF-16 (LE, as stored by the 7z name table) to UTF-8. */
+static void utf16_to_utf8(const UInt16 *src, char *dst, size_t dst_size)
+{
+  size_t out = 0;
+
+  while (*src) {
+    UInt32 c = *src++;
+
+    if (c >= 0xD800 && c <= 0xDBFF && *src >= 0xDC00 && *src <= 0xDFFF)
+      c = 0x10000 + ((c - 0xD800) << 10) + (*src++ - 0xDC00);
+
+    if (out + 5 >= dst_size)
+      break;
+
+    if (c < 0x80) {
+      dst[out++] = (char)c;
+    } else if (c < 0x800) {
+      dst[out++] = (char)(0xC0 | (c >> 6));
+      dst[out++] = (char)(0x80 | (c & 0x3F));
+    } else if (c < 0x10000) {
+      dst[out++] = (char)(0xE0 | (c >> 12));
+      dst[out++] = (char)(0x80 | ((c >> 6) & 0x3F));
+      dst[out++] = (char)(0x80 | (c & 0x3F));
+    } else {
+      dst[out++] = (char)(0xF0 | (c >> 18));
+      dst[out++] = (char)(0x80 | ((c >> 12) & 0x3F));
+      dst[out++] = (char)(0x80 | ((c >> 6) & 0x3F));
+      dst[out++] = (char)(0x80 | (c & 0x3F));
+    }
+  }
+  dst[out] = 0;
+}
+
+/* ---------------------------------------------------------------- main */
+
+int main(int argc, char **argv)
+{
+  CFileInStream archive_stream;
+  CLookToRead2 look_stream;
+  CSzArEx db;
+  SRes res;
+  UInt16 *name16 = NULL;
+  size_t name16_cap = 0;
+  UInt32 i;
+  UInt32 block_index = 0xFFFFFFFF;
+  Byte *out_buffer = NULL;
+  size_t out_buffer_size = 0;
+  const char *out_dir;
+
+  if (argc < 3) {
+    fprintf(stderr, "usage: %s <archive.7z> <out-dir>\n", argv[0]);
+    return 2;
+  }
+  out_dir = argv[2];
+
+  if (InFile_Open(&archive_stream.file, argv[1]) != 0) {
+    fprintf(stderr, "cannot open %s\n", argv[1]);
+    return 1;
+  }
+  FileInStream_CreateVTable(&archive_stream);
+  archive_stream.wres = 0;
+
+  LookToRead2_CreateVTable(&look_stream, 0);
+  look_stream.buf = (Byte *)ISzAlloc_Alloc(&g_alloc, INPUT_BUF_SIZE);
+  if (!look_stream.buf) {
+    fprintf(stderr, "out of memory\n");
+    return 1;
+  }
+  look_stream.bufSize = INPUT_BUF_SIZE;
+  look_stream.realStream = &archive_stream.vt;
+  LookToRead2_INIT(&look_stream)
+
+  CrcGenerateTable();
+  SzArEx_Init(&db);
+
+  res = SzArEx_Open(&db, &look_stream.vt, &g_alloc, &g_temp);
+  if (res != SZ_OK) {
+    fprintf(stderr, "SzArEx_Open failed: res=%d\n", (int)res);
+    if (res == SZ_ERROR_UNSUPPORTED)
+      fprintf(stderr, "  (unsupported coder - encrypted header or exotic method)\n");
+    return 1;
+  }
+
+  printf("entries: %u\n", (unsigned)db.NumFiles);
+
+  for (i = 0; i < db.NumFiles; i++) {
+    const int is_dir = SzArEx_IsDir(&db, i);
+    const size_t len = SzArEx_GetFileNameUtf16(&db, i, NULL);
+    char rel[MAX_PATH_LEN];
+    char full[MAX_PATH_LEN];
+    size_t offset = 0;
+    size_t processed = 0;
+
+    if (len + 1 > name16_cap) {
+      UInt16 *grown = (UInt16 *)realloc(name16, (len + 1) * sizeof(UInt16));
+      if (!grown) {
+        fprintf(stderr, "out of memory\n");
+        return 1;
+      }
+      name16 = grown;
+      name16_cap = len + 1;
+    }
+    SzArEx_GetFileNameUtf16(&db, i, name16);
+    utf16_to_utf8(name16, rel, sizeof(rel));
+
+    if (snprintf(full, sizeof(full), "%s/%s", out_dir, rel) >= (int)sizeof(full)) {
+      printf("  SKIP (path too long) %s\n", rel);
+      g_failures++;
+      continue;
+    }
+
+    if (is_dir) {
+      make_dirs(full);
+      printf("  dir  %s\n", rel);
+      continue;
+    }
+
+    res = SzArEx_Extract(&db, &look_stream.vt, i, &block_index, &out_buffer,
+                         &out_buffer_size, &offset, &processed, &g_alloc, &g_temp);
+    if (res != SZ_OK) {
+      printf("  FAIL %s (res=%d)\n", rel, (int)res);
+      g_failures++;
+      /* SzArEx_Extract leaves the block cache primed with a half-decoded
+         buffer when the folder decode fails; drop it so the next entry
+         reports its own error instead of a bogus CRC mismatch. */
+      block_index = 0xFFFFFFFF;
+      continue;
+    }
+
+    {
+      char *slash = strrchr(full, '/');
+      if (slash) {
+        *slash = 0;
+        make_dirs(full);
+        *slash = '/';
+      }
+    }
+    if (write_file(full, out_buffer + offset, processed) != 0) {
+      printf("  FAIL %s (write error)\n", rel);
+      g_failures++;
+      continue;
+    }
+
+    {
+      UInt32 crc = 0;
+      if (SzBitWithVals_Check(&db.CRCs, i)) {
+        crc = CrcCalc(out_buffer + offset, processed);
+        if (crc != db.CRCs.Vals[i]) {
+          printf("  FAIL %s (crc mismatch)\n", rel);
+          g_failures++;
+          continue;
+        }
+      }
+    }
+    printf("  ok   %s (%lu bytes)\n", rel, (unsigned long)processed);
+  }
+
+  ISzAlloc_Free(&g_alloc, out_buffer);
+  ISzAlloc_Free(&g_alloc, look_stream.buf);
+  SzArEx_Free(&db, &g_alloc);
+  File_Close(&archive_stream.file);
+  free(name16);
+
+  printf("%s: %d failure(s)\n", argv[1], g_failures);
+  return g_failures ? 1 : 0;
+}
@@ -1,18 +1,18 @@
 /* Host test suite for the RAR extraction engine.
   Build: see run-tests.sh (uses gcc + the MinGW POSIX shim).

-   Scope (v1.8):
-     * Pure error-path coverage — we do not ship a genuine RAR fixture
-       because no rar/7z writer is available in the sandboxed host test
-       environment. The test suite therefore focuses on the negative
-       branches that the dispatcher hits when a user uploads something
-       that is not a valid single-volume, unencrypted RAR.
-     * Happy-path smoke coverage is provided by make_fixtures.py when a
-       rar or 7z binary is available; if neither is present, the script
-       writes 1-byte placeholder files so that test_rar_extract.c still
-       has something to point at for the "format rejected" assertions.
-     * See docs/HANDOVER.md for the manual smoke procedure and the
-       fixture TODO that should be cleared when opello/unrar is vendored. */
+   Scope (v1.9):
+     * Negative paths: the dispatcher must classify garbage, truncated and
+       non-archive input without ever returning ZIPX_OK. These fixtures are
+       generated on the fly, so this part runs anywhere.
+     * Real-archive coverage: RAR5 "v6", RAR4, multi-volume and encrypted
+       samples live in tests/fixtures-real/ and are regenerated by
+       tests/make-rar-fixtures.bat (needs WinRAR). Those sections skip
+       themselves when the directory is missing.
+     * Encrypted archives are exercised end to end: no password and a wrong
+       password must both yield ZIPX_ERR_PASSWORD with nothing published,
+       and the correct password must actually decrypt the payload. The
+       password for enc-v6.rar is fixed by make-rar-fixtures.bat. */

 #include "../src/zip_extract.h"
 #include "../src/rar_extract.h"
@@ -28,15 +28,39 @@
 #include "posix_compat.h"

 static const char *g_fixtures;
+static const char *g_fixtures_real;
 static char g_work[4096];
 static int g_failures;
 static int g_checks;

+/* Progress capture: g_pmid_extract is set when a progress event reports a
+   partially complete EXTRACT phase (0 < bytes_done < bytes_total). Before
+   the UCM_PROCESSDATA callback existed the RAR engine only accounted bytes
+   after a whole entry finished, so a single entry spanning volumes produced
+   no mid-file progress at all. */
+static int g_pmid_extract;
+static zipx_progress_t g_last_progress;
+
+static void
+progress_cb(void *userdata, const zipx_progress_t *p) {
+  (void)userdata;
+  g_last_progress = *p;
+  if(p->phase == ZIPX_PHASE_EXTRACT && p->bytes_total > 0 &&
+     p->bytes_done > 0 && p->bytes_done < p->bytes_total) {
+    g_pmid_extract = 1;
+  }
+}
+
 static void
 fixture_path(char *out, size_t size, const char *name) {
  snprintf(out, size, "%s/%s", g_fixtures, name);
 }

+static void
+fixture_real_path(char *out, size_t size, const char *name) {
+  snprintf(out, size, "%s/%s", g_fixtures_real, name);
+}
+
 static void
 work_path(char *out, size_t size, const char *name) {
  snprintf(out, size, "%s/%s", g_work, name);
@@ -138,7 +162,7 @@ run_rar(const char *fixture, const char *dst, zipx_status_t expected,
  work_path((char *)dst, 0, dst); /* dst is already absolute under work */
  memset(&res, 0, sizeof(res));
  st = rar_extract(src, dst, ZIPX_CONFLICT_FAIL,
-                   zipx_default_limits(), NULL, NULL, NULL, &res);
+                   zipx_default_limits(), NULL, NULL, NULL, NULL, &res);
  check(st == expected, label);
  if(st != ZIPX_OK) {
    check(res.message[0] != 0, "  has error message");
@@ -170,7 +194,7 @@ test_engine_dispatch(void) {
    if(exists(src)) {
      memset(&res, 0, sizeof(res));
      st = rar_extract(src, dst, ZIPX_CONFLICT_FAIL,
-                       zipx_default_limits(), NULL, NULL, NULL, &res);
+                       zipx_default_limits(), NULL, NULL, NULL, NULL, &res);
      check(st != ZIPX_OK, "notar.rar rejected");
      check(!exists(dst), "  no files written for rejected archive");
      if(st == ZIPX_OK) {
@@ -191,7 +215,7 @@ test_engine_dispatch(void) {
      zipx_result_t res;
      zipx_status_t st = rar_extract(src, dst, ZIPX_CONFLICT_FAIL,
                                     zipx_default_limits(), NULL, NULL, NULL,
-                                     &res);
+                                     NULL, &res);
      check(st != ZIPX_OK, "junk.rar rejected");
      check(!exists(dst), "  no files written for junk archive");
      if(st == ZIPX_OK) {
@@ -213,7 +237,7 @@ test_engine_dispatch(void) {
    fixture_path(src, sizeof(src), "does-not-exist.rar");
    memset(&res, 0, sizeof(res));
    st = rar_extract(src, dst, ZIPX_CONFLICT_FAIL,
-                     zipx_default_limits(), NULL, NULL, NULL, &res);
+                     zipx_default_limits(), NULL, NULL, NULL, NULL, &res);
    check(st == ZIPX_ERR_OPEN, "missing source -> ZIPX_ERR_OPEN");
    check(!exists(dst), "  no files written when source is missing");
    if(st == ZIPX_OK) {
@@ -225,13 +249,13 @@ test_engine_dispatch(void) {
  {
    zipx_result_t res;
    check(rar_extract(NULL, "/tmp", ZIPX_CONFLICT_FAIL, NULL, NULL, NULL,
-                      NULL, &res) == ZIPX_ERR_INTERNAL,
+                      NULL, NULL, &res) == ZIPX_ERR_INTERNAL,
          "null rar_path -> ZIPX_ERR_INTERNAL");
    check(rar_extract("/tmp", NULL, ZIPX_CONFLICT_FAIL, NULL, NULL, NULL,
-                      NULL, &res) == ZIPX_ERR_INTERNAL,
+                      NULL, NULL, &res) == ZIPX_ERR_INTERNAL,
          "null dst_dir -> ZIPX_ERR_INTERNAL");
    check(rar_extract("/tmp", "", ZIPX_CONFLICT_FAIL, NULL, NULL, NULL,
-                      NULL, &res) == ZIPX_ERR_INTERNAL,
+                      NULL, NULL, &res) == ZIPX_ERR_INTERNAL,
          "empty dst_dir -> ZIPX_ERR_INTERNAL");
  }

@@ -256,7 +280,7 @@ test_engine_dispatch(void) {
    if(exists(src)) {
      zipx_status_t st = rar_extract(src, dst, ZIPX_CONFLICT_FAIL,
                                     zipx_default_limits(), NULL, NULL, NULL,
-                                     &res);
+                                     NULL, &res);
      check(st == ZIPX_ERR_CONFLICT, "dst is a regular file -> ZIPX_ERR_CONFLICT");
    } else {
      printf("  SKIP dst-is-file (junk.rar missing)\n");
@@ -267,16 +291,15 @@ test_engine_dispatch(void) {

 static void
 test_format_translation(void) {
-  /* Direct exercise of the error-code mapping: this only requires that the
-     dispatcher classifies "encrypted" and "multi-volume" correctly. Since
-     those states are reached only with a real RAR that has the right flags
-     set, we cannot generate that fixture on the fly — but we can confirm
-     that the rejection paths we *do* hit (FORMAT / OPEN / IO) never
+  /* Direct exercise of the error-code mapping. The encrypted and
+     multi-volume states now have real fixtures and are asserted in the
+     real-archive section above; this function only guarantees that the
+     rejection paths reachable without a fixture (FORMAT / OPEN / IO) never
     accidentally return ZIPX_OK. */
  printf("test_format_translation\n");
-  /* The dispatch test already covered the negative paths; nothing more to do
-     here for v1.8. Future fixtures can directly assert ZIPX_ERR_UNSUPPORTED
-     once we have encrypted/multi-volume samples (see docs/HANDOVER.md). */
+  /* Nothing further to check here: encrypted (-p) coverage lives in the
+     real-archive section, which asserts ZIPX_ERR_PASSWORD for a missing or
+     wrong password and a successful decrypt for the right one. */
 }

 static void
@@ -298,13 +321,214 @@ test_limits_handoff(void) {
        "default() matches ZIPX_LIMITS_DEFAULT");
 }

+/* Real-archive happy paths (v1.9, unrar 7.20.1 engine).
+   The fixtures are produced by tests/make-rar-fixtures.bat on a machine with
+   WinRAR; when they are missing (plain CI checkout) these checks SKIP. */
+static void
+test_real_archives(void) {
+  char dst[4096];
+  char checkp[4096];
+
+  printf("test_real_archives\n");
+
+  /* RAR5 (WinRAR 6/7 "v6" compression) single volume. */
+  work_path(dst, sizeof(dst), "rdst_v6");
+  remove_dir(dst);
+  {
+    zipx_result_t res;
+    zipx_status_t st;
+    char src[4096];
+    fixture_real_path(src, sizeof(src), "basic-v6.rar");
+    if(exists(src)) {
+      memset(&res, 0, sizeof(res));
+      st = rar_extract(src, dst, ZIPX_CONFLICT_FAIL,
+                       zipx_default_limits(), NULL, NULL, NULL, NULL, &res);
+      check(st == ZIPX_OK, "basic-v6.rar extracts (v6 RAR5)");
+      if(st == ZIPX_OK) {
+        snprintf(checkp, sizeof(checkp), "%s/root.txt", dst);
+        check(exists(checkp), "  root.txt present");
+        snprintf(checkp, sizeof(checkp), "%s/dir/nested.txt", dst);
+        check(exists(checkp), "  dir/nested.txt present");
+        check(res.entries_done >= 3, "  entries_done >= 3");
+      } else {
+        printf("    message=%s\n", res.message);
+      }
+    } else {
+      printf("  SKIP basic-v6.rar (missing — run tests/make-rar-fixtures.bat)\n");
+    }
+  }
+  remove_dir(dst);
+
+  /* RAR4 legacy single volume. */
+  work_path(dst, sizeof(dst), "rdst_r4");
+  remove_dir(dst);
+  {
+    zipx_result_t res;
+    zipx_status_t st;
+    char src[4096];
+    fixture_real_path(src, sizeof(src), "basic-rar4.rar");
+    if(exists(src)) {
+      memset(&res, 0, sizeof(res));
+      st = rar_extract(src, dst, ZIPX_CONFLICT_FAIL,
+                       zipx_default_limits(), NULL, NULL, NULL, NULL, &res);
+      check(st == ZIPX_OK, "basic-rar4.rar extracts (RAR4)");
+      if(st == ZIPX_OK) {
+        snprintf(checkp, sizeof(checkp), "%s/root.txt", dst);
+        check(exists(checkp), "  root.txt present");
+      } else {
+        printf("    message=%s\n", res.message);
+      }
+    } else {
+      printf("  SKIP basic-rar4.rar (missing)\n");
+    }
+  }
+  remove_dir(dst);
+
+  /* Multi-volume: opening vol.part1.rar must auto-merge part2 from the same
+     directory (unrar drives the volume chain). Also asserts that progress
+     is byte-accurate and updates mid-entry (see progress_cb). */
+  work_path(dst, sizeof(dst), "rdst_vol");
+  remove_dir(dst);
+  {
+    zipx_result_t res;
+    zipx_status_t st;
+    char src[4096];
+    fixture_real_path(src, sizeof(src), "vol.part1.rar");
+    if(exists(src)) {
+      memset(&res, 0, sizeof(res));
+      g_pmid_extract = 0;
+      memset(&g_last_progress, 0, sizeof(g_last_progress));
+      st = rar_extract(src, dst, ZIPX_CONFLICT_FAIL,
+                       zipx_default_limits(), NULL, progress_cb, NULL, NULL, &res);
+      check(st == ZIPX_OK, "vol.part1.rar auto-merges volumes");
+      if(st == ZIPX_OK) {
+        snprintf(checkp, sizeof(checkp), "%s/root.txt", dst);
+        check(exists(checkp), "  root.txt present across volumes");
+        snprintf(checkp, sizeof(checkp), "%s/big.bin", dst);
+        check(exists(checkp), "  big.bin (split file) present and whole");
+        check(res.entries_done >= 2, "  entries_done >= 2");
+        check(g_last_progress.bytes_total > 0,
+              "  progress bytes_total reported");
+        check(g_last_progress.bytes_total == g_last_progress.bytes_done,
+              "  final bytes_done reaches bytes_total");
+        check(g_pmid_extract,
+              "  progress updates mid-entry (not only at entry end)");
+      } else {
+        printf("    message=%s\n", res.message);
+      }
+    } else {
+      printf("  SKIP vol.part1.rar (missing)\n");
+    }
+  }
+  remove_dir(dst);
+
+  /* Encrypted RAR (-p: entry data encrypted, names stored in the clear).
+     The engine decrypts through RARSetPassword, which the wrapper must call
+     after RAROpenArchiveEx and before the first RARReadHeaderEx. */
+  work_path(dst, sizeof(dst), "rdst_enc");
+  remove_dir(dst);
+  {
+    zipx_result_t res;
+    zipx_status_t st;
+    char src[4096];
+    char checkp[4096];
+    fixture_real_path(src, sizeof(src), "enc-v6.rar");
+    if(exists(src)) {
+      /* (a) no password: rejected before anything is written, and with the
+         retryable code rather than a blanket UNSUPPORTED. */
+      memset(&res, 0, sizeof(res));
+      st = rar_extract(src, dst, ZIPX_CONFLICT_FAIL,
+                       zipx_default_limits(), NULL, NULL, NULL, NULL, &res);
+      check(st == ZIPX_ERR_PASSWORD,
+            "enc-v6.rar with no password -> ZIPX_ERR_PASSWORD");
+      check(!exists(dst), "  nothing written (no password)");
+
+      /* (b) wrong password: same code, still nothing published. */
+      memset(&res, 0, sizeof(res));
+      st = rar_extract(src, dst, ZIPX_CONFLICT_FAIL,
+                       zipx_default_limits(), NULL, NULL, NULL, "wrong-pw",
+                       &res);
+      check(st == ZIPX_ERR_PASSWORD,
+            "enc-v6.rar with wrong password -> ZIPX_ERR_PASSWORD");
+      check(!exists(dst), "  nothing written (wrong password)");
+
+      /* (c) correct password: really decrypts. */
+      memset(&res, 0, sizeof(res));
+      st = rar_extract(src, dst, ZIPX_CONFLICT_FAIL,
+                       zipx_default_limits(), NULL, NULL, NULL, "secret123",
+                       &res);
+      check(st == ZIPX_OK, "enc-v6.rar with correct password -> ZIPX_OK");
+      if(st == ZIPX_OK) {
+        snprintf(checkp, sizeof(checkp), "%s/root.txt", dst);
+        check(exists(checkp), "  root.txt decrypted");
+        snprintf(checkp, sizeof(checkp), "%s/dir/nested.txt", dst);
+        check(exists(checkp), "  dir/nested.txt decrypted");
+        check(res.entries_done >= 2, "  entries_done >= 2");
+      } else {
+        printf("    message=%s\n", res.message);
+      }
+    } else {
+      printf("  SKIP enc-v6.rar (missing)\n");
+    }
+  }
+  remove_dir(dst);
+}
+
+/* A dictionary above Cmd->WinSizeLimit (4 GiB, options.cpp:13) makes unrar call
+   back with UCM_LARGEDICT and abort unless the callback answers 1. We answer 0
+   on purpose (see rar_data_cb), so this must surface as ZIPX_ERR_LIMIT_DICT and
+   say *what* is oversized -- it is the dictionary, not the 7 KB entry that
+   happened to be in flight.
+
+   dict-8g.rar is synthetic: RAR 5.0 headers carry the dictionary in four bits
+   (arcread.cpp:871), i.e. the format's own ceiling is exactly 4 GiB, so no
+   `-ma5` archive can reach this path at all. The fixture rewrites CompInfo to
+   the RAR7 field width plus FCI_RAR5_COMPAT; tests/make_fixtures.py:bigdict()
+   builds it and UnRAR 7.23 confirms it as a valid 8 GiB-dictionary archive. */
+static void
+test_dict_limit(void) {
+  char src[4096];
+  char dst[4096];
+  zipx_result_t res;
+
+  printf("test_dict_limit\n");
+
+  fixture_path(src, sizeof(src), "dict-8g.rar");
+  if(!exists(src)) {
+    printf("  SKIP dict-8g.rar (missing)\n");
+    return;
+  }
+
+  work_path(dst, sizeof(dst), "dict-limit");
+  remove_dir(dst);
+  memset(&res, 0, sizeof(res));
+
+  check(rar_extract(src, dst, ZIPX_CONFLICT_FAIL, zipx_default_limits(),
+                    NULL, NULL, NULL, NULL, &res) == ZIPX_ERR_LIMIT_DICT,
+        "8 GiB dictionary is refused as ZIPX_ERR_LIMIT_DICT");
+  check(res.detail[0] != 0 && strstr(res.detail, "8192 MiB") != NULL,
+        "  refusal names the dictionary size");
+  check(strstr(res.detail, "4096 MiB") != NULL,
+        "  refusal names the limit it exceeded");
+  {
+    char landed[4096];
+    snprintf(landed, sizeof(landed), "%s/hello.txt", dst);
+    check(!exists(landed), "  the entry was not extracted");
+  }
+  printf("    detail=%s\n", res.detail);
+  printf("    message=%s\n", res.message);
+  remove_dir(dst);
+}
+
 int
 main(int argc, char **argv) {
  if(argc < 3) {
-    fprintf(stderr, "usage: %s <fixtures-dir> <work-dir>\n", argv[0]);
+    fprintf(stderr, "usage: %s <fixtures-dir> <work-dir> [real-fixtures-dir]\n",
+            argv[0]);
    return 2;
  }
  g_fixtures = argv[1];
+  g_fixtures_real = (argc >= 4) ? argv[3] : argv[1];
  snprintf(g_work, sizeof(g_work), "%s", argv[2]);
  mkdir(g_work, 0777);

@@ -341,6 +565,8 @@ main(int argc, char **argv) {
  test_engine_dispatch();
  test_format_translation();
  test_limits_handoff();
+  test_real_archives();
+  test_dict_limit();

  printf("\nrar_extract: %d checks, %d failures\n", g_checks, g_failures);
  return g_failures == 0 ? 0 : 1;
@@ -0,0 +1,298 @@
+/*
+ * Test driver for the 7z extraction facade (src/sevenz_extract.c).
+ *
+ *   test_sevenz_extract <archive.7z> <out-dir> [password]
+ *       Extract one archive. Exit status 0 means ZIPX_OK; the shell compares
+ *       the result against the fixture's source tree byte for byte.
+ *
+ *   test_sevenz_extract --cases <fixtures-dir> <work-dir>
+ *       Exercise the error and policy paths that need no byte comparison:
+ *       a missing/wrong password, an encrypted header, conflicts under each
+ *       policy, cancellation, limits, a missing destination parent, and the
+ *       guarantee that nothing is published and no staging tree survives a
+ *       failure.
+ *
+ * The host build injects tests/posix_compat.h (see run-sevenz-tests.sh), so
+ * the engine can stay plain POSIX.
+ */
+
+#include <dirent.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/stat.h>
+
+#include "sevenz_extract.h"
+
+#define PASSWORD "Secret123"
+#define PATH_MAX_LOCAL 4096
+
+static int g_checks = 0;
+static int g_failures = 0;
+
+static void
+check(int ok, const char *what) {
+  g_checks++;
+  if(!ok) {
+    g_failures++;
+    printf("  FAIL %s\n", what);
+  }
+}
+
+static int
+cancel_always(void *userdata) {
+  (void)userdata;
+  return 1;
+}
+
+static int
+has_staging_leftover(const char *dir) {
+  DIR *d = opendir(dir);
+  struct dirent *ent;
+  int found = 0;
+
+  if(!d) {
+    return 0;
+  }
+  while((ent = readdir(d))) {
+    if(!strncmp(ent->d_name, ".wfm-extract-", 13)) {
+      found = 1;
+      break;
+    }
+  }
+  closedir(d);
+  return found;
+}
+
+static int
+extract_one(const char *archive, const char *dst, const char *password) {
+  zipx_result_t r;
+  zipx_status_t st = sevenz_extract(archive, dst, ZIPX_CONFLICT_FAIL,
+                                    zipx_default_limits(), NULL, NULL, NULL,
+                                    password, &r);
+
+  if(st != ZIPX_OK) {
+    fprintf(stderr, "  %s: %s: %s\n", archive, zipx_status_string(st),
+            r.message);
+    return 1;
+  }
+  return 0;
+}
+
+/* Runs a case that is expected to fail, and checks the status and message. */
+static void
+expect_fail(const char *label, const char *archive, const char *dst,
+            const char *password, zipx_conflict_t conflict,
+            const zipx_limits_t *limits, zipx_cancel_fn cancel,
+            zipx_status_t want, const char *needle) {
+  zipx_result_t r;
+  zipx_status_t st;
+  char buf[256];
+
+  st = sevenz_extract(archive, dst, conflict, limits, cancel, NULL, NULL,
+                      password, &r);
+  snprintf(buf, sizeof(buf), "%s: status is %s, not %s", label,
+           zipx_status_string(st), zipx_status_string(want));
+  check(st == want, buf);
+  if(needle) {
+    snprintf(buf, sizeof(buf), "%s: message mentions \"%s\" (got \"%s\")",
+             label, needle, r.message);
+    check(strstr(r.message, needle) != NULL, buf);
+  }
+}
+
+/* Extracts store.7z into `dst` under the given policy, expecting `want`. */
+static void
+policy_case(const char *label, const char *archive, const char *dst,
+            zipx_conflict_t conflict, int run, zipx_status_t want) {
+  zipx_result_t r;
+  zipx_status_t st;
+  char buf[256];
+
+  st = sevenz_extract(archive, dst, conflict, zipx_default_limits(), NULL, NULL,
+                      NULL, NULL, &r);
+  snprintf(buf, sizeof(buf), "%s (run %d): status is %s, not %s", label, run,
+           zipx_status_string(st), zipx_status_string(want));
+  check(st == want, buf);
+}
+
+/* The progress callback the dispatch driver installs fires the UI loop; it has
+   to be called multiple times, with monotonic bytes_done and a non-zero
+   bytes_total, or the front-end ends up with no spinner.  These checks pin
+   that down so a refactor that drops the callback returns the test set to
+   red instead of "no progress shown" on the device. */
+typedef struct {
+  int calls;
+  unsigned long long prev_done;
+  unsigned long long max_bytes_total;
+  unsigned long long max_bytes_done;
+  unsigned long long max_entries_total;
+  unsigned long long max_entries_done;
+} progress_recorder_t;
+
+static void
+recorder_progress(void *userdata, const zipx_progress_t *p) {
+  progress_recorder_t *r = userdata;
+
+  r->calls++;
+  if(p->bytes_total > r->max_bytes_total) r->max_bytes_total = p->bytes_total;
+  if(p->bytes_done > r->max_bytes_done) r->max_bytes_done = p->bytes_done;
+  if((unsigned long long)p->entries_total > r->max_entries_total) {
+    r->max_entries_total = (unsigned long long)p->entries_total;
+  }
+  if((unsigned long long)p->entries_done > r->max_entries_done) {
+    r->max_entries_done = (unsigned long long)p->entries_done;
+  }
+  if(p->bytes_done < r->prev_done) {
+    printf("  FAIL progress: bytes_done went backwards (%llu -> %llu)\n",
+           r->prev_done, p->bytes_done);
+    g_failures++;
+  }
+  r->prev_done = p->bytes_done;
+}
+
+static int
+run_cases(const char *fx, const char *work) {
+  char arc[PATH_MAX_LOCAL];
+  char dst[PATH_MAX_LOCAL];
+  zipx_limits_t tight;
+
+  mkdir(work, 0777);
+
+  /* --- passwords ----------------------------------------------------- */
+  snprintf(arc, sizeof(arc), "%s/aes.7z", fx);
+  snprintf(dst, sizeof(dst), "%s/pw-missing", work);
+  mkdir(dst, 0777);
+  expect_fail("aes with no password", arc, dst, NULL, ZIPX_CONFLICT_FAIL,
+              zipx_default_limits(), NULL, ZIPX_ERR_PASSWORD, "encrypted");
+
+  snprintf(dst, sizeof(dst), "%s/pw-wrong", work);
+  mkdir(dst, 0777);
+  expect_fail("aes with the wrong password", arc, dst, "NotThePassword",
+              ZIPX_CONFLICT_FAIL, zipx_default_limits(), NULL,
+              ZIPX_ERR_PASSWORD, "7zAES");
+  {
+    char b2[ZIPX_PATH_MAX + 96];
+    zipx_result_t r;
+    (void)sevenz_extract(arc, dst, ZIPX_CONFLICT_FAIL,
+                         zipx_default_limits(), NULL, NULL, NULL,
+                         "NotThePassword", &r);
+    snprintf(b2, sizeof(b2),
+             "wrong password: detail names the archive (got '%s')", r.detail);
+    check(strstr(r.detail, "aes.7z") != NULL, b2);
+  }
+  check(!has_staging_leftover(work), "no staging tree survives a wrong password");
+
+  snprintf(dst, sizeof(dst), "%s/pw-ok", work);
+  mkdir(dst, 0777);
+  check(extract_one(arc, dst, PASSWORD) == 0,
+        "aes extracts with the right password");
+
+  /* --- encrypted header (-mhe=on) ------------------------------------- */
+  /* The file names, the folder table and every entry size live inside the
+     encrypted header, so this is the case where nothing at all is readable
+     without the password -- not even the entry list. */
+  snprintf(arc, sizeof(arc), "%s/aeshe.7z", fx);
+
+  snprintf(dst, sizeof(dst), "%s/he-missing", work);
+  mkdir(dst, 0777);
+  expect_fail("aeshe with no password", arc, dst, NULL, ZIPX_CONFLICT_FAIL,
+              zipx_default_limits(), NULL, ZIPX_ERR_PASSWORD, "mhe=on");
+  check(!has_staging_leftover(work), "no staging tree survives a locked header");
+
+  snprintf(dst, sizeof(dst), "%s/he-wrong", work);
+  mkdir(dst, 0777);
+  expect_fail("aeshe with the wrong password", arc, dst, "NotThePassword",
+              ZIPX_CONFLICT_FAIL, zipx_default_limits(), NULL,
+              ZIPX_ERR_PASSWORD, "password");
+
+  snprintf(dst, sizeof(dst), "%s/he-ok", work);
+  mkdir(dst, 0777);
+  check(extract_one(arc, dst, PASSWORD) == 0,
+        "aeshe extracts and verifies with the right password");
+  check(!has_staging_leftover(work), "no staging tree survives an aeshe run");
+
+  /* --- open failures -------------------------------------------------- */
+  snprintf(dst, sizeof(dst), "%s/missing-file", work);
+  mkdir(dst, 0777);
+  expect_fail("a missing archive", "/no/such/archive.7z", dst, NULL,
+              ZIPX_CONFLICT_FAIL, zipx_default_limits(), NULL, ZIPX_ERR_OPEN,
+              "cannot open");
+
+  snprintf(arc, sizeof(arc), "%s/store.7z", fx);
+  snprintf(dst, sizeof(dst), "%s/no-parent/deeper", work);
+  expect_fail("a destination whose parent is missing", arc, dst, NULL,
+              ZIPX_CONFLICT_FAIL, zipx_default_limits(), NULL, ZIPX_ERR_IO,
+              "destination parent is missing");
+
+  /* --- conflict policies ---------------------------------------------- */
+  snprintf(dst, sizeof(dst), "%s/policy-fail", work);
+  mkdir(dst, 0777);
+  policy_case("fail", arc, dst, ZIPX_CONFLICT_FAIL, 1, ZIPX_OK);
+  policy_case("fail", arc, dst, ZIPX_CONFLICT_FAIL, 2, ZIPX_ERR_CONFLICT);
+
+  snprintf(dst, sizeof(dst), "%s/policy-overwrite", work);
+  mkdir(dst, 0777);
+  policy_case("overwrite", arc, dst, ZIPX_CONFLICT_OVERWRITE, 1, ZIPX_OK);
+  policy_case("overwrite", arc, dst, ZIPX_CONFLICT_OVERWRITE, 2, ZIPX_OK);
+
+  snprintf(dst, sizeof(dst), "%s/policy-merge", work);
+  mkdir(dst, 0777);
+  policy_case("merge", arc, dst, ZIPX_CONFLICT_MERGE, 1, ZIPX_OK);
+  policy_case("merge", arc, dst, ZIPX_CONFLICT_MERGE, 2, ZIPX_OK);
+
+  /* --- cancellation --------------------------------------------------- */
+  snprintf(dst, sizeof(dst), "%s/cancel", work);
+  mkdir(dst, 0777);
+  expect_fail("a canceled extraction", arc, dst, NULL, ZIPX_CONFLICT_FAIL,
+              zipx_default_limits(), cancel_always, ZIPX_ERR_CANCELED, NULL);
+  check(!has_staging_leftover(work), "no staging tree survives a cancellation");
+
+  /* --- limits --------------------------------------------------------- */
+  tight = *zipx_default_limits();
+  tight.max_entries = 1;
+  snprintf(dst, sizeof(dst), "%s/limits", work);
+  mkdir(dst, 0777);
+  expect_fail("an archive over the entry limit", arc, dst, NULL,
+              ZIPX_CONFLICT_FAIL, &tight, NULL, ZIPX_ERR_LIMIT_ENTRIES,
+              "more than 1 entries");
+
+  /* --- progress callback ---------------------------------------------- */
+  {
+    progress_recorder_t rec = {0};
+    zipx_result_t r;
+
+    snprintf(dst, sizeof(dst), "%s/progress", work);
+    mkdir(dst, 0777);
+    (void)sevenz_extract(arc, dst, ZIPX_CONFLICT_FAIL,
+                          zipx_default_limits(), NULL, recorder_progress,
+                          &rec, NULL, &r);
+    check(rec.calls >= 2, "progress callback fires multiple times");
+    check(rec.max_bytes_total > 0, "progress reports a non-zero bytes_total");
+    check(rec.max_bytes_done > 0,
+          "progress reports a non-zero bytes_done during extraction");
+    check(rec.max_entries_total >= 1,
+          "progress reports a non-zero entries_total");
+    check(rec.max_bytes_done >= rec.max_bytes_total * 9 / 10,
+          "progress reaches within 90% of the declared total");
+  }
+
+  printf("  cases: %d checks, %d failures\n", g_checks, g_failures);
+  return g_failures == 0 ? 0 : 1;
+}
+
+int
+main(int argc, char **argv) {
+  setvbuf(stdout, NULL, _IONBF, 0);
+  if(argc >= 4 && !strcmp(argv[1], "--cases")) {
+    return run_cases(argv[2], argv[3]);
+  }
+  if(argc < 3) {
+    fprintf(stderr,
+            "usage: %s <archive.7z> <out-dir> [password]\n"
+            "       %s --cases <fixtures-dir> <work-dir>\n",
+            argv[0], argv[0]);
+    return 2;
+  }
+  return extract_one(argv[1], argv[2], argc > 3 ? argv[3] : NULL);
+}
@@ -1,5 +1,12 @@
 /* Host test suite for the ZIP extraction engine.
-   Build: see run-tests.sh (uses gcc + the MinGW POSIX shim). */
+   Build: see run-tests.sh (uses gcc + the MinGW POSIX shim).
+
+   Scope: the generated fixtures under tests/fixtures cover the negative and
+   structural paths. Encrypted archives cannot be produced with the Python
+   standard library, so enc-zipcrypto.zip / enc-aes256.zip / enc-aes256-store.zip
+   live in tests/fixtures-real/ and are regenerated by
+   tests/make-zip-enc-fixtures.bat (needs 7-Zip or NanaZip). The password is
+   fixed at "secret123" by that script. */

 #include "../src/zip_extract.h"

@@ -15,6 +22,7 @@
 #include "posix_compat.h"

 static const char *g_fixtures;
+static const char *g_fixtures_real;
 static char g_work[4096];
 static int g_failures;
 static int g_checks;
@@ -24,6 +32,11 @@ fixture_path(char *out, size_t size, const char *name) {
  snprintf(out, size, "%s/%s", g_fixtures, name);
 }

+static void
+fixture_real_path(char *out, size_t size, const char *name) {
+  snprintf(out, size, "%s/%s", g_fixtures_real, name);
+}
+
 static void
 work_path(char *out, size_t size, const char *name) {
  snprintf(out, size, "%s/%s", g_work, name);
@@ -59,9 +72,23 @@ read_text(const char *path, char *buf, size_t size) {
  return 0;
 }

+/* Reads binary content (entries may contain NUL bytes, so read_text cannot be
+   used to verify them). Returns the number of bytes read, or -1. */
+static long
+read_bytes(const char *path, unsigned char *buf, size_t size) {
+  FILE *f = fopen(path, "rb");
+  size_t n;
+
+  if(!f) {
+    return -1;
+  }
+  n = fread(buf, 1, size, f);
+  fclose(f);
+  return (long)n;
+}
+
 static int
-remove_dir(const char *path) {
-  DIR *dir = opendir(path);
+remove_dir(const char *path) {  DIR *dir = opendir(path);
  struct dirent *ent;

  if(!dir) {
@@ -165,6 +192,14 @@ cb_progress(void *userdata, const zipx_progress_t *p) {
  }
 }

+static zipx_status_t
+run_ex(const char *zip, const char *dst, zipx_conflict_t conflict,
+       const zipx_limits_t *limits, test_ctx_t *t, const char *password,
+       zipx_result_t *res) {
+  return zipx_extract(zip, dst, conflict, limits, cb_cancel, cb_progress,
+                      t, password, res);
+}
+
 static zipx_status_t
 run(const char *fixture, const char *dst_name, zipx_conflict_t conflict,
    const zipx_limits_t *limits, test_ctx_t *t, zipx_result_t *res) {
@@ -173,8 +208,20 @@ run(const char *fixture, const char *dst_name, zipx_conflict_t conflict,

  fixture_path(zip, sizeof(zip), fixture);
  work_path(dst, sizeof(dst), dst_name);
-  return zipx_extract(zip, dst, conflict, limits, cb_cancel, cb_progress,
-                      t, res);
+  return run_ex(zip, dst, conflict, limits, t, NULL, res);
+}
+
+/* Same, but against tests/fixtures-real/ and with a password. */
+static zipx_status_t
+run_real(const char *fixture, const char *dst_name, zipx_conflict_t conflict,
+         const zipx_limits_t *limits, test_ctx_t *t, const char *password,
+         zipx_result_t *res) {
+  char zip[4096];
+  char dst[4096];
+
+  fixture_real_path(zip, sizeof(zip), fixture);
+  work_path(dst, sizeof(dst), dst_name);
+  return run_ex(zip, dst, conflict, limits, t, password, res);
 }

 static void
@@ -199,6 +246,111 @@ expect_status(zipx_result_t *res, zipx_status_t status,

 /**************************************************************************/

+/* Verifies the entries all three split layouts share: the same archive was
+   sliced three ways, so every extraction has to produce identical content. */
+static void
+check_split_content(const char *dst_name, const char *label) {
+  static unsigned char data[16384];
+  char dst[4096];
+  char file[4224];
+  char buf[512];
+  long n;
+  size_t i;
+  int ok = 1;
+
+  work_path(dst, sizeof(dst), dst_name);
+  check(exists(dst), label);
+
+  snprintf(file, sizeof(file), "%s/readme.txt", dst);
+  n = read_bytes(file, (unsigned char *)buf, sizeof(buf));
+  check(n == 440 && !memcmp(buf, "split archive fixture\n", 22),
+        "  readme.txt content");
+
+  snprintf(file, sizeof(file), "%s/sub/data.bin", dst);
+  n = read_bytes(file, data, 10240);
+  if(n != 10240) {
+    ok = 0;
+  } else {
+    for(i = 0; i < 10240; i++) {
+      if(data[i] != (unsigned char)(i % 256)) {
+        ok = 0;
+        break;
+      }
+    }
+  }
+  check(ok, "  sub/data.bin binary content (10 KiB across volumes)");
+
+  snprintf(file, sizeof(file), "%s/sub/deep/more.bin", dst);
+  n = read_bytes(file, data, 12000);
+  check(n == 12000 && data[0] == 'A' && data[3] == 'D',
+        "  sub/deep/more.bin content");
+}
+
+static void
+test_volumes(void) {
+  zipx_result_t res;
+  test_ctx_t t = {0};
+  char dst[4096];
+
+  printf("split volumes\n");
+
+  /* name.zip.001 style (7-Zip byte split), picked from the first volume. */
+  expect_ok(&res, run("plain.zip.001", "out_vol_plain_a", ZIPX_CONFLICT_FAIL,
+                      NULL, &t, &res),
+            "byte split: extract from part 001");
+  check_split_content("out_vol_plain_a", "  output tree exists");
+
+  /* Same set, but the user clicked the last volume this time. */
+  expect_ok(&res, run("plain.zip.003", "out_vol_plain_b", ZIPX_CONFLICT_FAIL,
+                      NULL, &t, &res),
+            "byte split: extract from part 003");
+  check_split_content("out_vol_plain_b", "  output tree exists");
+
+  /* name.partN.zip style, picked from the middle volume. */
+  expect_ok(&res, run("parts.part2.zip", "out_vol_parts", ZIPX_CONFLICT_FAIL,
+                      NULL, &t, &res),
+            "partN split: extract from part2");
+  check_split_content("out_vol_parts", "  output tree exists");
+
+  /* name.z01 ... name.zip: offsets are relative to each disk, so this one
+     exercises the disk-aware volume stream. */
+  expect_ok(&res, run("disks.z01", "out_vol_disks_a", ZIPX_CONFLICT_FAIL,
+                      NULL, &t, &res),
+            "split disks: extract from z01");
+  check_split_content("out_vol_disks_a", "  output tree exists");
+
+  expect_ok(&res, run("disks.zip", "out_vol_disks_b", ZIPX_CONFLICT_FAIL,
+                      NULL, &t, &res),
+            "split disks: extract from the final volume");
+  check_split_content("out_vol_disks_b", "  output tree exists");
+
+  /* A plain archive must still take the ordinary path. */
+  expect_ok(&res, run("split_single.zip", "out_vol_single", ZIPX_CONFLICT_FAIL,
+                      NULL, &t, &res),
+            "plain archive still extracts (no volume set detected)");
+  check_split_content("out_vol_single", "  output tree exists");
+
+  /* Broken sets must fail with the exact missing volume, not a vague error. */
+  expect_status(&res, run("gap.zip.001", "out_vol_gap", ZIPX_CONFLICT_FAIL,
+                          NULL, &t, &res),
+                ZIPX_ERR_OPEN, "incomplete set: reported as an open failure");
+  check(strstr(res.message, "gap.zip.002") != NULL,
+        "  error names the missing volume");
+  printf("       message: %s\n", res.message);
+
+  expect_status(&res, run("broken.zip.001", "out_vol_broken", ZIPX_CONFLICT_FAIL,
+                          NULL, &t, &res),
+                ZIPX_ERR_OPEN, "lone first volume: reported as an open failure");
+  check(strstr(res.message, "no other volumes") != NULL,
+        "  error says the remaining volumes are missing");
+  printf("       message: %s\n", res.message);
+
+  work_path(dst, sizeof(dst), "out_vol_gap");
+  check(!exists(dst), "nothing was written for the incomplete set");
+}
+
+/**************************************************************************/
+
 static void
 test_basic(void) {
  zipx_result_t res;
@@ -442,9 +594,18 @@ test_unsupported(void) {
  zipx_limits_t limits;

  printf("encrypted, corrupt and truncated archives\n");
+  /* encrypted.zip only has the general purpose encryption bit flipped on a
+     plain archive, so there is no password that could open it: the scan must
+     stop at the missing password before touching any entry data. */
  expect_status(&res, run("encrypted.zip", "out_encrypted",
                          ZIPX_CONFLICT_FAIL, NULL, &t, &res),
-                ZIPX_ERR_UNSUPPORTED, "encrypted entry rejected");
+                ZIPX_ERR_PASSWORD, "encrypted entry without password rejected");
+  {
+    char dst[4096];
+
+    work_path(dst, sizeof(dst), "out_encrypted");
+    check(!exists(dst), "nothing published for encrypted zip");
+  }
  expect_status(&res, run("bad_crc.zip", "out_bad_crc", ZIPX_CONFLICT_FAIL,
                          NULL, &t, &res),
                ZIPX_ERR_CRC, "crc mismatch detected");
@@ -462,6 +623,7 @@ test_unsupported(void) {

  limits = *base;
  limits.max_ratio = 10;
+  limits.ratio_min_bytes = 1024; /* floor below bomb.zip's 4 MiB */
  expect_status(&res, run("bomb.zip", "out_limit_ratio", ZIPX_CONFLICT_FAIL,
                          &limits, &t, &res),
                ZIPX_ERR_LIMIT_RATIO, "compression ratio limit enforced");
@@ -485,6 +647,85 @@ test_unsupported(void) {
                ZIPX_ERR_LIMIT_DEPTH, "depth limit enforced");
 }

+/* One encrypted archive, exercised four ways. The password is fixed by
+   tests/make-zip-enc-fixtures.bat. */
+static void
+encrypted_archive(const char *fixture, const char *dst_name) {
+  static const char *password = "secret123";
+  zipx_result_t res;
+  test_ctx_t t = {0};
+  char zip[4096];
+  char dst[4096];
+  char file[4224];
+  char buf[2048];
+
+  fixture_real_path(zip, sizeof(zip), fixture);
+  if(!exists(zip)) {
+    printf("  skip %s (run tests/make-zip-enc-fixtures.bat)\n", fixture);
+    return;
+  }
+  work_path(dst, sizeof(dst), dst_name);
+
+  /* No password: the scan phase refuses before any entry data is touched. */
+  expect_status(&res, run_real(fixture, dst_name, ZIPX_CONFLICT_FAIL, NULL,
+                               &t, NULL, &res),
+                ZIPX_ERR_PASSWORD, "no password rejected");
+  check(!exists(dst), "nothing published without a password");
+
+  /* An empty string means the same as no password at all. */
+  expect_status(&res, run_real(fixture, dst_name, ZIPX_CONFLICT_FAIL, NULL,
+                               &t, "", &res),
+                ZIPX_ERR_PASSWORD, "empty password rejected");
+
+  /* Wrong password: caught by the ZipCrypto header check / the AES verifier. */
+  expect_status(&res, run_real(fixture, dst_name, ZIPX_CONFLICT_FAIL, NULL,
+                               &t, "not-the-password", &res),
+                ZIPX_ERR_PASSWORD, "wrong password rejected");
+  check(!exists(dst), "nothing published with a wrong password");
+
+  /* Correct password: the payload has to come out byte for byte. */
+  expect_ok(&res, run_real(fixture, dst_name, ZIPX_CONFLICT_FAIL, NULL, &t,
+                           password, &res),
+            "correct password decrypts");
+  check(res.entries_total == 2, "entry count reported");
+  snprintf(file, sizeof(file), "%s/root.txt", dst);
+  check(!read_text(file, buf, sizeof(buf)) &&
+        !strcmp(buf, "###############\nzip v1.9 fixture root content\n"),
+        "decrypted root.txt content");
+  snprintf(file, sizeof(file), "%s/dir/nested.txt", dst);
+  check(!read_text(file, buf, sizeof(buf)) &&
+        !strcmp(buf, "nested payload line one\nnested payload line two\n"),
+        "decrypted dir/nested.txt content");
+  check(count_staging_leftovers(dst) == 0, "no staging leftovers inside dst");
+}
+
+static void
+test_encrypted(void) {
+  zipx_result_t res;
+  test_ctx_t t = {0};
+  const zipx_limits_t *base = zipx_default_limits();
+  zipx_limits_t limits;
+  char zip[4096];
+
+  printf("encrypted archives (traditional PKWARE + WinZip AES)\n");
+  encrypted_archive("enc-zipcrypto.zip", "out_enc_zipcrypto");
+  encrypted_archive("enc-aes256.zip", "out_enc_aes256");
+  encrypted_archive("enc-aes256-store.zip", "out_enc_aes256_store");
+
+  /* Handing over a password must not skip the scan phase: the limits still
+     apply to encrypted archives. */
+  fixture_real_path(zip, sizeof(zip), "enc-aes256.zip");
+  if(exists(zip)) {
+    limits = *base;
+    limits.max_entries = 1;
+    expect_status(&res, run_real("enc-aes256.zip", "out_enc_limit",
+                                 ZIPX_CONFLICT_FAIL, &limits, &t, "secret123",
+                                 &res),
+                  ZIPX_ERR_LIMIT_ENTRIES,
+                  "entry limit still applies to encrypted archives");
+  }
+}
+
 static void
 test_cancel(void) {
  zipx_result_t res;
@@ -559,9 +800,13 @@ test_large_profile(void) {
  check(large->max_entries == 500000, "max_entries == 500000");
  check(large->max_file_bytes == 1ULL * 1024 * 1024 * 1024 * 1024,
        "max_file_bytes == 1 TiB");
-  check(large->max_total_bytes == 2ULL * 1024 * 1024 * 1024 * 1024,
-        "max_total_bytes == 2 TiB");
+  check(large->max_total_bytes == 4ULL * 1024 * 1024 * 1024 * 1024,
+        "max_total_bytes == 4 TiB");
  check(large->max_ratio == 1000, "max_ratio == 1000");
+  check(large->ratio_min_bytes == base->ratio_min_bytes,
+        "ratio_min_bytes same in both profiles");
+  check(base->ratio_min_bytes == 1ULL * 1024 * 1024 * 1024,
+        "ratio_min_bytes == 1 GiB");

  /* Behaviour: medium_bomb.zip is 1 MiB of 0..255 cycled, compressing to
     ~4 KiB (ratio ~238). Default ratio cap 500 accepts it; large ratio
@@ -576,23 +821,37 @@ test_large_profile(void) {
                      ZIPX_CONFLICT_FAIL, large, &t, &res),
            "large ratio cap (1000) accepts medium_bomb.zip (~238:1)");

-  /* bomb.zip is 4 MiB of identical 'A' bytes, compressing to ~4 KiB
-     (ratio ~1026). Both default cap 500 and large cap 1000 reject it.
-     A bomb is a bomb regardless of which profile you opt into. */
-  expect_status(&res, run("bomb.zip", "out_ratio_bomb_default",
-                          ZIPX_CONFLICT_FAIL, NULL, &t, &res),
+  /* bomb.zip is 4 MiB of identical 'A' bytes (~1026:1). Although its ratio
+     exceeds both caps, it is far below the 1 GiB ratio_min_bytes floor, so
+     it is accepted: small highly-compressible entries are common in
+     legitimate archives (zero-filled placeholders, sparse blobs) and are
+     harmless because writes are bounded by the declared size plus the real
+     free-space check. A true bomb's claimed size is what check_space() and
+     the total/file caps stop, not a small file's ratio. */
+  expect_ok(&res, run("bomb.zip", "out_ratio_bomb_default",
+                      ZIPX_CONFLICT_FAIL, NULL, &t, &res),
+            "default accepts small high-ratio bomb.zip (below ratio_min_bytes)");
+  expect_ok(&res, run("bomb.zip", "out_ratio_bomb_large",
+                      ZIPX_CONFLICT_FAIL, large, &t, &res),
+            "large accepts small high-ratio bomb.zip (below ratio_min_bytes)");
+
+  /* The ratio screen still fires once the entry clears the floor: lowering
+     the floor below bomb.zip's 4 MiB re-arms the caps. */
+  tight = *base;
+  tight.max_ratio = 500;
+  tight.ratio_min_bytes = 1024;
+  expect_status(&res, run("bomb.zip", "out_ratio_bomb_floor",
+                          ZIPX_CONFLICT_FAIL, &tight, &t, &res),
                ZIPX_ERR_LIMIT_RATIO,
-                "default ratio cap (500) rejects bomb.zip (~1026:1)");
-  expect_status(&res, run("bomb.zip", "out_ratio_bomb_large",
-                          ZIPX_CONFLICT_FAIL, large, &t, &res),
-                ZIPX_ERR_LIMIT_RATIO,
-                "large ratio cap (1000) rejects bomb.zip (~1026:1)");
+                "ratio enforced once entry clears ratio_min_bytes");

  /* Lowering the user's chosen ratio below the medium bomb's actual
-     ratio still rejects the archive. The caps are still enforced; the
-     profile just starts at a higher number. */
+     ratio still rejects the archive (floor disabled to keep the fixture
+     small). The caps are still enforced; the profile just starts at a
+     higher number. */
  tight = *large;
  tight.max_ratio = 200;
+  tight.ratio_min_bytes = 0;
  expect_status(&res, run("medium_bomb.zip", "out_ratio_medium_tight",
                          ZIPX_CONFLICT_FAIL, &tight, &t, &res),
                ZIPX_ERR_LIMIT_RATIO,
@@ -611,11 +870,13 @@ test_large_profile(void) {
 int
 main(int argc, char **argv) {
  if(argc < 3) {
-    fprintf(stderr, "usage: %s <fixtures-dir> <work-dir>\n", argv[0]);
+    fprintf(stderr, "usage: %s <fixtures-dir> <work-dir> [fixtures-real-dir]\n",
+            argv[0]);
    return 2;
  }
  g_fixtures = argv[1];
  snprintf(g_work, sizeof(g_work), "%s", argv[2]);
+  g_fixtures_real = (argc >= 4) ? argv[3] : "";
  remove_dir(g_work);
  if(make_dirs(g_work)) {
    fprintf(stderr, "cannot create work dir\n");
@@ -633,9 +894,11 @@ main(int argc, char **argv) {
  test_duplicates();
  test_special_entries();
  test_unsupported();
+  test_encrypted();
  test_cancel();
  test_many_files();
  test_large_profile();
+  test_volumes();

  printf("\n%d checks, %d failures\n", g_checks, g_failures);
  return g_failures ? 1 : 0;
@@ -0,0 +1,204 @@
+/* 7z.h -- 7z interface
+2023-04-02 : Igor Pavlov : Public domain */
+
+#ifndef ZIP7_INC_7Z_H
+#define ZIP7_INC_7Z_H
+
+#include "7zTypes.h"
+
+EXTERN_C_BEGIN
+
+#define k7zStartHeaderSize 0x20
+#define k7zSignatureSize 6
+
+extern const Byte k7zSignature[k7zSignatureSize];
+
+typedef struct
+{
+  const Byte *Data;
+  size_t Size;
+} CSzData;
+
+/* CSzCoderInfo & CSzFolder support only default methods */
+
+typedef struct
+{
+  size_t PropsOffset;
+  UInt32 MethodID;
+  Byte NumStreams;
+  Byte PropsSize;
+} CSzCoderInfo;
+
+typedef struct
+{
+  UInt32 InIndex;
+  UInt32 OutIndex;
+} CSzBond;
+
+#define SZ_NUM_CODERS_IN_FOLDER_MAX 4
+#define SZ_NUM_BONDS_IN_FOLDER_MAX 3
+#define SZ_NUM_PACK_STREAMS_IN_FOLDER_MAX 4
+
+typedef struct
+{
+  UInt32 NumCoders;
+  UInt32 NumBonds;
+  UInt32 NumPackStreams;
+  UInt32 UnpackStream;
+  UInt32 PackStreams[SZ_NUM_PACK_STREAMS_IN_FOLDER_MAX];
+  CSzBond Bonds[SZ_NUM_BONDS_IN_FOLDER_MAX];
+  CSzCoderInfo Coders[SZ_NUM_CODERS_IN_FOLDER_MAX];
+} CSzFolder;
+
+
+SRes SzGetNextFolderItem(CSzFolder *f, CSzData *sd);
+
+typedef struct
+{
+  UInt32 Low;
+  UInt32 High;
+} CNtfsFileTime;
+
+typedef struct
+{
+  Byte *Defs; /* MSB 0 bit numbering */
+  UInt32 *Vals;
+} CSzBitUi32s;
+
+typedef struct
+{
+  Byte *Defs; /* MSB 0 bit numbering */
+  // UInt64 *Vals;
+  CNtfsFileTime *Vals;
+} CSzBitUi64s;
+
+#define SzBitArray_Check(p, i) (((p)[(i) >> 3] & (0x80 >> ((i) & 7))) != 0)
+
+#define SzBitWithVals_Check(p, i) ((p)->Defs && ((p)->Defs[(i) >> 3] & (0x80 >> ((i) & 7))) != 0)
+
+typedef struct
+{
+  UInt32 NumPackStreams;
+  UInt32 NumFolders;
+
+  UInt64 *PackPositions;          // NumPackStreams + 1
+  CSzBitUi32s FolderCRCs;         // NumFolders
+
+  size_t *FoCodersOffsets;        // NumFolders + 1
+  UInt32 *FoStartPackStreamIndex; // NumFolders + 1
+  UInt32 *FoToCoderUnpackSizes;   // NumFolders + 1
+  Byte *FoToMainUnpackSizeIndex;  // NumFolders
+  UInt64 *CoderUnpackSizes;       // for all coders in all folders
+
+  Byte *CodersData;
+
+  UInt64 RangeLimit;
+} CSzAr;
+
+UInt64 SzAr_GetFolderUnpackSize(const CSzAr *p, UInt32 folderIndex);
+
+SRes SzAr_DecodeFolder(const CSzAr *p, UInt32 folderIndex,
+    ILookInStreamPtr stream, UInt64 startPos,
+    Byte *outBuffer, size_t outSize,
+    ISzAllocPtr allocMain);
+
+typedef struct
+{
+  CSzAr db;
+
+  UInt64 startPosAfterHeader;
+  UInt64 dataPos;
+  
+  UInt32 NumFiles;
+
+  UInt64 *UnpackPositions;  // NumFiles + 1
+  // Byte *IsEmptyFiles;
+  Byte *IsDirs;
+  CSzBitUi32s CRCs;
+
+  CSzBitUi32s Attribs;
+  // CSzBitUi32s Parents;
+  CSzBitUi64s MTime;
+  CSzBitUi64s CTime;
+
+  UInt32 *FolderToFile;   // NumFolders + 1
+  UInt32 *FileToFolder;   // NumFiles
+
+  size_t *FileNameOffsets; /* in 2-byte steps */
+  Byte *FileNames;  /* UTF-16-LE */
+} CSzArEx;
+
+#define SzArEx_IsDir(p, i) (SzBitArray_Check((p)->IsDirs, i))
+
+#define SzArEx_GetFileSize(p, i) ((p)->UnpackPositions[(i) + 1] - (p)->UnpackPositions[i])
+
+void SzArEx_Init(CSzArEx *p);
+void SzArEx_Free(CSzArEx *p, ISzAllocPtr alloc);
+UInt64 SzArEx_GetFolderStreamPos(const CSzArEx *p, UInt32 folderIndex, UInt32 indexInFolder);
+int SzArEx_GetFolderFullPackSize(const CSzArEx *p, UInt32 folderIndex, UInt64 *resSize);
+
+/*
+if dest == NULL, the return value specifies the required size of the buffer,
+  in 16-bit characters, including the null-terminating character.
+if dest != NULL, the return value specifies the number of 16-bit characters that
+  are written to the dest, including the null-terminating character. */
+
+size_t SzArEx_GetFileNameUtf16(const CSzArEx *p, size_t fileIndex, UInt16 *dest);
+
+/*
+size_t SzArEx_GetFullNameLen(const CSzArEx *p, size_t fileIndex);
+UInt16 *SzArEx_GetFullNameUtf16_Back(const CSzArEx *p, size_t fileIndex, UInt16 *dest);
+*/
+
+
+
+/*
+  SzArEx_Extract extracts file from archive
+
+  *outBuffer must be 0 before first call for each new archive.
+
+  Extracting cache:
+    If you need to decompress more than one file, you can send
+    these values from previous call:
+      *blockIndex,
+      *outBuffer,
+      *outBufferSize
+    You can consider "*outBuffer" as cache of solid block. If your archive is solid,
+    it will increase decompression speed.
+  
+    If you use external function, you can declare these 3 cache variables
+    (blockIndex, outBuffer, outBufferSize) as static in that external function.
+    
+    Free *outBuffer and set *outBuffer to 0, if you want to flush cache.
+*/
+
+SRes SzArEx_Extract(
+    const CSzArEx *db,
+    ILookInStreamPtr inStream,
+    UInt32 fileIndex,         /* index of file */
+    UInt32 *blockIndex,       /* index of solid block */
+    Byte **outBuffer,         /* pointer to pointer to output buffer (allocated with allocMain) */
+    size_t *outBufferSize,    /* buffer size for output buffer */
+    size_t *offset,           /* offset of stream for required file in *outBuffer */
+    size_t *outSizeProcessed, /* size of file in *outBuffer */
+    ISzAllocPtr allocMain,
+    ISzAllocPtr allocTemp);
+
+
+/*
+SzArEx_Open Errors:
+SZ_ERROR_NO_ARCHIVE
+SZ_ERROR_ARCHIVE
+SZ_ERROR_UNSUPPORTED
+SZ_ERROR_MEM
+SZ_ERROR_CRC
+SZ_ERROR_INPUT_EOF
+SZ_ERROR_FAIL
+*/
+
+SRes SzArEx_Open(CSzArEx *p, ILookInStreamPtr inStream,
+    ISzAllocPtr allocMain, ISzAllocPtr allocTemp);
+
+EXTERN_C_END
+
+#endif
@@ -0,0 +1,89 @@
+/* 7zAlloc.c -- Allocation functions for 7z processing
+2023-03-04 : Igor Pavlov : Public domain */
+
+#include "Precomp.h"
+
+#include <stdlib.h>
+
+#include "7zAlloc.h"
+
+/* #define SZ_ALLOC_DEBUG */
+/* use SZ_ALLOC_DEBUG to debug alloc/free operations */
+
+#ifdef SZ_ALLOC_DEBUG
+
+/*
+#ifdef _WIN32
+#include "7zWindows.h"
+#endif
+*/
+
+#include <stdio.h>
+static int g_allocCount = 0;
+static int g_allocCountTemp = 0;
+
+static void Print_Alloc(const char *s, size_t size, int *counter)
+{
+  const unsigned size2 = (unsigned)size;
+  fprintf(stderr, "\n%s count = %10d : %10u bytes; ", s, *counter, size2);
+  (*counter)++;
+}
+static void Print_Free(const char *s, int *counter)
+{
+  (*counter)--;
+  fprintf(stderr, "\n%s count = %10d", s, *counter);
+}
+#endif
+
+void *SzAlloc(ISzAllocPtr p, size_t size)
+{
+  UNUSED_VAR(p)
+  if (size == 0)
+    return 0;
+  #ifdef SZ_ALLOC_DEBUG
+  Print_Alloc("Alloc", size, &g_allocCount);
+  #endif
+  return malloc(size);
+}
+
+void SzFree(ISzAllocPtr p, void *address)
+{
+  UNUSED_VAR(p)
+  #ifdef SZ_ALLOC_DEBUG
+  if (address)
+    Print_Free("Free ", &g_allocCount);
+  #endif
+  free(address);
+}
+
+void *SzAllocTemp(ISzAllocPtr p, size_t size)
+{
+  UNUSED_VAR(p)
+  if (size == 0)
+    return 0;
+  #ifdef SZ_ALLOC_DEBUG
+  Print_Alloc("Alloc_temp", size, &g_allocCountTemp);
+  /*
+  #ifdef _WIN32
+  return HeapAlloc(GetProcessHeap(), 0, size);
+  #endif
+  */
+  #endif
+  return malloc(size);
+}
+
+void SzFreeTemp(ISzAllocPtr p, void *address)
+{
+  UNUSED_VAR(p)
+  #ifdef SZ_ALLOC_DEBUG
+  if (address)
+    Print_Free("Free_temp ", &g_allocCountTemp);
+  /*
+  #ifdef _WIN32
+  HeapFree(GetProcessHeap(), 0, address);
+  return;
+  #endif
+  */
+  #endif
+  free(address);
+}
@@ -0,0 +1,19 @@
+/* 7zAlloc.h -- Allocation functions
+2023-03-04 : Igor Pavlov : Public domain */
+
+#ifndef ZIP7_INC_7Z_ALLOC_H
+#define ZIP7_INC_7Z_ALLOC_H
+
+#include "7zTypes.h"
+
+EXTERN_C_BEGIN
+
+void *SzAlloc(ISzAllocPtr p, size_t size);
+void SzFree(ISzAllocPtr p, void *address);
+
+void *SzAllocTemp(ISzAllocPtr p, size_t size);
+void SzFreeTemp(ISzAllocPtr p, void *address);
+
+EXTERN_C_END
+
+#endif
@@ -0,0 +1,36 @@
+/* 7zBuf.c -- Byte Buffer
+2017-04-03 : Igor Pavlov : Public domain */
+
+#include "Precomp.h"
+
+#include "7zBuf.h"
+
+void Buf_Init(CBuf *p)
+{
+  p->data = 0;
+  p->size = 0;
+}
+
+int Buf_Create(CBuf *p, size_t size, ISzAllocPtr alloc)
+{
+  p->size = 0;
+  if (size == 0)
+  {
+    p->data = 0;
+    return 1;
+  }
+  p->data = (Byte *)ISzAlloc_Alloc(alloc, size);
+  if (p->data)
+  {
+    p->size = size;
+    return 1;
+  }
+  return 0;
+}
+
+void Buf_Free(CBuf *p, ISzAllocPtr alloc)
+{
+  ISzAlloc_Free(alloc, p->data);
+  p->data = 0;
+  p->size = 0;
+}