refactor: Wave 3 — typed SubscriptionTier + ArcSwap streaming state + layout moves + LOW batch (refs #500) (#507)

E. Typed `SubscriptionTier` enum
================================

`crates/thetadatadx/src/mdds/tier.rs` introduces a four-variant
`SubscriptionTier` enum (`Free`, `Value`, `Standard`, `Pro`) replacing
the prior `Option<i32>` representation of the `stock_tier` and
`options_tier` fields on `MddsClient`. The discriminant mirrors the
wire byte; `from_wire(i32)` decodes (returning `None` for unknown
values rather than silently coercing); `max_concurrent_requests`
codifies the `2^tier` semaphore semantics. Re-exported as
`thetadatadx::SubscriptionTier`. The wire-side `auth::nexus::AuthUser`
keeps its raw `Option<i32>` fields so deserialization stays
infallible for unknown future tiers; the typed enum is the post-
decode in-memory shape callers see. Unit tests cover the
round-trip, the unknown-value rejection, and the powers-of-two
semaphore math (1, 2, 4, 8).

F. `ArcSwap<StreamingSlot>` state machine
=========================================

The streaming side of `ThetaDataDx` collapses to a single
`ArcSwap<StreamingSlot>` cell walking
`Idle -> Live -> Stopped -> Live -> Stopped`. The previous trio of
coordinated fields — `Mutex<Option<FpssClient>>`,
`Mutex<Option<StreamingDispatcher>>`, `AtomicBool was_streaming` —
went away. Read paths (`is_streaming`, `connection_status`,
`with_streaming`, every per-subscription forwarder) collapse to one
atomic load on the slot and a borrow of the contained
`Arc<FpssClient>`. Lifecycle paths retain serial semantics through
an rcu-CAS install and an atomic swap-to-`Stopped`, with the previous
`Live` payload (if any) running the FPSS-then-dispatcher shutdown
sequence. The `dispatcher` field sits in a `Mutex<Option<...>>`
inside `Live` because `StreamingDispatcher::shutdown` consumes by
value; the lock is hit only by `stop_streaming` and
`dropped_event_count`, never by hot-path readers. Adds `arc-swap`
1.7 to the runtime dependencies. A state-machine walk through
`Idle -> Live -> Stopped -> Live -> Stopped` and a CAS-race test
covering the rejected double-install live alongside the existing
`reconnect_streaming` regression tests. The `Drop` contract is
documented in place: stop_streaming is idempotent because only a
`Live` slot triggers the shutdown sequence.

G. Layout moves
===============

Top-level mdds-specific modules move under `mdds/`:

  endpoint.rs       -> mdds/endpoint_args.rs (rename clarifies args-only)
  macros.rs         -> mdds/macros.rs
  registry.rs       -> mdds/registry.rs
  validate.rs       merged into mdds/validate.rs
  wire_semantics.rs -> mdds/wire_semantics.rs

`mdds/validate.rs` now hosts the canonical two-arg validators
(date / expiration / strike / symbol / interval / right / year)
plus a `validate_date_required` single-arg adapter the
`parsed_endpoint!` macro expansion needs. The macro switches to the
fully-qualified `$crate::mdds::validate::validate_date_required`
path so it expands cleanly from generated endpoint bodies; the
generator emit (`build_support/endpoints/render/mdds.rs`) follows.

`unified.rs` is renamed to `client.rs` so the filename matches the
primary type (`ThetaDataDx`). The frames module folds into a
directory: `frames.rs` + `frames_generated.rs` -> `frames/mod.rs` +
`frames/generated.rs`. The build-time generator paths
(`build_support/ticks/mod.rs`, `build_support/ticks/rust_frames.rs`)
follow.

The `tdbe::types::*_generated.rs` trio segregates under
`tdbe::types::generated/`: `enums_endpoint.rs`, `tick.rs`,
`tick_layout_asserts.rs`, with a `mod.rs` documenting the
directory. The hand-written siblings keep their `include!` sites
(now `include!("generated/...rs")`); `mod generated;` is declared
privately in `types/mod.rs`. The build-time generator paths
(`build_support/endpoints/render/sdk_files.rs`,
`build_support/ticks/tdbe_structs.rs`,
`build_support/ticks/mod.rs`) follow.

Re-exports in `lib.rs` keep the public surface stable:

  pub use mdds::endpoint_args as endpoint;
  pub use mdds::registry::{by_category, find, ..., EndpointMeta, ENDPOINTS, ...};
  pub use client::{ConnectionStatus, SubscriptionInfo, ThetaDataDx};

`thetadatadx::endpoint::*` and `thetadatadx::ENDPOINTS` /
`EndpointMeta` continue to resolve.

Build-script `[path = ...]` mounts (`build_support/mod.rs`,
`crates/thetadatadx/src/bin/generate_sdk_surfaces.rs`) follow the
file moves. `git mv` was used everywhere file blame is meaningful so
history follows the rename.

H. LOW batch
============

* 3.1 (`mdds.connect_timeout_secs`) — already shipped in Wave 2.
* 3.2 (`extract_*_column` return type) — kept as `Vec<Option<T>>`.
  The three helpers are public surface, exercised by benches,
  integration tests, the macro-driven list endpoints, and the
  Polars / Arrow column projections. Switching to
  `impl Iterator<Item = Option<T>>` would force every caller
  (including generated FFI bindings) to deal with the iterator
  shape and would lose the "missing-header -> empty result" early
  return the warn-log path relies on. The Vec allocation is one
  per column per call, never on a per-tick path.
* 3.5 (`FpssConnectArgs` struct) — deferred to Wave 4 B4 as a
  breaking signature change. Not landed here.
* 3.9 (`Drop::drop` idempotency on `ThetaDataDx`) — addressed in F.
  The state machine guarantees `stop_streaming` runs the FPSS /
  dispatcher shutdown at most once; `Drop::drop`'s doc comment now
  records the contract in-place.
* 3.10 (`#[allow(dead_code)]` on `flatfiles::framing::msg`) —
  removed. Every one of the ten `u16` wire-code constants is
  genuinely used by `flatfiles::request` and `flatfiles::session`.
  The attribute was a false positive; clippy stays green.

Version bump: 8.0.36 -> 8.0.37 across every crate manifest,
`sdks/typescript/package.json` (+ optionalDependencies, + the three
per-platform `npm/<platform>/package.json` files), Cargo.lock, and
the matching CHANGELOG entry mirrored to `docs-site/docs/changelog.md`.

Author: userFRM

CHANGELOG.md

@@ -5,6 +5,64 @@ 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.37] - 2026-05-07
+
+### Added
+
+- **Typed `SubscriptionTier` enum** (`Free`, `Value`, `Standard`, `Pro`)
+  replacing raw `Option<i32>` on `MddsClient`.
+  `max_concurrent_requests(self)` codifies the `2^tier` semaphore
+  semantics; `from_wire(i32)` decodes the wire byte (returning `None`
+  for unknown values rather than silently coercing). Re-exported as
+  `thetadatadx::SubscriptionTier`. The wire-side `auth::nexus::AuthUser`
+  keeps its raw `Option<i32>` fields so deserialization stays
+  infallible for unknown future tiers; the typed enum is the
+  post-decode in-memory shape callers see.
+
+### Changed
+
+- **Streaming state machine collapsed into a single `ArcSwap<StreamingSlot>`.**
+  `ThetaDataDx`'s prior 3-field state (`Mutex<Option<FpssClient>>`,
+  `Mutex<Option<StreamingDispatcher>>`, `AtomicBool was_streaming`) is
+  now one `ArcSwap` of an `Idle` / `Live` / `Stopped` enum. Read paths
+  (`is_streaming`, `connection_status`, `with_streaming`, every
+  per-subscription forwarder) collapse to one atomic load. Lifecycle
+  paths retain serial semantics through an rcu-CAS install and an
+  atomic swap-to-`Stopped`. Adds `arc-swap` 1.7 to runtime deps.
+- **Layout moves:**
+  - Top-level mdds-specific modules relocated under `mdds/`
+    (`endpoint.rs` → `mdds/endpoint_args.rs`, `macros.rs` →
+    `mdds/macros.rs`, `registry.rs` → `mdds/registry.rs`,
+    `validate.rs` merged into `mdds/validate.rs`,
+    `wire_semantics.rs` → `mdds/wire_semantics.rs`). Re-exports
+    preserved at crate root for back-compat
+    (`thetadatadx::endpoint::*`, `thetadatadx::EndpointMeta`,
+    `thetadatadx::ENDPOINTS`).
+  - `unified.rs` → `client.rs` (filename = primary type name).
+  - `frames.rs` + `frames_generated.rs` → `frames/{mod,generated}.rs`.
+  - `tdbe::types::*_generated.rs` segregated under
+    `tdbe::types::generated/`.
+
+### Fixed
+
+- (LOW 3.2) `extract_*_column` return type left as `Vec<Option<T>>` —
+  iterator conversion deferred. The three helpers are public surface
+  exercised by benches, integration tests, the macro-driven list
+  endpoints, and the Polars / Arrow column projections; switching to
+  `impl Iterator<Item = Option<T>>` would force every caller to deal
+  with the iterator shape and lose the missing-header early-return the
+  warn-log path relies on.
+- (LOW 3.9) `Drop::drop` on `ThetaDataDx` documents its idempotency
+  invariant. The `Idle` / `Live` / `Stopped` state machine guarantees
+  the FPSS / dispatcher shutdown sequence runs at most once across
+  `stop_streaming` + `Drop`.
+- (LOW 3.10) `#[allow(dead_code)]` removed from
+  `flatfiles/framing.rs::msg`. Every one of the ten `u16` wire-code
+  constants is genuinely used by `flatfiles::request` and
+  `flatfiles::session`; the attribute was a false positive.
+
+  Refs #500.
+
 ## [8.0.36] - 2026-05-07
 
 ### Changed

