omnizip 0.3.1

data/lib/omnizip/algorithms/lzma/lzma_alone_decoder.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+# Copyright (C) 2025 Ribose Inc.
+#
+# Permission is hereby granted, free of charge, to any person obtaining a
+# copy of this software and associated documentation files (the "Software"),
+# to deal in the Software without restriction, including without limitation
+# the rights to use, copy, modify, merge, publish, distribute, sublicense,
+# and/or sell copies of the Software, and to permit persons to whom the
+# Software is furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+# DEALINGS IN THE SOFTWARE.
+
+require_relative "xz_utils_decoder"
+require "stringio"
+
+module Omnizip
+  module Algorithms
+    class LZMA < Algorithm
+      #
+      # Decoder for .lzma (LZMA_Alone) format
+      #
+      # This is the legacy LZMA_Alone format used by LZMA Utils 4.32.x.
+      # It is DIFFERENT from the XZ format's LZMA2 compression!
+      #
+      # File format:
+      # - Properties (1 byte): encodes lc, lp, pb values
+      # - Dictionary size (4 bytes, little-endian)
+      # - Uncompressed size (8 bytes, little-endian, UINT64_MAX = unknown)
+      # - LZMA1 compressed stream (no footer, no CRC32)
+      #
+      # Reference: /Users/mulgogi/src/external/xz/src/liblzma/common/alone_decoder.c
+      #
+      # This decoder uses the same LZMA1 decoding engine as XZ format,
+      # but with the legacy .lzma container format.
+      #
+      # @example Decode .lzma file
+      #   data = File.binread("file.lzma")
+      #   decoder = Omnizip::Algorithms::LZMA::LzmaAloneDecoder.new(StringIO.new(data))
+      #   result = decoder.decode_stream
+      #
+      class LzmaAloneDecoder
+        # Maximum valid uncompressed size (256 GiB)
+        # From alone_decoder.c:118
+        MAX_UNCOMPRESSED_SIZE = (1 << 38)
+
+        # Property byte validation limits
+        # From lzma_decoder.c:1218
+        MAX_PROPERTY_BYTE = (((4 * 5) + 4) * 9) + 8 # = 233
+
+        # Initialize the decoder with .lzma format input
+        #
+        # @param input [IO] Input stream of .lzma compressed data
+        # @param options [Hash] Decoding options
+        # @option options [Boolean] :picky If true, reject files unlikely to be .lzma (default: false)
+        # @raise [RuntimeError] If header is invalid or unsupported
+        def initialize(input, options = {})
+          @input = input
+          @picky = options.fetch(:picky, false)
+
+          # Parse .lzma header
+          parse_header
+
+          # Create a wrapper stream that starts after the header
+          # The XzUtilsDecoder will read from this stream
+          @lzma_stream = @input
+
+          # Initialize the XZ Utils LZMA decoder with parsed parameters
+          # validate_size=true because .lzma format has explicit uncompressed size
+          # allow_eopm=true because .lzma format allows EOPM even with known size
+          # Reference: alone_decoder.c:127 (LZMA_LZMA1EXT_ALLOW_EOPM)
+          @decoder = XzUtilsDecoder.new(@lzma_stream,
+                                        lzma2_mode: true,
+                                        validate_size: true,
+                                        allow_eopm: true,
+                                        lc: @lc,
+                                        lp: @lp,
+                                        pb: @pb,
+                                        dict_size: @dict_size,
+                                        uncompressed_size: @uncompressed_size)
+        end
+
+        # Decode the .lzma stream
+        #
+        # @param output [IO, nil] Optional output stream
+        # @return [String, Integer] Decompressed data or bytes written
+        def decode_stream(output = nil)
+          # .lzma format allows EOPM even when uncompressed size is known
+          # Reference: alone_decoder.c:127 (LZMA_LZMA1EXT_ALLOW_EOPM)
+          @decoder.decode_stream(output, check_rc_finished: false)
+        end
+
+        private
+
+        # Parse .lzma format header
+        #
+        # Format (from alone_decoder.c):
+        # - Properties (1 byte): lc/lp/pb encoded
+        # - Dictionary size (4 bytes, little-endian)
+        # - Uncompressed size (8 bytes, little-endian, UINT64_MAX = unknown)
+        #
+        # Reference: /Users/mulgogi/src/external/xz/src/liblzma/common/alone_decoder.c
+        #
+        # @return [void]
+        # @raise [RuntimeError] If header is invalid
+        def parse_header
+          # Step 1: Parse properties byte (SEQ_PROPERTIES)
+          # Reference: alone_decoder.c:64-68
+          props = @input.getbyte
+          raise "Invalid .lzma header: missing properties byte" if props.nil?
+
+          # Use XZ Utils property byte parsing
+          # Reference: /Users/mulgogi/src/external/xz/src/liblzma/lzma/lzma_decoder.c:1216-1228
+          if props > MAX_PROPERTY_BYTE
+            raise "Invalid .lzma header: properties byte #{props} exceeds maximum #{MAX_PROPERTY_BYTE}"
+          end
+
+          # Parse lc, lp, pb from properties byte
+          # Formula: pb = props / (9 * 5); lp = (props % 45) / 9; lc = (props % 45) % 9
+          @pb = props / (9 * 5)
+          remainder = props - (@pb * 9 * 5)
+          @lp = remainder / 9
+          @lc = remainder - (@lp * 9)
+
+          # Validate lc + lp <= 4 (LZMA_LCLP_MAX)
+          # Reference: lzma_decoder.c:1227
+          if @lc + @lp > 4
+            raise "Invalid .lzma header: lc (#{@lc}) + lp (#{@lp}) exceeds maximum 4"
+          end
+
+          # Step 2: Parse dictionary size (SEQ_DICTIONARY_SIZE)
+          # Reference: alone_decoder.c:71-96
+          @dict_size = 0
+          4.times do |i|
+            byte = @input.getbyte
+            raise "Incomplete .lzma header: missing dictionary size byte" if byte.nil?
+
+            @dict_size |= (byte << (i * 8))
+          end
+
+          # Picky mode validation: only accept dictionary sizes that are
+          # 2^n or 2^n + 2^(n-1). This reduces false positives.
+          # Reference: alone_decoder.c:76-93
+          if @picky && @dict_size != 0xFFFFFFFF
+            # Check if dict_size is valid: 2^n or 2^n + 2^(n-1)
+            d = @dict_size - 1
+            d |= d >> 2
+            d |= d >> 3
+            d |= d >> 4
+            d |= d >> 8
+            d |= d >> 16
+            d += 1
+
+            if d != @dict_size
+              raise "Invalid .lzma header: dictionary size #{@dict_size} is not 2^n or 2^n + 2^(n-1)"
+            end
+          end
+
+          # Step 3: Parse uncompressed size (SEQ_UNCOMPRESSED_SIZE)
+          # Reference: alone_decoder.c:102-120
+          @uncompressed_size = 0
+          8.times do |i|
+            byte = @input.getbyte
+            raise "Incomplete .lzma header: missing uncompressed size byte" if byte.nil?
+
+            @uncompressed_size |= (byte << (i * 8))
+          end
+
+          # Picky mode validation: if uncompressed size is known (not UINT64_MAX),
+          # it must be less than 256 GiB
+          # Reference: alone_decoder.c:116-120
+          if @picky && @uncompressed_size != 0xFFFFFFFFFFFFFFFF &&
+              @uncompressed_size >= MAX_UNCOMPRESSED_SIZE
+            raise "Invalid .lzma header: uncompressed size #{@uncompressed_size} exceeds maximum #{MAX_UNCOMPRESSED_SIZE}"
+          end
+
+          # Note: XZ Utils uses UINT64_MAX (0xFFFFFFFFFFFFFFFF) for unknown size
+          # Our decoder treats this as "allow end-of-payload marker"
+        end
+      end
+    end
+  end
+end

