wal

type ApplyCallbackFn func(lsn uint64, tstamp int64, key, value []byte) error

type Header struct {
	// Write-Ahead Log magic number.
	//
	// This equates to the string `WALX`.
	Magic uint32

	// File format version number.
	Version uint32

	// Features.
	Features uint64

	// When the write-ahead log was created.
	CreatedAt time.Time
}

type Policy struct {
	// SyncEveryBytes: fsync after this many bytes appended since the
	// last sync.
	//
	// 0 disables byte-based syncing (only time-based or explicit
	// sync/reset/close).
	SyncEveryBytes int64

	// SyncEvery: also fsync on this cadence if there is unsynced data.
	//
	// 0 disables time-based syncing.
	SyncEvery time.Duration

	// Maximum size of a value in bytes.
	MaxValueBytes uint32

	// Maximum size of a key in bytes.
	MaxKeyBytes uint32
}

type WriteAheadLog interface {
	// Append writes one record to the log.
	//
	// Errors:
	//   • ErrKeyTooLarge / ErrValueTooLarge / ErrRecordTooLarge when
	//     limits are exceeded.
	//   • ErrTimestampNegative / ErrTimestampTooBig for invalid
	//     timestamps.
	//   • I/O errors wrapped with stack context
	//
	// Durability:
	//   • Subject to Policy; may buffer in page cache until
	//     SyncEvery/SyncEveryBytes hit.
	//   • Call Sync() to force durability.
	Append(lsn uint64, tstamp int64, key, value []byte) error

	// Replay re-applies records with LSN > baseLSN in log order.
	//
	// The supplied callback is invoked for each record; if the callback
	// returns an error, replay aborts and that error is returned. On
	// success, the returned uint64 is the highest LSN applied.
	//
	// Robustness:
	//   • Stops at first malformed/incomplete/CRC-mismatched record
	//     (treats as a safely truncatable tail). Earlier valid records
	//     are preserved.
	Replay(baseLSN uint64, applyCb ApplyCallbackFn) (uint64, error)

	// SetPolicy atomically updates durability and size limits at runtime.
	//
	// Notes:
	//   • Time-based flushing may start/stop a background ticker.
	//   • Limits (MaxKeyBytes/MaxValueBytes) apply to subsequent appends
	//     only.
	SetPolicy(Policy)

	// Sync forces an fsync if there are dirty bytes; otherwise it is a
	// no-op.
	//
	// Returns any I/O error encountered.
	Sync() error

	// Reset truncates the log back to just the header (discarding all
	// records), then fsyncs.
	//
	// Use with care.
	Reset() error

	// Close stops background flushing, flushes if dirty, and closes the
	// file.
	//
	// Returns any flush/close error encountered. Close is
	// idempotent-safe to call once; do not use the instance after Close.
	Close() error
}