erofs-freebsd-out-tree/current/report-1/2026-08-09-overall-progress.md

repo22 当前总体进度

更新时间：2026-08-09 UTC

状态报告代码基线：cd0e985b5ac54a4b7acb7042422329ad1729fb3e

本报告记录的是上述基线上的阶段性状态。测试结果、问题状态和统计会随后续 提交继续更新，不能将本文视为 TC001-TC156 已完成全量回归的声明。

目标与执行范围

repo22 的目标是在 FreeBSD 15 amd64 上提供只读 EROFS 内核模块，并以可复现 fixture、真实 KLD、真实 mount/read/errno 和完整清理证据验证声明的功能边界。

当前执行约束如下：

• 只修改和提交 repo-community/repo22，fixture、VM overlay、KLD 和原始日志仅 放在 /work/build 或 guest 临时目录。
• 不建设或使用 CI、runner、自动 PASS wrapper；每个 TC 必须逐份对照对应 Markdown 手工执行。
• host 侧 mkfs.erofs、dump.erofs、fsck.erofs 和静态源码审查只作为 fixture 或分析证据，不能替代 FreeBSD 内核动态结果。
• 每批测试形成独立 manual report，记录 commit、构建配置、KLD SHA256、guest 版本、命令、可观察输出或 errno、fixture hash 和清理状态。
• 每批完成后提交并 push 到 xdm/main；并行批次若使远端前进，则 fetch、rebase 自己的 test-only 提交后正常 push，禁止 force push。

已完成实现与审查

当前源码已覆盖 superblock、compact/extended inode、plain/inline/chunk 数据、 目录/namecache、xattr/ACL/metabox、LZ4/MicroLZMA/DEFLATE/ZSTD、fragment、 multi-device、NFS export、pager 和多项 fail-closed 边界检查。功能声明的准确边界 以 docs/features.md 为准。

主要 feature 批次包括：

• 29a215dd：POSIX ACL 与完整 xattr namespace 集成。
• 545d35bd：xattr、long prefix、shared xattr 和 metabox 边界加固。
• 96e22cc：cold nested namei 与目录结构校验修复。
• 4ef680df、78182686：真实 multi-device、slot mapping、flatdev 和 extent 映射审查修复。
• 2354b448：NFS export、稳定句柄和相关 vnode 路径。
• c208bf1f：压缩映射 P0 收口，包括多算法、partial reference 和 extent 路径。
• 9a3604fb：metadata/VFS 语义收口，包括 inline bounds、special rdev、pager、 namei、NFS generation 和真实压缩占用统计。

关键收尾与工程对齐提交：

Commit	已完成内容
c881f656	修复 48-bit superblock union、OFF_MAX、大 hole 内存和大目录索引等最终 metadata 边界；建立 TC150-TC153 与三份未决 issue。
4d51ca9e	停止跟踪 build/obj、生成头和架构 symlink，避免构建产物进入正式提交。
89594551	将 KLD 构建布局、源文件命名、架构门控和 WITH_ZSTDIO 方式与 FreeBSD/Linux 上游职责对齐。
2f2ac5a8	更新 README、architecture、refactoring plan/status，使构建、BSD API 差异和功能边界与源码一致。
077b37ab	删除会伪造覆盖或无条件 PASS 的旧 runner/wrapper，加入字段断言的 fixture transformer 与 FreeBSD probe，修订关键 TC 文档。
cd0e985b	完成最终 review finding：per-inode NFS generation、显式 extent 物理地址溢出检查、compact/extended timestamp 校验，并直接动态执行 TC154-TC156。

上述工作也包含多轮 code review 和 style review：源文件职责、函数顺序和磁盘 ABI 尽量贴近 Linux EROFS；FreeBSD vnode、pager、NFS、GEOM 和 dev_t 差异采用 FreeBSD 15 原生接口；磁盘长度、加法、移位和 signed/unsigned 转换按 fail-closed 原则处理。

已有动态验证

tests/results/manual/ 中保留了各 feature 在对应历史 commit 上的真实 FreeBSD 15 动态证据。它们证明对应变更批次曾执行内核路径，但不能替代当前 final source 的 TC001-TC156 全量重跑。

批次	主要动态证据	当前解释
压缩	compact/full LZ4、legacy full index、partial reference、MicroLZMA、DEFLATE、ZSTD、fragment、ztailpacking 和多种边界 source/hash compare	历史 feature 证据存在；G5/G6 尚需在本轮 exact KLD 重跑。
xattr/ACL/metabox	inline/shared/long-prefix xattr、ACL、metabox carrier 和 corruption errno	历史 feature 证据存在；G4 尚未启动。
directory/namei/pager	cold nested lookup、目录 padding、special rdev、真实 mmap/page fault 和 inline bounds	历史 feature 证据存在；G1/G3 将按当前文档重跑。
multi-device	外部 provider、显式 slot、flatdev、unified address、fragment 和 orphan/error 路径	历史 feature 证据存在；G7 尚未启动。
NFS	getfh/fhopen、同镜像重挂、同 md 替换、ESTALE、background/stress cleanup	历史 feature 证据存在；G8 尚未启动。
final review	TC150-TC152 动态 PASS；TC153 明确 SHELVED	结果来自 c881f656 前后的 final-review 批次，不是 156 项全量 PASS。

当前 final source cd0e985b 的直接动态证据是 tests/results/manual/2026-08-09T0557Z-review-fixes/manual-test-report.md：

