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

* 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>

* docs: sync docs-site/docs/changelog.md with CHANGELOG.md

`Extended Surfaces` job runs `scripts/check_docs_consistency.py`
which verifies the docs-site changelog mirror matches the
canonical `CHANGELOG.md`. Bring it in sync.

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

* fix(extended): bump tdbe to 0.12.9 in tools/sdks Cargo.toml + lockfiles

CI's `Extended Surfaces` job runs `cargo check --locked` against
each separately-locked extended-surface crate (`tools/{cli,server,mcp}`,
`sdks/{python,typescript}`). Their `Cargo.toml` declared
`tdbe = "0.12.8"` and the lockfiles resolved to that, so the
locked check failed once tdbe rebased to `0.12.9` on this branch.

Lift the pin to `0.12.9` and refresh each lockfile so the locked
builds pass.

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

---------

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

@@ -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

docs-site/docs/changelog.md

@@ -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

ffi/Cargo.toml

@@ -19,7 +19,7 @@ doc = false
 [dependencies]
 # The Rust SDK we're wrapping
 thetadatadx = { path = "../../crates/thetadatadx" }
-tdbe = { version = "0.12.8", path = "../../crates/tdbe" }
+tdbe = { version = "0.12.9", path = "../../crates/tdbe" }
 
 # Direct prost dep for decoding `thetadatadx::proto::ResponseData` bytes in
 # the `decode_response_bytes` hook. The main crate no longer re-exports