data/lib/omnizip/algorithms/lzma/lzma_state.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Omnizip
+  module Algorithms
+    class LZMA < Algorithm
+      # LZMA State Machine
+      # Ported from XZ Utils lzma_common.h and lzma_decoder.c
+      class LZMAState
+        # State transition table (from lzma_decoder.c)
+        TRANSITIONS = {
+          # Literal after literal (matches XZ Utils update_literal macro)
+          update_literal: {
+            0 => 0, 1 => 0, 2 => 0, 3 => 0, 4 => 1, 5 => 2,
+            6 => 3, 7 => 4, 8 => 5, 9 => 6, 10 => 4, 11 => 5
+          }.freeze,
+
+          # Matched literal (literal after match, matches XZ Utils update_literal_matched macro)
+          # Only called when previous state was NOT a literal (states 7-11)
+          update_literal_matched: {
+            0 => 0, 1 => 0, 2 => 0, 3 => 0, 4 => 1, 5 => 2,
+            6 => 3, 7 => 4, 8 => 5, 9 => 6, 10 => 4, 11 => 5
+          }.freeze,
+
+          # Regular match
+          update_match: {
+            0 => 7, 1 => 7, 2 => 7, 3 => 7, 4 => 7, 5 => 7,
+            6 => 7, 7 => 10, 8 => 10, 9 => 10, 10 => 10, 11 => 10
+          }.freeze,
+
+          # Repeat match
+          update_rep: {
+            0 => 8, 1 => 8, 2 => 8, 3 => 8, 4 => 8, 5 => 8,
+            6 => 8, 7 => 11, 8 => 11, 9 => 11, 10 => 11, 11 => 11
+          }.freeze,
+
+          # Short repeat (length=1)
+          update_short_rep: {
+            0 => 9, 1 => 9, 2 => 9, 3 => 9, 4 => 9, 5 => 9,
+            6 => 9, 7 => 11, 8 => 11, 9 => 11, 10 => 11, 11 => 11
+          }.freeze,
+
+          # Long repeat (length>1)
+          # Ported from XZ Utils: state < LIT_STATES ? STATE_LIT_LONGREP : STATE_NONLIT_REP
+          # where LIT_STATES=7, STATE_LIT_LONGREP=8, STATE_NONLIT_REP=11
+          update_long_rep: {
+            0 => 8, 1 => 8, 2 => 8, 3 => 8, 4 => 8, 5 => 8,
+            6 => 8, 7 => 11, 8 => 11, 9 => 11, 10 => 11, 11 => 11
+          }.freeze,
+        }.freeze
+
+        attr_reader :value, :reps
+
+        def initialize(value = 0)
+          @value = value
+          @reps = [0, 0, 0, 0] # Initial repeat distances (matches XZ Utils)
+        end
+
+        # After encoding a literal
+        def update_literal!
+          @value = if use_matched_literal?
+                     TRANSITIONS[:update_literal_matched][@value]
+                   else
+                     TRANSITIONS[:update_literal][@value]
+                   end
+        end
+
+        # After encoding a regular match
+        def update_match!(distance)
+          @value = TRANSITIONS[:update_match][@value]
+          rotate_reps!(distance)
+        end
+
+        # After encoding a repeat match
+        def update_rep!(rep_index)
+          @value = TRANSITIONS[:update_rep][@value]
+          rotate_reps_for_rep!(rep_index)
+        end
+
+        # After encoding a short rep (length=1)
+        def update_short_rep!
+          @value = TRANSITIONS[:update_short_rep][@value]
+        end
+
+        # After encoding a long rep (length>1)
+        # Ported from XZ Utils update_long_rep macro
+        def update_long_rep!
+          @value = TRANSITIONS[:update_long_rep][@value]
+        end
+
+        # Check if we should use matched literal encoding
+        # XZ Utils logic: is_literal_state(state) = (state < LIT_STATES)
+        # where LIT_STATES = 7
+        # States 0-6: literal states (use unmatched literal)
+        # States 7-11: non-literal states (use matched literal)
+        def use_matched_literal?
+          @value >= 7
+        end
+
+        # Repeat distance rotation
+        def rotate_reps!(distance)
+          @reps[3] = @reps[2]
+          @reps[2] = @reps[1]
+          @reps[1] = @reps[0]
+          @reps[0] = distance
+        end
+
+        private
+
+        def rotate_reps_for_rep!(rep_index)
+          case rep_index
+          when 0
+            # Keep rep0, no rotation
+          when 1
+            # rep1 -> rep0
+            @reps[0], @reps[1] = @reps[1], @reps[0]
+          when 2
+            # rep2 -> rep0, rep0 -> rep1, rep1 -> rep2
+            @reps[0], @reps[1], @reps[2] = @reps[2], @reps[0], @reps[1]
+          when 3
+            # rep3 -> rep0, rotate others
+            @reps[0], @reps[1], @reps[2], @reps[3] =
+              @reps[3], @reps[0], @reps[1], @reps[2]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/omnizip/algorithms/lzma/match.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Omnizip
+  module Algorithms
+    class LZMA < Algorithm
+      # Match candidate result from LZ77 match finding
+      class Match
+        attr_reader :distance, :length
+
+        def initialize(distance, length)
+          @distance = distance
+          @length = length
+        end
+
+        # Check if match is valid for given dictionary size
+        #
+        # @param dict_size [Integer] Dictionary size in bytes
+        # @return [Boolean] true if match is valid
+        def valid?(dict_size)
+          @distance <= dict_size && @length >= 2
+        end
+
+        # String representation for debugging
+        #
+        # @return [String] Match description
+        def to_s
+          "Match(dist=#{@distance}, len=#{@length})"
+        end
+      end
+    end
+  end
+end

