cabriolet 0.2.1 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d301c701aa57d4033c110e9610d76f11e26ae3b8debd3a52d8a3df5ccb725905
-  data.tar.gz: d009c4741e7885ec25ad6766dd79158d1955b80ffc16e9acb0c5a0c1a813b9d0
+  metadata.gz: 59d85958b00fa7eb684912e7ec77bfd9ce261a01035ed7ef42c2d6db5b1405a7
+  data.tar.gz: e9fa2123fe7c48778a01018c68f47cdb66f68449fe4fee48074e2b7591d5b9e1
 SHA512:
-  metadata.gz: fd0314bf6196cad4749d2497ee639b7a355eab2a93a4a5e4967878e64cabd6413c08bbfab99aa767e67d1a13a0a3e7e428801819192c6506dba2dbf30f653b3d
-  data.tar.gz: dd1bb57af42a9cc7fa8556bd05632ce79b3b2a994d8276bee8349db7f10428e9d61f254ea8f928583dc8e7f0eca8e2bdd326fd137912fe5afc74c1b0b3f684da
+  metadata.gz: ddc9ef226ce8359cbe65ac4e80853dbd8e57f25c6e934e48837a163f614bcdbdf94f18609c788c6396f4b87f93d4e12c1fa326c8f291bc1156ec0eaf0387d377
+  data.tar.gz: 20206a2b5011d4a869d0f4d29085b5b874fe1d34daa00ce14f842d55a71722c19329ea75b1f46adaebf88fc43805a467b089e038aa19fe5736010d1a9ca951ad

data/lib/cabriolet/binary/bitstream.rb

@@ -4,7 +4,7 @@ module Cabriolet
   module Binary
     # Bitstream provides bit-level I/O operations for reading compressed data
     class Bitstream
-      attr_reader :io_system, :handle, :buffer_size, :bit_order
+      attr_reader :io_system, :handle, :buffer_size, :bit_order, :bits_left
 
       # Initialize a new bitstream
       #
@@ -29,6 +29,9 @@ buffer_size = Cabriolet.default_buffer_size, bit_order: :lsb, salvage: false)
         # For MSB mode, we need to know the bit width of the buffer
         # Ruby integers are arbitrary precision, so we use 32 bits as standard
         @bitbuf_width = 32
+
+        # Cache ENV lookups once at initialization
+        @debug_bitstream = ENV.fetch("DEBUG_BITSTREAM", nil)
       end
 
       # Read specified number of bits from the stream
@@ -83,7 +86,7 @@ buffer_size = Cabriolet.default_buffer_size, bit_order: :lsb, salvage: false)
           byte = 0 if byte.nil?
 
           # DEBUG
-          if ENV["DEBUG_BITSTREAM"]
+          if @debug_bitstream
             warn "DEBUG LSB read_byte: buffer_pos=#{@buffer_pos} byte=#{byte} (#{byte.to_s(2).rjust(
               8, '0'
             )}) bits_left=#{@bits_left}"
@@ -101,7 +104,7 @@ buffer_size = Cabriolet.default_buffer_size, bit_order: :lsb, salvage: false)
         @bits_left -= num_bits
 
         # DEBUG
-        warn "DEBUG LSB read_bits(#{num_bits}): result=#{result} buffer=#{@bit_buffer.to_s(16)} bits_left=#{@bits_left}" if ENV["DEBUG_BITSTREAM"]
+        warn "DEBUG LSB read_bits(#{num_bits}): result=#{result} buffer=#{@bit_buffer.to_s(16)} bits_left=#{@bits_left}" if @debug_bitstream
 
         result
       end
@@ -116,7 +119,7 @@ buffer_size = Cabriolet.default_buffer_size, bit_order: :lsb, salvage: false)
           word = read_msb_word
 
           # DEBUG
-          warn "DEBUG MSB read_bytes: word=0x#{word.to_s(16)} bits_left=#{@bits_left}" if ENV["DEBUG_BITSTREAM"]
+          warn "DEBUG MSB read_bytes: word=0x#{word.to_s(16)} bits_left=#{@bits_left}" if @debug_bitstream
 
           # INJECT_BITS (MSB): inject at the left side
           @bit_buffer |= (word << (@bitbuf_width - 16 - @bits_left))
@@ -131,7 +134,7 @@ buffer_size = Cabriolet.default_buffer_size, bit_order: :lsb, salvage: false)
         @bits_left -= num_bits
 
         # DEBUG