Cargo.lock

@@ -473,4 +473,4 @@ pub enum RemoveReason {
     InvalidCredentialsNullUser = 18,
 }
 
-include!("enums_endpoint_generated.rs");
+include!("generated/enums_endpoint.rs");

crates/tdbe/src/types/enums.rs

@@ -0,0 +1,27 @@
+//! Generator-emitted modules.
+//!
+//! Wave 3 segregated the three `*_generated.rs` files that previously
+//! sat next to their hand-written counterparts (`enums.rs`, `tick.rs`)
+//! into this subdirectory so the on-disk separation between
+//! human-authored and code-generator output is unambiguous.
+//!
+//! All three are `include!`-ed into a hand-written sibling so the
+//! feature gates, hand-written `impl` blocks, and rustdoc above each
+//! `include!` site keep their place. This `mod.rs` exists as the
+//! re-export hub the file paths point to; nothing here is imported
+//! directly from outside `crates/tdbe`.
+//!
+//! Files:
+//!
+//! - [`enums_endpoint`] — `Endpoint` / `EndpointMeta` enum bodies, included
+//!   from `super::enums`.
+//! - [`tick`] — `#[repr(C, align(N))]` tick struct definitions, included
+//!   from `super::tick`.
+//! - [`tick_layout_asserts`] — compile-time layout asserts pinned against
+//!   the schema-derived figures the C / Go FFI mirrors and
+//!   `tick_layout_asserts.hpp.inc` rely on, included from `super::tick`.
+
+// The `*.rs` files are reached via `include!("generated/<name>.rs")`
+// from the hand-written modules above, so no `mod` declarations are
+// emitted here. This mod.rs is the re-export hub the spec calls for and
+// documents the segregation.

