///|
/// Semantic record kinds supported by the transactional journal.
pub(all) enum RecordKind {
  Begin
  Put
  Delete
  Commit
  Abort
  Checkpoint
} derive(Debug, Eq)

///|
/// One decoded journal record.
pub(all) struct JournalRecord {
  kind : RecordKind
  sequence : UInt
  transaction : UInt
  payload : Bytes
} derive(Debug, Eq)

///|
/// Outcome category for bounded, non-throwing record decoding.
pub(all) enum DecodeStatus {
  Decoded
  NeedMoreData
  Corrupt
  Unsupported
} derive(Debug, Eq)

///|
/// Result of decoding one record at a byte offset.
pub(all) struct DecodeResult {
  status : DecodeStatus
  record : JournalRecord?
  next_offset : Int
  message : String
} derive(Debug, Eq)

///|
/// Why a journal scan stopped.
pub(all) enum ScanStop {
  CleanEnd
  TruncatedTail
  Corruption
  UnsupportedVersion
  SequenceViolation
  RecordLimit
} derive(Debug, Eq)

///|
/// Result of scanning a byte stream up to its last trusted boundary.
pub(all) struct ScanResult {
  records : Array[JournalRecord]
  valid_bytes : Int
  total_bytes : Int
  stop : ScanStop
  fault_offset : Int
  message : String
} derive(Debug, Eq)

///|
/// A committed state change reconstructed from the journal.
pub(all) enum MutationKind {
  PutValue
  DeleteKey
} derive(Debug, Eq)

///|
/// One key mutation associated with its transaction and source sequence.
pub(all) struct Mutation {
  transaction : UInt
  sequence : UInt
  kind : MutationKind
  key : Bytes
  value : Bytes
} derive(Debug, Eq)

///|
/// Bounded result of decoding a put or delete payload.
pub(all) struct MutationDecode {
  valid : Bool
  mutation : Mutation?
  message : String
} derive(Debug, Eq)

///|
/// A semantic journal problem that does not compromise byte-level framing.
pub(all) struct RecoveryIssue {
  code : String
  sequence : UInt
  transaction : UInt
  message : String
} derive(Debug, Eq)

///|
/// Deterministic replay plan produced from a trusted record prefix.
pub(all) struct RecoveryPlan {
  actions : Array[Mutation]
  committed_transactions : Int
  aborted_transactions : Int
  incomplete_transactions : Array[UInt]
  checkpoint_sequence : UInt
  issues : Array[RecoveryIssue]
  recoverable : Bool
} derive(Debug, Eq)

///|
/// Immutable metadata for one planned journal segment.
pub(all) struct SegmentMeta {
  id : UInt
  first_sequence : UInt
  last_sequence : UInt
  record_count : Int
  byte_size : Int
} derive(Debug, Eq)

///|
/// Result of deterministic journal rotation planning.
pub(all) struct SegmentPlan {
  segments : Array[SegmentMeta]
  total_records : Int
  total_bytes : Int
  valid : Bool
  message : String
} derive(Debug, Eq)

///|
/// Aggregate evidence from cutting a journal at every byte position.
pub(all) struct CrashSweepReport {
  cuts_checked : Int
  exact_prefixes : Int
  unsafe_replays : Int
  passed : Bool
} derive(Debug, Eq)

///|
/// Aggregate evidence from flipping every individual bit in a byte stream.
pub(all) struct CorruptionSweepReport {
  bits_checked : Int
  corruptions_detected : Int
  undetected : Int
  passed : Bool
} derive(Debug, Eq)