wip: clawsync + clawhdf5-onion in-progress (ci-doctor branch)

crates/clawsync-hdf5/src/differ.rs

@@ -33,6 +33,7 @@ pub struct DatasetPatch {
 /// Result of diffing two manifests.
 #[derive(Debug, Default)]
 pub struct DiffResult {
+    /// Ordered list of patches (Added, Modified, Removed) to apply to the target.
     pub patches: Vec<DatasetPatch>,
     /// Number of datasets that are identical in both manifests.
     pub unchanged_count: usize,

crates/clawsync-hdf5/src/error.rs

@@ -2,24 +2,33 @@
 
 use thiserror::Error;
 
+/// All errors that can occur in the `clawsync-hdf5` HDF5 sync layer.
 #[derive(Debug, Error)]
 pub enum Hdf5SyncError {
+    /// An error from the `clawhdf5` HDF5 parser or builder.
     #[error("HDF5 error: {0}")]
     Hdf5(#[from] clawhdf5::Error),
 
+    /// An underlying I/O error (file read/write, temp-file rename, etc.).
     #[error("I/O error: {0}")]
     Io(#[from] std::io::Error),
 
+    /// A dataset path referenced in a patch does not exist in the target file.
     #[error("dataset not found: {0}")]
     DatasetNotFound(String),
 
+    /// A patch attempted to overwrite a dataset with data of a different dtype.
     #[error("patch type mismatch for dataset '{path}': expected {expected}, got {actual}")]
     TypeMismatch {
+        /// HDF5 path of the mismatched dataset (e.g., `/group/weights`).
         path: String,
+        /// The dtype present in the target file.
         expected: String,
+        /// The dtype carried by the incoming patch.
         actual: String,
     },
 
+    /// A `DatasetManifest` could not be serialized or deserialized.
     #[error("manifest serialization error: {0}")]
     Serialize(String),
 }

crates/clawsync-hdf5/src/patcher.rs

@@ -24,10 +24,15 @@ use crate::error::Hdf5SyncError;
 /// Statistics from a patch operation.
 #[derive(Debug, Default, Clone)]
 pub struct PatchStats {
+    /// Number of new datasets added to the target file.
     pub datasets_added: u32,
+    /// Number of existing datasets overwritten with new data.
     pub datasets_modified: u32,
+    /// Number of datasets deleted from the target file.
     pub datasets_removed: u32,
+    /// Number of datasets copied unchanged from the old target file.
     pub datasets_unchanged: u32,
+    /// Total bytes written to the rebuilt target file.
     pub bytes_written: u64,
 }