omnizip 0.4.7-x86_64-linux

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

@@ -0,0 +1,237 @@
+# 07 — Replace `respond_to?` with proper typing
+
+Priority: **medium**.
+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.
+
+## 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/` → 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/TODO.refactor/08-spec-doubles.md

@@ -0,0 +1,27 @@
+# 08 — Remove `double()` from specs
+
+Priority: **low** (1 occurrence).
+Status: TODO.
+
+## Rule
+
+> NEVER use `double()` in specs. Use real model instances or lightweight
+  Structs.
+
+## Inventory
+
+| File:Line | Code |
+|---|---|
+| `spec/omnizip/formats/rar/rar5/solid/solid_stream_spec.rb:41` | `stat = double("stat")` |
+
+## Plan
+
+1. Read the spec context to see which `File::Stat` interface the spec
+   exercises.
+2. Replace with `Struct.new(:mtime, :size, :mode, ...).new(...)` or
+   `File::Stat.new(real_path)` if a real file is available.
+
+## Acceptance
+
+- `grep -rn "double(" spec/` returns zero matches.
+- Spec passes.

data/TODO.refactor/09-cli-shared-module.md

@@ -0,0 +1,35 @@
+# 09 — CLI shared module
+
+Priority: **low**.
+Status: TODO.
+
+## Problem
+
+`handle_error` is duplicated verbatim in three Thor classes inside
+`lib/omnizip/cli.rb` (lines 81–84, 312–315, 557–560). `format_bytes`
+(line 562) is a utility that doesn't belong inside the CLI class.
+
+## Plan
+
+1. Create `lib/omnizip/cli/shared.rb` defining:
+   ```ruby
+   module Omnizip
+     class Cli
+       module Shared
+         def handle_error(err)
+           # ...
+         end
+         module_function :format_bytes
+       end
+     end
+   end
+   ```
+2. Each Thor class `include`s `Shared`.
+3. Move `format_bytes` out of the CLI class proper; place it in a
+   `Omnizip::Cli::Formatters` module (or under `Omnizip::Utils::Bytes` if
+   broader use exists).
+
+## Acceptance
+
+- Single definition of `handle_error` and `format_bytes`.
+- CLI specs pass.

data/TODO.refactor/10-format-detector-ocp.md

@@ -0,0 +1,34 @@
+# 10 — FormatDetector OCP
+
+Priority: **medium**.
+Status: TODO.
+
+## Problem
+
+`lib/omnizip/format_detector.rb:112-123` maps format symbols to reader
+classes via a `case` statement. Adding a new format requires modifying
+this method — a clear OCP violation. The `FormatRegistry` already
+registers each format handler; this case statement duplicates that
+knowledge.
+
+## Plan
+
+1. Replace the case statement with a lookup against `FormatRegistry`:
+   ```ruby
+   def reader_for(format)
+     FormatRegistry.get(format) ||
+       raise(UnsupportedFormatError, "No reader for #{format}")
+   end
+   ```
+2. Ensure every format that previously appeared in the case statement is
+   registered in `FormatRegistry` with its reader class.
+3. If a format is detected but its handler hasn't been required yet, the
+   registry lookup must trigger autoload — verify the autoload wiring in
+   `lib/omnizip.rb` makes this work.
+
+## Acceptance
+
+- `lib/omnizip/format_detector.rb` no longer has a format-specific case.
+- All format_detector specs pass.
+- A new format can be added by registering it, with zero edits to
+  FormatDetector.

data/TODO.refactor/11-convenience-decoupling.md

@@ -0,0 +1,38 @@
+# 11 — Convenience module decoupling
+
+Priority: **medium**.
+Status: TODO.
+
+## Problem
+
+`lib/omnizip/convenience.rb` (359 lines) hardcodes `Omnizip::Zip::File`
+in 7 method bodies (lines 45, 87, 112, 149, 175, 207, 227) —
+`compress_file`, `compress_directory`, `extract_archive`,
+`list_archive`, `read_from_archive`, `add_to_archive`,
+`remove_from_archive`. The codebase supports 7z, XZ, tar, gzip, bzip2,
+RAR, but convenience methods are ZIP-only.
+
+## Plan
+
+1. Add a `format:` keyword argument to each convenience method.
+   Default to `:zip` for backward compatibility.
+2. Resolve the format handler via `FormatRegistry.get(format)` and
+   delegate. If the handler doesn't expose the needed operation, raise a
+   clear `UnsupportedFormatError` describing what's missing.
+3. Each format handler (zip, seven_zip, tar, gzip, xz, bzip2) should
+   implement a shared `Handler` interface with `#add_file`,
+   `#add_directory`, `#extract`, `#list`, `#read`, `#remove`. This
+   becomes the contract for being usable from `convenience.rb`.
+
+## Acceptance
+
+- Convenience methods accept `format:` and dispatch via registry.
+- ZIP path remains the default with no behavior change.
+- At least one non-ZIP format (e.g., tar) is wired up end-to-end.
+
+## Scope note
+
+Full format handler interface extraction is large. This pass:
+1. Adds the `format:` keyword with ZIP default.
+2. Wires tar as a second supported format (simplest after zip).
+3. Leaves the remaining formats as documented future work.