-        warn "DEBUG MSB read_bits(#{num_bits}) result=#{result} (0x#{result.to_s(16)}) buffer=0x#{@bit_buffer.to_s(16)} bits_left=#{@bits_left}" if ENV["DEBUG_BITSTREAM"]
+        warn "DEBUG MSB read_bits(#{num_bits}) result=#{result} (0x#{result.to_s(16)}) buffer=0x#{@bit_buffer.to_s(16)} bits_left=#{@bits_left}" if @debug_bitstream
 
         result
       end
@@ -172,15 +175,62 @@ buffer_size = Cabriolet.default_buffer_size, bit_order: :lsb, salvage: false)
         byte
       end
 
+      # Ensure at least num_bits are available in the bit buffer.
+      # Reads from input if needed. Used for alignment operations.
+      #
+      # @param num_bits [Integer] Minimum number of bits required
+      # @return [void]
+      def ensure_bits(num_bits)
+        if @bit_order == :msb
+          while @bits_left < num_bits
+            word = read_msb_word
+            @bit_buffer |= (word << (@bitbuf_width - 16 - @bits_left))
+            @bits_left += 16
+          end
+        else
+          while @bits_left < num_bits
+            byte = read_byte
+            byte = 0 if byte.nil?
+            @bit_buffer |= (byte << @bits_left)
+            @bits_left += 8
+          end
+        end
+      end
+
       # Align to the next byte boundary
       #
       # @return [void]
       def byte_align
         discard_bits = @bits_left % 8
-        @bit_buffer >>= discard_bits
+        if @bit_order == :msb
+          # MSB mode: valid bits are at the left (high) end, shift left to discard
+          @bit_buffer = (@bit_buffer << discard_bits) & ((1 << @bitbuf_width) - 1)
+        else
+          @bit_buffer >>= discard_bits
+        end
         @bits_left -= discard_bits
       end
 
+      # Flush the bit buffer entirely (discard all remaining bits).
+      # Per libmspack lzxd.c: used when transitioning to raw byte reading
+      # for uncompressed blocks. Sets bits_left=0 and bit_buffer=0.
+      #
+      # @return [void]
+      def flush_bit_buffer
+        @bit_buffer = 0
+        @bits_left = 0
+      end
+
+      # Read a raw byte directly from the input, bypassing the bit buffer.
+      # Per libmspack lzxd.c: uncompressed block headers and data are read
+      # directly from the input pointer (i_ptr), not through the bitstream.
+      # Call flush_bit_buffer first to discard any residual bits.
+      #
+      # @return [Integer] Byte value (0 on EOF)
+      def read_raw_byte
+        read_byte || 0
+      end
+
       # Peek at bits without consuming them
       #
       # @param num_bits [Integer] Number of bits to peek at

data/lib/cabriolet/cab/decompressor.rb

@@ -157,8 +157,11 @@ module Cabriolet
               offset = cab_offset + 4
             end
           else
-            # No cabinet found in this chunk, move to next
-            offset += length
+            # No cabinet found in this chunk, move to next.
+            # Overlap by 20 bytes so MSCF signatures spanning chunk
+            # boundaries are not missed (state machine reads 20 bytes).
+            overlap = length > 20 ? 20 : 0
+            offset += [length - overlap, 1].max
           end
         end
 
@@ -452,7 +455,7 @@ file_length)
                                                         cablen_u32, caboff, file_length)
 
             # Not valid, restart search after "MSCF"
-            return nil
+            state = 0
           end
         end
 

data/lib/cabriolet/cab/extractor.rb

@@ -22,6 +22,9 @@ module Cabriolet
         @current_decomp = nil
         @current_input = nil
         @current_offset = 0
+
+        # Cache ENV lookups once at initialization
+        @debug_block = ENV.fetch("DEBUG_BLOCK", nil)
       end
 
       # Extract a single file from the cabinet
@@ -34,25 +37,7 @@ module Cabriolet
       def extract_file(file, output_path, **options)
         salvage = options[:salvage] || @decompressor.salvage
         folder = file.folder
