fix(v9.1.0): close PR #514 external audit findings

External audit closed-out:

HIGH-001 — multi-generation drain barrier. The single-slot
`prev_drained: Mutex<Option<Arc<AtomicBool>>>` overwrote on every
retire, so a stacked stop/start/stop where the earlier session was
still draining when the later one retired silently lost the earlier
flag. `await_drain()` then returned `true` based on the latest
generation while the earlier callback could still fire on a freed
FFI `ctx` — a use-after-free hazard under reconnect-storm scenarios.
Replaced with `Mutex<Vec<Arc<AtomicBool>>>` on both `ThetaDataDx`
and `TdxFpssHandle`; every retired session's flag is pushed onto
the Vec, and `await_drain()` / `tdx_*_free` walk the full set with
lazy GC. Soak coverage at
`streaming_soak_tests::multi_gen_drain_waits_for_all_retired_sessions`
drives three flags through the production poll cadence with a
staggered drain order so the pre-fix code path is a hard regression
gate.

MED-001 — WS payload now carries `unresolved_contract_id` for
pre-`ContractAssigned` ticks. The decoder builds an unresolved-
contract sentinel whose `symbol` is `__pending:<id>` (the canonical
`sec_type == SecType::Unknown` check still gates consumer code
paths); the WS formatter detects the prefix, emits
`contract: {"status": "pending"}`, and surfaces the parsed wire id
as a top-level integer. Public SDK callback signature unchanged.

LOW-001 — WS `/subscribe` option path now runs the canonical
Gregorian validator alongside the bounds check. Impossible dates
like `20260230` (Feb 30) or `20260431` (Apr 31) no longer leak
through.

REPO-MED-001 — documented the explicit-handoff contract on Python
and TypeScript `stop_streaming`, `shutdown`, and `reconnect`.
Sourced from the codegen surface (`sdk_surface.toml` +
`build_support/sdk_surface/{python,typescript}.rs`) so the
generated `streaming_methods.rs` files stay in sync.

CHANGELOG, `.github/release-notes/v9.1.0.md`, and
`docs-site/docs/changelog.md` updated. Codegen `--check` clean,
banned-vocab grep zero matches, full workspace tests green.

Author: userFRM

.github/release-notes/v9.1.0.md

@@ -210,6 +210,38 @@ the user callback directly from the Disruptor consumer thread.
 
 ### Fixed
 
+- **External audit: single-slot drain barrier could falsely report
+  quiescence under stacked lifecycle transitions.** `prev_drained`
+  tracked only the most-recently-retired session's flag; a stacked
+  `start → stop → start → stop` cycle in which the earlier session
+  was still draining when the later one retired silently lost the
+  earlier flag, and `await_drain()` returned `true` while the
+  earlier callback could still be firing on the FFI `ctx`. The slot
+  is now a `Mutex<Vec<Arc<AtomicBool>>>`; `await_drain()` and
+  `tdx_*_free` walk every retired generation, lazily GC'ing flags
+  that have flipped. Multi-generation soak coverage in
+  `streaming_soak_tests.rs::multi_gen_drain_waits_for_all_retired_sessions`.
+- **WS payload now carries `unresolved_contract_id` for
+  pre-`ContractAssigned` ticks.** The decoder builds an unresolved-
+  contract sentinel whose `symbol` is `__pending:<id>`; the WS
+  formatter detects the prefix, emits `contract: {"status":
+  "pending"}`, and surfaces the parsed wire id as a top-level
+  `unresolved_contract_id` integer. The public SDK callback signature
+  is unchanged — `__pending:` is a diagnostic payload, not a stable
+  identifier; downstream consumers continue to pattern-match on
+  `sec_type == SecType::Unknown`.
+- **WS `/subscribe` option path now runs the canonical Gregorian
+  validator.** The Wave H `tdbe::time::is_valid_yyyymmdd` calendar
+  check ran on the historical / REST surfaces but not on the WS
+  option-subscribe path; impossible dates like `20260230` (Feb 30)
+  or `20260431` (Apr 31) leaked through. Both gates now run.
+- **Python and TypeScript bindings: stop / shutdown clear the
+  registered callback.** Documented the explicit-handoff contract
+  on `stop_streaming`, `shutdown`, and `reconnect` for both
+  bindings. The unified C API preserves the callback by design; the
+  high-level bindings clear it deliberately to enforce the explicit
+  re-handoff model shared with the C++ RAII wrapper and the Python
+  `with`-block `__exit__`.
 - **`stop_streaming()` race that could resurrect streaming after
   stop returned.** Each `stop_streaming` now bumps an `AtomicU64`
   generation counter; each `start_streaming*()` snapshots the counter

