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 admission;
36pub mod batch;
37pub mod chunker;
38pub mod delta;
39pub mod hash;
40pub mod merkle;
41pub mod object;
42pub mod ops;
43pub mod pack;
44// Erasure-coded pack delivery (Reed-Solomon). Feature-gated because
45// the dep stack (`commonware-coding` + `commonware-cryptography` +
46// `commonware-parallel` + `commonware-storage`) is large and only
47// needed by the shard-aware transports — see
48// `docs/specs/SPEC-PACK-SHARDS.md`. Sibling of `pack`, not nested: the
49// on-disk pack format stays untouched; shards are a wire-level
50// encoding *of* a pack.
51#[cfg(feature = "pack-shards")]
52pub mod pack_shard;
53pub mod serialize;
54pub mod sign;
55pub mod store;
56pub mod transfer;
57// BLAKE3 subtree hashing for resumable part uploads
58// (SPEC-TRANSPORT-CONNECT §7.6). Pure and wasm-safe.
59pub mod upload_parts;
60// Partial-disclosure verification: prove and verify that a path, chunk, or
61// byte range belongs to a commit id, with no store access and no trust
62// beyond the id itself (issue #1015 verifier kit PR 2). `default-features
63// = false` wasm-safe, builder included: `build_disclosure_from` reads through
64// any verifying `store::ObjectSource`; `build_disclosure` wraps `ObjectStore`.
65pub mod verify;
66pub mod write_auth;
67
68// Repository path layout (issue #493 Phase 0): the single authority
69// for resolving state under `.mkit/`, splitting shared (common-dir)
70// from per-worktree state.
71pub mod layout;
72
73// Refs, index, worktree, ignore, and repo_lock.
74pub(crate) mod atomic;
75pub mod ignore;
76pub mod index;
77pub mod refs;
78// SPEC-TRANSPORT-CONNECT §7.4 repository identity grammar (namespaces and
79// names), shared by server addressing and the grant codec.
80pub mod repo_identity;
81pub mod repo_lock;
82pub mod worktree;
83
84// Transport trait surface (vtable + SSH framing + retry policy).
85pub mod protocol;
86
87// Issue #157 — append-only MMB (Merkle Mountain Belt) over the commit
88// chain for O(log n) inclusion proofs. Feature-gated so the
89// `commonware-storage` dep tree only materialises for downstream callers
90// that opt in. Persisted (journaled) MMB is in this build; commit-field
91// integration is planned — see docs/specs/SPEC-HISTORY-PROOF.md.
92#[cfg(feature = "history-mmr")]
93pub mod history;
94
95// Verifiable sparse-checkout (issue #158). Feature-gated
96// because the upstream `commonware-storage::AuthenticatedBitMap` is
97// ALPHA-tier and pulls in `commonware-runtime` /
98// `commonware-cryptography`. Off by default.
99#[cfg(feature = "sparse-checkout")]
100pub mod sparse;
101
102#[cfg(feature = "sparse-checkout")]
103pub use sparse::{
104    MAX_FILTER_PATHS as SPARSE_MAX_FILTER_PATHS, MAX_LEAVES as SPARSE_MAX_LEAVES, SPARSE_CACHE_DIR,
105    SPARSE_CACHE_MAGIC, SPARSE_CACHE_VERSION, SPARSE_WIRE_MAGIC, SPARSE_WIRE_MAX_BYTES,
106    SPARSE_WIRE_VERSION, SparseError, SparseManifest, SparseProof, SparseResponse, SparseWireError,
107    VerifiedSparseTree, build_sparse, decode_sparse_cache, decode_sparse_response,
108    encode_sparse_cache, encode_sparse_response, hash_filter, verify_sparse,
109};
110
111pub use hash::{HASH_LEN, HEX_LEN, Hash, Hasher, to_hex, to_hex_bytes};
112pub use object::{
113    Blob, ChunkedBlob, Commit, Delta, EntryMode, IDENTITY_MAX_LEN, Identity, IdentityKind, MAGIC,
114    MkitError, Object, ObjectType, Remix, RemixSource, SCHEMA_VERSION, TAG_NAME_MAX_LEN, Tag, Tree,
115    TreeEntry,
116};
117pub use serialize::{deserialize, serialize};
118pub use sign::{
119    COMMIT_DOMAIN, KeyPair, PublicKey, REMIX_DOMAIN, SecretSeed, Signature, TAG_DOMAIN,
120    commit_signing_bytes, commit_signing_hash, remix_signing_bytes, remix_signing_hash,
121    sign_commit, sign_remix, sign_tag, tag_signing_bytes, tag_signing_hash, verify, verify_commit,
122    verify_object_signature, verify_remix, verify_tag,
123};
124pub use store::{
125    MAX_RAW_OBJECT_SIZE, MAX_TREE_DEPTH, MKIT_DIR, OBJECTS_DIR, ObjectStore, StoreError,
126    StoreResult,
127};
128
129// Content-defined chunker (FastCDC v1).
130pub use chunker::{
131    AVG_SIZE as CHUNK_AVG_SIZE, ChunkBoundary, ChunkIterator, FastCdc, MASK_L as CHUNK_MASK_L,
132    MASK_S as CHUNK_MASK_S, MAX_SIZE as CHUNK_MAX_SIZE, MIN_SIZE as CHUNK_MIN_SIZE,
133    SEED as CHUNK_SEED, chunk_boundaries, gear_table_digest,
134};
135
136// Delta instruction stream (SPEC-DELTA v1).
137pub use delta::{
138    DeltaCorruption, HEADER_LEN as DELTA_HEADER_LEN, MAX_INSERT_LEN, OP_COPY, STREAM_VERSION,
139};
140
141// Packfile reader/writer (SPEC-PACKFILE v1).
142pub use pack::{
143    DecodeLimits, DecodeReport, DecodedEntry, DeltaBaseSource, HEADER_LEN as PACK_HEADER_LEN,
144    MAGIC as PACK_MAGIC, MAX_ENTRIES as PACK_MAX_ENTRIES,
145    MAX_TOTAL_PAYLOAD as PACK_MAX_TOTAL_PAYLOAD, NoExternalBases, PackEntries, PackEntry,
146    PackError, PackReader, PackWriter, TRAILER_LEN as PACK_TRAILER_LEN, UnpackReport,
147    VERSION as PACK_VERSION, decode_entries_with, pack_key,
148};
149
150// Refs, index, worktree, ignore, and repo_lock.
151pub use ignore::{IgnoreError, IgnoreList, MAX_IGNORE_FILE_BYTES, Pattern, glob_match};
152pub use index::{
153    EntryStatus, INDEX_FILE, Index, IndexEntry, IndexError, IndexResult, MAGIC as INDEX_MAGIC,
154    MAX_INDEX_BYTES, MAX_PATH_LEN, validate_index_path,
155};
156pub use layout::RepoLayout;
157pub use refs::{
158    BRANCH_REF_PREFIX, HEAD_FILE, HEADS_DIR, Head, MAX_BRANCH_NAME_BYTES, MAX_REF_NAME_BYTES,
159    MAX_TAG_NAME_BYTES, PACKMAP_REF_PREFIX, REFS_DIR, Ref, RefError, RefNameKind, RefResult,
160    RefWriteCondition, SHALLOW_FILE, TAG_REF_PREFIX, TAGS_DIR, check_new_name, check_new_ref_name,
161    check_pushable_branch, decode_ref_wire, encode_ref_wire, validate_ref_name,
162    validate_ref_name_grammar, validate_ref_prefix,
163};
164pub use repo_lock::{DEFAULT_TIMEOUT as LOCK_DEFAULT_TIMEOUT, LockError, LockResult, RepoLock};
165pub use worktree::{
166    CHUNK_THRESHOLD, LoadedBlob, MAX_FILE_BYTES, WorktreeError, WorktreeResult, read_blob,
167    store_file_object, validate_symlink_target,
168};
169
170// Cross-transport types. The SSH-specific wire bytes live in
171// mkit-rpc's ssh.proto and are consumed by mkit-transport-ssh
172// directly.
173pub use protocol::{
174    AdvanceOutcome, BACKOFF_CAP, BACKOFF_INITIAL, BACKOFF_MAX_ATTEMPTS, BackoffIterator,
175    CommitOutcome, PackKey, Transport, TransportError, TransportResult, UploadLimits, is_retryable,
176    pack_key_from_hex,
177};
178
179// Ops re-exports (OPS1: diff/graph/merge/cherry_pick).
180// OPS2's rebase/bisect/blame/stash/restore are accessed via
181// `mkit_core::ops::{rebase, bisect, ...}` directly rather than re-exported
182// at the crate root — the submodule is typically the right import scope
183// for state-machine APIs.
184pub use ops::{
185    CherryPickError, CherryPickResult, ClosureMode, Conflict, ConflictKind, DiffEntry, DiffError,
186    DiffKind, DiffResult, MergeResult, StatusEntry, StatusStaging, cherry_pick, children,
187    collect_ancestor_set, diff_trees, find_merge_base, is_ancestor, merge_trees, reachable_closure,
188    reachable_objects, reachable_snapshot, status_diff,
189};
mkit_core/lib.rs

mkit_core/
lib.rs
