omnizip 0.3.19 → 0.3.21

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: affda0906d52a418254670adb02e96312d6e268d1df4aafbba575ade503edfbe
-  data.tar.gz: ae4e84af21221350bf4d67a1b295546674527e091b500a715cb96f8547870990
+  metadata.gz: 5d0052490f16345b27296100499706bddd9936ea4a4b839dc34ea862bef32d77
+  data.tar.gz: f33f511d967b2a4f5d881b0e9205c72e57a9744480fdcb914b5ee44df9a14983
 SHA512:
-  metadata.gz: 91044c5b1067662c5177e2b8ca262ad0434e4a4cf94e9ea321251723499188fc4b57b3793e2ed88ce51ea406cdb1bfb6d31921ef3b08a7baaf4fd6e62102dc5b
-  data.tar.gz: b6614848a2eb450b748bca1d3d297b7bcd5751607124687237c75ebdeeb43b033ffe6d9af49af457e94aa1cace5ab615c3fe6d04f6a5bb3206a863249225ead6
+  metadata.gz: 722b0ece40f17d907a74df2fd9a333945f5060101f6c816bc613c56b1e653d907b31fc803afe40b840217e70dd6301304e0c39660071a0fab20d3df4e6a9c884
+  data.tar.gz: f3810c7f1d35b12a88dbc2651945ff18d66399b42f5bb3db1299aece2545fceb9e6336025d2e3555d4b8aa4608f3991091ddd33dca0d575a1b6153da0b4c6a02

data/CHANGELOG.md