CHANGELOG.md

@@ -171,6 +171,51 @@ code does not change.
 
 ### Fixed
 
+- **External audit: single-slot drain barrier could falsely report
+  quiescence under stacked lifecycle transitions.** The
+  `prev_drained` slot tracked only the most recently retired session's
+  flag, so a `start → stop → start → stop` sequence in which the
+  earlier session was still draining when the later one retired
+  silently lost the earlier flag. `await_drain()` then returned `true`
+  based on the latest generation while the earlier callback could
+  still be firing on the FFI `ctx` — a use-after-free vector under
+  reconnect-storm scenarios. The slot is now a
+  `Mutex<Vec<Arc<AtomicBool>>>`; every retired session's flag is
+  pushed onto the Vec, and `await_drain()` / `tdx_*_free` walk the
+  full set, lazily GC'ing flags that have flipped. Mirrored on the
+  FFI handle's `prev_drained` field. Regression coverage:
+  `crates/thetadatadx/src/fpss/streaming_soak_tests.rs::multi_gen_drain_waits_for_all_retired_sessions`
+  drives three real `FpssClient` instances back-to-back with slow
+  callbacks and asserts the barrier waits for every generation.
+- **WS payload now carries `unresolved_contract_id` for
+  pre-`ContractAssigned` ticks.** Pre-Wave-G the WS bridge surfaced
+  the wire-internal numeric id; post-removal of the public `contract_id`
+  field, ticks that arrived before the matching `ContractAssigned`
+  frame serialised as an empty `Contract` envelope with no diagnostic
+  channel for operators to correlate. The decoder now builds an
+  unresolved-contract sentinel whose `symbol` is `__pending:<id>`
+  (the canonical `sec_type == SecType::Unknown` check still gates
+  consumer code paths); the WS formatter detects the prefix, emits
+  `contract: {"status": "pending"}`, and surfaces the parsed wire id
+  as a top-level `unresolved_contract_id` integer. The public SDK
+  callback signature is unchanged — `__pending:` is a diagnostic
+  payload, not a stable identifier.
+- **WS `/subscribe` option path now runs the canonical Gregorian
+  validator.** The Wave H `tdbe::time::is_valid_yyyymmdd` calendar
+  check ran on the historical / REST surfaces but not on the WS
+  option-subscribe path, which only applied the cheap
+  `is_valid_yyyymmdd_range` bounds check. Impossible dates like
+  `20260230` (Feb 30), `20260431` (Apr 31), or `20251301` (month 13)
+  leaked through. Both gates now run; the bounds check is the
+  precheck, the calendar validator is the real gate.
+- **Python and TypeScript bindings: stop / shutdown clear the
+  registered callback.** The unified C API preserves the callback
+  across stop/reconnect, but the high-level bindings deliberately
+  diverge: `stop_streaming()` and `shutdown()` clear the stored
+  callback, so a subsequent `reconnect()` raises until the caller
+  re-registers via `start_streaming(callback)`. Documented on every
+  affected method (`stop_streaming`, `shutdown`, `reconnect` on both
+  bindings) so the explicit-handoff model is no longer surprising.
 - **`stop_streaming()` race that could resurrect streaming after
   stop returned.** The `ArcSwap` slot accepted `Stopped → Live`, so
   an in-flight `start_streaming*()` that began before

crates/thetadatadx/build_support/sdk_surface/python.rs