…be/src/types/enums_endpoint_generated.rs …be/src/types/generated/enums_endpoint.rscrates/tdbe/src/types/enums_endpoint_generated.rs renamed to crates/tdbe/src/types/generated/enums_endpoint.rs crates/tdbe/src/types/enums_endpoint_generated.rs renamed to crates/tdbe/src/types/generated/enums_endpoint.rs

@@ -2,6 +2,13 @@ pub mod enums;
 pub mod price;
 pub mod tick;
 
+// Generator-emitted modules live in `generated/`. The submodule
+// itself is empty (a doc hub) — the actual files are reached via
+// `include!("generated/<name>.rs")` from the hand-written
+// `enums.rs` / `tick.rs` siblings, so the feature gates and
+// hand-written `impl` blocks keep their place above each include site.
+mod generated;
+
 pub use enums::*;
 pub use price::Price;
 pub use tick::*;

crates/tdbe/src/types/generated/mod.rs

@@ -14,7 +14,7 @@
 //! `crates/thetadatadx/tick_schema.toml` by
 //! `cargo run -p thetadatadx --bin generate_sdk_surfaces`.
 
-include!("tick_generated.rs");
+include!("generated/tick.rs");
 
 pub use crate::right::ParsedRight;
 
@@ -118,4 +118,4 @@ impl OptionContract {
 //  `cargo test -p tdbe` before it lands on the FFI side.
 // ─────────────────────────────────────────────────────────────────────────────
 
-include!("tick_layout_asserts_generated.rs");
+include!("generated/tick_layout_asserts.rs");

crates/tdbe/src/types/tick_generated.rs crates/tdbe/src/types/generated/tick.rscrates/tdbe/src/types/tick_generated.rs renamed to crates/tdbe/src/types/generated/tick.rs

@@ -1,6 +1,6 @@
 [package]
 name = "thetadatadx"
-version = "8.0.36"
+version = "8.0.37"
 edition.workspace = true
 rust-version.workspace = true
 authors.workspace = true
@@ -125,6 +125,14 @@ zeroize = { version = "1.8.2", features = ["derive"] }
 # cost benchmark.
 crossbeam-channel = "0.5.15"
 
+# Lock-free atomic swap of an `Arc<StreamingSlot>` for the streaming
+# state machine on `ThetaDataDx`. Replaces three coordinated fields
+# (`Mutex<Option<FpssClient>>`, `Mutex<Option<StreamingDispatcher>>`,
+# `AtomicBool was_streaming`) with a single atomic load on the read
+# path — `is_streaming`, `connection_status`, `dropped_event_count` and
+# the `with_streaming` helper all collapse to one `state.load()`.
+arc-swap = "1.7"
+
 [dev-dependencies]
 criterion = { version = "0.8.2", features = ["html_reports"] }
 # Test-only: load captured-response fixtures and their sidecar .meta.toml