R2.5.7 previously described a single-mode drain: beforeSleep always
restores the compressed form. With the new declarative model
(compression-master-switch: compression / decompression / off), the
drain mode must follow the master switch:

  - master = compression or off: restore mode (current behavior;
    compressed form preserved across the iteration boundary).
  - master = decompression: permanent-decompress mode (compressed
    buffer released; temp sds installed as the value's val_ptr;
    encoding stays RAW).

The permanent-decompress branch exists because in decompression mode
the operator's intent is "drain the DB". A transient view that
restores the compressed form on every read-touched key would
oscillate the same key between compressed and RAW every iteration —
defeating the drain.

This is the ONLY cross-mechanism dependency between master switch
and transient view (per R2.1's "three orthogonal mechanics" framing
— mechanics 1 and 3 share this one coupling, by design). The
section calls this out explicitly so future readers know it's
deliberate, not accidental.

Both modes share the underlying release-and-decRef cleanup
(releaseCompressedBuffer for the compressed buffer; same
discardTransientEntry helper); only the restore-vs-leave-as-RAW
step differs.

Also updated R2.5.6 to reference the new master-switch + sweeper
combination instead of "COMPRESSION SWEEP direction=decompress" as
the operator's drain affordance.

§2.10.1 INFO fields:
  - Renamed compression_enabled → compression_master_switch (enum,
    reports compression / decompression / off per R2.1.1).
  - Added compression_sweeper (enum, reports enabled / disabled per
    R2.1.2).
  - Added compression_sweeper_interval (seconds, reports the
    R2.1.3 setting).
  - Added compression_sweeper_state (enum, reports the runtime
    sweeper engine state: idle / scanning / sleeping / disabled).
    Distinct from compression_sweeper because the configured switch
    and the runtime engine state aren't always the same — e.g. with
    compression-sweeper=enabled but master=off, the engine is idle
    (no direction); with sweeper=enabled + master=compression
    actively running, the engine is scanning.
  - Existing fields (compression_state, dict counters, sweep
    back-pressure counters, ratio counters) all preserved unchanged.

§2.12 config table:
  - Primary section grew from 5 → 6 knobs:
      • compression-master-switch (enum, default off) — replaces the
        former compression-enabled bool entry
      • compression-sweeper (enum, default disabled) — new
      • compression-threads kept; description annotated to flag
        "only relevant in master=compression" per R2.1.6
      • size bounds and dict-size unchanged
  - Advanced section grew from 11 → 12:
      • compression-sweeper-interval (seconds, default 0) — new
      • all other advanced knobs unchanged

Together these surfaces give the operator the declarative-model
view: declare master state, optionally run the sweeper to converge,
observe progress via the runtime sweeper_state and the back-pressure
counters.

§4.5 COMPRESSION subcommand container:
  - Removed COMPRESSION ENABLE / COMPRESSION DISABLE rows. The new
    3-state master switch (compression / decompression / off) doesn't
    map cleanly to enable/disable verbs; operators use CONFIG SET
    directly. Documented this rationale in the section text plus a
    reference to the precedent (maxmemory-policy, appendfsync are
    other tri-state Valkey configs without verb aliases).
  - Replaced "COMPRESSION SWEEP [direction=compress|decompress]" with
    "COMPRESSION SWEEP FORCE" (R2.1.4): direction is implicit from
    the master switch's current state; the FORCE keyword indicates
    it bypasses both the sweeper-enabled config and the periodic
    timer to do an immediate one-shot pass.
  - Kept all other rows unchanged (TRAIN, STATUS, DICT
    LIST/EXPORT/IMPORT/DROP, HELP).

§1.3, §2.6, §7 cleanup of stale compression-enabled / SWEEP refs:
  - §1.3 Goals: "single master switch (compression-master-switch)
    and zero fixed cost when set to off".
  - R2.6.2 / R2.6.3 / R2.6.4 / R2.6.8: master-switch enum vocabulary.
    R2.6.2 covers "master ∈ {compression, off}" (load-keep-compressed
    path). R2.6.3 covers "master == decompression" (load-and-drain
    path). R2.6.4 references the master-switch config as the
    reject-on-corruption gate. R2.6.8 (full-sync RDB always
    uncompressed) phrased against the new enum.
  - R2.3.3 (dict-cap unblock paths): now references master-switch
    + sweeper for drain, and DICT DROP for explicit retirement.
  - §4.4 step 7 (cap interaction): same updates.
  - §2.10 R2.10.4 back-pressure remediation table: "Manual
    COMPRESSION SWEEP" → "Manual COMPRESSION SWEEP FORCE".
  - §7.1 transparency-mode test config: --compression-master-switch
    compression + --compression-sweeper enabled (replaces the
    --compression-enabled yes line).
  - §7.2 persistence test description: "load with
    compression-master-switch decompression".
  - §7.3 perf scenario: compares "off" vs "compression".
  - §7.5 benchmark driver: same.

