[liulanzheng]

What this PR does / why we need it:

Align each non-zero local data extent and the index start in compacted LSMT output to 4 KiB. This gives block-aligned consumers a 4 KiB payload layout while retaining 512-byte logical I/O and mapping units.

The shared compaction path covers ordinary commits and merge/flatten output; warp commits apply the same alignment to local data. Explicit zero extents remain index-only, and remote mappings retain their original offsets. Zero padding costs at most 3584 bytes before each local extent, plus up to 3584 bytes before the index.

The on-disk records and reader addressing are unchanged. Existing layers remain readable; newly compacted output uses the aligned layout. Logical offsets are not rounded, so extents whose logical starts are not 4 KiB aligned do not necessarily share their physical offsets within a page.

For uncompressed layers, alignment applies to file offsets. For compressed output, it applies to offsets in the decoded LSMT stream, not the compressed backing file.

Validation:

• 15 local LSMT tests passed, covering ordinary/warp layouts, zero padding and extents, multi-buffer copying, reopened reads, compressed layers, stacked layers and hybrid writes.
• Library source passed a C++14 syntax check with -Wall -Werror=sign-compare; git diff --check passed.
• GitHub build, benchmark and Project Checks passed for commit 8b354eb.

Local tests used Debian 13 x86_64, Photon v0.9.6 and psync I/O (--nwrites=256 --layers=3 --vsize=8). The QEMU test runner used EPOLL/INIT_IO_NONE because io_setup is unsupported, and returned the GoogleTest exit status. These runner adjustments are outside the repository; local libaio validation was not performed.

Which issue(s) this PR fixes:

None.

Please check the following list:

• Does the affected code have corresponding tests, e.g. unit test, E2E test?
• Does this change require a documentation update? Updated the LSMT format documentation.
• Does this introduce breaking changes that would require an announcement or bumping the major version? No.
• Do all new files have an appropriate license header? No new files.

[Copilot]

🟢 Approval recommended

No blocking issues were identified in offset accounting, ordinary and warp integration, or default-layout compatibility.

No open issues 🎉

What changed in this PR

Adds optional page-offset preservation to LSMT compaction, enabling direct mapping of complete logical 4 KiB pages from eligible uncompressed layers while keeping the default tightly packed layout.

Changes:

• Adds --preserve-page-offset and a matching commit option.
• Pads local extents and aligns the index start in ordinary and warp commits.
• Documents the layout and adds tests for offsets, padding, zero extents, and reopened reads.

File	Description
src/​tools/​overlaybd-commit.cpp	Exposes and forwards the new CLI flag.
src/​overlaybd/​lsmt/​test/​test.cpp	Tests ordinary and warp layouts with padding enabled and disabled.
src/​overlaybd/​lsmt/​format_spec.md	Documents optional padding and unchanged format units.
src/​overlaybd/​lsmt/​file.h	Adds the default-disabled commit option.
src/​overlaybd/​lsmt/​file.cpp	Implements extent padding and index alignment in both commit paths.

_{Review effort: Balanced}

[BigVan]

We've also encountered a similar issue. We believe it's sufficient to simply align to the default 4K block size used by ext4 during mkfs, without needing to explicitly specify it via parameters. Using 4K padding effectively reduces the number of indices during compress_index. I'll be opening a PR shortly to fix this.