omnizip 0.3.8 → 0.3.10

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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "stringio"
+
 # Copyright (C) 2025 Ribose Inc.
 #
 # Permission is hereby granted, free of charge, to any person obtaining a
@@ -40,13 +42,6 @@ module Omnizip
     # - XZ format (.xz files)
     # - LZMA2 compression in XZ format
     #
-    module XzUtilsDecoderDebug
-      # Debug helper to conditionally output debug messages
-      # Set ENV['LZMA_DEBUG'] = 'true' to enable all debug output
-      def self.debug_puts(*args)
-        puts(*args) if ENV["LZMA_DEBUG"]
-      end
-    end
 
     # XZ Utils implementation of LZMA decoder
     #
@@ -91,13 +86,58 @@ module Omnizip
       RangeDecoder = LZMA::RangeDecoder
       SdkStateMachine = Implementations::SevenZip::LZMA::StateMachine
 
-      attr_reader :lc, :lp, :pb, :dict_size, :uncompressed_size
+      attr_reader :lc, :lp, :pb, :dict_size, :uncompressed_size,
+                  :range_decoder
 
       # XZ Utils dictionary constants (from lz_decoder.h)
       # See: /Users/mulgogi/src/external/xz/src/liblzma/lz/lz_decoder.h
       LZ_DICT_REPEAT_MAX = 288
       LZ_DICT_INIT_POS = 2 * LZ_DICT_REPEAT_MAX # = 576
 
+      # Map a monotonic position to a circular buffer index.
+      # Buffer layout: [LZ_DICT_INIT_POS zero bytes] + [dict_size circular region]
+      # @pos grows forever; this maps it to the fixed-size buffer.
+      # Matches C++ 7-Zip SDK: dic[dicPos] with dicPos wrapping at dicBufSize.
+      def dict_index(pos)
+        LZ_DICT_INIT_POS + ((pos - LZ_DICT_INIT_POS) % @dict_size)
+      end
+
+      # Flush decoded output from the circular dictionary buffer.
+      # Copies bytes from @flush_pos to @pos into the output stream or accumulator.
+      # Handles wrap-around when the data spans the circular buffer boundary.
+      def flush_circular_output(output)
+        return if @pos == @flush_pos
+
+        length = @pos - @flush_pos
+
+        if length > @dict_size
+          raise Omnizip::DecompressionError,
+                "Internal error: flush lag (#{length}) exceeds dict_size (#{@dict_size})"
+        end
+
+        start_idx = dict_index(@flush_pos)
+        buf_end = @buf_end
+
+        if start_idx + length <= buf_end
+          # No wrap
+          data = @dict_buf.byteslice(start_idx, length)
+        else
+          # Wraps around the circular boundary
+          first_len = buf_end - start_idx
+          data = @dict_buf.byteslice(start_idx, first_len)
+          data << @dict_buf.byteslice(LZ_DICT_INIT_POS, length - first_len)
+        end
+
+        if output
+          output.write(data.force_encoding(Encoding::BINARY))
+        else
+          @output_accumulator ||= StringIO.new("".b)
+          @output_accumulator.write(data)
+        end
+
+        @flush_pos = @pos
+      end
+
       # Initialize the SDK-compatible decoder
       #
       # @param input [IO] Input stream of compressed data
@@ -116,11 +156,6 @@ module Omnizip
       def initialize(input, options = {})
         @input = input
         @decoder_id = object_id # Track decoder instance ID
-        puts "DEBUG LZMA::Decoder.new created[#{@decoder_id}]" if ENV["LZMA_DEBUG_DECODE_STREAM"]
-        if ENV["LZMA_DEBUG_DECODE_STREAM"]
-          warn "SDK Decoder #{@decoder_id} created"
-        end
-        @input = input
 
         # Check for preloaded data (from LZMA2 uncompressed chunks)
         @preloaded_data = options[:preloaded_data]
@@ -140,9 +175,15 @@ module Omnizip
           # Standalone LZMA file - read header from input
           read_header
         end
+
         validate_parameters
         init_models
         init_coders
+
+        # Cache computed values for hot loop
+        @pb_mask = (1 << @pb) - 1
+        @pb_shift = 1 << @pb
+        @literal_mask = (0x100 << @lp) - (0x100 >> @lc)
       end
 
       # Decode a compressed stream
@@ -167,46 +208,17 @@ module Omnizip
 check_rc_finished: true)
         @decode_stream_call_count ||= 0
         @decode_stream_call_count += 1
-        call_num = @decode_stream_call_count
-
-        puts "DEBUG decode_stream START (call ##{call_num}): @pos=#{@pos.inspect}, @dict_full=#{@dict_full.inspect}, preserve_dict=#{preserve_dict}, @uncompressed_size=#{@uncompressed_size.inspect}" if ENV.fetch(
-          "LZMA_DEBUG", nil
-        ) && @dict_full && @dict_full >= 200 && @dict_full <= 230
-        if ENV["LZMA_DEBUG_DECODE_STREAM"]
-          warn "DEBUG decode_stream[#{@decoder_id}] START: preserve_dict=#{preserve_dict}, @pos=#{@pos.inspect}, @dict_full=#{@dict_full.inspect}, @dict_buf.object_id=#{@dict_buf&.object_id || 'nil'}, @dict_buf.size=#{@dict_buf&.size || 'nil'}"
-        end
-
-        # Initialize range decoder
-        # For LZMA2, reuse persistent range decoder across chunks (like XZ Utils)
-        # The range decoder is created in set_input when the first chunk is processed
-        # See: /Users/mulgogi/src/external/xz/src/liblzma/lzma/lzma2_decoder.c:140-141
-        if ENV["LZMA_DEBUG"]
-          warn "DEBUG: decode_stream - reusing range decoder @input.pos=#{begin
-            @input.pos
-          rescue StandardError
-            'N/A'
-          end}, @range_decoder.class=#{@range_decoder.class}"
-        end
 
         # Create range decoder if it doesn't exist (first chunk)
         # This happens when the decoder is created directly for LZMA (not LZMA2)
-        unless @range_decoder
-          if ENV["LZMA_DEBUG"]
-            warn "DEBUG: decode_stream - creating NEW range decoder"
-          end
-          @range_decoder = RangeDecoder.new(@input)
-        end
+        @range_decoder ||= RangeDecoder.new(@input)
 
         # Special case: empty input (uncompressed_size == 0)
         # Return immediately without trying to decode anything
         if @uncompressed_size != 0xFFFFFFFFFFFFFFFF && @uncompressed_size.zero?
-          if ENV["LZMA_DEBUG"]
-            warn "DEBUG: decode_stream - empty input (uncompressed_size=0), returning immediately"
-          end
           return "" # Empty output
         end
 
-        # TEMP DEBUG: Trace first 10 iterations
         @debug_iter = 0
 
         # Track bytes decoded in this chunk (for multi-chunk streams)
@@ -214,13 +226,6 @@ check_rc_finished: true)
         # represents only the current chunk's size, not the total size
         @chunk_bytes_decoded = 0
 
-        # DEBUG: Show chunk_bytes_decoded initialization
-        if @dict_full && @dict_full >= 220 && @dict_full <= 240 && ENV.fetch(
-          "LZMA_DEBUG", nil
-        )
-          puts "DEBUG: chunk_bytes_decoded reset to 0 for chunk (call_num=#{call_num}, dict_full=#{@dict_full})"
-        end
-
         # Initialize state and dictionary (XZ Utils system from lz_decoder.c)
         # See: /Users/mulgogi/src/external/xz/src/liblzma/lz/lz_decoder.c:56
         # For LZMA2 multi-chunk streams, state machine persists across chunks
@@ -235,38 +240,31 @@ check_rc_finished: true)
         # when preserve_dict is true (control >= 0x80 but < 0xA0)
         # For subsequent chunks, the reset() method handles dictionary reset
         # For the first chunk (when @dict_buf is nil), we need to init it here
-        puts "DEBUG: Checking @dict_buf.nil? = #{@dict_buf.nil?}, preserve_dict=#{preserve_dict}" if ENV["LZMA_DEBUG_RESET"]
         if @dict_buf.nil?
-          buf_size = @dict_size + LZ_DICT_INIT_POS
-          @dict_buf = Array.new(buf_size, 0)
+          @buf_end = LZ_DICT_INIT_POS + @dict_size
+          buf_size = @buf_end
+          @dict_buf = ("\0" * buf_size).b
           @pos = LZ_DICT_INIT_POS
+          @dict_pos = LZ_DICT_INIT_POS # Circular buffer write position (tracks @pos)
           @dict_full = 0
           @has_wrapped = false
 
           # Add preloaded data to dictionary (from LZMA2 uncompressed chunks)
           # This must be done before decoding so matches can reference this data
           if @preloaded_data && !@preloaded_data.empty?
-            if ENV["LZMA_DEBUG_RESET"]
-              warn "DEBUG: Preloading #{@preloaded_data.bytesize} bytes into dictionary[#{@decoder_id}]"
-            end
+            idx = @dict_pos
+            buf_end = @buf_end
             @preloaded_data.each_byte do |byte|
-              @dict_buf[@pos] = byte
+              @dict_buf.setbyte(idx, byte)
               @pos += 1
+              idx += 1
+              idx = LZ_DICT_INIT_POS if idx >= buf_end
             end
+            @dict_pos = idx
             # Update dict_full to reflect preloaded data
             @dict_full = @pos - LZ_DICT_INIT_POS
-            if ENV["LZMA_DEBUG_RESET"]
-              warn "DEBUG: After preload - @pos=#{@pos}, @dict_full=#{@dict_full}"
-              warn "  Preloaded data (hex): #{@preloaded_data[0..50].unpack1('H*')}"
-            end
             @preloaded_data = nil # Clear after loading
           end
-
-          if ENV["LZMA_DEBUG_RESET"]
-            warn "DEBUG: Dictionary init in decode_stream[#{@decoder_id}] - @pos=#{@pos}, @dict_full=#{@dict_full}, @dict_buf.size=#{@dict_buf.size}, @dict_buf.object_id=#{@dict_buf.object_id}"
-            # Verify buffer initialization by checking a few positions
-            warn "  Sample values: [576]=#{@dict_buf[576]}, [577]=#{@dict_buf[577]}, [578]=#{@dict_buf[578]}, [583]=#{@dict_buf[583]}"
-          end
         end
 
         # Track starting position for multi-chunk streams
@@ -275,13 +273,6 @@ check_rc_finished: true)
         # properly reflected in start_pos, so we only return NEW bytes.
         # For LZMA2, we need to return only the NEW bytes, not all bytes from LZ_DICT_INIT_POS
         start_pos = @pos || LZ_DICT_INIT_POS
-        puts "DEBUG: start_pos=#{start_pos}, @pos=#{@pos.inspect}, @dict_full=#{@dict_full.inspect}, preserve_dict=#{preserve_dict}, @decoder_id=#{@decoder_id}" if ENV.fetch(
-          "LZMA_DEBUG", nil
-        ) && @dict_full && @dict_full >= 200 && @dict_full <= 230
-        # Also show for chunk #1 start (dict_full around 227)
-        puts "DEBUG: start_pos=#{start_pos}, @pos=#{@pos.inspect}, @dict_full=#{@dict_full.inspect}, @uncompressed_size=#{@uncompressed_size}, @decoder_id=#{@decoder_id}" if ENV.fetch(
-          "LZMA_DEBUG", nil
-        ) && @dict_full && @dict_full >= 225 && @dict_full <= 230
 
         # Initialize rep distances (XZ Utils initializes to 0)
         # See: /Users/mulgogi/src/external/xz/src/liblzma/lzma/lzma_decoder.c:1054-1055
