docs: sweep stale root/exp_date refs across doc tree (closes #503) (#504)

userFRM · claude · web-flow · commit 1f4087fa8891 · 2026-05-07T05:58:48.000+02:00
Post-#484 (8.0.28) follow-up. The Rust SDK rename Contract.root -> Contract.symbol and Contract.exp_date -> Contract.expiration was not propagated to the doc tree. Sweep brings the docs into alignment with the SDK surface; wire codecs (FPSS binary frames, MDDS gRPC) are unchanged. Touched: - docs/api-reference.md - Rust struct definitions and prose - docs/macro-guide.md - parsed_endpoint! example query block - docs/architecture.md - clarifies that the FPSS binary diagram labels are wire-format names, not SDK struct names - docs/java-parity-checklist.md - top-of-file vocabulary note plus Rust-side rewrites; Java-side root/expDate references kept verbatim - docs-site/docs/api-reference.md - field tables and prose - docs-site/docs/streaming/{connection,events}.md - inline comments - docs-site/docs/historical/option/list/roots.md - prose only; URL slug preserved for inbound-link stability - docs-site/docs/historical/option/list/contracts.md - JSON sample, response table, and Go example (t.Root -> t.Symbol) - docs-site/public/thetadatadx.yaml - OpenAPI schema for Contract - sdks/cpp/README.md - OptionContract surface row Version bump 8.0.33 -> 8.0.35 across all manifests; sub-Cargo.lock files updated (8.0.34 placeholder is reserved for Wave 2A's parallel work-stream). CHANGELOG entry added under [8.0.35] in both CHANGELOG.md and the docs-site mirror. Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,6 +5,17 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [8.0.35] - 2026-05-07
+
+### Documentation
+
+- **Sweep stale `root` / `exp_date` references across the doc tree.**
+  Post-#484 (8.0.28) follow-up: `docs/api-reference.md`, `docs/macro-guide.md`,
+  `docs/architecture.md`, `docs/java-parity-checklist.md`, `docs-site/docs/api-reference.md`,
+  `docs-site/docs/streaming/{connection,events}.md`, `docs-site/docs/historical/option/list/{roots,contracts}.md`,
+  `sdks/cpp/README.md` — Rust SDK references rewritten to use the post-#484
+  `symbol` / `expiration` vocabulary. Closes #503.
+
 ## [8.0.33] - 2026-05-07
 
 ### Added
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/crates/thetadatadx/Cargo.toml b/crates/thetadatadx/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "thetadatadx"
-version = "8.0.33"
+version = "8.0.35"
 edition.workspace = true
 rust-version.workspace = true
 authors.workspace = true
diff --git a/docs-site/docs/api-reference.md b/docs-site/docs/api-reference.md
@@ -608,7 +608,7 @@ auto contracts = client.option_list_contracts("TRADE", "SPY", "20240315");
 | `date` | string | Yes | Date (`YYYYMMDD`) |
 | `max_dte` | int | No | Maximum days to expiration filter |
 
-**Returns:** Array of OptionContract records with root, expiration, strike, right.
+**Returns:** Array of OptionContract records with symbol, expiration, strike, right.
 
 ---
 
@@ -2528,9 +2528,9 @@ fpss.subscribe_quotes("AAPL");
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `root` | string | Ticker symbol |
+| `symbol` | string | Ticker symbol |
 | `sec_type` | SecType | Security type |
-| `exp_date` | int (optional) | Expiration date as YYYYMMDD (options only) |
+| `expiration` | int (optional) | Expiration date as YYYYMMDD (options only) |
 | `is_call` | bool (optional) | true = call, false = put (options only) |
 | `strike` | string (optional) | Strike price in dollars (options only) |
 
diff --git a/docs-site/docs/changelog.md b/docs-site/docs/changelog.md
@@ -5,6 +5,17 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [8.0.35] - 2026-05-07
+
+### Documentation
+
+- **Sweep stale `root` / `exp_date` references across the doc tree.**
+  Post-#484 (8.0.28) follow-up: `docs/api-reference.md`, `docs/macro-guide.md`,
+  `docs/architecture.md`, `docs/java-parity-checklist.md`, `docs-site/docs/api-reference.md`,
+  `docs-site/docs/streaming/{connection,events}.md`, `docs-site/docs/historical/option/list/{roots,contracts}.md`,
+  `sdks/cpp/README.md` — Rust SDK references rewritten to use the post-#484
+  `symbol` / `expiration` vocabulary. Closes #503.
+
 ## [8.0.33] - 2026-05-07
 
 ### Added
diff --git a/docs-site/docs/historical/option/list/contracts.md b/docs-site/docs/historical/option/list/contracts.md
@@ -32,7 +32,7 @@ console.log(data);
 data, _ := client.OptionListContracts("TRADE", "SPY", "20260402")
 for _, t := range data {
     fmt.Printf("symbol=%s expiration=%d strike=%.2f right=%s\n",
-        t.Root, t.Expiration, t.Strike, t.Right)
+        t.Symbol, t.Expiration, t.Strike, t.Right)
 }
 ```
 ```cpp [C++]
