feat(io-compression): add the three streams' ZLibCompressionOptions constructors (#2150)

Rule-14 sweep. The recorded gate was a classification -- "public surface
addition; needs approval" -- and this repository's own design record already
contradicted it: SystemIOCompressionNamespaceReviewPlan.md section 7 lists
#2150 as signature "new ctors", vtable --, layout --, noexcept --, result
"additive". That is the #1980-G-1 and #1997-A-1 shape, both of which landed
as ordinary SA-5 work.

The one substantive claim is false and is now asserted rather than argued. A
new overload can change an existing call only if some argument binds to both
parameter types. CompressionMode is a scoped enumeration and
ZLibCompressionOptions has no converting constructor, so nothing converts to
both -- pinned, so the claim must be re-made if either fact changes. Adding
mangled symbols breaks nothing: no existing symbol was removed or changed.

All three streams gain (Stream*, const ZLibCompressionOptions&, bool = false),
implying Compress as .NET's does. Level, strategy and window log all reach
zlib; memLevel follows .NET's rule of 7 at quality 0, otherwise 8.

The format arithmetic went from three copies to one, not four. Each encoder
carried its own in an anonymous namespace and the streams had none, so
Detail::ResolveWindowBits is now shared and the encoders delegate to it -- a
net removal, proven behaviour-preserving by all 103 pre-existing cases passing
unchanged. Two asymmetries are transcribed rather than smoothed: Deflate and
GZip clamp the window log to 9 and ZLib deliberately does not, and the sign
and offset are the container.

Six mutations, all caught. M3 only after a pin was added: every end-to-end
case used a window log of 9 or 15 and never exercised the one input that
separates clamping from not clamping. Asserting the resolver directly was
necessary rather than convenient -- classic zlib upgrades windowBits 8 to 9
internally, so no end-to-end test could discriminate it. M6 was invalid as
first written (-Werror on an orphaned constexpr) and was reformulated rather
than counted.

The compile-time absence pin is inverted in place, not deleted. Downstream
measured: 0 sites in cna, 0 in mobile-eggbert.

Gate: 17,444 run, 17,444 passed, 0 failed, 0 skipped across 38 executables
(+10 on 17,434; SharpRuntimeTests_IO_Compression 103 -> 113; no other
executable moved). Module graph unchanged at 41/93.

Author: robertvokac

CLAUDE.md