@@ -290,15 +281,17 @@ check_rc_finished: true)
         #
         # IMPORTANT: Initialize rep distances if they're nil OR not preserving dict
         if @rep0.nil? || @rep1.nil? || @rep2.nil? || @rep3.nil? || !preserve_dict
-          puts "DEBUG: Resetting rep distances to 0 (rep0.nil?=#{@rep0.nil?}, preserve_dict=#{preserve_dict})" if ENV.fetch(
-            "LZMA_DEBUG", nil
-          ) && @dict_full && @dict_full >= 200 && @dict_full <= 230
           @rep0 = 0
           @rep1 = 0
           @rep2 = 0
           @rep3 = 0
         end
 
+        # Read range decoder init bytes (must happen after set_input sets correct stream)
+        if @range_decoder.respond_to?(:read_init_bytes) && @range_decoder.init_bytes_remaining.positive?
+          @range_decoder.read_init_bytes
+        end
+
         # Main decoding loop
         # XZ Utils pattern (lzma_decoder.c:305-306):
         # Set dict.limit = dict.pos + (size_t)(coder->uncompressed_size)
@@ -313,178 +306,42 @@ check_rc_finished: true)
                   start_pos + @uncompressed_size
                 end
 
-        # DEBUG: Show limit calculation for chunk #1
-        if ENV.fetch("LZMA_DEBUG_LIMIT",
-                     nil) && @dict_full && @dict_full >= 220 && @dict_full <= 240
-          puts "DEBUG LIMIT CALCULATION: start_pos=#{start_pos}, @uncompressed_size=#{@uncompressed_size}, limit=#{limit.inspect}"
-        end
-        # DEBUG: Also show for dict_full around 293 (where the error occurs)
-        if ENV.fetch("LZMA_DEBUG_LIMIT",
-                     nil) && @dict_full && @dict_full >= 290 && @dict_full <= 300
-          puts "DEBUG LIMIT CALCULATION at dict_full=#{@dict_full}: start_pos=#{start_pos}, @uncompressed_size=#{@uncompressed_size}, limit=#{limit.inspect}, @decoder_id=#{@decoder_id}"
-        end
+        # Circular buffer: no growth needed. Buffer is fixed at dict_size + LZ_DICT_INIT_POS.
+        # Output is flushed incrementally when the circular position nears wrap point.
+        # Matches C++ 7-Zip SDK: dic is pre-allocated to dicBufSize and never resized.
+        @flush_pos = @pos
+        @output_accumulator = output.nil? ? StringIO.new("".b) : nil
 
         iteration = 0
         loop do
           iteration += 1
-          # DEBUG: Show every iteration after position 200
-          if ENV.fetch("LZMA_DEBUG_ITER",
-                       nil) && @dict_full && @dict_full >= 200 && @dict_full <= 500
-            puts "DEBUG ITERATION ##{iteration}: pos=#{@pos}, dict_full=#{@dict_full}, limit=#{limit.inspect}"
-          end
           # Check if we've reached the expected size (if known)
           # XZ Utils: checks dict.pos < dict.limit
-          if ENV["LZMA_DEBUG_LIMIT"]
-            compare_result = begin
-              limit && @pos >= limit
-            rescue StandardError
-              "ERROR"
-            end
-            XzUtilsDecoderDebug.debug_puts "DEBUG LIMIT: iter=#{iteration}, pos=#{@pos.inspect}, dict_full=#{@dict_full}, limit=#{limit.inspect}, pos >= limit: #{compare_result}"
-          end
 
           # Handle nil @pos or limit gracefully
           if limit && (@pos.nil? || limit.nil?)
             raise "Invalid state: @pos=#{@pos.inspect}, limit=#{limit.inspect}"
           end
 
-          if ENV["LZMA_DEBUG_LIMIT"]
-            XzUtilsDecoderDebug.debug_puts "DEBUG LIMIT: iter=#{iteration}, pos=#{@pos}, dict_full=#{@dict_full}, limit=#{limit}"
+          # Circular buffer: flush output before it can be overwritten.
+          # LZMA matches are at most 273 bytes, so flush when within 273 of wrapping.
+          if @pos - @flush_pos > @dict_size - 273
+            flush_circular_output(output)
           end
 
-          # DEBUG: Track position before decoding
-          @pos if ENV["LZMA_DEBUG_POS"]
-
           # Decode is_match bit
-          pos_state = @pos & ((1 << @pb) - 1)
+          pos_state = @pos & @pb_mask
           # XZ Utils: is_match[state][pos_state] where the array is NUM_STATES * (1 << pb)
           # The array stride changes with pb value
-          model_index = (@state.value * (1 << @pb)) + pos_state
+          model_index = (@state.value * @pb_shift) + pos_state
 
-          # DEBUG: Show state before decode (for position tracking)
-          if ENV["LZMA_DEBUG_POS_227"]
-            XzUtilsDecoderDebug.debug_puts "DEBUG: Before is_match at pos=#{@pos}, dict_full=#{@dict_full}, state=#{@state.value}, pos_state=#{pos_state}"
-          end
-
-          # Debug trace (disabled - remove or enable with ENV var as needed)
           @debug_iter += 1
 
-          # DEBUG: Trace is_match decision around position 256
-          # IMPORTANT: Capture range/code BEFORE calling decode_bit
-          if @dict_full.between?(255, 257)
-            range = @range_decoder.instance_variable_get(:@range)
-            code = @range_decoder.instance_variable_get(:@code)
-            model = @is_match_models[model_index]
-            XzUtilsDecoderDebug.debug_puts "  [IS_MATCH] pos=#{@pos}, dict_full=#{@dict_full}, state=#{@state.value}, pos_state=#{pos_state}, model_index=#{model_index}"
-            XzUtilsDecoderDebug.debug_puts "    BEFORE decode: range=0x#{range.to_s(16)}, code=0x#{code.to_s(16)}, prob=#{model.probability}"
-            # Enable detailed tracing for the critical is_match[0][0] decision
-            $trace_is_match_0_0 = (@dict_full == 256)
-          end
-
-          if ENV.fetch("LZMA_DEBUG_ITER", nil)
-            range = @range_decoder.instance_variable_get(:@range)
-            code = @range_decoder.instance_variable_get(:@code)
-            model = @is_match_models[model_index]
-            bound = (range >> 11) * model.probability
-            XzUtilsDecoderDebug.debug_puts ""
-            XzUtilsDecoderDebug.debug_puts "ITER #{@debug_iter}:"
-            XzUtilsDecoderDebug.debug_puts "  pos=#{@pos}, state=#{@state.value}, pos_state=#{pos_state}, model_index=#{model_index}"
-            XzUtilsDecoderDebug.debug_puts "  dict_full=#{@dict_full}"
-            XzUtilsDecoderDebug.debug_puts "  range=0x#{range.to_s(16)}, code=0x#{code.to_s(16)}, model.prob=#{model.probability}"
-            XzUtilsDecoderDebug.debug_puts "  bound=0x#{bound.to_s(16)}, code < bound: #{code < bound}"
-          end
-
           is_match = @range_decoder.decode_bit(@is_match_models[model_index])
 
-          # DEBUG: Trace is_match and literal/match decisions around dict_full = 50-62
-          if @dict_full.between?(50, 62)
-            range_val = @range_decoder.instance_variable_get(:@range)
-            code_val = @range_decoder.instance_variable_get(:@code)
-            prob_val = @is_match_models[model_index].probability
-            XzUtilsDecoderDebug.debug_puts "\n=== dict_full=#{@dict_full}: is_match=#{is_match}, state=#{@state.value}, pos_state=#{pos_state} ==="
-            XzUtilsDecoderDebug.debug_puts "  model_index=#{model_index}, prob=#{prob_val}"
-            XzUtilsDecoderDebug.debug_puts "  range=0x#{range_val.to_s(16).upcase}, code=0x#{code_val.to_s(16).upcase}"
-          end
-
-          if ENV.fetch("LZMA_DEBUG_ITER", nil)
-            XzUtilsDecoderDebug.debug_puts "  is_match=#{is_match}"
-          end
-
-          # DEBUG: Show is_match result after decode
-          if @dict_full.between?(255, 257)
-            XzUtilsDecoderDebug.debug_puts "    AFTER decode: is_match=#{is_match}"
-            XzUtilsDecoderDebug.debug_puts "    (is_match=0 means literal, is_match=1 means match)"
-          end
-
-          # DEBUG: Track what's happening around dict_full=227 (corruption point)
-          if ENV["LZMA_DEBUG"] && @dict_full == 227
-            puts "DEBUG CORRUPTION POINT: dict_full=#{@dict_full}, pos=#{@pos}"
-            puts "  is_match=#{is_match}, state=#{@state.value}"
-            range_val = @range_decoder.instance_variable_get(:@range)
-            code_val = @range_decoder.instance_variable_get(:@code)
-            puts "  range=0x#{range_val.to_s(16)}, code=0x#{code_val.to_s(16)}"
-            puts "  dict_buf[#{@pos - 5}...#{@pos + 5}] = #{@dict_buf[[
-              @pos - 5, LZ_DICT_INIT_POS
-            ].max...[@pos + 5, @dict_buf.size - 1].min].inspect}"
-          end
-
-          if ENV["LZMA_DEBUG"] && @dict_full.between?(224, 235)
-            puts "DEBUG pos #{@dict_full}: is_match=#{is_match}, state=#{@state.value}"
-            if is_match.zero?
-              puts "  Next byte should be literal"
-            else
-              puts "  Next byte should be match"
-            end
-          end
-
-          # DEBUG: Verify first 256 bytes are correct
-          if @dict_full == 256
-            XzUtilsDecoderDebug.debug_puts ""
-            XzUtilsDecoderDebug.debug_puts "  Verifying first 256 bytes:"
-            # Check specific bytes around position 253
-            XzUtilsDecoderDebug.debug_puts "  Byte 253: @dict_buf[#{LZ_DICT_INIT_POS + 253}]=#{@dict_buf[LZ_DICT_INIT_POS + 253].inspect} (expected 'i'=0x69)"
-            XzUtilsDecoderDebug.debug_puts "  Byte 254: @dict_buf[#{LZ_DICT_INIT_POS + 254}]=#{@dict_buf[LZ_DICT_INIT_POS + 254].inspect} (expected 'n'=0x6E)"
-            XzUtilsDecoderDebug.debug_puts "  Byte 255: @dict_buf[#{LZ_DICT_INIT_POS + 255}]=#{@dict_buf[LZ_DICT_INIT_POS + 255].inspect} (expected ' '=0x20)"
-            all_correct = true
-            256.times do |i|
-              expected = i
-              actual = @dict_buf[LZ_DICT_INIT_POS + i]
-              if actual != expected
-                all_correct = false
-                if (i >= 253) && ENV.fetch("LZMA_DEBUG", nil)
-                  puts "    Byte #{i}: expected 0x#{expected.to_s(16)}, got 0x#{actual.to_s(16)} MISMATCH!"
-                end
-              end
-            end
-            XzUtilsDecoderDebug.debug_puts "    First 256 bytes: #{all_correct ? 'ALL CORRECT ✓' : 'HAS MISMATCH'}"
-            XzUtilsDecoderDebug.debug_puts ""
-          end
-
-          if ENV.fetch("LZMA_DEBUG", nil) && @pos >= 605 && @pos <= 615
-            warn "DEBUG: is_match at pos=#{@pos}, state=#{@state.value}, pos_state=#{pos_state}, model_index=#{model_index}, is_match=#{is_match}"
-          end
-
           if is_match.zero?
             # Decode literal
             decode_literal