After these changes the doc has zero remaining references to
compression-enabled or to bare COMPRESSION SWEEP (without FORCE).
The legacy command names appear only in the §4.5 sentence that
explicitly documents their absence in v1.

…pression-active-sweeper

Two corrections from PR-B review:

1. R2.1.5 retire policy. Original PR-B text auto-retired the active
   dict on both 'compression → decompression' AND 'compression → off'.
   The latter contradicts the 'off freezes the DB compression state'
   semantic — retiring the dict starts it draining toward eventual
   free, which is not 'frozen'. Corrected to retire ONLY on
   transitions INTO 'decompression' (from 'compression' or from
   'off').

   New rule: retire the active dict on any transition INTO
   'decompression'. All other transitions leave the registry
   untouched. Specifically:

     - compression → decompression: retire active dict (drain mode)
     - off         → decompression: retire active dict if there
       happens to be one (drain mode)
     - compression → off: NO retire. State frozen. Operator can
       manually reclaim via COMPRESSION DICT DROP <id> if desired.
     - decompression → off: no action; active was already retired
       on the prior transition.
     - off → compression: no retire; reuse existing active dict if
       any (no retraining).
     - decompression → compression: no retire; system enters
       R2.1.7 third state until a new dict is trained.

   Effect: master=off truly freezes the registry; the dict stays
   ACTIVE and ready to resume compression if the operator flips
   back. Memory cost is bounded (~200 KB raw + digested) and
   operator-recoverable.

2. Rename compression-sweeper → compression-active-sweeper.
   Picks up Valkey's existing 'active-X' prefix convention for
   background-engine configs (matches `activedefrag`,
   `active-expire-effort`). Operator reading
   `compression-active-sweeper enabled` immediately recognizes
   this as the same family of automated background workers.

   Affected names:
     - compression-sweeper          → compression-active-sweeper
     - compression-sweeper-interval → compression-active-sweeper-interval
     - compression_sweeper          → compression_active_sweeper (INFO)
     - compression_sweeper_interval → compression_active_sweeper_interval
     - compression_sweeper_state    → compression_active_sweeper_state

   Updated across §2.1, §2.3, §2.5, §2.10, §2.12, §3, §4.4, §4.5,
   §7.1 — every config-name and INFO-field reference. The English
   word 'sweeper' is preserved in prose where it refers to the
   engine concept (not the config-name identifier).

Three companion docs updated alongside detailed-design.md (which
landed earlier in this PR):

idea-honing.md:
  - Added a top-level Status note (2026-06-14) pointing readers to
    detailed-design.md as the source of truth, with explicit
    callouts for Q5 (master switch model — superseded by the
    declarative 3-state model) and Q5's operator-surface corollary
    (COMPRESSION ENABLE/DISABLE and COMPRESSION SWEEP direction=...
    are NOT part of v1).
  - Q1–Q4, Q6–Q16 are preserved as the historical walkthrough
    audit trail. Their decisions still hold under the current
    design (the inline "superseded by review" annotations from the
    original walkthrough remain).
  - Q3's body uses old-vocabulary 'compression-enabled no' but the
    decision (transparently decompress on load when the feature is
    off) is still in force; preserved as historical Q&A. The header
    note covers the vocabulary shift.

summary.md:
  - Activation row: "Opt-in via compression-enabled yes" replaced
    with the new 3-state declarative model description.
  - PR #15 read-hot-gap historical bullet: operator-recovery
    affordance updated from "COMPRESSION SWEEP direction=decompress"
    to the current model: "CONFIG SET compression-master-switch
    decompression + compression-active-sweeper enabled".
  - All other historical bullets preserved unchanged.

implementation/plan.md:
  - S2.9 description rewritten as "Master switch + sweeper
    (declarative model)" — describes the full declarative-model
    implementation (3-state master-switch enum + active-sweeper
    enum + interval + auto-retire on transitions into
    decompression).
  - The §4.5-style command-tree mention rewritten:
    COMPRESSION SWEEP [ASYNC] → COMPRESSION SWEEP FORCE.
  - S3.3 mention updated: compression-enabled → compression-master-
    switch.
  - Phase 1 gate criterion updated: compression-enabled yes →
    compression-master-switch compression + compression-active-
    sweeper enabled.

detailed-design.md is the source of truth; these companion docs
now describe the same model consistently. DESIGN_TODO.md is not
edited — its 31 walkthrough threads pre-date the master-switch
redesign and their resolutions still hold (e.g., R2.6.8 full-sync
RDB uncompressed, the eligibility-predicate revisions, the
COW-invariant audit, the §7.5 benchmark suite).