@@ -0,0 +1,132 @@
+<!-- SPDX-License-Identifier: MIT -->
+<!-- Copyright (c) Robert Vokac and contributors -->
+
+# Migration — the three compression streams gained their options constructors (ticket #2150)
+
+*2026-08-19.* `System::IO::Compression::DeflateStream`, `GZipStream` and `ZLibStream` each gained
+
+```cpp
+Stream(System::IO::Stream* stream, const ZLibCompressionOptions& options, bool leaveOpen = false);
+```
+
+matching .NET's `(Stream, ZLibCompressionOptions, bool)` constructor on all three types.
+
+**Purely additive.** Nothing that compiled before compiles differently, no existing call changes
+meaning, no symbol changed, and no object grew. Landed under `docs/StandingApprovals.md` **SA-5**.
+
+---
+
+## 1. The ticket's classification was wrong, and the repository's own record already said so
+
+#2150 was recorded as *"blocked — public surface addition, approval required"*, on the grounds
+that *"new overloads change source overload resolution and add mangled symbols"*.
+
+**The design record already contradicted that.** `docs/SystemIOCompressionNamespaceReviewPlan.md`
+§7 lists #2150 as: signature *new ctors*, vtable —, layout —, `noexcept` —, accepted input —,
+observable result **additive**.
+
+**And the overload-resolution claim is false here, measurably.** A new overload can change the
+meaning of an existing call only if some argument can bind to both. Two facts prevent that:
+
+| Fact | Consequence |
+|---|---|
+| `CompressionMode` is a **scoped** enumeration | no integer, `bool` or other enum converts to it, and it converts to nothing |
+| `ZLibCompressionOptions` has **no converting constructor** — only a defaulted default one | nothing implicitly converts *to* it |
+
+With no type convertible to both parameter types, no existing call can rebind and no new call can
+bind to the old overload. This is asserted, not argued, by
+`Decl2150_TheAdditionCannotRebindAnExistingCall` — and if either fact stops holding, that test
+fails and the additive claim must be re-made.
+
+*Adding* mangled symbols breaks nothing: no existing symbol was removed or changed, so an
+already-linked consumer is unaffected and a recompiling one sees only new declarations.
+
+This is the same shape as #1980's G-1 and #1997's A-1 earlier in this programme: a sub-item whose
+own record calls it additive is ordinary SA-5 work.
+
+## 2. What the constructor does
+
+It implies **`CompressionMode::Compress`** — .NET's options overload carries no mode, for the
+same reason its `CompressionLevel` overloads are commented *"Implies mode = Compress"*: every
+option the type holds describes compression.
+
+Every option is honoured:
+
+| Option | Becomes |
+|---|---|
+| `CompressionLevel` | zlib's `level` |
+| `CompressionStrategy` | zlib's `strategy`, via the shared `Detail::ResolveZLibStrategy` |
+| `WindowLog` | zlib's `windowBits`, via the shared `Detail::ResolveWindowBits` |
+| *(derived from the level)* | zlib's `memLevel` — **7** at quality 0, otherwise **8**, as .NET does |
+
+## 3. One definition of the format arithmetic, not four
+
+`Detail::ResolveWindowBits(windowLog, CompressionFormat)` and `Detail::ResolveDeflateMemLevel`
+are new, and they are transcribed from .NET's `CompressionFormatHelper.ResolveWindowBits`
+(`CompressionFormat.cs:30-48`) and `DeflateEncoder` (`DeflateEncoder.cs:75-77, 95-97`).
+
+Before this ticket, each of the three **encoders** carried its own copy of the format arithmetic
+in an anonymous namespace, and the three **streams** had none — because they had no options
+constructor to need one. Rather than add three more copies, the three encoders now delegate to
+the shared resolver too. That is a net removal, and it is proven behaviour-preserving: all 103
+pre-existing `SharpRuntimeTests_IO_Compression` cases pass unchanged.
+
+**Two asymmetries are transcribed rather than smoothed away**, and both are pinned:
+
+1. **Deflate and GZip clamp the window log to a minimum of 9; ZLib does not.** .NET's own comment
+   gives the reason — *"zlib-ng rejects windowBits 8 for raw deflate and gzip; classic zlib
+   silently upgrades to 9"* — so the clamp makes the two zlib implementations agree. A resolver
+   that clamped uniformly would change what a `WindowLog` of 8 means for `ZLibStream`.
+2. **The sign and offset are the container**: raw deflate is negative, zlib positive, gzip
+   positive plus 16.
+
+## 4. Evidence
+
+Six mutations, **all caught**:
+
+| Mutation | Caught by |
+|---|---|
+| M1 — the stream constructor drops the strategy | `Fix2150_TheStrategyReachesZlibInAllThreeStreams` |
+| M2 — the window log is ignored and the default used | `Fix2150_TheWindowLogReachesZlibInAllThreeStreams` |
+| M3 — the ZLib arm clamps to 9 as well | `Fix2150_ResolveWindowBitsTranscribesBothAsymmetries` — **only after that test was added**, see below |
+| M4 — the deflate window-bits sign is lost | six cases, four of them **pre-existing** |
+| M5 — the gzip `+16` offset is lost | five cases, three of them **pre-existing** |
+| M6 — the `memLevel` boundary moves | `Fix2150_ResolveDeflateMemLevelIsSevenOnlyAtQualityZero` |
+
+**M3 is the one worth recording.** It went uncaught at first because every end-to-end case used a
+`WindowLog` of 9 or 15, so the single input that distinguishes clamping from not clamping — a
+`WindowLog` of 8 — was never exercised. The fix was to assert the **resolver** directly rather
+than to hunt for the difference in emitted bytes, and that is not merely more convenient: classic
+zlib silently upgrades a `windowBits` of 8 to 9 internally, so an end-to-end test could not have
+discriminated this reliably at all.
+
+M6 was invalid as first written — removing the quality-0 arm left a `constexpr` unused and
+`-Werror` rejected it — and was reformulated (moving the boundary to `<= 1`) rather than counted.
+
+Gate: **17,444 run, 17,444 passed, 0 failed, 0 skipped** across 38 executables — `+10` on 17,434,
+exactly the ten new cases (`SharpRuntimeTests_IO_Compression` 103 → 113). No other executable
+moved. Module graph
+unchanged at 41/93.
+
+## 5. To use it
+
+```cpp
+ZLibCompressionOptions options;
+options.setCompressionLevelProperty(9);
+options.setCompressionStrategyProperty(ZLibCompressionStrategy::RunLengthEncoding);
+
+MemoryStream sink;
+GZipStream out(&sink, options, /*leaveOpen=*/true);
+out.Write(data.data(), 0, static_cast<intcs>(data.size()));
+out.Close();
+```
+
+Nothing needs migrating. The `(Stream*, CompressionMode, bool)` constructor is untouched and
+still the only way to build a **decompressing** stream.
+
+## 6. Downstream, measured
+
+Per SA-2 condition 5 — recorded although SA-2 is not the approval this landed under, because an
+addition to a public type deserves the measurement anyway: `DeflateStream`, `GZipStream`,
+`ZLibStream` and `ZLibCompressionOptions` appear in **zero** places in `cna` and **zero** in
+`mobile-eggbert`. Neither repository was modified.