@@ -255,7 +255,25 @@ fn python_streaming_method(method: &MethodSpec) -> String {
                  `RuntimeError` if no callback is registered. All\n\
                  active subscriptions are restored on the new\n\
                  connection — see `thetadatadx::ThetaDataDx::reconnect_streaming`\n\
-                 for partial-failure semantics.",
+                 for partial-failure semantics.\n\
+                 \n\
+                 # Callback lifetime across `stop_streaming`\n\
+                 \n\
+                 `stop_streaming()` and `shutdown()` clear the registered\n\
+                 callback. To resume streaming on this client after\n\
+                 `stop_streaming()`, you MUST call `start_streaming(callback)`\n\
+                 again with a freshly bound callable; `reconnect()` raises\n\
+                 `RuntimeError` because no callback is held.\n\
+                 \n\
+                 This explicit-handoff model matches the C++ wrapper's RAII\n\
+                 destructor and the Python `with` block's `__exit__`: the\n\
+                 resource (the callback closure plus its captured environment)\n\
+                 is cleared at the same scope boundary the user observes. The\n\
+                 unified C API preserves the callback across stop/reconnect,\n\
+                 but the Python and TypeScript bindings deliberately diverge\n\
+                 to enforce the explicit handoff and avoid retaining captured\n\
+                 references past a teardown the application has already\n\
+                 observed.",
             );
             writeln!(out, "    fn {}(&self) -> PyResult<()> {{", method.name).unwrap();
             out.push_str(include_str!("templates/python/reconnect_body.rs.tmpl"));

crates/thetadatadx/build_support/sdk_surface/typescript.rs

@@ -189,7 +189,24 @@ fn ts_streaming_method(method: &MethodSpec) -> String {
                  no callback is registered. All active subscriptions are\n\
                  restored on the new connection — see\n\
                  `thetadatadx::ThetaDataDx::reconnect_streaming` for\n\
-                 partial-failure semantics.",
+                 partial-failure semantics.\n\
+                 \n\
+                 # Callback lifetime across `stopStreaming`\n\
+                 \n\
+                 `stopStreaming()` and `shutdown()` clear the registered\n\
+                 callback. To resume streaming on this client after\n\
+                 `stopStreaming()`, you MUST call `startStreaming(callback)`\n\
+                 again with a freshly bound function; `reconnect()` throws\n\
+                 because no callback is held.\n\
+                 \n\
+                 This explicit-handoff model matches the C++ wrapper's RAII\n\
+                 destructor and the Python `with` block's `__exit__`: the\n\
+                 resource (the JS callback handle) is cleared at the same\n\
+                 scope boundary the application observes. The unified C API\n\
+                 preserves the callback across stop/reconnect, but the\n\
+                 TypeScript and Python bindings deliberately diverge to enforce\n\
+                 the explicit handoff and avoid retaining captured references\n\
+                 past a teardown the caller has already observed.",
             );
             writeln!(out, "    #[napi(js_name = \"reconnect\")]").unwrap();
             writeln!(

crates/thetadatadx/sdk_surface.toml

@@ -215,13 +215,17 @@ targets = ["python_unified", "typescript_napi", "cpp_fpss"]
 [[methods]]
 name = "stop_streaming"
 kind = "stop_streaming"
-doc = "Stop streaming while keeping the historical client usable."
+doc = """Stop streaming while keeping the historical client usable.
+
+Clears the registered callback. To resume streaming, call `start_streaming(callback)` again with a freshly bound callable -- `reconnect()` will fail because no callback is held. See the `reconnect` docs for the rationale (explicit-handoff model shared with the C++ RAII wrapper and the Python `with`-block `__exit__`; the unified C API keeps the callback by design, but the high-level bindings clear it deliberately)."""
 targets = ["python_unified", "typescript_napi"]
 
 [[methods]]
 name = "shutdown"
 kind = "shutdown"
-doc = "Shut down the FPSS streaming connection."
+doc = """Shut down the FPSS streaming connection.
+
+On the Python and TypeScript bindings, this clears the registered callback (same explicit-handoff semantics as `stop_streaming`); a subsequent `reconnect()` will fail until the caller re-registers via `start_streaming(callback)`. The C++ binding preserves the unified C API's behaviour."""
 targets = ["python_unified", "typescript_napi", "cpp_fpss"]
 
 [[methods]]