Format and protocol specifications
Object formats, repository state, and communication protocols.
Check each document’s status and implementation notes before relying on it. Each entry links to the full text in the repository’s docs/specs/ directory.
Each document declares its status in front matter. SPEC-CONVENTIONS defines two maturity terms: draft content may change or have documented gaps; stable behavior changes only with a version change.
The requirement level is separate. normative content defines requirements for compatible implementations. advisory content provides local guidance.
Objects and hashing
How bytes become content-addressed objects: layouts, Merkle identity, chunking, and deltas.
SPEC-OBJECTS(opens in a new tab) 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(opens in a new tab) 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(opens in a new tab) 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(opens in a new tab) 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.
SPEC-DISCLOSURE(opens in a new tab) draft-normative
Partial-disclosure bundles and closure-profile verification: a few KiB of proof show that a path, chunk, or byte range belongs to a commit, or that a served set is that commit's full content.
Repository state
State stored in .mkit/: refs, the staging index, linked worktrees, lock order, and garbage collection.
SPEC-REFS(opens in a new tab) 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(opens in a new tab) stable-advisory
The on-disk layout of the staging area: paths staged for the next commit, plus a stat cache that checks file metadata without rereading the contents. Local-only, never exchanged between peers.
SPEC-WORKTREE(opens in a new tab) 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(opens in a new tab) draft-normative
The order in which all mkit processes must acquire locks to prevent deadlocks.
SPEC-GC(opens in a new tab) 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(opens in a new tab) stable
The packfile container for object exchange (v1 and v2): header framing, entry types, per-entry zstd compression, and a BLAKE3 trailer to detect corruption.
SPEC-PACK-SHARDS(opens in a new tab) stable-normative
Reed-Solomon erasure coding over pack delivery: any N of the N + K shards reconstruct the pack, so a transfer completes over lossy networks or from partial caches.
SPEC-TRANSPORT(opens in a new tab) 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(opens in a new tab) draft-normative
The mkit.transport.v1 Connect service, the canonical remote protocol behind mkit+https: multi-repository addressing, namespace and write policy, compare-and-swap semantics, and resumable, ticketed pack uploads.
SPEC-SERVER(opens in a new tab) draft-normative
Server pipeline guarantees beside the wire protocol: durable outcomes, storage leases, garbage collection, takedown notices, and the authenticated remote-hook contract a deployment implements.
SPEC-HTTP-OBJECTS(opens in a new tab) draft-normative
Plain HTTP object serving: repository selection, published-view access, read authorization, and disclosure proofs over immutable object URLs.
SPEC-TRANSPORT-ENC(opens in a new tab) 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(opens in a new tab) draft
Verifiable sparse checkout over HTTP and S3: the server sends the requested subtree, and the client verifies its completeness with proofs.
Security and signing
Signatures and attestations: signing bytes, key storage, config trust boundaries, and verifiable history.
SPEC-SIGNING(opens in a new tab) 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(opens in a new tab) stable-normative
Signing-key storage for mkit key: software, OS-native, and hardware-backed implementations, with supported capabilities reported through one interface.
SPEC-WRITE-GRANTS(opens in a new tab) draft-normative
Owner-signed grants that let an Ed25519 key write to, or read from, a namespace's repositories: wallet and passkey owner signatures, ref scopes, exact-epoch revocation, and private repositories with signed reads.
SPEC-CONFIG-SECURITY(opens in a new tab) normative
The config trust split between repository and user: which keys a repository may set and which are user-only, so a cloned repository cannot change your signing identity or access your credentials.
SPEC-ATTESTATIONS(opens in a new tab) 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(opens in a new tab) 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(opens in a new tab) draft-normative
An append-only Merkle Mountain Belt 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
Protocols for Git import and export, external signers, and subprocess RPC.
SPEC-GIT-BRIDGE(opens in a new tab) 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(opens in a new tab) 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(opens in a new tab) 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(opens in a new tab) stable-normative
The length-prefixed protobuf framing shared by every mkit subprocess protocol; external signers and the SSH transport use the same framing.
Spec conventions
How to write and read the specifications.
SPEC-CONVENTIONS(opens in a new tab) stable-normative
Shared vocabulary for the specifications: RFC 2119 keywords, the status tokens shown on this page, wire-encoding notation, and golden-vector citation rules.