docs/Migration-CompressionStreamOptionsConstructors.md

@@ -219,4 +219,45 @@ namespace System::IO::Compression::Detail {
      */
     [[nodiscard]] intcs ResolveZLibStrategy(ZLibCompressionStrategy strategy);
 
+    /**
+     * @brief The three zlib container formats this component encodes.
+     *
+     * C++ counterpart of .NET's internal `System.IO.Compression.CompressionFormat`
+     * (`CompressionFormat.cs:9-17`). It exists for the same reason: window bits are the one
+     * parameter whose meaning depends on the container, so resolving them needs the format as
+     * an argument rather than three near-identical local functions.
+     */
+    enum class CompressionFormat { Deflate, ZLib, GZip };
+
+    /**
+     * @brief Resolves a `WindowLog` (8..15, or -1 for the default) to zlib's `windowBits`.
+     *
+     * Transcribed from .NET's `CompressionFormatHelper.ResolveWindowBits`
+     * (`CompressionFormat.cs:30-48`), including both of its asymmetries:
+     *
+     * * `-1` resolves to **15**, the default window log;
+     * * **Deflate and GZip clamp to a minimum of 9, and ZLib does not.** .NET's own comment
+     *   gives the reason — *"zlib-ng rejects windowBits 8 for raw deflate and gzip; classic zlib
+     *   silently upgrades to 9"* — so the clamp reproduces classic zlib's behaviour on both
+     *   implementations. A resolver that clamped uniformly would change what a `WindowLog` of 8
+     *   means for `ZLibStream`.
+     *
+     * The sign and offset are then the container: raw deflate is negative, zlib is positive,
+     * gzip is positive plus 16.
+     *
+     * Defined once here so the three encoders and the three stream types share one definition.
+     * Before ticket #2150 each encoder carried its own copy in an anonymous namespace, and the
+     * streams had none at all because they had no options constructor to need one.
+     */
+    [[nodiscard]] intcs ResolveWindowBits(intcs windowLog, CompressionFormat format);
+
+    /**
+     * @brief Resolves the zlib `memLevel` for a compression quality.
+     *
+     * Transcribed from .NET's `DeflateEncoder` (`DeflateEncoder.cs:75-77, 95-97`): quality 0
+     * ("no compression") uses memLevel **7**, every other quality uses **8**. The rule is the
+     * same for all three containers, so it takes no format.
+     */
+    [[nodiscard]] intcs ResolveDeflateMemLevel(intcs quality);
+
 } // namespace System::IO::Compression::Detail

modules/io-compression/include/System/IO/Compression/CompressionArgumentValidation.hpp

@@ -4,6 +4,7 @@
 #pragma once
 #include "System/IO/Stream.hpp"
 #include "System/IO/Compression/CompressionMode.hpp"
+#include "System/IO/Compression/ZLibCompressionOptions.hpp"
 #include <memory>
 
 // Note: .NET DeflateStream uses raw DEFLATE (no gzip wrapper), unlike GZipStream.