@@ -5,6 +5,100 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [0.3.19] - 2026-08-25
+
+### Fixed
+- 7-Zip LZMA2 encoder corrupted every chunk after the first: pos_state was
+  computed from the chunk-relative position while decoders count positions
+  continuously across chunk boundaries. The stale duplicated encoder is now a
+  thin subclass of the fixed XZ Utils encoder (also picking up its state-reset,
+  64 KiB chunk-cap and symbol-queue fixes).
+
+## [0.3.18] - 2026-08-25
+
+### Added
+- Zstandard long-distance matching (LDM): a sparse hash table over the whole
+  frame finds matches beyond the 128 KiB block window at levels >= 19 for
+  multi-block inputs, bringing zstd-22 output to reference parity
+  (0.146 vs omnizip-rs 0.1456 on the benchmark corpus).
+
+## [0.3.17] - 2026-08-25
+
+### Changed
+- Zstandard greedy parser: rep0 fast-path and backward match extension into
+  the pending literals (default-level text ratio 0.177 -> 0.167).
+
+## [0.3.16] - 2026-08-24
+
+### Added
+- Zstandard Compressed_Blocks now carry a sequences section: LZ77 match
+  finder (greedy/lazy/lazy2) and LL/OF/ML FSE sequence encoding with
+  Predefined/FSE_Compressed table selection. Text ratio 0.49 -> ~0.17.
+
+### Changed
+- Migrated ConversionOptions, ParallelOptions, ProgressOptions and EtaResult
+  models to lutaml-model (breaking change for hand-rolled hash access).
+
+## [0.3.15] - 2026-08-24
+
+### Fixed
+- Zstandard codec rebuilt per RFC 8878: FSE tables from stream, FSE Huffman
+  weights, treeless literals, repeat mode, XXH64 frame checksums, window
+  descriptor; `compress` with default options now really compresses instead
+  of emitting stored frames (issues #27, BUGREPORT 01-10).
+- XZ LZMA2 encoder: chunking, repeat-offset state and wire format repaired
+  (issue #26; missing `tempfile` require, symbol-buffer overflow at ~10 MB).
+
+## [0.3.14] - 2026-07-25
+
+### Changed
+- Documented the Algorithms vs Implementations boundary; deepened the
+  Algorithm base class with a class-level facade and IO::Source/Sink.
+- Extracted `Omnizip::Parallel::Engine`.
+
+## [0.3.13] - 2026-07-24
+
+### Changed
+- Reverted the v0.3.12 require-omnizip-everywhere band-aid in favor of
+  per-file entry-point requires.
+
+## [0.3.12] - 2026-07-24
+
+### Fixed
+- Circular dependency at gemspec load (`version.rb` no longer requires
+  omnizip); missing entry-point requires at the top of internal files.
+
+## [0.3.11] - 2026-07-22
+
+### Fixed
+- Format files broke when required directly by external code; LinkHandler
+  symlink gating; BCJ filter autoload.
+
+## [0.3.10] - 2026-07-21
+
+### Changed
+- Migrated CompressionOptions and AlgorithmMetadata to lutaml-model;
+  decoupled Convenience from ZIP via ArchiveHandler; replaced `respond_to?`
+  type checks with `is_a?`.
+
+## [0.3.9] - 2026-03-24
+
+### Fixed
+- Windows unrar detection; 7-Zip SDK version validation (major version only).
+
+## [0.3.8] - 2026-02-24
+
+### Fixed
+- Formats now auto-register when their files are loaded directly.
+
+## [0.3.7] - 2026-02-23
+
+### Fixed
+- XZ dictionary-size bounds checking (OOM prevention); block header parser
+  autoload.
+
 ## [0.3.6] - 2026-02-23
 
 ### Changed
@@ -18,8 +112,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Fixed RAR format `verify` and `repair` convenience methods
 - Fixed library loading to ensure convenience methods are available at startup
 
-## [Unreleased]
-
 ### Added
 - **XAR Format Support**: Full read/write support for XAR (eXtensible ARchive) format
   - XAR is primarily used on macOS for software packages (.pkg files) and installers
@@ -594,4 +686,4 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Native compression support documented
   - All 6 compression methods explained
   - Performance characteristics detailed
-  - Real-world usage examples
+  - Real-world usage examples

data/TODO.refactor/00-overview.md

@@ -26,7 +26,7 @@ as absolute rules:
 | 04 | `04-filter-base-consolidation.md` | medium | **DONE** |
 | 05 | `05-send-private-methods.md` | high | **DONE** |
 | 06 | `06-instance-variable-access.md` | high | **DONE** |
-| 07 | `07-respond-to-replacement.md` | medium | **PARTIAL** — IO::Source/Sink adapter built; type-check sites converted; ~76 IO capability checks remain in xz_impl/* and ole/* (legitimate duck-typing for ungetbyte / set_encoding etc.) |
+| 07 | `07-respond-to-replacement.md` | medium | **DONE** — 11 type checks converted; 45 feature-detection sites annotated `# allowed:` and enforced by a spec; 1 deferred type check in `algorithms/lzma.rb` pending `LzmaOptions` unification |
 | 08 | `08-spec-doubles.md` | low | **DONE** |
 | 09 | `09-cli-shared-module.md` | low | **DONE** |
 | 10 | `10-format-detector-ocp.md` | medium | **DONE** |
@@ -43,7 +43,7 @@ as absolute rules:
 | `.send` on private methods | 17 | **0** |
 | `instance_variable_set`/`get` | 54 | **0** |
 | `double()` in specs | 1 | **0** |
-| `respond_to?` | 111 | 76 (mostly IO capability detection) |
+| `respond_to?` | 60 at track 07 start (111 originally) | 49 — 46 annotated `# allowed:` (45 feature detection + 1 deferred type check) plus 3 doc comments |
 | Hand-rolled model `to_h` | 26 | 24 (2 migrated to lutaml-model) |
 
 ## Architecture summary

data/TODO.refactor/07-respond-to-replacement.md

@@ -1,91 +1,237 @@
 # 07 — Replace `respond_to?` with proper typing
 
 Priority: **medium**.
-Status: **partial — see Remaining Work**.
+Status: **DONE**, with one known exception — `algorithms/lzma.rb:200` is a type
+check we chose not to convert, not feature detection. See "The one exception".
 
 ## Rule
 
 > NEVER use `respond_to?` for type checking. Use `is_a?` for type checks,
 > or better yet, design the type hierarchy so the check isn't needed.
 
-## Done in this pass
-
-- Removed `opts.respond_to?(:"#{k}=")` from `parallel_compressor.rb` and
-  `parallel_extractor.rb` by adding `ParallelOptions#apply(hash)` with a
-  fixed setter whitelist.
-- Removed `format.respond_to?(:metadata)` from
-  `optimization_registry.rb` by relying on `Strategy.metadata` being
-  defined on the base class.
-
-## Remaining work
-
-109 `respond_to?` occurrences remain in `lib/`. They fall into these
-categories (sampled):
-
-### A. Duck-typed IO/String inputs (largest category)
-
-`input.respond_to?(:read)` / `output.respond_to?(:write)` in
-`formats/xz.rb`, `formats/lzma_alone.rb`, `formats/lzip.rb`,
-`formats/xz_impl/*.rb`, `pipe/*.rb`.
-
-**Fix:** introduce `Omnizip::IO::Source.for(input)` and
-`Omnizip::IO::Sink.for(output)` adapter methods in `lib/omnizip/io.rb`
-that wrap String / StringIO / File / Pathname behind a single API.
-Replace each `respond_to?`-guarded branch with a polymorphic call on the
-adapter.
-
-### B. Job-size duck typing
-
-`job.respond_to?(:size)` in `parallel/job_scheduler.rb` (6 occurrences).
-
-**Fix:** define `Parallel::Job` base with `#size` returning a default of
-1. Jobs that know their size override; others inherit the default. The
-scheduler stops needing to ask.
-
-### C. Entry-type duck typing
-
-`entry.respond_to?(:name)`, `entry.respond_to?(:path)`,
-`entry.respond_to?(:filename)`, `entry.respond_to?(:read)`,
-`entry.respond_to?(:get_input_stream)` in
-`extraction/selective_extractor.rb`, `parallel/parallel_extractor.rb`,
-`commands/archive_list_command.rb`, `pipe/stream_decompressor.rb`,
-`formats/rar/reader.rb`.
-
-**Fix:** define `Omnizip::Models::Entry` as a common base for
-zip/seven_zip/rar/tar entry classes. Each format's entry inherits and
-implements the contract (`#name`, `#size`, `#unix_perms`, `#mtime`,
-etc., returning nil when not applicable).
-
-### D. Platform feature detection
-
-`File.respond_to?(:symlink)`, `File.respond_to?(:link)`,
-`io.respond_to?(:pos)`, `io.respond_to?(:seek)` in `link_handler.rb`,
-`file_type.rb`.
-
-**Fix:** add `Platform.symlinks_supported?`,
-`Platform.seekable?(io)` predicates in `lib/omnizip/platform.rb`.
-
-### E. Hash-to-object metaprogramming
-
-`opts.respond_to?(:"#{k}=")` — same as ParallelOptions pattern. Fix
-case-by-case with whitelisted `apply(hash)` methods.
-
-### F. Reader-specific methods
-
-`reader.respond_to?(:split_reader)`,
-`elem.respond_to?(:text)`, `entry.respond_to?(:method)` — these are
-narrow cases. Convert to `is_a?` checks against the concrete class, or
-introduce a small type hierarchy.
-
-## Recommended execution order
-
-1. Tracks A and D — small, localized, no API change for callers.
-2. Track B — single file, base class addition.
-3. Track C — larger; needs the Entry base class first.
-4. Track E — case-by-case.
-5. Track F — case-by-case.
+## Outcome
+
+`lib/` went from 60 `respond_to?` occurrences to 49:
+
+| | count |
+|---|---|
+| Converted to a real type check | 11 |
+| Retained as genuine feature detection, annotated `# allowed:` | 45 |
+| Retained as a **deferred type check**, annotated `# allowed:` | 1 |
+| Prose inside doc comments (not code) | 3 |
+
+46 sites carry an `# allowed:` annotation, but they are not all the same kind of
+thing. 45 are feature detection on objects we do not control. **One is a type
+check we decided not to convert** — counting it with the other 45 would overstate
+how complete this track is, so it is broken out here and below.
+
+The three prose occurrences are in `entry.rb`, `io/source.rb` and
+`parallel/job_scheduler.rb`, where they document the pattern that was removed.
+They are kept deliberately — rewording them so a `grep` returns zero would be
+dishonest.
+
+`spec/omnizip/respond_to_annotation_spec.rb` enforces the convention. It lexes
+`lib/` with `Ripper` and fails on any `respond_to?` **identifier token** that
+lacks a `# allowed: <reason>` **comment token** on its own line or the one
+above. Being lexer-based rather than substring-based, a `# allowed:` inside a
+string literal cannot satisfy it and a `respond_to?` inside a heredoc cannot
+trip it.
+
+Note what that spec does and does not do: it enforces that a reason is
+**stated**, not that the reason is **good**. It cannot tell feature detection
+from a deferred type check, which is exactly why the one exception is recorded
+here in prose rather than left for the spec to imply.
+
+## The governing distinction
+
+A check is a **type check** (convert it) when every runtime type is enumerable
+from the source. It is **feature detection** (annotate it) when a third party
+can register or pass something we cannot enumerate.
+
+The second half is what this pass got wrong at first. omnizip's world is open:
+
+- `FilterRegistry.register` (`filter_registry.rb:30`) raises only on a nil name
+  or nil class. **No inheritance check.**
+- `ProfileRegistry.register` (`profile_registry.rb:23`) requires only
+  `is_a?(CompressionProfile)`, not membership in the built-in set.
+- `ArchiveHandler.register` (`archive_handler.rb:26`) accepts any object.
+- The third positional `options` parameter on every `Algorithm#compress` /
+  `#decompress` is public and unconstrained.
+
+So a check can look like a type check, and be one inside this repo today, while
+still being reachable with a type we cannot name. Those stay, annotated.
+
+## What was converted (11)
+
+| site | conversion |
+|---|---|
+| `algorithms/registration.rb:22` | guard dropped; `Algorithm.inherited` defines `register_algorithm` on every subclass |
+| `algorithms/lzma/xz_utils_decoder.rb:291` | guard dropped; `@range_decoder ||=` runs earlier in the same method |
+| `commands/archive_list_command.rb:72`, `:105` | `archive.entries`; the private builder returns one of three readers, all of which expose it |
+| `implementations/seven_zip/lzma2/encoder.rb`, `implementations/xz_utils/lzma2/encoder.rb` | both `StringCompat` modules deleted, `byteslice` inlined at all three call sites — see below |
+| `commands/archive_extract_command.rb:225` | `archive.is_a?(Omnizip::Zip::File)`; closed 4-way set, only ZIP closes |
+| `implementations/xz_utils/lzma2/decoder.rb:420` | guard dropped; `@lzma_decoder` is always an `XzUtilsDecoder`, which exposes `range_decoder` |
+| `io/stream_manager.rb:74` | `@source.close if @owned`; `@owned` is only true for a path the manager itself opened as a `File` |
+| `algorithms/xz_lzma2.rb:59`, `algorithms/sevenzip_lzma2.rb:64` | routed through `Omnizip::IO::Source.for`, which accepts any `#read` duck |
+
+The String branch in those last two was deliberately **not** routed through the
+adapter: `Source::StringSource#read` treats a String that exists on disk as a
+file path, so routing it would silently start reading files off disk whenever
+input collided with a filename.
+
+### The `StringCompat` modules
+
+Each held `if "".respond_to?(:byteslice)` with a `string.bytes[start, length]`
+fallback, under a comment claiming Ruby 3.0-3.1 lacks `String#byteslice`.
+**That comment was simply wrong** — `String#byteslice` has existed since Ruby
+1.9.3, so the fallback was unreachable on every Ruby that could ever have run
+this gem.
+
+Deleting only the `respond_to?` branch would have left a module named `Compat`
+whose sole purpose was that branch, forwarding one call to `String#byteslice`
+and nothing else — and two of the three call sites still carried a "for Ruby
+3.0-3.1 compatibility" comment that would have become a lie. So both modules
+were deleted outright and `temp_buffer.byteslice(0, out_pos.value)` inlined at
+all three call sites (`xz_utils/lzma2/encoder.rb` ×2,
+`seven_zip/lzma2/encoder.rb` ×1).
+
+The separate comment at the two XZ Utils call sites is **kept**: it explains why
+`byteslice` rather than `[]`, citing
+https://bugs.ruby-lang.org/issues/15985 (the `[]` operator can return extra
+bytes around NULs). That reason is real and outlives the compat shim.
+
+## What was retained as feature detection (45)
+
+Grouped by what the object actually is. `algorithms/lzma.rb:200` is deliberately
+excluded from these counts and covered in the next section.
+
+- **Caller-supplied IO** (24) — `formats/xz_impl/stream_decoder.rb` (8),
+  `formats/xz_impl/block_decoder.rb` (3), `algorithms/lzma/xz_utils_decoder.rb`
+  (2), `file_type.rb` (3), `io/source.rb` (4), `io/stream_manager.rb` (2),
+  `io/buffered_input.rb`, `io/buffered_output.rb`. Ruby has no `Seekable` or
+  `Ungettable` interface to type against; `StringIO`, `File`, `Socket`,
+  `Tempfile` and a user's own duck all differ in exactly `seek` / `pos` / `size`
+  / `ungetbyte` / `set_encoding` / `close`.
+- **Public `options` parameter** (7) — `algorithms/lzma.rb` (4),
+  `algorithms/bzip2.rb`, `algorithms/deflate.rb`, `algorithms/zstandard.rb`.
+- **Open registries** (4) — `models/filter_config.rb`,
+  `commands/profile_show_command.rb`, `convenience.rb` (2).
+- **Other caller-supplied objects** (10) — foreign archives and entries in
+  `extraction/selective_extractor.rb` (5) and `extraction/filter_chain.rb` (3),
+  an output sink in `implementations/seven_zip/lzma/encoder.rb`, and a metadata
+  object in `metadata/metadata_validator.rb`.
+
+## The one exception (1)
+
+`algorithms/lzma.rb:200` is annotated *"type check deferred, not feature
+detection"*. That annotation is accurate and the code is honest, but it means
+**track 07 is complete except for this single site**. It is a type check that
+survives, not a capability probe.
+
+```ruby
+level = if options.respond_to?(:level)
+```
+
+Two unrelated value objects reach `build_encoder_options` carrying `#level`:
+`Models::CompressionOptions` and
+`Formats::Rar::Rar5::Solid::SolidEncoder::LzmaOptions` (`solid_encoder.rb:95`,
+reaching this method from `:52`). They share no ancestor. Rewriting the check to
+`is_a?(Models::CompressionOptions)` would send solid-RAR5 compression down the
+`else` branch and pin its level to 5 instead of the configured 1–5 — a silent
+regression, which is why the conversion was rejected rather than attempted.
+
+**What would close it:** unify `SolidEncoder::LzmaOptions`,
+`Compression::LZMA::LzmaOptions` (`rar5/compression/lzma.rb:184`) and
+`Models::CompressionOptions` into one type. That is RAR5 work, it breaks
+`solid_encoder_spec.rb` and `lzma_spec.rb` assertions on `dict_size`, and
+`CompressionOptions` names the attribute `dictionary_size`. Once those are one
+type, this site converts to `is_a?` in a single line and track 07 is
+unconditionally done.
+
+Three cheaper-looking alternatives were considered and rejected: reaching from
+`algorithms/` into `formats/rar/rar5/solid/` with a two-armed `is_a?`; a shared
+`LevelledOptions` mixin introduced for exactly two call sites; and replacing
+`LzmaOptions` with `CompressionOptions` outright, which the specs block.
+
+## Corrections to the previous version of this document
+
+- The count was **60**, not 109.
+- Category B (`job.respond_to?(:size)` in `parallel/job_scheduler.rb`) and
+  category E (`opts.respond_to?(:"#{k}=")`) were **already done**.
+- Category D was wrong. No `File.respond_to?(:symlink)` / `(:link)` sites
+  remained and `link_handler.rb` had none at all. The survivors filed under D
+  were `io.respond_to?(:pos)` / `(:seek)` in `file_type.rb`, which are **IO**
+  capability checks. The proposed `Platform.seekable?(io)` was rejected:
+  seekability is not a platform property, and the helper would still have
+  contained `respond_to?`, merely relocated.
+- `formats/ole/` contained **zero** occurrences. The capability cluster was
+  `formats/xz_impl/` plus `algorithms/lzma/xz_utils_decoder.rb`.
+- Category C was partly done already: `Omnizip::Entry` existed and was included
+  by 12 entry classes. Converting `extraction/filter_chain.rb` to use it was
+  attempted and rejected — below.
+
+## Rejected: converting `extraction/filter_chain.rb`
+
+`FilterChain#extract_filename` still walks `name` / `path` / `filename`. Routing
+it through `Omnizip::Entry` looked like the intended fix, but a foreign entry
+with `name == "secret.txt"` and `to_s == "opaque"` matches `*.txt` today and
+would not afterwards. Because these filters drive **exclusion** as well as
+inclusion, a filter that stops matching means a file the caller meant to block
+gets extracted. `Extraction.extract_with_filter` is public, so this is
+reachable. The conversion needs every entry reaching `FilterChain` to include
+`Omnizip::Entry`, which the public API cannot guarantee.
+
+## Bug found while doing this work
+
+Auditing `IO::Source` for this track surfaced a live `NameError` in shipped
+code. `io/source.rb` had **no `require` statements at all**, while `Source.for`
+and `Sink.for` both `case` on `::IO, ::StringIO, ::Tempfile`. After a bare
+`require "omnizip"` neither `StringIO` nor `Tempfile` is defined, so any input
+that was not already an `::IO` raised:
+
+```
+$ ruby -Ilib -e 'require "omnizip"
+                 sink = Object.new; def sink.write(d); end
+                 Omnizip::Formats::Xz.create("hello", sink)'
+NameError: uninitialized constant Tempfile
+```
+
+The adapter had 12 production call sites across `Formats::Xz`, `Formats::Lzip`,
+`Formats::LzmaAlone` and `Algorithms::LZMA2`. The failure moved with the caller
+— whichever constant the load path happened to pull in first appeared to work —
+which is why it survived.
+
+Fixed in its own commit across 15 files: 12 requires added to 11 files that
+referenced a constant without requiring it, and 4 requires relocated out of
+method and class bodies into the file prologue.
+
+`spec/omnizip/constant_require_spec.rb` enforces the invariant statically —
+`Ripper.lex` finds the constant references, `Ripper.sexp` confirms the matching
+require is a top-level unconditional statement in the prologue, accepting both
+`require "x"` and `require("x")`. `spec/omnizip/clean_load_spec.rb` adds four
+subprocess regression proofs. Those must shell out: an in-process example passes
+on the broken library, because `spec_helper` and sibling specs load both
+constants as a side effect. That is the same masking that hid the bug.
 
 ## Acceptance
 
-`grep -rn "respond_to?" lib/` returns zero matches (or each remaining
-occurrence is annotated with `# allowed: <reason>`).
+- `grep -rn "respond_to?" lib/` → 49: 46 annotated code sites (45 feature
+  detection + 1 deferred type check) and 3 doc comments.
+- `spec/omnizip/respond_to_annotation_spec.rb` passes, and fails loudly on any
+  new unannotated occurrence.
+- The one deferred type check is tracked in "The one exception" above, not
+  quietly folded into the feature-detection count.
+
+## Follow-ups
+
+- Unify `SolidEncoder::LzmaOptions`, `Compression::LZMA::LzmaOptions` and
+  `Models::CompressionOptions`, which would let `algorithms/lzma.rb:200`
+  convert.
+- Normalize algorithm `options` to a single type. `Algorithm.compress(data,
+  level: 9)` forwards a Hash, so `bzip2`, `deflate` and `zstandard` silently
+  drop the level today — reached from `formats/zip/writer.rb:390`,
+  `zip/output_stream.rb:278` and `parallel/parallel_compressor.rb:104`. This
+  changes compressed output, so it needs its own pass. It would delete most of
+  the `options` annotations.
+- Give `FilterChain` a guaranteed `Omnizip::Entry` contract, which would let
+  `extract_filename` convert.

data/lib/omnizip/algorithm.rb

@@ -16,6 +16,8 @@
 # See the COPYING file for the complete text of the license.
 #
 
+require "stringio"
+
 module Omnizip
   # Abstract base class for compression algorithms.
   #
@@ -23,8 +25,6 @@ module Omnizip
   # the required methods. Algorithms are automatically registered with the
   # AlgorithmRegistry when defined.
   class Algorithm
-    require "stringio"
-
     attr_reader :options, :filter
 
     # Initialize algorithm with options.

data/lib/omnizip/algorithms/bzip2.rb

@@ -99,6 +99,7 @@ module Omnizip
 
         opts = {}
 
+        # allowed: options is a public parameter; any object with #level is honored
         if options.respond_to?(:level)
           level = options.level || 9
           opts[:block_size] = block_size_for_level(level)

data/lib/omnizip/algorithms/deflate.rb

@@ -94,6 +94,7 @@ module Omnizip
 
         opts = {}
 
+        # allowed: options is a public parameter; any object with #level is honored
         if options.respond_to?(:level)
           opts[:level] = map_compression_level(options.level)
         end

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

@@ -288,9 +288,7 @@ check_rc_finished: true)
         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
+        @range_decoder.read_init_bytes if @range_decoder.init_bytes_remaining.positive?
 
         # Main decoding loop
         # XZ Utils pattern (lzma_decoder.c:305-306):
@@ -439,6 +437,7 @@ check_rc_finished: true)
               next_byte = stream.getbyte
               if next_byte
                 # Put the byte back
+                # allowed: caller-supplied stream; peek-back is optional
                 stream.ungetbyte(next_byte) if stream.respond_to?(:ungetbyte)
                 raise Omnizip::DecompressionError,
                       "LZMA_Alone file has data after the end-of-payload marker. The file may be corrupted or contain concatenated streams."
@@ -452,6 +451,7 @@ check_rc_finished: true)
             begin
               next_byte = stream.getbyte
               if next_byte
+                # allowed: caller-supplied stream; peek-back is optional
                 stream.ungetbyte(next_byte) if stream.respond_to?(:ungetbyte)
                 raise Omnizip::DecompressionError,
                       "LZMA_Alone file has more compressed data than expected. The uncompressed size field (#{@uncompressed_size} bytes) appears to be too small."

data/lib/omnizip/algorithms/lzma.rb

@@ -155,6 +155,7 @@ module Omnizip
           decoder_opts[:uncompressed_size] =
             @uncompressed_size
         end
+        # allowed: options is a public parameter; the body needs #key? and #[]
         decoder_opts[:uncompressed_size] ||= options[:size] if options.respond_to?(:key?) && options.key?(:size)
 
         decoder = Decoder.new(input_stream, decoder_opts)
@@ -174,6 +175,7 @@ module Omnizip
         opts = {}
 
         # Handle Hash-like options
+        # allowed: options is a public parameter; the body needs #[] and #key?
         if options.respond_to?(:[])
           opts[:lc] = options[:lc] if options[:lc]
           opts[:lp] = options[:lp] if options[:lp]
@@ -192,13 +194,16 @@ module Omnizip
         end
 
         # Handle level from both Hash and CompressionOptions
+        # Models::CompressionOptions and SolidEncoder::LzmaOptions both expose
+        # #level and share no ancestor; converting needs them unified first.
+        # allowed: type check deferred, not feature detection
         level = if options.respond_to?(:level)
-                  options.level || 5
-                elsif options.respond_to?(:[]) && options[:level]
-                  options[:level] || 5
-                else
-                  5
+                  options.level
+                # allowed: reader-style options are handled above; this arm needs #[]
+                elsif options.respond_to?(:[])
+                  options[:level]
                 end
+        level ||= 5
 
         opts[:dict_size] ||= dictionary_size_for_level(level)
 
@@ -218,6 +223,7 @@ module Omnizip
         opts = {}
 
         # Handle Hash-like options - pass through all decoder-relevant options
+        # allowed: options is a public parameter; the body needs #key? and #[]
         if options.respond_to?(:key?)
           if options.key?(:sdk_compatible)
             opts[:sdk_compatible] =

data/lib/omnizip/algorithms/lzma2/encoder.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "stringio"
+
 module Omnizip
   module Algorithms
     # LZMA2 encoder - delegates to XzLZMA2Encoder

data/lib/omnizip/algorithms/lzma2/xz_encoder_adapter.rb

@@ -20,6 +20,8 @@
 # FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 # DEALINGS IN THE SOFTWARE.
 
+require "stringio"
+
 module Omnizip
   module Algorithms
     # Adapter for XZ Encoder to work with LZMA2 chunking

data/lib/omnizip/algorithms/lzma2.rb

@@ -20,6 +20,8 @@
 # FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 # DEALINGS IN THE SOFTWARE.
 
+require "stringio"
+
 module Omnizip
   module Algorithms
     # LZMA2 compression algorithm

data/lib/omnizip/algorithms/ppmd7.rb

@@ -20,6 +20,8 @@
 # FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 # DEALINGS IN THE SOFTWARE.
 
+require "stringio"
+
 module Omnizip
   module Algorithms
     # PPMd7 compression algorithm

data/lib/omnizip/algorithms/ppmd_base.rb

@@ -20,6 +20,8 @@
 # FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 # DEALINGS IN THE SOFTWARE.
 
+require "stringio"
+
 module Omnizip
   module Algorithms
     # Base class for PPMd (Prediction by Partial Matching) algorithms

data/lib/omnizip/algorithms/registration.rb

@@ -19,7 +19,7 @@ end
 
 # Now register all algorithms
 Omnizip::AlgorithmRegistry.register(:lzma, Omnizip::Algorithms::LZMA)
-Omnizip::Algorithms::LZMA2.register_algorithm if Omnizip::Algorithms::LZMA2.respond_to?(:register_algorithm)
+Omnizip::Algorithms::LZMA2.register_algorithm
 Omnizip::AlgorithmRegistry.register(:ppmd7, Omnizip::Algorithms::PPMd7)
 Omnizip::AlgorithmRegistry.register(:ppmd8, Omnizip::Algorithms::PPMd8)
 Omnizip::AlgorithmRegistry.register(:bzip2, Omnizip::Algorithms::BZip2)