Summary

Docs-only PR — adds R2.8.4 (maxmemory ↔ compression interaction prose) + a stickiness paragraph in R2.5.7. No code change. Lands as Topic-1 from implementation/plan.md, scheduled to follow Topic-2 PR-B so the prose could revisit whether anything new from PR-B's stress test justifies an additional metric.

What changes

design/detailed-design.md

R2.8.4 — Savings are workload-dependent; existing observability is sufficient. New requirement under §2.8 Memory accounting. Three sub-points:

1. The same maxmemory yields a wide range of effective dataset capacity:
   • Compressible content → capacity grows by 1/ratio.
   • Incompressible content → unchanged minus per-value header (~16 B/key) and fixed pool overhead.
2. Eviction interaction. Per R2.8.1 the sampler/MEMORY USAGE see compressed footprints. Eviction triggers at maxmemory measured in compressed bytes; victim selection by LRU/LFU is unchanged (per-key compression-ratio asymmetry doesn't bias which key is picked); evicted_keys (existing) is the canonical signal.
3. Decompress-mode drain memory growth. Flipping compression-master-switch decompression progressively reverts values to RAW (R2.5.7's permanent-decompress mode + sweeper). used_memory grows toward the no-compression baseline. Operators with active maxmemory should ensure headroom before flipping; otherwise the drain may trigger eviction.

R2.5.7 — stickiness paragraph. Added inline (cross-referenced from R2.5.6). A value permanently decompressed — by drain-mode or by a write-path mutation through compressionPermanentlyDecompress — stays RAW until one of:

• The sweeper visits the key on a subsequent tick under master=compression and the eligibility predicate (R2.2) admits it. The compression-min-idle-seconds gate means a freshly-mutated value waits one idle window before re-compressing — by design, to avoid churning the worker pool on hot keys.
• The key is evicted, expired, or deleted — the stickiness question becomes moot.

No immediate auto-recompress path on permanent-decompress: re-compressing on every mutation would either churn the worker pool or compete for main-thread CPU; the sweep's pacing (compression-sweep-max-cpu-pct) bounds the re-compress overhead globally.

implementation/plan.md

• Topic-2 PR-B marked complete ([x]). Notes the eventual merge at unstable@7013e370b via fixup PR Ikolomi/dict import #35 — PR [Topic-2 PR-B] compression-stress.tcl integration tests + strEncoding fix #34 inadvertently merged into the now-stale ikolomi/dict-import base instead of unstable, so the change set was re-landed via Ikolomi/dict import #35.
• Topic-1 marked complete ([x]) — lands via this same PR.

Decision-record: no new metric introduced for v1

A "compression headroom" metric (or some equivalent of "effective uncompressed capacity") was considered after Topic-2 PR-B's stress test landed and rejected. Reasoning:

• The existing INFO surface already lets operators reason about workload-dependent capacity:
  • used_memory (the standard one)
  • compression_ratio and compression_live_ratio_10m
  • compression_net_saved_bytes
  • compression_compressed_objects
  • compression_total_uncompressed_bytes / compression_total_compressed_bytes
  • evicted_keys (existing)
  • planned compression_transient_view_capped_total (S4.1, R2.5.7) for cap-fallback observability
• PR-B's stress test surfaced no observation that would justify a new metric.

Revisit after S5.x benchmark scenarios run if a specific operator-facing gap surfaces.

Verification

Docs-only — no code change. git -P diff --stat shows 2 files, +17 / -2 lines (15 new lines in detailed-design.md, 2 plan.md edits + 2 lines).

CI's lint/clang-format/etc. should be unaffected.