Plan version-dependent deserialization strategy

[joaosreis]

Overview

Currently, the SCLS format has version information in the header record (Hdr), but there's no deserialization implementation yet. We need to plan how to make deserialization dependent on the file serialization version to ensure the system can handle multiple format versions gracefully.

Current State

• Version type exists (Cardano.SCLS.Internal.Version) with only V1 currently defined
• The Hdr record contains a version field that's written at the beginning of each file
• Serialization always uses V1 (see mkHdr in Hdr.hs:69-76)
• No deserialization implementation exists yet

Relevant Code

• scls-format/src/Cardano/SCLS/Internal/Version.hs - Version type definition
• scls-format/src/Cardano/SCLS/Internal/Record/Hdr.hs - Header record with version field
• scls-format/src/Cardano/SCLS/Internal/Serializer/Dump.hs:107 - TODO comment about parametrizing builder machine

Planning Tasks

This issue tracks the planning phase for version-dependent deserialization. The plan should address:

1. Architecture Design

   • How should version-specific deserialization be structured? (type classes, ADTs, functions?)
   • Should we use a versioned reader monad or dispatch on version at the top level?
   • How to handle backwards compatibility when adding new versions?

2. API Surface

   • What's the user-facing API for deserialization?
   • How should errors be reported when encountering unsupported versions?
   • Should we support reading multiple versions transparently?

3. Builder Machine Parametrization

   • The TODO at Dump.hs:107 suggests parametrizing the builder machine
   • How does this relate to version-dependent deserialization?
   • Should accumulator operations be customizable per version?

4. Testing Strategy

   • How to test deserialization across versions?
   • Should we maintain reference files for each version?
   • How to ensure version migration correctness?

5. Migration Path

   • How to handle format evolution (adding/removing fields)?
   • Should we support writing old versions or only the latest?
   • How to handle deprecated versions?

Acceptance Criteria

• Document architectural approach for version-dependent deserialization
• Define API for version-aware reading
• Outline testing strategy
• Identify necessary changes to existing serialization code
• Create follow-up implementation issues with concrete tasks

References

• Related to builder machine parametrization TODO in Dump.hs:107