Module format 

The on-disk format versions, and the one rule for checking them.

Chronix writes four durable formats and every one of them used to carry its own version constant, its own comparison and its own error text:

• the .csx segment header refused anything but an exact match, and said so through a dedicated UnsupportedVersion variant;
• the WAL file header refused anything but an exact match, as an InvalidHeader;
• the .series sidecar refused anything but an exact match and reported it as Corrupt — which points an operator at a failing disk when what actually happened is that they upgraded chronix;
• and the catalog snapshot refused only a newer version, silently accepting an older one it has no code to interpret.

That last one is an asymmetry nobody decided. The three others agree that a version is an identity, not an ordering: there is no partial reader for a superseded layout, because the layouts were superseded before anyone could have data under them.

The rule

A format version is checked for equality, in both directions, and a mismatch is its own error — never corruption. The two are different facts with different remedies: corruption means the bytes are damaged and the answer is a restore; a version mismatch means the software and the directory disagree about the layout and the answer is to match them up.

Changing a format

Bump the constant here and state the break in CHANGELOG.md. There is deliberately no migration: chronix reads exactly the generation it writes, and a directory from another generation is refused by name with the remedy in the message. That is a decision with an expiry date — it holds only while the project is willing to tell a consumer to recreate their data directory, which is a promise 1.0 will have to replace.

Bump it when the bytes change, not before. The version exists to make a foreign directory legible: without a bump, an old directory has matching magic and a matching version, so the reader proceeds into a layout it does not understand and the failure arrives as a CRC error, a bounds check or a decode error — which is exactly the “report a version mismatch as corruption” confusion this module exists to remove. A bump with no layout change is the mirror mistake: it invalidates every directory in exchange for nothing. All four are still at 1 because nothing has changed the bytes yet; the format-changing work is batched so they move together, once.

Constants

CATALOG_FORMAT_VERSION

The catalog manifest snapshot.

SEGMENT_FORMAT_VERSION

.csx segment files.

SERIES_INDEX_FORMAT_VERSION

The per-segment .series sidecar.

WAL_FORMAT_VERSION

Write-ahead log files.

Functions

check

Check a format version, returning the message to report on a mismatch.

version_mismatch

What to tell somebody whose directory this build cannot read.