Module journal 

HADBJ (hadb journal) format for logical replication.

Ships opaque journal entries (rewritten queries, WAL records, etc.) with per-entry CRC32C + SHA-256 chain integrity. Supports sealed/unsealed lifecycle and optional zstd compression.

The entry payload is opaque bytes. Each engine defines its own payload format (e.g., graphstream uses protobuf Cypher entries).

Format

Header (128 bytes):
  magic(5) "HADBJ" | version(1) | flags(1) | compression(1)
  first_seq(8) | last_seq(8) | entry_count(8) | body_len(8)
  body_checksum(32) | prev_segment_checksum(8) | created_ms(8)
  reserved(32)

Body (variable):
  [entry_crc32c(4) | payload_len(4) | sequence(8) | prev_hash(32) | payload(payload_len)]*

Trailer (optional, 32 bytes when FLAG_HAS_CHAIN_HASH):
  chain_hash(32)   -- SHA-256 of last entry, enables O(1) recovery

Structs

JournalEntry

A single journal entry with opaque payload.

JournalHeader

Header for a journal segment.

JournalSegment

A complete sealed journal segment: header + entries + chain hash.

Constants

CHAIN_HASH_TRAILER_SIZE

Chain hash trailer size.

COMPRESSION_NONE

ENTRY_HEADER_SIZE

Per-entry fixed header: crc32c(4) + payload_len(4) + sequence(8) + prev_hash(32) = 48.

FLAG_COMPRESSED

FLAG_HAS_CHAIN_HASH

FLAG_SEALED

HADBJ_MAGIC

HADBJ_VERSION

HEADER_SIZE

Header size in bytes.

ZERO_HASH

Zero hash (32 bytes of zeros) used as prev_hash for the first entry.

Functions

build_entry_chain

Build a chain of journal entries from opaque payloads.

compute_entry_hash

Compute the chain hash for an entry: SHA-256(prev_hash || payload).

decode

Decode a sealed journal segment from bytes.

decode_entry

Decode a single journal entry from bytes at the given offset. Returns the entry and the number of bytes consumed.

decode_header

Decode a header from bytes.

encode

Encode a sealed journal segment to bytes.

encode_entry

Encode a single journal entry to bytes.

encode_header

Encode a header to bytes.

hash_to_u64

Truncate a SHA-256 hash to u64 (for prev_segment_checksum compatibility).

seal

Create a new sealed journal segment from entries.