Module handle_codec 

Backend-agnostic codec for HandleOpaque payloads.

RFC-v0.7 Wave 1c. Extracted from ff-backend-valkey so the Postgres backend (Wave 4+) decodes the same wire shape. Worker-B §4.1 flagged handle_codec as one of the top Valkey-shape-leaking subsystems in the v0.7 migration master spec; this module is the relocation target.

Responsibilities

• Serialize a HandlePayload (attempt-cookie fields every backend needs to route an op) into the opaque byte buffer carried inside a [Handle]. See encode.
• Parse that buffer back into a HandlePayload plus the BackendTag that minted it. See decode.
• Expose a typed HandleDecodeError mapping cleanly to EngineError::Validation { kind: Corruption, .. } at the backend boundary. See [From<HandleDecodeError> for EngineError].

Wire format v2

New-format opaque buffers are self-identifying — the leading byte distinguishes pre-Wave-1c (Valkey-only) buffers from v2 buffers:

v2 layout (Wave 1c+):
  [0]       u8    magic (0x02) — new-format marker
  [1]       u8    wire version (today: 0x01)
  [2]       u8    BackendTag wire byte (0x01 = Valkey, 0x02 = Postgres)
  [3..]             fields (see §Fields)

v1 layout (pre-Wave-1c, Valkey-only — read-only compat):
  [0]       u8    wire version (0x01)
  [1..]             fields (§Fields)

§Fields

u32(LE)  execution_id length
utf8     execution_id bytes
u32(LE)  attempt_index
u32(LE)  attempt_id length
utf8     attempt_id bytes
u32(LE)  lease_id length
utf8     lease_id bytes
u64(LE)  lease_epoch
u64(LE)  lease_ttl_ms
u32(LE)  lane_id length
utf8     lane_id bytes
u32(LE)  worker_instance_id length
utf8     worker_instance_id bytes

Backward-compat

v1 is Valkey-only: any pre-Wave-1c handle in-flight at upgrade time decodes under BackendTag::Valkey. The magic byte 0x02 was chosen to be disjoint from the v1 leading byte (0x01 = version tag) — the decoder switches on the first byte.

Structs

DecodedHandle

Output of decode — the decoded HandlePayload plus the BackendTag embedded in the opaque buffer (or inferred from the v1 compat path).

HandlePayload

Decoded view of an encoded HandleOpaque — the minimum set of fields every backend needs to construct its per-op KEYS + ARGV.

Enums

HandleDecodeError

Typed decode-failure classification. Mapped to EngineError::Validation { kind: Corruption, .. } at the backend boundary via the From impl.

Functions

decode

Decode a HandleOpaque into a DecodedHandle. Accepts both v2 buffers (leading V2_MAGIC) and legacy v1 Valkey buffers (leading V1_VERSION_TAG); the v1 path returns tag = BackendTag::Valkey.

encode

Encode a HandlePayload into a HandleOpaque tagged with tag. Produces a v2 buffer — callers decoding via decode always get the tag they encoded.