-
-        # Validate file
-        raise Cabriolet::ArgumentError, "File has no folder" unless folder
-
-        if file.offset > Constants::LENGTH_MAX
-          raise DecompressionError,
-                "File offset beyond 2GB limit"
-        end
-
-        # Check file length
-        filelen = file.length
-        if filelen > (Constants::LENGTH_MAX - file.offset)
-          unless salvage
-            raise DecompressionError,
-                  "File length exceeds 2GB limit"
-          end
-
-          filelen = Constants::LENGTH_MAX - file.offset
-        end
+        filelen = validate_file_for_extraction(file, folder, salvage)
 
         # Check for merge requirements
         if folder.needs_prev_merge?
@@ -60,81 +45,22 @@ module Cabriolet
                 "File requires previous cabinet, cabinet set is incomplete"
         end
 
-        # Check file fits within folder
-        unless salvage
-          max_len = folder.num_blocks * Constants::BLOCK_MAX
-          if file.offset > max_len || filelen > (max_len - file.offset)
-            raise DecompressionError, "File extends beyond folder data"
-          end
-        end
+        validate_file_in_folder(folder, file.offset, filelen, salvage)
 
         # Create output directory if needed
         output_dir = ::File.dirname(output_path)
         FileUtils.mkdir_p(output_dir) unless ::File.directory?(output_dir)
 
-        # Check if we need to change folder or reset (libmspack lines 1076-1078)
-        if ENV["DEBUG_BLOCK"]
-          warn "DEBUG extract_file: Checking reset condition for file #{file.filename} (offset=#{file.offset}, length=#{file.length})"
-          warn "  @current_folder == folder: #{@current_folder == folder} (current=#{@current_folder.object_id}, new=#{folder.object_id})"
-          warn "  @current_offset (#{@current_offset}) > file.offset (#{file.offset}): #{@current_offset > file.offset}"
-          warn "  @current_decomp.nil?: #{@current_decomp.nil?}"
-          warn "  Reset needed?: #{@current_folder != folder || @current_offset > file.offset || !@current_decomp}"
-        end
-
-        if @current_folder != folder || @current_offset > file.offset || !@current_decomp
-          if ENV["DEBUG_BLOCK"]
-            warn "DEBUG extract_file: RESETTING state (creating new BlockReader)"
-          end
-
-          # Reset state
-          @current_input&.close
-          @current_input = nil
-          @current_decomp = nil
-
-          # Create new input (libmspack lines 1092-1095)
-          # This BlockReader will be REUSED across all files in this folder
-          @current_input = BlockReader.new(@io_system, folder.data,
-                                           folder.num_blocks, salvage)
-          @current_folder = folder
-          @current_offset = 0
-
-          # Create decompressor ONCE and reuse it (this is the key fix!)
-          # The decompressor maintains bitstream state across files
-          @current_decomp = @decompressor.create_decompressor(folder,
-                                                              @current_input, nil)
-        elsif ENV["DEBUG_BLOCK"]
-          warn "DEBUG extract_file: NOT resetting (reusing existing BlockReader and decompressor)"
-        end
-
-        # Skip ahead if needed (libmspack lines 1130-1134)
-        if file.offset > @current_offset
-          skip_bytes = file.offset - @current_offset
-
-          # Decompress with NULL output to skip (libmspack line 1130: self->d->outfh = NULL)
-          null_output = System::MemoryHandle.new("", Constants::MODE_WRITE)
-
-          # Reuse existing decompressor, change output to NULL
-          @current_decomp.instance_variable_set(:@output, null_output)
-
-          # Set output length for LZX frame limiting
-          @current_decomp.set_output_length(skip_bytes) if @current_decomp.respond_to?(:set_output_length)
-
-          @current_decomp.decompress(skip_bytes)
-          @current_offset += skip_bytes
-        end
+        setup_decompressor_for_folder(folder, salvage, file.offset)
+        skip_to_file_offset(file.offset, salvage, file.filename)
 
         # Extract actual file (libmspack lines 1137-1141)
         output_fh = @io_system.open(output_path, Constants::MODE_WRITE)
 
         begin
-          # Reuse existing decompressor, change output to real file
-          @current_decomp.instance_variable_set(:@output, output_fh)
-
-          # Set output length for LZX frame limiting
-          @current_decomp.set_output_length(filelen) if @current_decomp.respond_to?(:set_output_length)
-
-          @current_decomp.decompress(filelen)
-          @current_offset += filelen
+          write_file_data(output_fh, filelen)
+        rescue DecompressionError
+          handle_extraction_error(output_fh, output_path, file.filename, salvage, filelen)
         ensure
           output_fh.close
         end
@@ -142,6 +68,15 @@ module Cabriolet
         filelen
       end
 
