raphael/secs-gem
Public Access
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

persistence: multi-version reads across every store

Browse Source 
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>
This commit is contained in:
Raphael Maenle
2026-06-09 14:53:05 +02:00
parent ce5abb4f72
commit e3765a5176
6 changed files with 98 additions and 31 deletions
Download Patch File Download Diff File Expand all files Collapse all files
include/secsgem/gem/store/carriers.hpp
+15 -6
View File
@@ -184,11 +184,15 @@ class CarrierStore {
CarrierAccessStatus acc_state;
};
// Carrier record layout, big-endian throughout:
// [u8 magic = 0xC4][u8 version = 1]
// Carrier record (v1), big-endian throughout:
// [u8 magic = 0xC4][u8 version]
// [u8 id_state][u8 sm_state][u8 acc_state][u8 port_id]
// [u16 slot_count][slot_count × u8 slot.state]
// [u16 cid_len][cid_len × u8 carrierid]
//
// Upgrade discipline (mirrors PJ/Substrate): loader accepts any
// version in [1, kVersion]; future field additions go at the end
// and are gated behind `if (version >= N)` blocks.
static constexpr uint8_t kMagic = 0xC4;
static constexpr uint8_t kVersion = 0x01;
@@ -266,7 +270,8 @@ class CarrierStore {
if (!in) return std::nullopt;
uint8_t header[6];
in.read(reinterpret_cast<char*>(header), sizeof(header));
if (!in || header[0] != kMagic || header[1] != kVersion) return std::nullopt;
if (!in || header[0] != kMagic ||
header[1] < 1 || header[1] > kVersion) return std::nullopt;
Record r;
r.id_state = static_cast<CarrierIDStatus>(header[2]);
r.sm_state = static_cast<SlotMapStatus>(header[3]);
@@ -418,10 +423,13 @@ class LoadPortStore {
LoadPortAssociationStatus as_state;
};
// Load-port record:
// [u8 magic = 0xC5][u8 version = 1]
// Load-port record (v1):
// [u8 magic = 0xC5][u8 version]
// [u8 port_id][u8 tx_state][u8 rs_state][u8 as_state]
// [u16 cid_len][cid_len × u8 carrierid]
//
// Upgrade discipline: loader accepts any version in [1, kVersion];
// future fields append at the end behind an `if (version >= N)` gate.
static constexpr uint8_t kMagic = 0xC5;
static constexpr uint8_t kVersion = 0x01;
@@ -492,7 +500,8 @@ class LoadPortStore {
if (!in) return std::nullopt;
uint8_t header[6];
in.read(reinterpret_cast<char*>(header), sizeof(header));
if (!in || header[0] != kMagic || header[1] != kVersion) return std::nullopt;
if (!in || header[0] != kMagic ||
header[1] < 1 || header[1] > kVersion) return std::nullopt;
Record r;
r.port_id = header[2];
r.tx_state = static_cast<LoadPortTransferState>(header[3]);