• FreeBSD 15.0-RELEASE-p8 amd64 上 WITH_ZSTDIO=0 KLD SHA256 为 d6e755c7a75dd5043b603d58215ae3e7c8f29318b31dc1885aa9bb070d6e57a5。
• WITH_ZSTDIO=1 KLD SHA256 为 b442f9f05af1d1a76801690c83c9a40ec6fc739adb0663e7dacaf837eeb2ecf3。
• TC154、TC155、TC156 均在该 final source 上直接动态 PASS，分别覆盖 per-inode NFS generation、explicit extent pa + plen overflow 和 inode timestamp validation。
• 该批结束时 EROFS mount、KLD 和 md provider 均已清理。

本轮八组全量回归

TC 编号范围为 TC001-TC156，共 156 项。以下集合经计数检查为总数 156、重复 0、 遗漏 0。

组	精确集合	数量	当前状态
G1	TC001, TC007, TC009, TC011-TC014, TC019-TC040, TC147, TC150, TC151	32	已启动；正在修订文档和确定性 fixture，尚未形成 final-source 32 项结论。
G2	TC002, TC008, TC010, TC015-TC018, TC112-TC116, TC119	13	已启动；使用独立 worktree/VM，尚未形成 13 项结论。
G3	TC041-TC066, TC141, TC148, TC149, TC153	30	未启动。
G4	TC005, TC067-TC083, TC117, TC134-TC140, TC142	27	未启动。
G5	TC003, TC084-TC092	10	未启动。
G6	TC004, TC102-TC110, TC143-TC146, TC155	15	未启动。
G7	TC006, TC093-TC101, TC118	11	未启动。
G8	TC111, TC120-TC133, TC152, TC154, TC156	18	未启动。

G1/G2 的“已启动”只表示执行代理、工作目录和任务集合已经建立，不表示其中任何 TC 已在本轮计为 PASS。G8 中 TC154/TC156、G6 中 TC155 虽已有 cd0e985b 直接 证据，仍需由对应全量组在最终统计中明确引用或按组要求重跑，不能导致重复计数。

已完成与未完成

已完成：

• 核心 feature 实现、针对性 code review、FreeBSD 15 API 对齐和构建布局收口。
• 多个历史 feature 批次的真实 KLD 动态验证与清理记录。
• 当前 final source 的双配置构建和 TC154-TC156 直接动态验证。
• 移除旧 CI 风格 runner/wrapper，建立“逐 Markdown 手工执行”的验收规则。
• 三项已知验证缺口均有详细 issue，没有把未执行或环境受限结果标成 PASS。

未完成：

• TC001-TC156 在同一 final-source 基线族上的八组全量手工回归与最终汇总。
• G1/G2 的文档修订、fixture 固化、exact KLD 执行、逐 TC 报告和 push。
• G3-G8 的启动、独立环境分配、执行和结果提交。
• TC010 所需 16 TiB 级合格 provider、TC153 大目录内核路径、explicit extent mapped compressed payload 的正向 fixture。

Issue 索引

检查时 issues/ 只有以下三份已跟踪文档，没有未提交 issue 文件或真实 issue 改动，因此本状态提交不修改 issues/。

Issue	状态	影响 feature	Shelved 原因
issues/TC010-48bit-statfs-large-provider.md	SHELVED - environment unavailable	48-bit block count、primary provider size validation、statfs(2)/df 总量和 root/block union 选择	非零 blocks_hi 在 4 KiB block 下至少要求 16 TiB GEOM provider；当前 vnode md 流程没有已验证、可安全清理的合格 provider。小 provider 拒绝和 TC150 fallback 都不能替代正向结果。
issues/TC153-large-directory-block-index-validation.md	SHELVED - kernel validation incomplete	超大目录二分索引、cold lookup、EINTEGRITY 传播和 negative namecache 正确性	已有可复现 FLAT_PLAIN fixture，但尚未在 FreeBSD fixed/pre-fix KLD 上完成冷查找对照；host 生成和静态审查不足以计 PASS。
issues/extent-metadata-fixture-unavailable.md	SHELVED - positive fixture unavailable	explicit compressed extent parser、4/8/16/32-byte record、物理/逻辑高位、binary search、partial reference/fragment 映射	erofs-utils 1.8.6 和已试 1.9.3 均不生成真实 mapped explicit-record payload。TC152 hole 与 TC155 overflow 只覆盖部分 header/negative 分支，不能替代正向压缩数据读取。

风险与依赖

• 并行组共享远端 xdm/main，每批 push 前必须重新 fetch/rebase 并确认没有覆盖其他 组的 TC、helper、report 或 issue。
• FreeBSD VM、SSH 端口、qcow overlay、md unit 和 mount point 必须按组隔离；任何 guest 残留都会污染后续动态证据。
• erofs-utils 的格式生成能力限制 explicit extent 等正向 fixture，必要时只能使用 字段自检、CRC32C-aware 的 structured transformer，不能手工猜偏移。
• 48-bit 大 provider、memory pressure、NFS stress 和性能 TC 对环境容量及稳定性要求 较高，环境不足时必须使用 SHELVED/ISSUE 或 ENVIRONMENT-UNAVAILABLE，不能 降低判据。
• 历史报告跨多个 commit。最终统计必须只接受对应 exact KLD 的本轮动态结果，或 明确标注尚未重跑，禁止把旧 HEAD 结果直接升级为全量 PASS。

下一步

1. 完成 G1/G2 文档和 fixture 修订，构建各自 exact KLD，逐 TC 手工执行并提交报告。
2. 每个先完成的组 fetch/rebase 最新 xdm/main，严格 pathspec 提交并正常 push。
3. 启动 G3/G4，随后按环境和依赖启动 G5-G8；压缩、multi-device、NFS 使用隔离 VM。
4. 对任何 kernel behavior failure 立即停止 PASS 计数，新增或更新有事实依据的 issue。
5. 八组结束后汇总 156 项，检查总数、重复、遗漏、KLD/image/source hash 和全部清理 证据，再发布 final-source 全量结论。