fix(v9.1.0): close codex r12 audit findings — sequence helper validation, more doc drift, ROADMAP wave vocabulary

Three findings from the r12 PR-wide audit on PR #514, all closed.

1. **TS sequence helpers reject out-of-range BigInt (Medium)** — the
   prior pass relied on `BigInt::get_u64()` which conflates negative
   inputs with truly out-of-range bigints, so
   `sequenceUnsignedToSigned(-1n)` silently returned `1n` instead of
   throwing, and `sequenceSignedToUnsigned(2^63)` saturated to
   `i64::MAX` instead of throwing. Replaced with a hand-written
   `bigint_to_i32` helper that walks the napi `(sign_bit, words)`
   representation directly. The helpers now:
   - clamp the signed input to the i32 wire range
     (`-2_147_483_648..=2_147_483_647`) — this is the actual
     terminal-protocol wire range; the SDK widens to i64 internally
     but the round-trip is only meaningful in i32 (per
     `crates/tdbe/src/sequences.rs:8-14`);
   - clamp the unsigned input to the unsigned wire range (`0..=2^32 - 1`);
   - throw on negative BigInt to `sequenceUnsignedToSigned`;
   - accept the asymmetric `i32::MIN` boundary correctly.
   Test suite gained range / rejection coverage; `npm test` runs
   19 / 19.

2. **Doc drift remainder (Medium)** — purged the stale public-surface
   references the prior pass missed:
   - `docs/api-reference.md`: TypeScript section described streaming
     as `tdx.startStreaming()` / `tdx.nextEvent()`. Both removed; the
     section now points to push-callback (`tdx.startStreaming(callback)`)
     and pull-iter (`for await (const event of await
     tdx.startStreamingIter())`). The TypeScript code example was
     fully rewritten against the modern API
     (`Contract.stock(...).quote()`, `await client.startStreamingIter()`,
     `awaitDrain` on shutdown). The contract-fields table dropped
     the Go-only column.
   - `docs-site/docs/streaming/connection.md`: replaced the
     `nextEvent()` row in the async/sync table with the actual
     `EventIterator.next(timeoutMs)` shape.
   - `docs-site/docs/getting-started/streaming.md`: the architecture
     paragraph dropped Go from the "polling queue" enumeration
     (Wave H removed Go end-to-end).

3. **ROADMAP.md vocabulary scrub (Low)** — `docs/ROADMAP.md` is a
   user-facing doc page and still leaked Wave / issue-tracker
   vocabulary (`Wave O`, `#431` / `#432` / `#433` / `#436` / `#438`,
   `#424`). The "Tracking" column on the binding-status table and
   the per-row `(Wave O)` annotations on the coverage matrix are
   gone; the open-work paragraph now says "Shipped" without the
   issue-number reference.

Pre-push pipeline: cargo fmt --all -- --check, clippy --workspace
--locked -- -D warnings, test --workspace --locked, deny check all,
docs consistency, generate_sdk_surfaces --check, npm run build, npm
test (19/19 pass), C++ CMake all green.

Author: userFRM

docs-site/docs/getting-started/streaming.md

