update

2026-08-18 09:20:44 +02:00
commit b826cd721a
522 changed files with 93730 additions and 0 deletions
@@ -0,0 +1,160 @@
+# 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 全量结论。
@@ -0,0 +1,8 @@
+# repo22 当前状态索引
+
+- [2026-08-09 总体进度](2026-08-09-overall-progress.md)：基线
+  `cd0e985b5ac54a4b7acb7042422329ad1729fb3e` 上的实现、历史动态证据、八组
+  全量回归分工、未决 issue、风险和下一步。
+
+此目录记录阶段性状态；测试结果会随后续 commit 更新。正式逐项证据位于
+`tests/results/manual/`，未决验证缺口位于 `issues/`。