omnizip 0.3.56 → 0.3.58

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3a34ac63f49299330b590a1f9010940af988984f875f7ea101f44c126d90f5d6
-  data.tar.gz: 5a7940049434d24a4f61d073db07133b6645133dd79783462e864856e3302d24
+  metadata.gz: 04bb0d1c81ef7f4571014bb6679ad0d4750d4c078729daea82c88f643e246818
+  data.tar.gz: 7523e6a77a43db5eb02ec7c16ef4adf0751150129f329af82eb11297f93a68f6
 SHA512:
-  metadata.gz: 8ad6baae78797134776df430810dc67b5fae438d702aa4613d02468fae496134d1e53d2d4c8c857ee51311fe1a72de463529ae0dc553bf9fc8a792be9a3a0718
-  data.tar.gz: 385b3cec020df42f2532944a287467bd63cb155212278b0164c2e61e7db5c262e2858a306c4cccfaf949dbd0f61b5c2a013a72586166fbfca0a4323a5e46b65a
+  metadata.gz: da1c027f6e44246e6421760d3197501db38957aeb1541c0db6e3553ab73b5e03a221a362b0165d4196bf1185f0022b341529321cdce9c2a339c3cf2f31b4f733
+  data.tar.gz: 7732ed6d8268d006195f7648980e2f8619ea89d45767932afd587f508592f627697a9cc436f6f3e1a01b41a8a579034f654c1bc33cc3331fced28af5bd68b8ff

data/CHANGELOG.md