@@ -18,7 +18,7 @@ graph LR
     C -->|"Disruptor SPSC<br/>131,072 slots"| D["Your app<br/>(callback / poll)"]
 ```
 
-Events are decoded from the FIT wire format and delta-decompressed on a dedicated I/O thread, then dispatched through an LMAX Disruptor SPSC ring buffer to your callback (Rust) or polling queue (Python / TypeScript / Go / C++). Every data event carries a `received_at_ns` nanosecond timestamp captured at frame decode time.
+Events are decoded from the FIT wire format and delta-decompressed on a dedicated I/O thread, then dispatched through an LMAX Disruptor SPSC ring buffer to your callback (push mode) or pull-iter consumer (Python / TypeScript / C++). Every data event carries a `received_at_ns` nanosecond timestamp captured at frame decode time.
 
 ## SPKI pinning
 

docs-site/docs/streaming/connection.md

@@ -215,7 +215,7 @@ ThetaDataDx uses two different concurrency models for its two data paths:
 |------|---------|-----|
 | `connect()` + all historical methods | **async** (tokio) | gRPC/tonic requires tokio for HTTP/2 multiplexing |
 | `start_streaming()` + callbacks | **sync** (OS threads) | Dedicated I/O thread + LMAX Disruptor ring buffer for lowest latency |
-| TypeScript `nextEvent()` | **Promise** (napi-rs) | Returns `Promise<FpssEvent \| null>` so Node's event loop stays unblocked during the 50ms read timeout |
+| TypeScript `EventIterator.next(timeoutMs)` | **Promise** (napi-rs) | Returns `Promise<FpssEvent \| null>` (`null` = timeout / drained) so Node's event loop stays unblocked during the read timeout |
 
 **What this means for your code:**
 

docs/ROADMAP.md

@@ -133,31 +133,31 @@ Server retention window: 7 calendar days. Older history: contact ThetaData sales
 
 ### FLATFILES — Binding Coverage
 
-| Binding | Status | Tracking |
-|---------|--------|----------|
-| Rust (`crates/thetadatadx`) | Shipped | v8.0.17 |
-| FFI (`ffi/`) | Shipped | #434 |
-| CLI (`tools/cli`) | Shipped | #433 (Wave O / v9.1.0) |
-| MCP (`tools/mcp`) | Shipped | #431 (Wave O / v9.1.0) |
-| REST/WS server (`tools/server`) | Shipped | #432 (Wave O / v9.1.0) |
-| Python (`sdks/python`) | Shipped | #435 |
-| TypeScript (`sdks/typescript`) | Shipped | #436 |
-| C++ (`sdks/cpp`) | Shipped | #438 |
-| `sdk_surface.toml` declarative spec | Skipped (hand-written) | #439 — flatfile bindings are intentionally hand-written; the dynamic `(SecType, ReqType)` schema doesn't fit the static codegen surface and the function set is finite. |
+| Binding | Status |
+|---------|--------|
+| Rust (`crates/thetadatadx`) | Shipped |
+| FFI (`ffi/`) | Shipped |
+| CLI (`tools/cli`) | Shipped |
+| MCP (`tools/mcp`) | Shipped |
+| REST/WS server (`tools/server`) | Shipped |
+| Python (`sdks/python`) | Shipped |
+| TypeScript (`sdks/typescript`) | Shipped |
+| C++ (`sdks/cpp`) | Shipped |
+| `sdk_surface.toml` declarative spec | Skipped (hand-written) — flatfile bindings are intentionally hand-written; the dynamic `(SecType, ReqType)` schema doesn't fit the static codegen surface and the function set is finite. |
 
 ## Binding Coverage Matrix
 
-End-to-end status of each public surface across every SDK / tool surface ThetaDataDx ships. Wave O (v9.1.0) closes the FLATFILES gaps in the tools row and the cross-language utility helpers gap.
+End-to-end status of each public surface across every SDK / tool surface ThetaDataDx ships.
 
 | Surface | Rust | Python | TypeScript | C | C++ | MCP | CLI | REST/WS |
 |---|---|---|---|---|---|---|---|---|
 | FPSS streaming push (callback) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ (control events surface as ticks) | ✅ | ✅ (WS broadcast) |
 | FPSS streaming pull (iter) | ✅ | ✅ | ✅ | ✅ | ✅ | — | — | — |
 | MDDS historical endpoints | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| FLATFILES whole-universe blobs | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ (Wave O) | ✅ (Wave O) | ✅ (Wave O) |
-| Cross-language utils — conditions | ✅ | ✅ (Wave O) | ✅ (Wave O) | ✅ (Wave O) | ✅ (Wave O) | — | — | — |
-| Cross-language utils — exchange | ✅ | ✅ (Wave O) | ✅ (Wave O) | ✅ (Wave O) | ✅ (Wave O) | — | — | — |
-| Cross-language utils — sequences | ✅ | ✅ (Wave O) | ✅ (Wave O) | ✅ (Wave O) | ✅ (Wave O) | — | — | — |
+| FLATFILES whole-universe blobs | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Cross-language utils — conditions | ✅ | ✅ | ✅ | ✅ | ✅ | — | — | — |
+| Cross-language utils — exchange | ✅ | ✅ | ✅ | ✅ | ✅ | — | — | — |
+| Cross-language utils — sequences | ✅ | ✅ | ✅ | ✅ | ✅ | — | — | — |
 | Greeks (offline calculator) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | — |
 | Implied volatility (offline) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | — |
 | Authentication / config / ping | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
@@ -185,7 +185,7 @@ Empty cells (`—`) are intentional: the MCP / CLI / REST surfaces don't expose
 
 ### Cross-language parity for `utils`
 
-Shipped in Wave O (v9.1.0). The Rust SDK exposes `tdbe::{conditions, exchange, sequences}` for post-processing tick records, and every public binding now mirrors that surface. Tracked under issue #424.
+Shipped. The Rust SDK exposes `tdbe::{conditions, exchange, sequences}` for post-processing tick records, and every public binding mirrors that surface.
 
 - [x] **Python** — `thetadatadx.util.{condition_name, exchange_name, exchange_symbol, sequence_signed_to_unsigned, ...}` via PyO3.
 - [x] **TypeScript** — `Util.{conditionName, exchangeName, exchangeSymbol, sequenceSignedToUnsigned, ...}` via napi-rs.

docs/api-reference.md

@@ -699,7 +699,7 @@ Every historical endpoint is available in the Python SDK via PyO3 bindings (e.g.
 
 ### TypeScript/Node.js SDK Coverage
 
-Every historical endpoint is available in the TypeScript/Node.js SDK via napi-rs bindings as camelCase methods (e.g., `tdx.stockHistoryEOD(...)`). Streaming is available via `tdx.startStreaming()` / `tdx.nextEvent()`. Returns columnar objects with typed fields.
+Every historical endpoint is available in the TypeScript/Node.js SDK via napi-rs bindings as camelCase methods (e.g., `tdx.stockHistoryEOD(...)`). Streaming is available in two modes: push-callback (`tdx.startStreaming(callback)`) and pull-iter (`for await (const event of await tdx.startStreamingIter())`); both return typed objects with the same field shape. Returns columnar objects with typed fields.
 
 ### Python SDK: Streaming
 
@@ -902,22 +902,29 @@ Check `event->kind` then read the corresponding field. Only the field matching `
 ### TypeScript/Node.js SDK: Streaming
 
 ```typescript
-import { ThetaDataDxClient } from 'thetadatadx';
+import { ThetaDataDxClient, Contract } from 'thetadatadx';
 
 const tdx = await ThetaDataDxClient.connectFromFile('creds.txt');
 
-tdx.startStreaming();
-tdx.subscribe(ContractRef.stock('AAPL').quote());
-while (true) {
-    const event = tdx.nextEvent(5000);
-    if (!event) continue;
-    if (event.kind === 'quote') {
-        console.log(`Quote: bid=${event.bid} ask=${event.ask}`);
-    } else if (event.kind === 'trade') {
-        console.log(`Trade: price=${event.price} size=${event.size}`);
+tdx.subscribe(Contract.stock('AAPL').quote());
+
+// Pull-iter mode: async iterable over the SPSC queue. Resolves
+// `done: true` once stopStreaming() fires and the queue drains.
+const iter = await tdx.startStreamingIter();
+try {
+    for await (const event of iter) {
+        if (event.kind === 'quote') {
+            console.log(`Quote: bid=${event.bid} ask=${event.ask}`);
+        } else if (event.kind === 'trade') {
+            console.log(`Trade: price=${event.price} size=${event.size}`);
+        } else if (event.kind === 'disconnected') {
+            break;
+        }
     }
+} finally {
+    tdx.stopStreaming();
+    await tdx.awaitDrain(5000);
 }
-tdx.stopStreaming();
 ```
 
 ### C++ SDK: Streaming
