update CHANGELOG

Author: skyler-ruiter

CHANGELOG.md

@@ -44,6 +44,9 @@ Version numbers follow [Semantic Versioning](https://semver.org/).
 - **`examples/presets/quantizer_lorenzo_bitpack.toml` had never been runnable.** It specified `nbits = 12`, which is not a power of two, so loading it threw. The pipeline was also mis-specified: `Lorenzo` emits *signed* residuals, and reinterpreting those as `uint32` puts every negative value near 2^32, so bit-packing them is a no-op no matter what `nbits` is. Inserted the missing `Zigzag` stage between `Lorenzo` and `Bitpack` and set `nbits = 16`. Now round-trips at 2.0x on CLDHGH (3600x1800) and vortex (128^3), PSNR 64.77 dB.
 
 ### Added
+- **`Stage::getRunNotes()` — a channel for "what this stage actually did", when it differs from what was configured in a way that affects comparability.** Returns short stable tokens (not prose) meant to land in a benchmark row and be grouped on; empty by default, so a stage that never surprises its caller implements nothing. The motivating case is `HuffmanStage<T>`, which overrides it to report `"huffman_adaptive_fallback"` once a `PerBlock`/`Fixed` build has fallen back to an Adaptive book because the histogram drove a symbol past the 27-bit code field. The fallback is correct — it does not relax the error bound, and `getBookSource()` deliberately keeps reporting what was *asked for* — but a field encoded with a different codebook is not compression-ratio comparable to one that was not, and until now nothing but a log line recorded that. `Pipeline::collectRunNotes()` aggregates over the stages that ran, keyed by stage name, omitting stages with nothing to report. Surfaced by `fzgmod-cli --report-json` as a `run_notes` block, itself omitted entirely when empty so the common case costs no bytes and an absent key reads as "nothing surprising happened". Observed live on 6 of 422 FZGM rows in a full-corpus sweep — rare enough to be invisible without the field, frequent enough to distort a ratio table.
+- **`--no-coloring` CLI flag and `coloring` TOML key**, disabling liveness-driven buffer aliasing under PREALLOCATE. Exists for the peak-memory ablation: with coloring off the pool peak becomes the sum of worst-case per-stage output bounds, which is what a framework that cannot know real extents would have to reserve. Measured on `pfpl.toml` over CESM `CLDHGH`: 217.37 MB colored against 269.25 MB uncolored, a 19.3 % reduction; `cusz.toml` shows 0 %, a genuine zero-alias topology rather than an inert flag, and the spread across presets is what shows the mechanism performs real liveness analysis rather than applying a constant discount. The TOML key is read *after* `memory_strategy` and emitted by `saveConfig()` only when non-default. `Pipeline::isColoringRequested()` reports what was asked for, as distinct from `isColoringEnabled()`, which reports whether the DAG found anything to alias — a benchmark row needs the former, so both arms of an ablation stay identifiable even where coloring saves nothing.
+- **`coloring` echoed in the `--report-json` config block**, resolved from either the CLI flag or the TOML key. Filled from the live `Pipeline` wherever one exists; the standalone decompress path keeps the CLI-flag default, since it runs through the static `Pipeline::decompressFromFile()` and owns no queryable object — and neither field is meaningful for a decompress, the Huffman fallback being an encode-side event.
 - **`HuffmanStage<T>` encode-path diagnostics — `getLastUsedFineEncode()` and `getLastMaxCodeLen()`.** `setEncodeMode(Fine)` is a request, not a guarantee: the fine kernel falls back to the coarse path whenever the book holds a code longer than 8 bits, and nothing observable distinguished the two, so a `Fine` pipeline could run coarse for its entire life while being benchmarked as fine. `getLastUsedFineEncode()` reports which path the last forward call actually took; `getLastMaxCodeLen()` reports the longest code in the book it used, in both modes, since that is what says whether switching to `Fine` would take effect at all. A fallback also emits one `FZ_LOG(WARN)`, re-armed only when the code length changes so a resident `Fixed`/`Adaptive` book does not warn per call. Test HF34.
 - **`HuffmanEncodeMode::Fine` is now documented as experimental**, and references promoting it elsewhere (the `cusz.toml` preset, the `GPU_ZSTD_HUF_FINE` toggle in `examples/gpu_zstd.cpp`, the stage card, the execution-flow narrative) are removed — it was selected in a shipped preset while silently running coarse. `Coarse` is the only supported path. Relatedly, **CUDA Graph capture for this stage is dropped as a goal**: it would require device-side `phf_header` assembly and a device-side merge, and graph capture has not shown a measurable benefit elsewhere in the library.
 - Measuring with these makes a design limit explicit: **`Fine` does not engage on realistic scientific data.** Across CESM-ATM `CLDHGH`/`CLDLOW`/`FLDSC`/`PRECT`/`TS` at `eb` `1e-2 … 1e-5` through `LorenzoQuant -> Huffman` (bklen 1024, radius 512), the longest code is 12–24 bits in all 20 cells — never ≤ 8. The barrier is structural, not a tuning matter: an 8-bit ceiling admits at most 256 codewords by Kraft's inequality, and the quantized fields carry 322–1025 distinct symbols at all but the coarsest bound. Where a ≤ 8-bit code is even constructible, package-merge puts its cost at +1.8% to +14.6% bits/symbol. **Restricting to ≤ 16 bits instead costs at most +0.31% across the same cells and is always constructible**, so a 2x16-bit shard geometry — rather than length-limiting to 8 — is the change that would make the fine path reachable.