Module transfer 

Transfer-layer helpers: delta-aware pack planning and the packlist discovery wire format.

These sit ABOVE the on-disk pack format (SPEC-PACKFILE / SPEC-DELTA) and below the transport. The push path uses plan_pack to decide which objects of a ref’s closure to send, and how — raw, or as a delta against a base the remote already holds. The plan is then serialised with crate::pack::PackWriter into one or more packs — split when the plan’s payload exceeds a single pack’s cap (issue #831; the CLI’s remote_dispatch::build_and_upload_packs owns the splitting) — each keyed by its own BLAKE3 digest.

Because a delta-encoded pack is keyed by the pack digest (not by the reconstructed object’s hash), the fetch side can no longer find it by walking object hashes. Each push records a PackListNode — this module’s small versioned wire format — holding the pack(s) it added plus a prev pointer to the previous node, forming a per-branch chain. The push side advertises the chain head through a refs/mkit/packmap/<branch> metadata ref whose value is the BLAKE3 of the head node (itself stored as a pack object). The fetch side reads that ref, walks the chain, and unpacks every pack oldest-first. Chaining keeps each push O(1) on the wire rather than re-uploading the whole history’s list.

Content addressing is unchanged: delta is a transfer encoding only. The reconstructed object’s id (BLAKE3 of its canonical bytes, or the merkle BMT root for a Tree/ChunkedBlob — see crate::merkle) is re-verified by PackReader before storing.

Structs

PackListNode

A single node in a branch’s packlist chain.

PackPlan

A deterministic plan for the pack(s) a push uploads for one ref — serialised into a single pack when it fits under the payload cap, or split across several when it doesn’t (issue #831).

PlannedDelta

One delta entry in a PackPlan: a target object encoded against a base the remote already holds.

Enums

PackListError

Errors decoding a PackListNode blob.

Constants

PACKLIST_MAGIC

ASCII magic at the start of every packlist node (“mkit pack list”).

PACKLIST_MAX_ENTRIES

Hard cap on packs recorded in a single node — a normal push records one; refuse to allocate unboundedly on a malformed blob.

PACKLIST_VERSION

Current packlist version. Readers reject anything else so a future format change is a loud error, not a silent misparse.

Functions

decode_packlist

Parse a packlist node blob.

encode_packlist

Serialise one packlist node: the MKPL/version guard header followed by the prev/packs body encoded with commonware-codec (idiomatic Option + Vec).

plan_pack

Plan the pack for pushing new_tip to a remote whose current tip is old_tip (None for a first push or a remote we cannot diff against).

select_chunk_delta_bases

Choose, for each changed FastCDC chunk or small blob in new_tip, a base object from old_tip to delta against.