data/lib/omnizip/algorithms/lzma/match_finder.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+# Copyright (C) 2025 Ribose Inc.
+#
+# Permission is hereby granted, free of charge, to any person obtaining a
+# copy of this software and associated documentation files (the "Software"),
+# to deal in the Software without restriction, including without limitation
+# the rights to use, copy, modify, merge, publish, distribute, sublicense,
+# and/or sell copies of the Software, and to permit persons to whom the
+# Software is furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+# DEALINGS IN THE SOFTWARE.
+
+require_relative "match"
+
+module Omnizip
+  module Algorithms
+    class LZMA < Algorithm
+      # Match Finder using hash chain algorithm for LZ77 compression
+      # Ported from XZ Utils lz_encoder.c
+      class MatchFinder
+        HASH_SIZE = 4096
+        MAX_MATCHES = 274
+
+        attr_reader :dictionary, :buffer, :position
+
+        def initialize(dictionary)
+          @dictionary = dictionary
+          @buffer = String.new(encoding: Encoding::BINARY)
+          @position = 0
+          # Use nil as empty marker (not 0) to distinguish from position 0
+          @hash_table = Array.new(HASH_SIZE, nil)
+          @hash_chain = Array.new(0)
+          @matches = Array.new(MAX_MATCHES)
+          @matches_count = 0
+        end
+
+        # Add input data for processing
+        #
+        # @param data [String] Binary data to add
+        # @return [void]
+        def feed(data)
+          @buffer << data
+        end
+
+        # Reset the match finder state for a new encoding session
+        # Clears the buffer, hash table, and hash chain
+        def reset
+          @buffer.clear
+          @position = 0
+          @hash_table = Array.new(HASH_SIZE, nil)
+          @hash_chain.clear
+          @matches_count = 0
+        end
+
+        # Initialize hash table for all positions up to end_pos
+        # This is called before encoding starts to ensure the hash table
+        # is populated for all positions. Matches XZ Utils "skip" behavior.
+        #
+        # @param end_pos [Integer] Last position to initialize (inclusive)
+        # @return [void]
+        def skip(end_pos)
+          pos = 0
+          while pos + 3 <= @buffer.bytesize && pos <= end_pos
+            hash = calc_hash(@buffer, pos)
+            if hash
+              @hash_chain[pos] = @hash_table[hash]
+              @hash_table[hash] = pos
+            end
+            pos += 1
+          end
+        end
+
+        # Find matches for current position
+        #
+        # @param current_pos [Integer] Position to find matches at (defaults to end)
+        # @return [Array<Match>] Array of matches sorted by length (descending)
+        def find_matches(current_pos = @buffer.bytesize - 273)
+          # Calculate hash for current position
+          hash = nil
+          if current_pos >= 0 && current_pos + 3 <= @buffer.bytesize
+            hash = calc_hash(@buffer, current_pos)
+          end
+
+          # Update hash table for current position (even for early positions)
+          # This ensures positions 0-3 are available for later matches
+          # XZ Utils calls this "skip" - update hash without finding matches
+          # CRITICAL: Only update if this position hasn't been processed yet
+          # (i.e., @hash_table[hash] != current_pos)
+          # This prevents overwriting the hash chain when find_matches is called
+          # after skip() has already initialized the hash table
+          if hash && @hash_table[hash] != current_pos
+            @hash_chain[current_pos] = @hash_table[hash]
+            @hash_table[hash] = current_pos
+          end
+
+          # Can't find matches if no hash or insufficient data
+          # Note: We CAN find matches at early positions (e.g., position 2 can match position 0)
+          # The only requirement is that there's enough data for hash calculation (current_pos + 3 <= buffer size)
+          # and that there's at least 2 bytes of history (for MIN_MATCH_LENGTH=2)
+          # CRITICAL: Don't produce matches until position >= 2 to ensure decoder has enough dict_full
+          # The decoder validates: dict_full > distance, where dict_full starts at 0 after 1st byte
+          # For distance=1 match to be valid, decoder needs dict_full >= 2 (at least 2 bytes decoded)
+          # This happens after processing position 1 (first byte was literal at position 0)
+          # So we can only produce matches starting at position 2
+          return [] if hash.nil? || @buffer.bytesize < 4 || current_pos + 3 > @buffer.bytesize || current_pos < 2
+
+          @matches_count = 0
+          chain_pos = @hash_chain[current_pos]
+
+          while chain_pos && @matches_count < MAX_MATCHES
+            # CRITICAL: Skip invalid chain_pos values (beyond buffer or negative)
+            next if chain_pos >= @buffer.bytesize || chain_pos.negative?
+
+            distance = current_pos - chain_pos
+            # CRITICAL: Break if distance is negative (chain_pos > current_pos)
+            # This can happen when skip() links positions within the same chunk
+            # where a later position has the same hash as an earlier position
+            break if distance.negative? || distance > @dictionary.size || distance.zero?
+
+            length = verify_match(current_pos, chain_pos)
+
+            if length >= 2
+              @matches[@matches_count] = Match.new(distance, length)
+              @matches_count += 1
+            end
+
+            # Safely get next chain position
+            chain_pos = if chain_pos < @hash_chain.size
+                          @hash_chain[chain_pos]
+                        end
+          end
+
+          @matches.first(@matches_count).sort_by { |m| -m.length }
+        end
+
+        # Get the longest match at current position
+        #
+        # @return [Match, nil] Longest match found or nil
+        def longest_match
+          find_matches.first
+        end
+
+        # Legacy API: Find longest match at given position in external byte array
+        # This is a compatibility method for older code that passes bytes and position
+        #
+        # @param bytes [Array<Integer>] Byte array
+        # @param pos [Integer] Position to find match at
+        # @return [Match, nil] Longest match found or nil
+        def find_longest_match(bytes, pos)
+          # If position is beyond current buffer, feed more data
+          if pos >= @buffer.bytesize
+            bytes_to_feed = bytes[pos..]
+            @buffer << bytes_to_feed.pack("C*")
+          end
+
+          # Find matches at the given position
+          matches = find_matches(pos)
+          matches.first
+        end
+
+        private
+
+        # Calculate hash for position (first 3 bytes)
+        #
+        # @param data [String] Buffer data
+        # @param pos [Integer] Position to hash
+        # @return [Integer] Hash value
+        def calc_hash(data, pos)
+          return 0 if pos + 3 > data.bytesize
+
+          (data.getbyte(pos) |
+           (data.getbyte(pos + 1) << 8) |
+           (data.getbyte(pos + 2) << 16)) % HASH_SIZE
+        end
+
+        # Verify match length between two positions
+        #
+        # @param pos1 [Integer] First position
+        # @param pos2 [Integer] Second position
+        # @return [Integer] Match length
+        def verify_match(pos1, pos2)
+          max_len = [273, @buffer.bytesize - pos1, @buffer.bytesize - pos2].min
+          length = 0
+
+          while length < max_len &&
+              @buffer.getbyte(pos1 + length) == @buffer.getbyte(pos2 + length)
+            length += 1
+          end
+
+          length
+        end
+      end
+    end
+  end
+end

