refactor!: rename Contract.root/exp_date to symbol/expiration (#484)

Closes #467.

Rename the public-API fields on the SDK to match the v3 vendor surface
documented in the v2 → v3 migration guide:

  Contract.root        -> Contract.symbol
  Contract.exp_date    -> Contract.expiration
  OptionContract.root  -> OptionContract.symbol
  FlatFileRow.root     -> FlatFileRow.symbol
  IndexEntry.root      -> IndexEntry.symbol
  IndexEntry.exp       -> IndexEntry.expiration

Plus the matching constructor + parameter renames (Contract::stock(symbol),
Contract::option(symbol, expiration, ...), Contract::option_raw(...),
FlatFileRow::from_decoded(symbol, expiration, ...)) and the cross-language
bindings regenerated from the SSOT (Python, TypeScript, Go, C++, C ABI).

The wire format is unchanged. Contract::to_bytes / Contract::from_bytes
still serialize the field as `root` per Contract.java parity, and the
FLATFILES decoder still resolves both v2 (`root`) and v3 (`symbol`)
response columns through the existing decode::HEADER_ALIASES alias
table.

Workspace 8.0.26 -> 8.0.27, tdbe 0.12.7 -> 0.12.8. CHANGELOG and
docs-site/docs/changelog.md kept byte-identical.

Local CI gate:

  cargo fmt --all -- --check                            # clean
  cargo clippy --workspace --all-targets -- -D warnings # clean
  cargo test --workspace                                # 0 failures
  cargo deny check                                      # advisories+bans+licenses+sources ok
  generate_sdk_surfaces --check                         # no drift
  cargo check/clippy/test --manifest-path tools/mcp/Cargo.toml
  cargo check/clippy/test --manifest-path tools/server/Cargo.toml

Author: userFRM

CHANGELOG.md

@@ -7,6 +7,70 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [8.0.28] - 2026-05-06
+
+### Breaking
+
+- **`Contract`, `OptionContract`, `FlatFileRow`, and `IndexEntry` rename
+  `root` to `symbol` and `exp_date` to `expiration` to match the v3
+  vendor surface documented in the [v2 → v3 migration guide][v3-mig].
+  The wire codec is unchanged — `Contract::to_bytes` /
+  `Contract::from_bytes` still serialize the field as `root` per
+  `Contract.java` parity, and the FLATFILES decoder still resolves both
+  v2 (`root`) and v3 (`symbol`) response columns through the existing
+  `decode::HEADER_ALIASES`. Per-language renames:
+
+  - **Rust** (`thetadatadx::fpss::protocol::Contract`,
+    `tdbe::types::tick::OptionContract`,
+    `thetadatadx::flatfiles::FlatFileRow`):
+    - `Contract.root` → `Contract.symbol`
+    - `Contract.exp_date` → `Contract.expiration`
+    - `Contract::stock(root)` → `Contract::stock(symbol)`
+    - `Contract::index(root)` → `Contract::index(symbol)`
+    - `Contract::rate(root)` → `Contract::rate(symbol)`
+    - `Contract::option(root, exp_date, …)` →
+      `Contract::option(symbol, expiration, …)`
+    - `Contract::option_raw(root, exp_date, …)` →
+      `Contract::option_raw(symbol, expiration, …)`
+    - `OptionContract.root` → `OptionContract.symbol`
+    - `FlatFileRow.root` → `FlatFileRow.symbol`
+  - **Python** (`thetadatadx.Contract`, `thetadatadx.OptionContract`):
+    `contract.root` / `contract.exp_date` →
+    `contract.symbol` / `contract.expiration`;
+    `OptionContract(root=…)` constructor keyword → `symbol=…`.
+  - **TypeScript** (`Contract`, `OptionContract`):
+    `contract.root` / `contract.expDate` →
+    `contract.symbol` / `contract.expiration`.
+  - **Go** (`thetadatadx.Contract`, `thetadatadx.OptionContract`):
+    `c.Root` / `c.ExpDate` → `c.Symbol` / `c.Expiration`.
+  - **C++** (`OptionContract`, `TdxContract`, `TdxOptionContract`):
+    `c.root` / `c.exp_date` / `c.has_exp_date` →
+    `c.symbol` / `c.expiration` / `c.has_expiration`.
+  - **C ABI**: `TdxContract.root` → `TdxContract.symbol`,
+    `TdxContract.exp_date` → `TdxContract.expiration`,
+    `TdxContract.has_exp_date` → `TdxContract.has_expiration`,
+    `TdxOptionContract.root` → `TdxOptionContract.symbol`.
+  - **FLATFILES CSV / JSONL**: contract-prefix headers and JSON keys
+    change from `root,expiration,strike,right,…` to
+    `symbol,expiration,strike,right,…`. Stock blobs go from `root,…` to
+    `symbol,…`. The vendor's response columns are unchanged; only the
+    SDK's emitted file headers change.
+  - **REST / WebSocket / MCP outputs** in `tools/server` and
+    `tools/mcp` emit `"symbol"` / `"expiration"` keys on every contract
+    payload (option lists, FPSS event contracts, FLATFILES rows).
+
+[v3-mig]: https://docs.thetadata.us/Articles/Getting-Started/v2-migration-guide.html#_5-parameter-mapping
+
+### Changed
+
+- Workspace 8.0.27 → 8.0.28, tdbe 0.12.7 → 0.12.8. The tdbe bump rides
+  the regenerated `OptionContract.symbol` field in
+  `crates/tdbe/src/types/tick_generated.rs`; every other change ships
+  as patch deltas off the existing v8 line per repo policy.
+- `tools/cli` raw column header for `OptionContract` is `symbol`
+  instead of `root`, sourced from `tick_schema.toml::field` so future
+  schema renames flow through the CLI without a helper edit.
+
 ## [8.0.27] - 2026-05-06
 
 ### Changed

Cargo.lock

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

crates/tdbe/Cargo.toml

@@ -4,7 +4,7 @@
 /// The FPSS decoder uses it for the empty-contract placeholder that flows on
 /// data events arriving before their `ContractAssigned` frame — downstream
 /// consumers can pattern-match `sec_type == SecType::Unknown` instead of
-/// relying on `contract.root.is_empty()`. `Unknown` has no wire-protocol
+/// relying on `contract.symbol.is_empty()`. `Unknown` has no wire-protocol
 /// representation: [`SecType::from_code`] never returns it, and it is not
 /// serialized in subscribe payloads.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]

crates/tdbe/src/types/enums.rs

@@ -8,7 +8,7 @@
 //!   ...). These read `flags::*` constants and don't fit the schema's
 //!   field-only model.
 //! * `impl OptionContract` for `is_call` / `is_put` -- a non-`Copy` struct
-//!   so the macro doesn't apply.
+//!   (because of the `String` `symbol` field) so the macro doesn't apply.
 //!
 //! The structs themselves are generated at build-time from
 //! `crates/thetadatadx/tick_schema.toml` by

crates/tdbe/src/types/tick.rs

@@ -275,12 +275,12 @@ pub struct OpenInterestTick {
 
 /// Option contract -- 4 fields. Contract specification.
 ///
-/// Cannot be `Copy` because of the `String` root field.
+/// Cannot be `Copy` because of the `String` symbol field.
 #[must_use]
 #[derive(Debug, Clone)]
 #[repr(C)]
 pub struct OptionContract {
-    pub root: String,
+    pub symbol: String,
     pub expiration: i32,
     pub strike: f64,
     pub right: i32,

crates/tdbe/src/types/tick_generated.rs

@@ -1,6 +1,6 @@
 [package]
 name = "thetadatadx"
-version = "8.0.27"
+version = "8.0.28"
 edition.workspace = true
 rust-version.workspace = true
 authors.workspace = true
@@ -40,7 +40,7 @@ frames = ["polars", "arrow"]
 live-tests = []
 
 [dependencies]
-tdbe = { version = "0.12.7", path = "../tdbe" }
+tdbe = { version = "0.12.8", 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"] }
@@ -138,7 +138,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.7", path = "../tdbe" }
+tdbe = { version = "0.12.8", path = "../tdbe" }
 
 [[bench]]
 name = "bench_decode"

crates/thetadatadx/Cargo.toml

@@ -9,7 +9,7 @@
     result.reserve(arr.len);
     for (size_t i = 0; i < arr.len; ++i) {
         OptionContract c;
-        c.root = arr.data[i].root ? std::string(arr.data[i].root) : "";
+        c.symbol = arr.data[i].symbol ? std::string(arr.data[i].symbol) : "";
         c.expiration = arr.data[i].expiration;
         c.strike = arr.data[i].strike;
         c.right = arr.data[i].right;

crates/thetadatadx/build_support/endpoints/render/templates/cpp/option_contracts_convert.cpp.tmpl

@@ -10,16 +10,16 @@ use super::schema::{sorted_data_events, Schema};
 /// `#[repr(C)] TdxContract`. Layout must match field-for-field with
 /// `render_contract_struct_rust` in `ffi_rust.rs`.
 fn render_contract_struct_c() -> &'static str {
-    "/* FPSS Contract shared across every data event. `root` is a\n\
+    "/* FPSS Contract shared across every data event. `symbol` is a\n\
  * NUL-terminated C string (may be null when not yet resolved);\n\
  * optional option fields use a tagged-present bool because C has no\n\
  * Option<T>. Layout is byte-identical to Rust's #[repr(C)] TdxContract.\n\
  */\n\
 typedef struct {\n\
-    const char *root;\n\
+    const char *symbol;\n\
     int32_t sec_type;\n\
-    bool has_exp_date;\n\
-    int32_t exp_date;\n\
+    bool has_expiration;\n\
+    int32_t expiration;\n\
     bool has_is_call;\n\
     bool is_call;\n\
     bool has_strike;\n\

crates/thetadatadx/build_support/fpss_events/ffi_c.rs

@@ -12,7 +12,7 @@ use super::schema::{sorted_data_events, Schema};
 /// event's `contract` field points at. Uses `#[repr(C)]` so the C header
 /// mirror gets byte-identical layout.
 ///
-/// Strings (the `root` field) cross as C strings — the field is
+/// Strings (the `symbol` field) cross as C strings — the field is
 /// `*const c_char` backed by a `CString` inside `FfiBufferedEvent` so the
 /// pointer stays valid for the lifetime of the buffered event. Optional
 /// fields use a tagged-optional pattern (`has_*: bool` + value) because
@@ -21,20 +21,20 @@ fn render_contract_struct_rust() -> String {
     String::from(
         "/// FPSS `Contract` shared across every data event.\n\
 /// \n\
-/// `root` is a NUL-terminated C string; may be null when the SDK has not\n\
+/// `symbol` is a NUL-terminated C string; may be null when the SDK has not\n\
 /// yet resolved the server-assigned contract_id to a `ContractAssigned`\n\
-/// frame. Optional option fields (`exp_date`, `is_call`, `strike`) use a\n\
+/// frame. Optional option fields (`expiration`, `is_call`, `strike`) use a\n\
 /// tagged-present bool because `#[repr(C)]` cannot express `Option<T>`\n\
 /// directly.\n\
 #[repr(C)]\n\
 pub struct TdxContract {\n\
-    /// Ticker root (e.g. \"AAPL\"). Null until ContractAssigned arrives.\n\
-    pub root: *const c_char,\n\
+    /// Ticker symbol (e.g. \"AAPL\"). Null until ContractAssigned arrives.\n\
+    pub symbol: *const c_char,\n\
     /// Security type code — matches `tdbe::types::enums::SecType`.\n\
     pub sec_type: i32,\n\
-    /// Whether `exp_date` is meaningful (options only).\n\
-    pub has_exp_date: bool,\n\
-    pub exp_date: i32,\n\
+    /// Whether `expiration` is meaningful (options only).\n\
+    pub has_expiration: bool,\n\
+    pub expiration: i32,\n\
     /// Whether `is_call` is meaningful (options only).\n\
     pub has_is_call: bool,\n\
     pub is_call: bool,\n\
@@ -44,10 +44,10 @@ pub struct TdxContract {\n\
 }\n\
 \n\
 pub(crate) const ZERO_CONTRACT_STRUCT: TdxContract = TdxContract {\n\
-    root: ptr::null(),\n\
+    symbol: ptr::null(),\n\
     sec_type: 0,\n\
-    has_exp_date: false,\n\
-    exp_date: 0,\n\
+    has_expiration: false,\n\
+    expiration: 0,\n\
     has_is_call: false,\n\
     is_call: false,\n\
     has_strike: false,\n\
@@ -178,14 +178,15 @@ pub(super) fn render_ffi_fpss_event_converter(schema: &Schema) -> String {
         // cursors / auxiliary fields without breaking the FFI conversion.
         out.push_str("            ..\n");
         out.push_str("        }) => {\n");
-        // Stage the CString backing the Contract.root pointer so it
+        // Stage the CString backing the Contract.symbol pointer so it
         // outlives the TdxFpssEvent inside the FfiBufferedEvent. The
         // backing-memory wrapper already has a `_detail_string` slot we
-        // repurpose here — only one owned CString per event, and Contract
-        // .root is mutually exclusive with Control.detail on Data variants.
+        // repurpose here — only one owned CString per event, and
+        // Contract.symbol is mutually exclusive with Control.detail on
+        // Data variants.
         if has_contract {
             out.push_str(
-                "            let contract_root_cstring = if contract.root.is_empty() {\n                None\n            } else {\n                std::ffi::CString::new(contract.root.as_str()).ok()\n            };\n            let contract_root_ptr = contract_root_cstring\n                .as_ref()\n                .map_or(ptr::null(), |cs| cs.as_ptr());\n            let tdx_contract = TdxContract {\n                root: contract_root_ptr,\n                sec_type: contract.sec_type as i32,\n                has_exp_date: contract.exp_date.is_some(),\n                exp_date: contract.exp_date.unwrap_or(0),\n                has_is_call: contract.is_call.is_some(),\n                is_call: contract.is_call.unwrap_or(false),\n                has_strike: contract.strike.is_some(),\n                strike: contract.strike.unwrap_or(0),\n            };\n",
+                "            let contract_symbol_cstring = if contract.symbol.is_empty() {\n                None\n            } else {\n                std::ffi::CString::new(contract.symbol.as_str()).ok()\n            };\n            let contract_symbol_ptr = contract_symbol_cstring\n                .as_ref()\n                .map_or(ptr::null(), |cs| cs.as_ptr());\n            let tdx_contract = TdxContract {\n                symbol: contract_symbol_ptr,\n                sec_type: contract.sec_type as i32,\n                has_expiration: contract.expiration.is_some(),\n                expiration: contract.expiration.unwrap_or(0),\n                has_is_call: contract.is_call.is_some(),\n                is_call: contract.is_call.unwrap_or(false),\n                has_strike: contract.strike.is_some(),\n                strike: contract.strike.unwrap_or(0),\n            };\n",
             );
         }
         out.push_str("            FfiBufferedEvent {\n");
@@ -225,7 +226,7 @@ pub(super) fn render_ffi_fpss_event_converter(schema: &Schema) -> String {
         out.push_str("                raw_data: ZERO_RAW,\n");
         out.push_str("            },\n");
         if has_contract {
-            out.push_str("            _detail_string: contract_root_cstring,\n");
+            out.push_str("            _detail_string: contract_symbol_cstring,\n");
         } else {
             out.push_str("            _detail_string: None,\n");
         }