-
-            # Trace positions 45-65 for debugging good-1-lzma2-3.xz divergence
-            if ENV.fetch("LZMA_DEBUG",
-                         nil) && @dict_full >= 45 && @dict_full <= 65
-              last_byte = @dict_buf[@pos - 1]
-              range_after = @range_decoder.instance_variable_get(:@range)
-              code_after = @range_decoder.instance_variable_get(:@code)
-              puts "  literal decoded: 0x#{last_byte.to_s(16).upcase} ('#{last_byte.chr}') at pos=#{@pos - 1}, dict_full=#{@dict_full}"
-              puts "    AFTER: range=0x#{range_after.to_s(16).upcase}, code=0x#{code_after.to_s(16).upcase}"
-            end
-
-            if ENV.fetch("LZMA_DEBUG_ITER", nil)
-              last_byte = @dict_buf[@pos - 1]
-              puts "  literal byte=0x#{last_byte.to_s(16)} ('#{last_byte.chr}')"
-            end
-            if ENV["LZMA_DEBUG_POS"] && @pos >= limit
-              puts "DEBUG: Literal overshoot: pos=#{@pos}, limit=#{limit}, delta=#{@pos - limit}"
-            end
           elsif decode_match
             # Decode match - returns true if EOS detected
             break
@@ -496,7 +353,6 @@ check_rc_finished: true)
           # IMPORTANT: Must verify range decoder is finished (code == 0)
           # If code != 0, there's leftover data in the compressed stream (corruption)
           if limit && @pos >= limit
-            puts "DEBUG LIMIT TRIGGERED (call #{call_num}): pos=#{@pos}, limit=#{limit}, dict_full=#{@dict_full}, chunk_bytes_decoded=#{@chunk_bytes_decoded}" if ENV["LZMA_DEBUG_LIMIT"]
 
             # XZ Utils pattern (lzma_decoder.c:689-700):
             # Check if range decoder is finished (code == 0)
@@ -531,32 +387,23 @@ check_rc_finished: true)
                 raise Omnizip::DecompressionError,
                       "LZMA stream finished with leftover compressed data (range_decoder.code=#{@range_decoder.code}, expected 0). This indicates corruption in the compressed stream or an invalid EOPM for LZMA2."
               end
+              # XZ Utils pattern (lzma_decoder.c): when STREAM_END is reached,
+              # reset the range coder for the next chunk. This happens even for
+              # no-reset chunks (control 0x80-0x9F) - the range coder is ALWAYS
+              # re-initialized between chunks, only state/dict/models are preserved.
+              @range_decoder.reset
               break
             elsif @range_decoder.code.zero?
               # EOPM is allowed (e.g., LZMA_Alone format)
               # If range decoder is finished, we're done
+              # XZ Utils: rc_reset at STREAM_END
+              @range_decoder.reset
               break
               # Otherwise, continue decoding to find EOPM marker
               # XZ Utils sets eopm_is_valid = true and continues
               # Reference: lzma_decoder.c:704
             end
           end
-
-          # DEBUG: Show when approaching limit for chunk #1
-          if ENV.fetch("LZMA_DEBUG_LIMIT",
-                       nil) && limit && @pos >= limit - 10 && @pos < limit + 10
-            puts "DEBUG NEAR LIMIT (call #{call_num}): pos=#{@pos}, limit=#{limit}, dict_full=#{@dict_full}, chunk_bytes_decoded=#{@chunk_bytes_decoded}, remaining=#{@uncompressed_size ? @uncompressed_size - @chunk_bytes_decoded : 'N/A'}"
-          end
-
-          # DEBUG: Show when we've passed the expected limit
-          if ENV.fetch("LZMA_DEBUG_LIMIT",
-                       nil) && limit && @pos >= limit && @pos < limit + 10
-            puts "DEBUG PASSED LIMIT: pos=#{@pos}, limit=#{limit}, dict_full=#{@dict_full}, delta=#{@pos - limit}"
-          end
-
-          if ENV["LZMA_DEBUG_POS"] && @pos >= limit
-            XzUtilsDecoderDebug.debug_puts "DEBUG: Overshoot detected: pos=#{@pos}, limit=#{limit}, delta=#{@pos - limit}"
-          end
         end
 
         # Validate decoded size against expected uncompressed_size
@@ -585,8 +432,8 @@ check_rc_finished: true)
           #
           # If EOPM was NOT encountered (code != 0), leftover data is expected
           # (it's part of the compressed stream that we haven't read yet).
-          if @allow_eopm && @range_decoder&.code&.zero? && @range_decoder.instance_variable_get(:@stream)
-            stream = @range_decoder.instance_variable_get(:@stream)
+          if @allow_eopm && @range_decoder&.code&.zero? && @range_decoder&.stream
+            stream = @range_decoder.stream
             # Try to peek at the next byte - if available, there's data AFTER EOPM
             begin
               next_byte = stream.getbyte
@@ -599,9 +446,9 @@ check_rc_finished: true)
             rescue IOError, EOFError
               # Stream doesn't support peeking or is exhausted, that's fine
             end
-          elsif !@allow_eopm && @range_decoder&.instance_variable_get(:@stream)
+          elsif !@allow_eopm && @range_decoder&.stream
             # For LZMA2 mode (EOPM not allowed): check for leftover data
-            stream = @range_decoder.instance_variable_get(:@stream)
+            stream = @range_decoder.stream
             begin
               next_byte = stream.getbyte
               if next_byte
@@ -615,34 +462,14 @@ check_rc_finished: true)
           end
         end
 
-        # Return output - only the valid portion of dictionary
-        # XZ Utils: valid data starts from LZ_DICT_INIT_POS onwards
-        # IMPORTANT: For LZMA2 multi-chunk streams, only return NEW bytes since start_pos!
-        # This ensures each chunk returns only its own output, not previous chunks' output.
-        if ENV["DEBUG_DICT_BUF"]
-          XzUtilsDecoderDebug.debug_puts "DEBUG: start_pos=#{start_pos}, @pos=#{@pos.inspect}, @dict_buf.size=#{@dict_buf.size}, LZ_DICT_INIT_POS=#{LZ_DICT_INIT_POS}"
-        end
-        valid_bytes = @dict_buf[start_pos...@pos]
-        # DEBUG: Show return value calculation
-        puts "DEBUG RETURN CALCULATION: call_num=#{call_num}, start_pos=#{start_pos}, @pos=#{@pos}, valid_bytes.size=#{@dict_buf[start_pos...@pos].size}, dict_full=#{@dict_full}, chunk_bytes_decoded=#{@chunk_bytes_decoded}" if ENV.fetch(
-          "LZMA_DEBUG", nil
-        ) && @dict_full && @dict_full >= 220 && @dict_full <= 240 && call_num == 2
-        puts "DEBUG RETURN CALCULATION: call_num=#{call_num}, start_pos=#{start_pos}, @pos=#{@pos}, valid_bytes.size=#{@dict_buf[start_pos...@pos].size}, dict_full=#{@dict_full}, chunk_bytes_decoded=#{@chunk_bytes_decoded}" if ENV["LZMA_DEBUG"] && call_num == 2
-        # Filter out nil values (can happen during dictionary reset transitions)
-        valid_bytes = valid_bytes.map { |b| b.nil? ? 0 : b }
-        if ENV["DEBUG_DICT_BUF"]
-          XzUtilsDecoderDebug.debug_puts "DEBUG: valid_bytes=#{begin
-            valid_bytes.size
-          rescue StandardError
-            valid_bytes.inspect
-          end}"
-        end
-        valid_data = valid_bytes.pack("C*")
+        # Flush remaining output from the circular buffer
+        flush_circular_output(output)
+
+        # Return output
         if output
-          output.write(valid_data.force_encoding(Encoding::BINARY))
-          valid_data.bytesize
+          @pos - start_pos
         else
-          valid_data.force_encoding(Encoding::BINARY)
+          @output_accumulator.string.force_encoding(Encoding::BINARY)
         end
       end
 
@@ -660,23 +487,19 @@ check_rc_finished: true)
       # @param preserve_dict [Boolean] If true, preserve dictionary state (pos, dict_full)
       # @return [void]
       def reset(new_lc: nil, new_lp: nil, new_pb: nil, preserve_dict: false)
-        if ENV["LZMA_DEBUG_RESET"]
-          warn "DEBUG reset[#{@decoder_id}] called: preserve_dict=#{preserve_dict}, @pos=#{@pos.inspect}, @dict_full=#{@dict_full.inspect}, @dict_buf.size=#{@dict_buf&.size || 'nil'}, nil_count=#{@dict_buf&.count(nil) || 'N/A'}"
-        end
-
-        # DEBUG: Trace reset calls around position 224-227
-        if @dict_full && @dict_full >= 220 && @dict_full <= 230
-          XzUtilsDecoderDebug.debug_puts "\n=== reset called at dict_full=#{@dict_full} ==="
-          XzUtilsDecoderDebug.debug_puts "  preserve_dict=#{preserve_dict}"
-          XzUtilsDecoderDebug.debug_puts "  Before reset: rep0/1/2/3=(#{@rep0},#{@rep1},#{@rep2},#{@rep3})"
-        end
-
         # Update properties if provided
         properties_changed = !!(new_lc || new_lp || new_pb)
         @lc = new_lc if new_lc
         @lp = new_lp if new_lp
         @pb = new_pb if new_pb
 
+        # Recompute cached values when properties change
+        if properties_changed
+          @pb_mask = (1 << @pb) - 1
+          @pb_shift = 1 << @pb
+          @literal_mask = (0x100 << @lp) - (0x100 >> @lc)
+        end
+
         # Reset state machine (XZ Utils line 1053)
         # Always create a new state machine when resetting
         @state = SdkStateMachine.new
@@ -695,53 +518,31 @@ check_rc_finished: true)
         # - rc_reset sets range=UINT32_MAX, code=0, init_bytes_left=5
         # - This MUST happen during reset, not deferred to decode_stream
         # Reference: /Users/mulgogi/src/external/xz/src/liblzma/lzma/lzma_decoder.c:1061
-        if @range_decoder
-          @range_decoder.reset
-          if ENV["LZMA_DEBUG_RESET"]
-            warn "DEBUG reset[#{@decoder_id}]: Reset range_decoder, code=0x#{@range_decoder.code.to_s(16)}, init_bytes_remaining=#{@range_decoder.instance_variable_get(:@init_bytes_remaining)}"
-          end
-        end
+        @range_decoder&.reset
 
         # Reinitialize probability models (XZ Utils lines 1064-1082)
         # IMPORTANT: Use reset_models (reset in place) instead of init_models (create new)
         # for state reset only. Only create new models when properties change.
         if properties_changed
-          if ENV["LZMA_DEBUG_RESET"]
-            warn "DEBUG reset[#{@decoder_id}]: Properties changed, calling init_models (create new arrays)"
-          end
           init_models
         else
-          if ENV["LZMA_DEBUG_RESET"]
-            warn "DEBUG reset[#{@decoder_id}]: No properties changed, calling reset_models (reset in place)"
-          end
           reset_models
         end
 
         # Reinitialize coders (needed for pb changes)
         # Only recreate coders when properties have changed
