refactor(sqs): drop unused alias + name decoder offsets + extra tests

Round 1 Claude review nits on PR #724:

1) Dropped sqsReceiptHandleVersion alias

  Round 1 added sqsReceiptHandleVersion as an alias of v1 "for
  existing call sites". In practice every call site now uses
  sqsReceiptHandleVersion1 explicitly, so the alias's only
  reference was a self-test. Dropped both the alias and the
  test assertion. The two version-byte constants
  (sqsReceiptHandleVersion1 / sqsReceiptHandleVersion2) are now
  the single source of truth.

2) Named per-field offset constants

  decodeReceiptHandleV1 / decodeReceiptHandleV2 used numeric
  offsets (1, 9, 13, 1+sqsMessageIDBytes, …) derived from layout
  arithmetic. Replaced with named constants:

    v1: V1VersionOffset, V1GenOffset, V1IDOffset,
        V1TokenOffset, V1Size
    v2: V2VersionOffset, V2PartitionOffset, V2GenOffset,
        V2IDOffset, V2TokenOffset, V2Size

  A future field-shape change touches the constants in one
  place instead of scattering numeric arithmetic through
  encoders / decoders.

3) Explicit upper bound on token slice

  bytes.Clone(b[start:]) → bytes.Clone(b[start:end]). The
  length check above guarantees the open-ended form would have
  read the right bytes, but the explicit upper bound is
  self-documenting and protects against a future refactor that
  forgets the length precondition.

4) Doc note on cross-version rejection

  decodedReceiptHandle's doc described the cross-version
  rejection contract ("a v1 handle against a partitioned queue
  → ReceiptHandleIsInvalid") that this scaffold PR does NOT
  enforce — that's PR 5b's gate-and-lift. Added an explicit
  note that enforcement is wired by PR 5b so future review of
  that PR doesn't go looking for the contract here.

5) New test case: v2 / v1 oversized

  TestDecodeReceiptHandle_RejectsLengthMismatch grew two cases
  (v2 + 1 byte, v1 + 1 byte) so the exact-length check on each
  decoder branch is independently exercised. The previous
  table covered "byte mismatch" and "truncated" but not "too
  long for the version".

Audit per the lessons-learned discipline

The semantic change here is the alias removal. grep -rn
sqsReceiptHandleVersion across the repo confirmed zero
remaining references after the test assertion was dropped.
The named-offset refactor preserves byte-for-byte the same
on-wire format; the constants ARE the layout.

go test -race ./adapter/... and golangci-lint clean.

Author: bootjp

adapter/sqs_messages.go

@@ -56,14 +56,10 @@ const (
 	// partitionFor hash. The version byte discriminates: a v1 handle
 	// against a partitioned queue is rejected, a v2 handle against
 	// a non-partitioned queue is rejected — both with
-	// ReceiptHandleIsInvalid (codex P1 round-2 on PR #715 documents
-	// the cross-version rejection contract).
+	// ReceiptHandleIsInvalid. Enforcement of the cross-version
+	// rejection contract is wired by Phase 3.D PR 5b together with
+	// the gate-and-lift; this scaffold PR adds the codec only.
 	sqsReceiptHandleVersion2 = byte(0x02)
-	// sqsReceiptHandleVersion is the legacy const name preserved as
-	// an alias of v1 so existing call sites in this file keep
-	// compiling. New call sites SHOULD use sqsReceiptHandleVersion1
-	// (or sqsReceiptHandleVersion2) explicitly.
-	sqsReceiptHandleVersion = sqsReceiptHandleVersion1
 	// Byte sizes used when pre-sizing key buffers. The exact value is not
 	// critical; it only avoids one append growth for typical queue/ID
 	// lengths.
@@ -231,15 +227,28 @@ func newReceiptToken() ([]byte, error) {
 	return buf, nil
 }
 
-// sqsReceiptHandleV1Size is the on-wire byte length of a v1
-// receipt handle: 1 byte version + 8 byte queue_gen + 16 byte
-// message_id + 16 byte receipt_token = 41 bytes.
-const sqsReceiptHandleV1Size = 1 + 8 + sqsMessageIDBytes + sqsReceiptTokenBytes
-
-// sqsReceiptHandleV2Size is the on-wire byte length of a v2
-// (partitioned) receipt handle: v1 + 4 bytes for the partition
-// uint32 inserted between version and queue_gen = 45 bytes.
-const sqsReceiptHandleV2Size = 1 + 4 + 8 + sqsMessageIDBytes + sqsReceiptTokenBytes
+// Per-field byte offsets and total sizes for the v1 / v2 receipt
+// handle layouts. Named constants so a future field-shape change
+// touches the offsets in one place instead of scattering numeric
+// arithmetic through encoders / decoders. Keep this aligned with
+// the table in encodeReceiptHandle / encodeReceiptHandleV2 doc
+// comments — the on-wire format is operator-visible.
+const (
+	// v1 layout: [version][queue_gen][message_id][receipt_token].
+	sqsReceiptHandleV1VersionOffset = 0
+	sqsReceiptHandleV1GenOffset     = sqsReceiptHandleV1VersionOffset + 1
+	sqsReceiptHandleV1IDOffset      = sqsReceiptHandleV1GenOffset + 8
+	sqsReceiptHandleV1TokenOffset   = sqsReceiptHandleV1IDOffset + sqsMessageIDBytes
+	sqsReceiptHandleV1Size          = sqsReceiptHandleV1TokenOffset + sqsReceiptTokenBytes
+
+	// v2 layout: [version][partition][queue_gen][message_id][receipt_token].
+	sqsReceiptHandleV2VersionOffset   = 0
+	sqsReceiptHandleV2PartitionOffset = sqsReceiptHandleV2VersionOffset + 1
+	sqsReceiptHandleV2GenOffset       = sqsReceiptHandleV2PartitionOffset + 4
+	sqsReceiptHandleV2IDOffset        = sqsReceiptHandleV2GenOffset + 8
+	sqsReceiptHandleV2TokenOffset     = sqsReceiptHandleV2IDOffset + sqsMessageIDBytes
+	sqsReceiptHandleV2Size            = sqsReceiptHandleV2TokenOffset + sqsReceiptTokenBytes
+)
 
 // encodeReceiptHandle packs (queue_gen, message_id, receipt_token) into
 // a single opaque v1 blob. Used by SendMessage on a NON-partitioned
@@ -348,11 +357,14 @@ func decodeReceiptHandleV1(b []byte) (*decodedReceiptHandle, error) {
 		return nil, errors.New("receipt handle length or version mismatch")
 	}
 	return &decodedReceiptHandle{
-		Version:         sqsReceiptHandleVersion1,
-		Partition:       0,
-		QueueGeneration: binary.BigEndian.Uint64(b[1:9]),
-		MessageIDHex:    hex.EncodeToString(b[9 : 9+sqsMessageIDBytes]),
-		ReceiptToken:    bytes.Clone(b[9+sqsMessageIDBytes:]),
+		Version:   sqsReceiptHandleVersion1,
+		Partition: 0,
+		QueueGeneration: binary.BigEndian.Uint64(
+			b[sqsReceiptHandleV1GenOffset:sqsReceiptHandleV1IDOffset]),
+		MessageIDHex: hex.EncodeToString(
+			b[sqsReceiptHandleV1IDOffset:sqsReceiptHandleV1TokenOffset]),
+		ReceiptToken: bytes.Clone(
+			b[sqsReceiptHandleV1TokenOffset:sqsReceiptHandleV1Size]),
 	}, nil
 }
 
