# 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 全量结论。