@@ -7,6 +7,43 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.57] - 2026-09-02
+
+### Fixed
+- TAR archives no longer corrupt silently on long paths: the writer
+  now splits entry names over 99 bytes across the ustar prefix +
+  name fields at a "/" boundary, the reader joins them back for
+  consumers, and paths no ustar fields can represent raise
+  `FormatError` instead of truncating. Verified against system tar.
+- `:auto` profile sampling walked directories in the OS's
+  iteration order, resolving different files (and compression
+  settings) per platform; the walk is sorted and deterministic now.
+- The getting-started docs' 7z examples used a Reader API that
+  never shipped (`each_file`, `close`, `Reader.info`) — every
+  snippet raised NoMethodError verbatim. Rewritten against the real
+  surface and executed to verify.
+
+### Changed
+- The last 28 bare `raise "string"` sites (RAR tree, cpio entries,
+  parity internals, zip compat streams, two commands) gained their
+  matching error classes — `lib/` now contains zero bare raises.
+- The dead `--preserve-ntfs-streams` CLI flag is removed; nothing
+  read it and no code path implements NTFS stream preservation.
+
+## [0.3.56] - 2026-09-02
+
+### Fixed
+- `FilterRegistry#entry_for` read its storage and lazy triggers
+  outside the mutex `register` writes under — a latent data race in
+  the 7z codec chain's filter resolution. Reads now hold the lock,
+  with the lazy trigger fired outside it (it re-enters through
+  register's own synchronize).
+- The progress lifecycle is complete: `ProgressTracker` gains
+  `#start` and `#finish`, firing the reporter start/finish hooks
+  every reporter class overrides but nothing ever called —
+  "operation started/finished" output could never appear. `#finish`
+  also forces a final report and is idempotent.
+
 ## [0.3.55] - 2026-09-01
 
 ### Changed

data/docs/developer/architecture.adoc

@@ -120,8 +120,8 @@ module Omnizip
           # Open archive
         end
 
-        def each_file
-          # Yield archive entries
+        def entries
+          # Enumerate archive entries
         end
 
         def extract_all(output_dir)

data/docs/getting-started/quick-start.adoc

@@ -103,11 +103,9 @@ omnizip archive list backup.7z
 require 'omnizip'
 
 reader = Omnizip::Formats::SevenZip::Reader.new('backup.7z')
-reader.open
-reader.each_file do |entry|
+reader.entries.each do |entry|
   puts "#{entry.name}: #{entry.size} bytes"
 end
-reader.close
 ----
 
 === Using Different Compression Algorithms

data/docs/getting-started/your-first-archive.adoc

@@ -180,12 +180,15 @@ writer.add_directory('/home/user/photos')
 writer.close
 
 # Get statistics
-info = Omnizip::Formats::SevenZip::Reader.info('backup.7z')
+entries = Omnizip.list_archive('backup.7z', details: true)
+files = entries.reject { |e| e[:directory] }
+uncompressed = files.sum { |e| e[:size] }
+compressed = File.size('backup.7z')
 puts "Archive created:"
-puts "  Files: #{info.entry_count}"
-puts "  Size: #{info.uncompressed_size} bytes"
-puts "  Compressed: #{info.compressed_size} bytes"
-puts "  Ratio: #{(info.compressed_size.to_f / info.uncompressed_size * 100).round(1)}%"
+puts "  Files: #{files.size}"
+puts "  Size: #{uncompressed} bytes"
+puts "  Compressed: #{compressed} bytes"
+puts "  Ratio: #{(compressed.to_f / uncompressed * 100).round(1)}%"
 ----
 
 === Verifying Your Archive
@@ -202,12 +205,10 @@ omnizip archive list backup.7z
 require 'omnizip'
 
 reader = Omnizip::Formats::SevenZip::Reader.new('backup.7z')
-reader.open
 puts "Archive contents:"
-reader.each_file do |entry|
+reader.entries.each do |entry|
   puts "  #{entry.name} (#{entry.size} bytes)"
 end
-reader.close
 ----
 
 === Next Steps

data/docs/guides/creating-archives.adoc

@@ -76,7 +76,7 @@ writer.write
 
 IMPORTANT: RAR5 CRC32 checksums only work with STORE compression. When LZMA is used, CRC32 is automatically disabled. Use BLAKE2sp (always present) for compressed file integrity.
 
-=== RAR5 Multi-Volume Archives (v0.5.0)
+=== RAR5 Multi-Volume Archives
 
 Split large archives across multiple volumes:
 
@@ -110,36 +110,30 @@ volumes = writer.write
 # Minimum volume size: 64 KB
 ----
 
-=== RAR5 Solid Compression (v0.5.0)
+=== RAR5 Solid Archives
 
-Achieve 10-30% better compression ratios for similar files:
+`solid: true` requests a shared solid block, but the RAR-compatible
+LZSS encoder is not implemented yet — the writer warns and writes
+independent STORE entries instead, so the archive stays extractable
+by official unrar:
 
 [source,ruby]
 ----
 require 'omnizip/formats/rar/rar5/writer'
 
-# Enable solid compression
 writer = Omnizip::Formats::Rar::Rar5::Writer.new('project.rar',
-  compression: :lzma,
-  level: 5,
-  solid: true  # Shared dictionary across files
+  solid: true  # warns: falls back to independent STORE entries
 )
 writer.add_directory('source_code/')
 writer.write
+----
 
-# Best for:
-# - Source code repositories
-# - Log files
-# - Text documents
-# - Similar structured data
-
-# Trade-offs:
-# - Cannot extract individual files without decompressing entire block
-# - Corruption may affect multiple files
-# - Slightly longer extraction time for single files
+Solid compression (shared dictionary across files, better ratios
+for similar content) arrives when the RAR-compatible LZSS encoder
+lands.
 ----
 
-=== RAR5 AES-256 Encryption (v0.5.0)
+=== RAR5 AES-256 Encryption
 
 Password-protect archives with industry-standard encryption:
 
@@ -177,7 +171,7 @@ writer.write
 # - Password verification before decryption
 ----
 
-=== RAR5 PAR2 Recovery Records (v0.5.0)
+=== RAR5 PAR2 Recovery Records
 
 Add error correction for archive recovery:
 
@@ -216,7 +210,7 @@ files = writer.write
 # - Works with multi-volume, solid, and encrypted archives
 ----
 
-=== RAR5 Combined Features (v0.5.0)
+=== RAR5 Combined Features
 
 Use all features together for comprehensive protection:
 
@@ -262,13 +256,13 @@ puts "  Total size: #{files.sum { |f| File.size(f) } / 1024 / 1024}MB"
 
 === RAR5 Best Practices
 
-**For Maximum Compression:**
+**For Maximum Compatibility:**
 [source,ruby]
 ----
 writer = Omnizip::Formats::Rar::Rar5::Writer.new('archive.rar',
   compression: :lzma,
-  level: 5,        # Best compression
-  solid: true,     # 10-30% better ratios
+  level: 5,        # Honored by the 7z-style writers; RAR5 entries
+                   # are STORE until the LZSS encoder lands
   include_mtime: true
 )
 ----

data/lib/omnizip/cli.rb

@@ -182,8 +182,6 @@ module Omnizip
                       desc: "Password for encryption (7z: header encryption, RAR5: AES-256-CBC)"
     option :encrypt_headers, type: :boolean, default: false,
                              desc: "Encrypt archive headers (7z only, hides filenames)"
-    option :preserve_ntfs_streams, type: :boolean, default: false,
-                                   desc: "Preserve NTFS alternate data streams (Windows only, 7z only)"
     option :rar_version, type: :numeric, default: 5,
                          desc: "RAR version (4 or 5, default: 5 for pure Ruby)"
     option :rar_compression, type: :string, default: "store",

data/lib/omnizip/commands/archive_repair_command.rb

@@ -18,7 +18,7 @@ module Omnizip
       # @param input_path [String] Path to corrupted archive
       # @param output_path [String] Path for repaired archive
       def run(input_path, output_path)
-        raise "Archive not found: #{input_path}" unless File.exist?(input_path)
+        raise Omnizip::IOError, "Archive not found: #{input_path}" unless File.exist?(input_path)
 
         # Detect format
         format = detect_format(input_path)

data/lib/omnizip/commands/archive_verify_command.rb

@@ -18,7 +18,7 @@ module Omnizip
       # @param archive_path [String] Path to archive
       def run(archive_path)
         unless File.exist?(archive_path)
-          raise "Archive not found: #{archive_path}"
+          raise Omnizip::IOError, "Archive not found: #{archive_path}"
         end
 
         # Detect format

data/lib/omnizip/commands/decompress_command.rb

@@ -80,7 +80,10 @@ module Omnizip
         end
       end
 
-      ARCHIVE_EXTENSIONS = %w[.zip .7z .tar .rar .cpio .iso .rpm .xar .msi].freeze
+      # Archive-vs-stream routing derives from the registry's
+      # extension routes so new formats route here automatically
+      ARCHIVE_EXTENSIONS = (Convenience::ARCHIVE_FORMAT_EXTENSIONS.keys +
+                            Convenience::READ_ARCHIVE_FORMAT_EXTENSIONS.keys).freeze
 
       private
 

data/lib/omnizip/entry.rb

@@ -7,7 +7,7 @@ module Omnizip
   # Each format-specific entry class (Zip::Entry, Tar::Entry,
   # SevenZip::Models::FileEntry, Iso::DirectoryRecord, Ole::Dirent,
   # Xar::Entry, Rpm::Entry, Msi::Entry, Cpio::Entry, Rar3::Entry,
-  # Rar5::Entry, Xz::Entry, Metadata::EntryMetadata) includes this
+  # Rar5::Entry, Metadata::EntryMetadata) includes this
   # module so callers can rely on a single narrow interface instead
   # of duck-typing through `respond_to?(:name) / :path / :filename`
   # cascades.

data/lib/omnizip/formats/cpio/entry.rb

@@ -232,7 +232,7 @@ module Omnizip
           when :odc
             parse_odc(io)
           else
-            raise "Unknown CPIO format"
+            raise Omnizip::InvalidArchiveError, "Unknown CPIO format"
           end
         end
 
@@ -258,7 +258,7 @@ module Omnizip
         # @return [Entry] Parsed entry
         def self.parse_newc(io)
           header = io.read(NEWC_HEADER_SIZE)
-          raise "Truncated CPIO header" unless header && header.bytesize == NEWC_HEADER_SIZE
+          raise Omnizip::InvalidArchiveError, "Truncated CPIO header" unless header && header.bytesize == NEWC_HEADER_SIZE
 
           # Parse ASCII hex fields
           magic = header[0, 6]
@@ -318,7 +318,7 @@ module Omnizip
         # @return [Entry] Parsed entry
         def self.parse_odc(io)
           header = io.read(76)
-          raise "Truncated CPIO header" unless header && header.bytesize == 76
+          raise Omnizip::InvalidArchiveError, "Truncated CPIO header" unless header && header.bytesize == 76
 
           # Parse octal fields
           magic = header[0, 6]

data/lib/omnizip/formats/rar/decompressor.rb

@@ -232,7 +232,7 @@ module Omnizip
             archive.extract_to_file(entry_name, output_path,
                                     password: password)
           rescue StandardError => e
-            raise "Gem entry extraction failed: #{e.message}"
+            raise Omnizip::DecompressionError, "Gem entry extraction failed: #{e.message}"
           end
 
           # Extract entry with command
@@ -255,7 +255,7 @@ module Omnizip
               cmd = build_extract_command(archive_path, cached_dir, password)
               unless system(*cmd)
                 FileUtils.rm_rf(cached_dir)
-                raise "Command entry extraction failed: #{entry_name}"
+                raise Omnizip::DecompressionError, "Command entry extraction failed: #{entry_name}"
               end
               extract_cache[cache_key] = cached_dir
               install_exit_sweeper

data/lib/omnizip/formats/rar/external_writer.rb

@@ -138,7 +138,7 @@ module Omnizip
           stdout, stderr, status = Open3.capture3(*cmd)
 
           unless status.success?
-            raise "RAR creation failed: #{stderr}\n#{stdout}"
+            raise Omnizip::CompressionError, "RAR creation failed: #{stderr}\n#{stdout}"
           end
 
           # Test archive if requested
@@ -257,7 +257,7 @@ module Omnizip
 
           return if status.success?
 
-          raise "Archive test failed: #{stderr}\n#{stdout}"
+          raise Omnizip::CompressionError, "Archive test failed: #{stderr}\n#{stdout}"
         end
 
         # Get RAR executable path

data/lib/omnizip/formats/rar/header.rb

@@ -52,10 +52,10 @@ module Omnizip
               @version = 5
               parse_rar5_header(io)
             else
-              raise "Invalid RAR signature: #{(sig_bytes + (extra_byte&.bytes || [])).inspect}"
+              raise Omnizip::InvalidArchiveError, "Invalid RAR signature: #{(sig_bytes + (extra_byte&.bytes || [])).inspect}"
             end
           else
-            raise "Invalid RAR signature: #{sig_bytes.inspect}"
+            raise Omnizip::InvalidArchiveError, "Invalid RAR signature: #{sig_bytes.inspect}"
           end
         end
 
@@ -103,7 +103,7 @@ module Omnizip
           end
 
           unless head_type == BLOCK_ARCHIVE
-            raise "Expected archive block, got 0x#{head_type.to_s(16)}"
+            raise Omnizip::InvalidArchiveError, "Expected archive block, got 0x#{head_type.to_s(16)}"
           end
 
           @flags = head_flags
@@ -140,7 +140,7 @@ module Omnizip
           end
 
           unless header_type == RAR5_HEADER_MAIN
-            raise "Expected main header, got #{header_type}"
+            raise Omnizip::InvalidArchiveError, "Expected main header, got #{header_type}"
           end
 
           @flags = header_flags

data/lib/omnizip/formats/rar/rar5/multi_volume/volume_splitter.rb

@@ -77,8 +77,8 @@ module Omnizip
             # @raise [RuntimeError] if no volume is active
             # @raise [RuntimeError] if data doesn't fit
             def write_to_current_volume(data)
-              raise "No active volume" if @current_volume_number.zero?
-              raise "Data doesn't fit in current volume" unless can_fit_in_current_volume?(data.bytesize)
+              raise Omnizip::CompressionError, "No active volume" if @current_volume_number.zero?
+              raise Omnizip::CompressionError, "Data doesn't fit in current volume" unless can_fit_in_current_volume?(data.bytesize)
 
               @current_volume_data << data
               @current_volume_bytes += data.bytesize

data/lib/omnizip/formats/rar/rar5/multi_volume/volume_writer.rb

@@ -80,7 +80,7 @@ module Omnizip
             #
             # @return [void]
             def write_signature
-              raise "Volume not open" unless @io
+              raise Omnizip::IOError, "Volume not open" unless @io
 
               # RAR5 signature: "Rar!\x1A\x07\x01\x00"
               signature = [0x52, 0x61, 0x72, 0x21, 0x1A, 0x07, 0x01,
@@ -92,7 +92,7 @@ module Omnizip
             #
             # @return [void]
             def write_main_header
-              raise "Volume not open" unless @io
+              raise Omnizip::IOError, "Volume not open" unless @io
 
               # Archive flags: every volume declares 0x0001; volumes
               # after the first also carry the volume number field
@@ -114,7 +114,7 @@ module Omnizip
             # @param compressed_data [String] Compressed file data
             # @return [void]
             def write_file_data(file_header, compressed_data)
-              raise "Volume not open" unless @io
+              raise Omnizip::IOError, "Volume not open" unless @io
 
               @io.write(file_header.encode)
               @io.write(compressed_data)
@@ -124,7 +124,7 @@ module Omnizip
             #
             # @return [void]
             def write_end_header
-              raise "Volume not open" unless @io
+              raise Omnizip::IOError, "Volume not open" unless @io
 
               # End-of-archive flags: 0x0001 marks a volume with more
               # volumes following; the last volume ends with 0.

data/lib/omnizip/formats/rar/rar5/writer.rb

@@ -199,6 +199,11 @@ module Omnizip
               if @options[:solid] && Compression::Lzss.available?
                 write_solid_block(f, @files)
               else
+                if @options[:solid]
+                  warn "omnizip: solid: true requested but the " \
+                       "RAR-compatible LZSS encoder is not available " \
+                       "— writing independent STORE entries instead"
+                end
                 @files.each do |file|
                   write_file_entry(f, file)
                 end

data/lib/omnizip/formats/rar/recovery_record.rb

@@ -229,7 +229,7 @@ module Omnizip
 
           loop do
             byte = io.read(1)&.unpack1("C")
-            raise "Unexpected EOF" unless byte
+            raise Omnizip::InvalidArchiveError, "Unexpected EOF" unless byte
 
             result |= (byte & 0x7F) << shift
             break if byte.nobits?(0x80)

data/lib/omnizip/formats/tar/header.rb

@@ -47,6 +47,11 @@ module Omnizip
             entry.prefix = extract_string(
               header_data, PREFIX_OFFSET, PREFIX_SIZE
             )
+            # ustar stores long paths split across prefix + name;
+            # consumers see the joined path
+            unless entry.prefix.empty?
+              entry.name = "#{entry.prefix}/#{entry.name}"
+            end
           end
 
           # Verify checksum
@@ -69,7 +74,8 @@ module Omnizip
           header = "\0" * HEADER_SIZE
 
           # Write fields to header
-          write_string(header, entry.name, NAME_OFFSET, NAME_SIZE)
+          name, prefix = split_long_name(entry.name, entry.prefix)
+          write_string(header, name, NAME_OFFSET, NAME_SIZE)
           write_octal(header, entry.mode, MODE_OFFSET, MODE_SIZE)
           write_octal(header, entry.uid, UID_OFFSET, UID_SIZE)
           write_octal(header, entry.gid, GID_OFFSET, GID_SIZE)
@@ -87,7 +93,7 @@ module Omnizip
           write_string(header, entry.gname, GNAME_OFFSET, GNAME_SIZE)
           write_octal(header, entry.devmajor, DEVMAJOR_OFFSET, DEVMAJOR_SIZE)
           write_octal(header, entry.devminor, DEVMINOR_OFFSET, DEVMINOR_SIZE)
-          write_string(header, entry.prefix, PREFIX_OFFSET, PREFIX_SIZE)
+          write_string(header, prefix, PREFIX_OFFSET, PREFIX_SIZE)
 
           # Calculate and write checksum
           checksum = Entry.calculate_checksum(header)
@@ -130,6 +136,41 @@ module Omnizip
           field.strip.to_i(8)
         end
 
+        # Split a path for the ustar name (100) + prefix (155)
+        # fields. Paths under 100 bytes pass through; longer paths
+        # split at a "/" boundary, preferring the longest prefix
+        # that keeps both halves in bounds. Raises when no ustar
+        # representation exists — silent truncation corrupts
+        # archives.
+        #
+        # @param path [String] Full entry path
+        # @param prefix [String] Explicit prefix (wins when given)
+        # @return [Array<String>] [name, prefix] pair
+        def self.split_long_name(path, prefix = nil)
+          path = path.to_s
+          prefix = prefix.to_s
+          return [path, prefix] if !prefix.empty? || path.bytesize < NAME_SIZE
+
+          best = nil
+          offset = -1
+          while (slash = path.index("/", offset + 1))
+            candidate_prefix = path[0...slash]
+            candidate_name = path[(slash + 1)..]
+            offset = slash
+
+            next if candidate_prefix.bytesize >= PREFIX_SIZE
+            next if candidate_name.bytesize >= NAME_SIZE
+
+            best = [candidate_name, candidate_prefix]
+          end
+
+          return best if best
+
+          raise Omnizip::FormatError,
+                "Path too long for the ustar name+prefix fields " \
+                "(no PAX/GNU long-name support): #{path}"
+        end
+
         # Write a string to header
         #
         # @param header [String] Header data

data/lib/omnizip/formats/zip/writer.rb

@@ -152,6 +152,8 @@ module Omnizip
         end
 
         def write_precompressed_to_io(io, compression_method: COMPRESSION_DEFLATE)
+          check_classic_entry_count!
+          entries.each { |entry| check_classic_size_limit!(entry) }
           local_header_offsets = []
 
           entries.each do |entry|
@@ -189,6 +191,7 @@ module Omnizip
 
         # Write to an IO object
         def write_to_io(io, compression_method: COMPRESSION_DEFLATE, level: 6)
+          check_classic_entry_count!
           local_header_offsets = []
 
           # Write local file headers and data. An entry-level
@@ -220,6 +223,8 @@ module Omnizip
               entry[:crc32] = calculate_crc32(entry[:uncompressed_data])
             end
 
+            check_classic_size_limit!(entry)
+
             # Update local header with compressed sizes
             local_header.compressed_size = entry[:compressed_size]
             local_header.uncompressed_size = entry[:uncompressed_size]
@@ -234,6 +239,7 @@ module Omnizip
 
           # Record start of central directory
           central_directory_offset = io.pos
+          check_classic_offset_limit!(central_directory_offset)
 
           # Write central directory headers
           entries.each_with_index do |entry, index|
@@ -257,8 +263,42 @@ module Omnizip
           io.write(eocd.to_binary)
         end
 
+        # Classic (non-ZIP64) ZIP headers pack sizes and offsets as
+        # 32-bit values and entry counts as 16-bit; exceeding them
+        # raises instead of letting Array#pack fail with a bare
+        # RangeError. ZIP64 writing is not supported.
+        MAX_CLASSIC_SIZE = 0xFFFFFFFF
+        MAX_CLASSIC_ENTRIES = 0xFFFF
+        private_constant :MAX_CLASSIC_SIZE, :MAX_CLASSIC_ENTRIES
+
         private
 
+        def check_classic_entry_count!
+          return if entries.size <= MAX_CLASSIC_ENTRIES
+
+          raise Omnizip::UnsupportedFormatError,
+                "#{entries.size} entries exceed the classic ZIP " \
+                "limit of #{MAX_CLASSIC_ENTRIES} (ZIP64 writing is " \
+                "not supported)"
+        end
+
+        def check_classic_size_limit!(entry)
+          return if entry[:compressed_size].to_i <= MAX_CLASSIC_SIZE &&
+            entry[:uncompressed_size].to_i <= MAX_CLASSIC_SIZE
+
+          raise Omnizip::UnsupportedFormatError,
+                "entry #{entry[:filename].inspect} exceeds the 4 GiB " \
+                "classic ZIP size limit (ZIP64 writing is not supported)"
+        end
+
+        def check_classic_offset_limit!(offset)
+          return if offset <= MAX_CLASSIC_SIZE
+
+          raise Omnizip::UnsupportedFormatError,
+                "archive layout exceeds the 4 GiB classic ZIP " \
+                "offset limit (ZIP64 writing is not supported)"
+        end
+
         # Create an entry hash
         def create_entry(
           filename:,

data/lib/omnizip/parity/par2_creator.rb

@@ -151,7 +151,7 @@ progress: nil)
       #
       # @raise [StandardError] if no files added
       def validate_files!
-        raise "No files added to PAR2 set" if @files.empty?
+        raise ArgumentError, "No files added to PAR2 set" if @files.empty?
       end
 
       # Generate unique set ID for this PAR2 set

data/lib/omnizip/parity/par2_repairer.rb

@@ -244,7 +244,7 @@ module Omnizip
 
         # Ensure metadata is loaded
         if file_list.nil? || file_list.empty?
-          raise "Internal error: file_list not populated in verifier"
+          raise Omnizip::Error, "Internal error: file_list not populated in verifier"
         end
 
         block_idx = 0

data/lib/omnizip/parity/par2cmdline_algorithm.rb

@@ -35,7 +35,7 @@ module Omnizip
           # Find next logbase where gcd(65535, logbase) == 1
           logbase += 1 while gcd(limit, logbase) != 1
 
-          raise "Too many input blocks" if logbase >= limit
+          raise ArgumentError, "Too many input blocks" if logbase >= limit
 
           # Use antilog to convert logbase to base value
           # This is the key: base = antilog[logbase]

data/lib/omnizip/parity/reed_solomon_decoder.rb

@@ -109,7 +109,7 @@ recovery_exponents, bases)
         num_rows.times do |pivot_row|
           # Get pivot value from right matrix diagonal
           pivot = right_matrix[pivot_row][pivot_row]
-          raise "Singular matrix at row #{pivot_row}" if pivot.zero?
+          raise Omnizip::Error, "Singular matrix at row #{pivot_row}" if pivot.zero?
 
           # Scale pivot row to make pivot = 1
           unless pivot == 1

data/lib/omnizip/parity/reed_solomon_matrix.rb

@@ -117,7 +117,7 @@ total_inputs, block_size)
       # @param recovery_idx [Integer] Recovery block index (0..recovery_count-1)
       # @return [Integer] Galois field coefficient
       def coefficient(output_idx, recovery_idx)
