fix(encryption): PR782 r3 codex P2 — narrow IsEncryptionRelevantOpcode to exclude OpRegistration

PR #782 round-3 codex P2 finding (Exclude registration opcode
from sidecar gap predicate).

## codex r3 P2 — IsEncryptionRelevantOpcode false positive on registration

The previous predicate range [OpEncryptionMin, OpEncryptionMax]
included OpRegistration (0x03). But ApplyRegistration in
applier.go only mutates writer-registry rows via SetRegistryRow;
it NEVER calls WriteSidecar. So a gap containing OpRegistration
entries does not actually need to refuse — the sidecar IS
consistent because the sidecar's raft_applied_index is not
advanced by registration applies (only WriteSidecar moves it).

The design's §5.5 enumeration agrees: the listed sidecar-relevant
opcodes are `rotate-dek`, `rewrap-deks`, `bootstrap-encryption`,
`enable-storage-envelope`, `enable-raft-envelope`, `retire-dek`
— notably NOT `register-writer`. The predicate range was wrong.

Concrete impact of the bug: every restart after the first
RegisterEncryptionWriter would fire ErrSidecarBehindRaftLog and
refuse to boot, because:
  - registration entries bump engine.AppliedIndex but not
    sidecar.RaftAppliedIndex
  - the gap therefore exists and contains OpRegistration
  - the previous predicate classified that as relevant
  - the guard would fire → cluster boot loop

Fix: narrow the range to [OpBootstrap, OpEncryptionMax] =
[0x04, 0x07]. OpRegistration (0x03) is explicitly excluded with
a clear IMPORTANT block in the godoc explaining why and pointing
at ApplyRegistration as the authoritative reference.

## Semantic change — caller audit

IsEncryptionRelevantOpcode's return value changes for opcode=0x03
(true → false). Per the cron directive, audited all callers:

  - audit.go (definition, updated)
  - audit_test.go (tests, updated to assert the new behavior:
    OpRegistration explicitly classified NOT relevant)
  - errors.go (docstring on ErrSidecarBehindRaftLog updated to
    reflect the narrowed range AND explicitly note that 0x03
    OpRegistration is excluded)

No production caller exists yet (the predicate is consumed by
GuardSidecarBehindRaftLog whose only caller is 6C-2c, not yet
landed). The 6C-2c scanner author will see the corrected
predicate from day one.

## Verification

- go test -race -timeout=60s ./internal/encryption/... — PASS
  (including the new TestIsEncryptionRelevantOpcode_KnownRanges
  sub-test "OpRegistration_0x03_NOT_relevant" that pins the
  exclusion explicitly)
- golangci-lint run ./internal/encryption/... — 0 issues

## Test additions

- TestIsEncryptionRelevantOpcode_AllRangeMembers now asserts
  OpRegistration is NOT relevant before iterating the
  sidecar-mutating range.
- TestIsEncryptionRelevantOpcode_KnownRanges adds a dedicated
  "OpRegistration_0x03_NOT_relevant" sub-test for grep-able
  regression anchoring.

Author: bootjp

internal/encryption/audit.go

@@ -6,10 +6,31 @@ import (
 )
 
 // IsEncryptionRelevantOpcode reports whether the supplied FSM
-// opcode byte is one of the §5.5 encryption-relevant opcodes:
-// 0x03 OpRegistration, 0x04 OpBootstrap, 0x05 OpRotation, and
-// the reserved 0x06 / 0x07 slots in the fsmwire OpEncryption
-// range.
+// opcode byte is one of the §5.5 SIDECAR-MUTATING opcodes —
+// the set of entry types whose apply path writes the §5.1
+// keys.json sidecar and therefore matters for the
+// ErrSidecarBehindRaftLog gap-coverage check:
+//
+//   - 0x04 OpBootstrap         (bootstrap-encryption — §5.6)
+//   - 0x05 OpRotation          (rotate-dek + future sub-tags
+//     rewrap-deks / retire-dek / enable-storage-envelope /
+//     enable-raft-envelope — §5.2 + §7.1)
+//   - 0x06 / 0x07              (reserved slots in the fsmwire
+//     OpEncryption range for Stage 6E wire extensions; whether
+//     they end up sidecar-mutating is design-stage-defined,
+//     but conservatively treating them as relevant matches the
+//     §5.5 enumeration and forces a future ABI extension to be
+//     explicit about adding a NOT-relevant opcode).
+//
+// IMPORTANT — 0x03 OpRegistration is EXCLUDED. ApplyRegistration
+// in internal/encryption/applier.go only mutates writer-registry
+// rows via SetRegistryRow; it never calls WriteSidecar. Treating
+// it as sidecar-relevant would fire ErrSidecarBehindRaftLog on
+// EVERY startup after the first registration, since the sidecar's
+// raft_applied_index is not advanced by registration applies.
+// The design's §5.5 enumeration matches this exclusion (rotate-
+// dek, rewrap-deks, bootstrap-encryption, enable-storage-envelope,
+// enable-raft-envelope, retire-dek — no register-writer).
 //
 // IMPORTANT — wire-format contract: the opcode byte is `data[0]`
 // of the FSM entry payload (the LEADING opcode tag), NOT the