@@ -361,11 +373,15 @@ func decodeReceiptHandleV2(b []byte) (*decodedReceiptHandle, error) {
 		return nil, errors.New("receipt handle length or version mismatch")
 	}
 	return &decodedReceiptHandle{
-		Version:         sqsReceiptHandleVersion2,
-		Partition:       binary.BigEndian.Uint32(b[1:5]),
-		QueueGeneration: binary.BigEndian.Uint64(b[5:13]),
-		MessageIDHex:    hex.EncodeToString(b[13 : 13+sqsMessageIDBytes]),
-		ReceiptToken:    bytes.Clone(b[13+sqsMessageIDBytes:]),
+		Version: sqsReceiptHandleVersion2,
+		Partition: binary.BigEndian.Uint32(
+			b[sqsReceiptHandleV2PartitionOffset:sqsReceiptHandleV2GenOffset]),
+		QueueGeneration: binary.BigEndian.Uint64(
+			b[sqsReceiptHandleV2GenOffset:sqsReceiptHandleV2IDOffset]),
+		MessageIDHex: hex.EncodeToString(
+			b[sqsReceiptHandleV2IDOffset:sqsReceiptHandleV2TokenOffset]),
+		ReceiptToken: bytes.Clone(
+			b[sqsReceiptHandleV2TokenOffset:sqsReceiptHandleV2Size]),
 	}, nil
 }
 

adapter/sqs_receipt_handle_v2_test.go

@@ -159,6 +159,22 @@ func TestDecodeReceiptHandle_RejectsLengthMismatch(t *testing.T) {
 				return out
 			},
 		},
+		{
+			name: "v2 oversized",
+			make: func() []byte {
+				out := make([]byte, sqsReceiptHandleV2Size+1)
+				out[0] = sqsReceiptHandleVersion2
+				return out
+			},
+		},
+		{
+			name: "v1 oversized",
+			make: func() []byte {
+				out := make([]byte, sqsReceiptHandleV1Size+1)
+				out[0] = sqsReceiptHandleVersion1
+				return out
+			},
+		},
 		{
 			name: "empty",
 			make: func() []byte { return nil },
@@ -229,9 +245,6 @@ func TestReceiptHandleVersionConstants_Distinct(t *testing.T) {
 		"v1 and v2 version bytes must differ for the dispatch to work")
 	require.Equal(t, byte(0x01), sqsReceiptHandleVersion1)
 	require.Equal(t, byte(0x02), sqsReceiptHandleVersion2)
-	require.Equal(t, sqsReceiptHandleVersion1, sqsReceiptHandleVersion,
-		"the legacy alias must continue to point at v1 so existing "+
-			"call sites stay on the v1 path")
 	// On-wire size constants must equal what the encoders write —
 	// pinning them keeps a future struct change from silently
 	// changing the wire format.