@@ -52,6 +53,36 @@ namespace System::IO::Compression {
          */
         DeflateStream(Stream* stream, CompressionMode mode, bool leaveOpen = false);
 
+        /**
+         * @brief Constructs a compressing DeflateStream using the given compression options.
+         *
+         * C++ counterpart of .NET's `DeflateStream(Stream, ZLibCompressionOptions, bool)`. **This
+         * constructor implies `CompressionMode::Compress`** — .NET's own comment above the
+         * `CompressionLevel` overloads says *"Implies mode = Compress"*, and the options
+         * overload has no mode parameter for the same reason: every option it carries describes
+         * compression.
+         *
+         * The options are honoured in full: `CompressionLevel` becomes zlib's level,
+         * `CompressionStrategy` its strategy, and `WindowLog` its window size, resolved for
+         * raw deflate (no header or trailer) by `Detail::ResolveWindowBits`. `memLevel` follows .NET's rule — 7 at
+         * quality 0, otherwise 8.
+         *
+         * @param stream    The stream to which compressed data is written.
+         * @param options   The compression options. Validated by `ZLibCompressionOptions`'
+         *                  own setters, so an out-of-range value cannot reach here.
+         * @param leaveOpen When @c true the inner stream is not closed on destruction.
+         *
+         * @throws System::ArgumentNullException if @p stream is null.
+         * @throws System::IO::IOException if zlib initialisation fails.
+         *
+         * @note Ticket **#2150**. Adding this overload cannot change the meaning of any existing
+         * call: `CompressionMode` is a scoped enumeration and `ZLibCompressionOptions` has no
+         * converting constructor, so no argument can bind to both this and the
+         * `(Stream*, CompressionMode, bool)` overload. That is asserted, not assumed, by
+         * `CompressionOptionsConstructorTests.Decl2150_TheAdditionCannotRebindAnExistingCall`.
+         */
+        DeflateStream(Stream* stream, const ZLibCompressionOptions& options, bool leaveOpen = false);
+
         ~DeflateStream() override;
 
         /** @brief Returns @c true when mode is Decompress. */

modules/io-compression/include/System/IO/Compression/DeflateStream.hpp

@@ -4,6 +4,7 @@
 #pragma once
 #include "System/IO/Stream.hpp"
 #include "System/IO/Compression/CompressionMode.hpp"
+#include "System/IO/Compression/ZLibCompressionOptions.hpp"
 #include <memory>
 
 namespace System::IO::Compression {
@@ -48,6 +49,36 @@ namespace System::IO::Compression {
          */
         GZipStream(Stream* stream, CompressionMode mode, bool leaveOpen = false);
 
+        /**
+         * @brief Constructs a compressing GZipStream using the given compression options.
+         *
+         * C++ counterpart of .NET's `GZipStream(Stream, ZLibCompressionOptions, bool)`. **This
+         * constructor implies `CompressionMode::Compress`** — .NET's own comment above the
+         * `CompressionLevel` overloads says *"Implies mode = Compress"*, and the options
+         * overload has no mode parameter for the same reason: every option it carries describes
+         * compression.
+         *
+         * The options are honoured in full: `CompressionLevel` becomes zlib's level,
+         * `CompressionStrategy` its strategy, and `WindowLog` its window size, resolved for
+         * the gzip container by `Detail::ResolveWindowBits`. `memLevel` follows .NET's rule — 7 at
+         * quality 0, otherwise 8.
+         *
+         * @param stream    The stream to which compressed data is written.
+         * @param options   The compression options. Validated by `ZLibCompressionOptions`'
+         *                  own setters, so an out-of-range value cannot reach here.
+         * @param leaveOpen When @c true the inner stream is not closed on destruction.
+         *
+         * @throws System::ArgumentNullException if @p stream is null.
+         * @throws System::IO::IOException if zlib initialisation fails.
+         *
+         * @note Ticket **#2150**. Adding this overload cannot change the meaning of any existing
+         * call: `CompressionMode` is a scoped enumeration and `ZLibCompressionOptions` has no
+         * converting constructor, so no argument can bind to both this and the
+         * `(Stream*, CompressionMode, bool)` overload. That is asserted, not assumed, by
+         * `CompressionOptionsConstructorTests.Decl2150_TheAdditionCannotRebindAnExistingCall`.
+         */
+        GZipStream(Stream* stream, const ZLibCompressionOptions& options, bool leaveOpen = false);
+
         ~GZipStream() override;
 
         /** @brief Returns @c true when mode is Decompress. */

modules/io-compression/include/System/IO/Compression/GZipStream.hpp

@@ -4,6 +4,7 @@
 #pragma once
 #include "System/IO/Stream.hpp"
 #include "System/IO/Compression/CompressionMode.hpp"
+#include "System/IO/Compression/ZLibCompressionOptions.hpp"
 #include <memory>
 
 namespace System::IO::Compression {
@@ -48,6 +49,36 @@ namespace System::IO::Compression {
          */
         ZLibStream(Stream* stream, CompressionMode mode, bool leaveOpen = false);
 
+        /**
+         * @brief Constructs a compressing ZLibStream using the given compression options.
+         *
+         * C++ counterpart of .NET's `ZLibStream(Stream, ZLibCompressionOptions, bool)`. **This
+         * constructor implies `CompressionMode::Compress`** — .NET's own comment above the
+         * `CompressionLevel` overloads says *"Implies mode = Compress"*, and the options
+         * overload has no mode parameter for the same reason: every option it carries describes
+         * compression.
+         *
+         * The options are honoured in full: `CompressionLevel` becomes zlib's level,
+         * `CompressionStrategy` its strategy, and `WindowLog` its window size, resolved for
+         * the zlib container by `Detail::ResolveWindowBits`. `memLevel` follows .NET's rule — 7 at
+         * quality 0, otherwise 8.
+         *
+         * @param stream    The stream to which compressed data is written.
+         * @param options   The compression options. Validated by `ZLibCompressionOptions`'
+         *                  own setters, so an out-of-range value cannot reach here.
+         * @param leaveOpen When @c true the inner stream is not closed on destruction.
+         *
+         * @throws System::ArgumentNullException if @p stream is null.
+         * @throws System::IO::IOException if zlib initialisation fails.
+         *
+         * @note Ticket **#2150**. Adding this overload cannot change the meaning of any existing
+         * call: `CompressionMode` is a scoped enumeration and `ZLibCompressionOptions` has no
+         * converting constructor, so no argument can bind to both this and the
+         * `(Stream*, CompressionMode, bool)` overload. That is asserted, not assumed, by
+         * `CompressionOptionsConstructorTests.Decl2150_TheAdditionCannotRebindAnExistingCall`.
+         */
+        ZLibStream(Stream* stream, const ZLibCompressionOptions& options, bool leaveOpen = false);
+
         ~ZLibStream() override;
 
         /** @brief Returns @c true when mode is Decompress. */

modules/io-compression/include/System/IO/Compression/ZLibStream.hpp

@@ -1,6 +1,7 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) Robert Vokac and contributors
 // Portions based on .NET runtime API (MIT License, Copyright .NET Foundation and Contributors)
+#include <algorithm>
 #include "System/IO/Compression/CompressionArgumentValidation.hpp"
 #include "System/ArgumentException.hpp"
 #include "System/ArgumentNullException.hpp"
@@ -61,4 +62,30 @@ namespace System::IO::Compression::Detail {
         throw System::ArgumentOutOfRangeException("strategy", "Value must be between Default and Fixed.");
     }
 
+    namespace {
+        // ZLibCompressionOptions publishes these as MinWindowLog/MaxWindowLog/DefaultWindowLog;
+        // they are restated locally so this translation unit does not depend on that header for
+        // two integers.
+        constexpr intcs DefaultWindowLog             = 15;
+        constexpr intcs Deflate_DefaultMemLevel      = 8;
+        constexpr intcs Deflate_NoCompressionMemLevel = 7;
+    }
+
+    intcs ResolveWindowBits(intcs windowLog, CompressionFormat format) {
+        if (windowLog == -1) windowLog = DefaultWindowLog;
+        // Deflate and GZip clamp; ZLib deliberately does not. See the header for .NET's reason.
+        if (format != CompressionFormat::ZLib)
+            windowLog = std::max(windowLog, static_cast<intcs>(9));
+        switch (format) {
+            case CompressionFormat::Deflate: return -windowLog;
+            case CompressionFormat::ZLib:    return windowLog;
+            case CompressionFormat::GZip:    return windowLog + 16;
+        }
+        throw System::ArgumentOutOfRangeException("format");
+    }
+
+    intcs ResolveDeflateMemLevel(intcs quality) {
+        return quality == 0 ? Deflate_NoCompressionMemLevel : Deflate_DefaultMemLevel;
+    }
+
 } // namespace System::IO::Compression::Detail

modules/io-compression/src/System/IO/Compression/CompressionArgumentValidation.cpp

@@ -23,10 +23,11 @@ namespace System::IO::Compression {
         constexpr intcs Deflate_DefaultMemLevel = 8;
         constexpr intcs Deflate_NoCompressionMemLevel = 7;
 
+        // #2150 replaced this function's body with the shared resolver. The three encoders each
+        // carried their own copy of the format arithmetic; there is now one definition, in
+        // Detail::ResolveWindowBits, which the three STREAM options constructors also use.
         intcs ResolveDeflateWindowBits(intcs windowLog) {
-            if (windowLog == -1) windowLog = DefaultWindowLog;
-            windowLog = std::max(windowLog, static_cast<intcs>(9));
-            return -windowLog;
+            return Detail::ResolveWindowBits(windowLog, Detail::CompressionFormat::Deflate);
         }
     }