feat(encryption): Stage 7c — ConfChange-time writer registration (#872)

## Summary

Implements the merged 7c design (PR #868). Pre-registers a new node's
writer-registry row from the admin-RPC `AddVoter`/`AddLearner` handler
so that:

1. **Write-window elimination** (optimization): encrypted writes from
the new node never fail closed on the 7a-2 storage gate after the
conf-change commits.
2. **Collision-safe membership change** (correctness): a §6.1 uint16
NodeID collision is caught at the RPC layer with
`ErrWriterUint16Collision` **before** the conf-change is proposed — no
§4.1 case-4 halt-apply on a durable conf-change entry.

### Three changes

1. **`internal/raftadmin`**: `MembershipChangeInterceptor` interface +
`NewServerWithInterceptor` constructor +
`RegisterOperationalServicesWithInterceptor`.
`Server.AddVoter`/`AddLearner` invoke the optional `PreAddMember` hook
before the engine's conf-change proposal. Nil interceptor preserves the
pre-7c posture.
2. **`internal/encryption`**: `ErrWriterUint16Collision` typed error for
the §6.1 collision branch.
3. **`main`**: `encryptionPreRegister` adapter implements the
interceptor — read-before-propose guard against §4.1 case-3
(re-proposing `epoch=0` against an existing `(epoch=0)` row), idempotent
skip on FullNodeID match, typed error on FullNodeID mismatch (§6.1
collision), case-1 first-seen propose otherwise. Wired into
`serversInput → runtimeServerRunner → startRaftServers →
RegisterOperationalServicesWithInterceptor` so the encryption adapter
coupling stays at the main-level wiring point.

### Test coverage (per design §5)

- `internal/raftadmin/server_test.go`:
- `TestServer_AddVoter_InvokesInterceptorBeforeConfChange` — ordering:
hook called, then engine.AddVoter.
- `TestServer_AddVoter_InterceptorErrorAbortsConfChange` —
engine.AddVoter NOT called when hook errs.
- `TestServer_AddVoter_NilInterceptorSkipsPreStep` — pre-7c posture
preserved.
- `TestServer_AddLearner_InterceptorContract` — symmetric sub-tests for
AddLearner.
- `main_encryption_confchange_test.go`:
- `TestEncryptionPreRegister_PreBootstrapSkips` — `ActiveStorageKeyID()
== (0, false)` → nil-skip.
- `TestEncryptionPreRegister_NilCacheReturnsNilInterceptor` — defensive
nil-check at constructor.
- `TestEncryptionPreRegister_IdempotentWhenRowExists` — pins the §3.1
read-before-propose guard against the §4.1 case-3
`ErrLocalEpochRollback` regression (claude round-2 BLOCKING on PR #868).
- `TestEncryptionPreRegister_Uint16CollisionReturnsTypedError` — pins
the §6.1 collision branch.

## 5-lens self review

- **Data loss**: clean. Pre-register propose is additive (`0x03` entry +
§4.1 case-1 insert); no user-data-path change.
- **Concurrency**: pre-register runs on the leader's RPC goroutine; the
guard catches the leader-flip retry race via the durable row, NOT via
case-2 monotonic (which requires strictly greater epoch).
- **Performance**: one registry read + at most one Raft round-trip per
`AddVoter`/`AddLearner` call. Encryption-unaware path unchanged (nil
interceptor skips the pre-step).
- **Data consistency**: §4.1 case-1 first-seen for genuinely new
members; guard returns idempotent-skip or `ErrWriterUint16Collision` for
existing rows. §6.1 case-4 halt-apply is restricted to the narrow TOCTOU
residual (two concurrent AddVoter for uint16-colliding raftIDs).
- **Test coverage**: complete per design §5 (raftadmin contract +
adapter branches). The §3.5 leader-flip retry path is pinned by
`IdempotentWhenRowExists`. End-to-end test deferred per design §5.3
(requires 2-node test cluster fixture; unit + integration above cover
the contract surface).

## Test plan

- [x] `go test -run
'TestApplier|TestApplyRotation|TestApplyBootstrap|TestRuntimeRegistration|TestBuildProcessStartRegistration|TestRegistrationCommittedAtEpoch|TestEncryption_E2E|TestRunWriterRegistration|TestServer|TestEncryptionPreRegister|TestRegisterOperational'
-race -timeout 180s ./internal/encryption ./internal/raftadmin ./.` —
green.
- [x] `make lint` clean.
- [ ] @claude review for correctness of the interceptor wiring,
guard-branch invariants, and main-level construction.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Author: bootjp

internal/encryption/errors.go

@@ -120,6 +120,18 @@ var (
 	// than a nil-pointer panic deep in the apply path.
 	ErrKEKNotConfigured = errors.New("encryption: KEK not configured on this node; cannot unwrap wrapped DEK material")
 
+	// ErrWriterUint16Collision is the Stage 7c §3.3 typed error returned
+	// by the encryption-aware MembershipChangeInterceptor when a new
+	// node's NodeID16 collides with an existing member's writer-
+	// registry row at the same uint16 truncation but with a different
+	// FullNodeID. The §3.1 read-before-propose guard catches the
+	// common case BEFORE any propose, so the admin RPC returns a
+	// retryable client-facing error rather than triggering a §4.1
+	// case-4 halt apply (which would, without 7c's interceptor, fire
+	// AFTER the conf-change had already committed — bricking the
+	// cluster). Operators choose a non-colliding raftID and retry.
+	ErrWriterUint16Collision = errors.New("encryption: writer registry uint16 collision; choose a different raftID")
+
 	// ErrSidecarPresentWithoutFlag is the §9.1 startup-refusal guard
 	// raised when the data dir already contains a sidecar (keys.json)
 	// but --encryption-enabled is NOT set. Continuing would silently

internal/raftadmin/health.go

@@ -21,14 +21,30 @@ const (
 )
 
 func RegisterOperationalServices(ctx context.Context, gs *grpc.Server, engine raftengine.Engine, serviceNames []string) {
+	RegisterOperationalServicesWithInterceptor(ctx, gs, engine, serviceNames, nil)
+}
+
+// RegisterOperationalServicesWithInterceptor is the Stage 7c variant
+// of RegisterOperationalServices that installs an optional
+// [MembershipChangeInterceptor] on the underlying [Server] so
+// AddVoter/AddLearner run an encryption-aware pre-step before the
+// conf-change proposal. Passing nil is equivalent to
+// [RegisterOperationalServices].
+func RegisterOperationalServicesWithInterceptor(
+	ctx context.Context,
+	gs *grpc.Server,
+	engine raftengine.Engine,
+	serviceNames []string,
+	interceptor MembershipChangeInterceptor,
+) {
 	if gs == nil {
 		return
 	}
 	if ctx == nil {
 		panic("raftadmin: RegisterOperationalServices requires non-nil context")
 	}
 
-	pb.RegisterRaftAdminServer(gs, NewServer(engine))
+	pb.RegisterRaftAdminServer(gs, NewServerWithInterceptor(engine, interceptor))
 
 	healthSrv := health.NewServer()
 	healthpb.RegisterHealthServer(gs, healthSrv)

internal/raftadmin/interceptor.go

@@ -0,0 +1,28 @@
+package raftadmin
+
+import "context"
+
+// MembershipChangeInterceptor lets a caller of [Server] inject a
+// pre-step into [Server.AddVoter] and [Server.AddLearner] that runs
+// **before** the underlying Raft engine proposes the configuration
+// change. A non-nil error from PreAddMember aborts the conf-change
+// proposal; the error is returned to the gRPC caller verbatim.
+//
+// Stage 7c uses this hook to pre-register a new node's writer-
+// registry row (see
+// docs/design/2026_05_29_proposed_7c_confchange_time_registration.md).
+// Keeping the encryption-aware adapter outside this package preserves
+// raftadmin's engine-generic posture — no concrete dependency on
+// the KV or encryption layers.
+//
+// The hook is intentionally optional: when nil is passed to [NewServer]
+// (or [NewServerWithInterceptor] is not used), AddVoter/AddLearner run
+// exactly as they did pre-7c. Encryption-unaware builds and
+// encryption-disabled clusters therefore see no behavior change.
+type MembershipChangeInterceptor interface {
+	// PreAddMember runs on the leader before AddVoter/AddLearner
+	// proposes the conf-change. The raftID is the same string the
+	// caller passed in the AddVoter/AddLearner request (the
+	// `Id` field).
+	PreAddMember(ctx context.Context, raftID string) error
+}

internal/raftadmin/server.go

@@ -13,15 +13,31 @@ import (
 type Server struct {
 	engine raftengine.Engine
 	admin  raftengine.Admin
+	// interceptor is invoked from AddVoter/AddLearner before the
+	// underlying Raft engine proposes the conf-change. nil = no
+	// pre-step (the pre-7c posture). Stage 7c wires the encryption-
+	// aware adapter via NewServerWithInterceptor; encryption-unaware
+	// builds keep this nil.
+	interceptor MembershipChangeInterceptor
 
 	pb.UnimplementedRaftAdminServer
 }
 
 func NewServer(engine raftengine.Engine) *Server {
+	return NewServerWithInterceptor(engine, nil)
+}
+
+// NewServerWithInterceptor constructs a Server with an optional
+// pre-step that runs before AddVoter/AddLearner propose the
+// conf-change. See [MembershipChangeInterceptor]. Passing nil is
+// equivalent to [NewServer] — the pre-step is skipped and the
+// conf-change runs exactly as the pre-7c posture.
+func NewServerWithInterceptor(engine raftengine.Engine, interceptor MembershipChangeInterceptor) *Server {
 	admin, _ := any(engine).(raftengine.Admin)
 	return &Server{
-		engine: engine,
-		admin:  admin,
+		engine:      engine,
+		admin:       admin,
+		interceptor: interceptor,
 	}
 }
 
@@ -73,6 +89,15 @@ func (s *Server) AddVoter(ctx context.Context, req *pb.RaftAdminAddVoterRequest)
 	if req == nil || req.Id == "" || req.Address == "" {
 		return nil, grpcStatus(codes.InvalidArgument, "id and address are required")
 	}
+	// Stage 7c §3.1 pre-step: run the encryption-aware adapter (if any)
+	// before the conf-change proposal so the new node's writer-registry
+	// row exists at apply time and any §6.1 uint16 collision halts here
+	// rather than after the conf-change is durable.
+	if s.interceptor != nil {
+		if err := s.interceptor.PreAddMember(ctx, req.Id); err != nil {
+			return nil, adminError(err)
+		}
+	}
 	index, err := s.admin.AddVoter(ctx, req.Id, req.Address, req.PreviousIndex)
 	if err != nil {
 		return nil, adminError(err)
@@ -87,6 +112,11 @@ func (s *Server) AddLearner(ctx context.Context, req *pb.RaftAdminAddLearnerRequ
 	if req == nil || req.Id == "" || req.Address == "" {
 		return nil, grpcStatus(codes.InvalidArgument, "id and address are required")
 	}
+	if s.interceptor != nil {
+		if err := s.interceptor.PreAddMember(ctx, req.Id); err != nil {
+			return nil, adminError(err)
+		}
+	}
 	index, err := s.admin.AddLearner(ctx, req.Id, req.Address, req.PreviousIndex)
 	if err != nil {
 		return nil, adminError(err)

internal/raftadmin/server_test.go

@@ -29,6 +29,14 @@ type fakeEngine struct {
 	removeServerCalls   []fakeRemoveServerCall
 	transferCalls       int
 	targetTransferCalls []fakeTransferCall
+
+	// addVoterHook is invoked synchronously inside AddVoter, before
+	// recording the call. Tests use this to observe the ordering of
+	// the engine call relative to the interceptor's hook so the
+	// "interceptor runs before engine.AddVoter" invariant is actually
+	// pinned (claude review on PR #872 — without the hook the test
+	// just observed that both ran in any order).
+	addVoterHook func()
 }
 
 type fakeAddVoterCall struct {
@@ -98,6 +106,12 @@ func (f *fakeEngine) CheckServing(context.Context) error {
 }
 
 func (f *fakeEngine) AddVoter(_ context.Context, id string, address string, prevIndex uint64) (uint64, error) {
+	f.mu.Lock()
+	hook := f.addVoterHook
+	f.mu.Unlock()
+	if hook != nil {
+		hook()
+	}
 	f.mu.Lock()
 	defer f.mu.Unlock()
 	f.addVoterCalls = append(f.addVoterCalls, fakeAddVoterCall{id: id, address: address, prevIndex: prevIndex})
@@ -348,3 +362,107 @@ func TestRegisterOperationalServicesRequiresContext(t *testing.T) {
 		RegisterOperationalServices(nilCtx, server, &fakeEngine{}, []string{"RawKV"})
 	})
 }
+
+// recordingInterceptor is a test double for MembershipChangeInterceptor
+// that records every PreAddMember call and optionally returns a
+// pre-configured error so tests can drive the abort branches.
+type recordingInterceptor struct {
+	mu      sync.Mutex
+	calls   []string
+	retErr  error
+	preHook func(raftID string) // optional callback; useful for ordering assertions
+}
+
+func (r *recordingInterceptor) PreAddMember(_ context.Context, raftID string) error {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	r.calls = append(r.calls, raftID)
+	if r.preHook != nil {
+		r.preHook(raftID)
+	}
+	return r.retErr
+}
+
+// TestServer_AddVoter_InvokesInterceptorBeforeConfChange pins Stage 7c
+// §5.1 contract item 1: AddVoter calls the interceptor (with the raftID
+// from the request) before the engine's AddVoter, in that order. The
+// fakeEngine.addVoterHook appends "addVoter" synchronously from inside
+// the engine call, so the recorded ordering pins interceptor-before-
+// engine, not just that-both-ran (claude review low finding on PR #872).
+func TestServer_AddVoter_InvokesInterceptorBeforeConfChange(t *testing.T) {
+	t.Parallel()
+	var order []string
+	engine := &fakeEngine{addVoterHook: func() { order = append(order, "addVoter") }}
+	interceptor := &recordingInterceptor{preHook: func(string) { order = append(order, "preAdd") }}
+	server := NewServerWithInterceptor(engine, interceptor)
+	resp, err := server.AddVoter(context.Background(), &pb.RaftAdminAddVoterRequest{Id: "n42", Address: "127.0.0.1:9999"})
+	require.NoError(t, err)
+	require.NotNil(t, resp)
+	require.Equal(t, []string{"n42"}, interceptor.calls)
+	require.Equal(t, []string{"preAdd", "addVoter"}, order)
+	require.Equal(t, 1, len(engine.addVoterCalls))
+}
+
+// TestServer_AddVoter_InterceptorErrorAbortsConfChange pins §5.1
+// contract item 2: a non-nil PreAddMember error aborts AddVoter; the
+// engine's AddVoter is never called.
+func TestServer_AddVoter_InterceptorErrorAbortsConfChange(t *testing.T) {
+	t.Parallel()
+	engine := &fakeEngine{}
+	sentinel := context.DeadlineExceeded
+	interceptor := &recordingInterceptor{retErr: sentinel}
+	server := NewServerWithInterceptor(engine, interceptor)
+	resp, err := server.AddVoter(context.Background(), &pb.RaftAdminAddVoterRequest{Id: "n42", Address: "127.0.0.1:9999"})
+	require.Error(t, err)
+	require.Nil(t, resp)
+	require.Equal(t, []string{"n42"}, interceptor.calls)
+	require.Equal(t, 0, len(engine.addVoterCalls), "engine.AddVoter must NOT be called when PreAddMember errs")
+}
+
+// TestServer_AddVoter_NilInterceptorSkipsPreStep pins §5.1 contract
+// item 3: with no interceptor installed (the pre-7c posture, or an
+// encryption-disabled build), AddVoter proceeds directly to the
+// engine's AddVoter as today.
+func TestServer_AddVoter_NilInterceptorSkipsPreStep(t *testing.T) {
+	t.Parallel()
+	engine := &fakeEngine{}
+	server := NewServer(engine) // nil interceptor by construction
+	resp, err := server.AddVoter(context.Background(), &pb.RaftAdminAddVoterRequest{Id: "n42", Address: "127.0.0.1:9999"})
+	require.NoError(t, err)
+	require.NotNil(t, resp)
+	require.Equal(t, 1, len(engine.addVoterCalls))
+}
+
+// TestServer_AddLearner_InterceptorContract is the symmetric set for
+// AddLearner — combined into one test since the behavior mirrors
+// AddVoter exactly.
+func TestServer_AddLearner_InterceptorContract(t *testing.T) {
+	t.Parallel()
+	t.Run("invokes interceptor then conf-change", func(t *testing.T) {
+		t.Parallel()
+		engine := &fakeEngine{}
+		interceptor := &recordingInterceptor{}
+		server := NewServerWithInterceptor(engine, interceptor)
+		_, err := server.AddLearner(context.Background(), &pb.RaftAdminAddLearnerRequest{Id: "l1", Address: "127.0.0.1:9000"})
+		require.NoError(t, err)
+		require.Equal(t, []string{"l1"}, interceptor.calls)
+		require.Equal(t, 1, len(engine.addLearnerCalls))
+	})
+	t.Run("interceptor error aborts", func(t *testing.T) {
+		t.Parallel()
+		engine := &fakeEngine{}
+		interceptor := &recordingInterceptor{retErr: context.DeadlineExceeded}
+		server := NewServerWithInterceptor(engine, interceptor)
+		_, err := server.AddLearner(context.Background(), &pb.RaftAdminAddLearnerRequest{Id: "l1", Address: "127.0.0.1:9000"})
+		require.Error(t, err)
+		require.Equal(t, 0, len(engine.addLearnerCalls))
+	})
+	t.Run("nil interceptor skips pre-step", func(t *testing.T) {
+		t.Parallel()
+		engine := &fakeEngine{}
+		server := NewServer(engine)
+		_, err := server.AddLearner(context.Background(), &pb.RaftAdminAddLearnerRequest{Id: "l1", Address: "127.0.0.1:9000"})
+		require.NoError(t, err)
+		require.Equal(t, 1, len(engine.addLearnerCalls))
+	})
+}