data/TODO.refactor/12-thread-safety.md

@@ -0,0 +1,8 @@
+# 12 — Thread safety
+
+Priority: covered by track 01.
+Status: n/a.
+
+The `Registry` base class introduced in track 01 includes `Mutex`-based
+synchronization around mutations (`register`, `reset!`). All migrated
+registries inherit this for free. No standalone work.

data/TODO.refactor/13-lutaml-model-migration.md

@@ -0,0 +1,158 @@
+# 13 — lutaml-model migration
+
+Priority: **medium**.
+Status: DONE for the models that should migrate. The remaining `to_h`
+methods are deliberate — see "Why 17 stay" below.
+
+## Rule
+
+> ALL (de)serialization goes through the framework. Declare attributes
+> with `attribute :name, :type`. Declare wire names with a `mapping do
+> ... end` block. Never write `def to_h` / `def from_h` / `def to_json`
+> / `def from_json` on a model class.
+
+## Result
+
+Six models now inherit `Lutaml::Model::Serializable`:
+
+- `CompressionOptions`, `AlgorithmMetadata` (earlier pass)
+- `ConversionOptions`, `ProgressOptions`, `ETAResult`, `ParallelOptions`
+
+Counts, measured against the tree rather than estimated:
+
+| Metric | Before | After |
+| --- | --- | --- |
+| `grep -rn "def to_h" lib/ \| wc -l` | 21 | 17 |
+| Same under `lib/omnizip/models/` | 10 | 6 |
+| `def to_json` / `from_h` / `from_json` in `lib/` | 0 | 0 |
+
+An earlier version of this document claimed "26 `def to_h` across 22
+files, 2 `def to_json`". Both were wrong; the numbers above are real.
+
+## The symbol-type blocker was not real
+
+This document previously held `ConversionOptions` back pending "lutaml
+symbol-type support". There is nothing to wait for. `:symbol` is a
+built-in type from 0.8.0 on: it is registered in `TYPE_CODES` in
+`lib/lutaml/model/type.rb` and implemented in
+`lib/lutaml/model/type/symbol.rb`. It casts symbols, strings, and nil
+correctly and round-trips through JSON. `ConversionOptions` uses it for
+`source_format`, `target_format`, `compression`, and `filter`.
+
+The gemspec asks for `~> 0.8` because of this. `~> 0.7` also resolved to
+0.8 on a fresh install, but it still admitted 0.7.1 through 0.7.7, where
+`:symbol` is unregistered and `default: -> { detect_cpu_count }` is
+evaluated against the class. Pin a build to 0.7.7 and 25 examples fail.
+
+## Recipe
+
+```ruby
+require "lutaml/model"
+
+class Thing < Lutaml::Model::Serializable
+  attribute :level, :integer, default: 5
+  attribute :name, :string
+
+  key_value do
+    map "level", to: :level, render_default: true, render_nil: true
+    map "name", to: :name, render_default: true, render_nil: true
+  end
+end
+```
+
+`key_value` covers hash, YAML, TOML, and JSON in one declaration.
+
+### Two behaviours that will catch you out
+
+**1. `to_hash` returns String keys.** The hand-rolled `to_h` methods
+returned Symbol keys. These are not interchangeable, and
+`Serializable` does not define `to_h` at all — calling it raises
+`NoMethodError`. Removing `to_h` is a breaking change for any external
+caller.
+
+**2. `render_default: true` alone does not give you a fixed key set.**
+It renders an unassigned default, but still drops a key that was
+explicitly assigned `nil`:
+
+| Mapping | fresh `.new` | after `x.a = nil` |
+| --- | --- | --- |
+| `render_default: true` | `{"a" => 5}` | `{}` |
+| `+ render_nil: true` | `{"a" => 5, "b" => nil}` | `{"a" => nil}` |
+
+Use **both** flags when the old `to_h` emitted every key. Use
+`render_default` alone when it ended in `.compact`. Use neither when
+there are no defaults and nils were dropped. There is no class-level or
+global switch — `render_default:` is per-rule and defaults to `false`.
+
+### Other gotchas
+
+- Lambda defaults (`default: -> { detect_cpu_count }`) are evaluated
+  with `self` bound to the **instance**. A private instance method
+  works; a class method raises `NameError`.
+- `dup` shares the internal `@using_default` hash. With both render
+  flags set this is unobservable, so no `dup` override or
+  `initialize_copy` hook is needed.
+- Unknown keyword arguments to `.new` are silently ignored, where a
+  plain-Ruby `initialize` would raise `ArgumentError`.
+- `self.class.attributes` returns a `Hash{Symbol=>Attribute}`. Iterate
+  it with `each_key`.
+
+## Why 17 `to_h` methods stay
+
+These are computed reports, projections over another object, or
+wire-format builders — not serializations of the receiver's own state.
+Converting them would drop the computed fields or force a second method
+back onto the class. Leave them alone.
+
+| File | Reason |
+| --- | --- |
+| `models/conversion_result.rb` | Three computed fields; drops a stored one |
+| `models/match_result.rb` | Keys don't match attributes; renames and computes |
+| `models/optimization_suggestion.rb` | Computed `priority_score`; ctor validates enums |
+| `models/performance_result.rb` | Computed fields plus `timestamp.iso8601` |
+| `models/profile_report.rb` | Nested computed `summary:`; maps nested results |
+| `models/filter_config.rb` | Emits `:name` for `@name_sym`; binary properties; registry lookups |
+| `formats/rpm/header.rb` | Tag-map projection over a collection |
+| `formats/xar/entry.rb` | XAR XML attributes; octal mode, formatted timestamps |
+| `formats/zip/unix_extra_field.rb` | Emits a constant tag; wire format is manual pack |
+| `metadata/entry_metadata.rb` | Pure delegation; stores no attributes of its own |
+| `metadata/archive_metadata.rb` | Computed aggregates |
+| `profile/compression_profile.rb` | `CustomProfile#to_h` calls `super` on it |
+| `profile/custom_profile.rb` | Inheritance chain over `to_h` |
+| `profile/profile_registry.rb` | Registry projection under a mutex |
+| `progress/operation_progress.rb` | Computed percentages and elapsed time |
+| `link_handler/symbolic_link.rb` | Type discriminator; storage uses `serialize` |
+| `link_handler/hard_link.rb` | Type discriminator; storage uses `serialize` |
+
+Because these stay, `grep "def to_h" lib/` will never reach zero. That
+is the intended end state, not unfinished work.
+
+## Follow-up work
+
+1. **Rename the 17 — DECIDED: deferred to a deliberate major/minor
+   release.** The names below remain the plan if that release
+   happens: `to_report` for the computed ones, `to_tag_map` /
+   `to_attributes` for projections, `to_xml_attributes` / `to_fields`
+   for wire-format builders. Each rename is a public-API break
+   (every one of the 17 is a public class method), so it cannot ship
+   silently in a patch; the 17 staying is the intended end state for
+   now, per "Why 17 stay" above.
+2. **DONE (0.3.28, PR #42).** `apply` fixed in both classes — all
+   three options models now share the tested
+   `Models::AttributeApply` concern, which also delivers (3).
+3. **DONE (0.3.28, PR #42)** — see (2).
+4. **Considered — decided against, with reasons.**
+   - `FilterConfig` is a behavior-heavy domain object, not a
+     serialization model: `filter_instance` reaches into
+     `FilterRegistry`, `id_for_format`/`bcj?`/`delta?` are domain
+     queries, `properties` defaults to a binary String (lutaml's
+     `:string` is UTF-8-oriented, so the attribute would need a
+     custom type), and initialization accepts two alias keys
+     (`:name`/`:name_sym`). Its `to_h` is a projection with no
+     round-trip consumer. Migration would fight the framework to
+     achieve nothing the class needs.
+   - The profile classes are abstract domain objects: subclasses
+     override `suitable_for?`, `apply_to` mutates an options object,
+     five validators run at construction, and `to_h` coexists with
+     `to_s`/`inspect` as display projections. No wire format round
+     trips them. Same verdict.

data/TODO.refactor/14-add-missing-specs.md

@@ -0,0 +1,25 @@
+# 14 — Add missing specs
+
+Priority: **high**.
+Status: TODO.
+
+## Plan
+
+Add or strengthen specs for:
+
+1. `Omnizip::Registry` (new base class from track 01) — register / get /
+   registered? / available / reset! / thread-safety smoke test / custom
+   not-found error.
+2. `Omnizip::Error` hierarchy (track 02) — confirm inheritance and
+   aliases.
+3. `Omnizip::Cli::Shared` (track 09) — `handle_error` and
+   `format_bytes`.
+4. `Omnizip::IO::Source` / `Omnizip::IO::Sink` (track 07) — adapter
+   behavior for String / StringIO / File / Pathname.
+5. Promoted public methods (track 05) — wherever a method moves from
+   private to public, ensure a spec covers its new visibility.
+
+## Acceptance
+
+- All new specs pass.
+- No `double()` introduced.