PCF: add end-of-file Trailer + chain direction; adopt in PFS-MS (Rust)#17
Merged
Conversation
Introduce an optional file Trailer so the partition-table head can be located from the end of the file instead of the header. The header's partition_table_offset may hold the all-ones sentinel (PT_OFFSET_TRAILER), in which case the head is read from a fixed 20-byte Trailer at EOF that also carries a chain-direction flag (forward/backward). This makes append-only writing possible with no in-place header rewrite: each commit appends a fresh trailer at the new end of file, and readers locate the most recent valid trailer by scanning backward (which also gives crash recovery for aborted appends). - pcf: PT_OFFSET_TRAILER/TRAILER_SIZE/TRAILER_MAGIC/CHAIN_* consts, a new Trailer type, Container::open sentinel resolution with backward scan, table_head()/chain_is_backward() accessors, finalize_with_trailer(), and BadTrailer error. Canonical 395-byte vector unchanged (header mode). - pfs-ms: adopt the trailer; header keeps the sentinel forever and commits are purely additive (no in-place writes). Reference vector regenerated (2986 -> 3066 bytes). - pcf-debug: resolve the sentinel in the forensic walk via backward scan, with a TrailerResolved diagnostic. - pcf-compact: reads trailer-mode files transparently via Container::open.
Mirror the Rust reference's end-of-file trailer feature in all three other implementations: PT_OFFSET_TRAILER sentinel + TRAILER_MAGIC/size/direction constants, a Trailer (de)serializer, Container.open backward-scan resolution (with crash-recovery for aborted appends and a head-block validity guard), tableHead()/chainIsBackward() accessors, a finalize-with-trailer writer, and a BadTrailer error. Each gets a trailer test suite; the canonical 395-byte PCF vector stays header-mode and byte-identical across implementations. Also bump the PFS-MS reference-vector size pin in ci-pfs.yml (2986 -> 3066) to match the trailer-mode layout.
PCF spec: add Section 5.4 (File Trailer and Chain Direction), the partition_table_offset trailer sentinel (Section 4), direction-dependent next_table_offset (Section 5.1), the trailer-aware reader algorithm (11.1), conformance rules C9/W6 (Section 12), assumptions A15/A16 (Section 14), the layout overview (Section 3), and Appendix A. The trailer is located by a backward scan for its magic, giving append-only writers crash recovery. PFS-MS spec: the profile now publishes each head by appending a PCF File Trailer instead of rewriting the header pointer, making it purely append-only (Sections 2, 4.1, 4.2, 4.3, 6.2, 6.3, 11.1, conformance W2, Section 17, Appendix A).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Introduce an optional file Trailer so the partition-table head can be
located from the end of the file instead of the header. The header's
partition_table_offset may hold the all-ones sentinel (PT_OFFSET_TRAILER),
in which case the head is read from a fixed 20-byte Trailer at EOF that
also carries a chain-direction flag (forward/backward).
This makes append-only writing possible with no in-place header rewrite:
each commit appends a fresh trailer at the new end of file, and readers
locate the most recent valid trailer by scanning backward (which also
gives crash recovery for aborted appends).
Trailer type, Container::open sentinel resolution with backward scan,
table_head()/chain_is_backward() accessors, finalize_with_trailer(),
and BadTrailer error. Canonical 395-byte vector unchanged (header mode).
are purely additive (no in-place writes). Reference vector regenerated
(2986 -> 3066 bytes).
with a TrailerResolved diagnostic.