1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
//! # Quilt Data Package Management System
//!
//! Quilt provides Git-like version control semantics for data files through content-addressed
//! storage with immutable objects and distributed collaboration via remote storage backends.
//!
//! ## Quick Start
//!
//! For all operations instantiate `LocalDomain` and then call some of its methods.
//!
//! ```rust
//! use std::path::PathBuf;
//! use quilt_rs::{LocalDomain, uri::{S3PackageUri, ManifestUri}};
//!
//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
//! // Create a local domain for package management
//! let path = PathBuf::from("/foo/bar");
//! let local_domain = LocalDomain::new(path);
//!
//! // Create a manifest URI from a package URI
//! let package_uri = S3PackageUri::try_from("quilt+s3://bucket#package=namespace@hash")?;
//! let manifest_uri = ManifestUri::try_from(package_uri)?;
//!
//! // Install the package
//! let installed_package = local_domain.install_package(&manifest_uri).await?;
//! # Ok(())
//! # }
//! ```
//!
//! ## Architecture Overview
//!
//! ### Content-Addressed Storage
//!
//! Quilt operates on the principle of **content-addressed storage** where files are identified
//! by their cryptographic hash rather than location. This enables:
//!
//! - **Immutable objects**: Once created, objects never change
//! - **Deduplication**: Identical content stored once regardless of logical paths
//! - **Integrity verification**: Content verified against cryptographic hashes
//! - **Distributed collaboration**: Content shared across storage locations
//!
//! ### Directory Structure
//!
//! The `.quilt` directory serves as the local repository:
//!
//! ```text
//! .quilt/
//! ├── packages/ # Cached manifests from remote
//! │ └── <bucket>/<hash>
//! ├── installed/ # Local package installations
//! │ └── <namespace>/<hash>
//! ├── objects/ # Content-addressed object store
//! │ └── <sha256> # Immutable data files
//! └── lineage.json # Package tracking and commit history
//! ```
//!
//! ### Key Concepts
//!
//! - **ManifestRow**: Represents a file with `logical_key` (virtual path) and `physical_key` (storage location)
//! - **Manifest**: Collection of ManifestRows describing a complete package state
//! - **PackageLineage**: Tracks installation history, modifications, and commits
//! - **Physical Keys**:
//! - `file:///path/to/objects/hash` for local storage (before push)
//! - `s3://bucket/path` for remote storage (after push)
//!
//! ### Workflow Stages
//!
//! 1. **Browse**: Discover remote packages (`flow::browse`)
//! 2. **Install**: Register package tracking (`flow::install_package`)
//! 3. **Install Paths**: Download content to working directory (`flow::install_paths`)
//! 4. **Status**: Detect modifications (`flow::status`)
//! 5. **Commit**: Create local package version (`flow::commit_package`)
//! 6. **Push**: Upload changes to remote (`flow::push_package`)
//!
//! ### Manifest Formats
//!
//! Manifests are stored in JSONL format for both local and remote storage.
//!
//! ## Hash Algorithms
//!
//! Supports multiple algorithms via [`checksum::ObjectHash`]:
//! - **SHA256**: General-purpose cryptographic hash
//! - **CRC64**: Fast checksum for large files
//! - **SHA256-Chunked**: Parallel hashing for very large files
//!
//! Algorithm selection based on file size and performance requirements.
//!
//! ## Error Handling
//!
//! The [`Error`] enum covers all failure modes:
//! - I/O operations, remote storage, manifest parsing
//! - Hash verification, package conflicts
//! - Comprehensive error context for debugging
//!
//! ## Extension Points
//!
//! - **Storage Backends**: Pluggable via [`io::storage::Storage`] trait
//! - **Remote Protocols**: Configurable via [`io::remote::Remote`] trait
//! - **Hash Algorithms**: Extensible [`checksum::ObjectHash`] enum
//! - **Metadata Schema**: User-defined metadata in manifests
pub use Error;
pub use InstalledPackage;
pub use LocalDomain;
pub type Res<T = > = Result;