@@ -69,7 +69,7 @@ for (const auto& t : data) {
 
 <div class="param-list">
 <div class="param">
-<div class="param-header"><code>root</code><span class="param-type">string</span></div>
+<div class="param-header"><code>symbol</code><span class="param-type">string</span></div>
 <div class="param-desc">Underlying symbol</div>
 </div>
 <div class="param">
@@ -91,12 +91,18 @@ for (const auto& t : data) {
 
 ```json
 [
-  {"root": "SPY", "expiration": 20260403, "strike": 320.00, "right": "C"},
-  {"root": "SPY", "expiration": 20260403, "strike": 640.00, "right": "C"},
-  {"root": "SPY", "expiration": 20260417, "strike": 550.00, "right": "P"}
+  {"symbol": "SPY", "expiration": 20260403, "strike": 320.00, "right": "C"},
+  {"symbol": "SPY", "expiration": 20260403, "strike": 640.00, "right": "C"},
+  {"symbol": "SPY", "expiration": 20260417, "strike": 550.00, "right": "P"}
 ]
 ```
 
+> Field names above match the typed `OptionContract` struct exposed by every
+> SDK (`symbol`, `expiration`, `strike`, `right`). The `Vec<OptionContract>` is
+> decoded from the v3 gRPC `DataTable` response — there is no raw JSON wire
+> format on this endpoint, so the SDK's `symbol` vocabulary is what callers
+> see.
+
 > Lists all option contracts for SPY on the given date. 5,467 contracts returned for 2026-04-02.
 
 ## Notes
diff --git a/docs-site/docs/historical/option/list/roots.md b/docs-site/docs/historical/option/list/roots.md
@@ -61,9 +61,9 @@ None.
 ["SPY", "SPY1", "SPY2", "SPY7"]
 ```
 
-> Returns all option root symbols for the given underlying.
+> Returns the full list of underlying symbols with available option chains.
 
 ## Notes
 
 - Returns all underlying symbols, not individual contracts. Use [option_list_expirations](./expirations) and [option_list_strikes](./strikes) to drill into a specific chain.
-- The Rust SDK method is `option_list_symbols`; "roots" refers to the underlying concept in ThetaData's API.
+- The Rust SDK method is `option_list_symbols`. The legacy "roots" term is preserved in this page's URL slug for inbound-link stability; the SDK and protobuf surface use `symbol` exclusively.
diff --git a/docs-site/docs/streaming/connection.md b/docs-site/docs/streaming/connection.md
@@ -34,7 +34,7 @@ let tdx = ThetaDataDx::connect(&creds, DirectConfig::production()).await?;
 
 tdx.start_streaming(|event: &FpssEvent| {
     match event {
-        // Every data event carries an `Arc<Contract>` — read the root ticker
+        // Every data event carries an `Arc<Contract>` — read the symbol
         // directly, no contract-ID map lookup required.
         FpssEvent::Data(FpssData::Quote { contract, bid, ask, received_at_ns, .. }) => {
             println!("Quote: {} bid={bid:.2} ask={ask:.2} rx={received_at_ns}ns", contract.symbol);
diff --git a/docs-site/docs/streaming/events.md b/docs-site/docs/streaming/events.md
@@ -13,7 +13,7 @@ tdx.start_streaming(|event: &FpssEvent| {
     match event {
         // --- Data events ---
         // Each data variant carries an `Arc<Contract>`, so `contract.symbol`
-        // (plus `.exp_date` / `.strike` / `.is_call` on options) is readable
+        // (plus `.expiration` / `.strike` / `.is_call` on options) is readable
         // inline — no contract-ID map lookup required.
         FpssEvent::Data(FpssData::Quote {
             contract, ms_of_day, bid, ask, bid_size, ask_size,
diff --git a/docs-site/public/thetadatadx.yaml b/docs-site/public/thetadatadx.yaml
@@ -3279,14 +3279,14 @@ components:
       type: object
       description: Full contract representation used in streaming
       properties:
-        root:
+        symbol:
           type: string
           description: Underlying symbol
         sec_type:
           type: integer
           enum: [0, 1, 2, 3]
           description: '0=Stock, 1=Option, 2=Index, 3=Rate'
-        exp_date:
+        expiration:
           type: integer
           description: Expiration as YYYYMMDD integer (options only)
         is_call:
diff --git a/docs/api-reference.md b/docs/api-reference.md
@@ -948,9 +948,9 @@ Returns `None` for permanent credential/account errors (`InvalidCredentials`, `I
 
 ```rust
 pub struct Contract {
-    pub root: String,
+    pub symbol: String,
     pub sec_type: SecType,
-    pub exp_date: Option<i32>,
+    pub expiration: Option<i32>,
     pub is_call: Option<bool>,
     pub strike: Option<i32>,
 }
@@ -1294,11 +1294,11 @@ pub struct InterestRateTick {
 
 ### OptionContract
 
-Option contract specification. Not `Copy` due to `String` root field.
+Option contract specification. Not `Copy` due to `String` symbol field.
 
 ```rust
 pub struct OptionContract {
-    pub root: String,
+    pub symbol: String,
     pub expiration: i32,
     pub strike: f64,
     pub right: i32,
diff --git a/docs/architecture.md b/docs/architecture.md
@@ -297,7 +297,13 @@ sequenceDiagram
 
 ### Contract Binary Format
 
-Contracts are serialized differently for equities vs options:
+Contracts are serialized differently for equities vs options. The byte-level
+labels below (`root_len`, `root`, `exp_date`) are the **FPSS streaming wire
+field names** and are deliberately preserved as-is; they describe the binary
+layout the FPSS server emits and consumes. The Rust SDK's `Contract` struct
+exposes these fields as `symbol` and `expiration` (renamed in #484, v8.0.28),
+but the on-the-wire encoding is unchanged. The MDDS gRPC v3 surface uses
+`symbol` natively in its protobuf schema.
 
 ```mermaid
 packet-beta
diff --git a/docs/java-parity-checklist.md b/docs/java-parity-checklist.md
@@ -4,6 +4,13 @@ Feature-by-feature comparison of the Rust SDK against the Java terminal's
 behavior. `[✓]` = parity, `[✗]` = intentional deviation (documented),
 `[~]` = partial / in progress.
 
+> **Vocabulary note.** The Java terminal exposes contract fields under the v2
+> wire names (`root`, `expDate`). The Rust SDK exposes them under the
+> post-#484 v3 vocabulary (`symbol`, `expiration`); see CHANGELOG entry for
+> v8.0.28. The wire codec is unchanged — the rename is API-side only — so any
+> `root` / `expDate` references on the Java side of a comparison row are kept
+> verbatim, and the Rust counterpart is given in the post-rename form.
+
 > **Last audited**: 2026-04-03 against the Java terminal v202603181.
 > Coverage: all 21 `StreamMsgType` codes, all 19 `RemoveReason` codes, all 4
 > `StreamResponseType` codes, all 4 `SecType` codes, all 30 `ReqType` codes,
@@ -108,7 +115,7 @@ client projections from that data. Requests remain wire-identical.
 | Ring-buffer capacity monitoring | [~] | Java's `RingBuffer.remainingCapacity()` enables back-pressure warnings; `disruptor-rs` v4 does not expose a fill-level API. Known upstream limitation. |
 | `FpssEvent` split (`FpssData` + `FpssControl`) | [✗] | Intentional API improvement — enables exhaustive `match` on data-only events without touching lifecycle events. Wire format unchanged. |
 | FPSS streaming prices exposed as `f64` | [✗] | Intentional improvement — Rust decodes prices at frame-parse time using the per-cell `price_type`. Java exposes raw integers + `price_type` and requires callers to invoke `PriceCalcUtils` manually. |
-| `Contract::option(root, exp, strike, right)` API | [✗] | Intentional improvement — Rust accepts string inputs matching MDDS historical (`"SPY"`, `"20260417"`, `"550"`, `"C"`). Java's `Contract(root, expDate, isCall, strike)` leaks wire-format details. `Contract::option_raw()` is available for the drop-in server. |
+| `Contract::option(symbol, expiration, strike, right)` API | [✗] | Intentional improvement — Rust accepts string inputs matching MDDS historical (`"SPY"`, `"20260417"`, `"550"`, `"C"`). Java's `Contract(root, expDate, isCall, strike)` leaks wire-format details. A typed `IntoOptionSpec` constructor is planned for 9.0.0 to replace the deferred `Contract::option_raw()` shape used by the drop-in server. |
 | FPSS subscription tracking | [✗] | Rust: per-instance `Mutex`. Java: static `ConcurrentHashMap` shared across all `FPSSClient` instances in the JVM. Rust isolates subscription state per client. |
 | Full-type subscribe payload `[req_id: i32 BE] [sec_type: u8]` | [✓] | |
 | `contract_map` cleared on `START`/`STOP` | [✓] | Matches Java's `idToContract.clear()`. |
@@ -147,7 +154,7 @@ client projections from that data. Requests remain wire-identical.
 
 | Feature | Parity | Notes |
 |---------|:------:|-------|
-| Contract root length check | [✗] | Rust: `assert!(root.len() <= 244)`. Java: silent `as byte` truncation. |
+| Contract symbol length check | [✗] | Rust: `assert!(symbol.len() <= 244)`. Java: silent `as byte` truncation on the `root` field. |
 | Price-type range check | [✓] | Both enforce `0 <= type < 20`. |
 | Frame payload size | [✗] | Rust: `assert!(payload.len() <= 255)` in release. Java: implicit `u8` truncation. |
 | Date format validation (8 ASCII digits) | [✗] | Rust validates client-side in `mdds/validate.rs::validate_date()`. Java relies on server-side rejection. |
@@ -273,8 +280,8 @@ Rust SDK defaults to `"09:30:00"`/`"16:00:00"` on all interval endpoints.
   instead of logging them as garbled strings.
 - **`f64` prices at parse time** — no `price_type` in the public API; every
   `Price` cell is decoded using its own `price_type`.
-- **Typed `Contract::option(root, exp, strike, right)` API** — strings
-  matching the MDDS historical API; no wire-format leakage.
+- **Typed `Contract::option(symbol, expiration, strike, right)` API** —
+  strings matching the MDDS historical API; no wire-format leakage.
 
 ## Class-level mapping
 
diff --git a/docs/macro-guide.md b/docs/macro-guide.md
@@ -44,7 +44,7 @@ parsed_endpoint! {
     grpc: get_stock_history_ohlc;     // gRPC stub method name
     request: StockHistoryOhlcRequest; // protobuf request wrapper type
     query: StockHistoryOhlcParams {   // protobuf params struct + field mapping
-        root: symbol.to_string(),
+        symbol: symbol.to_string(),
         date: date.to_string(),
         ivl: interval.to_string(),
     };
diff --git a/ffi/Cargo.toml b/ffi/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "thetadatadx-ffi"
-version = "8.0.33"
+version = "8.0.35"
 edition.workspace = true
 rust-version.workspace = true
 authors.workspace = true
diff --git a/sdks/cpp/README.md b/sdks/cpp/README.md
@@ -256,7 +256,7 @@ All endpoints return fully typed C++ structs. No raw JSON.
 | `IvTick` | ms_of_day, implied_volatility, iv_error, date, **expiration, strike, right** | IV-only endpoints |
 | `PriceTick` | ms_of_day, price, date | Index price endpoints |
 | `MarketValueTick` | ms_of_day, market_bid, market_ask, market_price, date, **expiration, strike, right** | Market value endpoints |
-| `OptionContract` | root, expiration, strike, right | option_list_contracts |
+| `OptionContract` | symbol, expiration, strike, right | option_list_contracts |
 | `CalendarDay` | date, is_open, open_time, close_time, status | Calendar endpoints |
 | `InterestRateTick` | ms_of_day, rate, date | Interest rate endpoints |
 | `Greeks` | implied_volatility, delta, gamma, theta, vega, rho, iv_error, vanna, charm, vomma, veta, speed, zomma, color, ultima, d1, d2, dual_delta, dual_gamma, epsilon, lambda, vera | Standalone all_greeks() |
diff --git a/sdks/python/Cargo.lock b/sdks/python/Cargo.lock
diff --git a/sdks/python/Cargo.toml b/sdks/python/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "thetadatadx-py"
-version = "8.0.33"
+version = "8.0.35"
 edition = "2021"
 description = "Python bindings for thetadatadx — native ThetaData SDK powered by Rust"
 license = "Apache-2.0"
diff --git a/sdks/typescript/Cargo.lock b/sdks/typescript/Cargo.lock
diff --git a/sdks/typescript/Cargo.toml b/sdks/typescript/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "thetadatadx-napi"
-version = "8.0.33"
+version = "8.0.35"
 edition = "2021"
 description = "TypeScript/Node.js bindings for thetadatadx — native ThetaData SDK powered by Rust"
 license = "Apache-2.0"
diff --git a/sdks/typescript/npm/darwin-arm64/package.json b/sdks/typescript/npm/darwin-arm64/package.json
@@ -1,6 +1,6 @@
 {
   "name": "thetadatadx-darwin-arm64",
-  "version": "8.0.33",
+  "version": "8.0.35",
   "os": [
     "darwin"
   ],
diff --git a/sdks/typescript/npm/linux-x64-gnu/package.json b/sdks/typescript/npm/linux-x64-gnu/package.json
@@ -1,6 +1,6 @@
 {
   "name": "thetadatadx-linux-x64-gnu",
-  "version": "8.0.33",
+  "version": "8.0.35",
   "os": [
     "linux"
   ],
diff --git a/sdks/typescript/npm/win32-x64-msvc/package.json b/sdks/typescript/npm/win32-x64-msvc/package.json
@@ -1,6 +1,6 @@
 {
   "name": "thetadatadx-win32-x64-msvc",
-  "version": "8.0.33",
+  "version": "8.0.35",
   "os": [
     "win32"
   ],
diff --git a/sdks/typescript/package.json b/sdks/typescript/package.json
@@ -1,6 +1,6 @@
 {
   "name": "thetadatadx",
-  "version": "8.0.33",
+  "version": "8.0.35",
   "description": "Native ThetaData SDK for Node.js — powered by Rust via napi-rs",
   "license": "Apache-2.0",
   "repository": {
@@ -30,9 +30,9 @@
     "@napi-rs/cli": "^3.6.2"
   },
   "optionalDependencies": {
-    "thetadatadx-linux-x64-gnu": "8.0.33",
-    "thetadatadx-darwin-arm64": "8.0.33",
-    "thetadatadx-win32-x64-msvc": "8.0.33"
+    "thetadatadx-linux-x64-gnu": "8.0.35",
+    "thetadatadx-darwin-arm64": "8.0.35",
+    "thetadatadx-win32-x64-msvc": "8.0.35"
   },
   "engines": {
     "node": ">= 20"
diff --git a/tools/cli/Cargo.toml b/tools/cli/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "thetadatadx-cli"
-version = "8.0.33"
+version = "8.0.35"
 edition.workspace = true
 rust-version.workspace = true
 authors.workspace = true
diff --git a/tools/mcp/Cargo.lock b/tools/mcp/Cargo.lock
diff --git a/tools/mcp/Cargo.toml b/tools/mcp/Cargo.toml
diff --git a/tools/server/Cargo.lock b/tools/server/Cargo.lock
diff --git a/tools/server/Cargo.toml b/tools/server/Cargo.toml