+      # Reset extraction state (used in salvage mode to recover from errors)
+      def reset_state
+        @current_input&.close
+        @current_input = nil
+        @current_decomp = nil
+        @current_folder = nil
+        @current_offset = 0
+      end
+
       # Extract all files from a cabinet
       #
       # @param cabinet [Models::Cabinet] Cabinet to extract from
@@ -150,16 +85,19 @@ module Cabriolet
       # @option options [Boolean] :preserve_paths Preserve directory structure (default: true)
       # @option options [Boolean] :set_timestamps Set file modification times (default: true)
       # @option options [Proc] :progress Progress callback
+      # @option options [Boolean] :salvage Skip files that fail to extract (default: false)
       # @return [Integer] Number of files extracted
       def extract_all(cabinet, output_dir, **options)
         preserve_paths = options.fetch(:preserve_paths, true)
         set_timestamps = options.fetch(:set_timestamps, true)
         progress = options[:progress]
+        salvage = options[:salvage] || false
 
         # Create output directory
         FileUtils.mkdir_p(output_dir) unless ::File.directory?(output_dir)
 
         count = 0
+        failed_count = 0
         cabinet.files.each do |file|
           # Determine output path
           output_path = if preserve_paths
@@ -169,8 +107,18 @@ module Cabriolet
                                       ::File.basename(file.filename))
                         end
 
-          # Extract file
-          extract_file(file, output_path, **options)
+          # Extract file (skip if salvage mode and extraction fails)
+          begin
+            extract_file(file, output_path, **options)
+          rescue DecompressionError => e
+            if salvage
+              warn "Salvage: skipping #{file.filename}: #{e.message}"
+              failed_count += 1
+              next
+            else
+              raise
+            end
+          end
 
           # Set timestamp if requested
           if set_timestamps && file.modification_time
@@ -185,11 +133,163 @@ module Cabriolet
           progress&.call(file, count, cabinet.files.size)
         end
 
+        warn "Salvage: #{failed_count} file(s) skipped due to extraction errors" if failed_count.positive?
+
         count
       end
 
       private
 