data/lib/omnizip/algorithms/lzma/match_finder_config.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+# Copyright (C) 2025 Ribose Inc.
+#
+# Permission is hereby granted, free of charge, to any person obtaining a
+# copy of this software and associated documentation files (the "Software"),
+# to deal in the Software without restriction, including without limitation
+# the rights to use, copy, modify, merge, publish, distribute, sublicense,
+# and/or sell copies of the Software, and to permit persons to whom the
+# Software is furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+# DEALINGS IN THE SOFTWARE.
+
+module Omnizip
+  module Algorithms
+    class LZMA < Algorithm
+      # Configuration model for Match Finder behavior
+      #
+      # This model separates configuration from implementation, allowing
+      # different match finding strategies (SDK-compatible vs simplified)
+      # to be configured declaratively.
+      #
+      # @example SDK-compatible configuration
+      #   config = MatchFinderConfig.new(
+      #     mode: :sdk,
+      #     hash_size: 65536,
+      #     chain_length: 32,
+      #     lazy_matching: false
+      #   )
+      #
+      # @example Simplified configuration
+      #   config = MatchFinderConfig.new(
+      #     mode: :simplified,
+      #     hash_size: 65536,
+      #     chain_length: 1024
+      #   )
+      class MatchFinderConfig
+        attr_accessor :mode, :hash_size, :chain_length, :search_mode,
+                      :lazy_matching, :max_match_length, :window_size
+
+        def initialize(mode: "simplified", hash_size: 65_536,
+                       chain_length: 1024, search_mode: "hash_chain",
+                       lazy_matching: false, max_match_length: 273,
+                       window_size: 65_536)
+          @mode = mode
+          @hash_size = hash_size
+          @chain_length = chain_length
+          @search_mode = search_mode
+          @lazy_matching = lazy_matching
+          @max_match_length = max_match_length
+          @window_size = window_size
+        end
+
+        # Validate configuration
+        #
+        # @return [Boolean] true if valid
+        # @raise [ArgumentError] if configuration is invalid
+        def validate!
+          unless %w[sdk simplified].include?(mode)
+            raise ArgumentError, "mode must be :sdk or :simplified"
+          end
+
+          unless %w[hash_chain binary_tree].include?(search_mode)
+            raise ArgumentError,
+                  "search_mode must be :hash_chain or :binary_tree"
+          end
+
+          raise ArgumentError, "hash_size must be positive" if hash_size <= 0
+
+          if chain_length <= 0
+            raise ArgumentError,
+                  "chain_length must be positive"
+          end
+          if max_match_length < 2
+            raise ArgumentError,
+                  "max_match_length must be >= 2"
+          end
+          if window_size <= 0
+            raise ArgumentError,
+                  "window_size must be positive"
+          end
+
+          true
+        end
+
+        # Create SDK-compatible configuration
+        #
+        # @param dict_size [Integer] Dictionary size
+        # @param level [Integer] Compression level (0-9)
+        # @return [MatchFinderConfig] SDK-compatible configuration
+        def self.sdk_config(dict_size: 65536, level: 5)
+          # SDK uses different parameters based on dictionary size and level
+          hash_size = dict_size >= (1 << 20) ? (1 << 20) : (1 << 16)
+
+          # SDK nice_len varies by compression level:
+          # Level 0-4: 32, Level 5-6: 64, Level 7-8: 128, Level 9: 273
+          chain_length = case level
+                         when 0..4 then 32
+                         when 5..6 then 64
+                         when 7..8 then 128
+                         else 273
+                         end
+
+          new(
+            mode: "sdk",
+            hash_size: hash_size,
+            chain_length: chain_length,
+            search_mode: "hash_chain",
+            lazy_matching: level >= 7, # Enable lazy matching for high compression
+            max_match_length: 273,
+            window_size: dict_size,
+          )
+        end
+
+        # Create simplified configuration (backward compatible)
+        #
+        # @param dict_size [Integer] Dictionary size
+        # @return [MatchFinderConfig] Simplified configuration
+        def self.simplified_config(dict_size: 65536)
+          new(
+            mode: "simplified",
+            hash_size: 65536,
+            chain_length: 1024,
+            search_mode: "hash_chain",
+            lazy_matching: false,
+            max_match_length: 273,
+            window_size: dict_size,
+          )
+        end
+      end
+    end
+  end
+end