-        if properties_changed
-          if ENV["LZMA_DEBUG_RESET"]
-            warn "DEBUG reset[#{@decoder_id}]: Properties changed, calling init_coders (create new coders)"
-          end
-          init_coders
-        elsif ENV["LZMA_DEBUG_RESET"]
-          warn "DEBUG reset[#{@decoder_id}]: No properties changed, skipping init_coders (preserve existing coders)"
-        end
+        init_coders if properties_changed
 
         # Reset dictionary position and full count (XZ Utils pattern)
         # Only reset if preserve_dict is false
         unless preserve_dict
           # Reinitialize dictionary buffer
           # XZ Utils allocates a new buffer for each dictionary reset
-          @dict_buf = Array.new(@dict_size + LZ_DICT_INIT_POS, 0)
+          @dict_buf = ("\0" * (@dict_size + LZ_DICT_INIT_POS)).b
           @pos = LZ_DICT_INIT_POS
+          @dict_pos = LZ_DICT_INIT_POS
           @dict_full = 0
           @has_wrapped = false
-          if ENV["LZMA_DEBUG_RESET"]
-            warn "DEBUG reset after dict reset[#{@decoder_id}]: @pos=#{@pos}, @dict_full=#{@dict_full}, @dict_buf.size=#{@dict_buf.size}, @dict_buf.object_id=#{@dict_buf.object_id}, nil_count=#{@dict_buf.count(nil)}"
-            # Verify buffer initialization by checking a few positions
-            warn "  Sample values: [576]=#{@dict_buf[576]}, [577]=#{@dict_buf[577]}, [578]=#{@dict_buf[578]}, [583]=#{@dict_buf[583]}"
-          end
         end
 
         nil
@@ -799,12 +600,6 @@ check_rc_finished: true)
       #
       # @return [void]
       def prepare_state_reset
-        # DEBUG: Trace when prepare_state_reset is called
-        if ENV["LZMA_DEBUG"]
-          XzUtilsDecoderDebug.debug_puts "\n=== prepare_state_reset called (decoder_id=#{@decoder_id}) ==="
-          XzUtilsDecoderDebug.debug_puts "  Before reset: rep0/1/2/3=(#{@rep0},#{@rep1},#{@rep2},#{@rep3})"
-        end
-
         # Reset state machine (XZ Utils line 1053)
         @state = SdkStateMachine.new
 
@@ -814,18 +609,9 @@ check_rc_finished: true)
         @rep2 = 0
         @rep3 = 0
 
-        # DEBUG: Show after reset
-        if ENV["LZMA_DEBUG"]
-          XzUtilsDecoderDebug.debug_puts "  After reset: rep0/1/2/3=(#{@rep0},#{@rep1},#{@rep2},#{@rep3})"
-        end
-
         # Reset probability models (XZ Utils init_temporals for control >= 0xA0)
         reset_models
 
-        if ENV["LZMA_DEBUG"]
-          XzUtilsDecoderDebug.debug_puts "=== end prepare_state_reset (range decoder will be reset in finish_state_reset) ==="
-        end
-
         nil
       end
 
@@ -837,23 +623,12 @@ check_rc_finished: true)
       #
       # @return [void]
       def reset_state_machine_only
-        # DEBUG: Trace when reset_state_machine_only is called
-        if @dict_full && @dict_full >= 220 && @dict_full <= 230
-          XzUtilsDecoderDebug.debug_puts "\n=== reset_state_machine_only called at dict_full=#{@dict_full} (decoder_id=#{@decoder_id}) ==="
-          XzUtilsDecoderDebug.debug_puts "  Before reset: rep0/1/2/3=(#{@rep0},#{@rep1},#{@rep2},#{@rep3})"
-        end
-
         # Reset state machine only (XZ Utils line 1053)
         @state = SdkStateMachine.new
 
         # Reset probability models (XZ Utils init_temporals for control >= 0xA0)
         reset_models
 
-        # DEBUG: Show after reset (note: rep distances are preserved)
-        if @dict_full && @dict_full >= 220 && @dict_full <= 230
-          XzUtilsDecoderDebug.debug_puts "  After reset: rep0/1/2/3=(#{@rep0},#{@rep1},#{@rep2},#{@rep3}) (preserved)"
-        end
-
         nil
       end
 
@@ -872,30 +647,7 @@ check_rc_finished: true)
         # Reset range decoder (XZ Utils rc_reset)
         # This reinitializes the range decoder for the new chunk
         # The reset will read 5 bytes from the input when decode_stream starts
-        if @range_decoder
-          if ENV["LZMA_DEBUG"]
-            input_pos = begin
-              @input.pos
-            rescue StandardError
-              "N/A"
-            end
-            input_size = begin
-              @input.size
-            rescue StandardError
-              "N/A"
-            end
-            XzUtilsDecoderDebug.debug_puts "=== finish_state_reset: resetting range_decoder, input pos=#{input_pos}, size=#{input_size}"
-          end
-          @range_decoder.reset
-          if ENV["LZMA_DEBUG"]
-            input_pos_after = begin
-              @input.pos
-            rescue StandardError
-              "N/A"
-            end
-            XzUtilsDecoderDebug.debug_puts "=== finish_state_reset: after reset, input pos=#{input_pos_after}, range_decoder.code=0x#{@range_decoder.code.to_s(16)}"
-          end
-        end
+        @range_decoder&.reset
       end
 
       def reset_state_only
@@ -931,45 +683,13 @@ check_rc_finished: true)
       def set_input(new_input)
         @input = new_input
 
-        # DEBUG: Trace input stream contents
-        if ENV.fetch("LZMA_DEBUG",
-                     nil) && @dict_full && @dict_full >= 220 && @dict_full <= 230
-          puts "\n=== set_input at dict_full=#{@dict_full} ==="
-          puts "  new_input.size=#{new_input.size}"
-          puts "  new_input.pos=#{new_input.pos}"
-          puts "  new_input.class=#{new_input.class}"
-
-          # Read first 10 bytes manually
-          first_bytes = []
-          10.times do |_i|
-            byte = new_input.getbyte
-            break if byte.nil?
-
-            first_bytes << byte
-          end
-          puts "  First 10 bytes: #{first_bytes.map do |b|
-            "0x#{b.to_s(16).upcase}"
-          end.join(' ')}"
-
-          new_input.rewind
-          test_byte = new_input.getbyte
-          puts "  Test getbyte: 0x#{test_byte.to_s(16).upcase}" if test_byte
-          new_input.rewind
-        end
-
         # Create range decoder if it doesn't exist (first chunk)
         if @range_decoder.nil?
           @range_decoder = RangeDecoder.new(@input)
-          if ENV["LZMA_DEBUG"]
-            XzUtilsDecoderDebug.debug_puts "=== set_input: created NEW range_decoder, input has #{@input.size} bytes"
-          end
         else
           # Update the range decoder's input stream to the new input
           # This is needed because RangeDecoder holds a reference to the stream
           @range_decoder.update_stream(@input)
-          if ENV["LZMA_DEBUG"]
-            XzUtilsDecoderDebug.debug_puts "=== set_input: reusing range_decoder, new input has #{@input.size} bytes, pos=#{@input.pos}"
-          end
         end
       end
 
@@ -985,29 +705,30 @@ check_rc_finished: true)
       # @param data [String] Uncompressed data to add to dictionary
       # @return [void]
       def add_to_dictionary(data)
-        if ENV["LZMA_DEBUG"]
-          old_dict_full = @dict_full
-          XzUtilsDecoderDebug.debug_puts "=== add_to_dictionary: adding #{data.bytesize} bytes to dictionary[#{@decoder_id}], current dict_full=#{@dict_full}, pos=#{@pos}"
-        end
-
+        idx = @dict_pos
+        buf_end = @buf_end
         data.each_byte do |byte|
-          @dict_buf[@pos] = byte
+          @dict_buf.setbyte(idx, byte)
           @pos += 1
+          idx += 1
+          idx = LZ_DICT_INIT_POS if idx >= buf_end
         end
+        @dict_pos = idx
 
         # Update dict_full to reflect new data
-        @dict_full = @pos - LZ_DICT_INIT_POS
-
-        # Check if we've reached the maximum dictionary size
-        if @dict_full >= @dict_size
-          @dict_full = @dict_size
-        end
-
-        if ENV["LZMA_DEBUG"]
-          XzUtilsDecoderDebug.debug_puts "=== add_to_dictionary: after adding, dict_full=#{@dict_full} (was #{old_dict_full}), pos=#{@pos}"
+        unless @has_wrapped
+          @dict_full = @pos - LZ_DICT_INIT_POS
+          if @dict_full >= @dict_size
+            @has_wrapped = true
+            @dict_full = @dict_size
+          end
         end
       end
 
+      # No-op: circular buffer has fixed size, no compaction needed.
+      # Kept for API compatibility — LZMA2 decoder calls this between chunks.
+      def compact_buffer; end
+
       # Set uncompressed size for chunked decoding
       #
       # XZ Utils pattern (lzma2_decoder.c:140-141):
@@ -1020,10 +741,6 @@ check_rc_finished: true)
       def set_uncompressed_size(size, allow_eopm: true)
         @uncompressed_size = size
         @allow_eopm = allow_eopm
-        # DEBUG: Track when uncompressed size is set
-        if ENV["LZMA_DEBUG"]
-          puts "DEBUG set_uncompressed_size: size=#{size}, @decoder_id=#{@decoder_id}, @dict_full=#{@dict_full}"
-        end
       end
 
       private
@@ -1136,13 +853,6 @@ check_rc_finished: true)
         @rep_length_coder = LengthCoder.new(pos_states)
         @distance_coder = DistanceCoder.new(NUM_LEN_TO_POS_STATES)
 
-        if ENV["TRACE_MODEL_INIT"]
-          puts "[XzUtilsDecoder.init] slot_encoders len_state=0 object_id=#{@distance_coder.instance_variable_get(:@slot_encoders)[0].object_id}"
-          puts "[XzUtilsDecoder.init] slot_encoders[0][1] object_id=#{@distance_coder.instance_variable_get(:@slot_encoders)[0][1].object_id}"
-          puts "[XzUtilsDecoder.init] is_match_models object_id=#{@is_match_models.object_id}"
-          puts "[XzUtilsDecoder.init] is_match_models[0] object_id=#{@is_match_models[0].object_id}"
-        end
-
         # Update probability model indices to match new pos_states
         # This is critical when pb changes between chunks
         @pos_states = pos_states
@@ -1174,202 +884,36 @@ check_rc_finished: true)
       #
       # @return [void]
       def decode_literal
-        # DEBUG: Trace literals around position 224-227
-        old_dict_full = @dict_full
-
-        # DEBUG: Track how many times we're called for each position
-        if ENV["LZMA_DEBUG_DECODE_LITERAL"]
-          caller_info = caller(1..1).first
-          XzUtilsDecoderDebug.debug_puts "DEBUG decode_literal[#{@decoder_id}]: pos=#{@pos}, dict_full=#{@dict_full}, from=#{caller_info.label}"
-        end
-
-        # DEBUG: Check array integrity before decode
-        if ENV.fetch("LZMA_DEBUG_ARRAY",
-                     nil) && @dict_full.positive? && @pos > 1
-          idx = @pos - 1
-          if @dict_buf[idx].nil?
-            raise "DEBUG before decode: @dict_buf[#{idx}] is nil! @pos=#{@pos}, @dict_full=#{@dict_full}, @dict_buf.size=#{@dict_buf.size}, nil_count=#{@dict_buf.count(nil)}"
-          end
-        end
-
         # Calculate literal state using SDK formula
         lit_state = calculate_literal_state
 
