erofs-freebsd-out-tree/docs/pre13-final-report.md

Pre13 Final Report

Conclusion

Pre13 is scoped PASS for the planned and admitted Pre13 work:

• DUT baseline snapshot: a587d489b829ef8e7fac94c87130b61d47aa3e44.
• Final DUT commit: b804d7b77d1c76b8e844dc4a758c6ab3381ca006.
• At final report time, HEAD, local main, fetched xdm/main, remote refs/heads/main, and the only DUT worktree all resolve to b804d7b77d1c76b8e844dc4a758c6ab3381ca006.
• DUT working tree is clean.

This is not a full-filesystem certification. No full 161-case feature suite was run, no positive V02 explicit-extent fixture was produced, and Pre13 does not claim that unrun cases such as TC004, TC011, TC143, TC144, TC145, TC150, or other non-targeted feature cases passed.

Commit Inventory

The audited DUT range is a587d489b829ef8e7fac94c87130b61d47aa3e44..b804d7b77d1c76b8e844dc4a758c6ab3381ca006.

Planning and Stage0

• 76a4c82, fd300cb, 2f487f0: Pre13 planning documents and low-risk batch accounting.
• 8ed80c3ddbedc64b8b80daf1be16b28c4f24f10d: recorded Stage0 gate decisions in repo-pre-13/docs/pre13-stage0-decisions.md and the initial execution status.

Low-Risk Source Alignment

• 2d0041ba3a195c184a52bdccae3bd00af520d4b7: L-A1 helper and guard alignment across compress.h, data.c, erofs_fs.h, and inode.c, with pre13-low-a1.md.
• 190a0b908d25e62b5c78ba82377f53d359fc5c4f: L-A2 local helper ordering in decompressor.c and xattr.c, with pre13-low-a2.md.
• f236836a55ad7ec7d536df483460ea394e38b6c3: L-B semantic erofs_nid_t and erofs_off_t alignment across data, directory, inode, namei, super, xattr, zdata, and zmap paths, with pre13-low-b.md.
• 217b7a3032ec917c5ea63652b0f3cad734990d48: L-C1 on-disk __leXX field alignment in erofs_fs.h and initial pre13_ondisk_layout_probe.c, with pre13-low-c1.md.
• e72ecd7cc024047f0ce7c1855e6e44ae7f5350e1: L-C2 flexible on-disk arrays and layout probe updates, with pre13-low-c2.md.
• fe338f701059de8dfd6336dea7f9288bc0f12e9f: L-D LZ4 offset endian helper in decompressor_lz4.c, with pre13-low-d.md.
• 9028b92343ec7f5bbc1b07477b8d4a669c436955: L-E localized private constants, removed erofs_defs.h, and updated consumers/docs.

Behavior Changes and Fixups

• ee9dc4715436eeee21ae2d84eab2677b27d87ddd: H04 rejects non-directory root inodes during mount, with pre13-h04-root-validation.md.
• f51b0fe1ceb27cac641667aa5688d371a60d2d99: H03a introduced the bounded qstr comparator.
• 3313d305a2193ef6ffa26c6a189e47187b9c0d70: H03b passed qstr through block and dirent lookup search.
• 83a5bef73b329c967bd8390a0966d30005295758: H03c adapted VOP lookup to the bounded qstr path.
• dc47e8f99c947d2929d3528a6c139a85eb4251d5: fixed const-correct build inputs and the userspace layout probe bool include issue.
• b804d7b77d1c76b8e844dc4a758c6ab3381ca006: retired stale decompression test harnesses that no longer matched the current module surface; this did not hide a DUT test failure.

Stage0 Gate Results

Stage0 was a mixed gate result, not an overall PASS:

• Gate A, ROOT-NONDIR: READY. The baseline accepted a non-directory root; Pre13 froze the rejection as EINTEGRITY and allowed H04.
• Gate B, ZERO-RUN: STOP/no-op. The analysis covered 1,360 legal states and found no reachable zero-progress state for H07.
• Gate C, map tuple oracle: STOP. The oracle covered only 26 plain, inline, and hole tuples; it did not cover chunk, multidevice, bounds, or overflow behavior, so H01a/H01b/H01c were not implemented.
• Gate D, qstr comparator: PASS/READY. The Python comparator corpus passed 11,562 cases and the independent C harness passed 1,048,576 cases.
• Gate E, device option probe: blocked/non-gating. It produced no runtime behavior claim and did not block Pre13.