+      # Validate file for extraction
+      #
+      # @param file [Models::File] File to validate
+      # @param folder [Models::Folder] Folder containing the file
+      # @param salvage [Boolean] Salvage mode flag
+      # @return [Integer] Validated file length
+      def validate_file_for_extraction(file, folder, salvage)
+        raise Cabriolet::ArgumentError, "File has no folder" unless folder
+
+        if file.offset > Constants::LENGTH_MAX
+          raise DecompressionError,
+                "File offset beyond 2GB limit"
+        end
+
+        filelen = file.length
+        if filelen > (Constants::LENGTH_MAX - file.offset)
+          unless salvage
+            raise DecompressionError,
+                  "File length exceeds 2GB limit"
+          end
+
+          filelen = Constants::LENGTH_MAX - file.offset
+        end
+
+        filelen
+      end
+
+      # Validate file fits within folder
+      #
+      # @param folder [Models::Folder] Folder to check
+      # @param file_offset [Integer] File offset
+      # @param filelen [Integer] File length
+      # @param salvage [Boolean] Salvage mode flag
+      def validate_file_in_folder(folder, file_offset, filelen, salvage)
+        return if salvage
+
+        max_len = folder.num_blocks * Constants::BLOCK_MAX
+        return unless file_offset > max_len || filelen > (max_len - file_offset)
+
+        raise DecompressionError, "File extends beyond folder data"
+      end
+
+      # Setup decompressor for folder
+      #
+      # @param folder [Models::Folder] Folder to setup for
+      # @param salvage [Boolean] Salvage mode flag
+      # @param file_offset [Integer] File offset for reset condition check
+      def setup_decompressor_for_folder(folder, salvage, file_offset)
+        if @debug_block
+          warn "DEBUG extract_file: Checking reset condition"
+          warn "  @current_folder == folder: #{@current_folder == folder}"
+          warn "  @current_offset (#{@current_offset}) > file_offset (#{file_offset})"
+          warn "  @current_decomp.nil?: #{@current_decomp.nil?}"
+        end
+
+        if @current_folder != folder || @current_offset > file_offset || !@current_decomp
+          if @debug_block
+            warn "DEBUG extract_file: RESETTING state (creating new BlockReader)"
+          end
+
+          # Reset state
+          @current_input&.close
+          @current_input = nil
+          @current_decomp = nil
+
+          # Create new input (libmspack lines 1092-1095)
+          @current_input = BlockReader.new(@io_system, folder.data,
+                                           folder.num_blocks, salvage)
+          @current_folder = folder
+          @current_offset = 0
+
+          # Create decompressor ONCE and reuse it
+          @current_decomp = @decompressor.create_decompressor(folder,
+                                                              @current_input, nil)
+
+          # Per libmspack cabd.c: set output_length from the folder's total
+          # uncompressed size (max file.offset + file.length across all files
+          # in the folder). This allows the LZX decompressor to reduce the
+          # last frame's size so it doesn't read past the end of the stream.
+          if @current_decomp.respond_to?(:set_output_length)
+            cab = folder.data&.cabinet
+            if cab&.files
+              folder_files = cab.files.select { |f| f.folder == folder }
+              max_end = folder_files.map { |f| f.offset + f.length }.max
+              @current_decomp.set_output_length(max_end) if max_end&.positive?
+            end
+          end
+        elsif @debug_block
+          warn "DEBUG extract_file: NOT resetting (reusing existing BlockReader)"
+        end
+      end
+
+      # Skip to file offset
+      #
+      # @param file_offset [Integer] Target offset
+      # @param salvage [Boolean] Salvage mode flag
+      # @param filename [String] Filename for error messages
+      def skip_to_file_offset(file_offset, salvage, filename)
+        return unless file_offset > @current_offset
+
+        skip_bytes = file_offset - @current_offset
+        null_output = System::MemoryHandle.new("", Constants::MODE_WRITE)
+
+        @current_decomp.instance_variable_set(:@output, null_output)
+
+        begin
+          @current_decomp.decompress(skip_bytes)
+        rescue DecompressionError
+          if salvage
+            warn "Salvage: unable to skip to file #{filename}, resetting state"
+            reset_state
+          else
+            raise
+          end
+        end
+        @current_offset += skip_bytes
+      end
+
+      # Write file data using decompressor
+      #
+      # @param output_fh [System::FileHandle] Output file handle
+      # @param filelen [Integer] Number of bytes to write
+      def write_file_data(output_fh, filelen)
+        unless @current_decomp
+          raise DecompressionError, "Decompressor not available (state was reset)"
+        end
+
+        @current_decomp.instance_variable_set(:@output, output_fh)
+        @current_decomp.decompress(filelen)
+        @current_offset += filelen
+      end
+
+      # Handle extraction error
+      #
+      # @param output_fh [System::FileHandle] Output file handle
+      # @param output_path [String] Output file path
+      # @param filename [String] Filename for error messages
+      # @param salvage [Boolean] Salvage mode flag
+      # @raise [DecompressionError] If not in salvage mode
+      def handle_extraction_error(output_fh, output_path, filename, salvage, _filelen)
+        output_fh.close
+        if salvage
+          ::File.write(output_path, "", mode: "wb")
+          warn "Salvage: created empty file for #{filename} due to decompression error"
+          reset_state
+        else
+          raise
+        end
+      end
+
       # Set file attributes based on CAB attributes
       #
       # @param path [String] File path
@@ -229,6 +329,9 @@ module Cabriolet
           @buffer_pos = 0
           @cab_handle = nil
 
+          # Cache ENV lookups once at initialization
+          @debug_block = ENV.fetch("DEBUG_BLOCK", nil)
+
           # Open first cabinet and seek to data offset
           open_current_cabinet
         end
@@ -236,7 +339,7 @@ module Cabriolet
         def read(bytes)
           # Early return if we've already exhausted all blocks and buffer
           if @current_block >= @num_blocks && @buffer_pos >= @buffer.bytesize
-            if ENV["DEBUG_BLOCK"]
+            if @debug_block
               warn "DEBUG BlockReader.read(#{bytes}): Already exhausted, returning empty"
             end
             return +""
@@ -244,14 +347,14 @@ module Cabriolet
 
           result = +""
 
-          if ENV["DEBUG_BLOCK"]
+          if @debug_block
             warn "DEBUG BlockReader.read(#{bytes}): buffer_size=#{@buffer.bytesize} buffer_pos=#{@buffer_pos} block=#{@current_block}/#{@num_blocks}"
           end
 
           while result.bytesize < bytes
             # Read more data if buffer is empty
             if (@buffer_pos >= @buffer.bytesize) && !read_next_block