-        # DEBUG: Trace lit_state at position 61
-        if @dict_full == 61 && ENV["TRACE_LITERAL_61"]
-          XzUtilsDecoderDebug.debug_puts "=== CALC_LITERAL_STATE at dict_full=61 ==="
-          XzUtilsDecoderDebug.debug_puts "  prev_byte=#{@dict_full.positive? ? @dict_buf[@pos - 1] : 0}"
-          XzUtilsDecoderDebug.debug_puts "  lit_state=#{lit_state}"
-          XzUtilsDecoderDebug.debug_puts "  lc=#{@lc}, lp=#{@lp}"
-          XzUtilsDecoderDebug.debug_puts "  state.value=#{@state.value}"
-          XzUtilsDecoderDebug.debug_puts "  use_matched_literal?=#{@state.use_matched_literal?}"
-          XzUtilsDecoderDebug.debug_puts "  dict_full.positive?=#{@dict_full.positive?}"
-          puts
-        end
-
         # Decode literal (matched or unmatched)
         # Check if dictionary has any valid bytes (XZ Utils: dict->full > 0)
         if @state.use_matched_literal? && @dict_full.positive?
-          # DEBUG: Track which branch is taken
-          if @dict_full == 61 && ENV["TRACE_LITERAL_61"]
-            XzUtilsDecoderDebug.debug_puts "  TAKING MATCHED LITERAL PATH"
-            XzUtilsDecoderDebug.debug_puts "  rep0=#{@rep0}"
-            match_byte_pos_calc = LZ_DICT_INIT_POS + @dict_full - @rep0 - 1
-            XzUtilsDecoderDebug.debug_puts "  match_byte_pos (calc)=#{match_byte_pos_calc}"
-            puts
-          end
-
           # Matched literal: use match byte from dictionary at distance rep0
           # XZ Utils dict_get pattern: dict->buf[dict->pos - distance - 1]
-          # IMPORTANT: dict->pos in XZ Utils is the actual output position (dict->full),
-          # not the buffer position with offset!
-          # omnizip uses @pos for buffer position (includes LZ_DICT_INIT_POS offset)
-          # and @dict_full for actual output position (starts at 0)
-          # So we must convert: buffer_pos = LZ_DICT_INIT_POS + (output_pos - rep0 - 1)
-          match_byte_pos = LZ_DICT_INIT_POS + @dict_full - @rep0 - 1
-          match_byte = @dict_buf[match_byte_pos]
-          if ENV["LZMA_DEBUG"]
-            warn "DEBUG: matched literal - dict_full=#{@dict_full}, rep0=#{@rep0}, reading dict_buf[#{match_byte_pos}]=0x#{match_byte.to_s(16).upcase} ('#{match_byte.chr}'), lit_state=#{lit_state}, state=#{@state.value}"
-          end
+          match_byte = @dict_buf.getbyte(dict_index(@pos - @rep0 - 1))
           byte = @literal_decoder.decode_matched(match_byte, lit_state, @lc,
                                                  @range_decoder, @literal_models)
-
-          # DEBUG: Trace decoded byte at position 61
-          if @dict_full == 61 && ENV["TRACE_LITERAL_61"]
-            XzUtilsDecoderDebug.debug_puts "  DECODED MATCHED LITERAL: 0x#{byte.to_s(16).upcase} ('#{byte.chr}')"
-            XzUtilsDecoderDebug.debug_puts "  match_byte=0x#{match_byte.to_s(16).upcase} ('#{match_byte.chr}')"
-            puts
-          end
         else
           # Unmatched literal: simple 8-bit decoding
-          if @dict_full == 61 && ENV["TRACE_LITERAL_61"]
-            XzUtilsDecoderDebug.debug_puts "  TAKING UNMATCHED LITERAL PATH"
-            puts
-          end
-
-          if ENV["LZMA_DEBUG"]
-            warn "DEBUG: calling decode_unmatched - pos=#{@pos}, lit_state=#{lit_state}"
-          end
           byte = @literal_decoder.decode_unmatched(lit_state, @lc,
                                                    @range_decoder, @literal_models)
         end
 
-        if ENV["LZMA_DEBUG"]
-          warn "DEBUG: decode_literal RETURNED - pos=#{@pos}, byte=#{'0x%02X' % byte} ('#{byte.chr}'), lit_state=#{lit_state}"
-        end
-
-        # DEBUG: Check byte value at critical positions
-        if @dict_full == 256
-          XzUtilsDecoderDebug.debug_puts "DEBUG: About to store 257th byte (pos=#{@pos}, dict_full=#{@dict_full})"
-          XzUtilsDecoderDebug.debug_puts "  byte.class=#{byte.class}"
-          XzUtilsDecoderDebug.debug_puts "  byte=#{byte.inspect}"
-          XzUtilsDecoderDebug.debug_puts "  byte.is_a?(Integer)=#{byte.is_a?(Integer)}"
-          if byte.is_a?(Integer)
-            XzUtilsDecoderDebug.debug_puts "  byte value=#{byte}"
-            XzUtilsDecoderDebug.debug_puts "  Expected byte value=0"
-          else
-            XzUtilsDecoderDebug.debug_puts "  byte is not an Integer!"
-            XzUtilsDecoderDebug.debug_puts "  byte.ord=#{byte.ord}"
-          end
-        end
-
-        if ENV["LZMA_DEBUG"]
-          decoded_bytes = @dict_full.positive? ? @dict_buf[LZ_DICT_INIT_POS..].map(&:chr).join : ""
-          warn "DEBUG: decode_literal - pos=#{@pos}, byte=#{'0x%02X' % byte} ('#{byte.chr}'), state=#{@state.value}, dict_full=#{@dict_full}, decoded_so_far='#{decoded_bytes[-10..]}'"
-        end
-
-        # DEBUG: Detailed trace around position 256
-        if ENV["LZMA_DEBUG"] && @dict_full.between?(230, 265)
-          expected = @dict_full % 256
-          match = byte == expected ? "✓" : "✗ MISMATCH!"
-          XzUtilsDecoderDebug.debug_puts "  [LITERAL] dict_full=#{@dict_full}: 0x#{byte.to_s(16).upcase} (expected 0x#{expected.to_s(16).upcase}) #{match}"
-          if @dict_full == 233
-            XzUtilsDecoderDebug.debug_puts "  DETAILED TRACE at dict_full=233 (pos=#{@pos}):"
-            XzUtilsDecoderDebug.debug_puts "    byte=0x#{byte.to_s(16)} ('#{begin
-              byte.chr
-            rescue StandardError
-              '?'
-            end}')"
-            XzUtilsDecoderDebug.debug_puts "    state.value=#{@state.value}, lit_state=#{lit_state}"
-            XzUtilsDecoderDebug.debug_puts "    use_matched_literal?=#{@state.use_matched_literal?}"
-            prev_byte_val = @dict_full.positive? ? @dict_buf[@pos - 1] : "N/A"
-            XzUtilsDecoderDebug.debug_puts "    prev_byte=#{prev_byte_val.inspect} (#{if prev_byte_val.is_a?(Integer)
-                                                                                        "0x#{prev_byte_val.to_s(16)} ('#{begin
-                                                                                          prev_byte_val.chr
-                                                                                        rescue StandardError
-                                                                                          '?'
-                                                                                        end}')"
-                                                                                      else
-                                                                                        'N/A'
-                                                                                      end})"
-            XzUtilsDecoderDebug.debug_puts "    range_decoder.range=0x#{@range_decoder.range.to_s(16)}, range_decoder.code=0x#{@range_decoder.code.to_s(16)}"
-            XzUtilsDecoderDebug.debug_puts "    input.pos=#{@input.pos}, input.size=#{@input.size}"
-          end
-          if @dict_full == 256
-            XzUtilsDecoderDebug.debug_puts "    pos=#{@pos}, lit_state=#{lit_state}, state.value=#{@state.value}"
-            XzUtilsDecoderDebug.debug_puts "    use_matched_literal?=#{@state.use_matched_literal?}"
-          end
-        end
-
         # Update state and dictionary
         # XZ Utils dict_put pattern:
         # dict->buf[dict->pos++] = byte;
         # if (!dict->has_wrapped)
         #     dict->full = dict->pos - LZ_DICT_INIT_POS;
         @state.update_literal
-        warn "DEBUG: After update_literal - state=#{@state.value}" if ENV["LZMA_DEBUG"]
 
         # Write to dictionary buffer at current position
         # XZ Utils dict_put pattern: dict->buf[dict->pos++] = byte;
-        # DEBUG: Check byte value at critical position
-        if @pos == 576 + 256
-          XzUtilsDecoderDebug.debug_puts "DEBUG: Storing byte at pos 832 (256th decoded byte)"
-          XzUtilsDecoderDebug.debug_puts "  byte.class=#{byte.class}"
-          XzUtilsDecoderDebug.debug_puts "  byte=#{byte}"
-          XzUtilsDecoderDebug.debug_puts "  byte.ord=#{byte.is_a?(String) ? byte.ord : 'N/A (not a string)'}"
-          XzUtilsDecoderDebug.debug_puts "  Integer value=#{byte.is_a?(Integer) ? byte : byte.ord}"
-        end
-        @dict_buf[@pos] = byte
-        # DEBUG: Track array size changes
-        if ENV["LZMA_DEBUG_ARRAY_WRITE"] && @dict_buf.size != (@dict_size + LZ_DICT_INIT_POS)
-          XzUtilsDecoderDebug.debug_puts "DEBUG: Array expanded! pos=#{@pos}, byte=#{byte}, old_size=#{@dict_buf.size - 1}, new_size=#{@dict_buf.size}, decoder_id=#{@decoder_id}"
-          XzUtilsDecoderDebug.debug_puts "  Writing beyond original size caused expansion!"
-        end
-        if ENV["LZMA_DEBUG_ARRAY_WRITE"]
-          XzUtilsDecoderDebug.debug_puts "DEBUG write[#{@decoder_id}]: pos=#{@pos}, byte=#{byte}, dict_buf.size=#{@dict_buf.size}, dict_buf.object_id=#{@dict_buf.object_id}, nil_count=#{@dict_buf.count(nil)}"
-        end
-        if ENV["LZMA_DEBUG_ARRAY"]
-          # Verify the write succeeded
-          if @dict_buf[@pos] != byte
-            raise "DEBUG after write: @dict_buf[#{@pos}] = #{@dict_buf[@pos].inspect}, expected #{byte}! nil_count=#{@dict_buf.count(nil)}"
-          end
-          if @dict_full.positive? && @pos > LZ_DICT_INIT_POS && @dict_buf[@pos - 1].nil?
-            raise "DEBUG after write: @dict_buf[#{@pos - 1}] is nil! @pos=#{@pos}, @dict_full=#{@dict_full}"
-          end
-        end
+        @dict_buf.setbyte(@dict_pos, byte)
         @pos += 1
