Module layout 

Repository path layout: the single authority for resolving on-disk state under .mkit/ (issue #493, Phase 0).

Every piece of repository state is classified into exactly one of two directories:

• the common dir — state shared by every working tree of the repository: the object store, refs, config, signing keys, the history MMR, the recovery log, attestations, transport caches;
• the worktree state dir — state private to one working tree: HEAD, the staging index, in-progress-operation files (MERGE_HEAD, rebase-apply/, …), the stash, and the worktree lock.

In the classic single-worktree layout both directories are the same <root>/.mkit/, so RepoLayout::single produces byte-identical paths to the historical ad-hoc joins. In a linked working tree (#493 Phase 1) they differ: the linked tree’s per-tree state lives under the main repository’s .mkit/worktrees/<id>/, and the linked tree’s own .mkit is a plain FILE — the pointer file — instead of a directory. Nothing outside this module may assume the two directories coincide.

Linked-worktree on-disk model (#493 Phase 1)

<main>/.mkit/                       # common dir (shared state)
  worktrees/<id>/                   # one per linked tree
    commondir                       # path to the common dir, `../..`
    mkitdir                         # abs path of the tree's pointer file
    HEAD, index, ORIG_HEAD, ...     # per-tree state, as classified below
<linked-tree>/.mkit                 # pointer FILE, not a directory:
    `mkitdir: <path to .mkit/worktrees/<id>>\n`

The pointer path may be absolute or relative to the linked tree root; commondir may be absolute or relative to the state dir. Both files are UTF-8, single-line, LF-terminated, and capped at MAX_POINTER_FILE_BYTES. Discovery (discover) fails closed on any malformed or dangling pointer; a .mkit DIRECTORY (every pre-Phase-1 repository) always resolves to the single-worktree layout, byte-identical to before.

Classification table

Path (relative)	Class	Owner module
objects/	common	crate::store
format	common	crate::store
refs/ (+heads,tags,remotes)	common	crate::refs
shallow	common	crate::refs
config	common	CLI config
keys/	common	CLI config
history/	common	crate::history (feature-gated)
recovery-log	common	crate::ops::recovery
attestations/	common	mkit-attest
applied-packs/	common	CLI remote dispatch (redownload cache, never a gc root)
git/	common	mkit-git-bridge
sparse/	common	CLI sparse bitmap cache
pack-shards/	common	CLI pack-shard output
HEAD	worktree	crate::refs
index	worktree	crate::index
ORIG_HEAD	worktree	crate::ops::conflict_state
MERGE_HEAD/MERGE_MSG	worktree	crate::ops::conflict_state
CHERRY_PICK_HEAD/_MSG	worktree	crate::ops::conflict_state
REVERT_HEAD/_MSG	worktree	crate::ops::conflict_state
mkit-conflicts	worktree	crate::ops::conflict_state
MKIT_OP_RESULT	worktree	crate::ops::conflict_state
rebase-apply/	worktree	crate::ops::rebase
bisect	worktree	crate::ops::bisect
stash	worktree	crate::ops::stash
sparse-checkout	worktree	crate::ops::restore
worktree.lock	worktree	CLI lock helper

Rationale for the git-divergent entries: shallow is shared because it constrains the one shared object graph; the stash is per-worktree (unlike git’s refs/stash) because mkit’s stash is a worktree-state manifest, not a ref — #493 specifies stash as tree-local.

Invariants

• Both directories always end in a final .mkit component (a linked tree’s state dir will live under the main .mkit; that still satisfies the prefix rule below).
• Every accessor resolves strictly inside common_dir() or worktree_state_dir(); no accessor ever escapes them.
• RepoLayout::single guarantees common_dir() == worktree_state_dir() == worktree_root().join(".mkit").

Structs

RepoLayout

Resolved repository layout: worktree root plus the two state directories (see the module docs for the classification table).

WorktreeEntry

One entry of the linked-worktree registry (<common>/worktrees/*), as reported by worktrees.

Enums

DiscoverError

Errors surfaced by discover on a broken linked-worktree setup.

Constants

APPLIED_PACKS_DIR_NAME

Per-remote applied-pack record directory name under the common dir. A redownload-avoidance cache — never a gc root source (#409).

ATTESTATIONS_DIR_NAME

Attestation store directory name under the common dir.

BACKPOINTER_FILE_NAME

File inside a per-tree state dir recording the absolute path of the linked tree’s pointer file — the back-pointer worktree prune checks before deleting a state dir.

COMMONDIR_FILE_NAME

File inside a per-tree state dir recording the path back to the common dir (relative to the state dir, or absolute). Written as ../.. by worktree add.

CONFIG_FILE_NAME

Config file name under the common dir (written by the CLI).

GIT_STATE_DIR_NAME

Git-bridge per-remote state directory name under the common dir.

HISTORY_DIR_NAME

Commit-history MMR directory name under the common dir. Canonical here (rather than in crate::history) because that module is feature-gated while the layout is not; history::HISTORY_DIR re-points at this constant.

INDEX_FILE_NAME

Staging-index file name under the worktree state dir.

KEYS_DIR_NAME

Repository signing-key directory name under the common dir.

MAX_POINTER_FILE_BYTES

Hard cap on the pointer, commondir, and back-pointer files. Far above any real path, small enough that a corrupt or hostile file cannot balloon discovery.

PACK_SHARDS_DIR_NAME

Default pack-shard output directory name under the common dir.

POINTER_PREFIX

Prefix of the linked-tree pointer file (<tree>/.mkit as a FILE): mkitdir: <path>\n — the analog of git’s gitdir: file.

SPARSE_CACHE_DIR_NAME

Sparse bitmap-cache directory name under the common dir.

SPARSE_CHECKOUT_FILE_NAME

Sparse-checkout filter file name under the worktree state dir.

STASH_FILE_NAME

Stash manifest file name under the worktree state dir.

WORKTREES_DIR_NAME

Directory under the common dir holding one per-tree state dir per linked worktree.

Functions

all_state_layouts

Every per-tree STATE layout of the repository, for cross-worktree root collection (#493 Phase 3): the main tree first, then one layout per worktrees/<id> state dir that exists on disk — in deterministic order (main, then ids ascending), so multi-lock acquisition over the result cannot deadlock against itself.

discover

Resolve the RepoLayout for the repository whose working tree is rooted at worktree_root (#493 Phase 1 discovery).

validate_worktree_id

Validate a linked-worktree id (the worktrees/<id> directory name).

worktrees

Enumerate the linked-worktree registry of layout’s repository, sorted by id. The main worktree is NOT an entry — its state dir is the common dir itself.

write_pointer_file

Write the linked-tree pointer file: <tree>/.mkit containing mkitdir: <state_dir>\n. Used by worktree add (#493 Phase 2); public now so the format has exactly one writer and one reader.