-              if ENV["DEBUG_BLOCK"]
+              if @debug_block
                 warn "DEBUG BlockReader.read: EXHAUSTED at result.bytesize=#{result.bytesize} (wanted #{bytes})"
               end
               break
@@ -265,7 +368,7 @@ module Cabriolet
             @buffer_pos += to_copy
           end
 
-          if ENV["DEBUG_BLOCK"]
+          if @debug_block
             warn "DEBUG BlockReader.read: returning #{result.bytesize} bytes"
           end
 
@@ -289,12 +392,12 @@ module Cabriolet
         private
 
         def read_next_block
-          if ENV["DEBUG_BLOCK"]
+          if @debug_block
             warn "DEBUG read_next_block: current_block=#{@current_block} num_blocks=#{@num_blocks}"
           end
 
           if @current_block >= @num_blocks
-            if ENV["DEBUG_BLOCK"]
+            if @debug_block
               warn "DEBUG read_next_block: EXHAUSTED (current_block >= num_blocks)"
             end
             return false
@@ -305,19 +408,19 @@ module Cabriolet
 
           loop do
             # Read CFDATA header
-            if ENV["DEBUG_BLOCK"]
+            if @debug_block
               handle_pos = @cab_handle.tell
               warn "DEBUG read_next_block: About to read CFDATA header at position #{handle_pos}"
             end
 
             header_data = @cab_handle.read(Constants::CFDATA_SIZE)
 
-            if ENV["DEBUG_BLOCK"]
+            if @debug_block
               warn "DEBUG read_next_block: Read #{header_data.bytesize} bytes (expected #{Constants::CFDATA_SIZE})"
             end
 
             if header_data.bytesize != Constants::CFDATA_SIZE
-              if ENV["DEBUG_BLOCK"]
+              if @debug_block
                 warn "DEBUG read_next_block: FAILED - header read returned #{header_data.bytesize} bytes"
               end
               return false
@@ -345,18 +448,18 @@ module Cabriolet
             end
 
             # Read compressed data
-            if ENV["DEBUG_BLOCK"]
+            if @debug_block
               warn "DEBUG read_next_block: About to read #{cfdata.compressed_size} bytes of compressed data"
             end
 
             compressed_data = @cab_handle.read(cfdata.compressed_size)
 
-            if ENV["DEBUG_BLOCK"]
+            if @debug_block
               warn "DEBUG read_next_block: Read #{compressed_data.bytesize} bytes of compressed data (expected #{cfdata.compressed_size})"
             end
 
             if compressed_data.bytesize != cfdata.compressed_size
-              if ENV["DEBUG_BLOCK"]
+              if @debug_block
                 warn "DEBUG read_next_block: FAILED - compressed data read returned #{compressed_data.bytesize} bytes"
               end
               return false
@@ -400,7 +503,7 @@ module Cabriolet
         end
 
         def open_current_cabinet
-          if ENV["DEBUG_BLOCK"]
+          if @debug_block
             warn "DEBUG open_current_cabinet: filename=#{@current_data.cabinet.filename} offset=#{@current_data.offset}"
           end
 
@@ -408,7 +511,7 @@ module Cabriolet
           @cab_handle = @io_system.open(@current_data.cabinet.filename, Constants::MODE_READ)
           @cab_handle.seek(@current_data.offset, Constants::SEEK_START)
 
-          if ENV["DEBUG_BLOCK"]
+          if @debug_block
             actual_pos = @cab_handle.tell
             warn "DEBUG open_current_cabinet: seeked to position #{actual_pos} (expected #{@current_data.offset})"
           end

data/lib/cabriolet/checksum.rb

@@ -28,14 +28,17 @@ module Cabriolet
         ul = 0
         offset = bytes.size - remainder
 
+        # Match libmspack's cabd_checksum remainder handling:
+        # The C fall-through switch processes bytes in decreasing shift
+        # order (first remaining byte gets the highest shift).
         case remainder
         when 3
-          ul |= bytes[offset + 2] << 16
+          ul |= bytes[offset] << 16
           ul |= bytes[offset + 1] << 8
-          ul |= bytes[offset]
+          ul |= bytes[offset + 2]
         when 2
-          ul |= bytes[offset + 1] << 8
-          ul |= bytes[offset]
+          ul |= bytes[offset] << 8
+          ul |= bytes[offset + 1]
         when 1
           ul |= bytes[offset]
         end