feat(streaming)!: remove flush_mode; always coalesce outbound writes on the ping heartbeat (#1195)

* feat(streaming)!: remove flush_mode; always coalesce outbound writes on the ping heartbeat

flush_mode had no counterpart in the Theta Terminal: the terminal exposes no flush knob and lets the socket coalesce outbound writes, and the "immediate" mode existed only to defeat that coalescing — a client-facing way to flood the upstream with one syscall per frame. It was a server-protection mechanism turned into a footgun on the public configuration surface, so it does not belong on a terminal-parity SDK.

The knob is removed from every binding (Rust StreamingConfig::flush_mode, Python Config.flush_mode, TypeScript Config.flushMode / setFlushMode, C++ set_flush_mode / get_flush_mode, C ABI thetadatadx_config_set_flush_mode / _get_flush_mode), along with the StreamingFlushMode enum, the config-file field, the cross-binding parity rows, and the docs. The I/O loop now hardwires the batched behavior: only the ping heartbeat flushes, so queued subscribe / unsubscribe frames coalesce until the next ping and a subscription burst leaves as fewer, larger packets. Received-data latency is unaffected, exactly as before.

Breaking change to the configuration surface; batching is now unconditional.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* test,docs: drop stale flushMode TS test + sync docs changelog

Remove the leftover thetadatadx-ts __tests__/flush_mode.test.mjs that still asserted the removed cfg.flushMode / setFlushMode surface (npm test globs every __tests__/*.test.mjs), and mirror the CHANGELOG Removed entry into the docs-site changelog so the byte-identical docs-consistency gate passes.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* test(parity): drop flush_mode from the setter-property selftest fixture

The .pyi setter-property degrade selftest read the real parity.toml + stub and used flush_mode as its canonical exempt-setter example; with flush_mode gone, remove setFlushMode from PYI_SETTER_PROPERTY_ROWS and the twin table and drop the flush_mode-specific getter assertion so --selftest reflects the real surface.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs: regenerate llms.txt after flush_mode removal

generate_docs_site emits docs-site/docs/public/llms.txt from the config surface; refresh it so the generated-docs drift check passes with flush_mode gone.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: preview <noreply@anthropic.com>

Author: userFRM

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Removed
+
+- **`flush_mode` streaming write-flush knob.** The `flush_mode` setting is removed from every binding (Rust `StreamingConfig::flush_mode`, Python `Config.flush_mode`, TypeScript `Config.flushMode` / `setFlushMode`, C++ `set_flush_mode` / `get_flush_mode`, C ABI `thetadatadx_config_set_flush_mode` / `_get_flush_mode`). Outbound streaming writes now always coalesce and flush on the ping heartbeat, so a subscription burst leaves as fewer, larger packets — the terminal's own behavior — with received-data latency unaffected as before. The `"immediate"` per-frame-flush mode existed only to defeat that server-friendly coalescing and is gone. This is a breaking change to the configuration surface.
+
 ## [0.1.1] - 2026-07-07
 
 ### Added

docs-site/docs/articles/configuration.md

@@ -37,7 +37,6 @@ from thetadatadx import Config
 
 cfg = Config.production()
 cfg.retry_max_attempts = 5
-cfg.flush_mode = "immediate"
 client = Client(creds, cfg)
 ```
 
@@ -86,7 +85,7 @@ You can also select environments inline at the client, without building a `Confi
 
 If you also set an explicit streaming or market-data host (through `THETADATA_MARKET_DATA_HOST` / `THETADATA_STREAMING_HOST`, in the environment, in the `.env` file, or in the config file), that explicit host wins over the environment's default for that channel.
 
-In Rust the same fields live on `DirectConfig` struct sub-configs (`config.retry.max_attempts`, `config.streaming.flush_mode`); TypeScript uses `Config` setters (`cfg.setRetryMaxAttempts(5)`); C++ uses `thetadatadx::Config::set_retry_max_attempts(5)`.
+In Rust the same fields live on `DirectConfig` struct sub-configs (`config.retry.max_attempts`, `config.streaming.ring_size`); TypeScript uses `Config` setters (`cfg.setRetryMaxAttempts(5)`); C++ uses `thetadatadx::Config::set_retry_max_attempts(5)`.
 
 ## The knobs that matter
 
@@ -95,7 +94,7 @@ In Rust the same fields live on `DirectConfig` struct sub-configs (`config.retry
 | Request deadlines | `timeout_ms` per request (builder / kwarg) | Hard per-call deadline; expiry raises a timeout error and frees the slot. |
 | Retries | `retry_initial_delay_ms`, `retry_max_delay_ms`, `retry_max_attempts`, `retry_jitter`, `retry_max_elapsed_secs` | Backoff schedule for transient market-data-request faults. |
 | Streaming reconnect | `reconnect_policy`, `reconnect_max_attempts`, `reconnect_wait_ms`, `reconnect_wait_max_ms`, `reconnect_jitter`, `reconnect_stable_window_secs`, … | Automatic streaming reconnection. See [Reconnection & Monitoring](/streaming/reliability). |
-| Streaming latency | `flush_mode` (`"batched"` default / `"immediate"`), `streaming_ring_size`, `streaming_timeout_ms`, keepalive fields | Write-path flush behavior and event-buffer capacity. |
+| Streaming latency | `streaming_ring_size`, `streaming_timeout_ms`, keepalive fields | Event-buffer capacity and I/O timeouts. |
 | Flat files | `flatfiles_max_attempts`, `flatfiles_initial_backoff_secs`, `flatfiles_max_backoff_secs`, `flatfiles_jitter` | Retry budget for bulk downloads. |
 | Observability | `metrics_port` | Optional local Prometheus exporter port (off by default). |
 | Runtime | `worker_threads` | Async worker-thread count for embedded bindings (0 = auto). |
@@ -114,7 +113,6 @@ host = "mdds-01.thetadata.us"
 port = 443
 
 [streaming]
-flush_mode = "immediate"
 hosts = ["host-a.example.com:20000", "host-b.example.com:20000"]
 ```
 

docs-site/docs/changelog.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Removed
+
+- **`flush_mode` streaming write-flush knob.** The `flush_mode` setting is removed from every binding (Rust `StreamingConfig::flush_mode`, Python `Config.flush_mode`, TypeScript `Config.flushMode` / `setFlushMode`, C++ `set_flush_mode` / `get_flush_mode`, C ABI `thetadatadx_config_set_flush_mode` / `_get_flush_mode`). Outbound streaming writes now always coalesce and flush on the ping heartbeat, so a subscription burst leaves as fewer, larger packets — the terminal's own behavior — with received-data latency unaffected as before. The `"immediate"` per-frame-flush mode existed only to defeat that server-friendly coalescing and is gone. This is a breaking change to the configuration surface.
+
 ## [0.1.1] - 2026-07-07
 
 ### Added

docs-site/docs/public/llms.txt

@@ -94,7 +94,7 @@
 /streaming/options/open-interest — Option Open Interest: Open-interest updates for an option contract.
 /streaming/options/quote — Option Quotes: Real-time NBBO quote stream for an option contract.
 /streaming/options/trade — Option Trades: Real-time trade stream for an option contract.
-/streaming/reliability — Reconnection & Monitoring: Automatic reconnect policy, flush mode, and the counters that tell you a stream is healthy.
+/streaming/reliability — Reconnection & Monitoring: Automatic reconnect policy and the counters that tell you a stream is healthy.
 /streaming/stocks/full-trade — Stock Full Trades: Every trade across all stocks in one subscription.
 /streaming/stocks/market-value — Stock Market Value: Real-time calculated market value for a stock.
 /streaming/stocks/quote — Stock Quotes: Real-time BBO quote stream for a stock.

docs-site/docs/streaming/reliability.md

@@ -1,6 +1,6 @@
 ---
 title: Reconnection & Monitoring
-description: Automatic reconnect policy, flush mode, and the counters that tell you a stream is healthy.
+description: Automatic reconnect policy and the counters that tell you a stream is healthy.
 ---
 
 # Reconnection & Monitoring
@@ -46,20 +46,6 @@ Permanent failures (for example rejected credentials) never reach the callback 
 
 Caller-driven recovery is always available: `reconnect()` re-opens the session and restores the saved subscription set on demand.
 
-## Flush mode
-
-`flush_mode` trades write-path latency against syscall volume:
-
-| Mode | Behavior |
-|---|---|
-| `"batched"` (default) | Outbound frames flush on the heartbeat cadence — the throughput-friendly default. |
-| `"immediate"` | Every frame flushes as written — lowest latency. |
-
-```python
-cfg = Config.production()
-cfg.flush_mode = "immediate"
-```
-
 ## Monitoring a live stream
 
 Incoming events are buffered between the connection and your callback. If your callback can't keep up, the buffer fills and the newest events are **counted and dropped** rather than stalling the feed — so these counters are the health dashboard:

parity.toml

@@ -671,17 +671,6 @@ python = true
 typescript = true
 cpp = true
 
-# `StreamingConfig.flush_mode` is exposed on every binding:
-# C ABI (`thetadatadx_config_set_flush_mode`), C++ (`set_flush_mode`),
-# Python (`Config.flush_mode` getter + setter accepting
-# `"batched"` / `"immediate"`), TypeScript (`Config.flushMode`
-# getter + `setFlushMode` accepting the same strings).
-[[class]]
-name = "StreamingConfig.flush_mode"
-python = true
-typescript = true
-cpp = true
-
 # `StreamingConfig.consumer_cpu` optional consumer-thread CPU pin,
 # exposed on every binding (Python `Config.consumer_cpu` `Optional[int]`,
 # TypeScript `consumerCpu` / `setConsumerCpu` `number | null`, C++
@@ -1903,34 +1892,6 @@ cpp = true
 params = ["String"]
 returns = "Config"
 
-# The flush-mode knob diverges on C++: the managed bindings pass / return the
-# mode as a String name, while C++ uses the integer enum code (`int`), so those
-# cells are per-lang overrides.
-[[method]]
-class = "Config"
-name = "setFlushMode"
-python = true
-typescript = true
-cpp = true
-[method.signature]
-params = ["String"]
-returns = "()"
-cpp_params = ["i32"]
-
-[[method]]
-class = "Config"
-name = "flushMode"
-python = true
-typescript = true
-cpp = true
-[method.signature]
-returns = "String"
-cpp_returns = "i32"
-# The Python stub constrains the knob to its exact value set; pin the Literal
-# so adding / removing / renaming a member fails (the bare `String` would hide
-# the value-set drift). The pyo3-source `python` lane still reads `&str`.
-python_pyi_returns = 'Literal["batched", "immediate"]'
-
 # The consumer-CPU pin is an optional core index. The managed bindings carry
 # it as an optional integer (`Option<usize>` / `Option<f64>` / `Option<u32>`);
 # C++ sentinel-encodes the option as a bare `int64_t` (-1 = unpinned), so the

scripts/ci/check_binding_parity.py

@@ -2444,7 +2444,6 @@ def _collect_cpp_class_methods(cpp_hpp: pathlib.Path) -> dict[str, set[str]]:
 PYI_SETTER_PROPERTY_ROWS: frozenset[tuple[str, str]] = frozenset(
     ("Config", name)
     for name in (
-        "setFlushMode",
         "setConsumerCpu",
         "setReconnectPolicy",
         "setStreamingRingSize",
@@ -12820,7 +12819,7 @@ def _case_sig_python_pyi_setter_property_degrade() -> None:
         `.pyi` lane does NOT fail on the (correctly) absent `set_x`, while the
         matching GETTER row IS `.pyi`-checked. Uses the live stub so the real
         property annotation is exercised."""
-        # The 9 enrolled setters are the only pinned-python rows absent from the
+        # The enrolled setters are the only pinned-python rows absent from the
         # real stub — assert that membership matches reality (a NEW absent
         # pinned setter must be enrolled or it fails).
         data = tomllib.loads(PARITY_TOML.read_text(encoding="utf-8"))
@@ -12833,18 +12832,13 @@ def _case_sig_python_pyi_setter_property_degrade() -> None:
         # The setter rows still get their pyo3-source `python` / ts / cpp / ffi
         # checks; only the `.pyi` lane is exempt. So no `python_pyi` error.
         assert not any("python_pyi" in e for e in setter_errs), setter_errs
-        # The matching getter (`flushMode` → property `flush_mode`) IS checked.
-        assert _sig_extract_python_pyi(PY_PYI, "Config", "flush_mode") == (
-            [], 'Literal["batched", "immediate"]'
-        ), _sig_extract_python_pyi(PY_PYI, "Config", "flush_mode")
         # FINDING-8 closure: the exemption is sound ONLY if EVERY exempt setter
         # has a getter twin whose `.pyi` property type the `python_pyi` lane
         # checks. Resolve each setter's twin from the real spec and assert (a) a
         # checked getter `[[method]]` row exists for it and (b) the stub declares
         # the property — so no exempt setter rides on an unchecked property.
         # `setStreamingRingSize` → `streamingRingSize` was the gap this closes.
         setter_to_getter = {
-            "setFlushMode": ("flushMode", "flush_mode"),
             "setConsumerCpu": ("consumerCpu", "consumer_cpu"),
             "setReconnectPolicy": ("reconnectPolicy", "reconnect_policy"),
             "setStreamingRingSize": ("streamingRingSize", "streaming_ring_size"),

thetadatadx-cpp/include/config_accessors.hpp.inc

@@ -1925,26 +1925,6 @@ int32_t thetadatadx_config_set_metrics_port(ThetaDataDxConfig* config, bool has_
  */
 int32_t thetadatadx_config_get_metrics_port(const ThetaDataDxConfig* config, bool* out_has_value, uint16_t* out_port);
 
-/**
- * Set streaming flush mode on a config handle.
- *   mode=0: Batched (default) -- flush only on PING every 100ms.
- *   mode=1: Immediate -- flush after every frame write.
- * @param config Config handle to mutate.
- * @param mode Flush mode selector (0 = Batched, 1 = Immediate).
- * @return 0 on success. -1 with thetadatadx_last_error set and thetadatadx_last_error_code =
- *         THETADATADX_ERR_CONFIG when mode is outside {0, 1} or config is null.
- */
-int thetadatadx_config_set_flush_mode(ThetaDataDxConfig* config, int mode);
-
-/**
- * Read the current streaming flush mode. Same encoding as
- * thetadatadx_config_set_flush_mode.
- * @param config Config handle to read.
- * @param out_mode Receives 0 (Batched) or 1 (Immediate) on success.
- * @return 0 on success, -1 if either pointer is null.
- */
-int32_t thetadatadx_config_get_flush_mode(const ThetaDataDxConfig* config, int32_t* out_mode);
-
 /**
  * Read the market-data environment carried by the config: "PROD"
  * for the production cluster or "STAGE" for staging. The market-data and

thetadatadx-cpp/include/thetadatadx.h

@@ -208,10 +208,6 @@ TEST_CASE("config enum setters reject an out-of-domain value with InvalidParamet
     // throw.
     auto cfg = thetadatadx::Config::production();
 
-    REQUIRE_NOTHROW(cfg.set_flush_mode(1));
-    REQUIRE_THROWS_AS(cfg.set_flush_mode(9), thetadatadx::InvalidParameterError);
-    REQUIRE_THROWS_AS(cfg.set_flush_mode(9), thetadatadx::ThetaDataError);
-
     REQUIRE_NOTHROW(cfg.set_reconnect_jitter(2));
     REQUIRE_THROWS_AS(cfg.set_reconnect_jitter(9), thetadatadx::InvalidParameterError);