-
-        # ARM64 DEBUG: Trace first 20 bytes being written to dictionary
-        if ENV["TRACE_ARM64_BYTES"]
-          @arm64_trace ||= []
-          if @arm64_trace.size < 20
-            @arm64_trace << [@dict_full, @pos, byte.class,
-                             byte.is_a?(Integer) ? byte : byte.ord, @dict_buf[@pos]]
-            if @arm64_trace.size == 20
-              # Dump the trace
-              puts "\n=== ARM64 BYTE TRACE (first 20 bytes) ==="
-              puts "Decoder ID: #{@decoder_id}"
-              @arm64_trace.each_with_index do |entry, i|
-                df, p, _, val, stored = entry
-                puts "  [#{i + 1}] dict_full=#{df.to_s.rjust(6)}, pos=#{p.to_s.rjust(6)}, byte=#{val.to_s.rjust(3)} (0x#{val.to_s(16).upcase.rjust(
-                  2, '0'
-                )}) stored=#{stored.inspect}"
-              end
-              puts "=========================================\n"
-              $stderr.flush
-            end
-          end
-        end
+        @dict_pos += 1
+        @dict_pos = LZ_DICT_INIT_POS if @dict_pos >= @buf_end
 
         # Update dict_full (XZ Utils pattern)
         # When dict_full reaches dict_size, the dictionary is full
@@ -1390,13 +934,6 @@ check_rc_finished: true)
         if @uncompressed_size != 0xFFFFFFFFFFFFFFFF
           @chunk_bytes_decoded += 1
         end
-
-        # DEBUG: Show literal decode for position 220-230
-        if old_dict_full.between?(220, 230)
-          XzUtilsDecoderDebug.debug_puts "\n=== decode_literal at dict_full=#{old_dict_full} ==="
-          XzUtilsDecoderDebug.debug_puts "  Decoded: 0x#{byte.to_s(16)} ('#{byte.chr}')"
-          XzUtilsDecoderDebug.debug_puts "  rep0/1/2/3=(#{@rep0},#{@rep1},#{@rep2},#{@rep3})"
-        end
       end
 
       # Decode a match
@@ -1416,60 +953,18 @@ check_rc_finished: true)
       #
       # @return [Boolean] True if EOS marker detected, false otherwise
       def decode_match
-        pos_state = @pos & ((1 << @pb) - 1)
-
-        # DEEP DEBUG: Trace every detail at position 227
-        if ENV["LZMA_DEBUG"] && @dict_full == 227
-          puts "\n=== DEEP DEBUG at dict_full=227 ==="
-          puts "  State: #{@state.value}, pos_state=#{pos_state}"
-          puts "  Rep distances BEFORE: (#{@rep0},#{@rep1},#{@rep2},#{@rep3})"
-          puts "  Range decoder: range=0x#{@range_decoder.range.to_s(16).upcase}, code=0x#{@range_decoder.code.to_s(16).upcase}"
-          input_buffer = @range_decoder.instance_variable_get(:@input)
-          puts "  Input buffer: #{input_buffer ? input_buffer.size : 'nil'} bytes"
-        end
+        pos_state = @pos & @pb_mask
 
         # Decode is_rep bit
         is_rep_model = @is_rep_models[@state.value]
-        if ENV["TRACE_IS_REP"]
-          range_val = @range_decoder.range
-          code_val = @range_decoder.code
-          puts "[XzUtilsDecoder.decode_match] Before is_rep: state.value=#{@state.value}"
-          puts "  is_rep_model.object_id=#{is_rep_model.object_id}, prob=#{is_rep_model.probability}"
-          puts "  range=#{range_val} (0x#{range_val.to_s(16)}), code=#{code_val} (0x#{code_val.to_s(16)})"
-          bound_calc = (range_val >> 11) * is_rep_model.probability
-          puts "  bound=(#{range_val} >> 11) * #{is_rep_model.probability} = #{bound_calc} (0x#{bound_calc.to_s(16)})"
-          puts "  code < bound? #{code_val < bound_calc}"
-        end
         is_rep = @range_decoder.decode_bit(is_rep_model)
 
-        if ENV["TRACE_IS_REP"]
-          range_val = @range_decoder.range
-          code_val = @range_decoder.code
-          puts "[XzUtilsDecoder.decode_match] Decoded is_rep=#{is_rep} with prob=#{is_rep_model.probability}"
-          puts "  After is_rep: range=#{range_val} (0x#{range_val.to_s(16)}), code=#{code_val} (0x#{code_val.to_s(16)})"
-        end
-
-        if ENV["LZMA_DEBUG"] && @dict_full == 227
-          puts "  Decoded is_rep bit: #{is_rep} (#{@is_rep_models[@state.value].probability})"
-          puts "  After is_rep: range=0x#{@range_decoder.range.to_s(16).upcase}, code=0x#{@range_decoder.code.to_s(16).upcase}"
-        end
-
-        if ENV["LZMA_DEBUG"]
-          warn "DEBUG: decode_match START - is_rep=#{is_rep}, state.value=#{@state.value}, pos_state=#{pos_state}, rep0/1/2/3=(#{@rep0},#{@rep1},#{@rep2},#{@rep3})"
-        end
-
         if is_rep.zero?
           # Regular match (not rep)
-          if ENV["LZMA_DEBUG"] && @dict_full.between?(220, 240)
-            puts "DEBUG pos #{@dict_full}: Regular match (not rep)"
-          end
           # Return result from decode_regular_match (true if EOS marker detected)
           return true if decode_regular_match(pos_state)
         else
           # Rep match - decode which rep distance to use
-          if ENV["LZMA_DEBUG"] && @dict_full.between?(220, 240)
-            puts "DEBUG pos #{@dict_full}: Rep match (is_rep=1)"
-          end
           decode_rep_match(pos_state)
         end
 
@@ -1488,14 +983,8 @@ check_rc_finished: true)
       # @param pos_state [Integer] Position state
       # @return [Boolean] True if EOS marker detected, false otherwise
       def decode_regular_match(pos_state)
-        # DEBUG: Trace matches around dict_full = 60-63
-        old_dict_full = @dict_full
-        old_rep0 = @rep0
-        old_state = @state.value
-
         # Decode match length
-        length_encoded = @length_coder.decode(@range_decoder,
-                                              pos_state)
+        length_encoded = @length_coder.decode(@range_decoder, pos_state)
         length = length_encoded + MATCH_LEN_MIN
 
         # Calculate length state for distance decoding
@@ -1508,54 +997,11 @@ check_rc_finished: true)
                       NUM_LEN_TO_POS_STATES - 1
                     end
 
-        # DEBUG: Show bytes being copied
-        if old_dict_full.between?(210, 230) || ENV["LZMA_DEBUG_DISTANCE"]
-          XzUtilsDecoderDebug.debug_puts "\n=== decode_regular_match at dict_full=#{old_dict_full} ===" if old_dict_full.between?(
-            210, 230
-          )
-          puts "[DISTANCE_DECODER] decode_regular_match at dict_full=#{old_dict_full}" if ENV["LZMA_DEBUG_DISTANCE"]
-          XzUtilsDecoderDebug.debug_puts "  pos_state=#{pos_state}" if old_dict_full.between?(
-            210, 230
-          )
-          puts "[DISTANCE_DECODER]   pos_state=#{pos_state}" if ENV["LZMA_DEBUG_DISTANCE"]
-          XzUtilsDecoderDebug.debug_puts "  state=#{old_state}" if old_dict_full.between?(
-            210, 230
-          )
-          puts "[DISTANCE_DECODER]   state=#{old_state}" if ENV["LZMA_DEBUG_DISTANCE"]
-          XzUtilsDecoderDebug.debug_puts "  length_encoded=#{length_encoded} length=#{length}" if old_dict_full.between?(
-            210, 230
-          )
-          puts "[DISTANCE_DECODER]   length_encoded=#{length_encoded} length=#{length}" if ENV["LZMA_DEBUG_DISTANCE"]
-          XzUtilsDecoderDebug.debug_puts "  len_state=#{len_state}" if old_dict_full.between?(
-            210, 230
-          )
-          puts "[DISTANCE_DECODER]   len_state=#{len_state}" if ENV["LZMA_DEBUG_DISTANCE"]
-          XzUtilsDecoderDebug.debug_puts "  rep0_before=#{old_rep0}" if old_dict_full.between?(
-            210, 230
-          )
-          puts "[DISTANCE_DECODER]   rep0_before=#{old_rep0}" if ENV["LZMA_DEBUG_DISTANCE"]
-        end
-
-        if ENV["LZMA_DEBUG"] && old_dict_full.between?(220, 230)
-          puts "DEBUG decode_regular_match at dict_full=#{old_dict_full}: length=#{length}"
-        end
-
         # Decode match distance
         # XZ Utils stores distance in rep0 without +1
         # The distance coder returns 0-based distance
         rep0 = @distance_coder.decode(@range_decoder, len_state)
 
-        # DEBUG
-        if (ENV.fetch("LZMA_DEBUG",
-                      nil) && old_dict_full.between?(210,
-                                                     230)) || old_dict_full == 293
-          puts "  rep0_decoded=#{rep0} (distance = #{rep0})"
-          puts "  buffer_back calculation: back=#{@dict_full - rep0 - 1}"
-        end
-        if ENV["LZMA_DEBUG"] && rep0 > 100000
-          puts "  [LARGE_DISTANCE at dict_full=#{old_dict_full}] rep0=#{rep0}, call count=#{$distance_decode_count || 'unknown'}"
-        end
-
         # Check for SDK EOS marker FIRST (before validation)
         # EOS marker: rep0 == UINT32_MAX (0xFFFFFFFF)
         # XZ Utils checks: if (rep0 == UINT32_MAX) goto eopm;
@@ -1582,22 +1028,13 @@ check_rc_finished: true)
           end
         end
 
-        # Validate distance using XZ Utils dict_is_distance_valid pattern
-        # XZ Utils: lzma_decoder.c:876 - dict_is_distance_valid(&dict, rep0)
-        # See lz_decoder.h:194-198: return dict->full > distance;
-        # XZ Utils dict->full = dict->pos - LZ_DICT_INIT_POS (same as our @dict_full)
-        # The distance is valid if: dict->full > distance
-        unless @dict_full > rep0
+        # Validate distance: ensure we have enough bytes in the buffer.
+        # In this linear buffer model, @pos grows unbounded across chunks while
+        # @dict_full is clamped at @dict_size. Use actual bytes written for validation.
+        actual_bytes_written = @pos - LZ_DICT_INIT_POS
+        unless actual_bytes_written > rep0
           raise Omnizip::DecompressionError,
-                "Invalid distance: #{rep0} (dict_full: #{@dict_full})"
-        end
-
-        # Additional validation: ensure distance doesn't exceed absolute dictionary size
-        # Only validate against absolute dictionary size to prevent buffer overflow
-        # The wrapping logic (below) handles rep0 >= @dict_full cases
-        if rep0 > @dict_size + @dict_full
-          raise Omnizip::DecompressionError,
-                "Invalid distance: #{rep0} exceeds maximum possible (dict_size=#{@dict_size}, dict_full=#{@dict_full})"
+                "Invalid distance: #{rep0} (bytes_written: #{actual_bytes_written})"
         end
 
         # IMPORTANT: Limit match length to not exceed uncompressed_size
@@ -1609,9 +1046,6 @@ check_rc_finished: true)
           # @uncompressed_size is the target for THIS chunk (not cumulative)
           remaining = @uncompressed_size - @chunk_bytes_decoded
           if length > remaining
-            if ENV["LZMA_DEBUG"] || remaining <= 5
-              puts "DEBUG: Limiting match length from #{length} to #{remaining} (chunk_bytes_decoded=#{@chunk_bytes_decoded}, uncompressed_size=#{@uncompressed_size}, dict_full=#{@dict_full})"
-            end
             length = remaining
           end
         end