@@ -1082,11 +1089,11 @@ All generated tick types are `Clone + Debug` structs generated from `tick_schema
 
 > **Note:** Only `expiration` and `strike` support wildcards (`"0"`). The `right` parameter does **not** accept wildcards -- you must specify `"C"` or `"P"`.
 
-| Field | Type (Rust/FFI) | Type (Go) | Description |
-|-------|-----------------|-----------|-------------|
-| `expiration` | `i32` | `int32` | Contract expiration date (YYYYMMDD). 0 on single-contract queries. |
-| `strike` | `i32` | `int32` | Strike price (f64, decoded at parse time). |
-| `right` | `i32` | `string` | Contract right. Rust/FFI: `67` = Call, `80` = Put, `0` = absent. Go: `"C"`, `"P"`, `""`. |
+| Field | Type (Rust/FFI) | Description |
+|-------|-----------------|-------------|
+| `expiration` | `i32` | Contract expiration date (YYYYMMDD). 0 on single-contract queries. |
+| `strike` | `i32` | Strike price (wire integer in thousandths of a dollar; `f64` after decode at parse time). |
+| `right` | `i32` | Contract right. Rust/FFI ASCII byte: `67` (`'C'`) = Call, `80` (`'P'`) = Put, `0` = absent. Python / TypeScript surface this as `right: Optional[str]` (`"C"` / `"P"`). |
 
 Helper methods on all 10 tick types:
 

sdks/typescript/__tests__/util_helpers.test.mjs

@@ -32,10 +32,45 @@ describe('Util cross-language helpers (#424)', () => {
     assert.equal(mod.Util.exchangeName(-1), 'UNKNOWN');
     assert.equal(mod.Util.exchangeSymbol(9999), 'UNKNOWN');
 
-    // Sequence helpers — bidirectional round-trip.
-    const signed = -1n;
-    const unsigned = mod.Util.sequenceSignedToUnsigned(signed);
-    assert.equal(typeof unsigned, 'bigint');
-    assert.equal(mod.Util.sequenceUnsignedToSigned(unsigned), signed);
+    // Sequence helpers — bidirectional round-trip across the i32
+    // wire range, including the asymmetric `i32::MIN` boundary. The
+    // upstream Java terminal encodes trade sequences as i32; the SDK
+    // widens to i64 internally, but the meaningful round-trip is the
+    // i32 range.
+    for (const signed of [-1n, 0n, 1n, 2147483647n, -2147483648n]) {
+      const unsigned = mod.Util.sequenceSignedToUnsigned(signed);
+      assert.equal(typeof unsigned, 'bigint');
+      assert.equal(mod.Util.sequenceUnsignedToSigned(unsigned), signed);
+    }
+  });
+
+  it('rejects BigInt inputs outside the wire range instead of silent coercion', async () => {
+    let mod;
+    try {
+      mod = await import('../index.js');
+    } catch {
+      console.log('SKIP: native addon not built');
+      return;
+    }
+    // i32::MAX + 1 — out of wire range.
+    assert.throws(
+      () => mod.Util.sequenceSignedToUnsigned(2147483648n),
+      /i32 wire range/,
+    );
+    // i32::MIN - 1 — out of wire range.
+    assert.throws(
+      () => mod.Util.sequenceSignedToUnsigned(-2147483649n),
+      /i32 wire range/,
+    );
+    // Negative BigInt for the unsigned helper — never valid.
+    assert.throws(
+      () => mod.Util.sequenceUnsignedToSigned(-1n),
+      /negative BigInt rejected/,
+    );
+    // Greater than 2^32 - 1 — out of unsigned wire range.
+    assert.throws(
+      () => mod.Util.sequenceUnsignedToSigned(4294967296n),
+      /wire range/,
+    );
   });
 });

sdks/typescript/index.d.ts

@@ -75,31 +75,78 @@ impl Util {
 
     /// Convert a signed wire-encoded trade-sequence value to its unsigned
     /// monotonic form. Mirrors `tdbe::sequences::signed_to_unsigned`.
-    /// Accepts a JS BigInt for the full i64 wire range; returns a JS
-    /// BigInt because the full u64 range cannot fit in a JS Number.
+    /// Accepts a JS BigInt in the **i32 wire range**
+    /// (`-2_147_483_648 ..= 2_147_483_647`) — the upstream Java
+    /// terminal encodes trade sequences as i32; the SDK widens to
+    /// i64 internally, but the meaningful round-trip is the i32
+    /// range. Returns a JS BigInt because the unsigned monotonic
+    /// sequence id can exceed `Number.MAX_SAFE_INTEGER`. Inputs
+    /// outside the i32 wire range throw so silent coercion cannot
+    /// produce a look-correct-but-wrong sequence id downstream.
     #[napi(js_name = "sequenceSignedToUnsigned")]
-    pub fn sequence_signed_to_unsigned(signed_value: BigInt) -> BigInt {
-        let (signed_neg, value, _) = signed_value.get_u64();
-        // `BigInt::get_u64` returns the magnitude in `value` and the
-        // sign in `signed_neg`. Reconstruct the i64 wire value by
-        // negating when the sign bit is set; saturating because the
-        // wire format itself is bounded by i64::MIN..=i64::MAX.
-        let signed = if signed_neg {
-            i64::try_from(value).map_or(i64::MIN, i64::wrapping_neg)
-        } else {
-            i64::try_from(value).unwrap_or(i64::MAX)
-        };
-        BigInt::from(tdbe::sequences::signed_to_unsigned(signed))
+    pub fn sequence_signed_to_unsigned(signed_value: BigInt) -> napi::Result<BigInt> {
+        let signed: i64 = bigint_to_i32(&signed_value).map(i64::from).ok_or_else(|| {
+            napi::Error::from_reason(
+                "sequenceSignedToUnsigned: BigInt outside the i32 wire range \
+                 (-2_147_483_648 ..= 2_147_483_647)",
+            )
+        })?;
+        Ok(BigInt::from(tdbe::sequences::signed_to_unsigned(signed)))
     }
 
     /// Convert an unsigned monotonic trade-sequence value back to its
     /// signed wire encoding. Mirrors `tdbe::sequences::unsigned_to_signed`.
-    /// Accepts a JS BigInt for the full u64 input range; returns a
-    /// JS BigInt because the i64 wire range exceeds
-    /// `Number.MAX_SAFE_INTEGER`.
+    /// Accepts a JS BigInt in the unsigned wire range
+    /// (`0 ..= SEQUENCE_RANGE - 1`, i.e. `0 ..= 2^32 - 1`); returns a
+    /// JS BigInt for symmetry with `sequenceSignedToUnsigned`.
+    /// Negative inputs and inputs above the wire range throw — the
+    /// unsigned monotonic sequence id is always non-negative and
+    /// never wider than the i32 wire range.
     #[napi(js_name = "sequenceUnsignedToSigned")]
-    pub fn sequence_unsigned_to_signed(unsigned_value: BigInt) -> BigInt {
-        let (_, value, _) = unsigned_value.get_u64();
-        BigInt::from(tdbe::sequences::unsigned_to_signed(value))
+    pub fn sequence_unsigned_to_signed(unsigned_value: BigInt) -> napi::Result<BigInt> {
+        if unsigned_value.sign_bit && !unsigned_value.words.iter().all(|w| *w == 0) {
+            return Err(napi::Error::from_reason(
+                "sequenceUnsignedToSigned: negative BigInt rejected; the unsigned \
+                 monotonic sequence id is always non-negative",
+            ));
+        }
+        if unsigned_value.words.len() > 1 {
+            return Err(napi::Error::from_reason(
+                "sequenceUnsignedToSigned: BigInt above the wire range \
+                 (0 ..= 2^32 - 1)",
+            ));
+        }
+        let value = unsigned_value.words.first().copied().unwrap_or(0);
+        if value > u32::MAX as u64 {
+            return Err(napi::Error::from_reason(
+                "sequenceUnsignedToSigned: BigInt above the wire range \
+                 (0 ..= 2^32 - 1)",
+            ));
+        }
+        Ok(BigInt::from(tdbe::sequences::unsigned_to_signed(value)))
+    }
+}
+
+/// Decode a napi `BigInt` into the i32 wire range, accepting the
+/// asymmetric `i32::MIN` boundary. Returns `None` for any value
+/// outside `[i32::MIN, i32::MAX]`.
+fn bigint_to_i32(value: &BigInt) -> Option<i32> {
+    if value.words.len() > 1 {
+        return None;
+    }
+    let magnitude = value.words.first().copied().unwrap_or(0);
+    if value.sign_bit {
+        if magnitude == 0 {
+            Some(0)
+        } else if magnitude <= i32::MAX as u64 {
+            // SAFETY: `magnitude` fits in i32 here.
+            Some(-(magnitude as i32))
+        } else if magnitude == (i32::MAX as u64) + 1 {
+            Some(i32::MIN)
+        } else {
+            None
+        }
+    } else {
+        i32::try_from(magnitude).ok()
     }
 }