mkit_core/
lib.rs

1// This attribute sits, identically, at the root of every library crate
2// (#441) and is deliberately NOT hoisted into `[workspace.lints.clippy]`:
3// manifest lint tables cannot cfg-gate, so a workspace-wide deny would hit
4// `#[cfg(test)]` code (which legitimately prints), and `mkit-rpc` declares
5// its own `[lints.clippy]` table (dropping workspace inheritance), so it
6// would silently escape a workspace-level deny. Scope is libraries only:
7// `mkit-cli` prints as its job, and `mkit-test-util` is dev-only test
8// infrastructure whose diagnostic prints are the point.
9#![cfg_attr(not(test), deny(clippy::print_stdout, clippy::print_stderr))]
10#![doc = include_str!("../README.md")]
11//!
12//! mkit-core — BLAKE3 hashing and canonical v1 object byte format.
13//!
14//! The byte layout implemented here is defined, normatively, in
15//! `docs/specs/SPEC-OBJECTS.md` (version `0x01`, magic `"MKT1"`). Any change
16//! to this crate MUST update the spec in the same PR.
17//!
18//! The library depends on `std` to keep the code readable. No `serde`,
19//! no `anyhow`, no panics on unchecked input.
20
21// `deny(unsafe_code)` rather than `forbid` so a small, justified set of
22// `#[allow(unsafe_code)]` callsites can call into libc. There are two
23// today: `sign::load_key` uses `libc::geteuid()` for the POSIX uid check,
24// and `batch::RealSyncer::file_barrier` uses `libc::fcntl(.., F_BARRIERFSYNC)`
25// on macOS/iOS. Every other module remains under the same prohibition; a
26// code-review gate (CONTRIBUTING) requires SAFETY notes on any new
27// `unsafe` block.
28#![deny(unsafe_code)]
29// `ed25519-dalek` v2.2 still pulls in older sha2/cpufeatures (and
30// rand_core 0.6 which transitively wants getrandom 0.2). These are
31// transitive duplicates we cannot dedupe without forking dalek; allow
32// them. cargo-deny still tracks them at warn level via deny.toml.
33#![allow(clippy::multiple_crate_versions)]
34
35pub mod batch;
36pub mod chunker;
37pub mod delta;
38pub mod hash;
39pub mod merkle;
40pub mod object;
41pub mod ops;
42pub mod pack;
43// Erasure-coded pack delivery (Reed-Solomon). Feature-gated because
44// the dep stack (`commonware-coding` + `commonware-cryptography` +
45// `commonware-parallel` + `commonware-storage`) is large and only
46// needed by the shard-aware transports — see
47// `docs/specs/SPEC-PACK-SHARDS.md`. Sibling of `pack`, not nested: the
48// on-disk pack format stays untouched; shards are a wire-level
49// encoding *of* a pack.
50#[cfg(feature = "pack-shards")]
51pub mod pack_shard;
52pub mod serialize;
53pub mod sign;
54pub mod store;
55pub mod transfer;
56
57// Repository path layout (issue #493 Phase 0): the single authority
58// for resolving state under `.mkit/`, splitting shared (common-dir)
59// from per-worktree state.
60pub mod layout;
61
62// Refs, index, worktree, ignore, and repo_lock.
63pub(crate) mod atomic;
64pub mod ignore;
65pub mod index;
66pub mod refs;
67pub mod repo_lock;
68pub mod worktree;
69
70// Transport trait surface (vtable + SSH framing + retry policy).
71pub mod protocol;
72
73// Issue #157 — append-only MMR over the commit chain for
74// O(log n) inclusion proofs. Feature-gated so the `commonware-storage`
75// dep tree only materialises for downstream callers that opt in.
76// Persisted (journaled) MMR is in this build; commit-field integration
77// is planned — see docs/specs/SPEC-HISTORY-PROOF.md.
78#[cfg(feature = "history-mmr")]
79pub mod history;
80
81// Verifiable sparse-checkout (issue #158). Feature-gated
82// because the upstream `commonware-storage::AuthenticatedBitMap` is
83// ALPHA-tier and pulls in `commonware-runtime` /
84// `commonware-cryptography`. Off by default.
85#[cfg(feature = "sparse-checkout")]
86pub mod sparse;
87
88#[cfg(feature = "sparse-checkout")]
89pub use sparse::{
90    MAX_FILTER_PATHS as SPARSE_MAX_FILTER_PATHS, MAX_LEAVES as SPARSE_MAX_LEAVES, SPARSE_CACHE_DIR,
91    SPARSE_CACHE_MAGIC, SPARSE_CACHE_VERSION, SPARSE_WIRE_MAGIC, SPARSE_WIRE_MAX_BYTES,
92    SPARSE_WIRE_VERSION, SparseError, SparseManifest, SparseProof, SparseResponse, SparseWireError,
93    build_sparse, decode_sparse_cache, decode_sparse_response, encode_sparse_cache,
94    encode_sparse_response, hash_filter, verify_sparse,
95};
96
97pub use hash::{HASH_LEN, HEX_LEN, Hash, Hasher, to_hex, to_hex_bytes};
98pub use object::{
99    Blob, ChunkedBlob, Commit, Delta, EntryMode, IDENTITY_MAX_LEN, Identity, IdentityKind, MAGIC,
100    MkitError, Object, ObjectType, Remix, RemixSource, SCHEMA_VERSION, TAG_NAME_MAX_LEN, Tag, Tree,
101    TreeEntry,
102};
103pub use serialize::{deserialize, serialize};
104pub use sign::{
105    COMMIT_DOMAIN, KeyPair, PublicKey, REMIX_DOMAIN, SecretSeed, Signature, TAG_DOMAIN,
106    commit_signing_bytes, commit_signing_hash, remix_signing_bytes, remix_signing_hash,
107    sign_commit, sign_remix, sign_tag, tag_signing_bytes, tag_signing_hash, verify, verify_commit,
108    verify_remix, verify_tag,
109};
110pub use store::{
111    MAX_RAW_OBJECT_SIZE, MAX_TREE_DEPTH, MKIT_DIR, OBJECTS_DIR, ObjectStore, StoreError,
112    StoreResult,
113};
114
115// Content-defined chunker (FastCDC v1).
116pub use chunker::{
117    AVG_SIZE as CHUNK_AVG_SIZE, ChunkBoundary, ChunkIterator, FastCdc, MASK_L as CHUNK_MASK_L,
118    MASK_S as CHUNK_MASK_S, MAX_SIZE as CHUNK_MAX_SIZE, MIN_SIZE as CHUNK_MIN_SIZE,
119    SEED as CHUNK_SEED, chunk_boundaries, gear_table_digest,
120};
121
122// Delta instruction stream (SPEC-DELTA v1).
123pub use delta::{HEADER_LEN as DELTA_HEADER_LEN, MAX_INSERT_LEN, OP_COPY, STREAM_VERSION};
124
125// Packfile reader/writer (SPEC-PACKFILE v1).
126pub use pack::{
127    HEADER_LEN as PACK_HEADER_LEN, MAGIC as PACK_MAGIC, MAX_ENTRIES as PACK_MAX_ENTRIES,
128    MAX_TOTAL_PAYLOAD as PACK_MAX_TOTAL_PAYLOAD, PackError, PackReader, PackWriter,
129    TRAILER_LEN as PACK_TRAILER_LEN, UnpackReport, VERSION as PACK_VERSION, pack_key,
130};
131
132// Refs, index, worktree, ignore, and repo_lock.
133pub use ignore::{IgnoreError, IgnoreList, MAX_IGNORE_FILE_BYTES, Pattern, glob_match};
134pub use index::{
135    EntryStatus, INDEX_FILE, Index, IndexEntry, IndexError, IndexResult, MAGIC as INDEX_MAGIC,
136    MAX_INDEX_BYTES, MAX_PATH_LEN, validate_index_path,
137};
138pub use layout::RepoLayout;
139pub use refs::{
140    HEAD_FILE, HEADS_DIR, Head, REFS_DIR, Ref, RefError, RefResult, RefWriteCondition,
141    SHALLOW_FILE, TAGS_DIR, decode_ref_wire, encode_ref_wire, validate_ref_name,
142    validate_ref_prefix,
143};
144pub use repo_lock::{DEFAULT_TIMEOUT as LOCK_DEFAULT_TIMEOUT, LockError, LockResult, RepoLock};
145pub use worktree::{
146    CHUNK_THRESHOLD, LoadedBlob, MAX_FILE_BYTES, WorktreeError, WorktreeResult, read_blob,
147    store_file_object, validate_symlink_target,
148};
149
150// Cross-transport types. The SSH-specific wire bytes live in
151// mkit-rpc's ssh.proto and are consumed by mkit-transport-ssh
152// directly.
153pub use protocol::{
154    AdvanceOutcome, BACKOFF_CAP, BACKOFF_INITIAL, BACKOFF_MAX_ATTEMPTS, BackoffIterator, PackKey,
155    Transport, TransportError, TransportResult, is_retryable, pack_key_from_hex,
156};
157
158// Ops re-exports (OPS1: diff/graph/merge/cherry_pick).
159// OPS2's rebase/bisect/blame/stash/restore are accessed via
160// `mkit_core::ops::{rebase, bisect, ...}` directly rather than re-exported
161// at the crate root — the submodule is typically the right import scope
162// for state-machine APIs.
163pub use ops::{
164    CherryPickError, CherryPickResult, Conflict, ConflictKind, DiffEntry, DiffError, DiffKind,
165    DiffResult, MergeResult, StatusEntry, StatusStaging, cherry_pick, collect_ancestor_set,
166    diff_trees, find_merge_base, is_ancestor, merge_trees, status_diff,
167};
mkit_core/lib.rs

mkit_core/
lib.rs