@@ -1627,75 +1061,28 @@ check_rc_finished: true)
         #
         # dict->size in XZ Utils = dict_size + 2 * LZ_DICT_REPEAT_MAX
         # Our dict_buf size = @dict_size + LZ_DICT_INIT_POS = @dict_size + 2 * LZ_DICT_REPEAT_MAX
-        back = @dict_full - rep0 - 1
-        if rep0 >= @dict_full
-          # Distance wraps to the end of the dictionary buffer
-          # XZ Utils: back += dict->size - LZ_DICT_REPEAT_MAX;
-          # Our dict_buf size = @dict_size + LZ_DICT_INIT_POS = @dict_size + 2 * LZ_DICT_REPEAT_MAX
-          # So: back += (@dict_size + 2 * LZ_DICT_REPEAT_MAX) - LZ_DICT_REPEAT_MAX
-          #    = back + @dict_size + LZ_DICT_REPEAT_MAX
-          back += @dict_size + LZ_DICT_REPEAT_MAX
-        end
-        # Convert to buffer position (add LZ_DICT_INIT_POS offset)
-        buffer_back = back + LZ_DICT_INIT_POS
-
-        # DEBUG: Show buffer position for position 217
-        if old_dict_full.between?(210, 230)
-          XzUtilsDecoderDebug.debug_puts "  buffer_back=#{buffer_back}, back=#{back}"
-          bytes_at_back = @dict_buf[buffer_back, 3]
-          bytes_hex = if bytes_at_back.is_a?(String)
-                        bytes_at_back.bytes.map do |b|
-                          "%02x" % b
-                        end.join(" ")
-                      else
-                        bytes_at_back.map do |b|
-                          "%02x" % b
-                        end.join(" ")
-                      end
-          XzUtilsDecoderDebug.debug_puts "  First 3 bytes at buffer_back: #{bytes_hex} (#{bytes_at_back.inspect})"
-        end
-
-        if ENV["LZMA_DEBUG"]
-          b0 = @dict_buf[buffer_back]
-          b1 = @dict_buf[buffer_back + 1]
-          b2 = @dict_buf[buffer_back + 2]
-          b0_str = b0 ? "0x#{b0.to_s(16).upcase}" : "nil"
-          b1_str = b1 ? "0x#{b1.to_s(16).upcase}" : "nil"
-          b2_str = b2 ? "0x#{b2.to_s(16).upcase}" : "nil"
-          b0_chr = b0 ? "'#{b0.chr}'" : "nil"
-          b1_chr = b1 ? "'#{b1.chr}'" : "nil"
-          b2_chr = b2 ? "'#{b2.chr}'" : "nil"
-          warn "DEBUG: copy from buffer_back=#{buffer_back} (distance #{rep0}): #{b0_str} (#{b0_chr}) #{b1_str} (#{b1_chr}) #{b2_str} (#{b2_chr})"
-          warn "DEBUG: pos_before=#{@pos} (output #{@pos - LZ_DICT_INIT_POS}), len=#{length}, pos_after=#{@pos + length} (output #{@pos + length - LZ_DICT_INIT_POS})"
-          # Show what the dictionary contains at key positions (simplified)
-          warn "DEBUG: dict_buf size=#{@dict_buf.size}, allocated=#{@dict_size + 608}"
-        end
+        # Linear buffer: use @pos directly for back reference
+        # @pos always points to the next write position, so @pos - rep0 - 1
+        # gives the correct source position for the match copy
+        buffer_back = @pos - rep0 - 1
 
         # Copy bytes from dictionary and extend buffer as needed
         # XZ Utils dict_repeat pattern: dict->buf[dict->pos++] = dict->buf[back++]
-        if ENV["LZMA_DEBUG"] && old_dict_full.between?(220, 260)
-          puts "  Copying #{length} bytes from buffer_back=#{buffer_back} to @pos=#{@pos}, dict_full=#{@dict_full}"
-          puts "  Source bytes: #{@dict_buf[buffer_back, length].inspect}"
-          puts "  First 5 target bytes before copy: #{@dict_buf[@pos,
-                                                                5].inspect}"
-        end
-        length.times do |i|
-          byte = @dict_buf[buffer_back + i]
-          if ENV["LZMA_DEBUG"]
-            warn "DEBUG: copy iteration #{i}: reading dict_buf[#{buffer_back + i}]=0x#{byte.to_s(16).upcase} ('#{byte.chr}'), writing to dict_buf[#{@pos + i}]"
-          end
-          @dict_buf[@pos + i] = byte
-          if ENV["LZMA_DEBUG_ARRAY_WRITE"] && @dict_buf.size != (@dict_size + LZ_DICT_INIT_POS)
-            XzUtilsDecoderDebug.debug_puts "DEBUG: Array expanded during copy! write_pos=#{@pos + i}, byte=#{byte}, old_size=#{@dict_buf.size - 1}, new_size=#{@dict_buf.size}, decoder_id=#{@decoder_id}"
-          end
-        end
-        if ENV["LZMA_DEBUG"] && old_dict_full.between?(220, 230)
-          puts "  After copy: #{@dict_buf[@pos, length].inspect}"
-        end
+        src_idx = dict_index(buffer_back)
+        dst_idx = @dict_pos
+        buf_end = @buf_end
+        length.times do
+          byte = @dict_buf.getbyte(src_idx)
+          @dict_buf.setbyte(dst_idx, byte)
+          src_idx += 1
+          src_idx = LZ_DICT_INIT_POS if src_idx >= buf_end
+          dst_idx += 1
+          dst_idx = LZ_DICT_INIT_POS if dst_idx >= buf_end
+        end
+        @dict_pos = dst_idx
 
         # Update state and position
         @state.update_match
-        warn "DEBUG: After update_match - state=#{@state.value}" if ENV["LZMA_DEBUG"]
         @pos += length
 
         # Update dict_full (XZ Utils pattern)
@@ -1721,45 +1108,11 @@ check_rc_finished: true)
         # Update rep distances - rotate and set new rep0
         # SDK rotation: rep3←rep2, rep2←rep1, rep1←rep0, rep0←rep0
         # XZ Utils stores the actual distance in rep0 (no +1)
-        if ENV["LZMA_DEBUG"]
-          warn "DEBUG: Before rotation - rep0/1/2/3=(#{@rep0},#{@rep1},#{@rep2},#{@rep3}), new distance=#{rep0}"
-        end
-
-        # DEBUG: Trace rep rotation for position 224
-        if ENV["LZMA_DEBUG"] && old_dict_full.between?(220, 230)
-          puts "\n=== Rep rotation after match at dict_full=#{old_dict_full} ==="
-          puts "  Before: rep0/1/2/3=(#{@rep0},#{@rep1},#{@rep2},#{@rep3})"
-          puts "  Setting rep0 to: #{rep0.inspect}"
-        end
-
         @rep3 = @rep2
         @rep2 = @rep1
         @rep1 = @rep0
         @rep0 = rep0
 
-        if ENV["LZMA_DEBUG"]
-          warn "DEBUG: After rotation - rep0/1/2/3=(#{@rep0},#{@rep1},#{@rep2},#{@rep3})"
-        end
-
-        # DEBUG: Show final rep values
-        if ENV["LZMA_DEBUG"] && old_dict_full.between?(220, 230)
-          puts "  After: rep0/1/2/3=(#{@rep0},#{@rep1},#{@rep2},#{@rep3})"
-        end
-
-        # DEBUG: Verify rep0 is actually set
-        if old_dict_full.between?(220, 230)
-          actual_rep0 = @rep0
-          XzUtilsDecoderDebug.debug_puts "  VERIFICATION: @rep0=#{actual_rep0.inspect}, @rep0.object_id=#{@rep0.object_id}"
-        end
-
-        # DEBUG: Trace range/code state after match at dict_full 56-62
-        if ENV.fetch("LZMA_DEBUG",
-                     nil) && old_dict_full >= 56 && old_dict_full <= 62
-          range_after = @range_decoder.instance_variable_get(:@range)
-          code_after = @range_decoder.instance_variable_get(:@code)
-          XzUtilsDecoderDebug.debug_puts "  AFTER match (dict_full #{old_dict_full}→#{@dict_full}): range=0x#{range_after.to_s(16).upcase}, code=0x#{code_after.to_s(16).upcase}"
-        end
-
         false # Not EOS, continue decoding
       end
 
@@ -1777,49 +1130,16 @@ check_rc_finished: true)
       # @param pos_state [Integer] Position state
       # @return [Boolean] Always false (rep matches are never EOS)
       def decode_rep_match(pos_state)
-        # DEBUG: Trace rep matches around position 217
-        old_dict_full = @dict_full
-        old_rep0 = @rep0
-
-        # DEBUG: Show rep distances at the start
-        if ENV["LZMA_DEBUG"]
-          warn "DEBUG: decode_rep_match START[#{@decoder_id}] - rep0/1/2/3=(#{@rep0},#{@rep1},#{@rep2},#{@rep3})"
-        end
-
-        # DEBUG: Trace rep matches around position 227
-        if old_dict_full.between?(220, 230)
-          XzUtilsDecoderDebug.debug_puts "\n=== decode_rep_match at dict_full=#{old_dict_full} (decoder_id=#{@decoder_id}) ==="
-          XzUtilsDecoderDebug.debug_puts "  At START: rep0/1/2/3=(#{@rep0},#{@rep1},#{@rep2},#{@rep3})"
-          XzUtilsDecoderDebug.debug_puts "  old_rep0=#{old_rep0} (captured @rep0)"
-          XzUtilsDecoderDebug.debug_puts "  @rep0.object_id=#{@rep0.object_id}"
-        end
-
         # Decode which rep distance to use
         is_rep0 = @range_decoder.decode_bit(@is_rep0_models[@state.value])
 
-        puts "DEBUG rep match selection at dict_full=#{@dict_full}: is_rep0=#{is_rep0}, rep0/1/2/3 before=(#{@rep0},#{@rep1},#{@rep2},#{@rep3})" if @dict_full.between?(
-          220, 230
-        )
-        puts "  state.value=#{@state.value}, pos_state=#{pos_state}, model_index=#{(@state.value * (1 << @pb)) + pos_state}" if @dict_full.between?(
-          220, 230
-        )
-
-        if ENV["LZMA_DEBUG"]
-          warn "DEBUG: decode_rep_match - is_rep0=#{is_rep0}"
-        end
-
         if is_rep0.zero?
           # Use rep0
-          puts "DEBUG rep match using rep0" if @dict_full.between?(220, 230)
           # XZ Utils: is_rep0_long[state][pos_state] where the array size is NUM_STATES * (1 << pb)
           is_rep0_long = @range_decoder.decode_bit(
-            @is_rep0_long_models[(@state.value * (1 << @pb)) + pos_state],
+            @is_rep0_long_models[(@state.value * @pb_shift) + pos_state],
           )
 
-          if ENV["LZMA_DEBUG"]
-            warn "DEBUG: decode_rep_match - is_rep0_long=#{is_rep0_long}"
-          end
-
           if is_rep0_long.zero?
             # Short rep (length=1)
             length = 1
@@ -1832,10 +1152,6 @@ check_rc_finished: true)
           end
         else
           # Not rep0, check rep1/rep2/rep3
-          puts "DEBUG rep match NOT using rep0 (is_rep0=#{is_rep0})" if @dict_full.between?(
-            220, 230
-          )
-
           is_rep1 = @range_decoder.decode_bit(@is_rep1_models[@state.value])
 
           if is_rep1.zero?