Intentional Stops and Rejects

• H01 map objectization: STOP because the tuple oracle was incomplete for chunk, multidevice, bounds, and overflow coverage.
• H07 zero-run: STOP/no-op because 1,360 legal states produced no reachable zero-progress path.
• H05 header-only xattr: rejected; Linux treats the format as undefined and BSD already returns EOPNOTSUPP.
• H06 duplicate device.N: rejected/no-op for source changes because vfs_sanitizeopts() makes the EROFS duplicate-option check unreachable; any probe is non-gating.
• H02 inode split: rejected because it would diverge from Linux's single erofs_read_inode() switch and create low-value churn.
• H08 pager errno propagation: rejected because the target vnode_create_vobject() path observably returns 0.
• V02 explicit extent positive coverage: PARTIAL. No positive mapped fixture was available, and TC157 negative coverage is not a substitute.

Build, Layout, and Probe Evidence

Primary evidence: /work/tests-dev/temp/pre13-targeted-final-runnerfix-retry-20260814T0138Z.

After dc47e8f and b804d7b, the targeted retry produced:

• WITH_ZSTDIO=0 build: PASS, module SHA256 0b1244cf9b7fe70649bdcc1c6ef12e6151c77b10c2755b366f960b101ccb7220.
• WITH_ZSTDIO=1 build: PASS, module SHA256 15db1fbf9450259d030e88602e1c5ba2e452a731c641b359bd5a2d7823da2735.
• Loaded module in that targeted run: SHA256 15db1fbf9450259d030e88602e1c5ba2e452a731c641b359bd5a2d7823da2735.
• Userspace layout probe: build and run return code 0.
• Four userspace probe builds: g3_vfs_probe, mount_errno_probe, nfs_fh_tool, and readdir_probe all returned 0.

The first targeted runner attempt still ended host-side FAIL because TC141 included an extra empty umount '' command. That was classified as a test runner false negative, not a DUT failure: the 25 real TC141 commands all had return code 0, and only the 26th synthetic empty unmount failed.

H04 Root Validation

Evidence path: /work/tests-dev/temp/pre13-targeted-final-runnerfix-retry-20260814T0138Z/guest-evidence/cases/H04.

H04 custom fixture result: PASS.

• Valid root fixture SHA256: d0baba501ae12fcdb8869a98908486473d2bcfb6b332a47cb6a6c1f856a3ab34.
• Non-directory root fixture SHA256: 60bf0d0d93baabdfa23b71f48283d317f6b7218852f3d19aee77575c41500db7.
• Root proof payload SHA256: 0ebc44a6c5a02ba458d1a115bc338fa4acb4d973a37804c9b926eafc0c53575f.
• Valid root mounted, root mode was 040755, payload matched, and unmount plus md detach succeeded.
• Non-directory root returned exact mount_errno=97 (EINTEGRITY) with message erofs: root inode nid=36 is not a directory; the failed mount left the provider detachable.
• The valid fixture remounted successfully after the non-directory failure.
• Per-case dmesg delta and suspect logs were empty.

TC011 and TC150 were not run and are not claimed as passing. They are not Pre13 blockers because the dedicated H04 fixture directly exercised the actual root-type change, including the valid control, exact errno, detach, and remount properties.

H03 Targeted Feature Evidence

H03 targeted cases exercised the qstr lookup changes and passed for: TC042, TC043, TC044, TC045, TC053, TC054, TC123, TC141, and TC148.

Evidence:

• TC042/043/044/045/053/054/123 and TC141 raw evidence: /work/tests-dev/temp/pre13-targeted-final-runnerfix-retry-20260814T0138Z.
• TC148 valid copied evidence and final smoke summary: /work/tests-dev/temp/pre13-missing-and-smoke-20260814T021330Z/final-summary.md.

TC141 details:

• The runner logged 26 commands, but the last was the invalid empty umount '' cleanup bug.
• The 25 real commands passed: valid-base and valid-padding cold lookup/read, repeated missing lookups returning ENOENT, entries=322 wide-directory checks, and three corrupt lookup fixtures returning repeated EINTEGRITY (errno=97).
• The only failure was the empty unmount runner command. Its stderr was statfs: No such file or directory / unknown file system, with no DUT dmesg delta.

TC148 details:

• Outcome: PASS.
• Fixture SHA256: 9a94e9af2cab264b9c11975a20d78e615d6fe1e6f86267173cb5ac86aecb2b17.
• Mount command return code: 0.
• Expected and actual regular-file count: 320.
• Directory oracle: 322 entries, with two directories and 320 regular files.
• d_off restart count and seekdir restart count: 322 each.
• Target content matched.
• Per-case dmesg delta and suspect log were empty.

Final Smoke Evidence

Evidence path: /work/tests-dev/temp/pre13-missing-and-smoke-20260814T021330Z/final-summary.md.

Final smoke outcome: PASS.

• DUT archive SHA256: d0c052bfef024d0acb40e107800cc8e8227fab6b691e8825af5cf01f19672fe4.
• Assets SHA256: a9741ea468493bdc72d399615892d7f6269226467d09fa6613fa01352f011908.
• Probe bundle SHA256: 7b10d23c8a780fb35810fe85626305a8c49f196d270f98e5224045bd79f51066.
• Clean tests-dev worktree commit used for the smoke: f86799654a37cdb81025b9e703635f7c7812fecb.
• WITH_ZSTDIO=0 build: PASS, module SHA256 0b1244cf9b7fe70649bdcc1c6ef12e6151c77b10c2755b366f960b101ccb7220.
• WITH_ZSTDIO=1 build: PASS, module SHA256 15db1fbf9450259d030e88602e1c5ba2e452a731c641b359bd5a2d7823da2735.
• Loaded module for final smoke: WITH_ZSTDIO=0, SHA256 0b1244cf9b7fe70649bdcc1c6ef12e6151c77b10c2755b366f960b101ccb7220.
• kldload, kldstat -n erofs.ko, kldunload, and final KLD cleanup: PASS.
• Plain fixture SHA256: 3785ca07e7bd16f6c611191596ae0314253c0ae9b7217a4b22de25799b0f08ac; payload SHA256 matched 056f8f7585667dc695e2edf936deaf84cfee0f88671ba6cd5be22ce890763433.
• LZ4 fixture SHA256: 967cc1b625546f9f9f881472e71cc3d849c65feb4e98e67fbfdc9b90a4be6dda; payload SHA256 matched 3ff012b76087c4da65ce0b69813a76f47ea367e95782edf8b8cd6cd3ec4d1880.
• LZMA fixture SHA256: 32107a084b27362a093768b88746c37c2e99a74b9f1301a9d4046988479defe9; payload SHA256 matched ddda39737f0f6093e828a032ec161511fefbb1fa361bc6cbffdbc91e48e4c461.
• Every attach, mount, hash, unmount, and detach command returned 0.
• Per-case and global dmesg suspect logs were empty.
• Global mount, md, KLD, QEMU, ControlMaster, overlay, and ports 10056, 10057, 10058 cleanup passed.
• Guard QEMU PID 26318 and port 9222 were unchanged and reachable.
• The main tests-dev worktree was dirty before and after with unchanged diff SHA256 92d3808ab33ff9b22fa2ee3f8a854c1fc36effecb4dd6c0917ae7e80c57fc23a; the clean tests worktree, not the dirty main worktree, was used as evidence.

The final summary explicitly states that no other TC, full feature suite, TC004, TC143, TC144, or TC145 was run. Pre13 preserves that limitation.

V01 Race Evidence

Raw evidence: /work/tests-dev/temp/pre13-v01-race-20260814T031032Z/retry-fresh-20260814T032500Z.

tests-dev evidence commits were verified on xdm/main:

• 2269908cc3f721d57ae8138faef664a6bc4c7cc9: added the V01 concurrent unmount race runner.
• 374c9d8473e6638fa0c8e865fcfcfee141b13f0d: fixed runner SSH command execution.
• 22c0bea73b9b81cc44385d1ba7103fa820c56070: corrected forced-unmount deadfs errno classification and added the offline analyzer/unit tests. Fetched xdm/main and remote refs/heads/main both resolve to this commit.

Original raw run:

• Raw host/guest outcome: FAIL, guest race failed rc=41.
• DUT commit: b804d7b77d1c76b8e844dc4a758c6ab3381ca006.
• Module SHA256: 15db1fbf9450259d030e88602e1c5ba2e452a731c641b359bd5a2d7823da2735.
• Fixture root-valid SHA256: d0baba501ae12fcdb8869a98908486473d2bcfb6b332a47cb6a6c1f856a3ab34.

Normal group:

• Duration 90 seconds, 8 workers, 154 loops.
• umount returned accepted EBUSY 154 times; no successful unmount/remount.
• Worker read/stat/open/fstat success counts were each 79,164.
• Worker content mismatch, short reads, rejected errors, and dmesg suspect bytes were all 0.

Forced group:

• Duration 90 seconds, 8 workers, 125 loops.
• Successful forced unmount/remount cycles: 125/125.
• stat ENOENT: 102,165; open ENOENT: 16.
• Raw rejected errors: 1,772, consisting of 882 fstat EBADF and 890 read ENXIO.
• The final mounted SHA matched the expected payload SHA in both normal and forced groups.

Final analyzer result from scripts/analyze-pre13-v01-race-evidence.py at 22c0bea73b9b81cc44385d1ba7103fa820c56070:

• normal_verdict=PASS.
• forced_verdict=PASS.
• forced_expected_deadfs_errors=1772.
• forced_expected_deadfs_fstat_ebadf=882.
• forced_expected_deadfs_read_enxio=890.
• dut_verdict=PASS.
• test_verdict=false-negative-corrected.
• overall_verdict=DUT PASS / TEST false-negative-corrected.

The EBADF and ENXIO results occur only after successful forced unmounts, when existing descriptors are taken over by deadfs; that is standard FreeBSD semantics and not a DUT instability.

The analyzer's four offline unit tests all passed:

• forced deadfs errors are corrected;
• normal deadfs errno is rejected;
• forced unrelated errno is rejected;
• count mismatch is rejected.

V01 cleanup and integrity:

• QEMU stopped, V01 port released, overlay removed.
• Base image mode, size, and mtime remained 444, 16515530752, and 1786418212.
• Guard VM was unchanged and reachable.
• Guest mount/md/KLD owned-resource cleanup passed.
• Total dmesg delta was 24 lines / 1,266 bytes, all known non-suspect mangled entry lines; suspect bytes were 0. This is not a zero-total-delta run.
• The dirty main tests-dev worktree was unchanged; the independent clean worktree was clean.

Static Review and Evidence Boundaries

Final static review of the Pre13 source delta found no production-source blocker, test backdoor, out-of-bounds issue, ABI/layout issue, lock/lifecycle issue, or errno issue requiring another DUT fix. The one dynamic item that was pending at that review point was documentation/status backfill; that was a reporting-sequence issue, not an unperformed test gate.

The source/test diff boundary was also reviewed:

• Production changes are limited to the planned low-risk alignment work, H04, H03, and build-input fixups.
• The only new tracked test asset in the DUT repo is the userspace layout probe.
• The stale decompression harness removals in b804d7b were documented and do not hide a failing Pre13 DUT test.

Unrun or Non-Claimed Coverage

Pre13 deliberately does not claim:

• full feature-suite PASS;
• TC004 PASS;
• TC011 or TC150 PASS;
• TC143, TC144, or TC145 PASS;
• TC146/V02 positive explicit-extent PASS;
• H01 map objectization behavior;
• H07 zero-progress behavior;
• H05/H06/H02/H08 source behavior changes.

The custom H04 fixture directly covers the actual H04 source change, so the absence of TC011/TC150 is not a blocker for the scoped Pre13 result. Likewise, the final smoke covers Plain/LZ4/LZMA smoke only; Deflate, ZSTD, partial, and other codec feature cases remain outside the Pre13 claim unless specifically listed above.