feat(tdbe): ParsedRight::from_wire_byte (inverse of as_wire_byte)

Add a `const fn` inverse of the existing `ParsedRight::as_wire_byte`,
decoding the FPSS wire byte (`67` for `'C'`, `80` for `'P'`) into
a typed `ParsedRight`. Returns `None` for any other byte so the
caller can lift the soft-skip / hard-error decision into its own
error type.

Round-trip property test confirms every variant whose
`as_wire_byte()` returns `Some(b)` decodes through
`from_wire_byte(b) == Some(self)`. The `Both` variant has no FPSS
wire encoding, so the test asserts that path stays unrepresentable
on the wire.

Removes the rationale for downstream tick decoders (analytics
chain snapshots, replay validators) to re-type the `67` / `80`
magic numbers at every trust boundary.

Patch bump tdbe 0.12.8 -> 0.12.9 per the 0.12.x patch-only policy;
`thetadatadx` and `ffi` dependency pins lifted to match. No
`thetadatadx` version bump in this commit -- a follow-up release
PR will roll the SDK forward through the next patch.

Closes #495.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: userFRM

CHANGELOG.md

@@ -124,6 +124,17 @@ PR #489 (dispatcher core), #490 (C ABI), #492 (Python), #493
   shipped in this release. The `fpss_smoke` example is restored on
   the callback path.
 
+### tdbe
+
+- `tdbe::right::ParsedRight::from_wire_byte(byte: i32) -> Option<Self>`
+  — `const fn` decoder for the FPSS wire `right` byte (`67` for
+  `'C'`, `80` for `'P'`). Inverse of the existing `as_wire_byte()`.
+  Removes the rationale for downstream tick decoders to re-type the
+  `67` / `80` magic numbers at every trust boundary; round-trip
+  property test confirms `from_wire_byte(self.as_wire_byte().unwrap())
+  == Some(self)` for every variant where the forward direction is
+  defined. Patch bump tdbe 0.12.8 → 0.12.9.
+
 ## [8.0.29] - 2026-05-06
 
 ### Removed

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "tdbe"
-version = "0.12.8"
+version = "0.12.9"
 edition.workspace = true
 rust-version.workspace = true
 authors.workspace = true

crates/tdbe/Cargo.toml

@@ -97,6 +97,39 @@ impl ParsedRight {
             Self::Both => None,
         }
     }
+
+    /// Decode an FPSS wire byte (`67` for `'C'`, `80` for `'P'`) into
+    /// a typed [`ParsedRight`]. Returns [`None`] for any other byte
+    /// so callers can lift the soft-skip / hard-error decision into
+    /// their own error type.
+    ///
+    /// Inverse of [`Self::as_wire_byte`]: every variant whose
+    /// `as_wire_byte()` returns `Some(b)` round-trips through
+    /// `from_wire_byte(b) == Some(self)`.
+    ///
+    /// `const fn` so it stays evaluable in const contexts. Removes the
+    /// rationale for downstream tick decoders (analytics chain
+    /// snapshots, replay validators) to re-type the `67` / `80` magic
+    /// numbers at every trust boundary.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use tdbe::right::ParsedRight;
+    ///
+    /// assert_eq!(ParsedRight::from_wire_byte(67), Some(ParsedRight::Call));
+    /// assert_eq!(ParsedRight::from_wire_byte(80), Some(ParsedRight::Put));
+    /// assert_eq!(ParsedRight::from_wire_byte(0), None);
+    /// assert_eq!(ParsedRight::from_wire_byte(-1), None);
+    /// ```
+    #[must_use]
+    pub const fn from_wire_byte(byte: i32) -> Option<Self> {
+        match byte {
+            67 => Some(Self::Call),
+            80 => Some(Self::Put),
+            _ => None,
+        }
+    }
 }
 
 /// Parse a user-supplied `right` string.
@@ -247,4 +280,55 @@ mod tests {
         let err = parse_right_strict("xyz").unwrap_err();
         assert!(format!("{err}").contains("invalid option right"));
     }
+
+    #[test]
+    fn from_wire_byte_decodes_call_and_put() {
+        assert_eq!(ParsedRight::from_wire_byte(67), Some(ParsedRight::Call));
+        assert_eq!(ParsedRight::from_wire_byte(80), Some(ParsedRight::Put));
+    }
+
+    #[test]
+    fn from_wire_byte_rejects_unknown_bytes() {
+        for byte in [
+            0_i32,
+            1,
+            65,
+            66,
+            68,
+            79,
+            81,
+            100,
+            256,
+            -1,
+            i32::MIN,
+            i32::MAX,
+        ] {
+            assert!(
+                ParsedRight::from_wire_byte(byte).is_none(),
+                "byte {byte} should not decode"
+            );
+        }
+    }
+
+    #[test]
+    fn wire_byte_round_trips_through_inverse() {
+        // Every variant whose `as_wire_byte()` returns Some(b) should
+        // round-trip through `from_wire_byte(b) == Some(self)`.
+        for variant in [ParsedRight::Call, ParsedRight::Put, ParsedRight::Both] {
+            match variant.as_wire_byte() {
+                Some(byte) => {
+                    assert_eq!(
+                        ParsedRight::from_wire_byte(byte),
+                        Some(variant),
+                        "round-trip failed for {variant:?}"
+                    );
+                }
+                None => {
+                    // `Both` returns None on the forward direction —
+                    // there is no FPSS byte to invert from.
+                    assert_eq!(variant, ParsedRight::Both);
+                }
+            }
+        }
+    }
 }

crates/tdbe/src/right.rs

@@ -40,7 +40,7 @@ frames = ["polars", "arrow"]
 live-tests = []
 
 [dependencies]
-tdbe = { version = "0.12.8", path = "../tdbe" }
+tdbe = { version = "0.12.9", path = "../tdbe" }
 
 # gRPC + protobuf (tonic 0.14 extracted prost codec into tonic-prost)
 tonic = { version = "=0.14.5", features = ["tls-ring", "tls-native-roots", "channel", "transport"] }
@@ -141,7 +141,7 @@ prost-build = "=0.14.3"
 regex = "1.12.3"
 toml = "1.1.2"
 serde = { version = "1.0.228", features = ["derive"] }
-tdbe = { version = "0.12.8", path = "../tdbe" }
+tdbe = { version = "0.12.9", path = "../tdbe" }
 
 [[bench]]
 name = "bench_decode"

crates/thetadatadx/Cargo.toml

@@ -31,7 +31,7 @@ testing-panic-boundary = []
 
 [dependencies]
 thetadatadx = { path = "../crates/thetadatadx" }
-tdbe = { version = "0.12.8", path = "../crates/tdbe" }
+tdbe = { version = "0.12.9", path = "../crates/tdbe" }
 tokio = { version = "1.52.1", features = ["rt-multi-thread"] }
 # Used by the FPSS streaming callback silent-drop observability path
 # (see `tdx_fpss_dropped_events` / `tdx_unified_dropped_events`). Keep