@@ -1880,27 +1196,12 @@ check_rc_finished: true)
         # XZ Utils stores distances without +1 offset
         distance = @rep0
 
-        puts "DEBUG rep match after rotation: dict_full=#{old_dict_full}, distance=#{distance}, rep0/1/2/3=(#{@rep0},#{@rep1},#{@rep2},#{@rep3})" if old_dict_full.between?(
-          220, 230
-        )
-
-        # DEBUG: Trace rep matches around position 217
-        if old_dict_full.between?(210, 230)
-          XzUtilsDecoderDebug.debug_puts "\n=== decode_rep_match at dict_full=#{old_dict_full} ==="
-          XzUtilsDecoderDebug.debug_puts "  old_rep0=#{old_rep0}, new rep0=#{@rep0} (distance=#{distance})"
-          XzUtilsDecoderDebug.debug_puts "  pos_state=#{pos_state}"
-        end
-
-        if ENV["LZMA_DEBUG"]
-          warn "DEBUG: decode_rep_match - length=#{length}, distance=#{distance}, dict_full=#{@dict_full}, rep0/1/2/3=(#{@rep0},#{@rep1},#{@rep2},#{@rep3})"
-        end
-
-        # Validate distance using XZ Utils dict_is_distance_valid pattern
-        # See lz_decoder.h:194-198: return dict->full > distance;
-        # Note: distance=0 is valid (means copy from position 0, the first byte)
-        # XZ Utils allows distance=0 as long as dict->full > 0 (at least one byte available)
-        unless @dict_full > distance
-          raise "Invalid rep distance: #{distance} (dict_full: #{@dict_full})"
+        # Validate distance: ensure we have enough bytes in the buffer.
+        # In this linear buffer model, @pos grows unbounded across chunks while
+        # @dict_full is clamped at @dict_size. Use actual bytes written for validation.
+        actual_bytes_written = @pos - LZ_DICT_INIT_POS
+        unless actual_bytes_written > distance
+          raise "Invalid rep distance: #{distance} (bytes_written: #{actual_bytes_written})"
         end
 
         # IMPORTANT: Limit match length to not exceed uncompressed_size
@@ -1912,9 +1213,6 @@ check_rc_finished: true)
           # @uncompressed_size is the target for THIS chunk (not cumulative)
           remaining = @uncompressed_size - @chunk_bytes_decoded
           if length > remaining
-            if ENV["LZMA_DEBUG"] || remaining <= 5
-              puts "DEBUG REP: Limiting rep match length from #{length} to #{remaining} (chunk_bytes_decoded=#{@chunk_bytes_decoded}, uncompressed_size=#{@uncompressed_size}, dict_full=#{@dict_full})"
-            end
             length = remaining
           end
         end
@@ -1928,79 +1226,23 @@ check_rc_finished: true)
         #
         # dict->size in XZ Utils = dict_size + 2 * LZ_DICT_REPEAT_MAX
         # Our dict_buf size = @dict_size + LZ_DICT_INIT_POS = @dict_size + 2 * LZ_DICT_REPEAT_MAX
-        back = @dict_full - distance - 1
-        old_back = back
-        if distance >= @dict_full
-          # Distance wraps to the end of the dictionary buffer
-          # XZ Utils: back += dict->size - LZ_DICT_REPEAT_MAX;
-          # Our dict_buf size = @dict_size + LZ_DICT_INIT_POS = @dict_size + 2 * LZ_DICT_REPEAT_MAX
-          # So: back += (@dict_size + 2 * LZ_DICT_REPEAT_MAX) - LZ_DICT_REPEAT_MAX
-          #    = back + @dict_size + LZ_DICT_REPEAT_MAX
-          back += @dict_size + LZ_DICT_REPEAT_MAX
-        end
-        # Convert to buffer position (add LZ_DICT_INIT_POS offset)
-        buffer_back = back + LZ_DICT_INIT_POS
-
-        puts "DEBUG rep match copy at dict_full=#{@dict_full}: @dict_full=#{@dict_full}, distance=#{distance}, back=#{back}, buffer_back=#{buffer_back}" if @dict_full.between?(
-          220, 230
-        )
-
-        # DEBUG: Show back calculation for position 217
-        if old_dict_full.between?(210, 230)
-          XzUtilsDecoderDebug.debug_puts "  back calculation: @dict_full=#{@dict_full}, distance=#{distance}"
-          XzUtilsDecoderDebug.debug_puts "  back=#{old_back}, wrapped_back=#{back}, buffer_back=#{buffer_back}"
-          bytes_at_back = @dict_buf[buffer_back, 3]
-          bytes_hex = if bytes_at_back.is_a?(String)
-                        bytes_at_back.bytes.map do |b|
-                          "%02x" % b
-                        end.join(" ")
-                      else
-                        [bytes_at_back].flatten.map do |b|
-                          "%02x" % b
-                        end.join(" ")
-                      end
-          XzUtilsDecoderDebug.debug_puts "  First 3 bytes at buffer_back: #{bytes_hex} (#{bytes_at_back.inspect})"
-        end
+        # Linear buffer: use @pos directly for back reference
+        buffer_back = @pos - distance - 1
 
-        # Copy bytes from dictionary and extend buffer as needed
+        # Copy bytes from dictionary
         # XZ Utils dict_repeat pattern: dict->buf[dict->pos++] = dict->buf[back++]
-        if old_dict_full.between?(250, 260)
-          source_val = @dict_buf[@pos - 1]
-          puts "  Rep match copy at dict_full=#{@dict_full}: length=#{length}, distance=#{distance}, @pos=#{@pos} (will write to #{@pos}...#{@pos + length - 1})"
-          puts "  Reading from @pos-1=#{@pos - 1}, source byte = #{source_val} (0x#{source_val.to_s(16)} '#{begin
-            source_val.chr
-          rescue StandardError
-            '?'
-          end}')"
-          puts "  Before copy: @dict_buf[#{@pos}...#{@pos + length - 1}] = #{@dict_buf[@pos,
-                                                                                       length].inspect}"
-        end
-        length.times do |i|
-          byte = @dict_buf[buffer_back + i]
-          if @dict_full == 227 && i.zero?
-            puts "DEBUG dict_copy at dict_full=227, i=0:"
-            puts "  buffer_back=#{buffer_back}, byte=#{byte} ('#{byte.chr}')"
-            puts "  Writing to @pos=#{@pos + i}"
-            puts "  dict_buf[buffer_back...buffer_back+10] = #{@dict_buf[buffer_back,
-                                                                         10].inspect}"
-            # DEBUG: Check if buffer_back+1 has the correct byte
-            puts "  dict_buf[buffer_back+1=#{buffer_back + 1}] = #{@dict_buf[buffer_back + 1].inspect} ('#{begin
-              @dict_buf[buffer_back + 1].chr
-            rescue StandardError
-              '?'
-            end}')"
-            prev_5 = if buffer_back > 4
-                       @dict_buf[(buffer_back - 5)..(buffer_back - 1)].map do |b|
-                         "0x#{b.to_s(16).upcase} (#{b.chr})"
-                       end.join(", ")
-                     else
-                       "N/A"
-                     end
-            puts "  Previous 5 bytes: [#{prev_5}]"
-            puts "  Current dict_full=#{@dict_full}, @pos=#{@pos}"
-          end
-          @dict_buf[@pos + i] = byte
-        end
+        src_idx = dict_index(buffer_back)
+        dst_idx = @dict_pos
+        buf_end = @buf_end
+        length.times do
+          byte = @dict_buf.getbyte(src_idx)
+          @dict_buf.setbyte(dst_idx, byte)
+          src_idx += 1
+          src_idx = LZ_DICT_INIT_POS if src_idx >= buf_end
+          dst_idx += 1
+          dst_idx = LZ_DICT_INIT_POS if dst_idx >= buf_end
+        end
+        @dict_pos = dst_idx
 
         # Update position
         @pos += length
@@ -2050,40 +1292,19 @@ check_rc_finished: true)
       def calculate_literal_state
         # XZ Utils dict_get0 pattern: dict->buf[dict->pos - 1]
         # For array buffer, use @pos - 1 as index
-
-        # DEBUG: Check buffer state before access
-        if ENV["LZMA_DEBUG_CALC_STATE"] && @dict_full == 8
-          XzUtilsDecoderDebug.debug_puts "DEBUG before calc_state[#{@decoder_id}]: pos=#{@pos}, dict_full=#{@dict_full}"
-          XzUtilsDecoderDebug.debug_puts "  @dict_buf.object_id=#{@dict_buf.object_id}, size=#{@dict_buf.size}"
-          XzUtilsDecoderDebug.debug_puts "  Accessing index #{@pos - 1}: value=#{@dict_buf[@pos - 1].inspect}"
-        end
-
-        prev_byte = @dict_full.positive? ? @dict_buf[@pos - 1] : 0
-
-        # Safeguard: if prev_byte is nil, use 0 and log detailed diagnostics
-        # This can happen if the buffer was not properly initialized or we're accessing the wrong buffer
-        if prev_byte.nil?
-          if ENV["LZMA_DEBUG_NIL_BYTE"]
-            raise "DEBUG: prev_byte is nil! decoder_id=#{@decoder_id}, @pos=#{@pos}, @dict_full=#{@dict_full}, @dict_buf.size=#{@dict_buf&.size || 'nil'}, accessing index #{@pos - 1}, nil_count=#{@dict_buf&.count(nil) || 'N/A'}, @dict_buf.object_id=#{@dict_buf&.object_id || 'nil'}"
-          end
-
-          prev_byte = 0
-        end
-
-        if ENV["LZMA_DEBUG_CALC_STATE"]
-          XzUtilsDecoderDebug.debug_puts "DEBUG calc_state[#{@decoder_id}]: pos=#{@pos}, dict_full=#{@dict_full}, @dict_buf.object_id=#{@dict_buf.object_id}, prev_byte=#{prev_byte}"
-        end
-
-        # XZ Utils formula from lzma_common.h:literal_mask_calc
-        # literal_mask = (UINT32_C(0x100) << (lp)) - (UINT32_C(0x100) >> (lc))
-        # For lc=3, lp=0: (256 << 0) - (256 >> 3) = 256 - 32 = 224 (0xE0)
-        literal_mask = (0x100 << @lp) - (0x100 >> @lc)
-
-        # Combine dict_full (actual decoded position) and prev_byte, then apply mask
-        # IMPORTANT: XZ Utils uses dict.pos (which starts at 0 and increments)
-        # omnizip's @pos starts at LZ_DICT_INIT_POS (576), so we use @dict_full instead
-        # This ensures we match XZ Utils's literal state calculation exactly
-        (((@dict_full << 8) + prev_byte) & literal_mask)
+        prev_idx = @dict_pos == LZ_DICT_INIT_POS ? @buf_end - 1 : @dict_pos - 1
+        prev_byte = @dict_full.positive? ? @dict_buf.getbyte(prev_idx) : 0
+
+        # Safeguard: if prev_byte is nil, use 0
+        prev_byte = 0 if prev_byte.nil?
+
+        # Combine current output position and prev_byte, then apply cached mask.
+        # XZ Utils uses dict.pos (continuous write position) for this calculation.
+        # We use @pos - LZ_DICT_INIT_POS (total bytes decoded) instead of @dict_full,
+        # because @dict_full is clamped at @dict_size after the circular buffer wraps,
+        # which would freeze the position-dependent literal model selection.
+        output_pos = @pos - LZ_DICT_INIT_POS
+        ((output_pos << 8) + prev_byte) & @literal_mask
       end
     end
   end