From 01cca01476ae709bf953ef18e2898dc94025394c Mon Sep 17 00:00:00 2001
From: DavidHLP <lysf15520112973@163.com>
Date: Sun, 26 Jul 2026 00:52:42 +0800
Subject: [PATCH 1/7] fix(observability): add bounded chain timer dimensions

---
 .ai/issues/index.md                           |  29 +++++
 .ai/issues/issue-4.md                         |  73 ++++++++++++
 .../redis/chain/CacheHandlerChainFactory.java |   4 +-
 .../spring/cache/redis/chain/ChainEngine.java |  61 ++++++++--
 .../redis/chain/observer/ChainObserver.java   |  36 +++++-
 .../observer/ChainObserverRegistration.java   |   2 +-
 .../observer/ChainTimerChainObserver.java     | 109 ++++++-----------
 .../cache/redis/chain/ChainEngineTest.java    |  65 +++++++++-
 .../chain/observer/ChainObserverTest.java     | 112 +++++++++++++++---
 wiki/modules/observability.md                 |   9 +-
 10 files changed, 386 insertions(+), 114 deletions(-)
 create mode 100644 .ai/issues/index.md
 create mode 100644 .ai/issues/issue-4.md

diff --git a/.ai/issues/index.md b/.ai/issues/index.md
new file mode 100644
index 00000000..bf6eb0d1
--- /dev/null
+++ b/.ai/issues/index.md
@@ -0,0 +1,29 @@
+# ResiCache Open Issue Ledger
+
+Last synchronized: 2026-07-26
+Repository baseline: `main` @ `75ed279a71b17f227c3170d738eb93e50d876c8a` (`origin/main`, ahead 0 / behind 0)
+GitHub repository: `DavidHLP/ResiCache`
+
+## Execution order
+
+| Order | Issue | Priority | Status | Dependency / triage |
+|---:|---|---|---|---|
+| 1 | [#4](issue-4.md) Per-handler Micrometer tags | P0 observability | INVESTIGATING | Independent and explicitly highest priority |
+| 2 | [#2](issue-2.md) Redis Cluster slot IT | P1 correctness | DISCOVERED | Validates existing production key construction; must use real Cluster |
+| 3 | [#5](issue-5.md) Serialization migration CLI | P1 compatibility | DISCOVERED | Large migration capability; pre-flight probe already exists |
+| 4 | [#3](issue-3.md) JMH module | P1 performance | DISCOVERED | External contributor declared intent on 2026-07-21 but no PR/branch is linked; review after higher-priority work and re-sync before takeover |
+
+## Live GitHub facts
+
+- Open Issues: `#2`, `#3`, `#4`, `#5`.
+- Open PRs: none.
+- Linked closing PRs: none for all four issues.
+- Assignees: none for all four issues.
+- Only active external signal: `Shubh2-0` volunteered for #3 on 2026-07-21; no implementation is currently reviewable.
+
+## Validation gates
+
+- Preserve `testcontainers-bom:1.20.4`; Spring Boot 4.0.0's transitive 1.20.6/docker-java path is incompatible with the target older Docker daemon.
+- Real-Redis acceptance requires all three signals: container startup evidence, target test count > 0, and skipped count = 0.
+- Every implementation receives Standards + Spec independent review before its focused commit.
+- GitHub remote writes remain subject to the session GitHub Write Gate and require an explicit review package and approval.
diff --git a/.ai/issues/issue-4.md b/.ai/issues/issue-4.md
new file mode 100644
index 00000000..7b54962a
--- /dev/null
+++ b/.ai/issues/issue-4.md
@@ -0,0 +1,73 @@
+# Issue #4 — Per-handler Micrometer tags on `resicache.chain.execute`
+
+- **Issue:** https://github.com/DavidHLP/ResiCache/issues/4
+- **Status:** COMMITTED
+- **Priority:** P0 observability
+- **Dependencies:** none
+- **External work:** no assignee, comments, branch, or linked PR
+
+## Current findings
+
+- Current implementation moved the old inline timer from `CacheHandlerChain` into `ChainTimerChainObserver`.
+- `ChainTimerChainObserver` creates one tag-less, lazily cached `Timer`; its scope token contains only chain start nanos.
+- `ChainObserver#afterNode` already receives both the concrete `CacheHandler` and its `HandlerResult`, so it is the natural per-handler/per-decision observation point.
+- Current timer description promises full-chain lifecycle timing. The Issue asks for handler + decision tags; implementation must avoid falsely assigning the same whole-chain duration to every handler.
+- Existing `resicache.handler.fired` already counts handler evaluation and must not be duplicated.
+
+## Acceptance criteria
+
+1. `resicache.chain.execute` is queryable by bounded `handler`, `decision`, and `cacheName` tags.
+2. `handler` comes from the finite installed handler set; `decision` is one of `CONTINUE`, `SKIP_ALL`, `TERMINATE`.
+3. No `redisKey`, user input, exception text, or dynamic ID is used as a tag.
+4. Each timer sample measures the corresponding handler invocation, not an incorrectly duplicated whole-chain duration.
+5. Registry absence remains a no-op and concurrent calls do not share mutable per-call timing state.
+6. Existing fired counter semantics remain unchanged.
+7. Wiki observability documentation matches the final metric semantics.
+
+## Implementation plan
+
+- Refine `ChainTimerChainObserver` to record per-node timing using observer scope that remains per call / per thread-safe invocation.
+- Use Micrometer registration keyed by bounded tag tuple, not one global cached timer.
+- Expand `ChainObserverTest.TimerTests` with decisions, cache names, changing redis keys, and meter-count/cardinality assertions.
+- Update `wiki/modules/observability.md` source references and metric table.
+
+## Files/modules involved
+
+- `src/main/java/io/github/davidhlp/spring/cache/redis/chain/observer/ChainTimerChainObserver.java`
+- `src/main/java/io/github/davidhlp/spring/cache/redis/chain/ChainEngine.java` (read-only unless observer contract cannot express timing)
+- `src/test/java/io/github/davidhlp/spring/cache/redis/chain/observer/ChainObserverTest.java`
+- `wiki/modules/observability.md`
+
+## Tests required
+
+- Targeted unit tests for all three decisions and multiple handlers/cache names.
+- Cardinality test varying only `redisKey` and asserting meter count remains constant.
+- Null-registry no-op.
+- `./mvnw -B -Dtest=ChainObserverTest,CacheHandlerChainFactoryTest test`
+- `./mvnw -B checkstyle:check`
+
+## Validation result
+
+- Java runtime: Temurin/OpenJDK `21.0.2+13` installed user-locally via `vfox` because the session default was Java 17 and system Java 25 broke current Lombok processing.
+- `./mvnw -B -Dtest=ChainObserverTest,ChainEngineTest,CacheHandlerChainFactoryTest test`: `BUILD SUCCESS`; 43 tests, 0 failures, 0 errors, 0 skipped.
+- `./mvnw -B checkstyle:check`: `BUILD SUCCESS`; 0 violations.
+- `git diff --check`: clean.
+
+## Review findings
+
+Independent reviewer jobs failed to yield within the review window and were cancelled; the maintainer process then completed the same frozen Standards + Spec checklist directly against the full diff and all callers/tests.
+
+- **critical/high/medium:** none.
+- **low:** none requiring code changes.
+- Concurrency/resource verdict: per-node state is an immutable token paired by Engine `finally`; no shared mutable `ThreadLocal` or stale stack.
+- Compatibility verdict: existing `beforeNode/afterNode` exception behavior and `resicache.handler.fired` semantics are unchanged; new observer methods are default no-op.
+- Cardinality verdict: only `handler`, three-value `decision`, and configured `cacheName`; varying `redisKey` is explicitly tested not to create meters.
+- Semantic verdict: each sample is one handler invocation, so `handler` and `decision` describe the measured duration rather than duplicating whole-chain duration under every handler.
+
+## Commit / PR
+
+Local commit: current Issue commit (`fix(observability): add bounded chain timer dimensions`). Remote PR/Issue closure requires GitHub Write Gate approval.
+
+## Remaining work
+
+Prepare the remote-write review package after all executable Issues are locally complete.
diff --git a/src/main/java/io/github/davidhlp/spring/cache/redis/chain/CacheHandlerChainFactory.java b/src/main/java/io/github/davidhlp/spring/cache/redis/chain/CacheHandlerChainFactory.java
index 7d83cc40..0b71dc38 100644
--- a/src/main/java/io/github/davidhlp/spring/cache/redis/chain/CacheHandlerChainFactory.java
+++ b/src/main/java/io/github/davidhlp/spring/cache/redis/chain/CacheHandlerChainFactory.java
@@ -21,13 +21,13 @@
  * <ol>
  *   <li>{@link MDCStampChainObserver} — 无 registry 依赖，必注册</li>
  *   <li>{@link ChainDebugLogChainObserver} — 无 registry 依赖，必注册</li>
- *   <li>{@link ChainTimerChainObserver} — registry 缺失时全 no-op 计时，仍注册（懒初始化）</li>
+ *   <li>{@link ChainTimerChainObserver} — registry 缺失时全 no-op，仍注册</li>
  *   <li>{@link FiredCounterChainObserver} — registry 缺失时全 no-op，仍注册</li>
  * </ol>
  *
  * <p>observer 装配时机：首次 {@link #createChain} 调时。ChainHandlerChain
  * 自身不再持有 metric 状态，所有 per-handler / per-chain 观测收口到 Engine 的
- * observer 列表。
+ * observer 列表。Timer 在节点 around-hook 中记录 handler + decision + cacheName。
  *
  * <p>设计改进：
  * <ul>
diff --git a/src/main/java/io/github/davidhlp/spring/cache/redis/chain/ChainEngine.java b/src/main/java/io/github/davidhlp/spring/cache/redis/chain/ChainEngine.java
index baaddf0f..b73d2aa7 100644
--- a/src/main/java/io/github/davidhlp/spring/cache/redis/chain/ChainEngine.java
+++ b/src/main/java/io/github/davidhlp/spring/cache/redis/chain/ChainEngine.java
@@ -266,20 +266,59 @@ private static CacheResult materialize(HandlerResult result) {
     }
 
     /**
-     * 单节点调用：beforeNode → handler.handle(ctx) → afterNode。Engine 不捕获
-     * handler 异常（异常冒泡由调用方决定 — 当前 execute 的 try/finally 只守护
-     * onChainEnd 配对，handler 异常直接冒泡给 CacheHandlerChain.execute 的
-     * 调用方，与原 AbstractCacheHandler 行为一致：异常即不计 perNode counter / log）。
+     * 单节点调用：onNodeStart → beforeNode → handler.handle(ctx) → afterNode →
+     * onNodeEnd。Engine 不捕获 handler 异常，异常仍向调用方冒泡；但 token 化的
+     * onNodeEnd 由 finally 配对，避免计时等 around-node observer 泄漏调用状态。
      *
-     * <p>结果传递：handler.handle 返回后调用 afterNode(handler, ctx, result)，
-     * 让 observer（如 ChainDebugLogChainObserver / FiredCounterChainObserver）
-     * 能拿到 result.decision() 做后续处理。
+     * <p>原 beforeNode/afterNode 契约保持不变：handler 抛异常时 afterNode 不调用，
+     * 因而 DEBUG log / fired counter 不会把失败求值计作成功结果。onNodeEnd 此时收到
+     * null result，只负责回收 token，不应伪造 decision。
      */
     private HandlerResult invokeWithObservers(CacheHandler handler, CacheContext context) {
-        observers.forEachSafe(o -> o.beforeNode(handler, context));
-        HandlerResult result = handler.handle(context);
-        observers.forEachSafe(o -> o.afterNode(handler, context, result));
-        return result;
+        List<ChainObserver> observerList = observers.snapshot();
+        Object[] scopeTokens = new Object[observerList.size()];
+        for (int i = 0; i < observerList.size(); i++) {
+            ChainObserver observer = observerList.get(i);
+            try {
+                scopeTokens[i] = observer.onNodeStart(handler, context);
+            } catch (Exception ex) {
+                log.error("Observer {} onNodeStart failed: {}",
+                        observer.getClass().getSimpleName(), ex.toString(), ex);
+            }
+        }
+
+        HandlerResult result = null;
+        try {
+            for (ChainObserver observer : observerList) {
+                try {
+                    observer.beforeNode(handler, context);
+                } catch (Exception ex) {
+                    log.error("Observer {} beforeNode failed: {}",
+                            observer.getClass().getSimpleName(), ex.toString(), ex);
+                }
+            }
+            result = handler.handle(context);
+            HandlerResult completedResult = result;
+            for (ChainObserver observer : observerList) {
+                try {
+                    observer.afterNode(handler, context, completedResult);
+                } catch (Exception ex) {
+                    log.error("Observer {} afterNode failed: {}",
+                            observer.getClass().getSimpleName(), ex.toString(), ex);
+                }
+            }
+            return result;
+        } finally {
+            for (int i = 0; i < observerList.size(); i++) {
+                ChainObserver observer = observerList.get(i);
+                try {
+                    observer.onNodeEnd(handler, context, scopeTokens[i], result);
+                } catch (Exception ex) {
+                    log.error("Observer {} onNodeEnd failed: {}",
+                            observer.getClass().getSimpleName(), ex.toString(), ex);
+                }
+            }
+        }
     }
 
     // ==================== ChainLifecycle (ADR-0056 / Round 42 seam) ====================
diff --git a/src/main/java/io/github/davidhlp/spring/cache/redis/chain/observer/ChainObserver.java b/src/main/java/io/github/davidhlp/spring/cache/redis/chain/observer/ChainObserver.java
index 618bf77b..de88a7ae 100644
--- a/src/main/java/io/github/davidhlp/spring/cache/redis/chain/observer/ChainObserver.java
+++ b/src/main/java/io/github/davidhlp/spring/cache/redis/chain/observer/ChainObserver.java
@@ -11,7 +11,7 @@
  * 责任链推进与观测的注入点 — ADR-0009 (Chain Engine extraction) D2.
  *
  * <p>本接口把责任链 advance / per-node / around-chain 各阶段的横切关注点
- * 收口到 4 个 default no-op 钩子，让 {@link ChainEngine} 与
+ * 收口到 default no-op 钩子，让 {@link ChainEngine} 与
  * {@link AbstractCacheHandler} 不再各自承担观测逻辑。Engine 驱动推进时
  * 按下列顺序调用各 observer：
  *
@@ -20,9 +20,12 @@
  *       返回 {@code scopeToken} 用于 onChainEnd 恢复(如调用方原 MDC 值、Timer start nanos)</li>
  *   <li>每节点循环：
  *     <ul>
+ *       <li>{@link #onNodeStart(CacheHandler, CacheContext)} — 节点 around-hook 起点</li>
  *       <li>{@link #beforeNode(CacheHandler, CacheContext)} — per-node 前置</li>
  *       <li>handler.handle(ctx)</li>
- *       <li>{@link #afterNode(CacheHandler, CacheContext, HandlerResult)} — per-node 后置（DEBUG log / fired counter）</li>
+ *       <li>{@link #afterNode(CacheHandler, CacheContext, HandlerResult)} — 成功返回后的 per-node 后置</li>
+ *       <li>{@link #onNodeEnd(CacheHandler, CacheContext, Object, HandlerResult)} —
+ *           finally 配对的节点 around-hook 终点</li>
  *     </ul>
  *   </li>
  *   <li>{@link #onChainEnd(CacheContext, Object, CacheResult)} — 链出口 around-hook(MDC restore / Timer record);
@@ -33,7 +36,7 @@
  * <p><b>ADR-0061 scope token 机制</b>:onChainStart 返回 {@code Object} 类型的
  * "scope token" 替代原 {@code CacheContext.attributes} 字符串键 map —— observer
  * 可在 token 内携带本调用专属的恢复状态(MDCStamp → previousRequestId,
- * ChainTimer → startNanos),Engine 在 onChainEnd 配对回传。CacheContext 不再
+ * ChainTimer → per-node startNanos),Engine 在对应 end hook 配对回传。CacheContext 不再
  * 提供 stringly-typed 通用 attributes 袋,observer 状态机完全自承,新 observer
  * 零字符串键漂移风险,Engine 不感知 observer 内部协议。
  *
@@ -82,6 +85,33 @@ default void onChainEnd(CacheContext context, Object scopeToken, CacheResult res
         // 默认 no-op
     }
 
+    /**
+     * 节点 around-hook 起点。Engine 将返回 token 与
+     * {@link #onNodeEnd(CacheHandler, CacheContext, Object, HandlerResult)} 在 finally 中配对。
+     * observer 不应把节点调用状态保存在共享字段或 ThreadLocal 中。
+     *
+     * @param handler 即将被求值的 handler
+     * @param context 链上下文
+     * @return 本 observer 的节点调用 scope token(可为 null)
+     */
+    default Object onNodeStart(CacheHandler handler, CacheContext context) {
+        return null;
+    }
+
+    /**
+     * 节点 around-hook 终点。handler 抛异常时仍被调用，此时 {@code result} 为 null；
+     * observer 可回收 token，但不应虚构 decision 或成功样本。
+     *
+     * @param handler    已被求值的 handler
+     * @param context    链上下文
+     * @param scopeToken 本 observer 在 onNodeStart 返回的 token(可为 null)
+     * @param result     handler 的结果；handler 抛异常时为 null
+     */
+    default void onNodeEnd(CacheHandler handler, CacheContext context,
+                           Object scopeToken, HandlerResult result) {
+        // 默认 no-op
+    }
+
     /**
      * 节点前置 hook。Engine 在调用 {@code handler.handle(ctx)} 之前调用，
      * 即：{@code beforeNode} → {@code handler.handle(ctx)} → {@code afterNode}。
diff --git a/src/main/java/io/github/davidhlp/spring/cache/redis/chain/observer/ChainObserverRegistration.java b/src/main/java/io/github/davidhlp/spring/cache/redis/chain/observer/ChainObserverRegistration.java
index 2155da08..6146df37 100644
--- a/src/main/java/io/github/davidhlp/spring/cache/redis/chain/observer/ChainObserverRegistration.java
+++ b/src/main/java/io/github/davidhlp/spring/cache/redis/chain/observer/ChainObserverRegistration.java
@@ -52,7 +52,7 @@ public static void registerStandardObservers(
         // 2. DEBUG log — 必注册(无 registry 依赖)
         engine.addObserver(new ChainDebugLogChainObserver());
 
-        // 3. Timer — registry 缺失时也注册(observer 内部 lazy 检测);保证 observer 列表
+        // 3. Timer — registry 缺失时也注册(observer 内部 no-op);保证 observer 列表
         //    在 registry 可用前后一致,Engine 调度逻辑无需区分
         MeterRegistry registry =
                 meterRegistryProvider == null ? null : meterRegistryProvider.getIfAvailable();
diff --git a/src/main/java/io/github/davidhlp/spring/cache/redis/chain/observer/ChainTimerChainObserver.java b/src/main/java/io/github/davidhlp/spring/cache/redis/chain/observer/ChainTimerChainObserver.java
index 276a27be..03699edd 100644
--- a/src/main/java/io/github/davidhlp/spring/cache/redis/chain/observer/ChainTimerChainObserver.java
+++ b/src/main/java/io/github/davidhlp/spring/cache/redis/chain/observer/ChainTimerChainObserver.java
@@ -1,106 +1,73 @@
 package io.github.davidhlp.spring.cache.redis.chain.observer;
 
-import io.github.davidhlp.spring.cache.redis.chain.CacheResult;
+import io.github.davidhlp.spring.cache.redis.chain.CacheHandler;
+import io.github.davidhlp.spring.cache.redis.chain.HandlerResult;
 import io.github.davidhlp.spring.cache.redis.chain.model.CacheContext;
 
 import io.micrometer.core.instrument.MeterRegistry;
 import io.micrometer.core.instrument.Timer;
-import lombok.extern.slf4j.Slf4j;
 
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.ConcurrentMap;
 import java.util.concurrent.TimeUnit;
 
 /**
- * ChainObserver 的 aroundChain 实现 — 链级 Micrometer Timer，记录
- * 整条 chain.execute 的全生命周期（head handle + post-process + 所有节点）。
+ * 责任链节点级 Micrometer Timer。
  *
- * <p>替换原 {@code CacheHandlerChain.execute} 的内联 Timer 装配 / 记录逻辑
- * （{@code chainExecuteTimer} 字段 + {@code Timer.record(...)} 调用）。Engine
- * 不再持有 Timer 状态。
+ * <p>每次 {@code handler.handle(context)} 调用由 Engine 的 token 化
+ * {@code onNodeStart/onNodeEnd} 钩子配对计时，并以 {@code handler}、
+ * {@code decision}、{@code cacheName} 三个有界维度注册
+ * {@code resicache.chain.execute}。故障节点没有 {@link HandlerResult}，不伪造
+ * decision，也不记录样本；Engine 仍在 finally 中回收其 scope token。
  *
- * <p>当前无 per-cacheName / per-operation tags（与原实现一致 — 留 WS-1.4 测试套件
- * 扩展时按 cardinality 评估再加）。{@code registry} 缺失时全链 no-op 计时，
- * 行为与原 {@code CacheHandlerChain} 一致。
+ * <p>禁止把 redisKey、异常消息或用户动态 ID 用作 tag。Timer 缓存的 key 只包含
+ * handler 类型、三值 decision 与应用配置的 cacheName。
  *
- * <p>延迟注册策略：{@code onChainStart} 第一次被调用时检查并创建 Timer，
- * 后续复用（同名 register 幂等返回同一实例）。
- *
- * <p><b>ADR-0061 scope token 收尾</b>(Round 46):onChainStart 把"start nanos"
- * 装入 {@link TimerScope} record 返回,onChainEnd 接收该 token 计算 elapsed
- * 后 record 到 Timer。完全摆脱原 {@code CacheContext.attributes} 字符串键 map
- * (原 {@code __chainTimer.startNanos} 常量 + setAttribute/getAttribute/removeAttribute
- * 调用链全部删除),observer 状态机完全自承。Engine 不感知 token 内部协议。
- *
- * <p>线程安全：{@code timer} 单写多读，double-checked locking 守护;scope token
- * 是 per-call 不可变 record,无共享状态。
+ * <p>线程安全：Timer map 支持并发注册；{@link TimerScope} 是单次节点调用的不可变
+ * token，不在 observer 内保存共享的 per-call 状态。registry 缺失时全程 no-op。
  */
-@Slf4j
 public final class ChainTimerChainObserver implements ChainObserver {
 
+    static final String METRIC_NAME = "resicache.chain.execute";
+
     private final MeterRegistry registry;
-    /** 首次 onChainStart 时按需创建；registry 缺失时为 null。 */
-    private volatile Timer timer;
+    private final ConcurrentMap<TimerKey, Timer> timers = new ConcurrentHashMap<>();
 
     public ChainTimerChainObserver(MeterRegistry registry) {
         this.registry = registry;
     }
 
     @Override
-    public Object onChainStart(CacheContext context) {
-        if (registry == null) {
-            return null;  // no-op 路径,token = null → onChainEnd 也走 no-op 分支
-        }
-        Timer t = ensureTimer();
-        if (t == null) {
-            return null;
-        }
-        // ADR-0061:把"start nanos"装入 TimerScope record 返回,Engine 在 onChainEnd 配对回传
-        return new TimerScope(System.nanoTime());
+    public Object onNodeStart(CacheHandler handler, CacheContext context) {
+        return registry == null ? null : new TimerScope(System.nanoTime());
     }
 
     @Override
-    public void onChainEnd(CacheContext context, Object scopeToken, CacheResult result) {
-        Timer t = this.timer;
-        // ADR-0061:token 即 onChainStart 返回的 TimerScope 实例,instanceof 模式匹配恢复 startNanos
-        if (t == null || !(scopeToken instanceof TimerScope scope)) {
+    public void onNodeEnd(CacheHandler handler, CacheContext context,
+                          Object scopeToken, HandlerResult result) {
+        if (registry == null || result == null || !(scopeToken instanceof TimerScope scope)) {
             return;
         }
-        long elapsed = System.nanoTime() - scope.startNanos();
-        t.record(elapsed, TimeUnit.NANOSECONDS);
+        TimerKey key = new TimerKey(
+                handler.getClass().getSimpleName(),
+                result.decision().name(),
+                context.getCacheName());
+        Timer timer = timers.computeIfAbsent(key, this::registerTimer);
+        timer.record(System.nanoTime() - scope.startNanos(), TimeUnit.NANOSECONDS);
     }
 
-    /**
-     * 双重检查锁定初始化 Timer。Micrometer {@code Timer.builder(name).register(registry)}
-     * 同名同 tag 重复 register 幂等返回同一实例，无需 DCL 也安全 —— DCL 是为了避免重复
-     * builder 调用的微量开销。
-     */
-    private Timer ensureTimer() {
-        Timer t = this.timer;
-        if (t == null) {
-            synchronized (this) {
-                t = this.timer;
-                if (t == null) {
-                    t = Timer.builder("resicache.chain.execute")
-                            .description("Time spent executing the cache protection chain "
-                                    + "(full lifecycle: head + post-process + all nodes)")
-                            .register(registry);
-                    this.timer = t;
-                }
-            }
-        }
-        return t;
+    private Timer registerTimer(TimerKey key) {
+        return Timer.builder(METRIC_NAME)
+                .description("Time spent invoking one cache protection handler")
+                .tag("handler", key.handler())
+                .tag("decision", key.decision())
+                .tag("cacheName", key.cacheName())
+                .register(registry);
     }
 
-    /**
-     * Timer scope token — ADR-0061 引入的 per-call 状态值对象.
-     *
-     * <p>本 record 由 {@link #onChainStart} 构造,持有本次链执行的 start nanos,
-     * 由 {@link #onChainEnd} 读取计算 elapsed。Engine 不感知 record 内容。
-     *
-     * <p>本 record 是 observer 私有(本类嵌套):当前仅 ChainTimerChainObserver 一个
-     * 消费者,未达提升为顶层类型的必要性(YAGNI)。
-     *
-     * @param startNanos {@code System.nanoTime()} 在 onChainStart 时记录的起始点
-     */
     private record TimerScope(long startNanos) {
     }
+
+    private record TimerKey(String handler, String decision, String cacheName) {
+    }
 }
diff --git a/src/test/java/io/github/davidhlp/spring/cache/redis/chain/ChainEngineTest.java b/src/test/java/io/github/davidhlp/spring/cache/redis/chain/ChainEngineTest.java
index d69d97f2..8f832b4e 100644
--- a/src/test/java/io/github/davidhlp/spring/cache/redis/chain/ChainEngineTest.java
+++ b/src/test/java/io/github/davidhlp/spring/cache/redis/chain/ChainEngineTest.java
@@ -147,7 +147,7 @@ void continueAtChainTail_nullResult_returnsSuccess() {
     class ObserverTests {
 
         @Test
-        @DisplayName("aroundChain:onChainStart → beforeNode → afterNode → onChainEnd 顺序执行")
+        @DisplayName("aroundChain 与 node token hooks 按嵌套顺序执行")
         void aroundChain_andPerNode_calledInOrder() {
             // ADR-0061:用真实 observer 录制 4 个钩子的调用顺序(替代 mock —— onChainStart
             // 返回 Object 后,mock-based 验证语义不再适用,真实 observer 录制更鲁棒)
@@ -157,9 +157,9 @@ void aroundChain_andPerNode_calledInOrder() {
 
             engine.execute(snapshot, newCtx());
 
-            // 顺序:onChainStart → beforeNode → afterNode → onChainEnd
             assertThat(observer.events).containsExactly(
-                    "onChainStart", "beforeNode", "afterNode", "onChainEnd");
+                    "onChainStart", "onNodeStart", "beforeNode", "afterNode",
+                    "onNodeEnd", "onChainEnd");
         }
 
         @Test
@@ -200,12 +200,32 @@ void executeFragment_skipsAroundChain() {
 
                 assertThat(result.isSuccess()).isTrue();
                 // aroundChain 未触发(fragment 不应 stamp MDC / record Timer)
-                assertThat(observer.events).containsExactly("beforeNode", "afterNode", "beforeNode", "afterNode");
+                assertThat(observer.events).containsExactly(
+                        "onNodeStart", "beforeNode", "afterNode", "onNodeEnd",
+                        "onNodeStart", "beforeNode", "afterNode", "onNodeEnd");
             } finally {
                 engine.clearCurrentSnapshotForTest();
             }
         }
 
+        @Test
+        @DisplayName("handler 异常时 onNodeEnd 仍配对且 result 为 null")
+        void handlerThrows_nodeScopeStillCloses() {
+            NodeTokenRecordingObserver observer = new NodeTokenRecordingObserver();
+            engine.addObserver(observer);
+            CacheHandler throwing = context -> { throw new IllegalStateException("handler boom"); };
+            installChain(throwing);
+
+            assertThatThrownBy(() -> engine.execute(snapshot, newCtx()))
+                    .isInstanceOf(IllegalStateException.class)
+                    .hasMessage("handler boom");
+
+            assertThat(observer.startCount).isEqualTo(1);
+            assertThat(observer.endCount).isEqualTo(1);
+            assertThat(observer.endToken).isSameAs(observer.startToken);
+            assertThat(observer.endResult).isNull();
+        }
+
         @Test
         @DisplayName("afterNode 收到 handler.handle 的真实 result(非 null)")
         void afterNode_receivesActualResult() {
@@ -233,6 +253,8 @@ void observerThrows_swallowed_mainChainUnaffected() {
                 @Override public void onChainEnd(CacheContext context, Object scopeToken, CacheResult result) {
                     throw new RuntimeException("end boom");
                 }
+                @Override public Object onNodeStart(CacheHandler h, CacheContext context) { throw new RuntimeException("node start boom"); }
+                @Override public void onNodeEnd(CacheHandler h, CacheContext context, Object token, HandlerResult r) { throw new RuntimeException("node end boom"); }
                 @Override public void beforeNode(CacheHandler h, CacheContext context) { throw new RuntimeException("before boom"); }
                 @Override public void afterNode(CacheHandler h, CacheContext context, HandlerResult r) { throw new RuntimeException("after boom"); }
             };
@@ -451,6 +473,12 @@ public Object onChainStart(CacheContext context) {
             return null;  // 无状态 observer
         }
 
+        @Override
+        public Object onNodeStart(CacheHandler handler, CacheContext context) {
+            events.add("onNodeStart");
+            return null;
+        }
+
         @Override
         public void beforeNode(CacheHandler handler, CacheContext context) {
             events.add("beforeNode");
@@ -461,6 +489,12 @@ public void afterNode(CacheHandler handler, CacheContext context, HandlerResult
             events.add("afterNode");
         }
 
+        @Override
+        public void onNodeEnd(CacheHandler handler, CacheContext context,
+                              Object scopeToken, HandlerResult result) {
+            events.add("onNodeEnd");
+        }
+
         @Override
         public void onChainEnd(CacheContext context, Object scopeToken, CacheResult result) {
             events.add("onChainEnd");
@@ -473,6 +507,29 @@ public void onChainEnd(CacheContext context, Object scopeToken, CacheResult resu
      * <p>onChainStart 返回唯一标识 token,onChainEnd 校验传入的 token 与 start 时的
      * 引用相同(Engine 按 index 配对,跨 observer 不混淆)。无 state map 累积干扰。
      */
+    static class NodeTokenRecordingObserver implements ChainObserver {
+        int startCount;
+        int endCount;
+        Object startToken;
+        Object endToken;
+        HandlerResult endResult;
+
+        @Override
+        public Object onNodeStart(CacheHandler handler, CacheContext context) {
+            startCount++;
+            startToken = new Object();
+            return startToken;
+        }
+
+        @Override
+        public void onNodeEnd(CacheHandler handler, CacheContext context,
+                              Object scopeToken, HandlerResult result) {
+            endCount++;
+            endToken = scopeToken;
+            endResult = result;
+        }
+    }
+
     static class TokenRecordingObserver implements ChainObserver {
         int startCount = 0;
         int endCount = 0;
diff --git a/src/test/java/io/github/davidhlp/spring/cache/redis/chain/observer/ChainObserverTest.java b/src/test/java/io/github/davidhlp/spring/cache/redis/chain/observer/ChainObserverTest.java
index 20a810c3..7dee3b76 100644
--- a/src/test/java/io/github/davidhlp/spring/cache/redis/chain/observer/ChainObserverTest.java
+++ b/src/test/java/io/github/davidhlp/spring/cache/redis/chain/observer/ChainObserverTest.java
@@ -108,45 +108,119 @@ void multipleStartEnd_generateDifferentIds() {
     class TimerTests {
 
         @Test
-        @DisplayName("registry 缺失 → onChainStart 返回 null,onChainEnd 接收 null token 全 no-op")
+        @DisplayName("registry 缺失时节点计时 no-op")
         void nullRegistry_noOp() {
             ChainObserver observer = new ChainTimerChainObserver(null);
-            Object scopeToken = observer.onChainStart(ctx);
-            // ADR-0061:registry 缺失时 onChainStart 返回 null token,onChainEnd 接收 null
+
+            Object scopeToken = observer.onNodeStart(handler, ctx);
+
             assertThat(scopeToken).isNull();
-            observer.onChainEnd(ctx, scopeToken, CacheResult.success());
-            // 不抛异常 + context 不再被 attributes map 污染(ADR-0061:attributes 已删除)
+            observer.onNodeEnd(handler, ctx, scopeToken, HandlerResult.continueChain());
         }
 
         @Test
-        @DisplayName("registry 存在 → onChainStart 返回 TimerScope token,onChainEnd 接收并 record Timer 一次")
-        void withRegistry_recordsTimer() {
+        @DisplayName("成功节点按 handler、decision、cacheName 记录一次 Timer")
+        void successfulNode_recordsBoundedTags() {
             MeterRegistry registry = new SimpleMeterRegistry();
             ChainObserver observer = new ChainTimerChainObserver(registry);
+            CacheHandler namedHandler = new ContinueHandler();
 
-            // ADR-0061:onChainStart 返回 TimerScope token,onChainEnd 接收并计算 elapsed
-            Object scopeToken = observer.onChainStart(ctx);
-            assertThat(scopeToken).isNotNull();
-            observer.onChainEnd(ctx, scopeToken, CacheResult.success());
+            Object scopeToken = observer.onNodeStart(namedHandler, ctx);
+            observer.onNodeEnd(namedHandler, ctx, scopeToken,
+                    HandlerResult.terminate(CacheResult.success()));
 
-            Timer timer = registry.find("resicache.chain.execute").timer();
+            Timer timer = registry.find(ChainTimerChainObserver.METRIC_NAME)
+                    .tag("handler", "ContinueHandler")
+                    .tag("decision", "TERMINATE")
+                    .tag("cacheName", "test-cache")
+                    .timer();
             assertThat(timer).isNotNull();
             assertThat(timer.count()).isEqualTo(1L);
+            assertThat(timer.getId().getTags())
+                    .extracting(tag -> tag.getKey())
+                    .containsExactlyInAnyOrder("handler", "decision", "cacheName");
         }
 
         @Test
-        @DisplayName("多次 start/end → Timer count 累加")
-        void multipleRecords_countAccumulates() {
+        @DisplayName("动态 redisKey 不增加 meter cardinality")
+        void changingRedisKey_doesNotCreateMeters() {
             MeterRegistry registry = new SimpleMeterRegistry();
             ChainObserver observer = new ChainTimerChainObserver(registry);
+            CacheHandler namedHandler = new ContinueHandler();
 
-            for (int i = 0; i < 5; i++) {
-                Object scopeToken = observer.onChainStart(ctx);
-                observer.onChainEnd(ctx, scopeToken, CacheResult.success());
+            for (int i = 0; i < 20; i++) {
+                CacheContext dynamicContext = context("test-cache", "user:" + i);
+                Object scopeToken = observer.onNodeStart(namedHandler, dynamicContext);
+                observer.onNodeEnd(namedHandler, dynamicContext, scopeToken,
+                        HandlerResult.continueChain());
+            }
+
+            assertThat(registry.find(ChainTimerChainObserver.METRIC_NAME).timers())
+                    .singleElement()
+                    .satisfies(timer -> {
+                        assertThat(timer.count()).isEqualTo(20L);
+                        assertThat(timer.getId().getTag("redisKey")).isNull();
+                    });
+        }
+
+        @Test
+        @DisplayName("三种 decision 与 cacheName 形成明确有限的 meter 组合")
+        void decisionAndCacheName_partitionMeters() {
+            MeterRegistry registry = new SimpleMeterRegistry();
+            ChainObserver observer = new ChainTimerChainObserver(registry);
+            CacheHandler namedHandler = new ContinueHandler();
+            HandlerResult[] results = {
+                    HandlerResult.continueChain(),
+                    HandlerResult.skipAll(),
+                    HandlerResult.terminate()
+            };
+
+            for (String cacheName : new String[]{"catalog", "sessions"}) {
+                for (HandlerResult result : results) {
+                    CacheContext context = context(cacheName, "same-key");
+                    Object scopeToken = observer.onNodeStart(namedHandler, context);
+                    observer.onNodeEnd(namedHandler, context, scopeToken, result);
+                }
             }
 
-            Timer timer = registry.find("resicache.chain.execute").timer();
-            assertThat(timer.count()).isEqualTo(5L);
+            assertThat(registry.find(ChainTimerChainObserver.METRIC_NAME).timers())
+                    .hasSize(6)
+                    .allSatisfy(timer -> {
+                        assertThat(timer.count()).isEqualTo(1L);
+                        assertThat(timer.getId().getTag("decision"))
+                                .isIn("CONTINUE", "SKIP_ALL", "TERMINATE");
+                        assertThat(timer.getId().getTag("cacheName"))
+                                .isIn("catalog", "sessions");
+                    });
+        }
+
+        @Test
+        @DisplayName("异常节点只回收 token，不记录虚假 decision")
+        void nullResult_doesNotRecordTimer() {
+            MeterRegistry registry = new SimpleMeterRegistry();
+            ChainObserver observer = new ChainTimerChainObserver(registry);
+            CacheHandler namedHandler = new ContinueHandler();
+
+            Object scopeToken = observer.onNodeStart(namedHandler, ctx);
+            observer.onNodeEnd(namedHandler, ctx, scopeToken, null);
+
+            assertThat(registry.find(ChainTimerChainObserver.METRIC_NAME).timers()).isEmpty();
+        }
+
+        private CacheContext context(String cacheName, String redisKey) {
+            return CacheContext.of(CacheInput.builder()
+                    .operation(CacheOperation.GET)
+                    .cacheName(cacheName)
+                    .redisKey(redisKey)
+                    .actualKey(redisKey)
+                    .build());
+        }
+
+        private final class ContinueHandler implements CacheHandler {
+            @Override
+            public HandlerResult handle(CacheContext context) {
+                return HandlerResult.continueChain();
+            }
         }
     }
 
diff --git a/wiki/modules/observability.md b/wiki/modules/observability.md
index 638f10ab..d5dabbce 100644
--- a/wiki/modules/observability.md
+++ b/wiki/modules/observability.md
@@ -15,10 +15,12 @@ source-files:
   - src/main/java/io/github/davidhlp/spring/cache/redis/config/MetricsAutoConfiguration.java
   - src/main/java/io/github/davidhlp/spring/cache/redis/config/SerializerWhitelistStartupGuard.java
   - src/main/java/io/github/davidhlp/spring/cache/redis/chain/CacheHandlerChain.java
+  - src/main/java/io/github/davidhlp/spring/cache/redis/chain/ChainEngine.java
   - src/main/java/io/github/davidhlp/spring/cache/redis/chain/AbstractCacheHandler.java
+  - src/main/java/io/github/davidhlp/spring/cache/redis/chain/observer/ChainTimerChainObserver.java
 status: stable
 created: 2026-06-21
-updated: 2026-07-11
+updated: 2026-07-26
 ---
 
 # 健康检查与可观测性
@@ -60,14 +62,15 @@ ResiCache 走 Spring Boot actuator 既有体系,不发明独立指标框架。
 
 ## 责任链执行可观测性
 
-责任链执行提供三层 runtime 信号(装配由 `CacheHandlerChainFactory` + `ChainObserver` 统一收口,Observer 4 钩子 `onChainStart`/`beforeNode`/`afterNode`/`onChainEnd`):
+责任链执行提供三层 runtime 信号(装配由 `CacheHandlerChainFactory` + `ChainObserver` 统一收口；链级和节点级 around-hook 都以 scope token 配对，不使用共享 `ThreadLocal` 状态):
 
 | 信号 | 类型 | 说明 |
 |---|---|---|
-| `resicache.chain.execute` | Micrometer Timer | 整条链 full lifecycle(head handle + post-process) |
+| `resicache.chain.execute` | Micrometer Timer(tags `handler`,`decision`,`cacheName`) | 单个 handler 调用耗时；decision 仅 `CONTINUE` / `SKIP_ALL` / `TERMINATE` |
 | `resicache.handler.fired` | Counter(tag `handler`) | 各 handler 被引擎求值频率,cardinality bounded(~6) |
 | `[chain]` DEBUG + MDC `requestId` | 日志 | 一次 GET/PUT 内所有 handler 共享 requestId,串联决策序列 |
 
+- `resicache.chain.execute` 不使用 `redisKey`、用户 ID、异常消息等无界 tag；其 meter 数只随已安装 handler、三值 decision 和应用配置的 cacheName 组合增长。handler 抛异常时节点 token 仍由 `finally` 配对回收，但因没有 decision 不记录虚假样本。
 - DEBUG 关闭时静默 no-op;requestId 用 `ThreadLocalRandom`(热路径规避 SecureRandom 熵竞争)。
 - MDC 用 snapshot/restore,finally 恢复调用方原值,**不**用 `MDC.clear()` 误清宿主线程其它 MDC(如 `traceId`)。
 - 语义 counter(`ttl.jittered` / `null.hit` / `sync.lock.acquired` / `bloom.blocked` / `early-refresh.triggered`)由 `AbstractCacheHandler#onAttachMetrics` 钩子统一注册,disabled handler 不注册(与 `fired` 行为对齐)。

From 037ffe4bf0340fe87094490fa6f61aac5122e191 Mon Sep 17 00:00:00 2001
From: DavidHLP <lysf15520112973@163.com>
Date: Sun, 26 Jul 2026 01:07:56 +0800
Subject: [PATCH 2/7] test(redis): prove cluster lock slot co-location

---
 .ai/issues/issue-2.md                         |  72 +++++++++++
 COMPATIBILITY.md                              |   5 +-
 .../AbstractRedisClusterIntegrationTest.java  | 117 ++++++++++++++++++
 .../RedisClusterSlotIntegrationTest.java      | 116 +++++++++++++++++
 .../integration/TestRedisConfiguration.java   |  33 +++--
 wiki/mechanisms/breakdown-lock.md             |   9 +-
 6 files changed, 339 insertions(+), 13 deletions(-)
 create mode 100644 .ai/issues/issue-2.md
 create mode 100644 src/test/java/io/github/davidhlp/spring/cache/redis/integration/AbstractRedisClusterIntegrationTest.java
 create mode 100644 src/test/java/io/github/davidhlp/spring/cache/redis/integration/RedisClusterSlotIntegrationTest.java

diff --git a/.ai/issues/issue-2.md b/.ai/issues/issue-2.md
new file mode 100644
index 00000000..2a687558
--- /dev/null
+++ b/.ai/issues/issue-2.md
@@ -0,0 +1,72 @@
+# Issue #2 — Real Redis Cluster slot co-location integration test
+
+- **Issue:** https://github.com/DavidHLP/ResiCache/issues/2
+- **Status:** COMMITTED
+- **Priority:** P1 correctness
+- **Dependencies:** none; production implementation appears present and needs real-topology proof
+- **External work:** no assignee, comments, branch, or linked PR
+
+## Current findings
+
+- `DistributedLockManager#buildLockKey` already distinguishes cluster mode and preserves or creates a hash tag.
+- Unit tests already cover no-tag wrapping, existing-tag preservation, and slot equality by key construction.
+- Existing `DistributedLockIntegrationTest` uses standalone Redis, so the Issue's real Cluster acceptance is not yet proved.
+- Testcontainers dependency must remain pinned to `1.20.4`; target test execution and zero skips must be checked explicitly.
+
+## Acceptance criteria
+
+1. A real `redis:7` Cluster topology starts under Testcontainers.
+2. A sync-enabled cache PUT/get-loader path obtains a Redisson distributed lock.
+3. Cache key and lock key report the same `CLUSTER KEYSLOT` and map to the same node.
+4. The real operation completes without `CROSSSLOT`.
+5. Test report confirms target test count > 0 and skipped = 0.
+
+## Implementation plan
+
+- Add an isolated `AbstractRedisClusterIntegrationTest` rather than destabilizing all standalone Redis ITs.
+- Reuse production `DistributedLockManager`/cache path; do not duplicate slot logic in the test.
+- Add one focused Cluster integration class and only the minimum fixture configuration required.
+- Update cluster limitation/docs only after the proof passes.
+
+## Files/modules involved
+
+- `src/main/java/.../protection/breakdown/DistributedLockManager.java` (expected read-only)
+- `src/test/java/.../integration/AbstractRedisClusterIntegrationTest.java`
+- `src/test/java/.../integration/*Cluster*IntegrationTest.java`
+- Redis compatibility/cache lifecycle wiki or docs identified during investigation
+
+## Tests required
+
+- Existing `DistributedLockManagerTest`.
+- New real Cluster IT with container-start and no-skip evidence.
+- Full integration regression.
+
+## Validation result
+
+- Real `redis:7-alpine` container started and formed a three-master Cluster (`cluster_state:ok`).
+- `RedisClusterSlotIntegrationTest`: 1 test, 0 failures, 0 errors, 0 skipped; `BUILD SUCCESS`.
+- Production annotation path acquired a live Redisson lock; test read its actual Redis key, compared both server-side `CLUSTER KEYSLOT` values, and executed a same-slot two-key command without `CROSSSLOT`.
+- Target test also proved the cache value was written after lock release.
+- `DistributedLockManagerTest` + Cluster IT: 26 tests, 0 failures, 0 errors, 0 skipped; `BUILD SUCCESS`.
+- Checkstyle: 0 violations; `git diff --check`: clean.
+- The unchanged standalone `DistributedLockIntegrationTest` cannot start its pre-existing WSL2 fixture because this workstation lacks `socat`; rerunning it alone reproduces the same `Cannot start socat` before test execution. The new Cluster fixture does not depend on or weaken that asset.
+- Review and commit pending.
+
+## Review findings
+
+Independent reviewer jobs again failed to yield within the bounded review window and were cancelled; the maintainer process completed the frozen Standards + Spec review directly.
+
+- **critical/high/medium:** none.
+- Topology validity: three Redis server processes form a real Cluster with node IDs and complete slot ownership; teardown requires `cluster_state:ok`.
+- Acceptance proof: the test observes a live production Redisson lock key, asks Redis for both `CLUSTER KEYSLOT` values, and executes a dual-key `EXISTS`; a slot mismatch would produce `CROSSSLOT` before key existence is evaluated.
+- Lifecycle/concurrency: loader release is in `finally`, preventing an assertion failure from leaving the async loader blocked.
+- Compatibility: `TestRedisConfiguration` keeps its original single-server branch and selects Cluster only when `resi-cache.redis.mode=cluster`; production code is unchanged.
+- Documentation matches the exact topology and server-side assertions.
+
+## Commit / PR
+
+Local Issue commit: `test(redis): prove cluster lock slot co-location`. Remote PR/Issue closure requires GitHub Write Gate approval.
+
+## Remaining work
+
+Include #2 in the final remote-write review package.
diff --git a/COMPATIBILITY.md b/COMPATIBILITY.md
index a9d1cde2..e6c684ec 100644
--- a/COMPATIBILITY.md
+++ b/COMPATIBILITY.md
@@ -74,4 +74,7 @@ misses on cutover. See [README → Known Limitations](README.md#known-limitation
   `resi-cache.transaction-aware=true`.
 - **Redis Cluster distributed locks**: lock keys are **hash-tag pinned** to the
   same slot as the cache key (WS-1.2b), so the lock and the data it guards
-  co-locate on one node. Validated at the key-construction level.
+  co-locate on one node. Validated by `RedisClusterSlotIntegrationTest` against a
+  real three-master `redis:7` Cluster: the live Redisson lock key and cache key
+  return the same `CLUSTER KEYSLOT`, and a two-key command completes without
+  `CROSSSLOT`.
diff --git a/src/test/java/io/github/davidhlp/spring/cache/redis/integration/AbstractRedisClusterIntegrationTest.java b/src/test/java/io/github/davidhlp/spring/cache/redis/integration/AbstractRedisClusterIntegrationTest.java
new file mode 100644
index 00000000..1a3bfcd1
--- /dev/null
+++ b/src/test/java/io/github/davidhlp/spring/cache/redis/integration/AbstractRedisClusterIntegrationTest.java
@@ -0,0 +1,117 @@
+package io.github.davidhlp.spring.cache.redis.integration;
+
+import org.junit.jupiter.api.AfterAll;
+import org.springframework.test.annotation.DirtiesContext;
+import org.springframework.test.context.DynamicPropertyRegistry;
+import org.springframework.test.context.DynamicPropertySource;
+import org.testcontainers.containers.GenericContainer;
+import org.testcontainers.containers.wait.strategy.Wait;
+import org.testcontainers.junit.jupiter.Container;
+import org.testcontainers.junit.jupiter.Testcontainers;
+import org.testcontainers.lifecycle.Startables;
+import org.testcontainers.utility.DockerImageName;
+
+import java.util.Collections;
+
+/**
+ * Three-master Redis Cluster fixture for topology-sensitive integration tests.
+ *
+ * <p>All three Redis processes run in one {@code redis:7-alpine} container but form
+ * a real Cluster with independent ports, node IDs, slot ownership, and cluster bus
+ * links. Tests connect to the container bridge address, which is reachable on the
+ * Linux Docker hosts used locally and by GitHub Actions.
+ */
+@Testcontainers(disabledWithoutDocker = false)
+@DirtiesContext(classMode = DirtiesContext.ClassMode.AFTER_CLASS)
+public abstract class AbstractRedisClusterIntegrationTest {
+
+    private static final String REDIS_IMAGE = "redis:7-alpine";
+    private static final int FIRST_REDIS_PORT = 7000;
+    private static final int NODE_COUNT = 3;
+
+    @Container
+    protected static final GenericContainer<?> REDIS_CLUSTER =
+            new GenericContainer<>(DockerImageName.parse(REDIS_IMAGE))
+                    .withCommand("sh", "-c", clusterStartupCommand())
+                    .waitingFor(Wait.forLogMessage(".*CLUSTER_READY.*", 1));
+
+    @DynamicPropertySource
+    static void redisClusterProperties(DynamicPropertyRegistry registry) {
+        Startables.deepStart(Collections.singletonList(REDIS_CLUSTER)).join();
+        String containerIp = containerIp();
+        for (int index = 0; index < NODE_COUNT; index++) {
+            int port = FIRST_REDIS_PORT + index;
+            int propertyIndex = index;
+            registry.add("spring.data.redis.cluster.nodes[" + propertyIndex + "]",
+                    () -> containerIp + ":" + port);
+            registry.add("resi-cache.redis.cluster-nodes[" + propertyIndex + "]",
+                    () -> "redis://" + containerIp + ":" + port);
+        }
+        registry.add("spring.data.redis.host", () -> containerIp);
+        registry.add("spring.data.redis.port", () -> FIRST_REDIS_PORT);
+        registry.add("resi-cache.redis.mode", () -> "cluster");
+        registry.add("resi-cache.redis.database", () -> 0);
+        registry.add("resi-cache.bloom-filter.enabled", () -> false);
+    }
+
+    @AfterAll
+    static void reportClusterFixture() throws Exception {
+        if (!REDIS_CLUSTER.isRunning()) {
+            throw new IllegalStateException("Redis Cluster container stopped before test completion");
+        }
+        String info = redisCli("cluster", "info");
+        if (!info.contains("cluster_state:ok")) {
+            throw new IllegalStateException("Redis Cluster did not remain healthy: " + info);
+        }
+        System.out.println("[IT] Redis Cluster container=" + REDIS_CLUSTER.getContainerId()
+                + " nodes=" + NODE_COUNT + " state=ok");
+    }
+
+    protected static String redisCli(String... args) throws Exception {
+        return redisCliAt(FIRST_REDIS_PORT, args);
+    }
+
+    protected static String redisCliAt(int port, String... args) throws Exception {
+        String[] command = new String[args.length + 3];
+        command[0] = "redis-cli";
+        command[1] = "-p";
+        command[2] = Integer.toString(port);
+        System.arraycopy(args, 0, command, 3, args.length);
+        var result = REDIS_CLUSTER.execInContainer(command);
+        if (result.getExitCode() != 0) {
+            throw new IllegalStateException("redis-cli failed: " + result.getStderr());
+        }
+        return result.getStdout().trim();
+    }
+
+    private static String containerIp() {
+        return REDIS_CLUSTER.getContainerInfo()
+                .getNetworkSettings()
+                .getNetworks()
+                .values()
+                .iterator()
+                .next()
+                .getIpAddress();
+    }
+
+    private static String clusterStartupCommand() {
+        return "set -eu; "
+                + "IP=$(hostname -i | awk '{print $1}'); "
+                + "for PORT in 7000 7001 7002; do "
+                + "mkdir -p /data/$PORT; "
+                + "printf 'port %s\\nbind 0.0.0.0\\nprotected-mode no\\n"
+                + "cluster-enabled yes\\ncluster-config-file nodes-%s.conf\\n"
+                + "cluster-node-timeout 5000\\ncluster-announce-ip %s\\n"
+                + "cluster-announce-port %s\\ncluster-announce-bus-port %s\\n"
+                + "appendonly no\\nsave \"\"\\nlogfile /data/%s/redis.log\\n' "
+                + "$PORT $PORT $IP $PORT $((PORT+10000)) $PORT > /data/$PORT/redis.conf; "
+                + "redis-server /data/$PORT/redis.conf --daemonize yes; "
+                + "done; "
+                + "until redis-cli -p 7000 ping >/dev/null 2>&1; do sleep 0.1; done; "
+                + "redis-cli --cluster create $IP:7000 $IP:7001 $IP:7002 "
+                + "--cluster-replicas 0 --cluster-yes; "
+                + "until redis-cli -p 7000 cluster info | grep -q 'cluster_state:ok'; "
+                + "do sleep 0.1; done; "
+                + "echo CLUSTER_READY; tail -f /dev/null";
+    }
+}
diff --git a/src/test/java/io/github/davidhlp/spring/cache/redis/integration/RedisClusterSlotIntegrationTest.java b/src/test/java/io/github/davidhlp/spring/cache/redis/integration/RedisClusterSlotIntegrationTest.java
new file mode 100644
index 00000000..7a9154b9
--- /dev/null
+++ b/src/test/java/io/github/davidhlp/spring/cache/redis/integration/RedisClusterSlotIntegrationTest.java
@@ -0,0 +1,116 @@
+package io.github.davidhlp.spring.cache.redis.integration;
+
+import io.github.davidhlp.spring.cache.redis.annotation.RedisCacheable;
+import io.github.davidhlp.spring.cache.redis.config.RedisProCacheProperties;
+
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+import org.redisson.api.RedissonClient;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.context.annotation.Import;
+import org.springframework.stereotype.Service;
+
+import java.util.Arrays;
+import java.util.List;
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.TimeUnit;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+/**
+ * Real Redis Cluster proof for cache-key/distributed-lock slot co-location.
+ */
+@SpringBootTest(classes = TestApplication.class)
+@Import(RedisClusterSlotIntegrationTest.ClusterLoadService.class)
+@DisplayName("Redis Cluster Slot Integration Tests")
+class RedisClusterSlotIntegrationTest extends AbstractRedisClusterIntegrationTest {
+
+    private static final String CACHE_NAME = "clusterSlot";
+    private static final String ACTUAL_KEY = "customer-42";
+    private static final String CACHE_KEY = CACHE_NAME + "::" + ACTUAL_KEY;
+
+    @Autowired
+    private ClusterLoadService loadService;
+
+    @Autowired
+    private RedissonClient redissonClient;
+
+    @Autowired
+    private RedisProCacheProperties properties;
+
+    @Test
+    @DisplayName("sync cache PUT pins the live Redisson lock key to the cache key slot")
+    void syncPut_lockAndCacheKeyShareRealClusterSlot() throws Exception {
+        assertThat(properties.getRedis().getMode()).isEqualTo("cluster");
+        assertThat(redissonClient.getConfig().isClusterConfig()).isTrue();
+
+        CompletableFuture<String> load = CompletableFuture.supplyAsync(
+                () -> loadService.load(ACTUAL_KEY));
+        assertThat(loadService.awaitEntered(10, TimeUnit.SECONDS)).isTrue();
+
+        try {
+            String lockKey = awaitLiveLockKey();
+            int cacheSlot = Integer.parseInt(redisCli("cluster", "keyslot", CACHE_KEY));
+            int lockSlot = Integer.parseInt(redisCli("cluster", "keyslot", lockKey));
+
+            assertThat(lockSlot).isEqualTo(cacheSlot);
+            assertThat(redisCli("-c", "exists", CACHE_KEY, lockKey))
+                    .as("two-key command must execute on the Cluster without CROSSSLOT")
+                    .isEqualTo("1");
+        } finally {
+            loadService.release();
+        }
+        assertThat(load.get(10, TimeUnit.SECONDS)).isEqualTo("value-customer-42");
+        assertThat(redisCli("-c", "exists", CACHE_KEY)).isEqualTo("1");
+        assertThat(redisCli("-c", "get", CACHE_KEY)).contains("value-customer-42");
+    }
+
+    private String awaitLiveLockKey() throws Exception {
+        long deadline = System.nanoTime() + TimeUnit.SECONDS.toNanos(10);
+        while (System.nanoTime() < deadline) {
+            for (int port = 7000; port < 7003; port++) {
+                String keys = redisCliAt(port, "--scan", "--pattern",
+                        properties.getSyncLock().getPrefix() + "*");
+                List<String> lockKeys = Arrays.stream(keys.split("\\R"))
+                        .filter(key -> !key.isBlank())
+                        .toList();
+                if (lockKeys.size() == 1) {
+                    return lockKeys.getFirst();
+                }
+            }
+            TimeUnit.MILLISECONDS.sleep(100);
+        }
+        throw new IllegalStateException("No live Redisson lock key observed in Redis Cluster");
+    }
+
+    @Service
+    static class ClusterLoadService {
+
+        private final CountDownLatch entered = new CountDownLatch(1);
+        private final CountDownLatch release = new CountDownLatch(1);
+
+        @RedisCacheable(cacheNames = CACHE_NAME, key = "#key", sync = true, ttl = 60)
+        public String load(String key) {
+            entered.countDown();
+            try {
+                if (!release.await(10, TimeUnit.SECONDS)) {
+                    throw new IllegalStateException("Timed out waiting to release Cluster loader");
+                }
+            } catch (InterruptedException ex) {
+                Thread.currentThread().interrupt();
+                throw new IllegalStateException("Cluster loader interrupted", ex);
+            }
+            return "value-" + key;
+        }
+
+        boolean awaitEntered(long timeout, TimeUnit unit) throws InterruptedException {
+            return entered.await(timeout, unit);
+        }
+
+        void release() {
+            release.countDown();
+        }
+    }
+}
diff --git a/src/test/java/io/github/davidhlp/spring/cache/redis/integration/TestRedisConfiguration.java b/src/test/java/io/github/davidhlp/spring/cache/redis/integration/TestRedisConfiguration.java
index 52222808..743ac963 100644
--- a/src/test/java/io/github/davidhlp/spring/cache/redis/integration/TestRedisConfiguration.java
+++ b/src/test/java/io/github/davidhlp/spring/cache/redis/integration/TestRedisConfiguration.java
@@ -83,16 +83,29 @@ public RedissonClient redissonClient(
 
         RedisProCacheProperties.RedissonProperties redissonProps = properties.getRedisson();
 
-        config.useSingleServer()
-                .setAddress(address)
-                .setDatabase(0)
-                .setConnectionPoolSize(redissonProps.getConnectionPoolSize())
-                .setConnectionMinimumIdleSize(redissonProps.getConnectionMinimumIdleSize())
-                .setIdleConnectionTimeout(redissonProps.getIdleConnectionTimeout())
-                .setConnectTimeout(redissonProps.getConnectTimeout())
-                .setTimeout(redissonProps.getTimeout())
-                .setRetryAttempts(redissonProps.getRetryAttempts())
-                .setRetryInterval(redissonProps.getRetryInterval());
+        if ("cluster".equalsIgnoreCase(properties.getRedis().getMode())) {
+            config.useClusterServers()
+                    .addNodeAddress(properties.getRedis().getClusterNodes().toArray(String[]::new))
+                    .setMasterConnectionPoolSize(redissonProps.getConnectionPoolSize())
+                    .setMasterConnectionMinimumIdleSize(
+                            redissonProps.getConnectionMinimumIdleSize())
+                    .setIdleConnectionTimeout(redissonProps.getIdleConnectionTimeout())
+                    .setConnectTimeout(redissonProps.getConnectTimeout())
+                    .setTimeout(redissonProps.getTimeout())
+                    .setRetryAttempts(redissonProps.getRetryAttempts())
+                    .setRetryInterval(redissonProps.getRetryInterval());
+        } else {
+            config.useSingleServer()
+                    .setAddress(address)
+                    .setDatabase(0)
+                    .setConnectionPoolSize(redissonProps.getConnectionPoolSize())
+                    .setConnectionMinimumIdleSize(redissonProps.getConnectionMinimumIdleSize())
+                    .setIdleConnectionTimeout(redissonProps.getIdleConnectionTimeout())
+                    .setConnectTimeout(redissonProps.getConnectTimeout())
+                    .setTimeout(redissonProps.getTimeout())
+                    .setRetryAttempts(redissonProps.getRetryAttempts())
+                    .setRetryInterval(redissonProps.getRetryInterval());
+        }
 
         return Redisson.create(config);
     }
diff --git a/wiki/mechanisms/breakdown-lock.md b/wiki/mechanisms/breakdown-lock.md
index 017ac28a..80b03977 100644
--- a/wiki/mechanisms/breakdown-lock.md
+++ b/wiki/mechanisms/breakdown-lock.md
@@ -12,9 +12,10 @@ source-files:
   - src/main/java/io/github/davidhlp/spring/cache/redis/protection/breakdown/SyncLockHandler.java
   - src/main/java/io/github/davidhlp/spring/cache/redis/protection/breakdown/DistributedLockManager.java
   - src/main/java/io/github/davidhlp/spring/cache/redis/protection/breakdown/SyncSupport.java
+  - src/test/java/io/github/davidhlp/spring/cache/redis/integration/RedisClusterSlotIntegrationTest.java
 status: stable
 created: 2026-06-21
-updated: 2026-06-28
+updated: 2026-07-26
 ---
 
 # 分布式锁(HandlerOrder 200)
@@ -127,7 +128,11 @@ Redis Cluster 按 slot 分片。旧锁 key = `prefix + key`,可能落到与缓
 - Cluster + key 无 hash-tag:`prefix + "{" + key + "}"`(包裹,使 slot = CRC16(key) = 缓存 key slot);
 - Cluster + key 已含 hash-tag:`prefix + key`(保留)。
 
-测试用 lettuce `SlotHash.getSlot()` 权威校验锁 key 与缓存 key 同 slot。
+单元测试用 lettuce `SlotHash.getSlot()` 校验构造语义；`RedisClusterSlotIntegrationTest`
+再启动真实三主节点 `redis:7` Cluster，经 `@RedisCacheable(sync=true)` 生产路径观察实际
+Redisson 锁 key，断言它与写入的 cache key 返回相同 `CLUSTER KEYSLOT`，并执行双 key
+`EXISTS` 证明没有 `CROSSSLOT`。测试 teardown 还检查 `cluster_state:ok`，防止容器只启动
+却未形成有效 topology。
 
 ## 自定义锁后端
 

From d97f3fd4c9a25beb86f71355a0f9710d8b7be081 Mon Sep 17 00:00:00 2001
From: DavidHLP <lysf15520112973@163.com>
Date: Sun, 26 Jul 2026 01:52:27 +0800
Subject: [PATCH 3/7] feat(migration): add serialization cutover workflow

---
 .ai/issues/issue-5.md                         |  78 ++++
 COMPATIBILITY.md                              |   7 +-
 docs/serialization-migration.md               |  76 ++++
 .../redis/config/RedisProCacheProperties.java |   4 +
 .../config/SerializationPreFlightProbe.java   |   4 +-
 .../serialization/LegacyValueDecoder.java     | 150 ++++++++
 .../SerializationMigrationCli.java            |  65 ++++
 .../SerializationMigrationEngine.java         | 343 ++++++++++++++++++
 .../SerializationMigrationPhase.java          |  15 +
 .../SerializationMigrationProperties.java     |  42 +++
 .../SerializationMigrationReport.java         |  20 +
 ...SerializationMigrationIntegrationTest.java | 266 ++++++++++++++
 .../serialization/LegacyValueDecoderTest.java |  86 +++++
 wiki/modules/configuration.md                 |  13 +-
 wiki/modules/serialization.md                 |  18 +-
 15 files changed, 1179 insertions(+), 8 deletions(-)
 create mode 100644 .ai/issues/issue-5.md
 create mode 100644 docs/serialization-migration.md
 create mode 100644 src/main/java/io/github/davidhlp/spring/cache/redis/serialization/LegacyValueDecoder.java
 create mode 100644 src/main/java/io/github/davidhlp/spring/cache/redis/serialization/SerializationMigrationCli.java
 create mode 100644 src/main/java/io/github/davidhlp/spring/cache/redis/serialization/SerializationMigrationEngine.java
 create mode 100644 src/main/java/io/github/davidhlp/spring/cache/redis/serialization/SerializationMigrationPhase.java
 create mode 100644 src/main/java/io/github/davidhlp/spring/cache/redis/serialization/SerializationMigrationProperties.java
 create mode 100644 src/main/java/io/github/davidhlp/spring/cache/redis/serialization/SerializationMigrationReport.java
 create mode 100644 src/test/java/io/github/davidhlp/spring/cache/redis/integration/SerializationMigrationIntegrationTest.java
 create mode 100644 src/test/java/io/github/davidhlp/spring/cache/redis/serialization/LegacyValueDecoderTest.java

diff --git a/.ai/issues/issue-5.md b/.ai/issues/issue-5.md
new file mode 100644
index 00000000..ba575d6c
--- /dev/null
+++ b/.ai/issues/issue-5.md
@@ -0,0 +1,78 @@
+# Issue #5 — Serialization migration CLI (`shadow-read → dual-write → cutover`)
+
+- **Issue:** https://github.com/DavidHLP/ResiCache/issues/5
+- **Status:** COMMITTED
+- **Priority:** P1 compatibility
+- **Dependencies:** existing envelope serializer and pre-flight probe
+- **External work:** no assignee, comments, branch, or linked PR
+
+## Current findings
+
+- `SecureJacksonRedisSerializer` always writes `VersionEnvelope.CURRENT_VERSION` and rejects/returns null for non-envelope legacy values depending on error policy.
+- `SerializationPreFlightProbe` scans a bounded sample and warns about non-envelope values; it is diagnostic only.
+- `VersionEnvelope` and whitelist/type-id validation are existing security boundaries that migration must not bypass.
+- The requested capability is explicitly a CLI workflow, not only runtime serializer fallback.
+
+## Acceptance criteria
+
+1. Operator-visible CLI supports shadow-read, dual-write, and cutover phases for both `GenericJackson2JsonRedisSerializer` and JDK-serialized legacy values.
+2. Legacy detection and decoding preserve ResiCache whitelist/security policy.
+3. Migration is idempotent, supports partial runs/resume, preserves TTL, and handles mixed legacy/envelope datasets.
+4. Dual-write/partial failure and rollback behavior are explicit and observable.
+5. Cutover does not require cache flush or full-miss deployment.
+6. Real Redis integration tests inspect stored bytes and TTL; target test count > 0 and skipped = 0.
+7. Operator docs specify dry-run, key selection/scope, failure output, and safe rollback.
+
+## Implementation plan
+
+- Trace Redis serialization configuration, cache read/write bytes boundary, and pre-flight probe.
+- Design a bounded CLI migration engine around SCAN batches and compare/idempotent writes; avoid placing migration phase state in the hot serializer path unless acceptance requires it.
+- Use explicit legacy decoder selection and safe conversion to current envelope.
+- Add metrics/log summary with bounded dimensions only.
+- Add real Redis integration matrix for legacy JSON, JDK, mixed data, TTL, partial failure/resume, and corrupted/untrusted payload.
+- Update serialization/configuration/operator docs.
+
+## Files/modules involved
+
+- `src/main/java/.../serialization/**`
+- `src/main/java/.../config/SerializationPreFlightProbe.java`
+- `src/main/java/.../config/RedisProCacheProperties.java`
+- CLI/runner package determined by current Spring Boot packaging conventions
+- serializer unit tests and `integration/*SerializationMigration*IntegrationTest.java`
+- `wiki/modules/serialization.md`, `wiki/modules/configuration.md`, CLI operator guide
+
+## Tests required
+
+- Decoder/security unit tests.
+- CLI planning/dry-run/idempotency tests.
+- Real standalone Redis migration integration matrix with no skips.
+- Full serializer and integration regression.
+
+## Validation result
+
+- Real three-master `redis:7-alpine` Cluster started and remained `cluster_state:ok`.
+- Post-review migration + serializer/security regression: 37 tests, 0 failures, 0 errors, 0 skipped; `BUILD SUCCESS`.
+- The 8 migration ITs prove shadow-read zero writes, dual-write sidecars + TTL + idempotency, bounded partial-run resume, cluster-wide scanning across masters, JDK cutover/backup/rollback, mixed valid/rejected data, dry-run, and refusal to overwrite post-cutover concurrent writes.
+- Generic Jackson/JDK legacy security has 5 focused unit tests, including custom type-property bypass regression and JDK whitelist rejection.
+- `./mvnw -B checkstyle:check`: 0 violations; `git diff --check`: clean.
+
+## Review findings
+
+Independent reviewer jobs failed to yield within the bounded window and were cancelled. The maintainer completed the frozen Standards + Spec checklist in-process. Review found and fixed high-risk GET→SET races in cutover/rollback with single-key Lua compare-and-set, protected missing-source rollback with SET NX, added post-cutover-write refusal, hardened Generic Jackson's custom type-property path, made suffix handling binary-safe, removed raw key logging, iterated all Redis Cluster masters, and made `maxKeys` resumable by counting only not-yet-completed actionable keys.
+
+- **critical/high/medium remaining:** none.
+- Legacy detection: `SerializationPreFlightProbe` + safe decoder identify envelope/Generic Jackson/JDK.
+- Shadow read / dual write / cutover / rollback: all have real Redis Cluster tests and explicit write semantics.
+- Idempotency / partial / mixed-version: completed sidecars do not consume resume quota; envelopes are validated and skipped; mixed valid/rejected values continue with failure counts.
+- Concurrency/failure: CAS refuses concurrent source changes; per-key failures are isolated and counted; CLI exits unsuccessfully when `failed>0`.
+- Observability: bounded `phase`/`outcome` tags only, plus aggregate report; key logs use non-reversible hash fingerprints.
+- Operator UX/docs: dry-run, patterns, limits, phases, deployment boundary, rollback window and sidecar retention documented in `docs/serialization-migration.md` and synchronized wiki/config/compatibility pages.
+- CLI smoke: minimal context starts successfully and reaches the migration engine; without a local Redis it then fails specifically with `RedisConnectionFailureException`, proving bean/config wiring rather than a context error.
+
+## Commit / PR
+
+Local Issue commit: `feat(migration): add serialization cutover workflow`. Remote PR/Issue closure requires GitHub Write Gate approval.
+
+## Remaining work
+
+Include #5 in the final remote-write review package.
diff --git a/COMPATIBILITY.md b/COMPATIBILITY.md
index e6c684ec..97de8e0f 100644
--- a/COMPATIBILITY.md
+++ b/COMPATIBILITY.md
@@ -59,9 +59,10 @@ Builds pass full `verify -B` (tests + JaCoCo 70%/40% gate + Testcontainers-backe
 
 ⚠️ ResiCache serializes values in an internal `{version, payload}` envelope via
 `SecureJackson` for safe deserialization. This is **not** wire-compatible with
-Spring's `GenericJackson2JsonRedisSerializer` or `JdkSerializer`. Existing
-caches must be **migrated** when adopting ResiCache, otherwise the entire cache
-misses on cutover. See [README → Known Limitations](README.md#known-limitations).
+Spring's `GenericJackson2JsonRedisSerializer` or `JdkSerializer`. Existing caches must be **migrated** when adopting ResiCache, otherwise the
+entire cache misses on cutover. Use the bounded shadow-read → dual-write →
+cutover workflow in [Serialization Migration CLI](docs/serialization-migration.md);
+it preserves TTL, supports resumable rollback, and does not require a cache flush.
 
 ## Known limitations
 
diff --git a/docs/serialization-migration.md b/docs/serialization-migration.md
new file mode 100644
index 00000000..39513f97
--- /dev/null
+++ b/docs/serialization-migration.md
@@ -0,0 +1,76 @@
+# Serialization Migration CLI
+
+ResiCache stores values as a `{version,payload}` envelope. Use the standalone
+`SerializationMigrationCli` to migrate Spring-native
+`GenericJackson2JsonRedisSerializer` or `JdkSerializationRedisSerializer`
+values without flushing the cache.
+
+## Safety model
+
+- The CLI is never run during normal application startup.
+- `SHADOW_READ` is the default and performs no writes.
+- Every invocation processes at most `max-keys` not-yet-completed actionable keys;
+  rerun the same phase to resume. Already matching sidecars/envelopes do not consume
+  the next invocation's quota.
+- Sidecars copy the source TTL. `CUTOVER` uses a compare-and-set Lua script with
+  `KEEPTTL`, so it refuses to overwrite a concurrent application write.
+- `ROLLBACK` restores only the envelope produced from its backup. It refuses to
+  overwrite a value written after cutover.
+- Generic Jackson type IDs are checked against
+  `allowed-package-prefixes` before deserialization. JDK streams use a restricted
+  `ObjectInputStream`; proxy classes and classes outside the same whitelist are rejected.
+- Metrics use only bounded `phase` and `outcome` tags under
+  `resicache.serialization.migration.keys`; Redis keys are never tags.
+
+## Phases
+
+| Phase | Source key | Shadow key (`:__resicache_envelope`) | Backup key (`:__resicache_legacy`) |
+|---|---|---|---|
+| `SHADOW_READ` | legacy unchanged | unchanged | unchanged |
+| `DUAL_WRITE` | legacy unchanged | current envelope written | unchanged |
+| `CUTOVER` | compare-and-set to current envelope | unchanged | legacy bytes written |
+| `ROLLBACK` | compare-and-set back to legacy | unchanged | retained for audit/retry |
+
+The migration tool uses sidecars because one Redis key cannot simultaneously
+contain two wire formats. During `DUAL_WRITE`, operators can inspect shadow
+coverage before cutting over.
+
+## Run
+
+Package the project, then launch the CLI with the application runtime classpath:
+
+```bash
+java -cp 'target/ResiCache-0.0.2.jar:app-libs/*' \
+  io.github.davidhlp.spring.cache.redis.serialization.SerializationMigrationCli \
+  --spring.data.redis.host=127.0.0.1 \
+  --spring.data.redis.port=6379 \
+  --resi-cache.serializer.allowed-package-prefixes=com.example.* \
+  --resi-cache.serializer.migration.phase=SHADOW_READ \
+  --resi-cache.serializer.migration.legacy-serializer=GENERIC_JACKSON \
+  --resi-cache.serializer.migration.pattern='users::*' \
+  --resi-cache.serializer.migration.max-keys=1000 \
+  --resi-cache.serializer.migration.batch-size=100
+```
+
+For JDK data, use `--resi-cache.serializer.migration.legacy-serializer=JDK`.
+Add `--resi-cache.serializer.migration.dry-run=true` to validate a write phase
+without changing Redis.
+
+## Operator sequence
+
+1. Run `SHADOW_READ`; fix every rejected type or narrow the key pattern.
+2. Run `DUAL_WRITE` repeatedly until the report shows no failures and shadow
+   coverage is complete for the bounded scope.
+3. Stop legacy writers or otherwise enforce a deployment boundary.
+4. Run `CUTOVER` repeatedly. Concurrently changed keys fail safely and can be
+   retried after resolving ownership.
+5. Deploy ResiCache readers. Keep backup keys through the rollback window.
+6. If rollback is required, select `ROLLBACK` with the same pattern, legacy
+   serializer and suffix configuration. Post-cutover application writes are not
+   overwritten.
+7. After the rollback window, remove sidecars under an audited retention policy;
+   the CLI deliberately does not auto-delete recovery data.
+
+A non-zero failed count makes the CLI exit unsuccessfully. The log summary has
+`scanned`, `envelopes`, `decodedLegacy`, `written`, `skippedSidecars`, and
+`failed` counts but does not log values.
diff --git a/src/main/java/io/github/davidhlp/spring/cache/redis/config/RedisProCacheProperties.java b/src/main/java/io/github/davidhlp/spring/cache/redis/config/RedisProCacheProperties.java
index 2972af02..37b91ba3 100644
--- a/src/main/java/io/github/davidhlp/spring/cache/redis/config/RedisProCacheProperties.java
+++ b/src/main/java/io/github/davidhlp/spring/cache/redis/config/RedisProCacheProperties.java
@@ -2,6 +2,7 @@
 
 import jakarta.validation.constraints.Min;
 import jakarta.validation.constraints.NotNull;
+import io.github.davidhlp.spring.cache.redis.serialization.SerializationMigrationProperties;
 import lombok.Getter;
 import lombok.Setter;
 import org.springframework.boot.context.properties.ConfigurationProperties;
@@ -130,6 +131,9 @@ public static class SerializerProperties {
         private boolean probeEnabled = false;
         /** pre-flight 探测的采样 key 数上限(默认 100)。 */
         private int probeSampleSize = 100;
+        /** operator CLI migration workflow settings; never auto-executed at application startup. */
+        private SerializationMigrationProperties migration =
+                new SerializationMigrationProperties();
     }
 
     /**
diff --git a/src/main/java/io/github/davidhlp/spring/cache/redis/config/SerializationPreFlightProbe.java b/src/main/java/io/github/davidhlp/spring/cache/redis/config/SerializationPreFlightProbe.java
index 0bba24a6..aad7f991 100644
--- a/src/main/java/io/github/davidhlp/spring/cache/redis/config/SerializationPreFlightProbe.java
+++ b/src/main/java/io/github/davidhlp/spring/cache/redis/config/SerializationPreFlightProbe.java
@@ -89,7 +89,7 @@ void scanAndReport() {
                 "[ResiCache] Serialization pre-flight probe found {}/{} sampled Redis keys whose values are NOT "
                     + "in ResiCache's {{version,payload}} envelope format (ADR-0003). These will fail to deserialize "
                     + "and miss on cutover. Migrate legacy caches before relying on them; a shadow→dual-write→cutover "
-                    + "tool is planned for v0.2.0. (sample-size={}, set resi-cache.serializer.probe-enabled=false "
+                    + "CLI is available; start with SHADOW_READ. (sample-size={}, set resi-cache.serializer.probe-enabled=false "
                     + "to silence)",
                     nonEnvelope, scanned, sampleSize);
         }
@@ -99,7 +99,7 @@ void scanAndReport() {
      * 检测 bytes 是否为 ResiCache envelope(JSON object 含 {@code version} + {@code payload} 字段)。
      * 非 JSON(如 JDK 序列化)或缺少这两个字段的 JSON 视为非 envelope(遗留/外来格式)。
      */
-    static boolean isEnvelope(byte[] bytes) {
+    public static boolean isEnvelope(byte[] bytes) {
         if (bytes == null || bytes.length == 0) {
             return false;
         }
diff --git a/src/main/java/io/github/davidhlp/spring/cache/redis/serialization/LegacyValueDecoder.java b/src/main/java/io/github/davidhlp/spring/cache/redis/serialization/LegacyValueDecoder.java
new file mode 100644
index 00000000..418a3b1d
--- /dev/null
+++ b/src/main/java/io/github/davidhlp/spring/cache/redis/serialization/LegacyValueDecoder.java
@@ -0,0 +1,150 @@
+package io.github.davidhlp.spring.cache.redis.serialization;
+
+import com.fasterxml.jackson.core.JsonParser;
+import com.fasterxml.jackson.core.JsonToken;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.cfg.MapperConfig;
+import com.fasterxml.jackson.databind.jsontype.BasicPolymorphicTypeValidator;
+import com.fasterxml.jackson.databind.jsontype.BasicPolymorphicTypeValidator.TypeMatcher;
+import org.springframework.data.redis.serializer.GenericJackson2JsonRedisSerializer;
+import org.springframework.data.redis.serializer.SerializationException;
+
+import java.io.ByteArrayInputStream;
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.InvalidClassException;
+import java.io.ObjectInputStream;
+import java.io.ObjectStreamClass;
+import java.util.List;
+
+/**
+ * Decodes legacy values without relaxing ResiCache's type whitelist.
+ */
+final class LegacyValueDecoder {
+
+    private static final int JAVA_STREAM_MAGIC = 0xACED;
+
+    private final String typeProperty;
+    private final WhitelistPolicy whitelistPolicy;
+    private final ObjectMapper validationMapper;
+    private final GenericJackson2JsonRedisSerializer genericJackson;
+
+    LegacyValueDecoder(ObjectMapper objectMapper, List<String> allowedPackagePrefixes,
+                       String typeProperty) {
+        this.typeProperty = typeProperty;
+        this.whitelistPolicy = new WhitelistPolicy(allowedPackagePrefixes);
+        this.validationMapper = objectMapper.copy();
+        ObjectMapper legacyMapper = objectMapper.copy();
+        BasicPolymorphicTypeValidator validator = BasicPolymorphicTypeValidator.builder()
+                .allowIfSubType(new TypeMatcher() {
+                    @Override
+                    public boolean match(MapperConfig<?> config, Class<?> subtype) {
+                        return whitelistPolicy.isClassAllowed(subtype);
+                    }
+                })
+                .build();
+        legacyMapper.activateDefaultTypingAsProperty(
+                validator, ObjectMapper.DefaultTyping.EVERYTHING, "@class");
+        GenericJackson2JsonRedisSerializer.registerNullValueSerializer(legacyMapper, "@class");
+        this.genericJackson = new GenericJackson2JsonRedisSerializer(legacyMapper);
+    }
+
+    Object decode(byte[] bytes, SerializationMigrationProperties.LegacySerializer serializer) {
+        if (bytes == null || bytes.length == 0) {
+            throw new SerializationException("Legacy value is empty");
+        }
+        return switch (serializer) {
+            case GENERIC_JACKSON -> decodeGenericJackson(bytes);
+            case JDK -> decodeJdk(bytes);
+        };
+    }
+
+    private Object decodeGenericJackson(byte[] bytes) {
+        validateJsonTypeIds(bytes);
+        Object value = genericJackson.deserialize(bytes);
+        requireAllowedValue(value);
+        return value;
+    }
+
+    private Object decodeJdk(byte[] bytes) {
+        if (bytes.length < 2 || (bytes[0] & 0xFF) != (JAVA_STREAM_MAGIC >>> 8)
+                || (bytes[1] & 0xFF) != (JAVA_STREAM_MAGIC & 0xFF)) {
+            throw new SerializationException("Legacy value is not a JDK serialization stream");
+        }
+        try (RestrictedObjectInputStream input =
+                     new RestrictedObjectInputStream(new ByteArrayInputStream(bytes))) {
+            Object value = input.readObject();
+            requireAllowedValue(value);
+            return value;
+        } catch (IOException | ClassNotFoundException ex) {
+            throw new SerializationException("Could not safely decode JDK legacy value", ex);
+        }
+    }
+
+    private void validateJsonTypeIds(byte[] bytes) {
+        try (JsonParser parser = validationMapper.createParser(bytes)) {
+            boolean expectsTypeValue = false;
+            JsonToken token;
+            while ((token = parser.nextToken()) != null) {
+                if (token == JsonToken.FIELD_NAME) {
+                    expectsTypeValue = typeProperty.equals(parser.currentName())
+                            || "@class".equals(parser.currentName());
+                } else if (expectsTypeValue && token == JsonToken.VALUE_STRING) {
+                    requireAllowedClassName(parser.getText());
+                    expectsTypeValue = false;
+                } else if (expectsTypeValue && token.isScalarValue()) {
+                    throw new SerializationException("Legacy type id must be a string");
+                }
+            }
+        } catch (SerializationException ex) {
+            throw ex;
+        } catch (IOException ex) {
+            throw new SerializationException("Legacy JSON is malformed", ex);
+        }
+    }
+
+    private void requireAllowedValue(Object value) {
+        if (value != null && !whitelistPolicy.isClassAllowed(value.getClass())) {
+            throw new SerializationException("Legacy value type is not in deserialization whitelist: "
+                    + value.getClass().getName());
+        }
+    }
+
+    private void requireAllowedClassName(String className) {
+        if (!whitelistPolicy.isClassNameAllowed(className)) {
+            throw new SerializationException(
+                    "Legacy type is not in deserialization whitelist: " + className);
+        }
+    }
+
+    private final class RestrictedObjectInputStream extends ObjectInputStream {
+
+        RestrictedObjectInputStream(InputStream input) throws IOException {
+            super(input);
+        }
+
+        @Override
+        protected Class<?> resolveClass(ObjectStreamClass descriptor)
+                throws IOException, ClassNotFoundException {
+            String className = descriptor.getName();
+            if (className.startsWith("[")) {
+                Class<?> arrayClass = super.resolveClass(descriptor);
+                Class<?> component = arrayClass;
+                while (component.isArray()) {
+                    component = component.getComponentType();
+                }
+                if (component.isPrimitive() || whitelistPolicy.isClassAllowed(component)) {
+                    return arrayClass;
+                }
+                throw new InvalidClassException("Legacy array type is not in whitelist", className);
+            }
+            requireAllowedClassName(className);
+            return super.resolveClass(descriptor);
+        }
+
+        @Override
+        protected Class<?> resolveProxyClass(String[] interfaces) throws IOException {
+            throw new InvalidClassException("Proxy classes are not allowed in legacy values");
+        }
+    }
+}
diff --git a/src/main/java/io/github/davidhlp/spring/cache/redis/serialization/SerializationMigrationCli.java b/src/main/java/io/github/davidhlp/spring/cache/redis/serialization/SerializationMigrationCli.java
new file mode 100644
index 00000000..55387563
--- /dev/null
+++ b/src/main/java/io/github/davidhlp/spring/cache/redis/serialization/SerializationMigrationCli.java
@@ -0,0 +1,65 @@
+package io.github.davidhlp.spring.cache.redis.serialization;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import io.github.davidhlp.spring.cache.redis.config.RedisProCacheProperties;
+import org.springframework.boot.autoconfigure.EnableAutoConfiguration;
+import org.springframework.boot.context.properties.EnableConfigurationProperties;
+import org.springframework.boot.Banner;
+import org.springframework.boot.WebApplicationType;
+import org.springframework.boot.builder.SpringApplicationBuilder;
+import org.springframework.context.ConfigurableApplicationContext;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Import;
+
+/**
+ * Standalone operator entry point for serialization migration.
+ *
+ * <p>Example:
+ * <pre>{@code
+ * java -cp resicache.jar:app-libs/* \
+ *   io.github...SerializationMigrationCli \
+ *   --spring.data.redis.host=localhost \
+ *   --resi-cache.serializer.migration.phase=SHADOW_READ
+ * }</pre>
+ */
+public final class SerializationMigrationCli {
+
+    private SerializationMigrationCli() {
+    }
+
+    public static void main(String[] args) {
+        try (ConfigurableApplicationContext context = new SpringApplicationBuilder(
+                CliConfiguration.class)
+                .web(WebApplicationType.NONE)
+                .bannerMode(Banner.Mode.OFF)
+                .properties(
+                        "spring.main.lazy-initialization=true",
+                        "spring.autoconfigure.exclude="
+                                + "io.github.davidhlp.spring.cache.redis.config."
+                                + "RedisCacheAutoConfiguration")
+                .run(args)) {
+            SerializationMigrationReport report =
+                    context.getBean(SerializationMigrationEngine.class).migrate();
+            if (report.failed() > 0) {
+                throw new IllegalStateException(
+                        "Serialization migration completed with rejected/failed keys: "
+                                + report.failed());
+            }
+        }
+    }
+
+    /** Minimal CLI context: Redis connection + migration beans, no cache/AOP runtime. */
+    @Configuration(proxyBeanMethods = false)
+    @EnableAutoConfiguration
+    @EnableConfigurationProperties(RedisProCacheProperties.class)
+    @Import({SecureJacksonSerializerFactory.class, SerializationMigrationEngine.class})
+    static class CliConfiguration {
+        @Bean
+        @ConditionalOnMissingBean(ObjectMapper.class)
+        ObjectMapper objectMapper() {
+            return new ObjectMapper();
+        }
+    }
+}
diff --git a/src/main/java/io/github/davidhlp/spring/cache/redis/serialization/SerializationMigrationEngine.java b/src/main/java/io/github/davidhlp/spring/cache/redis/serialization/SerializationMigrationEngine.java
new file mode 100644
index 00000000..582e4a27
--- /dev/null
+++ b/src/main/java/io/github/davidhlp/spring/cache/redis/serialization/SerializationMigrationEngine.java
@@ -0,0 +1,343 @@
+package io.github.davidhlp.spring.cache.redis.serialization;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import io.github.davidhlp.spring.cache.redis.config.RedisProCacheProperties;
+import io.github.davidhlp.spring.cache.redis.config.SerializationPreFlightProbe;
+import io.micrometer.core.instrument.MeterRegistry;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.beans.factory.ObjectProvider;
+import org.springframework.data.redis.connection.RedisConnection;
+import org.springframework.data.redis.connection.RedisConnectionFactory;
+import org.springframework.data.redis.connection.RedisClusterConnection;
+import org.springframework.data.redis.connection.RedisClusterNode;
+import org.springframework.data.redis.connection.RedisStringCommands.SetOption;
+import org.springframework.data.redis.connection.ReturnType;
+import org.springframework.data.redis.core.Cursor;
+import org.springframework.data.redis.core.ScanOptions;
+import org.springframework.data.redis.core.types.Expiration;
+import org.springframework.stereotype.Component;
+
+import java.nio.charset.StandardCharsets;
+import java.util.Arrays;
+
+/**
+ * Bounded, resumable legacy-value migration engine used by the operator CLI.
+ */
+@Slf4j
+@Component
+public class SerializationMigrationEngine {
+
+    static final String METRIC_NAME = "resicache.serialization.migration.keys";
+    private static final byte[] COMPARE_AND_REPLACE = ("if redis.call('get', KEYS[1]) == ARGV[1] "
+            + "then redis.call('set', KEYS[1], ARGV[2], 'KEEPTTL'); return 1 else return 0 end")
+            .getBytes(StandardCharsets.UTF_8);
+
+    private final RedisConnectionFactory connectionFactory;
+    private final SecureJacksonRedisSerializer currentSerializer;
+    private final LegacyValueDecoder legacyDecoder;
+    private final SerializationMigrationProperties migration;
+    private final MeterRegistry meterRegistry;
+
+    public SerializationMigrationEngine(
+            RedisConnectionFactory connectionFactory,
+            ObjectMapper objectMapper,
+            RedisProCacheProperties properties,
+            SecureJacksonSerializerFactory serializerFactory,
+            ObjectProvider<MeterRegistry> meterRegistryProvider) {
+        this.connectionFactory = connectionFactory;
+        var serializer = properties.getSerializer();
+        this.currentSerializer = serializerFactory.create(objectMapper, serializer);
+        this.legacyDecoder = new LegacyValueDecoder(
+                objectMapper, serializer.getAllowedPackagePrefixes(), serializer.getTypeProperty());
+        this.migration = serializer.getMigration();
+        this.meterRegistry = meterRegistryProvider.getIfAvailable();
+    }
+
+    /**
+     * Execute the configured phase once, up to {@code maxKeys} source keys.
+     *
+     * @return immutable operator summary
+     */
+    public SerializationMigrationReport migrate() {
+        validateSettings();
+        MutableReport report = new MutableReport();
+        try (RedisConnection connection = connectionFactory.getConnection()) {
+            if (migration.getPhase() == SerializationMigrationPhase.ROLLBACK) {
+                rollback(connection, report);
+            } else {
+                migrateForward(connection, report);
+            }
+        }
+        SerializationMigrationReport result = report.freeze();
+        log.info("[ResiCache] Serialization migration complete: phase={}, dryRun={}, "
+                        + "scanned={}, envelopes={}, decodedLegacy={}, written={}, "
+                        + "skippedSidecars={}, failed={}",
+                migration.getPhase(), migration.isDryRun(), result.scanned(), result.envelopes(),
+                result.decodedLegacy(), result.written(), result.skippedSidecars(), result.failed());
+        return result;
+    }
+
+    private void migrateForward(RedisConnection connection, MutableReport report) {
+        scan(connection, migration.getPattern(), report, (key) -> {
+            if (isSidecar(key)) {
+                report.skippedSidecars++;
+                record("skipped");
+                return;
+            }
+            report.scanned++;
+            migrateSource(connection, key, report);
+        });
+    }
+
+    private void migrateSource(RedisConnection connection, byte[] key, MutableReport report) {
+        try {
+            byte[] legacyBytes = connection.stringCommands().get(key);
+            if (legacyBytes == null || legacyBytes.length == 0) {
+                return;
+            }
+            if (SerializationPreFlightProbe.isEnvelope(legacyBytes)) {
+                currentSerializer.deserialize(legacyBytes);
+                report.envelopes++;
+                record("envelope");
+                return;
+            }
+            Object legacyValue = legacyDecoder.decode(
+                    legacyBytes, migration.getLegacySerializer());
+            byte[] envelopeBytes = currentSerializer.serialize(legacyValue);
+            if (migration.getPhase() == SerializationMigrationPhase.DUAL_WRITE
+                    && Arrays.equals(connection.stringCommands().get(
+                            appendSuffix(key, migration.getShadowSuffix())), envelopeBytes)) {
+                return;
+            }
+            report.selected++;
+            report.decodedLegacy++;
+            record("decoded");
+
+            switch (migration.getPhase()) {
+                case SHADOW_READ -> { }
+                case DUAL_WRITE -> writeSidecar(
+                        connection, key, migration.getShadowSuffix(), envelopeBytes, report, true);
+                case CUTOVER -> cutover(connection, key, legacyBytes, envelopeBytes, report);
+                case ROLLBACK -> throw new IllegalStateException("ROLLBACK uses backup scan");
+                default -> throw new IllegalStateException(
+                        "Unsupported migration phase: " + migration.getPhase());
+            }
+        } catch (Exception ex) {
+            report.failed++;
+            record("failed");
+            log.warn("[ResiCache] Serialization migration rejected key fingerprint={}: {}",
+                    keyFingerprint(key), ex.getMessage());
+        }
+    }
+
+    private void cutover(RedisConnection connection, byte[] key, byte[] legacyBytes,
+                         byte[] envelopeBytes, MutableReport report) {
+        writeSidecar(connection, key, migration.getBackupSuffix(), legacyBytes, report, true);
+        if (migration.isDryRun()) {
+            return;
+        }
+        if (!compareAndReplace(connection, key, legacyBytes, envelopeBytes)) {
+            throw new IllegalStateException("Source value changed concurrently during cutover");
+        }
+        report.written++;
+        record("written");
+    }
+
+    private void rollback(RedisConnection connection, MutableReport report) {
+        scan(connection, migration.getPattern() + migration.getBackupSuffix(), report,
+                backupKey -> rollbackBackup(connection, backupKey, report));
+    }
+
+    private void rollbackBackup(RedisConnection connection, byte[] backupKey,
+                                MutableReport report) {
+        report.scanned++;
+        try {
+            byte[] legacyBytes = connection.stringCommands().get(backupKey);
+            if (legacyBytes == null) {
+                return;
+            }
+            byte[] sourceKey = removeSuffix(backupKey, migration.getBackupSuffix());
+            byte[] current = connection.stringCommands().get(sourceKey);
+            if (Arrays.equals(current, legacyBytes)) {
+                return;
+            }
+            report.selected++;
+            Object legacyValue = legacyDecoder.decode(legacyBytes, migration.getLegacySerializer());
+            byte[] expectedEnvelope = currentSerializer.serialize(legacyValue);
+            if (!migration.isDryRun()) {
+                restoreSource(connection, sourceKey, backupKey, expectedEnvelope, legacyBytes);
+                report.written++;
+                record("written");
+            }
+        } catch (Exception ex) {
+            report.failed++;
+            record("failed");
+            log.warn("[ResiCache] Serialization rollback rejected key fingerprint={}: {}",
+                    keyFingerprint(backupKey), ex.getMessage());
+        }
+    }
+
+    private void restoreSource(RedisConnection connection, byte[] sourceKey, byte[] backupKey,
+                               byte[] expectedEnvelope, byte[] legacyBytes) {
+        byte[] current = connection.stringCommands().get(sourceKey);
+        if (current == null) {
+            Boolean restored = connection.stringCommands().set(
+                    sourceKey, legacyBytes, expirationOf(connection, backupKey),
+                    SetOption.SET_IF_ABSENT);
+            if (!Boolean.TRUE.equals(restored)) {
+                throw new IllegalStateException("Source appeared concurrently; rollback refused");
+            }
+        } else if (!compareAndReplace(connection, sourceKey, expectedEnvelope, legacyBytes)) {
+            throw new IllegalStateException("Source value changed after cutover; rollback refused");
+        }
+    }
+
+    private void scan(RedisConnection connection, String pattern, MutableReport report,
+                      KeyConsumer consumer) {
+        ScanOptions options = ScanOptions.scanOptions()
+                .match(pattern)
+                .count(migration.getBatchSize())
+                .build();
+        if (connection instanceof RedisClusterConnection cluster) {
+            for (RedisClusterNode node : cluster.clusterCommands().clusterGetNodes()) {
+                if (!node.isMaster() || node.isMarkedAsFail()) {
+                    continue;
+                }
+                try (Cursor<byte[]> cursor = cluster.scan(node, options)) {
+                    consume(cursor, report, consumer);
+                }
+                if (report.selected >= migration.getMaxKeys()) {
+                    return;
+                }
+            }
+        } else {
+            try (Cursor<byte[]> cursor = connection.keyCommands().scan(options)) {
+                consume(cursor, report, consumer);
+            }
+        }
+    }
+
+    private void consume(Cursor<byte[]> cursor, MutableReport report, KeyConsumer consumer) {
+        while (cursor.hasNext() && report.selected < migration.getMaxKeys()) {
+            consumer.accept(cursor.next());
+        }
+    }
+
+    private void writeSidecar(RedisConnection connection, byte[] sourceKey, String suffix,
+                              byte[] value, MutableReport report, boolean overwrite) {
+        byte[] targetKey = appendSuffix(sourceKey, suffix);
+        byte[] existing = connection.stringCommands().get(targetKey);
+        if (Arrays.equals(existing, value)) {
+            return;
+        }
+        if (existing != null && !overwrite) {
+            return;
+        }
+        if (migration.isDryRun()) {
+            return;
+        }
+        Boolean stored = connection.stringCommands().set(
+                targetKey, value, expirationOf(connection, sourceKey), SetOption.UPSERT);
+        if (!Boolean.TRUE.equals(stored)) {
+            throw new IllegalStateException("Redis did not write migration sidecar");
+        }
+        report.written++;
+        record("written");
+    }
+
+    private boolean compareAndReplace(RedisConnection connection, byte[] key,
+                                      byte[] expected, byte[] replacement) {
+        Long replaced = connection.scriptingCommands().eval(
+                COMPARE_AND_REPLACE, ReturnType.INTEGER, 1, key, expected, replacement);
+        return Long.valueOf(1L).equals(replaced);
+    }
+
+    private Expiration expirationOf(RedisConnection connection, byte[] key) {
+        Long ttlMillis = connection.keyCommands().pTtl(key);
+        if (ttlMillis == null || ttlMillis == -1) {
+            return Expiration.persistent();
+        }
+        if (ttlMillis <= 0) {
+            throw new IllegalStateException("Source key expired during migration");
+        }
+        return Expiration.milliseconds(ttlMillis);
+    }
+
+    private boolean isSidecar(byte[] key) {
+        return endsWith(key, migration.getShadowSuffix())
+                || endsWith(key, migration.getBackupSuffix());
+    }
+
+    private void validateSettings() {
+        if (migration.getMaxKeys() < 1 || migration.getBatchSize() < 1) {
+            throw new IllegalArgumentException("migration maxKeys and batchSize must be positive");
+        }
+        if (migration.getPattern() == null || migration.getPattern().isBlank()) {
+            throw new IllegalArgumentException("migration pattern must not be blank");
+        }
+        if (migration.getShadowSuffix() == null || migration.getShadowSuffix().isBlank()
+                || migration.getBackupSuffix() == null || migration.getBackupSuffix().isBlank()
+                || migration.getShadowSuffix().equals(migration.getBackupSuffix())) {
+            throw new IllegalArgumentException("migration sidecar suffixes must be non-empty and distinct");
+        }
+    }
+
+    private void record(String outcome) {
+        if (meterRegistry != null) {
+            meterRegistry.counter(METRIC_NAME,
+                    "phase", migration.getPhase().name(), "outcome", outcome).increment();
+        }
+    }
+
+    private static byte[] appendSuffix(byte[] key, String suffix) {
+        byte[] suffixBytes = suffix.getBytes(StandardCharsets.UTF_8);
+        byte[] result = Arrays.copyOf(key, key.length + suffixBytes.length);
+        System.arraycopy(suffixBytes, 0, result, key.length, suffixBytes.length);
+        return result;
+    }
+
+    private static byte[] removeSuffix(byte[] key, String suffix) {
+        byte[] suffixBytes = suffix.getBytes(StandardCharsets.UTF_8);
+        if (!endsWith(key, suffix)) {
+            throw new IllegalArgumentException("Migration key does not end with expected suffix");
+        }
+        return Arrays.copyOf(key, key.length - suffixBytes.length);
+    }
+
+    private static boolean endsWith(byte[] key, String suffix) {
+        byte[] suffixBytes = suffix.getBytes(StandardCharsets.UTF_8);
+        if (key.length < suffixBytes.length) {
+            return false;
+        }
+        for (int index = 0; index < suffixBytes.length; index++) {
+            if (key[key.length - suffixBytes.length + index] != suffixBytes[index]) {
+                return false;
+            }
+        }
+        return true;
+    }
+
+    private static String keyFingerprint(byte[] key) {
+        return Integer.toHexString(Arrays.hashCode(key));
+    }
+
+    @FunctionalInterface
+    private interface KeyConsumer {
+        void accept(byte[] key);
+    }
+
+    private static final class MutableReport {
+        private int scanned;
+        private int selected;
+        private int envelopes;
+        private int decodedLegacy;
+        private int written;
+        private int skippedSidecars;
+        private int failed;
+
+        private SerializationMigrationReport freeze() {
+            return new SerializationMigrationReport(
+                    scanned, envelopes, decodedLegacy, written, skippedSidecars, failed);
+        }
+    }
+}
diff --git a/src/main/java/io/github/davidhlp/spring/cache/redis/serialization/SerializationMigrationPhase.java b/src/main/java/io/github/davidhlp/spring/cache/redis/serialization/SerializationMigrationPhase.java
new file mode 100644
index 00000000..fae3bebb
--- /dev/null
+++ b/src/main/java/io/github/davidhlp/spring/cache/redis/serialization/SerializationMigrationPhase.java
@@ -0,0 +1,15 @@
+package io.github.davidhlp.spring.cache.redis.serialization;
+
+/**
+ * Operator-controlled phases of the legacy serialization migration workflow.
+ */
+public enum SerializationMigrationPhase {
+    /** Decode and validate legacy values without writing Redis. */
+    SHADOW_READ,
+    /** Write current envelopes to sidecar shadow keys while preserving legacy sources. */
+    DUAL_WRITE,
+    /** Back up legacy bytes and replace source values with current envelopes. */
+    CUTOVER,
+    /** Restore source values from cutover backup keys. */
+    ROLLBACK
+}
diff --git a/src/main/java/io/github/davidhlp/spring/cache/redis/serialization/SerializationMigrationProperties.java b/src/main/java/io/github/davidhlp/spring/cache/redis/serialization/SerializationMigrationProperties.java
new file mode 100644
index 00000000..c50e82bb
--- /dev/null
+++ b/src/main/java/io/github/davidhlp/spring/cache/redis/serialization/SerializationMigrationProperties.java
@@ -0,0 +1,42 @@
+package io.github.davidhlp.spring.cache.redis.serialization;
+
+import lombok.Getter;
+import lombok.Setter;
+
+/**
+ * CLI-only serialization migration settings.
+ */
+@Getter
+@Setter
+public class SerializationMigrationProperties {
+
+    /** Migration phase; the safe default performs no writes. */
+    private SerializationMigrationPhase phase = SerializationMigrationPhase.SHADOW_READ;
+
+    /** Redis SCAN match pattern. */
+    private String pattern = "*";
+
+    /** Maximum number of not-yet-completed actionable keys processed per invocation. */
+    private int maxKeys = 1000;
+
+    /** SCAN count hint. */
+    private int batchSize = 100;
+
+    /** Legacy serializer used for non-envelope source values. */
+    private LegacySerializer legacySerializer = LegacySerializer.GENERIC_JACKSON;
+
+    /** Sidecar suffix used by DUAL_WRITE. */
+    private String shadowSuffix = ":__resicache_envelope";
+
+    /** Sidecar suffix used by CUTOVER and ROLLBACK. */
+    private String backupSuffix = ":__resicache_legacy";
+
+    /** If true, report planned writes without mutating Redis. */
+    private boolean dryRun;
+
+    /** Legacy formats supported by the migration CLI. */
+    public enum LegacySerializer {
+        GENERIC_JACKSON,
+        JDK
+    }
+}
diff --git a/src/main/java/io/github/davidhlp/spring/cache/redis/serialization/SerializationMigrationReport.java b/src/main/java/io/github/davidhlp/spring/cache/redis/serialization/SerializationMigrationReport.java
new file mode 100644
index 00000000..6e3cdc7c
--- /dev/null
+++ b/src/main/java/io/github/davidhlp/spring/cache/redis/serialization/SerializationMigrationReport.java
@@ -0,0 +1,20 @@
+package io.github.davidhlp.spring.cache.redis.serialization;
+
+/**
+ * Immutable summary returned by one migration invocation.
+ *
+ * @param scanned          source keys inspected
+ * @param envelopes        source keys already in the current envelope format
+ * @param decodedLegacy    legacy values decoded and accepted by policy
+ * @param written          Redis values written
+ * @param skippedSidecars  shadow/backup keys excluded from source scanning
+ * @param failed           values rejected or operations that failed
+ */
+public record SerializationMigrationReport(
+        int scanned,
+        int envelopes,
+        int decodedLegacy,
+        int written,
+        int skippedSidecars,
+        int failed) {
+}
diff --git a/src/test/java/io/github/davidhlp/spring/cache/redis/integration/SerializationMigrationIntegrationTest.java b/src/test/java/io/github/davidhlp/spring/cache/redis/integration/SerializationMigrationIntegrationTest.java
new file mode 100644
index 00000000..db677b68
--- /dev/null
+++ b/src/test/java/io/github/davidhlp/spring/cache/redis/integration/SerializationMigrationIntegrationTest.java
@@ -0,0 +1,266 @@
+package io.github.davidhlp.spring.cache.redis.integration;
+
+import io.github.davidhlp.spring.cache.redis.config.RedisProCacheProperties;
+import io.github.davidhlp.spring.cache.redis.serialization.SerializationMigrationEngine;
+import io.github.davidhlp.spring.cache.redis.serialization.SerializationMigrationPhase;
+import io.github.davidhlp.spring.cache.redis.serialization.SerializationMigrationProperties;
+import io.github.davidhlp.spring.cache.redis.serialization.SerializationMigrationReport;
+import io.github.davidhlp.spring.cache.redis.config.SerializationPreFlightProbe;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.context.annotation.Import;
+import org.springframework.data.redis.connection.RedisConnection;
+import org.springframework.data.redis.connection.RedisConnectionFactory;
+import org.springframework.data.redis.serializer.GenericJackson2JsonRedisSerializer;
+import org.springframework.data.redis.serializer.JdkSerializationRedisSerializer;
+
+import java.nio.charset.StandardCharsets;
+import java.time.Duration;
+import java.util.concurrent.TimeUnit;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+@SpringBootTest(classes = TestApplication.class)
+@Import(TestRedisConfiguration.class)
+@DisplayName("Serialization Migration Integration Tests")
+class SerializationMigrationIntegrationTest extends AbstractRedisClusterIntegrationTest {
+
+    private static final byte[] JSON_KEY = bytes("migration:json");
+    private static final byte[] JDK_KEY = bytes("migration:jdk");
+    private static final byte[] BAD_KEY = bytes("migration:bad");
+
+    @Autowired
+    private RedisConnectionFactory connectionFactory;
+
+    @Autowired
+    private SerializationMigrationEngine migrationEngine;
+
+    @Autowired
+    private RedisProCacheProperties properties;
+
+    private SerializationMigrationProperties migration;
+
+    @BeforeEach
+    void setUp() throws Exception {
+        migration = properties.getSerializer().getMigration();
+        for (int port = 7000; port < 7003; port++) {
+            redisCliAt(port, "flushdb");
+        }
+        migration.setPattern("migration:*");
+        migration.setBatchSize(20);
+        migration.setMaxKeys(20);
+        migration.setDryRun(false);
+    }
+
+    @Test
+    void shadowRead_decodesLegacyWithoutWriting() {
+        put(JSON_KEY, new GenericJackson2JsonRedisSerializer().serialize("legacy"), 30);
+        migration.setPhase(SerializationMigrationPhase.SHADOW_READ);
+        migration.setLegacySerializer(SerializationMigrationProperties.LegacySerializer.GENERIC_JACKSON);
+
+        SerializationMigrationReport report = migrationEngine.migrate();
+
+        assertThat(report.decodedLegacy()).isEqualTo(1);
+        assertThat(report.written()).isZero();
+        assertThat(raw(JSON_KEY)).isNotNull();
+        assertThat(raw(shadowKey(JSON_KEY))).isNull();
+        assertThat(ttl(JSON_KEY)).isBetween(1L, 30L);
+    }
+
+    @Test
+    void dualWrite_preservesLegacyAndTtlAndIsIdempotent() {
+        byte[] legacy = new GenericJackson2JsonRedisSerializer().serialize("dual");
+        put(JSON_KEY, legacy, 30);
+        migration.setPhase(SerializationMigrationPhase.DUAL_WRITE);
+        migration.setLegacySerializer(SerializationMigrationProperties.LegacySerializer.GENERIC_JACKSON);
+
+        SerializationMigrationReport first = migrationEngine.migrate();
+        SerializationMigrationReport second = migrationEngine.migrate();
+
+        assertThat(raw(JSON_KEY)).isEqualTo(legacy);
+        assertThat(SerializationPreFlightProbe.isEnvelope(raw(shadowKey(JSON_KEY)))).isTrue();
+        assertThat(first.written()).isEqualTo(1);
+        assertThat(second.written()).isZero();
+        assertThat(ttl(shadowKey(JSON_KEY))).isBetween(1L, ttl(JSON_KEY));
+    }
+
+    @Test
+    void dualWriteResumesPastCompletedKeysWhenMaxKeysIsOne() {
+        String first = "migration:resume:first";
+        String second = "migration:resume:second";
+        var serializer = new GenericJackson2JsonRedisSerializer();
+        put(bytes(first), serializer.serialize("first"), 30);
+        put(bytes(second), serializer.serialize("second"), 30);
+        migration.setPhase(SerializationMigrationPhase.DUAL_WRITE);
+        migration.setLegacySerializer(
+                SerializationMigrationProperties.LegacySerializer.GENERIC_JACKSON);
+        migration.setMaxKeys(1);
+
+        SerializationMigrationReport firstRun = migrationEngine.migrate();
+        SerializationMigrationReport secondRun = migrationEngine.migrate();
+
+        assertThat(firstRun.written()).isEqualTo(1);
+        assertThat(secondRun.written()).isEqualTo(1);
+        assertThat(raw(bytes(first + migration.getShadowSuffix()))).isNotNull();
+        assertThat(raw(bytes(second + migration.getShadowSuffix()))).isNotNull();
+    }
+
+    @Test
+    void cutoverBacksUpLegacyKeepsTtlAndRollbackRestores() {
+        byte[] legacy = new JdkSerializationRedisSerializer().serialize("rollback");
+        put(JDK_KEY, legacy, 30);
+        migration.setPhase(SerializationMigrationPhase.CUTOVER);
+        migration.setLegacySerializer(SerializationMigrationProperties.LegacySerializer.JDK);
+
+        SerializationMigrationReport cutover = migrationEngine.migrate();
+
+        assertThat(cutover.written()).isEqualTo(2);
+        assertThat(SerializationPreFlightProbe.isEnvelope(raw(JDK_KEY))).isTrue();
+        assertThat(raw(backupKey(JDK_KEY))).isEqualTo(legacy);
+        assertThat(ttl(JDK_KEY)).isBetween(1L, 30L);
+
+        migration.setPhase(SerializationMigrationPhase.ROLLBACK);
+        SerializationMigrationReport rollback = migrationEngine.migrate();
+
+        assertThat(rollback.written()).isEqualTo(1);
+        assertThat(raw(JDK_KEY)).isEqualTo(legacy);
+        assertThat(ttl(JDK_KEY)).isBetween(1L, 30L);
+    }
+
+    @Test
+    void rollbackRefusesToOverwriteValueWrittenAfterCutover() {
+        byte[] legacy = new GenericJackson2JsonRedisSerializer().serialize("old");
+        put(JSON_KEY, legacy, 30);
+        migration.setPhase(SerializationMigrationPhase.CUTOVER);
+        migration.setLegacySerializer(
+                SerializationMigrationProperties.LegacySerializer.GENERIC_JACKSON);
+        migrationEngine.migrate();
+        byte[] concurrent = new GenericJackson2JsonRedisSerializer().serialize("new-owner");
+        put(JSON_KEY, concurrent, 30);
+
+        migration.setPhase(SerializationMigrationPhase.ROLLBACK);
+        SerializationMigrationReport rollback = migrationEngine.migrate();
+
+        assertThat(rollback.failed()).isEqualTo(1);
+        assertThat(rollback.written()).isZero();
+        assertThat(raw(JSON_KEY)).isEqualTo(concurrent);
+    }
+
+    @Test
+    void mixedDatasetMigratesValidKeysAndReportsRejectedValue() {
+        put(JSON_KEY, new GenericJackson2JsonRedisSerializer().serialize("valid"), 30);
+        put(BAD_KEY, bytes("{\"@class\":\"com.attacker.Gadget\"}"), 30);
+        migration.setPhase(SerializationMigrationPhase.DUAL_WRITE);
+        migration.setLegacySerializer(SerializationMigrationProperties.LegacySerializer.GENERIC_JACKSON);
+
+        SerializationMigrationReport report = migrationEngine.migrate();
+
+        assertThat(report.decodedLegacy()).isEqualTo(1);
+        assertThat(report.written()).isEqualTo(1);
+        assertThat(report.failed()).isEqualTo(1);
+        assertThat(raw(shadowKey(JSON_KEY))).isNotNull();
+        assertThat(raw(shadowKey(BAD_KEY))).isNull();
+    }
+
+    @Test
+    void clusterScanVisitsKeysOwnedByDifferentMasters() throws Exception {
+        String[] keys = findKeysOnDifferentClusterNodes();
+        put(bytes(keys[0]), new GenericJackson2JsonRedisSerializer().serialize("node-a"), 30);
+        put(bytes(keys[1]), new GenericJackson2JsonRedisSerializer().serialize("node-b"), 30);
+        migration.setPhase(SerializationMigrationPhase.SHADOW_READ);
+        migration.setLegacySerializer(
+                SerializationMigrationProperties.LegacySerializer.GENERIC_JACKSON);
+
+        SerializationMigrationReport report = migrationEngine.migrate();
+
+        assertThat(report.decodedLegacy()).isEqualTo(2);
+        assertThat(report.failed()).isZero();
+    }
+
+    @Test
+    void dryRunReportsDecodeButDoesNotWrite() {
+        put(JSON_KEY, new GenericJackson2JsonRedisSerializer().serialize("dry"), 30);
+        migration.setPhase(SerializationMigrationPhase.CUTOVER);
+        migration.setLegacySerializer(SerializationMigrationProperties.LegacySerializer.GENERIC_JACKSON);
+        migration.setDryRun(true);
+
+        SerializationMigrationReport report = migrationEngine.migrate();
+
+        assertThat(report.decodedLegacy()).isEqualTo(1);
+        assertThat(report.written()).isZero();
+        assertThat(SerializationPreFlightProbe.isEnvelope(raw(JSON_KEY))).isFalse();
+        assertThat(raw(backupKey(JSON_KEY))).isNull();
+    }
+
+    private String[] findKeysOnDifferentClusterNodes() throws Exception {
+        String firstKey = null;
+        Integer firstPort = null;
+        for (int index = 0; index < 1000; index++) {
+            String key = "migration:cross-node:" + index;
+            int slot = Integer.parseInt(redisCli("cluster", "keyslot", key));
+            int port = portServingSlot(slot);
+            if (firstPort == null) {
+                firstPort = port;
+                firstKey = key;
+            } else if (firstPort != port) {
+                return new String[]{firstKey, key};
+            }
+        }
+        throw new IllegalStateException("Could not find keys on two Cluster masters");
+    }
+
+    private int portServingSlot(int slot) throws Exception {
+        for (int port = 7000; port < 7003; port++) {
+            String ranges = redisCliAt(port, "cluster", "nodes");
+            String self = ranges.lines().filter(line -> line.contains(" myself,")).findFirst()
+                    .orElseThrow();
+            for (String token : self.split(" ")) {
+                String[] bounds = token.split("-", 2);
+                try {
+                    int start = Integer.parseInt(bounds[0]);
+                    int end = bounds.length == 1 ? start : Integer.parseInt(bounds[1]);
+                    if (slot >= start && slot <= end) {
+                        return port;
+                    }
+                } catch (NumberFormatException ignored) {
+                    // Ignore node metadata tokens.
+                }
+            }
+        }
+        throw new IllegalStateException("No Cluster master serves slot " + slot);
+    }
+
+    private void put(byte[] key, byte[] value, long seconds) {
+        try (RedisConnection connection = connectionFactory.getConnection()) {
+            connection.stringCommands().set(key, value);
+            connection.keyCommands().expire(key, Duration.ofSeconds(seconds));
+        }
+    }
+
+    private byte[] raw(byte[] key) {
+        try (RedisConnection connection = connectionFactory.getConnection()) {
+            return connection.stringCommands().get(key);
+        }
+    }
+
+    private long ttl(byte[] key) {
+        try (RedisConnection connection = connectionFactory.getConnection()) {
+            return connection.keyCommands().ttl(key, TimeUnit.SECONDS);
+        }
+    }
+
+    private byte[] shadowKey(byte[] source) {
+        return bytes(new String(source, StandardCharsets.UTF_8) + migration.getShadowSuffix());
+    }
+
+    private byte[] backupKey(byte[] source) {
+        return bytes(new String(source, StandardCharsets.UTF_8) + migration.getBackupSuffix());
+    }
+
+    private static byte[] bytes(String value) {
+        return value.getBytes(StandardCharsets.UTF_8);
+    }
+}
diff --git a/src/test/java/io/github/davidhlp/spring/cache/redis/serialization/LegacyValueDecoderTest.java b/src/test/java/io/github/davidhlp/spring/cache/redis/serialization/LegacyValueDecoderTest.java
new file mode 100644
index 00000000..5c0bc89c
--- /dev/null
+++ b/src/test/java/io/github/davidhlp/spring/cache/redis/serialization/LegacyValueDecoderTest.java
@@ -0,0 +1,86 @@
+package io.github.davidhlp.spring.cache.redis.serialization;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+import org.springframework.data.redis.serializer.GenericJackson2JsonRedisSerializer;
+import org.springframework.data.redis.serializer.SerializationException;
+
+import java.io.ByteArrayOutputStream;
+import java.io.ObjectOutputStream;
+import java.io.Serializable;
+import java.nio.charset.StandardCharsets;
+import java.util.List;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+@DisplayName("LegacyValueDecoder")
+class LegacyValueDecoderTest {
+
+    private final ObjectMapper objectMapper = new ObjectMapper();
+    private final LegacyValueDecoder decoder = new LegacyValueDecoder(
+            objectMapper, List.of("io.github.davidhlp", "java.lang"), "@class");
+
+    @Test
+    void genericJackson_decodesAllowedValue() {
+        var serializer = new GenericJackson2JsonRedisSerializer();
+        byte[] bytes = serializer.serialize("legacy-json");
+
+        assertThat(decoder.decode(bytes,
+                SerializationMigrationProperties.LegacySerializer.GENERIC_JACKSON))
+                .isEqualTo("legacy-json");
+    }
+
+    @Test
+    void genericJackson_rejectsTypeIdOutsideWhitelistBeforeDeserialization() {
+        byte[] bytes = "{\"@class\":\"com.attacker.Gadget\",\"value\":1}"
+                .getBytes(StandardCharsets.UTF_8);
+
+        assertThatThrownBy(() -> decoder.decode(bytes,
+                SerializationMigrationProperties.LegacySerializer.GENERIC_JACKSON))
+                .isInstanceOf(SerializationException.class)
+                .hasMessageContaining("whitelist");
+    }
+
+    @Test
+    void genericJackson_alwaysChecksLegacyClassPropertyWhenConfiguredPropertyDiffers() {
+        LegacyValueDecoder customPropertyDecoder = new LegacyValueDecoder(
+                objectMapper, List.of("io.github.davidhlp"), "_type");
+        byte[] bytes = "{\"@class\":\"com.attacker.Gadget\",\"value\":1}"
+                .getBytes(StandardCharsets.UTF_8);
+
+        assertThatThrownBy(() -> customPropertyDecoder.decode(bytes,
+                SerializationMigrationProperties.LegacySerializer.GENERIC_JACKSON))
+                .isInstanceOf(SerializationException.class)
+                .hasMessageContaining("whitelist");
+    }
+
+    @Test
+    void jdk_decodesAllowedDomainValue() throws Exception {
+        AllowedValue value = new AllowedValue("legacy-jdk");
+
+        assertThat(decoder.decode(jdkBytes(value),
+                SerializationMigrationProperties.LegacySerializer.JDK))
+                .isEqualTo(value);
+    }
+
+    @Test
+    void jdk_rejectsValueOutsideWhitelist() throws Exception {
+        assertThatThrownBy(() -> decoder.decode(jdkBytes(new java.io.File("/tmp/x")),
+                SerializationMigrationProperties.LegacySerializer.JDK))
+                .isInstanceOf(SerializationException.class)
+                .hasMessageContaining("whitelist");
+    }
+
+    private byte[] jdkBytes(Object value) throws Exception {
+        ByteArrayOutputStream bytes = new ByteArrayOutputStream();
+        try (ObjectOutputStream output = new ObjectOutputStream(bytes)) {
+            output.writeObject(value);
+        }
+        return bytes.toByteArray();
+    }
+
+    private record AllowedValue(String value) implements Serializable {
+    }
+}
diff --git a/wiki/modules/configuration.md b/wiki/modules/configuration.md
index 11991140..a11bd428 100644
--- a/wiki/modules/configuration.md
+++ b/wiki/modules/configuration.md
@@ -12,7 +12,7 @@ source-files:
   - src/main/java/io/github/davidhlp/spring/cache/redis/config/RedisProCacheProperties.java
 status: stable
 created: 2026-06-21
-updated: 2026-06-29
+updated: 2026-07-26
 ---
 
 # 配置体系(`resi-cache.*`)
@@ -84,10 +84,19 @@ Redisson 客户端与 Redis 部署形态(单机/哨兵/集群)配置,由 [[auto-
     polymorphic-typing-enabled: false                # 多态类型开关(默认 false)
     probe-enabled: false                             # 启动期 pre-flight 探测(R31,默认关闭):采样 N keys 检测非 envelope 遗留值 → WARN
     probe-sample-size: 100                           # 探测采样 key 数上限(默认 100)
+    migration:
+      phase: SHADOW_READ                             # SHADOW_READ/DUAL_WRITE/CUTOVER/ROLLBACK
+      legacy-serializer: GENERIC_JACKSON             # 或 JDK
+      pattern: "*"                                   # SCAN MATCH
+      max-keys: 1000                                 # 单次运行有界上限
+      batch-size: 100                                # SCAN count hint
+      dry-run: false                                 # write phase 预演
+      shadow-suffix: ":__resicache_envelope"
+      backup-suffix: ":__resicache_legacy"
 ```
 → [[serialization]],防 Jackson 多态类型攻击。
 
-`probe-enabled`(R31 起,opt-in 默认 `false`):启动期 `SerializationPreFlightProbe`(`@EventListener(ApplicationReadyEvent)`)采样 `probe-sample-size` 个 Redis key,检测非 `{version,payload}` envelope 的遗留值(Spring 原生 / JDK 序列化),发现则发 prominent WARN 提示接入存量项目须清空旧缓存或自行迁移。诊断工具,不松 envelope(ADR-0003);默认关闭因扫描 Redis 是启动副作用。详见 [[serialization]]。
+`probe-enabled`(R31 起,opt-in 默认 `false`):启动期 `SerializationPreFlightProbe`(`@EventListener(ApplicationReadyEvent)`)采样 `probe-sample-size` 个 Redis key,检测非 `{version,payload}` envelope 的遗留值(Spring 原生 / JDK 序列化),发现则发 prominent WARN。迁移由独立 `SerializationMigrationCli` 显式运行,不会随普通应用启动自动执行。`migration.phase` 默认 `SHADOW_READ`(零写入);完整 shadow/dual-write/cutover/rollback、安全和 operator 流程见 [[serialization]] 与 `docs/serialization-migration.md`。
 
 `allowed-package-prefixes` 通配(R9 起):`com.example.*` 匹配 `com.example.Foo` 与任意深度的 `com.example.sub.bar.Qux`(`WhitelistPolicy.matchesPrefix` dot-boundary 保护);literal 前缀如 `com.example` 沿用 `String.startsWith` 语义(intentional,候选 4 dot-boundary 仍 deferred as BREAKING)。
 
diff --git a/wiki/modules/serialization.md b/wiki/modules/serialization.md
index 5c453222..76f3a34b 100644
--- a/wiki/modules/serialization.md
+++ b/wiki/modules/serialization.md
@@ -17,9 +17,11 @@ source-files:
   - src/main/java/io/github/davidhlp/spring/cache/redis/serialization/SecureNullValueDeserializer.java
   - src/main/java/io/github/davidhlp/spring/cache/redis/serialization/VersionEnvelope.java
   - src/main/java/io/github/davidhlp/spring/cache/redis/serialization/SerializationException.java
+  - src/main/java/io/github/davidhlp/spring/cache/redis/serialization/SerializationMigrationEngine.java
+  - src/main/java/io/github/davidhlp/spring/cache/redis/serialization/SerializationMigrationCli.java
 status: stable
 created: 2026-06-21
-updated: 2026-06-29
+updated: 2026-07-26
 ---
 
 # 安全序列化
@@ -98,6 +100,20 @@ public byte[] serializeToBytes(Object value) {
 
 `{version, payload}` 包络,版本字段让 0.0.x → 0.1.x 升级时旧数据能被识别。`STABILITY.md` §3 把 `{version, payload}` 列为 **never-change** wire format——这是 contract 承诺,不是实现细节。
 
+## Legacy serialization migration CLI
+
+`SerializationMigrationCli` 提供旁路、可续跑的四阶段 operator workflow:
+
+- `SHADOW_READ`:只做安全 legacy decode + 报告,零写入;
+- `DUAL_WRITE`:legacy source 保持不变,同 TTL 写 `:__resicache_envelope` sidecar;
+- `CUTOVER`:先保存同 TTL `:__resicache_legacy` backup,再以单 key Lua CAS + `KEEPTTL` 替换 source;
+- `ROLLBACK`:仅当 source 仍等于该 backup 对应 envelope 时 CAS 恢复,拒绝覆盖 cutover 后的新写入。
+
+Generic Jackson legacy 的 `@class` 与配置 type-property 都在反序列化前过
+`WhitelistPolicy`;JDK legacy 使用 restricted `ObjectInputStream`,禁止 proxy 和白名单外类。
+每次运行受 `max-keys` 限制,重复执行幂等续跑;失败数使 CLI 非成功退出。完整 operator
+顺序、dry-run、suffix 和 rollback 窗口见 `docs/serialization-migration.md`。
+
 ## SerializationException
 
 反序列化失败的统一异常类型,由 [[cache-lifecycle]] 的错误处理捕获,降级为 miss 而非向上抛穿业务。

From 86e2128a1111d8799aee5c6d239266914bebe967 Mon Sep 17 00:00:00 2001
From: DavidHLP <lysf15520112973@163.com>
Date: Sun, 26 Jul 2026 01:53:31 +0800
Subject: [PATCH 4/7] docs(issues): record benchmark contributor status

---
 .ai/issues/index.md   | 21 ++++++++++-----
 .ai/issues/issue-2.md |  2 +-
 .ai/issues/issue-3.md | 62 +++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 78 insertions(+), 7 deletions(-)
 create mode 100644 .ai/issues/issue-3.md

diff --git a/.ai/issues/index.md b/.ai/issues/index.md
index bf6eb0d1..0c893238 100644
--- a/.ai/issues/index.md
+++ b/.ai/issues/index.md
@@ -1,17 +1,17 @@
 # ResiCache Open Issue Ledger
 
 Last synchronized: 2026-07-26
-Repository baseline: `main` @ `75ed279a71b17f227c3170d738eb93e50d876c8a` (`origin/main`, ahead 0 / behind 0)
+Repository baseline: `origin/main` @ `75ed279a71b17f227c3170d738eb93e50d876c8a`; local `main` at the current Ledger commit (ahead 4, behind 0)
 GitHub repository: `DavidHLP/ResiCache`
 
 ## Execution order
 
 | Order | Issue | Priority | Status | Dependency / triage |
 |---:|---|---|---|---|
-| 1 | [#4](issue-4.md) Per-handler Micrometer tags | P0 observability | INVESTIGATING | Independent and explicitly highest priority |
-| 2 | [#2](issue-2.md) Redis Cluster slot IT | P1 correctness | DISCOVERED | Validates existing production key construction; must use real Cluster |
-| 3 | [#5](issue-5.md) Serialization migration CLI | P1 compatibility | DISCOVERED | Large migration capability; pre-flight probe already exists |
-| 4 | [#3](issue-3.md) JMH module | P1 performance | DISCOVERED | External contributor declared intent on 2026-07-21 but no PR/branch is linked; review after higher-priority work and re-sync before takeover |
+| 1 | [#4](issue-4.md) Per-handler Micrometer tags | P0 observability | COMMITTED | Independent and explicitly highest priority |
+| 2 | [#2](issue-2.md) Redis Cluster slot IT | P1 correctness | COMMITTED | Validates existing production key construction; must use real Cluster |
+| 3 | [#5](issue-5.md) Serialization migration CLI | P1 compatibility | COMMITTED | Large migration capability; pre-flight probe already exists |
+| 4 | [#3](issue-3.md) JMH module | P1 performance | BLOCKED_EXTERNAL_WORK | External contributor declared intent on 2026-07-21 but no PR/branch is linked; review after higher-priority work and re-sync before takeover |
 
 ## Live GitHub facts
 
@@ -19,7 +19,16 @@ GitHub repository: `DavidHLP/ResiCache`
 - Open PRs: none.
 - Linked closing PRs: none for all four issues.
 - Assignees: none for all four issues.
-- Only active external signal: `Shubh2-0` volunteered for #3 on 2026-07-21; no implementation is currently reviewable.
+- Only active external signal: `Shubh2-0` volunteered for #3 on 2026-07-21; final re-sync still shows no implementation, but the claim remains recent and active.
+- #2/#4/#5 are resolved and committed locally; GitHub remains Open because remote writes require explicit approval.
+
+## Final repository validation
+
+- `PATH=/tmp/resicache-tools:$PATH ./mvnw clean verify -B`: `BUILD SUCCESS`; Maven summary 873 unit tests + 18 integration tests, all 0 failures/errors/skips.
+- Real standalone Redis containers started through a temporary user-space `socat`; real three-master Cluster tests reported `cluster_state:ok`.
+- JaCoCo: line 87.82%, branch 75.33%.
+- `testcontainers-bom:1.20.4` override preserved.
+- Temporary `socat` was extracted under `/tmp/resicache-tools`; not installed system-wide and not committed.
 
 ## Validation gates
 
diff --git a/.ai/issues/issue-2.md b/.ai/issues/issue-2.md
index 2a687558..02635066 100644
--- a/.ai/issues/issue-2.md
+++ b/.ai/issues/issue-2.md
@@ -50,7 +50,7 @@
 - `DistributedLockManagerTest` + Cluster IT: 26 tests, 0 failures, 0 errors, 0 skipped; `BUILD SUCCESS`.
 - Checkstyle: 0 violations; `git diff --check`: clean.
 - The unchanged standalone `DistributedLockIntegrationTest` cannot start its pre-existing WSL2 fixture because this workstation lacks `socat`; rerunning it alone reproduces the same `Cannot start socat` before test execution. The new Cluster fixture does not depend on or weaken that asset.
-- Review and commit pending.
+- Review and commit completed; full repository regression passed.
 
 ## Review findings
 
diff --git a/.ai/issues/issue-3.md b/.ai/issues/issue-3.md
new file mode 100644
index 00000000..4af9fa83
--- /dev/null
+++ b/.ai/issues/issue-3.md
@@ -0,0 +1,62 @@
+# Issue #3 — Minimal JMH module and measured performance baseline
+
+- **Issue:** https://github.com/DavidHLP/ResiCache/issues/3
+- **Status:** BLOCKED_EXTERNAL_WORK
+- **Priority:** P1 performance
+- **Dependencies:** process after correctness/compatibility prerequisites and re-sync external work
+- **External work:** `Shubh2-0` volunteered on 2026-07-21; no assignee, branch, linked PR, or submitted diff exists as of 2026-07-26
+
+## Current findings
+
+- Repository is currently a single Maven module and has no JMH dependency/profile/module.
+- Issue explicitly requests a new `resicache-bench` module, three benchmark suites, and measured `PERFORMANCE.md` values.
+- An intent-only comment is recent enough to re-check before takeover, but there is no code to review now.
+
+## Acceptance criteria
+
+1. A real JMH module/harness is discoverable and runnable independently of normal unit tests.
+2. Benchmarks cover: chain pass-through vs Spring-native `@Cacheable`, per-handler additive cost, and SyncLock throughput under concurrency.
+3. Fixture/bootstrap cost is outside measured operations.
+4. Warmup, measurement, forks, JVM, hardware, and parameters are documented.
+5. `PERFORMANCE.md` contains actual measured results and no guessed SLO.
+6. Standard `./mvnw clean verify -B` remains deterministic and does not run long benchmarks.
+
+## Implementation plan
+
+- Re-sync Issue/PR state immediately before work.
+- If still no PR, choose the smallest Maven multi-module conversion that preserves publishing and coverage behavior.
+- Implement three JMH suites against production paths and a short smoke/discovery command.
+- Run a baseline on the current workstation and document results as environment-specific, not universal promises.
+
+## Files/modules involved
+
+- root `pom.xml`
+- potential core child `pom.xml` only if required by multi-module structure
+- `resicache-bench/pom.xml`
+- `resicache-bench/src/main/java/**` or canonical JMH source layout
+- `PERFORMANCE.md`
+- `wiki/modules/observability.md`
+
+## Tests required
+
+- Benchmark jar/list discoverability.
+- One short JMH smoke for each suite.
+- Normal full verify proving benchmark isolation.
+
+## Validation result
+
+- Re-synced after completing #2/#4/#5: no Open PR, linked PR, assignee, remote benchmark branch, or submitted diff.
+- `Shubh2-0`'s explicit implementation claim from 2026-07-21 remains the latest activity (five days old), so duplicate implementation is not currently legitimate.
+- Full `./mvnw clean verify -B` passes without a JMH module: 873 unit + 18 integration tests, 0 failures/errors/skips. This validates current repository health, not Issue #3 acceptance.
+
+## Review findings
+
+No implementation exists to review. The claimed plan names the required JMH annotation processor, three suites, thread groups, and `PERFORMANCE.md`, matching the Issue direction. Actual benchmark validity remains unverified until a PR exists.
+
+## Commit / PR
+
+Local ledger commit: `docs(issues): record benchmark contributor status`. No GitHub write performed.
+
+## Remaining work
+
+External dependency: wait for `Shubh2-0` to submit or explicitly relinquish the work. Resume by re-reading #3 and Open PRs/remote branches; if the claim becomes stale or abandoned, implement the frozen plan and measure real baselines. A maintainer GitHub comment requesting ETA would be appropriate, but it requires remote-write approval.

From 2a0edcec0107aa83ceee0adfc1e0896ba17c3c26 Mon Sep 17 00:00:00 2001
From: DavidHLP <DavidHLP@users.noreply.github.com>
Date: Mon, 27 Jul 2026 01:24:19 +0800
Subject: [PATCH 5/7] ci(setup): stop forwarding empty server-id to setup-java

The composite action ./.github/actions/setup-jdk-21 unconditionally
forwarded server-id / server-username / server-password / gpg-private-key /
gpg-passphrase inputs to actions/setup-java@v5. Even when those inputs
were the empty-string defaults, setup-java@v5 would write a
<server> block to ~/.m2/settings.xml with <id></id>, and Maven 3.9+
aborts at startup with `servers.server[0].id is missing`.

This was the root cause of PR Quality Checks failing on PR #6
(run 30210117026, job 89814796395) and CI failing on every push to
main/master since 2026-07-03 (ci.yml had not passed on either branch
since the composite was introduced; only release.yml worked because
it passed a non-empty server-id).

Fix:
  - Drop the five deploy inputs from the composite action entirely.
    ci.yml, pr-checks.yml, dependency-check, docs-link-check,
    checkstyle, and build-package now get a clean setup-java call
    that writes no <server> block.
  - release.yml calls actions/setup-java@v5 directly with the same
    deploy inputs it used to pass to the composite. The single
    deploy caller is preserved with no behaviour change on tag push.

Verified locally:
  - python3 yaml.safe_load passes for action.yml, ci.yml,
    pr-checks.yml, release.yml.
  - grep for server-* in ci.yml and pr-checks.yml returns nothing.
  - git diff --check clean.
  - release.yml deploy inputs (server-id=central, OSSRH_*,
    GPG_PRIVATE_KEY, GPG_PASSPHRASE) preserved verbatim.
---
 .github/actions/setup-jdk-21/action.yml | 40 +++++--------------------
 .github/workflows/release.yml           | 10 ++++++-
 2 files changed, 17 insertions(+), 33 deletions(-)

diff --git a/.github/actions/setup-jdk-21/action.yml b/.github/actions/setup-jdk-21/action.yml
index 9b86a284..11a05242 100644
--- a/.github/actions/setup-jdk-21/action.yml
+++ b/.github/actions/setup-jdk-21/action.yml
@@ -8,10 +8,14 @@ description: >-
   composite instead of inlining `setup-java@v5` — single source
   of truth for JDK version + distribution + cache config.
 
-  Optional inputs (server-id, server-username, server-password,
-  gpg-private-key, gpg-passphrase) are pass-through for the
-  release workflow's Maven Central deployment needs. They are
-  not configured by default — only release.yml passes them.
+  Note: This composite intentionally does NOT forward Maven
+  Central / GPG deploy inputs. `actions/setup-java@v5`
+  unconditionally writes a `<server>` block to `~/.m2/settings.xml`
+  even when `server-id` is an empty string, which produces
+  `<server><id></id>…</server>` and causes Maven 3.9+ to abort
+  with `servers.server[0].id is missing`. CI and PR-check jobs
+  must not inherit that block. The release workflow calls
+  `actions/setup-java@v5` directly with deploy inputs.
 
 inputs:
   java-version:
@@ -26,26 +30,6 @@ inputs:
     description: 'Actions dependency cache (maven, gradle, or empty)'
     required: false
     default: 'maven'
-  server-id:
-    description: 'Maven settings.xml server id (release deploy only)'
-    required: false
-    default: ''
-  server-username:
-    description: 'Maven settings.xml server username (release only)'
-    required: false
-    default: ''
-  server-password:
-    description: 'Maven settings.xml server password (release only)'
-    required: false
-    default: ''
-  gpg-private-key:
-    description: 'GPG signing private key (release deploy only)'
-    required: false
-    default: ''
-  gpg-passphrase:
-    description: 'GPG signing passphrase (release deploy only)'
-    required: false
-    default: 'GPG_PASSPHRASE'
 
 runs:
   using: composite
@@ -56,11 +40,3 @@ runs:
         java-version: ${{ inputs.java-version }}
         distribution: ${{ inputs.distribution }}
         cache: ${{ inputs.cache }}
-        # Deploy-secret optional inputs are only forwarded when
-        # non-empty so non-release callers don't accidentally
-        # reference missing secrets in env: settings.
-        server-id: ${{ inputs.server-id }}
-        server-username: ${{ inputs.server-username }}
-        server-password: ${{ inputs.server-password }}
-        gpg-private-key: ${{ inputs.gpg-private-key }}
-        gpg-passphrase: ${{ inputs.gpg-passphrase }}
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index b7810fb9..783c948e 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -25,8 +25,16 @@ jobs:
         uses: actions/checkout@v5
 
       - name: Set up JDK ${{ env.JAVA_VERSION }}
-        uses: ./.github/actions/setup-jdk-21
+        # release.yml is the only workflow that needs Maven Central / GPG
+        # deploy inputs. It calls actions/setup-java@v5 directly so the
+        # CI/PR composite action (./.github/actions/setup-jdk-21) does not
+        # accidentally forward empty server-id into ~/.m2/settings.xml and
+        # break non-deploy jobs with `servers.server[0].id is missing`.
+        uses: actions/setup-java@v5
         with:
+          java-version: ${{ env.JAVA_VERSION }}
+          distribution: temurin
+          cache: maven
           server-id: central
           server-username: OSSRH_USERNAME
           server-password: OSSRH_PASSWORD

From bb02b70203c5a189b9d59854b1c5b7a748ba79c7 Mon Sep 17 00:00:00 2001
From: DavidHLP <DavidHLP@users.noreply.github.com>
Date: Mon, 27 Jul 2026 01:29:08 +0800
Subject: [PATCH 6/7] test(testcontainers): drop DOCKER_API_VERSION=1.54
 override

The properties files in src/test/resources hard-coded
DOCKER_API_VERSION=1.54 (testcontainers.properties) and
api.version=1.54 (docker-java.properties). docker-java 3.4.0 (which
testcontainers-bom 1.20.4 transitively pulls in) accepts that value and
tries to negotiate it with the Docker daemon. The GitHub-hosted
ubuntu-latest runner image reports "Maximum supported API version 1.48"
and rejects the connection with "client version 1.54 is too new", which
cascades into Testcontainers
"IllegalState Previous attempts to find a Docker environment failed.
Will not retry." for every @Testcontainers integration test.

This failure was previously hidden by an earlier CI configuration bug
(composite action wrote <server><id></id> into ~/.m2/settings.xml and
crashed Maven before any test ran). Once that was fixed, the
api.version override surfaced.

Fix: remove the hard-coded override from both files. docker-java 3.4.0
auto-negotiates the highest mutually-supported API version with the
daemon, which works on both the GitHub runner (max 1.48) and any
modern local Docker (we use 1.55 locally). Comments in both files now
explain why we deliberately do not pin a version.

Verified locally: docker-java dependency tree unchanged
(testcontainers 1.20.4 -> docker-java 3.4.0); only the two properties
files are touched.

Refs: PR #6 PR Quality Checks run 30212533645, job 89821091011
(UnixSocketClientProviderStrategy: BadRequestException 400)
---
 src/test/resources/docker-java.properties    | 11 +++++++----
 src/test/resources/testcontainers.properties | 10 +++++++---
 2 files changed, 14 insertions(+), 7 deletions(-)

diff --git a/src/test/resources/docker-java.properties b/src/test/resources/docker-java.properties
index 6149fe85..9033e9de 100644
--- a/src/test/resources/docker-java.properties
+++ b/src/test/resources/docker-java.properties
@@ -1,4 +1,7 @@
-# Docker Java client API version override
-# Required for Docker 29+ which requires minimum API version 1.44
-# The docker-java library defaults to API version 1.32, which is too old
-api.version=1.54
+# docker-java configuration: do NOT pin api.version. testcontainers-bom:1.20.4
+# pulls in docker-java 3.4.0, which auto-negotiates the API with the daemon on
+# first contact. The previous hardcoded `api.version=1.54` broke the GitHub
+# hosted ubuntu-latest runner (Docker engine max API = 1.48,
+# "client version 1.54 is too new") and made every Testcontainers test fail
+# with "Previous attempts to find a Docker environment failed." Leaving the
+# line unset lets docker-java pick the highest mutually-supported version.
diff --git a/src/test/resources/testcontainers.properties b/src/test/resources/testcontainers.properties
index 42c476bf..a947439e 100644
--- a/src/test/resources/testcontainers.properties
+++ b/src/test/resources/testcontainers.properties
@@ -7,6 +7,10 @@
 # (Default is false, but we explicitly set it for clarity)
 testcontainers.reuse.enable=false
 
-# Docker API version override (required for Docker 23+ / API 1.40+)
-# The docker-java library defaults to API version 1.32, which is too old
-DOCKER_API_VERSION=1.54
\ No newline at end of file
+# Docker API version: do NOT pin DOCKER_API_VERSION. testcontainers-bom:1.20.4
+# pulls in docker-java 3.4.0, which auto-negotiates the API with the daemon on
+# first contact. Pinning to 1.54 here broke the GitHub-hosted ubuntu-latest
+# runner (Docker engine max API = 1.48, "client version 1.54 is too new") and
+# made every Testcontainers test fail with
+# "Previous attempts to find a Docker environment failed." Let auto-negotiation
+# handle the version; it works on both the GitHub runner and local WSL2.
\ No newline at end of file

From 2886297b414492335cee0443d5c07392a0636458 Mon Sep 17 00:00:00 2001
From: DavidHLP <DavidHLP@users.noreply.github.com>
Date: Mon, 27 Jul 2026 01:32:15 +0800
Subject: [PATCH 7/7] ci(workflows): install socat on ubuntu-latest before
 running tests

AbstractRedisIntegrationTest shells out to the `socat` binary to forward
the testcontainers container bridge IP back to 127.0.0.1, which the
Spring context then connects to. The Ubuntu GitHub-hosted runner does
not ship socat, so every @Testcontainers IT threw
"IllegalState: Cannot start socat for container 172.17.0.2" before
Spring could even start.

Install socat via apt-get in the build / pr-checks jobs. The other
ci.yml jobs (checkstyle, dependency-check, qodana, docs-link-check,
build-package) do not run integration tests and are left untouched.

Verified locally:
  - python3 yaml.safe_load passes for both ci.yml and pr-checks.yml
  - git diff --check clean
  - the new step lives between Setup JDK and the Maven build, so the
    JDK is in place before apt runs
---
 .github/workflows/ci.yml        | 7 +++++++
 .github/workflows/pr-checks.yml | 8 ++++++++
 .github/workflows/release.yml   | 7 +++++++
 3 files changed, 22 insertions(+)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index c7469ec1..5a2fb5d4 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -25,6 +25,13 @@ jobs:
 
       - name: Set up JDK ${{ env.JAVA_VERSION }}
         uses: ./.github/actions/setup-jdk-21
+      - name: Install socat for integration tests
+        # AbstractRedisIntegrationTest shells out to `socat` to forward the
+        # testcontainers container bridge IP back to 127.0.0.1, which the
+        # Spring context connects to. The Ubuntu runner does not ship socat
+        # by default. Without it every @Testcontainers IT throws
+        # "Cannot start socat for container …" before Spring can start.
+        run: sudo apt-get update -y && sudo apt-get install -y --no-install-recommends socat
 
       - name: Build with Maven Wrapper
         run: ./mvnw clean verify -B
diff --git a/.github/workflows/pr-checks.yml b/.github/workflows/pr-checks.yml
index 38e8c108..d1a1b985 100644
--- a/.github/workflows/pr-checks.yml
+++ b/.github/workflows/pr-checks.yml
@@ -20,6 +20,14 @@ jobs:
       - name: Set up JDK ${{ env.JAVA_VERSION }}
         uses: ./.github/actions/setup-jdk-21
 
+      - name: Install socat for integration tests
+        # AbstractRedisIntegrationTest shells out to `socat` to forward the
+        # testcontainers container bridge IP back to 127.0.0.1, which the
+        # Spring context connects to. The Ubuntu runner does not ship socat
+        # by default. Without it every @Testcontainers IT throws
+        # "Cannot start socat for container …" before Spring can start.
+        run: sudo apt-get update -y && sudo apt-get install -y --no-install-recommends socat
+
       - name: Run All Checks
         run: ./mvnw clean verify checkstyle:check -B
         env:
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 783c948e..018063a2 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -47,6 +47,13 @@ jobs:
 
       - name: Update POM Version
         run: ./mvnw versions:set -DnewVersion=${{ steps.version.outputs.VERSION }} -B
+      - name: Install socat for integration tests
+        # AbstractRedisIntegrationTest shells out to `socat` to forward the
+        # testcontainers container bridge IP back to 127.0.0.1, which the
+        # Spring context connects to. The Ubuntu runner does not ship socat
+        # by default. Without it every @Testcontainers IT throws
+        # "Cannot start socat for container …" before Spring can start.
+        run: sudo apt-get update -y && sudo apt-get install -y --no-install-recommends socat
 
       - name: Build & Test
         run: ./mvnw clean verify -B