Specified down to the byte
Every format mkit writes to disk or the wire has a specification, and this page indexes all of them. The documents are the contract: you can build a compatible implementation from them alone, without reading the Rust source. Each entry links to the full text under docs/specs/ in the repository.
Each status token comes verbatim from the document’s front matter and combines two axes (defined in SPEC-CONVENTIONS): maturity — draft behavior is still changing or has a called-out gap, stable behavior changes only with a version bump — and bindingness — normative means interop depends on conforming, advisory means local-only guidance.
Objects and hashing
How bytes become content-addressed objects: layouts, Merkle identity, chunking, and deltas.
SPEC-OBJECTS stable
The on-disk byte layout of every object type (blob, tree, commit, remix, chunked blob, delta, tag) over 32-byte BLAKE3 IDs. External tools can produce and consume these bytes from this document alone.
SPEC-MERKLE-OBJECTS stable-normative
The Binary Merkle Tree construction behind tree and chunked-blob object IDs: a matching root proves every child present and correctly ordered.
SPEC-FASTCDC stable
Deterministic content-defined chunking for large files: the gear table, chunking parameters, and the contract that keeps chunked-blob hashes identical across producers.
SPEC-DELTA stable
The byte layout of the delta instruction stream inside packfile delta entries, with a version byte so readers reject streams they do not understand.
Repository state
What lives inside .mkit/: refs, the staging index, linked worktrees, lock order, and garbage collection.
SPEC-REFS draft
Ref names, the 65-byte ref wire format, on-disk storage, and the exact semantics of prefix listing and conditional (compare-and-swap) updates across transports.
SPEC-INDEX stable-advisory
The on-disk layout of the staging area: paths staged for the next commit, plus a stat cache that proves a worktree file unchanged without rereading it. Local-only, never exchanged between peers.
SPEC-WORKTREE draft-normative
Linked working trees: the split between shared and per-tree state, pointer files, the worktree registry, repository discovery, and cross-worktree locking.
SPEC-CONCURRENCY draft-normative
The one total acquisition order across every lock an mkit process takes, so two processes can never grab the same two locks in opposite order.
SPEC-GC stable-normative
Garbage collection and recovery: the complete retention-root set that makes pruning safe, and the recovery log that keeps amended or reset tips reachable for a grace period.
Packs and transport
How objects move between repositories: the packfile container, erasure-coded delivery, and the transport protocols.
SPEC-PACKFILE stable
The packfile container for object exchange (v1 and v2): header framing, entry types, per-entry zstd compression, and a BLAKE3 trailer as defense against bit rot.
SPEC-PACK-SHARDS stable-normative
Reed-Solomon erasure coding over pack delivery: any N of N plus K shards reconstruct the pack, so lossy networks and partial caches still complete a transfer.
SPEC-TRANSPORT stable-normative
The cross-transport contract for the verbs every transport implements (memory, file, HTTP, S3, SSH): URL parsing, authentication, size caps, retry policy, and the error taxonomy.
SPEC-TRANSPORT-CONNECT draft-normative
The mkit.transport.v1 Connect service, the canonical remote protocol behind mkit+https: proto shape, verb-to-trait mapping, compare-and-swap semantics, and streaming pack transfer.
SPEC-TRANSPORT-ENC draft
A self-contained encrypted transport (mkit+enc) that exchanges the same frames as the SSH transport over an authenticated, encrypted TCP stream instead of an ssh child process.
SPEC-SPARSE-CHECKOUT draft
Verifiable server-side sparse checkout over HTTP and S3: the server ships only the requested subtree, and proofs let the client tell "filtered as asked" from "withheld".
Security and signing
The signature and attestation machinery: signing bytes, key storage, config trust boundaries, and verifiable history.
SPEC-SIGNING stable-normative
The exact bytes an Ed25519 signature covers on a commit, remix, or tag, and the BLAKE3 domain separation that stops a signature in one domain from validating in another.
SPEC-KEYSTORE stable-normative
The signing-key vault behind mkit key: software, OS-native, and hardware-backed storage under one interface, with honest capability reporting throughout.
SPEC-CONFIG-SECURITY normative
The repo-vs-user config trust split: which keys a cloned repository may set and which stay user-only, so a hostile repo never reaches your signing identity or credentials.
SPEC-ATTESTATIONS draft
Native attestations as in-toto v1 Statements in DSSE envelopes: on-disk layout, wire envelope, signing contract, and CLI. Off-the-shelf in-toto tooling can consume the signed bytes.
SPEC-RELEASE-THRESHOLD draft-normative
BLS12-381 threshold signatures for releases: M-of-N maintainer shares recover a single signature that verifiers check against one aggregated public key.
SPEC-HISTORY-PROOF draft-normative
An append-only Merkle Mountain Range over each branch, with inclusion proofs so a light client verifies that a commit belongs to a branch without walking its history.
Interop and subprocess protocols
The wire contracts mkit speaks with other systems: git bridges in both directions, external signers, and the shared RPC framing.
SPEC-GIT-BRIDGE draft-normative
Deterministic mkit-to-git export: any two implementations translating the same history produce byte-identical git objects, with mkit-only fields carried in commit headers.
SPEC-GIT-IMPORT draft-normative
Importer-signed git-to-mkit translation: every imported commit is a new object signed by the importer, attributing the original author and binding the git bytes as provenance.
SPEC-EXTERNAL-SIGNER draft
The subprocess protocol for out-of-process signers (HSM, Secure Enclave, TPM, WebAuthn): invocation, capability discovery, authentication round-trips, and error semantics.
SPEC-RPC stable-normative
The length-prefixed protobuf framing shared by every mkit subprocess protocol; external signers and the SSH transport speak the same wire.
Spec conventions
How the corpus itself is written and read.
SPEC-CONVENTIONS stable-normative
Shared vocabulary for the corpus: RFC 2119 keywords, the status tokens shown on this page, wire-encoding notation, and golden-vector citation rules.