ProcessJobStore and SubstrateStore already implemented the
loader-accepts-any-version-in-[1, kVersion] pattern. The other five
stores (ControlJobStore, CarrierStore, LoadPortStore, ExceptionStore,
SpoolStore) used strict `header[1] != kVersion` rejection, meaning
a future kVersion bump there would silently nuke every persisted
record on first replay. That's a footgun the test_persistence_upgrade
test already flagged as a tripwire.
This commit flips the strict checks to `< 1 || > kVersion`, mirroring
PJ + Substrate. No format change (kVersion stays at 1 across the
five stores), but:
- Future v2 of any store now Just Works: add fields at the end of
write_record_, bump kVersion to 2, gate the new reads behind
`if (version >= 2)`. Old v1 records on disk continue to replay
with the new fields defaulted.
- Future versions beyond kVersion still get rejected (downgrade
protection — older code can't try to decode trailers it doesn't
understand).
Comment blocks on each kVersion declaration now describe the upgrade
discipline so the next contributor doesn't reinvent it.
Test additions:
- Positive test that v1 ControlJob records load on current code
(will continue to pass when kVersion bumps to 2, proving v1 is
still readable)
- ExceptionStore rejects a v9 (future) record, matching CJ + Carrier
- The existing tripwire tests get retitled from "rejects unknown
version" to "rejects a future version" to reflect the new contract
README §6 gets honest: every store is now multi-version-aware, not
just PJ + Substrate.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
README §6 claimed bidirectional forward-compat for journal records.
Reality is narrower:
- ProcessJobStore (kVersion=2) and SubstrateStore (kVersion=2) accept
v1 records on replay — their loaders explicitly switch on the version
byte and treat the v2 trailer fields as empty when absent. This is
the actual upgrade path the README half-described.
- ControlJobStore, CarrierStore, LoadPortStore, ExceptionStore, and
SpoolStore use strict `header[1] != kVersion` rejection. A future
kVersion bump there without a matching loader-side dispatch would
silently nuke every replayed record. The README sold this as a
feature; it isn't yet.
This commit adds:
- tests/test_persistence_upgrade.cpp: five cases that craft journal
records byte-by-byte so format drift is caught (no codec round-trip
hiding the field layout). PJ v1 -> v2 read; PJ v1 rewrite stamps
current kVersion=2; PJ unknown future version rejected; Substrate
v1 read with empty history trailer; CJ + Carrier reject unknown
versions (tripwire for the strict-version stores).
- README §6: replaces the rosy "newer versions ignore unknown
trailers" claim with what's actually implemented — multi-version
reads on PJ + Substrate, strict equality elsewhere — and points
at the test as the contract anchor.
When the strict-version stores grow their own v2, the rejection
tests will need to flip to acceptance; the layout is right there in
the test so the edit is mechanical.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
raphael