File formats
mado’s binary formats are self-describing: each begins with a 4-byte ASCII magic and a version byte, and every format is ossified (a reader rejects a higher-than-known version with a typed error; a newer reader can still read the old version). This table lists each magic, a one-line description, and the module that owns its encoder/decoder.
| Magic | Name | Owning module | One-line description |
|---|---|---|---|
MDLP | Mado Locality Pack | crates/mado-filestore/src/pack.rs | A content-addressed bundle of a subtree’s inline files (and, in v2, chunked-file manifests + chunks as typed members), so one ranged GET hydrates a whole small-file subtree instead of one GET per file. |
MDPI | Mado Pack Index | crates/mado/src/pack_build.rs | The directory → covering-pack index a mado pack build records; content-addressed by the tree it describes. v1 = per-directory (exact match); v2 = recursive-subtree (ancestor-walk covering lookup). The daemon loads either version. |
MDPW | Mado Pack Well-known (pointer) | crates/mado/src/pack_publish.rs | The well-known derived discovery pointer — a tiny blob at a key derived from the tree id — that points at the freshest MDPI index for a tree, enabling zero-config pack discovery with no local file and no new RPC. |
MDFM | Mado File Manifest | crates/mado-filestore/src/manifest.rs | A chunked file’s manifest: the ordered content-defined-chunk list that reassembles a large file, plus its size (so file_size can stat without fetching content). |
MDSM | Mado Scratch Manifest | crates/mado-filestore/src/scratch.rs | The snapshot of a workspace’s scratch (off-snapshot build-dir) tree — the redirected paths and their content, captured for a checkpoint / pause. |
MDSP | Mado Scratch (manifest) Pointer | crates/mado/src/scratch.rs | A pointer record naming the freshest MDSM scratch-manifest blob (distinct from the MDSM manifest it points at). |
MDWC | Mado Workspace Checkpoint | crates/mado/src/scratch.rs | The durable checkpoint record binding a jj operation id, the scratch-manifest hash, and attr-table presence into one blob — the record mado ws pause / resume travel on. |
MDWL | Mado Workspace Lease (handoff) | crates/mado/src/ws.rs | A local, single-machine lease-handoff file (.jj/working_copy/ws-lease) recording the lease held by this workspace so a daemon and a mado ws command on the same box rendezvous on it. |
MDOJ | Mado Op Journal | crates/mado-server/src/journal.rs | An op-heads journal record in the blobstore’s opjournal namespace: every op-heads mutation is chained here (hash chain per scope) before it commits, so mado recover-op-heads can rebuild the op-heads database from blobs alone. |
Notes
- The magics
MDLP,MDSM,MDWC, andMDPIshare a v1 header layout (magic | version | encryption byte | …); the encryption byte reserves space for a future key-wrapping scheme and is currently a fixed marker. MDLPis grouping-agnostic: per-directory (v1) and recursive-subtree (v2) packs use the identical pack format — only the builder grouping, theMDPIindex semantics, and the trigger gate differ. See Performance § Locality packs.- These magics are the wire/at-rest contract; the store’s own at-rest format
(loose files vs the fjall LSM engine, and whether the production
Pack(zstd)/Prefix/Multiplexedcomposition wraps it) is a separate, orthogonal concern selected atmado init/mado servetime. A store’s at-rest format is recorded in ablobs-formatmarker inside.jj/repo/store(absent = the original loose-file layout).