Module pack 

Packfile writer / reader — conformant to docs/SPEC-PACKFILE.md.

Layout (SPEC-PACKFILE §1, §2, §3, §8):

[4B  magic            "MKIT"]                       offset 0
[4B  version u32 LE  == 1   ]
[4B  entry_count u32 LE     ]
  for each entry:
    [u8  entry_type]                                0x00 raw | 0x02 delta
    [u32 LE payload_len]                            length of payload only
    [payload_len bytes payload]
[32B trailer = BLAKE3 of all preceding bytes]

Entry types (SPEC-PACKFILE §3):

• 0x00 raw — payload is a fully serialised mkit object.
• 0x01 — RESERVED, MUST be rejected.
• 0x02 delta — payload is [32B base_hash][SPEC-DELTA stream].

Caps (SPEC-PACKFILE §5):

• entry_count <= 10_000_000
• total payload_len sum <= 4 GiB

Delta-base ordering rule (SPEC-PACKFILE §4): every delta entry’s base_hash MUST appear earlier in the same pack as a raw entry, OR already exist in the destination object store.

The pack key (SPEC-PACKFILE §7) is packs/<lower-hex BLAKE3 of entire pack>. The trailer is then redundant w.r.t. that key, but it lets a streaming reader detect bit-rot before the whole pack has been hashed end-to-end.

Structs

PackReader

Streaming-style packfile reader. Verifies header, trailer, entry framing, and the base-before-delta ordering rule. Reconstructs delta targets and writes every resolved object to store.

PackWriter

Builds a packfile in memory, enforcing entry/payload caps and recording entries in insertion order. Call Self::finish to obtain the final packfile bytes (header + entries + trailer).

UnpackReport

Result of an unpack: which entries were stored, plus a count of delta resolutions vs raw writes. Useful for transport/CLI summaries.

Enums

PackError

Packfile errors. Distinct from MkitError so callers can match on pack-specific failures (trailer mismatch, base-missing) without catching every object decode error.

Constants

ENTRY_FRAME_LEN

Per-entry framing overhead is [1B type][4B payload_len].

HEADER_LEN

Header is [4B magic][4B version][4B entry_count].

MAGIC

ASCII magic (“MKIT”) at the start of every v1 pack.

MAX_ENTRIES

Hard cap on entries (SPEC-PACKFILE §5).

MAX_TOTAL_PAYLOAD

Hard cap on the sum of payload bytes across all entries.

TRAILER_LEN

Trailer is a 32-byte raw BLAKE3 digest.

VERSION

Current packfile version. Reader rejects anything else.

Functions

pack_key

Compute the on-disk pack key: BLAKE3 of the entire packfile bytes (including the trailer). SPEC-PACKFILE §7. Returns the bare digest; callers prepend packs/ and lower-hex-encode for the storage path.