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

crates/clawsync-onion/src/error.rs

@@ -2,36 +2,54 @@
 
 use thiserror::Error;
 
+/// All errors that can occur in the `clawsync-onion` sync layer.
 #[derive(Debug, Error)]
 pub enum SyncOnionError {
+    /// An error propagated from the underlying `clawhdf5-onion` VFD.
     #[error("onion error: {0}")]
     Onion(#[from] clawhdf5_onion::OnionError),
 
+    /// An error propagated from `clawsync-core` (compression, checksums, I/O).
     #[error("core error: {0}")]
     Core(#[from] clawsync_core::CoreError),
 
+    /// An underlying I/O error.
     #[error("I/O error: {0}")]
     Io(#[from] std::io::Error),
 
+    /// The requested revision number does not exist in the source `.onion` file.
     #[error("revision {0} not found in source")]
     RevisionNotFound(u64),
 
+    /// The named branch does not exist in the source `.onion` file.
     #[error("branch not found: {0}")]
     BranchNotFound(String),
 
+    /// The BLAKE3 hash of a received revision's pages does not match the expected value.
     #[error("BLAKE3 mismatch on revision {revision}: expected {expected}, got {actual}")]
     HashMismatch {
+        /// The revision number whose pages failed the integrity check.
         revision: u64,
+        /// The BLAKE3 hex string that was expected.
         expected: String,
+        /// The BLAKE3 hex string that was computed from the received pages.
         actual: String,
     },
 
+    /// A `LayerPacket` could not be serialized or deserialized.
     #[error("packet serialization error: {0}")]
     Serialization(String),
 
+    /// A merge was attempted with an empty set of packets.
     #[error("empty packet set — nothing to merge")]
     EmptyPackets,
 
+    /// Revisions arrived out of order during a merge — a gap was detected.
     #[error("revision gap: received {got}, expected {expected}")]
-    RevisionGap { expected: u64, got: u64 },
+    RevisionGap {
+        /// The next consecutive revision that was expected.
+        expected: u64,
+        /// The revision number that was actually received.
+        got: u64,
+    },
 }

crates/clawsync-onion/src/iblt.rs

@@ -100,12 +100,16 @@ pub enum IbltDecodeResult {
 // Error type
 // ─────────────────────────────────────────────────────────────────────────────
 
+/// Errors from IBLT sketch serialisation/deserialisation.
 #[derive(Debug, thiserror::Error, PartialEq, Eq)]
 pub enum IbltError {
+    /// The byte slice is too short to contain a valid sketch header or payload.
     #[error("serialised data too short")]
     Truncated,
+    /// The first bytes do not match the expected IBLT magic sequence.
     #[error("bad magic bytes")]
     BadMagic,
+    /// The format version byte is not supported by this reader.
     #[error("unknown version {0}")]
     UnknownVersion(u8),
 }

crates/clawsync-onion/src/manifest.rs

@@ -15,12 +15,17 @@ use crate::iblt::{DEFAULT_HASH_COUNT, IbltDecodeResult, IbltDiff, IbltSketch};
 /// A compact summary of one revision — used in the manifest.
 #[derive(Archive, Deserialize, Serialize, Debug, Clone, PartialEq)]
 pub struct RevisionSummaryPacket {
+    /// Monotonically increasing revision number (0-based).
     pub revision: u64,
+    /// ID of the branch this revision belongs to; `0` = `main`.
     pub branch_id: u32,
+    /// Revision number of the direct parent; `u64::MAX` for the initial commit.
     pub parent_rev: u64,
+    /// Unix timestamp (seconds since epoch, as `f64`) when the revision was committed.
     pub timestamp: f64,
     /// BLAKE3 hash of the pages in this revision.
     pub blake3: [u8; 32],
+    /// Optional human-readable annotation stored with the revision.
     pub annotation: Option<String>,
 }
 
@@ -119,11 +124,17 @@ impl ClawSyncManifest {
 /// For N=1 000: ~3 KB vs ~60 KB for `ClawSyncManifest`.
 #[derive(Archive, Deserialize, Serialize, Debug, Clone, PartialEq)]
 pub struct IbltManifest {
+    /// Logical agent / file identifier (same as in `ClawSyncManifest`).
     pub agent_id: String,
+    /// BLAKE3 hash of the raw `.h5` base file; zero-filled during pre-flight.
     pub file_blake3: [u8; 32],
+    /// Total number of revisions in the sender's sidecar.
     pub revision_count: u64,
+    /// HEAD revision number on the sender's default branch.
     pub head_revision: u64,
+    /// BLAKE3 hash of the HEAD revision's pages; zero-filled during pre-flight.
     pub head_blake3: [u8; 32],
+    /// Unix timestamp (seconds since epoch, as `f64`) of the last committed revision.
     pub last_write: f64,
     /// Serialised [`IbltSketch`] bytes.
     pub sketch: Vec<u8>,