@@ -24,17 +45,17 @@ import (
 //
 // The predicate is the §9.1 ErrSidecarBehindRaftLog guard's
 // gap-coverage check: an unapplied entry in the sidecar/engine
-// gap matters iff its `data[0]` is in this range. Non-encryption-
-// relevant entries (writes, transactions, control-plane RPCs)
-// in the gap do not affect the encryption sidecar and are safe
-// to ignore.
+// gap matters iff its `data[0]` is in this range. Non-sidecar-
+// mutating entries (writes, transactions, control-plane RPCs,
+// AND OpRegistration) in the gap do not affect the encryption
+// sidecar and are safe to ignore.
 //
 // Defined here (rather than in fsmwire) so the encryption
 // package owns its semantic-level predicate; the fsmwire
-// package owns the wire-level constants (OpEncryptionMin /
+// package owns the wire-level constants (OpBootstrap /
 // OpEncryptionMax) that this function reads.
 func IsEncryptionRelevantOpcode(opcode byte) bool {
-	return opcode >= fsmwire.OpEncryptionMin && opcode <= fsmwire.OpEncryptionMax
+	return opcode >= fsmwire.OpBootstrap && opcode <= fsmwire.OpEncryptionMax
 }
 
 // EncryptionRelevantScanner is the cross-package contract that

internal/encryption/audit_test.go

@@ -10,33 +10,45 @@ import (
 )
 
 // TestIsEncryptionRelevantOpcode_AllRangeMembers pins the
-// §5.5 predicate against every byte in the [OpEncryptionMin,
-// OpEncryptionMax] range AND a sampling of out-of-range bytes
-// (including the boundaries one below and one above the range).
+// §5.5 predicate against every byte in the sidecar-mutating
+// range [OpBootstrap, OpEncryptionMax] AND a sampling of
+// out-of-range bytes (including OpRegistration directly below
+// the lower bound, since that is the most likely regression to
+// reintroduce false-positive refusals).
 // The predicate is the load-bearing input to the
 // ErrSidecarBehindRaftLog guard; a regression that widens or
 // narrows the range silently changes the security guarantee.
 func TestIsEncryptionRelevantOpcode_AllRangeMembers(t *testing.T) {
-	// Every byte in the OpEncryption range MUST be relevant.
+	// Every byte in the sidecar-mutating range MUST be relevant.
 	//
 	// Iterate via int so the loop terminates even if a future
 	// stage sets OpEncryptionMax = 0xFF; a byte-typed loop
 	// counter would wrap to 0x00 on opcode++ at 0xFF and the
 	// loop would never exit. The design reserves 0x06 / 0x07
 	// for Stage 6E, so the range is expected to grow and a
 	// byte-typed loop is a latent overflow risk.
-	for i := int(fsmwire.OpEncryptionMin); i <= int(fsmwire.OpEncryptionMax); i++ {
+	for i := int(fsmwire.OpBootstrap); i <= int(fsmwire.OpEncryptionMax); i++ {
 		opcode := byte(i)
 		if !encryption.IsEncryptionRelevantOpcode(opcode) {
 			t.Errorf("opcode 0x%02X in [0x%02X, 0x%02X] must be encryption-relevant",
-				opcode, fsmwire.OpEncryptionMin, fsmwire.OpEncryptionMax)
+				opcode, fsmwire.OpBootstrap, fsmwire.OpEncryptionMax)
 		}
 	}
+	// OpRegistration sits just below the sidecar-mutating range
+	// (0x03 < 0x04) and MUST NOT be relevant. ApplyRegistration
+	// in applier.go only mutates writer-registry rows and never
+	// calls WriteSidecar, so registration-only gaps would be
+	// false-positive refusals if this byte were classified as
+	// relevant.
+	if encryption.IsEncryptionRelevantOpcode(fsmwire.OpRegistration) {
+		t.Errorf("OpRegistration (0x%02X) must NOT be encryption-relevant (writer-registry only, never WriteSidecar)",
+			fsmwire.OpRegistration)
+	}
 	// The byte one below the range must NOT be relevant.
-	if fsmwire.OpEncryptionMin > 0 {
-		below := fsmwire.OpEncryptionMin - 1
+	if fsmwire.OpBootstrap > 0 {
+		below := fsmwire.OpBootstrap - 1
 		if encryption.IsEncryptionRelevantOpcode(below) {
-			t.Errorf("opcode 0x%02X (one below OpEncryptionMin) must NOT be encryption-relevant", below)
+			t.Errorf("opcode 0x%02X (one below OpBootstrap) must NOT be encryption-relevant", below)
 		}
 	}
 	// The byte one above the range must NOT be relevant.
@@ -49,37 +61,52 @@ func TestIsEncryptionRelevantOpcode_AllRangeMembers(t *testing.T) {
 }
 
 // TestIsEncryptionRelevantOpcode_KnownRanges pins the explicit
-// opcode values mentioned in §5.5: 0x03 (registration), 0x04
-// (bootstrap), 0x05 (rotation), plus 0x06/0x07 reserved slots.
-// Spelling them out by name catches a regression where someone
-// changes the constants but leaves the predicate range alone.
+// opcode values mentioned in §5.5: 0x04 (bootstrap), 0x05
+// (rotation), plus 0x06/0x07 reserved slots. Spelling them out
+// by name catches a regression where someone changes the
+// constants but leaves the predicate range alone.
+//
+// 0x03 OpRegistration is EXCLUDED — see the per-opcode comment
+// below and the IMPORTANT block in IsEncryptionRelevantOpcode's
+// godoc.
 func TestIsEncryptionRelevantOpcode_KnownRanges(t *testing.T) {
 	for _, tc := range []struct {
 		name   string
 		opcode byte
 	}{
-		{"OpRegistration_0x03", fsmwire.OpRegistration},
 		{"OpBootstrap_0x04", fsmwire.OpBootstrap},
 		{"OpRotation_0x05", fsmwire.OpRotation},
 		// Reserved slots in the OpEncryption range. No named
 		// constant yet (Stage 6E will assign them); pinning the
 		// raw bytes here ensures the predicate still treats them
 		// as relevant when 6E lands the wire-format extension
 		// and a future reader is reminded the range is reserved-
-		// not-just-currently-3-opcodes.
+		// not-just-currently-2-opcodes.
 		{"Reserved_0x06", 0x06},
 		{"Reserved_0x07", 0x07},
 	} {
 		t.Run(tc.name, func(t *testing.T) {
 			if !encryption.IsEncryptionRelevantOpcode(tc.opcode) {
-				t.Errorf("known encryption opcode 0x%02X must be relevant", tc.opcode)
+				t.Errorf("known sidecar-mutating opcode 0x%02X must be relevant", tc.opcode)
 			}
 		})
 	}
+	// OpRegistration (0x03) is in the OpEncryption opcode range
+	// but is NOT sidecar-mutating — ApplyRegistration only writes
+	// writer-registry rows via SetRegistryRow, never WriteSidecar.
+	// Including it in the predicate would force startup refusal
+	// on every restart after the first registration, since the
+	// sidecar's raft_applied_index is not advanced by registration
+	// applies.
+	t.Run("OpRegistration_0x03_NOT_relevant", func(t *testing.T) {
+		if encryption.IsEncryptionRelevantOpcode(fsmwire.OpRegistration) {
+			t.Errorf("OpRegistration (0x%02X) must NOT be relevant (writer-registry only)", fsmwire.OpRegistration)
+		}
+	})
 	// 0x00, 0x01, 0x02 (non-encryption FSM opcodes) MUST NOT be
 	// relevant. The exact non-encryption opcode space is project-
 	// specific; what matters here is that bytes below 0x03 are
-	// never in the encryption range.
+	// never in the sidecar-mutating range.
 	for _, op := range []byte{0x00, 0x01, 0x02} {
 		if encryption.IsEncryptionRelevantOpcode(op) {
 			t.Errorf("non-encryption opcode 0x%02X must NOT be relevant", op)

internal/encryption/errors.go

@@ -178,10 +178,14 @@ var (
 	// ErrSidecarBehindRaftLog is the §9.1 startup-refusal guard
 	// raised when the sidecar's raft_applied_index is behind the
 	// raftengine's persisted applied index AND the gap covers any
-	// encryption-relevant Raft entry (per §5.5's
-	// IsEncryptionRelevantOpcode predicate: 0x03 OpRegistration,
-	// 0x04 OpBootstrap, 0x05 OpRotation, plus the reserved opcodes
-	// 0x06 / 0x07 from the fsmwire OpEncryption range).
+	// SIDECAR-MUTATING Raft entry (per §5.5's
+	// IsEncryptionRelevantOpcode predicate: 0x04 OpBootstrap,
+	// 0x05 OpRotation, plus the reserved opcodes 0x06 / 0x07
+	// from the fsmwire OpEncryption range). 0x03 OpRegistration
+	// is in the OpEncryption range but is NOT sidecar-mutating
+	// — its apply path writes writer-registry rows only and
+	// never WriteSidecar, so registration-only gaps would be
+	// spurious refusals.
 	//
 	// The classic scenario this catches is a partial-write crash:
 	// an encryption-relevant entry was applied to the engine and