-        raise "Matrix not computed - call compute! first" unless @matrix
+        raise Omnizip::Error, "Matrix not computed - call compute! first" unless @matrix
 
         # After transpose, indices are swapped: @matrix[recovery_idx][output_idx]
         @matrix[recovery_idx][output_idx]
@@ -200,7 +200,7 @@ output_offset: 0)
 
         num_rows.times do |pivot_row|
           pivot = left_matrix[pivot_row][pivot_row]
-          raise "Singular matrix at row #{pivot_row}" if pivot.zero?
+          raise Omnizip::Error, "Singular matrix at row #{pivot_row}" if pivot.zero?
 
           # Scale pivot row to make pivot = 1
           unless pivot == 1

data/lib/omnizip/profile.rb

@@ -181,11 +181,11 @@ module Omnizip
 
       private
 
-      # Depth-first search for the first regular file under +dir+.
+      # Depth-first search for the first regular file under +dir+,
+      # in sorted child order — :auto sampling must not depend on
+      # the OS's directory iteration order.
       def first_file_within(dir)
-        ::Dir.foreach(dir) do |entry|
-          next if [".", ".."].include?(entry)
-
+        ::Dir.children(dir).sort.each do |entry|
           full_path = ::File.join(dir, entry)
           return full_path if ::File.file?(full_path)
 

data/lib/omnizip/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Omnizip
-  VERSION = "0.3.56"
+  VERSION = "0.3.58"
 end

data/lib/omnizip/zip/file.rb

@@ -130,7 +130,7 @@ module Omnizip
             action = yield(entry, dest_path)
             return if action == false
           else
-            raise "Destination file already exists: #{dest_path}"
+            raise Errno::EEXIST, "Destination file already exists: #{dest_path}"
           end
         end
 

data/lib/omnizip/zip/output_stream.rb

@@ -75,7 +75,7 @@ compression: :deflate, level: 6)
       # Write data to current entry
       # @param data [String] Data to write
       def write(data)
-        raise "No entry started. Call put_next_entry first" unless @current_entry
+        raise Omnizip::IOError, "No entry started. Call put_next_entry first" unless @current_entry
 
         @current_entry_data << data.b
         self

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: omnizip
 version: !ruby/object:Gem::Version
-  version: 0.3.56
+  version: 0.3.58
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-02 00:00:00.000000000 Z
+date: 2026-09-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64