feat(redis): flip one-phase txn dedup default to on (closes #937) (#943)

## Summary

Flips `adapter.RedisServer.onePhaseTxnDedup` from default-off to
default-on, closing the rollout of the option-2 idempotency design
landed by
[`docs/design/2026_05_21_proposed_txn_secondary_idempotency.md`](https://github.com/bootjp/elastickv/blob/main/docs/design/2026_05_21_proposed_txn_secondary_idempotency.md).
No new mechanism — the FSM probe (`dedupProbeOnePhase`), the wire change
(`TxnMeta.PrevCommitTS`, V2-only when non-zero), and every adapter-side
reuse path already ship and are exercised every day by the dedup-mode
Jepsen workflow.

Closes #937.

## Authorization

The parent design's `M4` 7-day criterion
([source](https://github.com/bootjp/elastickv/blob/main/docs/design/2026_05_21_proposed_txn_secondary_idempotency.md#m4--validation))
reads:

> 7 consecutive days without `:duplicate-elements` /
`:G-single-item-realtime` in the dedup-mode workflow.


[`jepsen-test-scheduled-dedup.yml`](https://github.com/bootjp/elastickv/blob/main/.github/workflows/jepsen-test-scheduled-dedup.yml)
(Redis stress profile, `ELASTICKV_REDIS_ONEPHASE_DEDUP=1`) has produced
**12 consecutive green runs over 10 calendar days, 2026-05-31 →
2026-06-10**. Run IDs are listed in the new design doc; the most recent
are:

| Date (UTC) | Run | Conclusion |
|---|---|---|
| 2026-06-10 04:50 |
[27253991270](https://github.com/bootjp/elastickv/actions/runs/27253991270)
| success |
| 2026-06-09 04:44 |
[27184402445](https://github.com/bootjp/elastickv/actions/runs/27184402445)
| success |
| 2026-06-08 04:57 |
[27116904871](https://github.com/bootjp/elastickv/actions/runs/27116904871)
| success |
| 2026-06-07 04:54 |
[27083142341](https://github.com/bootjp/elastickv/actions/runs/27083142341)
| success |
| 2026-06-06 04:40 |
[27052820868](https://github.com/bootjp/elastickv/actions/runs/27052820868)
| success |
| 2026-06-05 04:49 |
[26996058409](https://github.com/bootjp/elastickv/actions/runs/26996058409)
| success |
| 2026-06-04 04:57 |
[26931749014](https://github.com/bootjp/elastickv/actions/runs/26931749014)
| success |
| 2026-06-04 04:16 |
[26930308744](https://github.com/bootjp/elastickv/actions/runs/26930308744)
| success |
| 2026-06-03 04:58 |
[26864667493](https://github.com/bootjp/elastickv/actions/runs/26864667493)
| success |
| ...(2 more) | | success |

Exceeds the 7-day threshold. The parent's R5 (FSM determinism across a
rolling upgrade) is discharged — the probe code has shipped on every
production node for months.

## Change

| File | Change |
|---|---|
| `docs/design/2026_06_10_proposed_redis_onephase_dedup_default_on.md` |
New design doc (commit 1) recording M4 evidence and the rollout. |
| `adapter/redis.go` | Flips env-var sense from `== "1"` to `!= "0"`;
updates the comment, godoc, and field comment. |
| `.github/workflows/jepsen-test-scheduled.yml` | Adds explicit
`ELASTICKV_REDIS_ONEPHASE_DEDUP: "0"` to the job env so the control
baseline keeps its meaning across the default change. Retirement of the
control workflow is a 30-day follow-up. |

## Behaviour change

- **Default**: dedup gate is now **on** for any process that does not
opt out.
- **Opt-out**: `ELASTICKV_REDIS_ONEPHASE_DEDUP=0` (single-env-var
rollback, no binary revert). The constructor option
`WithOnePhaseTxnDedup(false)` still trumps the env.
- **Existing opt-in users**: `=1` (the dedup-mode workflow's existing
setting) continues to resolve to `true`. No breakage.

## Risk

| Concern | Disposition |
|---|---|
| Data loss | None — the dedup path only short-circuits on a confirmed
prior commit at the exact `prev_commit_ts` (the parent design's R1 + the
existing `kv/fsm.go` probe). No write is dropped. |
| Concurrency / distributed failures | None — every node already runs
the probe code; no new fanout, no new round-trip. R5 discharged as
above. |
| Performance | Default-on adds the `PrevCommitTS` probe on each
retryable attempt. Cost is one `CommittedVersionAt` MVCC lookup at the
primary key + stale `commit_ts`; this is the same cost the dedup-mode
workflow has been paying for 12 days without regression. No hot-path
allocation change. |
| Data consistency | Improved — the failure modes the parent design
predicted (`:duplicate-elements`, `:future-read`,
`:G-single-item-realtime`) become unreachable on the protected path.
Issue #937 is the most recent control-baseline reproduction. |
| Test coverage | No new branches added; existing
`adapter/redis_*_dedup_test.go` suites cover both gate states. Tests
that construct `&RedisServer{...}` directly (zero-value
`onePhaseTxnDedup`) still observe the legacy path, so the off-path
remains covered at unit level. |

## Verification

- `go vet ./...` — clean
- `go build ./...` — clean
- `go test -run 'Dedup|OnePhase|PrevCommit|Idempot' ./adapter/` — pass
(1.2s)
- `go test -run
'TestRedis|TestList|TestSet|TestZSet|TestStream|TestExec|TestMulti'
./adapter/` — pass (169s)
- `golangci-lint run ./adapter/...` — 0 issues

## Follow-ups

- **30 days post-merge** — review whether `jepsen-test-scheduled.yml`
(now explicit dedup-off) still adds signal. If not, retire it.
- **DynamoDB default-on** — parallel work tracked by
[`2026_06_03_partial_dynamodb_onephase_dedup.md`](https://github.com/bootjp/elastickv/blob/main/docs/design/2026_06_03_partial_dynamodb_onephase_dedup.md)'s
`M2`. Not part of this PR.
- **S3, SQS dedup paths** — not yet routed through one-phase reuse; out
of scope for the parent design.


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **Documentation**
* Added a design doc describing a planned default-on change for Redis
transaction dedup and rollout/verification plans.

* **Chores**
* Flipped adapter default behavior so transaction dedup is enabled by
default, with an environment opt-out preserved.
* Introduced a separate opt-in gate for standalone SET dedup to avoid
unintended behavior changes.

* **Tests**
* Updated standalone SET tests and added a regression test to verify
overwrite semantics remain correct under current defaults.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: bootjp

.github/workflows/jepsen-test-scheduled.yml

@@ -39,6 +39,19 @@ jobs:
     runs-on: ubuntu-latest
     env:
       GOCACHE: /tmp/go-build
+      # Explicit dedup-OFF control baseline. The Redis adapter's
+      # onePhaseTxnDedup flipped to default-on in
+      # docs/design/2026_06_10_proposed_redis_onephase_dedup_default_on.md;
+      # this workflow is preserved as the legacy-path coverage so anomalies
+      # the dedup gate prevents (`:duplicate-elements`, `:future-read`,
+      # `:G-single-item-realtime`) continue to be measured against an
+      # unprotected build. Pair with the dedup-ON workflow
+      # (.github/workflows/jepsen-test-scheduled-dedup.yml) which sets
+      # ELASTICKV_REDIS_ONEPHASE_DEDUP=1 explicitly. Retirement of this
+      # workflow is a follow-up after 30 days of post-flip data; until
+      # then, do NOT remove this env var — without it the two workflows
+      # would exercise the same path under the new default.
+      ELASTICKV_REDIS_ONEPHASE_DEDUP: "0"
     steps:
       - uses: actions/checkout@v6
         with:

adapter/redis.go

@@ -243,27 +243,59 @@ type RedisServer struct {
 	// retryable write error, list-push retries reuse the failed attempt's
 	// write set and carry prev_commit_ts so the FSM can dedup a commit that
 	// landed under leadership churn (see
-	// docs/design/2026_05_21_proposed_txn_secondary_idempotency.md). It
-	// MUST stay off until every node runs a probe-aware binary — see R5
-	// (FSM determinism across a rolling upgrade). Default off; enabled via
-	// WithOnePhaseTxnDedup / the ELASTICKV_REDIS_ONEPHASE_DEDUP env var
-	// after a full rollout.
+	// docs/design/2026_05_21_proposed_txn_secondary_idempotency.md). The
+	// FSM probe ships on every node in production, satisfying R5 (FSM
+	// determinism across a rolling upgrade), so the gate now defaults on
+	// per docs/design/2026_06_10_proposed_redis_onephase_dedup_default_on.md.
+	// Set ELASTICKV_REDIS_ONEPHASE_DEDUP=0 (or WithOnePhaseTxnDedup(false))
+	// to opt out — kept as a one-env-var operator rollback.
 	onePhaseTxnDedup bool
 
+	// standaloneSetDedup gates whether the *standalone* SET command (not SET
+	// inside MULTI/EXEC) routes through runTransactionWithDedup. Default off
+	// because the dedup path's applySet does not match the legacy
+	// executeSet/replaceWithStringTxn semantics for SET-over-collection: a
+	// `SET k v` after `RPUSH k x` returns WRONGTYPE on the dedup path but
+	// overwrites correctly on the legacy path (PR #943 round-1 codex P1).
+	// Bringing applySet to parity (collection-deletion + string write inside
+	// the dedup txn) is tracked as a follow-up; until that lands, the
+	// standalone SET path stays on the legacy default-on-flip code path
+	// regardless of onePhaseTxnDedup's value. Enable explicitly via
+	// WithStandaloneSetDedup(true) or ELASTICKV_REDIS_ONEPHASE_DEDUP_SET=1
+	// only when applySet's parity is verified for the workload at hand.
+	standaloneSetDedup bool
+
 	route map[string]func(conn redcon.Conn, cmd redcon.Command)
 }
 
 type RedisServerOption func(*RedisServer)
 
-// WithOnePhaseTxnDedup enables the option-2 one-phase idempotency dedup on
-// list-push retries (see RedisServer.onePhaseTxnDedup). Off by default;
-// enable only after the whole cluster runs a probe-aware binary.
+// WithOnePhaseTxnDedup enables (or disables) the option-2 one-phase
+// idempotency dedup on list-push and MULTI/EXEC retries
+// (see RedisServer.onePhaseTxnDedup). On by default since the rollout
+// recorded in docs/design/2026_06_10_proposed_redis_onephase_dedup_default_on.md;
+// pass false to opt out from code, or set ELASTICKV_REDIS_ONEPHASE_DEDUP=0
+// to opt out from the environment. The constructor option trumps the env var.
+// Standalone SET requires the separate WithStandaloneSetDedup gate; see
+// RedisServer.standaloneSetDedup.
 func WithOnePhaseTxnDedup(enabled bool) RedisServerOption {
 	return func(r *RedisServer) {
 		r.onePhaseTxnDedup = enabled
 	}
 }
 
+// WithStandaloneSetDedup enables the option-2 dedup path on the *standalone*
+// SET command (not SET inside MULTI/EXEC). Off by default because the dedup
+// path's applySet does not yet match the legacy executeSet semantics for
+// SET-over-collection — see RedisServer.standaloneSetDedup. Enable only
+// after verifying applySet parity for the workload (no SET-over-list /
+// SET-over-hash / SET-over-set / SET-over-zset / SET-over-stream issued).
+func WithStandaloneSetDedup(enabled bool) RedisServerOption {
+	return func(r *RedisServer) {
+		r.standaloneSetDedup = enabled
+	}
+}
+
 func WithRedisActiveTimestampTracker(tracker *kv.ActiveTimestampTracker) RedisServerOption {
 	return func(r *RedisServer) {
 		r.readTracker = tracker
@@ -495,15 +527,20 @@ func NewRedisServer(listen net.Listener, redisAddr string, store store.MVCCStore
 		// getLuaPool, which honors luaPoolMaxIdle the same way.
 		luaPool:       nil,
 		traceCommands: os.Getenv("ELASTICKV_REDIS_TRACE") == "1",
-		// onePhaseTxnDedup honors the documented opt-in env var; the
-		// WithOnePhaseTxnDedup option below can still override either way.
-		// Default off — see R5 in the design doc (the writer must not be
-		// enabled until the whole cluster runs a probe-aware binary).
-		onePhaseTxnDedup: os.Getenv("ELASTICKV_REDIS_ONEPHASE_DEDUP") == "1",
-		baseCtx:          baseCtx,
-		baseCancel:       baseCancel,
-		streamWaiters:    newKeyWaiterRegistry(),
-		zsetWaiters:      newKeyWaiterRegistry(),
+		// onePhaseTxnDedup defaults on — the parent design's R5 rolling-upgrade
+		// constraint is discharged (FSM probe shipped on every node months ago,
+		// 12 consecutive green dedup-mode Jepsen runs 2026-05-31 → 2026-06-10).
+		// See docs/design/2026_06_10_proposed_redis_onephase_dedup_default_on.md.
+		// ELASTICKV_REDIS_ONEPHASE_DEDUP=0 opts out; the WithOnePhaseTxnDedup
+		// constructor option still trumps the env var.
+		onePhaseTxnDedup: os.Getenv("ELASTICKV_REDIS_ONEPHASE_DEDUP") != "0",
+		// standaloneSetDedup defaults off; see field comment for the
+		// applySet-vs-executeSet parity gap that gates this separately.
+		standaloneSetDedup: os.Getenv("ELASTICKV_REDIS_ONEPHASE_DEDUP_SET") == "1",
+		baseCtx:            baseCtx,
+		baseCancel:         baseCancel,
+		streamWaiters:      newKeyWaiterRegistry(),
+		zsetWaiters:        newKeyWaiterRegistry(),
 	}
 	r.relay.Bind(r.publishLocal)
 
@@ -1131,7 +1168,13 @@ func (r *RedisServer) set(conn redcon.Conn, cmd redcon.Command) {
 	// SET there is exactly one element with the same redisResult shape as
 	// the standalone reply (resultString OK / resultNil for NX/XX miss /
 	// resultBulk for GET).
-	if r.onePhaseTxnDedup {
+	// Both gates must be on to route standalone SET through the dedup path.
+	// onePhaseTxnDedup covers the MULTI/EXEC and list-push retries that the
+	// parent design's M4 validated; standaloneSetDedup is a separate sub-gate
+	// (default off) because applySet diverges from executeSet on SET-over-
+	// collection — flipping onePhaseTxnDedup default-on without this guard
+	// would change normal Redis overwrite behaviour (PR #943 round-1 codex P1).
+	if r.onePhaseTxnDedup && r.standaloneSetDedup {
 		// Call runTransactionWithDedup directly instead of going through
 		// runTransaction. runTransaction re-checks the same
 		// r.onePhaseTxnDedup gate and routes here anyway; the indirection

adapter/redis_set_dedup_test.go

@@ -28,7 +28,12 @@ func TestStandaloneSetDedup_LandedPriorAttempt_ReturnsOK(t *testing.T) {
 	ctx := context.Background()
 	st := store.NewMVCCStore()
 	coord := newDedupTestCoordinator(st, 1, true) // attempt 1 lands then errors
-	srv := &RedisServer{store: st, coordinator: coord, scriptCache: map[string]string{}, onePhaseTxnDedup: true}
+	// Both gates: onePhaseTxnDedup is the umbrella; standaloneSetDedup is
+	// the per-path sub-gate that opts the *standalone* SET branch into
+	// the dedup routing. The sub-gate defaults off (PR #943 round-1 codex
+	// P1 — applySet diverges from executeSet on SET-over-collection).
+	// Tests that pin the dedup-on routing must explicitly enable both.
+	srv := &RedisServer{store: st, coordinator: coord, scriptCache: map[string]string{}, onePhaseTxnDedup: true, standaloneSetDedup: true}
 
 	conn := &recordingConn{}
 	cmd := redcon.Command{Args: [][]byte{[]byte(cmdSet), []byte("k"), []byte("v1")}}
@@ -61,7 +66,12 @@ func TestStandaloneSetDedup_NXMissReturnsNil(t *testing.T) {
 	require.NoError(t, st.PutAt(ctx, redisStrKey([]byte("k")), encodeRedisStr([]byte("seed"), nil), 5, 0))
 
 	coord := newDedupTestCoordinator(st, 1, true) // attempt 1 lands then errors
-	srv := &RedisServer{store: st, coordinator: coord, scriptCache: map[string]string{}, onePhaseTxnDedup: true}
+	// Both gates: onePhaseTxnDedup is the umbrella; standaloneSetDedup is
+	// the per-path sub-gate that opts the *standalone* SET branch into
+	// the dedup routing. The sub-gate defaults off (PR #943 round-1 codex
+	// P1 — applySet diverges from executeSet on SET-over-collection).
+	// Tests that pin the dedup-on routing must explicitly enable both.
+	srv := &RedisServer{store: st, coordinator: coord, scriptCache: map[string]string{}, onePhaseTxnDedup: true, standaloneSetDedup: true}
 
 	conn := &recordingConn{}
 	// SET k v1 NX -- attempt 1 records resultNil because NX miss.
@@ -99,7 +109,12 @@ func TestStandaloneSetDedup_GETOptionReturnsOldBulk(t *testing.T) {
 	require.NoError(t, st.PutAt(ctx, redisStrKey([]byte("k")), encodeRedisStr([]byte("prior"), nil), 5, 0))
 
 	coord := newDedupTestCoordinator(st, 1, true) // attempt 1 lands then errors
-	srv := &RedisServer{store: st, coordinator: coord, scriptCache: map[string]string{}, onePhaseTxnDedup: true}
+	// Both gates: onePhaseTxnDedup is the umbrella; standaloneSetDedup is
+	// the per-path sub-gate that opts the *standalone* SET branch into
+	// the dedup routing. The sub-gate defaults off (PR #943 round-1 codex
+	// P1 — applySet diverges from executeSet on SET-over-collection).
+	// Tests that pin the dedup-on routing must explicitly enable both.
+	srv := &RedisServer{store: st, coordinator: coord, scriptCache: map[string]string{}, onePhaseTxnDedup: true, standaloneSetDedup: true}
 
 	conn := &recordingConn{}
 	// SET k v1 GET -- attempt 1 records resultBulk("prior").

adapter/redis_set_overwrite_default_test.go

@@ -0,0 +1,54 @@
+package adapter
+
+import (
+	"context"
+	"testing"
+
+	"github.com/redis/go-redis/v9"
+	"github.com/stretchr/testify/require"
+)
+
+// TestRedis_SET_OverwritesList_UnderDefaultGate locks in the legacy
+// SET-over-collection overwrite semantics under the new default-on dedup
+// gate landed in PR #943. The dedup path's applySet returns WRONGTYPE on
+// a SET that hits a key already holding a list/hash/set/zset/stream,
+// while the legacy setLegacy / executeSet / replaceWithStringTxn path
+// deletes the collection's logical elements and writes the string.
+// Codex flagged this as a P1 regression on PR #943 round-1: flipping
+// onePhaseTxnDedup default-on without a separate gate on the standalone
+// SET path would have changed normal Redis overwrite behaviour. The fix
+// is the standaloneSetDedup sub-gate, which defaults off — so
+// `SET k v` after `RPUSH k x` must still return OK and let the next
+// GET observe the string value, not WRONGTYPE.
+//
+// This is a regression test (CLAUDE.md self-review §5 + the
+// "when code review surfaces a defect, first add a failing test"
+// convention). If a future change re-enables standaloneSetDedup as
+// default-on without bringing applySet to parity with executeSet, this
+// test must fail.
+func TestRedis_SET_OverwritesList_UnderDefaultGate(t *testing.T) {
+	t.Parallel()
+	nodes, _, _ := createNode(t, 3)
+	defer shutdown(nodes)
+
+	ctx := context.Background()
+	rdb := redis.NewClient(&redis.Options{Addr: nodes[0].redisAddress})
+	defer func() { _ = rdb.Close() }()
+
+	// Seed the key as a list — the encoding that the dedup path's
+	// applySet hard-fails against.
+	require.NoError(t, rdb.Do(ctx, "RPUSH", "setover:list", "elem-a").Err())
+
+	// Real Redis behaviour: SET unconditionally replaces the value,
+	// dropping the previous type. The legacy path implements this; the
+	// dedup path returns WRONGTYPE. With the default config
+	// (onePhaseTxnDedup on, standaloneSetDedup off) we must take the
+	// legacy path and observe OK + string value.
+	res, err := rdb.Do(ctx, "SET", "setover:list", "replaced").Result()
+	require.NoError(t, err, "SET must overwrite an existing list under default config")
+	require.Equal(t, "OK", res)
+
+	got, err := rdb.Get(ctx, "setover:list").Result()
+	require.NoError(t, err, "GET after SET-over-list must succeed")
+	require.Equal(t, "replaced", got)
+}