check_binding_parity.py

#!/usr/bin/env python3
"""Cross-binding parity check (Gate 2 / issue #545 + #595).

Reads `sdks/parity.toml` — the declared cross-binding presence matrix
— and compares each row's `python` / `typescript` / `cpp` claims to
the actual binding state extracted from:

Class-level rows (no dot in `name`):
- Python: every `m.add_class::<T>()` registered in `lib.rs` + helper
  `register_*` calls, expanded statically by parsing the Rust source.
  Mirrors the regex powering `test_no_pyclass_name_collisions.py`.
- TypeScript: `export declare class X` / `export class X` declarations
  in `sdks/typescript/index.d.ts`.
- C++: `^class X` / `^struct X` declarations in
  `sdks/cpp/include/thetadatadx.hpp`. The `.h` header is C-only and not
  considered for parity.

Field-level rows (dotted `name`, e.g. `ReconnectConfig.wait_ms`):
- Python: `#[setter] fn set_<canonical>` and `#[getter] fn <canonical>`
  parsed from `sdks/python/src/*.rs`. The canonical name composes the
  struct prefix (e.g. `reconnect_`) with the row suffix (`wait_ms`).
- TypeScript napi: `#[napi(js_name = "set<CamelCase>")]` and the
  matching getter declaration in `sdks/typescript/src/*.rs`. The
  CamelCase form lifts the snake_case canonical name.
- C++: `set_<canonical>` / `get_<canonical>` member functions on the
  `class Config { ... }` body in `thetadatadx.hpp` PLUS the matching
  `thetadatadx_config_set_<canonical>` C-ABI declaration in `thetadatadx.h`.
- FFI: `thetadatadx_config_set_<canonical>` AND
  `thetadatadx_config_get_<canonical>` (or the `_explicit` widened-ABI shape)
  parsed from `ffi/src/*.rs`. Any binding flagged `true` on a field
  row implies the FFI symbol exists, because every higher-level
  binding forwards into the same C ABI.

Rust-only rows: a dotted row with `rust_only = true` MUST cite an
`issue = "#N"` tracking number. The script enforces both — a
`rust_only` flag with no issue or an `issue` flag with no `rust_only`
fails the gate.

Historical endpoint families (`[[historical_base]]` /
`[[historical_async]]` / `[[historical_streaming]]`): the buffered,
async-query, and server-stream surfaces per endpoint. Each carries a
`rust` column whose source of truth is the registry of record,
`crates/thetadatadx/endpoint_surface.toml` — the file the build pipeline
generates every binding's historical method from. The Rust buffered
surface is every `[[endpoints]]` entry except the four `*_stream` FPSS
subscription endpoints (61 endpoints); the Rust streaming subset mirrors
the build's `endpoint_streams` SSOT (list / snapshot / calendar endpoints
get no server-stream terminal). `[[historical_base]]` additionally pins
the C-ABI `thetadatadx_<endpoint>_with_options` base symbol read from the
SHIPPED header (`sdks/cpp/include/endpoint_with_options.h.inc`) and
cross-checks the shipped header, the `ffi/src` source, and the registry
for agreement so a stale regenerated header is caught. This is the core
"every endpoint exists on all five surfaces" guarantee.

Exits non-zero on any mismatch. Run from the repo root.

A `--selftest` switch runs an in-process synthetic-source matrix
covering positive (all-bound) and negative (missing-on-TS,
missing-on-C++, missing-on-FFI, undocumented-orphan, rust_only-
without-issue) cases. The selftest is registered with the
audit-protocol convention for CI gates.
"""

from __future__ import annotations

import pathlib
import re
import sys
import tempfile
import tomllib
from typing import Any


REPO_ROOT = pathlib.Path(__file__).resolve().parents[1]
PARITY_TOML = REPO_ROOT / "sdks" / "parity.toml"
PY_SRC = REPO_ROOT / "sdks" / "python" / "src"
TS_DTS = REPO_ROOT / "sdks" / "typescript" / "index.d.ts"
TS_SRC = REPO_ROOT / "sdks" / "typescript" / "src"
CPP_HPP = REPO_ROOT / "sdks" / "cpp" / "include" / "thetadatadx.hpp"
CPP_H = REPO_ROOT / "sdks" / "cpp" / "include" / "thetadatadx.h"
FFI_SRC = REPO_ROOT / "ffi" / "src"
CONFIG_DIR = REPO_ROOT / "crates" / "thetadatadx" / "src" / "config"
# Core Rust streaming surfaces whose public observability accessors must
# each carry a parity row. The unified surface lives on the
# `StreamSurface` view returned by `Client::stream()`; the standalone
# surface is the `StreamingClient` FPSS client.
CORE_CLIENT_RS = REPO_ROOT / "crates" / "thetadatadx" / "src" / "client.rs"
CORE_FPSS_MOD_RS = REPO_ROOT / "crates" / "thetadatadx" / "src" / "fpss" / "mod.rs"
# The canonical endpoint registry of record. The build pipeline generates
# the Rust historical surface (`HistoricalClient::<endpoint>` methods + the
# per-endpoint streaming builders) from this file; the parity gate reads it
# directly so a dropped or renamed Rust historical endpoint trips without a
# full build. Every `[[endpoints]]` entry not named `*_stream` (the four FPSS
# real-time subscription endpoints) is one of the buffered historical
# endpoints (the 61-endpoint base surface).
ENDPOINT_SURFACE_TOML = (
    REPO_ROOT / "crates" / "thetadatadx" / "endpoint_surface.toml"
)
# The shipped C-ABI base header fragment. `thetadatadx.h` includes it; it
# declares one `thetadatadx_<endpoint>_with_options` extern "C" symbol per
# buffered endpoint. Reading the SHIPPED header (not just the `ffi/src`
# source) catches a stale regenerated header that drifted from the Rust
# source of truth.
ENDPOINT_WITH_OPTIONS_INC = (
    REPO_ROOT / "sdks" / "cpp" / "include" / "endpoint_with_options.h.inc"
)


# ─── Public-surface vocabulary guard ────────────────────────────────
#
# OUR Rust implementation-detail names that must never appear inside a
# PUBLIC client identifier (class / method / field / setter / getter /
# exported type). The bindings legitimately USE the async runtime, the
# lock-free ring, and the lock primitives internally — those uses live
# in implementation code and are out of scope here. This guard fires
# only on the identifiers the parity collectors already harvest, i.e.
# the names a user types. It catches the leak class structurally (a
# banned token embedded in a snake_case / camelCase identifier) where a
# word-boundary (`\bword\b`) text rule cannot, without false-positives
# on internal code.
#
# ALLOW-LIST: `mdds` and `fpss` are ThetaData's PROPRIETARY PROTOCOL names (the
# vendor this SDK wraps). They are NOT impl-detail leaks; the public
# surface stays aligned with the vendor's vocabulary. They are NOT
# listed below and MUST NOT be flagged. Only OUR own implementation
# details (the async runtime, the disruptor-style ring, the lock
# primitives, the I/O-bridge calls) are leaks.
#
# Lowercased; matched as a substring against the lowercased identifier
# (so `Tokio`, `tokio`, `TOKIO`, and an embedded `_tokio_` all hit).
BANNED_SURFACE_TOKENS: tuple[str, ...] = (
    "tokio",
    "disruptor",
    "crossbeam",
    "parking_lot",
    "parkinglot",
    "block_on",
    "blockon",
    "allow_threads",
    "allowthreads",
    "os_pipe",
    "ospipe",
)


def _surface_token_hit(identifier: str) -> str | None:
    """Return the banned implementation-detail token embedded in
    `identifier`, or ``None`` if the identifier is clean.

    The match is case-insensitive and substring-based so a token buried
    inside a snake_case or camelCase name (`set_tokio_worker_threads`,
    `TokioWorkerThreadsSetting`) is caught — exactly the blind spot in a
    word-boundary text rule. Vendor protocol names
    (`mdds`, `fpss`) are intentionally absent from the token list, so a
    `mdds_client` / `fpss` engine stem is never flagged.
    """
    lowered = identifier.lower()
    for token in BANNED_SURFACE_TOKENS:
        if token in lowered:
            return token
    return None


# ─── Class-level discovery (legacy / non-dotted rows) ───────────────


PYCLASS_RE = re.compile(
    r"#\[pyclass(?:\(([^)]*)\))?\][^{]*?"
    r"(?:pub(?:\(crate\))?\s+)?(?:struct|enum)\s+(\w+)",
    re.MULTILINE | re.DOTALL,
)
NAME_ATTR_RE = re.compile(r'name\s*=\s*"([^"]+)"')


def _python_name(attrs: str | None, struct_name: str) -> str:
    if attrs:
        m = NAME_ATTR_RE.search(attrs)
        if m:
            return m.group(1)
    return struct_name.removeprefix("Py")


def collect_python_classes(py_src: pathlib.Path) -> set[str]:
    """Python-side pyclasses, in the same way `m.add_class::<T>()`
    would surface them."""
    out: set[str] = set()
    for rs in py_src.rglob("*.rs"):
        text = rs.read_text(encoding="utf-8")
        for m in PYCLASS_RE.finditer(text):
            out.add(_python_name(m.group(1), m.group(2)))
    errors_rs = py_src / "errors.rs"
    if errors_rs.is_file():
        for m in re.finditer(r'm\.add\(\s*"(\w+)"\s*,', errors_rs.read_text(encoding="utf-8")):
            out.add(m.group(1))
    return out


TS_CLASS_RE = re.compile(r"export\s+declare\s+class\s+(\w+)")
TS_INTERFACE_RE = re.compile(r"export\s+(?:declare\s+)?interface\s+(\w+)")


def collect_typescript_classes(ts_dts: pathlib.Path) -> set[str]:
    out: set[str] = set()
    if not ts_dts.is_file():
        return out
    text = ts_dts.read_text(encoding="utf-8")
    for m in TS_CLASS_RE.finditer(text):
        out.add(m.group(1))
    for m in TS_INTERFACE_RE.finditer(text):
        out.add(m.group(1))
    js_path = ts_dts.with_name("index.js")
    if js_path.is_file():
        for m in re.finditer(r"exports\.(\w+)\s*=\s*\w+", js_path.read_text(encoding="utf-8")):
            out.add(m.group(1))
    return out


CPP_CLASS_RE = re.compile(r"^(?:class|struct)\s+(\w+)", re.MULTILINE)
CPP_USING_RE = re.compile(r"^using\s+(\w+)\s*=", re.MULTILINE)


def collect_cpp_classes(cpp_hpp: pathlib.Path) -> set[str]:
    out: set[str] = set()
    if not cpp_hpp.is_file():
        return out
    text = cpp_hpp.read_text(encoding="utf-8")
    for m in CPP_CLASS_RE.finditer(text):
        out.add(m.group(1))
    for m in CPP_USING_RE.finditer(text):
        out.add(m.group(1))
    return out


CPP_ALIASES: dict[str, str] = {
    "FlatFilesNamespace": "FlatFiles",
    "Contract": "FluentContract",
    "Subscription": "FluentSubscription",
    "SecType": "FluentSecType",
    "ParseError": "StreamParseError",
    # The unified client's sub-namespace views carry the Python / TypeScript
    # canonical names in `parity.toml`; the C++ header names them without the
    # `View` suffix (`client.historical()` -> `Historical`, `client.stream()`
    # -> `Stream`).
    "HistoricalView": "Historical",
    "StreamView": "Stream",
}


def _cpp_class_for(class_name: str) -> str:
    """Resolve a parity-toml `class` field to its C++ class symbol.

    Honors `CPP_ALIASES` so a row carrying the Python/TS canonical
    name (`Contract`) routes to the corresponding C++ class body
    (`FluentContract`).
    """
    return CPP_ALIASES.get(class_name, class_name)


def cpp_has(symbol: str, cpp: set[str]) -> bool:
    if symbol in cpp:
        return True
    alias = CPP_ALIASES.get(symbol)
    if alias and alias in cpp:
        return True
    return False


# Parity-toml `class` field → the Rust struct name the Python method
# collector keys on. The collector harvests methods under the bare Rust
# struct identifier (`impl PyContract`), while the cross-binding row uses
# the canonical pyclass `name` (`Contract`). The fluent builders are the
# load-bearing case: `Contract.quote()` lives on `impl PyContract`,
# `SecType.fullTrades()` on `impl PySecType`. Routing the row through this
# table lets a single canonical row resolve against the Python source.
PY_CLASS_ALIASES: dict[str, str] = {
    "Contract": "PyContract",
    "SecType": "PySecType",
    "Subscription": "PySubscription",
}

# Parity-toml `class` field → the Rust struct name the TypeScript method
# collector keys on (lifted from `impl <Name>`). The per-contract fluent
# builders live on the napi `ContractRef` impl, which the cross-binding
# matrix tracks under the canonical `Contract` name (the `ContractRef`
# class itself carries its own `[[class]]` row). The full-stream builders
# live on `impl SecType`, already the canonical name.
TS_CLASS_ALIASES: dict[str, str] = {
    "Contract": "ContractRef",
}


def _py_class_for(class_name: str) -> str:
    """Resolve a parity-toml `class` field to the Python collector's key.

    Honors `PY_CLASS_ALIASES` so a row carrying the canonical pyclass name
    (`Contract`) routes to the Rust struct the collector harvests
    (`PyContract`).
    """
    return PY_CLASS_ALIASES.get(class_name, class_name)


def _ts_class_for(class_name: str) -> str:
    """Resolve a parity-toml `class` field to the TypeScript collector's key.

    Honors `TS_CLASS_ALIASES` so a row carrying the canonical name
    (`Contract`) routes to the napi impl the collector harvests
    (`ContractRef`).
    """
    return TS_CLASS_ALIASES.get(class_name, class_name)


def _py_methods_for(class_name: str, py_methods: dict[str, set[str]]) -> set[str]:
    """Python method set for a parity-toml `class`, trying the aliased
    struct key first and falling back to the bare canonical name.

    The fallback keeps synthetic selftest matrices keyed by the canonical
    name (`{"Contract": {"quote"}}`) resolving while the production
    collector keys by the Rust struct (`PyContract`).
    """
    aliased = _py_class_for(class_name)
    if aliased in py_methods:
        return py_methods[aliased]
    return py_methods.get(class_name, set())


def _ts_methods_for(class_name: str, ts_methods: dict[str, set[str]]) -> set[str]:
    """TypeScript method set for a parity-toml `class`, trying the aliased
    impl key first and falling back to the bare canonical name."""
    aliased = _ts_class_for(class_name)
    if aliased in ts_methods:
        return ts_methods[aliased]
    return ts_methods.get(class_name, set())


def _is_implicitly_tracked(name: str) -> bool:
    if name.endswith("Tick") or name.endswith("TickList") or name.endswith("TickListIter"):
        return True
    if name.endswith("Builder"):
        return True
    if name.endswith("List") or name.endswith("ListIter"):
        return True
    if name in {
        "Quote",
        "Trade",
        "Ohlcvc",
        "OpenInterest",
        "MarketValue",
        "ContractAssigned",
        "Connected",
        "Disconnected",
        "Error",
        "LoginSuccess",
        "MarketOpen",
        "MarketClose",
        "Ping",
        "Reconnected",
        "ReconnectedServer",
        "Reconnecting",
        "ReconnectsExhausted",
        "ReqResponse",
        "Restart",
        "ServerError",
        "UnknownControl",
        "UnknownFrame",
        "OptionContract",
        "AllGreeks",
    }:
        return True
    return False


# ─── Field-level discovery (per-setter granularity / #595) ──────────


# Struct → setter-name prefix. The Rust struct lives on
# `DirectConfig.<accessor>`, but the binding-side setter name combines
# the prefix with the row's field suffix. E.g. `ReconnectConfig.wait_ms`
# resolves to Python `set_reconnect_wait_ms`, TS `setReconnectWaitMs`,
# C++ `set_reconnect_wait_ms`, FFI `thetadatadx_config_set_reconnect_wait_ms`.
STRUCT_TO_PREFIX: dict[str, str] = {
    "HistoricalConfig": "",
    "StreamingConfig": "",
    "FlatFilesConfig": "flatfiles_",
    "ReconnectConfig": "reconnect_",
    "RuntimeConfig": "",
    "RetryPolicy": "retry_",
    "AuthConfig": "",
    "MetricsConfig": "metrics_",
}


def _snake_to_camel(snake: str) -> str:
    """`reconnect_wait_ms` → `reconnectWaitMs`."""
    head, *rest = snake.split("_")
    return head + "".join(part.capitalize() for part in rest)


def _canonical_setter(struct_name: str, suffix: str) -> str | None:
    """Compose the binding-side canonical setter name from the struct
    prefix and the row suffix. Returns ``None`` for unknown structs
    so the caller surfaces a clear diagnostic.
    """
    prefix = STRUCT_TO_PREFIX.get(struct_name)
    if prefix is None:
        return None
    return f"{prefix}{suffix}"


# Some FFI / C++ setters use the widened `_explicit(has_value, n)` ABI
# shape for `Option<usize>` fields (`RuntimeConfig.tokio_worker_threads`,
# `MetricsConfig.port`). The
# parity row uses the bare field name, but the binding exposes
# `thetadatadx_config_set_<field>_explicit` as the canonical setter. Accept
# either shape when matching.
FFI_EXPLICIT_SUFFIXES = ("_explicit",)


def _collect_python_setters(py_src: pathlib.Path) -> set[str]:
    """Setter names on the `Config` pyclass. The pyo3 macro pattern is
    ``#[setter] fn set_<name>`` (or ``fn <name>``). Field-level parity
    requires the setter — getter presence is a UX nicety but several
    write-only knobs (e.g. ``reconnect_max_attempts``) have no
    getter on any binding by design.
    """
    setters: set[str] = set()
    if not py_src.is_dir():
        return setters
    for rs in py_src.rglob("*.rs"):
        text = rs.read_text(encoding="utf-8")
        for m in re.finditer(r"#\[setter\][^}]*?fn\s+(\w+)", text, re.DOTALL):
            name = m.group(1)
            if name.startswith("set_"):
                setters.add(name[4:])
            else:
                setters.add(name)
    return setters


# TypeScript camelCase compound-word aliases. Multi-word terms that
# the cross-binding contract names as a single snake_case token (e.g.
# `flatfiles` in Python / C++ / FFI) get camelCased as a multi-word
# `FlatFiles` in the napi `js_name`. The alias table records the
# canonical snake form so the parity gate accepts both conventions.
TS_CAMEL_COMPOUNDS: dict[str, str] = {
    "flat_files": "flatfiles",
}


def _camel_to_snake_with_aliases(camel: str) -> set[str]:
    """`FlatFilesMaxAttempts` → both `flat_files_max_attempts` and
    `flatfiles_max_attempts`. Returns every plausible snake-case
    rendering so the parity gate accepts the cross-binding
    convention regardless of which form is canonical.
    """
    base = re.sub(r"(?<!^)([A-Z])", r"_\1", camel).lower()
    renderings = {base}
    for source, target in TS_CAMEL_COMPOUNDS.items():
        if source in base:
            renderings.add(base.replace(source, target))
    return renderings


def _collect_typescript_setters(ts_src: pathlib.Path) -> set[str]:
    """napi `set<CamelName>` setter declarations on the napi `Config`
    impl block. Returns a set of canonical snake_case names. Getter
    presence is intentionally not gated — several write-only knobs
    (e.g. `setReconnectMaxAttempts`) have no getter on any binding
    by design.
    """
    setters_camel: set[str] = set()
    if not ts_src.is_dir():
        return set()
    for rs in ts_src.rglob("*.rs"):
        text = rs.read_text(encoding="utf-8")
        # Scope to `impl Config { ... }` blocks so a `set<X>` napi method
        # on a non-Config class (e.g. the live `StreamView` streaming
        # knobs like `setSlowCallbackThresholdUs`) is not mistaken for a
        # Config knob setter. This mirrors the Python collector, which
        # relies on `#[setter]` being a Config-property-only attribute,
        # and the C++/FFI collectors, which intersect with the
        # `thetadatadx_config_set_*` C ABI surface.
        for body in _iter_impl_config_bodies(text):
            # `#[napi(js_name = "setX")]` → setter `X` (drop the `set` prefix).
            for m in re.finditer(
                r'#\[napi\([^)]*\bjs_name\s*=\s*"set([A-Z]\w*)"[^)]*\)\]',
                body,
            ):
                setters_camel.add(m.group(1))
    # Lift to snake_case for parity-row matching. Every camelCase
    # name renders to one or more snake-case candidates (the bare
    # snake form plus any compound-word alias rendering); the gate
    # accepts a match against any rendering.
    setters_snake: set[str] = set()
    for name in setters_camel:
        setters_snake.update(_camel_to_snake_with_aliases(name))
    return setters_snake


def _collect_cpp_setters(cpp_hpp: pathlib.Path, cpp_h: pathlib.Path) -> set[str]:
    """C++ wrapper exposes setters as inline `set_<name>(<type>)` on
    the `class Config { ... }` body. The matching
    `thetadatadx_config_set_<name>` declaration in `thetadatadx.h` is the C ABI
    surface the wrapper forwards to; the parity gate requires both
    halves so a forgotten C header declaration trips at link time.
    Getter presence is not gated — several write-only knobs have no
    C++ getter by design (matching the FFI / Python / TS contract).
    """
    cpp_setters: set[str] = set()
    if cpp_hpp.is_file():
        text = cpp_hpp.read_text(encoding="utf-8")
        for m in re.finditer(r"\bvoid\s+set_(\w+)\s*\(", text):
            cpp_setters.add(m.group(1))
        # Some C++ setters return `int32_t` for status codes (the
        # `_explicit` widened-ABI shape on `Option<usize>` fields).
        for m in re.finditer(r"\bint32_t\s+set_(\w+)\s*\(", text):
            cpp_setters.add(m.group(1))
    h_setters: set[str] = set()
    if cpp_h.is_file():
        text = cpp_h.read_text(encoding="utf-8")
        for m in re.finditer(r"\bthetadatadx_config_set_(\w+)\s*\(", text):
            h_setters.add(m.group(1))
    return cpp_setters & h_setters


def _collect_ffi_setters(ffi_src: pathlib.Path) -> set[str]:
    """FFI extern C setter declarations in `ffi/src/*.rs`. The
    convention is ``thetadatadx_config_set_<name>``. Getter presence is not
    gated — several write-only knobs (e.g. the per-class reconnect
    budgets) have no FFI getter by design.
    """
    setters: set[str] = set()
    if not ffi_src.is_dir():
        return setters
    for rs in ffi_src.rglob("*.rs"):
        text = rs.read_text(encoding="utf-8")
        for m in re.finditer(r"\bfn\s+thetadatadx_config_set_(\w+)\s*\(", text):
            setters.add(m.group(1))
    return setters


def _setter_present(canonical: str, setters: set[str]) -> bool:
    """True if `canonical` (or the `_explicit` widened-ABI variant) is
    in `setters`.
    """
    if canonical in setters:
        return True
    for suffix in FFI_EXPLICIT_SUFFIXES:
        if f"{canonical}{suffix}" in setters:
            return True
    return False


# ─── Config getter collection (read-back accessor roster) ───────────
#
# The setter collectors above harvest the write side of the Config knob
# roster. These collectors harvest the read-back side: every binding that
# exposes a getter for a knob in one language must expose it (idiomatic
# name) in all. The naming conventions mirror the setters:
#   * Python: `#[getter] fn get_<name>` (pyo3 strips `get_`, so the
#     property is the bare `<name>`).
#   * TypeScript: `#[napi(getter, js_name = "<camelCase>")]`.
#   * C++: a `get_<name>(...)` member on `class Config`.
#   * C ABI: `thetadatadx_config_get_<name>`.


def _iter_impl_config_bodies(text: str) -> list[str]:
    """Return the body text of every `impl Config { ... }` block in
    `text`, bounded by a brace counter. Used to scope the getter
    collectors to the `Config` knob roster — getters live on many
    pyclasses / napi classes (tick structs, the fluent `Subscription`),
    but only the `Config` read-back accessors are part of the
    cross-binding knob roster the setter check's read-side complements.
    """
    bodies: list[str] = []
    for header in re.finditer(r"impl\s+Config\s*\{", text):
        bodies.append(_balanced_body(text, header.end()))
    return bodies


def _collect_python_getters(py_src: pathlib.Path) -> set[str]:
    """Read-back getter names on the `Config` pyclass.

    Scoped to `impl Config { ... }` blocks so tick-class / fluent-value
    getters (`QuoteTick.quote_timestamp_ms`, `Subscription.kind`) do not
    leak into the Config knob roster. The pyo3 pattern is ``#[getter] fn
    get_<name>``; the `get_` prefix the Rust fn name carries is stripped to
    the bare canonical name (the Python property spelling).
    """
    getters: set[str] = set()
    if not py_src.is_dir():
        return getters
    for rs in py_src.rglob("*.rs"):
        text = rs.read_text(encoding="utf-8")
        for body in _iter_impl_config_bodies(text):
            for m in re.finditer(r"#\[getter\][^}]*?fn\s+(\w+)", body, re.DOTALL):
                name = m.group(1)
                getters.add(name[4:] if name.startswith("get_") else name)
    return getters


def _collect_typescript_getters(ts_src: pathlib.Path) -> set[str]:
    """napi `#[napi(getter, js_name = "<camelCase>")]` read-back accessors
    on the `Config` napi class.

    Scoped to `impl Config { ... }` blocks (the fluent `Subscription`
    getters `isFull` / `secType` and tick-object fields are not Config
    knobs). Returns canonical snake_case names — every camelCase `js_name`
    lifted back through the compound-word alias table, exactly like the
    setter collector.
    """
    getters_camel: set[str] = set()
    if not ts_src.is_dir():
        return set()
    for rs in ts_src.rglob("*.rs"):
        text = rs.read_text(encoding="utf-8")
        for body in _iter_impl_config_bodies(text):
            for m in re.finditer(
                r'#\[napi\([^)]*\bgetter\b[^)]*\bjs_name\s*=\s*"([a-zA-Z_]\w*)"[^)]*\)\]',
                body,
            ):
                getters_camel.add(m.group(1))
    getters_snake: set[str] = set()
    for name in getters_camel:
        getters_snake.update(_camel_to_snake_with_aliases(name))
    return getters_snake


def _collect_cpp_getters(cpp_hpp: pathlib.Path) -> set[str]:
    """C++ `get_<name>(...)` read-back members on the `class Config` body.

    The wrapper exposes each read-back as a `get_<name>()` member. The
    bare `<name>` is the canonical form (the `get_` prefix is the C++
    convention, stripped here to compare against the cross-binding roster).
    Restricted to the `class Config { ... }` body so unrelated `get_*`
    members on other classes are not counted.
    """
    getters: set[str] = set()
    if not cpp_hpp.is_file():
        return getters
    text = _expand_cpp_includes(cpp_hpp.read_text(encoding="utf-8"), cpp_hpp.parent)
    m = re.search(r"^class\s+Config\s*(?::[^{]*)?\{", text, re.MULTILINE)
    if not m:
        return getters
    body = _balanced_body(text, m.end())
    for fm in re.finditer(r"\bget_(\w+)\s*\(", body):
        getters.add(fm.group(1))
    return getters


def _collect_ffi_getters(ffi_src: pathlib.Path) -> set[str]:
    """FFI `thetadatadx_config_get_<name>` extern C read-back declarations.

    Mirrors `_collect_ffi_setters` on the read side. Returns the bare
    canonical names with the `thetadatadx_config_get_` prefix stripped.
    """
    getters: set[str] = set()
    if not ffi_src.is_dir():
        return getters
    for rs in ffi_src.rglob("*.rs"):
        text = rs.read_text(encoding="utf-8")
        for m in re.finditer(r"\bfn\s+thetadatadx_config_get_(\w+)\s*\(", text):
            getters.add(m.group(1))
    return getters


# ─── Client-facing setter-set parity ────────────────────────────────


# Per-binding spelling differences that are pure transport / language
# idiom, not a semantic divergence. Folding them away lets the four
# setter sets be compared for exact equality:
#
#   * `_explicit` — the widened `(has_value, n)` ABI variant a binding
#     emits for an `Option<usize>` field (`worker_threads_explicit` on
#     the C ABI / C++ / napi vs the bare `worker_threads` on Python).
#     Same knob, transport-only suffix.
#   * `flat_files` → `flatfiles` — napi auto-camelCases `setFlatFiles*`
#     to a multi-word `FlatFiles`, which lifts back to BOTH
#     `flat_files_*` and `flatfiles_*`; the cross-binding canonical
#     form is the single-token `flatfiles_*`.
def _normalize_setter(name: str) -> str:
    """Collapse a per-binding setter spelling to its cross-binding
    canonical form so the four setter sets compare for equality.
    """
    for suffix in FFI_EXPLICIT_SUFFIXES:
        if name.endswith(suffix):
            name = name[: -len(suffix)]
            break
    name = name.replace("flat_files", "flatfiles")
    return name


# Client-facing setters that legitimately exist on only some bindings.
# Each entry maps the canonical (normalized) setter name to a written
# reason. This is the documented per-language-idiom carve-out the gate
# tolerates — every entry is a reviewed decision, not a silencer.
#
# Empty today: the `historical_host` / `historical_port` advanced endpoint
# overrides are now bound on every binding (Python / TypeScript / C++ /
# the C ABI), so no carve-out is required. Add an entry here only when a
# setter is intentionally exposed on a strict subset of bindings.
SETTER_PARITY_EXEMPT: dict[str, str] = {}

# Read-back getter equivalent of `SETTER_PARITY_EXEMPT`. A knob exposed
# read-only / write-only on a strict subset of bindings on purpose lists
# its canonical (normalized) name here with a written reason. Several
# write-only knobs (the per-class reconnect budgets) have no getter on ANY
# binding — those never enter the getter universe and need no entry.
#
# Empty today: every knob that exposes a read-back getter exposes it on
# all four bindings.
GETTER_PARITY_EXEMPT: dict[str, str] = {}


def _check_accessor_set_parity(
    accessors: dict[str, set[str]],
    exempt: dict[str, str],
    noun: str,
    exempt_const_name: str,
) -> list[str]:
    """Assert a client-facing accessor SET matches across Python /
    TypeScript / C++ / the C ABI after normalization.

    `accessors` maps each binding name to its raw accessor-name set;
    `noun` is the accessor kind for diagnostics (`"setter"` / `"getter"`);
    `exempt_const_name` names the carve-out constant in the diagnostic.
    Genuine per-language idioms are folded by `_normalize_setter` (the
    `_explicit` widened-ABI suffix and the `flat_files`↔`flatfiles`
    camelCase split apply identically to setters and getters). Anything
    still divergent must be listed in `exempt` with a reason or it fails
    the gate. A stale exemption (now uniformly bound everywhere) is itself
    flagged so the carve-out list never rots.
    """
    norm = {lang: {_normalize_setter(a) for a in names} for lang, names in accessors.items()}
    universe: set[str] = set().union(*norm.values()) if norm else set()
    errors: list[str] = []
    for accessor in sorted(universe - set(exempt)):
        present_on = [lang for lang, names in norm.items() if accessor in names]
        if len(present_on) != len(norm):
            missing = [lang for lang in norm if lang not in present_on]
            errors.append(
                f"  {noun} `{accessor}`: present on {sorted(present_on)}, "
                f"missing on {sorted(missing)}. Bind it on every binding, "
                f"or add it to {exempt_const_name} with a per-language-idiom "
                f"reason."
            )
    for accessor, reason in exempt.items():
        present_on = [lang for lang, names in norm.items() if accessor in names]
        if present_on and len(present_on) == len(norm):
            errors.append(
                f"  {noun} `{accessor}`: listed in {exempt_const_name} "
                f"({reason!r}) but is now uniformly bound on every binding. "
                f"Drop the stale exemption."
            )
    return errors


def _check_setter_set_parity(
    py_setters: set[str],
    ts_setters: set[str],
    cpp_setters: set[str],
    ffi_setters: set[str],
    exempt: dict[str, str] | None = None,
) -> list[str]:
    """Assert the client-facing setter SET matches across Python /
    TypeScript / C++ / the C ABI after normalization.

    The per-row dotted check (`_check_dotted_rows`) verifies each
    declared knob resolves on the bindings it claims; this set-level
    check is the complementary direction — it catches a knob that
    landed on some bindings but silently never made it into the parity
    matrix on the others (the `derive_ohlcvc`-missing-on-TS defect
    class). Genuine per-language idioms are folded by
    `_normalize_setter`; anything still divergent must be listed in
    `exempt` (defaults to `SETTER_PARITY_EXEMPT`) with a reason or it
    fails the gate. The `exempt` parameter is injectable so the
    selftest can exercise the logic with synthetic carve-out lists.
    """
    if exempt is None:
        exempt = SETTER_PARITY_EXEMPT
    return _check_accessor_set_parity(
        {
            "python": py_setters,
            "typescript": ts_setters,
            "cpp": cpp_setters,
            "ffi": ffi_setters,
        },
        exempt,
        "setter",
        "SETTER_PARITY_EXEMPT",
    )


def _check_getter_set_parity(
    py_getters: set[str],
    ts_getters: set[str],
    cpp_getters: set[str],
    ffi_getters: set[str],
    exempt: dict[str, str] | None = None,
) -> list[str]:
    """Assert the client-facing read-back getter SET matches across
    Python / TypeScript / C++ / the C ABI after normalization.

    The complement to `_check_setter_set_parity` on the read side: a knob
    that exposes a getter on some bindings but silently never grew one on
    the others trips the gate. Together the two checks pin the full Config
    knob roster — both write and read accessors — across every binding.
    Per-language idioms fold via `_normalize_setter`; intentional
    subset-of-bindings getters list in `exempt` (defaults to
    `GETTER_PARITY_EXEMPT`) with a reason.
    """
    if exempt is None:
        exempt = GETTER_PARITY_EXEMPT
    return _check_accessor_set_parity(
        {
            "python": py_getters,
            "typescript": ts_getters,
            "cpp": cpp_getters,
            "ffi": ffi_getters,
        },
        exempt,
        "getter",
        "GETTER_PARITY_EXEMPT",
    )


# ─── Public-surface identifier collection (vocab guard) ─────────────


def _check_public_surface_vocab(
    py_classes: set[str],
    ts_classes: set[str],
    cpp_classes: set[str],
    py_setters: set[str],
    ts_setters: set[str],
    cpp_setters: set[str],
    ffi_setters: set[str],
    py_methods: dict[str, set[str]],
    ts_methods: dict[str, set[str]],
    cpp_methods: dict[str, set[str]],
) -> list[str]:
    """Assert no PUBLIC client identifier embeds a banned architecture
    token.

    Scans the identifier sets the parity collectors already harvest —
    classes, config setters, and per-class methods on every binding —
    for an internal-architecture token (`tokio`, `mdds`, `disruptor`,
    ...) buried inside the name. This is the structural counterpart to
    the text scrubber: it sees only declared public API names, so it
    never false-positives on the bindings' legitimate internal use of
    the runtime / ring / lock primitives, and it catches a banned token
    embedded in a snake_case / camelCase identifier that the scrubber's
    `\\bword\\b` rule misses.
    """
    errors: list[str] = []

    def _check(identifier: str, where: str) -> None:
        token = _surface_token_hit(identifier)
        if token is not None:
            errors.append(
                f"  {where}: public identifier `{identifier}` embeds "
                f"banned architecture token `{token}`. Rename to a "
                f"neutral client-facing name (the user concept, not the "
                f"implementation)."
            )

    for cls in sorted(py_classes):
        _check(cls, "python class")
    for cls in sorted(ts_classes):
        _check(cls, "typescript class")
    for cls in sorted(cpp_classes):
        _check(cls, "cpp class")
    for setter in sorted(py_setters):
        _check(setter, "python setter")
    for setter in sorted(ts_setters):
        _check(setter, "typescript setter")
    for setter in sorted(cpp_setters):
        _check(setter, "cpp setter")
    for setter in sorted(ffi_setters):
        _check(setter, "ffi setter")
    for cls, methods in sorted(py_methods.items()):
        for method in sorted(methods):
            _check(method, f"python method {cls}.")
    for cls, methods in sorted(ts_methods.items()):
        for method in sorted(methods):
            _check(method, f"typescript method {cls}.")
    for cls, methods in sorted(cpp_methods.items()):
        for method in sorted(methods):
            _check(method, f"cpp method {cls}.")
    return errors


# ─── Rust field discovery (reverse-direction orphan check) ──────────


# Structs we consider in scope for the field-level gate. Adding a new
# struct here is one half of the binding-sweep workflow; the other
# half is adding rows to `parity.toml` for every pub field on the new
# struct (or marking each as `rust_only = true, issue = "#N"`).
#
# `ReconnectAttemptLimits` is intentionally NOT scoped here even
# though it carries `pub max_attempts / max_rate_limited_attempts /
# stable_window` fields; those mirror onto the bindings via
# `ReconnectConfig.max_attempts` etc. (the inner `limits` struct is
# wrapped in `ReconnectPolicy::Auto(...)` and the binding setters
# write through to it). The parity-toml rows under `ReconnectConfig.*`
# already cover the cross-binding contract for those fields.
SCOPED_STRUCTS: tuple[str, ...] = (
    "HistoricalConfig",
    "StreamingConfig",
    "FlatFilesConfig",
    "ReconnectConfig",
    "RuntimeConfig",
    "RetryPolicy",
    "AuthConfig",
    "MetricsConfig",
)


STRUCT_HEADER_RE = re.compile(
    r"pub\s+struct\s+(\w+)\s*\{",
)
PUB_FIELD_RE = re.compile(
    r"^\s+pub\s+(\w+)\s*:",
    re.MULTILINE,
)


def _collect_rust_pub_fields(config_dir: pathlib.Path) -> dict[str, set[str]]:
    """Return `{struct_name: {field, ...}}` for every scoped struct.

    Parses `crates/thetadatadx/src/config/*.rs`. Skips fields on
    structs not listed in `SCOPED_STRUCTS` — `DirectConfig`'s pub
    fields are nested-struct accessors that the class-level gate
    already covers.
    """
    out: dict[str, set[str]] = {}
    if not config_dir.is_dir():
        return out
    for rs in config_dir.rglob("*.rs"):
        text = rs.read_text(encoding="utf-8")
        # Find every `pub struct X {` block and walk forward until the
        # closing brace. The structs in `crates/thetadatadx/src/config/`
        # never nest other struct definitions; a depth=1 brace counter
        # suffices.
        for header in STRUCT_HEADER_RE.finditer(text):
            struct_name = header.group(1)
            if struct_name not in SCOPED_STRUCTS:
                continue
            body_start = header.end()
            depth = 1
            i = body_start
            while i < len(text) and depth > 0:
                c = text[i]
                if c == "{":
                    depth += 1
                elif c == "}":
                    depth -= 1
                i += 1
            body = text[body_start : i - 1]
            for fm in PUB_FIELD_RE.finditer(body):
                out.setdefault(struct_name, set()).add(fm.group(1))
    return out


# Some Rust pub field names differ from the binding-side setter
# suffix:
#
#   - `ReconnectConfig.stable_window: Duration` → setter
#     `set_reconnect_stable_window_secs` (the binding takes a `u64`
#     seconds value; the row name carries the unit suffix).
#   - `FlatFilesConfig.initial_backoff: Duration` →
#     `set_flatfiles_initial_backoff_secs`.
#   - `RetryPolicy.initial_delay: Duration` →
#     `set_retry_initial_delay_ms`.
#
# The table below records the rust-field → binding-suffix renames.
# Fields not listed are 1:1.
RUST_FIELD_RENAMES: dict[tuple[str, str], str] = {
    # The async worker-thread count is stored internally on
    # `RuntimeConfig.tokio_worker_threads`, but the public client setter
    # is named `worker_threads` on every binding (the implementation
    # runtime name never reaches the user surface). The parity row is
    # keyed by the public concept; this mapping bridges the internal
    # storage field to that row for the reverse-direction orphan check.
    ("RuntimeConfig", "tokio_worker_threads"): "worker_threads",
    ("ReconnectConfig", "stable_window"): "stable_window_secs",
    ("ReconnectAttemptLimits", "stable_window"): "stable_window_secs",
    ("ReconnectAttemptLimits", "max_elapsed"): "max_elapsed_secs",
    ("FlatFilesConfig", "initial_backoff"): "initial_backoff_secs",
    ("FlatFilesConfig", "max_backoff"): "max_backoff_secs",
    ("RetryPolicy", "initial_delay"): "initial_delay_ms",
    ("RetryPolicy", "max_delay"): "max_delay_ms",
    ("RetryPolicy", "max_elapsed"): "max_elapsed_secs",
    # StreamingConfig scalar knobs carry a `streaming_` prefix at the
    # binding surface so the generic field names (`timeout_ms`, `ring_size`)
    # stay unambiguous against sibling sub-configs.
    ("StreamingConfig", "timeout_ms"): "streaming_timeout_ms",
    ("StreamingConfig", "ring_size"): "streaming_ring_size",
    ("StreamingConfig", "ping_interval_ms"): "streaming_ping_interval_ms",
    ("StreamingConfig", "connect_timeout_ms"): "streaming_connect_timeout_ms",
    ("StreamingConfig", "io_read_slice_ms"): "streaming_io_read_slice_ms",
    ("StreamingConfig", "data_watchdog_ms"): "streaming_data_watchdog_ms",
    ("StreamingConfig", "keepalive_idle_secs"): "streaming_keepalive_idle_secs",
    ("StreamingConfig", "keepalive_interval_secs"): "streaming_keepalive_interval_secs",
    ("StreamingConfig", "keepalive_retries"): "streaming_keepalive_retries",
    ("StreamingConfig", "host_selection"): "streaming_host_selection",
    ("StreamingConfig", "host_shuffle_seed"): "streaming_host_shuffle_seed",
}


def _rust_field_to_row_suffix(struct: str, field: str) -> str:
    return RUST_FIELD_RENAMES.get((struct, field), field)


# ─── Method-level discovery (per-method granularity / unified clients) ───


def _camel_to_snake(camel: str) -> str:
    """`activeFullSubscriptions` -> `active_full_subscriptions`."""
    return re.sub(r"(?<!^)([A-Z])", r"_\1", camel).lower()


def _collect_python_class_methods(py_src: pathlib.Path) -> dict[str, set[str]]:
    """Return `{pyclass_name: {method, ...}}` for every Python pyclass.

    Parses every `#[pymethods] impl <Path>` block (or `impl <Path>`
    block participating in `multiple-pymethods`) and harvests the
    `fn <name>` declarations inside. `<Path>` accepts a bare class
    name (`impl Client`) or a fully-qualified Rust path
    (`impl crate::Client`); the collector normalises both
    to the bare class name so the parity row can refer to it directly.

    Filters out the lifecycle dunders (`__new__`, `__repr__`,
    `__getattr__`, `__init__`, `__enter__`, `__exit__`) and the
    constructor `new` so the matrix tracks user-facing methods only.
    """
    out: dict[str, set[str]] = {}
    if not py_src.is_dir():
        return out
    skip_names = {
        "new",
        "__new__",
        "__repr__",
        "__getattr__",
        "__init__",
        "__enter__",
        "__exit__",
    }
    # `impl <Path> {` — `<Path>` may be `Name` or `crate::...::Name`.
    # Capture the last identifier segment before the opening brace.
    impl_re = re.compile(
        r"impl\s+(?:[A-Za-z_][A-Za-z0-9_]*::)*([A-Za-z_][A-Za-z0-9_]*)\s*\{"
    )
    fn_re = re.compile(r"fn\s+([a-zA-Z_][a-zA-Z0-9_]*)\s*[(<]")
    for rs in py_src.rglob("*.rs"):
        text = rs.read_text(encoding="utf-8")
        for header in impl_re.finditer(text):
            class_name = header.group(1)
            # Walk the impl block with a brace counter to bound the
            # method scan to a single impl body.
            body_start = header.end()
            depth = 1
            i = body_start
            while i < len(text) and depth > 0:
                c = text[i]
                if c == "{":
                    depth += 1
                elif c == "}":
                    depth -= 1
                i += 1
            body = text[body_start : i - 1]
            for fm in fn_re.finditer(body):
                name = fm.group(1)
                if name in skip_names:
                    continue
                out.setdefault(class_name, set()).add(name)
    return out


def _collect_typescript_class_methods(ts_src: pathlib.Path) -> dict[str, set[str]]:
    """Return `{ts_class_name: {method, ...}}` for every TypeScript
    napi class.

    Parses every `#[napi]` / `#[napi(js_name = "...")] impl <Name>` block
    and harvests the JS-visible method names inside. The TS impl blocks
    live across multiple files (`lib.rs`, `_generated/*.rs`,
    `config_class.rs`, ...); the collector walks each one and bounds
    the method scan to the impl body with a brace counter.

    Covers both method-attribute shapes:

    * `#[napi(js_name = "<camelCase>")] fn <snake>` — explicit JS name.
    * `#[napi] fn <snake>` (or `#[napi(...)]` without `js_name`) —
      napi-rs auto-camelCases the fn name. Both the snake_case fn
      name and its camelCase derivation are recorded so a row matches
      against either spelling.

    The class name is lifted from `impl <Name>` directly (not the
    `#[napi(js_name = "X")]` on the struct itself), which is the form
    the cross-binding parity rows use as the canonical class identifier.
    """
    out: dict[str, set[str]] = {}
    if not ts_src.is_dir():
        return out
    # `impl <Path> {` — handle bare names and qualified paths
    # (`impl crate::Client`) symmetrically with the Python
    # collector. The captured class name is always the last path segment.
    impl_re = re.compile(
        r"impl\s+(?:[A-Za-z_][A-Za-z0-9_]*::)*([A-Za-z_][A-Za-z0-9_]*)\s*\{"
    )
    js_name_re = re.compile(
        r'#\[napi\([^)]*\bjs_name\s*=\s*"([a-zA-Z_][a-zA-Z0-9_]*)"[^)]*\)\]\s*'
        r'(?:pub\s+)?(?:async\s+)?fn\s+([a-z_][a-z0-9_]*)\s*[(<]'
    )
    bare_napi_re = re.compile(
        r'#\[napi(?:\((?:(?!js_name)[^)])*\))?\]\s*'
        r'(?:pub\s+)?(?:async\s+)?fn\s+([a-z_][a-z0-9_]*)\s*[(<]'
    )
    for rs in ts_src.rglob("*.rs"):
        text = rs.read_text(encoding="utf-8")
        for header in impl_re.finditer(text):
            class_name = header.group(1)
            # Walk the impl block with a brace counter to bound the
            # method scan to a single impl body.
            body_start = header.end()
            depth = 1
            i = body_start
            while i < len(text) and depth > 0:
                c = text[i]
                if c == "{":
                    depth += 1
                elif c == "}":
                    depth -= 1
                i += 1
            body = text[body_start : i - 1]
            for m in js_name_re.finditer(body):
                out.setdefault(class_name, set()).add(m.group(1))
            for m in bare_napi_re.finditer(body):
                snake = m.group(1)
                head, *rest = snake.split("_")
                camel = head + "".join(p.capitalize() for p in rest)
                out.setdefault(class_name, set()).add(camel)
                out.setdefault(class_name, set()).add(snake)
    return out


def _expand_cpp_includes(hpp_text: str, include_dir: pathlib.Path) -> str:
    """Inline every `#include "<name>.inc"` directive against the
    matching file under `include_dir`. The `*.inc` files extend a
    class body with generator-emitted member declarations
    (`sdks/cpp/include/fpss.hpp.inc` adds `StreamingClient` methods that
    live in `crates/thetadatadx/sdk_surface.toml`), and the parity
    gate must see those declarations as part of the surrounding
    class body.

    Falls back to leaving the directive in place when the included
    file is missing, so a malformed `#include` cannot wedge the gate.
    """
    include_re = re.compile(r'#include\s+"([^"]+\.inc)"')

    def _sub(m: re.Match[str]) -> str:
        rel = m.group(1)
        target = include_dir / rel
        if target.is_file():
            return target.read_text(encoding="utf-8")
        return m.group(0)

    return include_re.sub(_sub, hpp_text)


def _collect_cpp_class_methods(cpp_hpp: pathlib.Path) -> dict[str, set[str]]:
    """Return `{class_name: {method, ...}}` for every C++ class.

    Parses each `class X { ... };` body in `thetadatadx.hpp` and collects
    every member declaration with a `name(` shape. The first identifier
    before the `(` is the method name. Bounded brace-counting keeps
    nested types (e.g. lambdas inside default-arg initializers) from
    leaking into the outer class's method set.

    Honors `#include "<file>.inc"` inside a class body by inlining the
    included file's contents before parsing — generator-emitted method
    declarations (`fpss.hpp.inc`) extend the surrounding class body
    and must count toward parity.
    """
    out: dict[str, set[str]] = {}
    if not cpp_hpp.is_file():
        return out
    text = _expand_cpp_includes(cpp_hpp.read_text(encoding="utf-8"), cpp_hpp.parent)
    # Limit to class bodies — struct bodies are POD-shaped value types
    # and irrelevant to the cross-binding method contract.
    class_header_re = re.compile(r"^class\s+(\w+)\s*(?::[^{]*)?\{", re.MULTILINE)
    for header in class_header_re.finditer(text):
        class_name = header.group(1)
        body_start = header.end()
        depth = 1
        i = body_start
        while i < len(text) and depth > 0:
            c = text[i]
            if c == "{":
                depth += 1
            elif c == "}":
                depth -= 1
            i += 1
        body = text[body_start : i - 1]
        # Match member declarations + definitions. The `name(` pattern is
        # preceded by whitespace and (optionally) qualifiers / return
        # type tokens; the first plain identifier immediately before the
        # opening paren is the method name.
        for fm in re.finditer(
            r"(?:^|\s)([a-z_][a-z0-9_]*)\s*\(",
            body,
            re.MULTILINE,
        ):
            name = fm.group(1)
            # Filter language keywords that look like method calls.
            if name in {
                "if",
                "while",
                "for",
                "switch",
                "return",
                "throw",
                "catch",
                "sizeof",
                "operator",
                "new",
                "delete",
                "static_cast",
                "reinterpret_cast",
                "const_cast",
                "dynamic_cast",
            }:
                continue
            out.setdefault(class_name, set()).add(name)
    return out


# The unified `Client`'s data surfaces are reached through view
# accessors that return a cheap handle clone (`historical`, `stream`,
# `flatFiles`). They are hand-written per binding rather than generated
# from `endpoint_surface.toml`, so a drop or rename in one binding would
# otherwise pass silently. The forward `[[method]]` check catches a drop
# of a declared accessor; this roster anchors the reverse-direction scan
# that catches a NEW symmetric view accessor added on a binding without
# an enrolling row. Names are the canonical camelCase row spelling; the
# scan derives the per-binding form exactly as the forward check does.
CLIENT_VIEW_ACCESSORS: frozenset[str] = frozenset(
    {"historical", "stream", "flatFiles"}
)


# The flat-file fetch surface lives on the namespace returned by
# `Client.flatFiles`. The forward `[[method]]` rows gate each declared fetch
# method against the bindings; this roster anchors the reverse-direction scan
# that catches a NEW fetch method added on a binding's namespace class without
# an enrolling row. Names are the canonical camelCase row spelling (the scan
# derives the per-binding form exactly as the forward check does). `request` is
# the generic dispatcher; the five named methods are the served-dataset
# conveniences. The blob-to-disk helper (`flatFileToPath`) is NOT a namespace
# method — it lives on the unified client (or, on C++, on the namespace under a
# different name) and is enrolled by its own row routed through
# `METHOD_BINDING_OVERRIDES`, so it is intentionally absent from this roster.
FLATFILES_NAMESPACE_METHODS: frozenset[str] = frozenset(
    {
        "optionTradeQuote",
        "optionOpenInterest",
        "optionEod",
        "stockTradeQuote",
        "stockEod",
        "request",
    }
)


# Names the per-binding method collectors harvest from the flat-file namespace
# class body that are NOT cross-binding fetch methods and so carry no
# `[[method]]` row of their own: the C++ collector picks up the `handle_` data
# member and the FFI extern declarations called inside the inline method bodies,
# and the Python collector picks up the module-private `pull_decoded` free fn.
# `to_path` is the C++ spelling of the blob-to-disk helper — a real public
# method, but enrolled by the `flatFileToPath` row routed through
# `METHOD_BINDING_OVERRIDES`, not by a namespace row — so it is exempt from the
# namespace reverse-orphan scan to avoid a double-count.
FLATFILES_NAMESPACE_EXEMPT_MEMBERS: frozenset[str] = frozenset(
    {
        "handle_",
        "pull_decoded",
        "pull_decoded_async",
        "thetadatadx_flatfile_request_decoded",
        "thetadatadx_flatfile_request_to_path",
        "to_path",
    }
)


# A few cross-binding methods do not share a single home class or a single
# name-derivation rule across bindings; the forward `[[method]]` check resolves
# one `(class, name)` per binding from the row, so those methods need an explicit
# per-binding target. The blob-to-disk flat-file helper is the load-bearing case:
# it is `Client.flatfile_to_path` (one word) on the Python pyclass,
# `Client.flatFileToPath` on the TypeScript napi class, and `FlatFiles::to_path`
# on the C++ class. Keyed by the canonical `(row_class, row_name)`, each entry
# gives the binding-specific `(collector_class, member_name)` the forward check
# must look up instead of deriving from the row. `collector_class` is the key the
# per-binding collector uses (the C++ entry already names the resolved C++ class,
# so it bypasses the alias table); `member_name` is the exact harvested spelling.
METHOD_BINDING_OVERRIDES: dict[tuple[str, str], dict[str, tuple[str, str]]] = {
    ("FlatFilesNamespace", "flatFileToPath"): {
        "python": ("Client", "flatfile_to_path"),
        "typescript": ("Client", "flatFileToPath"),
        "cpp": ("FlatFiles", "to_path"),
    },
}


def _check_method_rows(
    method_rows: list[dict[str, Any]],
    py_methods: dict[str, set[str]],
    ts_methods: dict[str, set[str]],
    cpp_methods: dict[str, set[str]],
) -> list[str]:
    """Per-method cross-binding gate.

    Each `[[method]]` row in `parity.toml` declares a `(class, name)`
    pair plus the expected presence in each binding. The checker
    verifies the actual binding state against the declared state and
    returns a list of human-readable mismatch strings (empty when
    every row matches).

    Beyond the per-row forward check, the unified `Client` view accessors
    (`CLIENT_VIEW_ACCESSORS`) get a reverse-direction orphan scan: a view
    accessor that exists on the `Client` class in a binding but carries no
    enrolling `Client` `[[method]]` row trips the gate, so a future
    accessor cannot ship on one binding untracked.
    """
    errors: list[str] = []
    for row in method_rows:
        class_name = row.get("class")
        camel = row.get("name")
        if not class_name or not camel:
            errors.append(
                f"  [[method]] row missing `class` or `name`: {row!r}"
            )
            continue
        snake = _camel_to_snake(camel)

        # A handful of methods do not share a home class or a single
        # name-derivation rule across bindings (the flat-file blob-to-disk
        # helper is the load-bearing case). `METHOD_BINDING_OVERRIDES` supplies
        # the binding-specific `(collector_class, member_name)` for those rows;
        # absent an entry, every binding resolves from the row's `class` / `name`
        # exactly as before.
        override = METHOD_BINDING_OVERRIDES.get((class_name, camel))

        # Python: snake_case method declared on the pyclass. A `#[getter]`
        # readback accessor carries a `get_` prefix on its Rust fn name
        # (`fn get_flush_mode`) while pyo3 strips the prefix so the Python
        # property name stays bare (`config.flush_mode`); accept the
        # `get_`-prefixed fn name against the bare row, exactly as the C++
        # branch below accepts `get_<snake>`.
        if override and "python" in override:
            py_lookup_class, py_member = override["python"]
        else:
            py_lookup_class, py_member = class_name, snake
        py_class_methods = _py_methods_for(py_lookup_class, py_methods)
        declared_py = row.get("python", False)
        actual_py = py_member in py_class_methods or f"get_{py_member}" in py_class_methods
        if declared_py != actual_py:
            verb = "missing" if declared_py and not actual_py else "unexpected"
            errors.append(
                f"  {class_name}.{camel}.python: declared={declared_py}, "
                f"actual={actual_py} ({verb} -- expected `fn {py_member}` "
                f"or `fn get_{py_member}` inside `impl {py_lookup_class}` on the "
                f"Python pyclass)"
            )

        # TypeScript: napi-attributed method declared inside the
        # matching `impl <ClassName>` block under `sdks/typescript/src/`.
        # The collector records both the `js_name` and the auto-
        # camelCased fn-name spelling so a row's `name` can match
        # against either.
        if override and "typescript" in override:
            ts_lookup_class, ts_member = override["typescript"]
        else:
            ts_lookup_class, ts_member = class_name, camel
        declared_ts = row.get("typescript", False)
        actual_ts = ts_member in _ts_methods_for(ts_lookup_class, ts_methods)
        if declared_ts != actual_ts:
            verb = "missing" if declared_ts and not actual_ts else "unexpected"
            errors.append(
                f"  {class_name}.{camel}.typescript: declared={declared_ts}, "
                f"actual={actual_ts} ({verb} -- expected "
                f'`#[napi(js_name = "{ts_member}")]` (or bare `#[napi]`) '
                f"inside `impl {ts_lookup_class}` under "
                f"sdks/typescript/src/)"
            )

        # C++: `<snake>(` member declaration inside the matching
        # class body in `thetadatadx.hpp`. C++ alias names route through
        # `CPP_ALIASES` (`Contract` -> `FluentContract`). Readback
        # getters on the C++ `Config` carry a uniform `get_` prefix
        # (`get_flush_mode`), where Python exposes the field-shaped
        # property (`flush_mode`) and TypeScript the camelCase getter
        # (`flushMode`); accept the `get_`-prefixed C++ form so the
        # per-language naming convention does not read as drift. An override
        # entry already names the resolved C++ class, so it bypasses the alias
        # table.
        if override and "cpp" in override:
            cpp_class, cpp_member = override["cpp"]
        else:
            cpp_class, cpp_member = _cpp_class_for(class_name), snake
        declared_cpp = row.get("cpp", False)
        cpp_class_methods = cpp_methods.get(cpp_class, set())
        actual_cpp = (
            cpp_member in cpp_class_methods or f"get_{cpp_member}" in cpp_class_methods
        )
        if declared_cpp != actual_cpp:
            verb = "missing" if declared_cpp and not actual_cpp else "unexpected"
            errors.append(
                f"  {class_name}.{camel}.cpp: declared={declared_cpp}, "
                f"actual={actual_cpp} ({verb} -- expected `{cpp_member}(` "
                f"or `get_{cpp_member}(` inside `class {cpp_class}` body in "
                f"sdks/cpp/include/thetadatadx.hpp)"
            )

    # Reverse-direction orphan scan for the unified-client view accessors.
    # An accessor present on the `Client` class in a binding but carrying
    # no enrolling `Client` `[[method]]` row is undocumented drift: the
    # symmetric `historical` / `stream` / `flatFiles` surface stays in
    # lockstep only if every accessor each binding exposes is enrolled.
    enrolled_client_methods = {
        row["name"]
        for row in method_rows
        if row.get("class") == "Client" and row.get("name")
    }
    py_client = py_methods.get("Client", set())
    ts_client = ts_methods.get("Client", set())
    cpp_client = cpp_methods.get(_cpp_class_for("Client"), set())
    for camel in sorted(CLIENT_VIEW_ACCESSORS):
        if camel in enrolled_client_methods:
            continue
        snake = _camel_to_snake(camel)
        present_on = sorted(
            lang
            for lang, seen in (
                ("python", snake in py_client or f"get_{snake}" in py_client),
                ("typescript", camel in ts_client),
                ("cpp", snake in cpp_client or f"get_{snake}" in cpp_client),
            )
            if seen
        )
        if present_on:
            errors.append(
                f"  Client.{camel}: view accessor present on {present_on} but "
                f"has no Client [[method]] row. Add one enrolling its "
                f"per-binding presence so the unified-client view surface "
                f"stays tracked."
            )

    # Reverse-direction orphan scan for the flat-file fetch namespace. A fetch
    # method present on the namespace class in a binding but carrying no
    # enrolling `FlatFilesNamespace` `[[method]]` row is undocumented drift: the
    # bulk per-day flat-file surface stays symmetric only if every fetch method
    # each binding exposes is enrolled. The scan walks the methods actually
    # harvested on the namespace class per binding (Python / TypeScript key on
    # `FlatFilesNamespace`, C++ on the aliased `FlatFiles`), maps each to its
    # canonical camelCase row name, and flags any that is neither enrolled nor a
    # non-public collector artifact (the C++ collector picks up the FFI extern
    # declarations and the `handle_` member inside the class body; Python picks
    # up the module-private `pull_decoded` free fn). The exempt roster names
    # those artifacts explicitly so the scan fires only on a genuine new fetch
    # method.
    enrolled_flatfiles_methods = {
        row["name"]
        for row in method_rows
        if row.get("class") == "FlatFilesNamespace" and row.get("name")
    }
    flatfiles_members: set[str] = set()
    flatfiles_members |= py_methods.get("FlatFilesNamespace", set())
    flatfiles_members |= ts_methods.get("FlatFilesNamespace", set())
    flatfiles_members |= cpp_methods.get(_cpp_class_for("FlatFilesNamespace"), set())
    for member in sorted(flatfiles_members - FLATFILES_NAMESPACE_EXEMPT_MEMBERS):
        # A Python `<fetch>_async` member is the awaitable twin of its sync
        # fetch, not a distinct fetch contract: the TypeScript fetch methods
        # are already `async` (Promise) and C++ exposes a `std::future`
        # companion, so the async surface rides the same enrolled row rather
        # than carrying its own. Strip a trailing `_async` and require the
        # base to be an enrolled fetch (mirroring how the historical `_async`
        # members are matched by their base endpoint). This does not weaken
        # the scan: an `_async` member whose base is not an enrolled fetch
        # still trips below.
        base = member[: -len("_async")] if member.endswith("_async") else member
        camel = _snake_to_camel(base)
        if camel in enrolled_flatfiles_methods or base in enrolled_flatfiles_methods:
            continue
        errors.append(
            f"  FlatFilesNamespace.{member}: fetch method present on the "
            f"namespace class but has no `[[method]]` row. Either enroll it "
            f"(with the cross-binding shape) or add it to "
            f"FLATFILES_NAMESPACE_EXEMPT_MEMBERS with the documented reason it "
            f"carries no cross-binding fetch contract."
        )

    # Reverse-direction orphan scan for the `StreamingSession` async-session
    # surface. `StreamingSession` is the Python-only `async with` /
    # `async for` session handle (it carries a `[[class]]` row;
    # `typescript`/`cpp` use a Promise iterator / RAII guard instead). Its
    # public surface is intentionally the inner `Client`'s, reached through
    # `__getattr__` proxying — its OWN first-class methods are only the
    # async-iterator and context-manager dunders, which carry no
    # cross-binding contract and are exempt by the roster below. This scan
    # documents that exemption AND fires if a future first-class method
    # (one the user calls directly on the session, not a proxied Client
    # method) is added without an enrolling `[[method]]` row.
    enrolled_session_methods = {
        row["name"]
        for row in method_rows
        if row.get("class") == "StreamingSession" and row.get("name")
    }
    session_methods = py_methods.get("StreamingSession", set())
    for name in sorted(session_methods - STREAMING_SESSION_EXEMPT_METHODS):
        camel = _snake_to_camel(name)
        if camel in enrolled_session_methods or name in enrolled_session_methods:
            continue
        errors.append(
            f"  StreamingSession.{name}: first-class session method present "
            f"on the Python pyclass but has no `[[method]]` row. Either enroll "
            f"it (with the cross-binding shape) or add it to "
            f"STREAMING_SESSION_EXEMPT_METHODS with the documented reason it "
            f"carries no cross-binding contract."
        )

    return errors


# `StreamingSession`'s own methods that carry no cross-binding contract:
# the async-iterator protocol (`__aiter__` / `__anext__`), the async and
# sync context-manager entries (`__aenter__` / `__aexit__` / `__enter__` /
# `__exit__`), and the attribute-proxy hook (`__getattr__`) that forwards
# every data call to the inner `Client`. None of these are a method a user
# calls by name expecting cross-binding symmetry, so they are exempt from
# the `StreamingSession` orphan scan. (The cross-binding method collector
# already filters the sync dunders; this roster names the full set
# explicitly so the exemption is self-documenting.)
STREAMING_SESSION_EXEMPT_METHODS: frozenset[str] = frozenset(
    {
        "__aiter__",
        "__anext__",
        "__aenter__",
        "__aexit__",
        "__enter__",
        "__exit__",
        "__getattr__",
        "__next__",
        "__iter__",
    }
)


# ─── Core streaming observability-surface orphan check ──────────────
#
# The cross-binding `[[method]]` rows above gate each DECLARED method
# against the bindings. They do not gate the reverse direction on the
# Rust side: a public observability accessor wired onto the core
# streaming surface (`StreamSurface` view / `StreamingClient`) that never
# grew a parity row is invisible — the row simply does not exist, so no
# check fires, and the accessor silently reaches none of the bindings.
# That is exactly how a wired-but-unbound counter/threshold knob drifts.
#
# This check harvests the public observability accessors on the two core
# streaming surfaces and asserts each maps to a `[[method]]` row. It is
# scoped to the observability accessor SHAPE (cumulative counters, ring
# telemetry, and the slow-callback threshold setter) so it never trips on
# the lifecycle / subscription methods whose cross-binding spelling
# legitimately diverges and which the forward rows already cover.

# The core Rust class name → the parity-toml `class` field. The unified
# streaming surface is the `StreamSurface` view returned by
# `Client::stream()`, tracked in `parity.toml` under the binding-facing
# `StreamView` name.
CORE_STREAMING_CLASS_TO_ROW: dict[str, str] = {
    "StreamSurface": "StreamView",
    "StreamingClient": "StreamingClient",
}

# Core Rust accessor name → the canonical camelCase parity-row `name`.
# Most accessors camelCase directly; the standalone `StreamingClient`
# core counter is named `dropped_count` but the binding/row contract
# spells it `droppedEventCount` (the same counter as the unified
# surface), so it is bridged explicitly here.
CORE_STREAMING_METHOD_RENAMES: dict[str, str] = {
    "dropped_count": "droppedEventCount",
    "dropped_event_count": "droppedEventCount",
    "slow_callback_count": "slowCallbackCount",
    "set_slow_callback_threshold": "setSlowCallbackThresholdUs",
}

# An observability accessor is one whose name matches this shape. The
# closure is intentionally narrow: cumulative counters (`*_count`), ring
# telemetry (`ring_*`), and the slow-callback threshold setter. Lifecycle
# / subscription / connection methods do not match and stay governed by
# the forward `[[method]]` rows alone.
def _is_core_observability_accessor(name: str) -> bool:
    if name == "record_panic":
        # Internal `#[cfg(feature = "__internal")]` fault-injection hook,
        # not a public client accessor.
        return False
    if name.endswith("_count"):
        return True
    if name.startswith("ring_"):
        return True
    if name.startswith("set_") and name.endswith("_threshold"):
        return True
    return False


def _collect_core_streaming_observability_methods(
    client_rs: pathlib.Path,
    fpss_mod_rs: pathlib.Path,
) -> dict[str, set[str]]:
    """Return `{core_class: {accessor, ...}}` for the public observability
    accessors on the core streaming surfaces.

    Parses `impl StreamSurface<...> { ... }` in `client.rs` and
    `impl StreamingClient { ... }` in `fpss/mod.rs`, collecting every
    `pub fn <name>` whose name matches the observability shape
    (`_is_core_observability_accessor`). `#[cfg(...)]` / `#[doc(hidden)]`
    gated methods are skipped — they are not part of the published
    surface a binding must mirror.
    """
    out: dict[str, set[str]] = {}
    sources: list[tuple[str, pathlib.Path]] = [
        ("StreamSurface", client_rs),
        ("StreamingClient", fpss_mod_rs),
    ]
    # `impl StreamSurface<'_> {` / `impl StreamingClient {` — tolerate an
    # optional generic / lifetime parameter list before the brace.
    pub_fn_re = re.compile(
        r"((?:#\[[^\]]*\]\s*)*)\bpub\s+fn\s+([a-z_][a-z0-9_]*)\s*[(<]"
    )
    for class_name, rs in sources:
        if not rs.is_file():
            continue
        text = rs.read_text(encoding="utf-8")
        impl_re = re.compile(
            rf"impl\s+{class_name}\b[^{{]*\{{"
        )
        for header in impl_re.finditer(text):
            body = _balanced_body(text, header.end())
            for m in pub_fn_re.finditer(body):
                attrs = m.group(1)
                name = m.group(2)
                if "cfg(" in attrs or "doc(hidden)" in attrs:
                    continue
                if not _is_core_observability_accessor(name):
                    continue
                out.setdefault(class_name, set()).add(name)
    return out


def _check_core_streaming_method_rows(
    core_methods: dict[str, set[str]],
    method_rows: list[dict[str, Any]],
) -> list[str]:
    """Assert every public observability accessor on the core streaming
    surfaces carries a `[[method]]` parity row.

    Closes the blind spot where a counter / threshold knob wired onto the
    core `StreamSurface` / `StreamingClient` surface reaches none of the
    bindings because no row enrolls it. The row's per-binding columns are
    then gated by `_check_method_rows`; this check only asserts the row
    EXISTS for the right class.
    """
    errors: list[str] = []
    declared: set[tuple[str, str]] = {
        (row.get("class", ""), row.get("name", "")) for row in method_rows
    }
    for core_class, names in sorted(core_methods.items()):
        row_class = CORE_STREAMING_CLASS_TO_ROW.get(core_class, core_class)
        for name in sorted(names):
            row_name = CORE_STREAMING_METHOD_RENAMES.get(name, _snake_to_camel(name))
            if (row_class, row_name) not in declared:
                errors.append(
                    f"  {core_class}::{name}: public observability accessor on "
                    f"the core streaming surface has no `[[method]]` row "
                    f"(expected `class = \"{row_class}\"`, `name = "
                    f"\"{row_name}\"` in sdks/parity.toml). A wired-but-"
                    f"unenrolled accessor reaches none of the bindings — add "
                    f"the row and bind it on python / typescript / cpp."
                )
    return errors


# ─── Free-function (utility) discovery ──────────────────────────────
#
# The standalone utility surface — the offline Greeks calculator
# (`all_greeks` / `implied_volatility`), the conditions / exchange /
# calendar / sequence lookups (`condition_name`, `exchange_symbol`,
# `calendar_status_name`, `timestamp_ms`, `sequence_signed_to_unsigned`,
# ...), and the Python-only date-range splitter — is exposed as free
# functions / namespace functions per binding, NOT as methods on a class
# the `[[method]]` rows cover. These collectors find each binding's
# utility surface so the `[[utility]]` rows can pin the cross-binding
# roster.
#
# The TypeScript binding groups its lookup utilities as static methods on
# a `Util` namespace class (`Util.conditionName(...)`), while Python uses
# a `thetadatadx.util` submodule, C++ a `thetadatadx::util` namespace, and the C
# ABI bare `thetadatadx_*` symbols. The collectors normalise each surface to the
# bare snake_case function name so a single `[[utility]]` row matches
# every binding's idiom.


# Internal `#[pyfunction]`s that are NOT part of the public utility
# surface: decode-bench hooks and the FPSS-method introspection helper
# used by tests / external tooling. Excluded from the Python utility
# roster so they are not mistaken for untracked utilities.
PY_NON_UTILITY_PYFUNCTIONS: frozenset[str] = frozenset(
    {"decode_response_bytes", "blocked_fpss_methods"}
)


def _collect_python_utility_functions(py_src: pathlib.Path) -> set[str]:
    """Snake_case names of every public-utility `#[pyfunction]`.

    The offline calculators (`all_greeks` / `implied_volatility`), the
    `thetadatadx.util` submodule lookups, and the date-range splitter are
    all module-level `#[pyfunction] fn <name>`. The attribute may carry a
    `(...)` arg list (a `#[pyo3(...)]` sibling on the next line), so the
    regex tolerates an optional attribute body before the `fn`. Internal
    decode-bench / introspection hooks (`PY_NON_UTILITY_PYFUNCTIONS`) are
    filtered so only the user-facing utility surface remains.
    """
    out: set[str] = set()
    if not py_src.is_dir():
        return out
    fn_re = re.compile(r"#\[pyfunction\][^{}]*?fn\s+(\w+)\s*\(", re.DOTALL)
    for rs in py_src.rglob("*.rs"):
        text = rs.read_text(encoding="utf-8")
        for m in fn_re.finditer(text):
            out.add(m.group(1))
    return out - PY_NON_UTILITY_PYFUNCTIONS


def _collect_typescript_utility_functions(ts_src: pathlib.Path) -> set[str]:
    """Snake_case names of the TypeScript utility surface.

    Two shapes: the offline calculators are napi FREE functions
    (`#[napi] pub fn all_greeks`), while the conditions / exchange /
    calendar / sequence lookups are static methods on the `Util` namespace
    class (`#[napi(js_name = "conditionName")] pub fn condition_name` inside
    `impl Util`). The free-function scan below collects the former; the
    `Util`-class methods are merged in by the caller via
    `_collect_typescript_class_methods`, camelCase folded back to
    snake_case. Both surfaces normalise to the bare snake_case name so a
    single `[[utility]]` row matches Python / C++ / FFI and TypeScript
    alike.

    A napi free function is a `#[napi(...)]`-attributed `pub fn <name>`
    that is NOT inside an `impl` block. Functions inside `impl` blocks
    (methods) are excluded by blanking each `impl { ... }` body before the
    scan, so only true free functions remain here.
    """
    out: set[str] = set()
    if not ts_src.is_dir():
        return out
    impl_re = re.compile(r"impl\s+(?:[A-Za-z_][\w]*::)*[A-Za-z_][\w]*\s*\{")
    # A napi free function: the `#[napi(...)]` attribute, then any number
    # of intervening outer attributes (`#[allow(...)]`, doc comments, or a
    # trailing `// ...` line comment), then `pub fn <name>`. The generated
    # calculator carries a `#[allow(clippy::too_many_arguments)] // Reason:
    # ...` line between the napi attribute and the fn, so the gap tolerates
    # further `#[...]` / `///` / `//` runs.
    free_fn_re = re.compile(
        r"#\[napi(?:\([^)]*\))?\]\s*"
        r"(?:(?:#\[[^\]]*\]|//[^\n]*)\s*)*"
        r"(?:pub\s+)?(?:async\s+)?fn\s+([a-z_][a-z0-9_]*)\s*[(<]"
    )
    for rs in ts_src.rglob("*.rs"):
        text = rs.read_text(encoding="utf-8")
        # Blank every impl body so method declarations inside them do not
        # masquerade as free functions. Walk with a brace counter.
        cleaned = []
        i = 0
        while i < len(text):
            m = impl_re.search(text, i)
            if not m:
                cleaned.append(text[i:])
                break
            cleaned.append(text[i : m.start()])
            # Skip from the impl header's opening brace to its match.
            depth = 0
            j = m.end() - 1  # position of the `{`
            while j < len(text):
                c = text[j]
                if c == "{":
                    depth += 1
                elif c == "}":
                    depth -= 1
                    if depth == 0:
                        j += 1
                        break
                j += 1
            i = j
        body = "".join(cleaned)
        for fm in free_fn_re.finditer(body):
            out.add(fm.group(1))
    return out


def _collect_cpp_utility_functions(cpp_hpp: pathlib.Path) -> set[str]:
    """Snake_case names of free functions declared in the `thetadatadx`
    namespace of the C++ wrapper.

    The calculator declarations live in
    `sdks/cpp/include/utilities.hpp.inc`, pulled into `thetadatadx.hpp` via
    `#include "utilities.hpp.inc"`. `_expand_cpp_includes` inlines the
    `.inc` first, then a `<ret> <name>(` shape outside any `class {...}`
    body is a free function. The collector blanks class bodies (mirroring
    the TS impl-body blanking) so member functions are not counted.
    """
    out: set[str] = set()
    if not cpp_hpp.is_file():
        return out
    text = _expand_cpp_includes(cpp_hpp.read_text(encoding="utf-8"), cpp_hpp.parent)
    # Blank class / struct bodies so only namespace-scope free functions
    # remain.
    type_re = re.compile(r"\b(?:class|struct)\s+\w+[^{;]*\{")
    cleaned = []
    i = 0
    while i < len(text):
        m = type_re.search(text, i)
        if not m:
            cleaned.append(text[i:])
            break
        cleaned.append(text[i : m.start()])
        depth = 0
        j = m.end() - 1
        while j < len(text):
            c = text[j]
            if c == "{":
                depth += 1
            elif c == "}":
                depth -= 1
                if depth == 0:
                    j += 1
                    break
            j += 1
        i = j
    body = "".join(cleaned)
    # `<return type> <name>(` at namespace scope. The return type may be
    # a qualified / templated type (`std::pair<double, double>`), so match
    # the identifier immediately before the `(` and filter keywords.
    for fm in re.finditer(r"(?:^|[\s>])([a-z_][a-z0-9_]*)\s*\(", body, re.MULTILINE):
        name = fm.group(1)
        if name in {"if", "while", "for", "switch", "return", "sizeof", "throw"}:
            continue
        out.add(name)
    return out


def _collect_ffi_utility_functions(ffi_src: pathlib.Path) -> set[str]:
    """Bare calculator names whose `thetadatadx_<name>` C ABI symbol exists.

    The FFI exposes the calculators as `extern "C" fn thetadatadx_all_greeks` /
    `fn thetadatadx_implied_volatility`. The collector strips the `thetadatadx_` prefix so
    the result matches the canonical `[[utility]]` row name directly.
    """
    out: set[str] = set()
    if not ffi_src.is_dir():
        return out
    for rs in ffi_src.rglob("*.rs"):
        text = rs.read_text(encoding="utf-8")
        for m in re.finditer(r"\bfn\s+thetadatadx_(\w+)\s*\(", text):
            out.add(m.group(1))
    return out


def _check_utility_rows(
    utility_rows: list[dict[str, Any]],
    py_utils: set[str],
    ts_utils: set[str],
    cpp_utils: set[str],
    ffi_utils: set[str],
) -> list[str]:
    """Per-free-function cross-binding gate for `[[utility]]` rows.

    Each row declares a snake_case function `name` plus the expected
    presence in Python / TypeScript / C++ / the C ABI. The checker
    compares the declared state against the actual binding state and
    returns a list of mismatch strings (empty when every row matches).
    The TypeScript spelling is derived as camelCase only for the
    diagnostic; the collector already records the snake_case fn name, so
    the match is name-to-name.

    A row whose C ABI symbol carries a disambiguating prefix the
    higher-level bindings drop (the conditions table exposes the bare
    `is_cancel` on Python / TypeScript / C++ but `thetadatadx_condition_is_cancel`
    on the C ABI, where the bare `is_cancel` would be ambiguous against
    the quote-condition predicate) records the bare C-symbol name under an
    `ffi_name` key. The gate strips the `thetadatadx_` prefix off the FFI symbol
    when collecting, so `ffi_name = "condition_is_cancel"` matches
    `thetadatadx_condition_is_cancel`. Absent the override the canonical `name` is
    used for every binding.

    A row may also carry a `binding_specific` reason string. Such a row is
    NOT cross-binding by contract — it pins a function that exists on a
    strict subset of bindings on purpose (a Python-only date-range splitter,
    the C-ABI memory-management / value-folding helpers the managed
    bindings have no analogue for). The per-binding booleans are still
    asserted against the live sources, so the function cannot silently
    appear or vanish on the bindings it does / does not target; the reason
    documents WHY the asymmetry is intended.
    """
    errors: list[str] = []
    for row in utility_rows:
        name = row.get("name")
        if not name:
            errors.append(f"  [[utility]] row missing `name`: {row!r}")
            continue
        camel = _snake_to_camel(name)
        ffi_name = row.get("ffi_name", name)
        for lang, lookup_name, actual_set, hint in (
            ("python", name, py_utils, f"`#[pyfunction] fn {name}`"),
            (
                "typescript",
                name,
                ts_utils,
                f'`#[napi(js_name = "{camel}")] fn {name}`',
            ),
            (
                "cpp",
                name,
                cpp_utils,
                f"`{name}(` in the `thetadatadx::util` namespace",
            ),
            ("ffi", ffi_name, ffi_utils, f"`thetadatadx_{ffi_name}`"),
        ):
            declared = row.get(lang, False)
            actual = lookup_name in actual_set
            if declared != actual:
                verb = "missing" if declared and not actual else "unexpected"
                errors.append(
                    f"  {name}.{lang}: declared={declared}, actual={actual} "
                    f"({verb} -- expected {hint})"
                )
    return errors


def _is_ts_internal_free_fn(name: str) -> bool:
    """True for a TypeScript napi free function that is serialization /
    coercion plumbing, not a user-facing utility.

    The JS shim emits a `<tick>_tick_to_arrow_ipc` free function per tick
    type for the zero-copy Arrow boundary, plus small numeric-coercion
    helpers (`bigint_to_i32`). These are not part of the standalone
    utility roster the `[[utility]]` rows track, so they are excluded from
    the TypeScript utility surface.
    """
    return name.endswith("_to_arrow_ipc") or name == "bigint_to_i32"


def _ts_utility_surface(
    ts_free_fns: set[str], ts_class_methods: dict[str, set[str]]
) -> set[str]:
    """The TypeScript standalone-utility surface as bare snake_case names.

    Merges the user-facing napi free functions (the offline calculators)
    with the `Util` namespace-class static methods (the conditions /
    exchange / calendar / sequence lookups), folding the camelCase `Util`
    method spellings back to snake_case so both shapes compare against the
    same `[[utility]]` row name. Internal serialization / coercion free
    functions (`_is_ts_internal_free_fn`) are filtered.
    """
    surface = {fn for fn in ts_free_fns if not _is_ts_internal_free_fn(fn)}
    for camel in ts_class_methods.get("Util", set()):
        surface.add(_camel_to_snake(camel))
    return surface


def _check_utility_roster_complete(
    utility_rows: list[dict[str, Any]],
    py_utils: set[str],
    ts_utils: set[str],
) -> list[str]:
    """Reverse-direction orphan check for the standalone-utility roster.

    `_check_utility_rows` verifies every declared row resolves on the
    bindings it claims. This complementary direction catches a utility
    that exists on a binding but has NO `[[utility]]` row at all — the
    `calendar_status_name` / `timestamp_ms` defect class where a util
    shipped on one binding and silently never made it into the matrix on
    the others.

    The orphan scan runs over the two bindings whose utility surface is
    precisely enumerable: the Python public `#[pyfunction]` set (internal
    decode-bench / introspection hooks already filtered) and the
    TypeScript utility surface (napi free functions + `Util` namespace
    methods). Every name in those surfaces must be a declared row's
    canonical `name`. The C++ `thetadatadx::util` / C ABI `thetadatadx_*` surfaces are
    pinned forward per row (and the C ABI additionally by
    `check_c_abi_completeness`); they are not enumerable cleanly here
    because the namespace mingles the lookups with dozens of unrelated
    fluent accessors and arrow-conversion symbols.
    """
    errors: list[str] = []
    declared_managed = {row["name"] for row in utility_rows if row.get("name")}
    for lang, seen in (
        ("python", py_utils),
        ("typescript", ts_utils),
    ):
        for fn in sorted(seen - declared_managed):
            errors.append(
                f"  {fn} ({lang}): standalone utility has no [[utility]] "
                f"row. Add one declaring its per-binding presence so the "
                f"roster stays tracked (use `ffi_name` if the C ABI symbol "
                f"carries a disambiguating prefix, or `binding_specific` if "
                f"the function is intentionally not cross-binding)."
            )
    return errors


# ─── Subscription-kind label discovery ──────────────────────────────
#
# The FPSS subscription-kind enum stringifies to a fixed snake_case label
# set that every binding surfaces (the C ABI `thetadatadx_*_active_subscriptions`
# `kind` field, the C++ `FluentSubscription::kind_string`, the Python /
# TypeScript `Subscription.kind` accessors). The label is the stable
# cross-binding contract — a quant filtering `sub.kind == "open_interest"`
# in Python must get the same string the C++ `kind_string()` returns. A
# binding that drifts onto the enum's PascalCase `Debug` spelling, or
# invents a label outside the canonical set (the `full_quote` /
# `full_market_value` C++ defect class — full-stream Quote / MarketValue
# do not exist on the wire, so a label for them is fictitious), breaks the
# contract. These collectors harvest the literal strings each binding
# emits so the set can be asserted equal to the canonical roster.


# The canonical snake_case subscription-kind label set. Per-contract
# subscriptions carry the bare kind (`quote` / `trade` / `open_interest` /
# `market_value`); full-stream subscriptions carry the `full_` prefix and
# exist only for trade + open-interest (the FPSS wire has no full-stream
# quote or market-value broadcast). This is the single roster every
# binding must emit.
CANONICAL_SUBSCRIPTION_KINDS: frozenset[str] = frozenset(
    {
        "quote",
        "trade",
        "open_interest",
        "market_value",
        "full_trades",
        "full_open_interest",
    }
)

SUBSCRIPTION_RS = (
    REPO_ROOT / "crates" / "thetadatadx" / "src" / "fpss" / "protocol" / "subscription.rs"
)
PY_FLUENT_RS = REPO_ROOT / "sdks" / "python" / "src" / "fluent.rs"
TS_FLUENT_RS = REPO_ROOT / "sdks" / "typescript" / "src" / "fluent.rs"


# A snake_case string literal that is one of the canonical kind labels OR
# the `full_<x>` shape (so a binding inventing `full_quote` is captured
# and then flagged against the canonical set rather than silently passing
# the harvest filter).
_KIND_LITERAL_RE = re.compile(r'"((?:full_)?[a-z]+(?:_[a-z]+)*)"')
_KIND_VOCAB: frozenset[str] = CANONICAL_SUBSCRIPTION_KINDS | frozenset(
    {"full_quote", "full_market_value"}
)


def _harvest_kind_labels(text: str, anchor_substrings: tuple[str, ...]) -> set[str]:
    """Collect kind-label string literals that appear on a line near one
    of the `match`-arm `anchor_substrings`.

    The kind accessors stringify by matching the enum and returning a
    literal per arm; the canonical labels (and the two fictitious
    `full_*` spellings the gate guards against) are the only snake_case
    string literals in those arm bodies. Scanning the whole accessor body
    rather than parsing the match keeps the collector resilient to the
    per-binding wrapper differences (pyo3 `#[getter]`, napi `#[napi(getter)]`,
    a Rust `&'static str` return) while still pinning the emitted set.
    """
    out: set[str] = set()
    for literal in _KIND_LITERAL_RE.findall(text):
        if literal in _KIND_VOCAB:
            out.add(literal)
    # `anchor_substrings` documents intent (the arms a reader expects to
    # carry the labels) and guards against an empty harvest from a file
    # the layout drifted out from under — if not one anchor is present,
    # the caller's source no longer matches the contract.
    return out if any(a in text for a in anchor_substrings) else out


def _collect_rust_subscription_kinds(subscription_rs: pathlib.Path) -> set[str]:
    """Canonical kind labels emitted by the Rust core SSOT.

    Harvests every canonical-vocabulary string literal in
    `subscription.rs`, where `SubscriptionKind::kind_str`,
    `SubscriptionKind::full_kind_str`, and `FullSubscriptionKind::kind_str`
    define the labels the whole stack reads.
    """
    if not subscription_rs.is_file():
        return set()
    return _harvest_kind_labels(
        subscription_rs.read_text(encoding="utf-8"),
        ("fn kind_str", "fn full_kind_str"),
    )


def _collect_binding_subscription_kinds(fluent_rs: pathlib.Path) -> set[str]:
    """Kind labels emitted by a Python / TypeScript `Subscription.kind`
    accessor in `fluent.rs`. Both bindings stringify the same way (a match
    on the inner protocol enum returning a literal per arm); the harvest
    is mechanism-agnostic.
    """
    if not fluent_rs.is_file():
        return set()
    return _harvest_kind_labels(
        fluent_rs.read_text(encoding="utf-8"),
        ("fn kind", "SubscriptionKind"),
    )


def _collect_cpp_subscription_kinds(cpp_hpp: pathlib.Path) -> set[str]:
    """Kind labels emitted by the C++ `FluentSubscription::kind_string`
    switch in `thetadatadx.hpp`. The method is the only place in the header
    that returns these snake_case labels, so a header-wide harvest of the
    canonical vocabulary captures exactly its emitted set (and any
    fictitious `full_*` label, which the canonical-set assertion then
    flags).
    """
    if not cpp_hpp.is_file():
        return set()
    text = cpp_hpp.read_text(encoding="utf-8")
    # Bound the harvest to the `kind_string()` body so an unrelated label
    # string elsewhere in the header cannot mask a divergence inside the
    # accessor.
    m = re.search(r"std::string\s+kind_string\s*\(\s*\)\s*const\s*\{", text)
    if not m:
        return set()
    body_start = m.end()
    depth = 1
    i = body_start
    while i < len(text) and depth > 0:
        c = text[i]
        if c == "{":
            depth += 1
        elif c == "}":
            depth -= 1
        i += 1
    body = text[body_start : i - 1]
    return {lit for lit in _KIND_LITERAL_RE.findall(body) if lit in _KIND_VOCAB}


def _collect_ffi_subscription_kinds(cpp_h: pathlib.Path) -> set[str]:
    """Kind labels documented as the C ABI contract in `thetadatadx.h`.

    The C ABI surfaces the kind as the `ThetaDataDxSubscription.kind` string field,
    populated by the Rust core's `kind_str` / `full_kind_str` (so the C ABI
    emits exactly the Rust set at runtime). The header documents the
    canonical label set in the `ThetaDataDxSubscription` doc comment; harvesting
    those literals pins the documented C contract against the same roster
    the runtime emits, so a header that drops a label (or documents a
    fictitious one) is caught.
    """
    if not cpp_h.is_file():
        return set()
    text = cpp_h.read_text(encoding="utf-8")
    # The kind label vocabulary appears in the `ThetaDataDxSubscription` struct
    # doc comment. Restrict the harvest to the lines mentioning the field
    # so unrelated snake_case literals in the header are not swept in.
    out: set[str] = set()
    for line in text.splitlines():
        if "kind" in line.lower() and ('"' in line or "full_" in line):
            for lit in _KIND_LITERAL_RE.findall(line):
                if lit in _KIND_VOCAB:
                    out.add(lit)
    return out


def _check_subscription_kind_parity(
    rust_kinds: set[str],
    py_kinds: set[str],
    ts_kinds: set[str],
    cpp_kinds: set[str],
    ffi_kinds: set[str],
    canonical: frozenset[str] = CANONICAL_SUBSCRIPTION_KINDS,
) -> list[str]:
    """Assert every binding emits exactly the canonical kind-label set.

    Each binding's harvested label set must equal `canonical`. A binding
    short of a label has dropped a kind (the C-ABI-collision class where a
    label silently differs); a binding with an extra label has invented a
    non-canonical string (the C++ `full_quote` / `full_market_value`
    class). Both directions fail the gate.
    """
    errors: list[str] = []
    for lang, emitted in (
        ("rust", rust_kinds),
        ("python", py_kinds),
        ("typescript", ts_kinds),
        ("cpp", cpp_kinds),
        ("ffi", ffi_kinds),
    ):
        missing = canonical - emitted
        extra = emitted - canonical
        if missing:
            errors.append(
                f"  {lang}: missing kind label(s) {sorted(missing)} — the "
                f"binding does not emit the full canonical set "
                f"{sorted(canonical)}."
            )
        if extra:
            errors.append(
                f"  {lang}: emits non-canonical kind label(s) {sorted(extra)} "
                f"— only {sorted(canonical)} are valid cross-binding kind "
                f"strings (full-stream exists for trade + open-interest only)."
            )
    return errors


# ─── Error-leaf mapping discovery ────────────────────────────────────
#
# Each core `thetadatadx::Error` variant maps to one leaf class on every
# binding (`InvalidCredentialsError`, `RateLimitError`, ...) and one
# `THETADATADX_ERR_*` integer code on the C ABI. The leaf vocabulary is the
# cross-binding contract: a caller porting an `except InvalidParameterError`
# clause from Python to a `catch (InvalidParameterError&)` in C++ must
# catch the same conditions. The Python `to_py_err`, the TypeScript
# `leaf_class_for`, the C++ `throw_for_code`, and the C ABI `error_code_for`
# all hand-write the same mapping; these collectors harvest each binding's
# leaf-class roster (and the C ABI code roster) so the sets can be asserted
# identical — the `FlatFilesUnavailable` / `PartialReconnect` (invisible on
# Py / TS) and `ConfigError` (missing leaf) defect class.


# The canonical leaf-class roster. Every binding's error dispatch must
# resolve to exactly this set of leaf classes (the root `ThetaDataError`
# included — it is the `#[non_exhaustive]` catch-all every binding routes
# unknown future variants to).
CANONICAL_ERROR_LEAVES: frozenset[str] = frozenset(
    {
        "ThetaDataError",
        "AuthenticationError",
        "InvalidCredentialsError",
        "SubscriptionError",
        "RateLimitError",
        "InvalidParameterError",
        "SchemaMismatchError",
        "NetworkError",
        "UnavailableError",
        "DeadlineExceededError",
        "NotFoundError",
        "StreamError",
        "ConfigError",
    }
)

# The canonical `THETADATADX_ERR_*` code roster mapped to its integer value. The C
# ABI surfaces these via `thetadatadx_last_error_code`; the higher bindings
# dispatch on them. `THETADATADX_ERR_NONE` (0) is the no-error sentinel, present in
# the header but not a leaf class, so the leaf-to-code correspondence skips
# it.
CANONICAL_ERROR_CODES: dict[str, int] = {
    "THETADATADX_ERR_NONE": 0,
    "THETADATADX_ERR_OTHER": 1,
    "THETADATADX_ERR_AUTHENTICATION": 2,
    "THETADATADX_ERR_INVALID_CREDENTIALS": 3,
    "THETADATADX_ERR_SUBSCRIPTION": 4,
    "THETADATADX_ERR_RATE_LIMIT": 5,
    "THETADATADX_ERR_NOT_FOUND": 6,
    "THETADATADX_ERR_DEADLINE_EXCEEDED": 7,
    "THETADATADX_ERR_UNAVAILABLE": 8,
    "THETADATADX_ERR_NETWORK": 9,
    "THETADATADX_ERR_SCHEMA_MISMATCH": 10,
    "THETADATADX_ERR_STREAM": 11,
    "THETADATADX_ERR_CONFIG": 12,
    "THETADATADX_ERR_INVALID_PARAMETER": 13,
}

PY_ERRORS_RS = REPO_ROOT / "sdks" / "python" / "src" / "errors.rs"
TS_LIB_RS = REPO_ROOT / "sdks" / "typescript" / "src" / "lib.rs"
FFI_ERROR_RS = REPO_ROOT / "ffi" / "src" / "error.rs"

# A class name ending in `Error` is a candidate leaf. The fixed roster
# filters harvested identifiers to the canonical leaves so a stray
# `Error`-suffixed local (`join_err`, a doc-comment word) is never counted.
_LEAF_RE = re.compile(r"\b([A-Z][A-Za-z0-9]*Error)\b")


def _collect_python_error_leaves(py_errors_rs: pathlib.Path) -> set[str]:
    """Leaf classes the Python `to_py_err` dispatch resolves to.

    Bounds the harvest to the `fn to_py_err` body so the exception-class
    *definitions* (`create_exception!`) and the back-compat alias
    registrations do not inflate the dispatch roster — the gate asserts
    the set the dispatch actually routes to, which is the user-observable
    contract.
    """
    if not py_errors_rs.is_file():
        return set()
    text = py_errors_rs.read_text(encoding="utf-8")
    m = re.search(r"pub fn to_py_err\s*\([^)]*\)\s*->\s*PyErr\s*\{", text)
    if not m:
        return set()
    body = _balanced_body(text, m.end())
    # The dispatch builds each leaf as `<Class>::new_err(...)`; the
    # rate-limit arm routes through the `rate_limit_err` helper which
    # builds `RateLimitError`. Harvest both shapes.
    leaves = {
        leaf for leaf in _LEAF_RE.findall(body) if leaf in CANONICAL_ERROR_LEAVES
    }
    if "rate_limit_err" in body:
        leaves.add("RateLimitError")
    return leaves


def _collect_typescript_error_leaves(ts_lib_rs: pathlib.Path) -> set[str]:
    """Leaf-class strings the TypeScript `leaf_class_for` dispatch returns.

    Bounds the harvest to the `fn leaf_class_for` body so only the strings
    the dispatch emits are counted.
    """
    if not ts_lib_rs.is_file():
        return set()
    text = ts_lib_rs.read_text(encoding="utf-8")
    m = re.search(r"fn leaf_class_for\s*\([^)]*\)\s*->\s*&'static str\s*\{", text)
    if not m:
        return set()
    body = _balanced_body(text, m.end())
    return {
        lit
        for lit in re.findall(r'"([A-Z][A-Za-z0-9]*Error)"', body)
        if lit in CANONICAL_ERROR_LEAVES
    }


def _collect_cpp_error_leaves(cpp_hpp: pathlib.Path) -> set[str]:
    """Leaf classes the C++ `throw_for_code` dispatch can throw.

    Bounds the harvest to the `throw_for_code` body and collects every
    `throw <Class>(...)` target.
    """
    if not cpp_hpp.is_file():
        return set()
    text = cpp_hpp.read_text(encoding="utf-8")
    m = re.search(r"void\s+throw_for_code\s*\([^)]*\)\s*\{", text)
    if not m:
        return set()
    body = _balanced_body(text, m.end())
    return {
        cls
        for cls in re.findall(r"throw\s+([A-Z][A-Za-z0-9]*Error)\s*\(", body)
        if cls in CANONICAL_ERROR_LEAVES
    }


def _collect_ffi_error_codes(ffi_error_rs: pathlib.Path) -> dict[str, int]:
    """`THETADATADX_ERR_*` discriminants defined in the FFI `error.rs`.

    Returns `{code_name: int_value}` for every `pub const THETADATADX_ERR_* : i32 =
    N;` declaration — the source of truth for the C ABI error codes.
    """
    if not ffi_error_rs.is_file():
        return {}
    text = ffi_error_rs.read_text(encoding="utf-8")
    out: dict[str, int] = {}
    for name, value in re.findall(
        r"pub const (THETADATADX_ERR_\w+)\s*:\s*i32\s*=\s*(\d+)\s*;", text
    ):
        out[name] = int(value)
    return out


def _collect_ffi_error_codes_dispatched(ffi_error_rs: pathlib.Path) -> set[str]:
    """`THETADATADX_ERR_*` codes the FFI `error_code_for` dispatch actually returns.

    Bounds the harvest to the `fn error_code_for` body so the roster is the
    set the dispatch routes to (not merely the defined constants).
    """
    if not ffi_error_rs.is_file():
        return set()
    text = ffi_error_rs.read_text(encoding="utf-8")
    m = re.search(r"fn error_code_for\s*\([^)]*\)\s*->\s*i32\s*\{", text)
    if not m:
        return set()
    body = _balanced_body(text, m.end())
    return set(re.findall(r"\b(THETADATADX_ERR_\w+)\b", body))


def _collect_cpp_error_codes(cpp_h: pathlib.Path) -> dict[str, int]:
    """`THETADATADX_ERR_*` codes defined in the C ABI header `thetadatadx.h`.

    Returns `{code_name: int_value}` for every `#define THETADATADX_ERR_* N`. The
    header is hand-maintained; the gate asserts it matches the FFI Rust
    constants exactly so a code that drifts on the C side (invisible to
    `cargo build`) is caught.
    """
    if not cpp_h.is_file():
        return {}
    text = cpp_h.read_text(encoding="utf-8")
    out: dict[str, int] = {}
    for name, value in re.findall(r"#define\s+(THETADATADX_ERR_\w+)\s+(\d+)\b", text):
        out[name] = int(value)
    return out


def _check_error_leaf_parity(
    py_leaves: set[str],
    ts_leaves: set[str],
    cpp_leaves: set[str],
    ffi_codes: dict[str, int],
    ffi_codes_dispatched: set[str],
    cpp_codes: dict[str, int],
    canonical_leaves: frozenset[str] = CANONICAL_ERROR_LEAVES,
    canonical_codes: dict[str, int] | None = None,
) -> list[str]:
    """Assert the error-leaf mapping is symmetric across all bindings.

    Four invariants:

    1. The Python / TypeScript / C++ leaf-class rosters each equal the
       canonical leaf set (so a variant invisible on one binding — the
       `FlatFilesUnavailable` / `PartialReconnect` defect — is caught, as
       is a missing `ConfigError` leaf).
    2. The FFI `THETADATADX_ERR_*` constants equal the canonical code table
       (name → value), so a renumbered or renamed code trips.
    3. The C ABI header `#define`s match the FFI Rust constants exactly,
       so a hand-maintained-header drift (invisible to `cargo build`)
       trips.
    4. Every dispatched FFI code is defined, and every leaf class has a
       corresponding `THETADATADX_ERR_*` code, so the leaf set and the code set
       stay in one-to-one correspondence.
    """
    if canonical_codes is None:
        canonical_codes = CANONICAL_ERROR_CODES
    errors: list[str] = []

    for lang, leaves in (
        ("python", py_leaves),
        ("typescript", ts_leaves),
        ("cpp", cpp_leaves),
    ):
        missing = canonical_leaves - leaves
        extra = leaves - canonical_leaves
        if missing:
            errors.append(
                f"  {lang}: error dispatch never routes to leaf class(es) "
                f"{sorted(missing)} — a core Error variant maps to a class "
                f"the other bindings expose but this one does not."
            )
        if extra:
            errors.append(
                f"  {lang}: error dispatch routes to non-canonical leaf "
                f"class(es) {sorted(extra)} — add them to the canonical "
                f"roster (and the other bindings) or remove the divergence."
            )

    # FFI Rust constant table must equal the canonical code table.
    if ffi_codes and ffi_codes != canonical_codes:
        for name, value in sorted(canonical_codes.items()):
            if name not in ffi_codes:
                errors.append(f"  ffi: `{name}` is not defined in ffi/src/error.rs")
            elif ffi_codes[name] != value:
                errors.append(
                    f"  ffi: `{name}` = {ffi_codes[name]} in ffi/src/error.rs, "
                    f"canonical is {value}"
                )
        for name in sorted(set(ffi_codes) - set(canonical_codes)):
            errors.append(
                f"  ffi: `{name}` = {ffi_codes[name]} is not in the canonical "
                f"code table — add it to CANONICAL_ERROR_CODES (and every "
                f"binding's dispatch) or remove it."
            )

    # C ABI header must match the FFI Rust constants exactly.
    if ffi_codes and cpp_codes and ffi_codes != cpp_codes:
        for name, value in sorted(ffi_codes.items()):
            if name not in cpp_codes:
                errors.append(
                    f"  cpp header: `{name}` defined in ffi/src/error.rs but "
                    f"missing from sdks/cpp/include/thetadatadx.h"
                )
            elif cpp_codes[name] != value:
                errors.append(
                    f"  cpp header: `#define {name} {cpp_codes[name]}` disagrees "
                    f"with the FFI constant value {value}"
                )
        for name in sorted(set(cpp_codes) - set(ffi_codes)):
            errors.append(
                f"  cpp header: `#define {name} {cpp_codes[name]}` has no FFI "
                f"constant — drop it or add the Rust constant."
            )

    # Every dispatched FFI code must be defined.
    if ffi_codes_dispatched:
        for code in sorted(ffi_codes_dispatched - set(ffi_codes)):
            errors.append(
                f"  ffi: `error_code_for` returns `{code}` but it is not a "
                f"defined `pub const`."
            )

    return errors


def _balanced_body(text: str, body_start: int) -> str:
    """Return the substring from `body_start` to the matching close brace.

    `body_start` must be the index immediately after the opening `{` of the
    block. Walks a depth counter to the balancing `}` and returns the body
    between (exclusive of the closing brace). Shared by the dispatch-body
    harvesters so each one pins its scan to a single function body.
    """
    depth = 1
    i = body_start
    while i < len(text) and depth > 0:
        c = text[i]
        if c == "{":
            depth += 1
        elif c == "}":
            depth -= 1
        i += 1
    return text[body_start : i - 1]


# ─── Historical server-stream surface discovery ─────────────────────
#
# The endpoint codegen casts an endpoint's snake_case name to PascalCase
# / camelCase with INITIALISM awareness: the segments `eod` / `ohlc` /
# `iv` / `dte` / `nbbo` render as all-caps (`EOD`, `OHLC`, ...) in the
# TypeScript `js_name` (`stockHistoryEODStream`) but as title-case in the
# Python builder struct (`StockHistoryEodBuilder`). A naive
# `camelCase → snake_case` inverse would split `EOD` into `e_o_d`. The
# helper below collapses any run of consecutive uppercase letters into a
# single segment, so both `stockHistoryEOD` and `StockHistoryEod` invert
# to the canonical `stock_history_eod` row name.


def _endpoint_method_to_snake(name: str) -> str:
    """Invert an endpoint method / builder stem to its snake_case name,
    collapsing initialism runs (`EOD`, `OHLC`) into one segment.

    `stockHistoryEOD` -> `stock_history_eod`;
    `StockHistoryEod` -> `stock_history_eod`;
    `optionHistoryTradeGreeksImpliedVolatility` ->
    `option_history_trade_greeks_implied_volatility`.
    """
    # Boundary BEFORE an uppercase run that is followed by a lowercase
    # (start of a new title-case word): `...EODStream` keeps `EOD`
    # together but splits before `Stream`'s `S...tream`.
    s = re.sub(r"(?<=[a-z0-9])([A-Z])", r"_\1", name)
    s = re.sub(r"([A-Z]+)([A-Z][a-z])", r"\1_\2", s)
    return s.lower()

#
# The buffered historical endpoints have a server-stream companion on
# every binding — the `.stream(handler)` core primitive surfaced as a
# per-binding terminal:
#
#   * Python: `fn stream` + `fn stream_async` on each `<Endpoint>Builder`
#     pyclass (generated into
#     `sdks/python/src/_generated/historical_methods.rs`).
#   * TypeScript: a `<endpoint>Stream` method on the `Client`
#     napi class (generated into
#     `sdks/typescript/src/_generated/historical_methods.rs`).
#   * C ABI: a `thetadatadx_<endpoint>_stream` extern "C" symbol in `ffi/src/`.
#   * C++: an `<endpoint>_stream` member on the `Client` wrapper
#     (`thetadatadx.hpp` + its `.inc` fragments).
#
# These methods live on per-endpoint builders / as endpoint-named
# methods, NOT on a class the `[[method]]` rows already cover, so without
# this dedicated family a binding could ship streaming on some endpoints
# and silently omit it on others (or on a whole binding) with no checker
# noticing — the exact gap the cross-binding contract exists to close.
# Each `[[historical_streaming]]` row pins one endpoint's streaming
# presence across the four bindings.


def _collect_python_streaming_endpoints(py_src: pathlib.Path) -> set[str]:
    """Snake_case endpoint names whose Python `<Endpoint>Builder` pyclass
    exposes a `fn stream` terminal.

    Walks every `impl <Name>Builder { ... }` block and records the
    builder's endpoint name (the CamelCase struct stem, lowered to
    snake_case) when the body declares `fn stream(`. The async companion
    `fn stream_async` rides on the same builder, so the sync terminal is
    the canonical presence signal.
    """
    out: set[str] = set()
    if not py_src.is_dir():
        return out
    impl_re = re.compile(r"impl\s+(\w+)Builder\s*\{")
    for rs in py_src.rglob("*.rs"):
        text = rs.read_text(encoding="utf-8")
        for header in impl_re.finditer(text):
            stem = header.group(1)
            body_start = header.end()
            depth = 1
            i = body_start
            while i < len(text) and depth > 0:
                c = text[i]
                if c == "{":
                    depth += 1
                elif c == "}":
                    depth -= 1
                i += 1
            body = text[body_start : i - 1]
            if re.search(r"\bfn\s+stream\s*\(", body):
                out.add(_endpoint_method_to_snake(stem))
    return out


def _collect_typescript_streaming_endpoints(
    ts_methods: dict[str, set[str]],
) -> set[str]:
    """Snake_case endpoint names whose `HistoricalView` napi class
    exposes a `<endpoint>Stream` method.

    The server-stream companions live on the `client.historical`
    `HistoricalView` view alongside the buffered historical queries.
    Reuses the already-collected `{class: {method, ...}}` map. A method
    whose camelCase name ends in `Stream` is a historical server-stream
    terminal; strip the suffix and lower to snake_case to recover the
    endpoint name. The FPSS lifecycle methods (`startStreaming` /
    `stopStreaming` / `isStreaming`) do NOT end in the bare `Stream`
    token preceded by an endpoint stem — they are excluded because
    stripping `Stream` would leave `starting` / `stopping` / `is`, none
    of which name an endpoint (and they are tracked by their own
    `[[method]]` rows regardless).
    """
    out: set[str] = set()
    methods = ts_methods.get("HistoricalView", set())
    lifecycle = {"startStreaming", "stopStreaming", "isStreaming"}
    for method in methods:
        if method in lifecycle:
            continue
        if method.endswith("Stream") and len(method) > len("Stream"):
            stem = method[: -len("Stream")]
            out.add(_endpoint_method_to_snake(stem))
    return out


def _collect_ffi_streaming_endpoints(ffi_src: pathlib.Path) -> set[str]:
    """Snake_case endpoint names whose `thetadatadx_<endpoint>_stream` extern "C"
    symbol exists in `ffi/src/`.

    The `thetadatadx_client_*` / `thetadatadx_streaming_*` callback symbols never match
    the `thetadatadx_<name>_stream` shape (their stems are `client` / `streaming`
    and they end in `set_callback` / `reconnect` / `shutdown`, not
    `_stream`), so they are not mistaken for a historical endpoint.
    """
    out: set[str] = set()
    if not ffi_src.is_dir():
        return out
    fn_re = re.compile(r"\bfn\s+thetadatadx_(\w+)_stream\s*\(")
    for rs in ffi_src.rglob("*.rs"):
        text = rs.read_text(encoding="utf-8")
        for m in fn_re.finditer(text):
            out.add(m.group(1))
    return out


def _collect_cpp_streaming_endpoints(cpp_methods: dict[str, set[str]]) -> set[str]:
    """Snake_case endpoint names whose C++ `Historical` view exposes an
    `<endpoint>_stream` member.

    Reuses the already-collected C++ `{class: {method, ...}}` map. The
    server-stream companions live on the `client.historical()`
    `Historical` view body in `thetadatadx.hpp`. A member whose snake_case
    name ends in `_stream` is a server-stream terminal; strip the suffix
    to recover the endpoint name.
    """
    out: set[str] = set()
    methods = cpp_methods.get(_cpp_class_for("HistoricalView"), set())
    for method in methods:
        if method.endswith("_stream") and len(method) > len("_stream"):
            out.add(method[: -len("_stream")])
    return out


def _check_historical_streaming_rows(
    rows: list[dict[str, Any]],
    rust_stream: set[str],
    py_stream: set[str],
    ts_stream: set[str],
    cpp_stream: set[str],
    ffi_stream: set[str],
) -> list[str]:
    """Per-endpoint cross-binding gate for `[[historical_streaming]]` rows.

    Each row declares a snake_case endpoint `name` plus the expected
    server-stream presence on Rust / Python / TypeScript / C++ / the C ABI.
    The checker compares the declared state against the actual surface state
    and returns a list of mismatch strings (empty when every row matches).
    The Rust column is the source of truth — the `<Endpoint>Builder::stream`
    terminal the registry generates and every binding mirrors; a dropped or
    renamed Rust streaming endpoint trips here even if a binding still
    declares it.

    Beyond the per-row check, the collected sets are reconciled against
    the union of declared row names: an endpoint that streams on ANY
    surface but has no row at all trips the gate, so a newly-streamed
    endpoint cannot slip in untracked.
    """
    errors: list[str] = []
    declared_names = {row.get("name") for row in rows if row.get("name")}
    for row in rows:
        name = row.get("name")
        if not name:
            errors.append(f"  [[historical_streaming]] row missing `name`: {row!r}")
            continue
        camel = _snake_to_camel(name)
        pascal = camel[:1].upper() + camel[1:] if camel else camel
        for lang, actual_set, hint in (
            ("rust", rust_stream, f"`{pascal}Builder::stream` terminal (registry of record)"),
            ("python", py_stream, f"`fn stream` on the `{pascal}Builder` pyclass"),
            ("typescript", ts_stream, f"`{camel}Stream` on the `Client` napi class"),
            ("cpp", cpp_stream, f"`{name}_stream(` on the C++ `Client` body"),
            ("ffi", ffi_stream, f"`thetadatadx_{name}_stream` extern \"C\" symbol"),
        ):
            declared = row.get(lang, False)
            actual = name in actual_set
            if declared != actual:
                verb = "missing" if declared and not actual else "unexpected"
                errors.append(
                    f"  {name}.{lang}: declared={declared}, actual={actual} "
                    f"({verb} -- expected {hint})"
                )
    # Reverse-direction orphan check: any endpoint that streams on a
    # surface but has no row is undocumented drift.
    seen = rust_stream | py_stream | ts_stream | cpp_stream | ffi_stream
    for endpoint in sorted(seen - declared_names):
        on = sorted(
            lang
            for lang, s in (
                ("rust", rust_stream),
                ("python", py_stream),
                ("typescript", ts_stream),
                ("cpp", cpp_stream),
                ("ffi", ffi_stream),
            )
            if endpoint in s
        )
        errors.append(
            f"  {endpoint}: streams on {on} but has no "
            f"[[historical_streaming]] row. Add one declaring its "
            f"per-binding presence so the surface stays tracked."
        )
    return errors


# ─── Historical async query surface ([[historical_async]]) ────────────
#
# Every buffered historical endpoint carries a non-blocking query
# companion so callers can run a request off the calling thread without
# managing their own threads. The shape is per-binding idiom:
#
#   * Python: an `<endpoint>_async` method on the historical surface,
#     returning an awaitable (generated into
#     `sdks/python/src/_generated/historical_methods.rs`).
#   * TypeScript: the buffered `<endpoint>` method is itself `async` and
#     returns a `Promise`, so there is no separate `_async` name — the
#     presence of the buffered endpoint method on `HistoricalView` IS the
#     async surface.
#   * C++: an inline `<endpoint>_async` member on the `Historical` view
#     returning `std::future<std::vector<Row>>` over the blocking member.
#
# There is no C ABI row: the async surface is a binding-layer concern
# layered over the existing blocking `thetadatadx_<endpoint>_with_options`
# symbols. C has no awaitable type and its idiom is callback / poll, so
# the C ABI stays blocking-only by design and is not tracked here.
#
# Like the streaming family, these terminals are endpoint-named methods
# NOT covered by the `[[method]]` rows, so without this family a binding
# could ship the async query on some endpoints and silently omit it on
# others (or on a whole binding) with no checker noticing.


def _collect_python_async_endpoints(py_src: pathlib.Path) -> set[str]:
    """Snake_case endpoint names whose Python `<Endpoint>Builder` pyclass
    exposes a buffered `list_async` terminal.

    The Python async query surface is the awaitable `list_async()` terminal
    on each buffered endpoint's `<Endpoint>Builder` — the async twin of the
    blocking `list()` collect. It rides on the same builder the blocking
    query returns, so the builder's endpoint name (the CamelCase struct
    stem, lowered to snake_case) is the async-query presence signal. The
    server-stream `stream_async` terminal is a different surface (tracked by
    the `[[historical_streaming]]` family) and is not matched here.
    """
    out: set[str] = set()
    if not py_src.is_dir():
        return out
    impl_re = re.compile(r"impl\s+(\w+)Builder\s*\{")
    for rs in py_src.rglob("*.rs"):
        text = rs.read_text(encoding="utf-8")
        for header in impl_re.finditer(text):
            stem = header.group(1)
            body_start = header.end()
            depth = 1
            i = body_start
            while i < len(text) and depth > 0:
                c = text[i]
                if c == "{":
                    depth += 1
                elif c == "}":
                    depth -= 1
                i += 1
            body = text[body_start : i - 1]
            # The terminal carries a `<'py>` lifetime generic between the
            # name and the arg list (`fn list_async<'py>(`), so allow an
            # optional generic-parameter clause before the paren.
            if re.search(r"\bfn\s+list_async\s*(<[^>]*>)?\s*\(", body):
                out.add(_endpoint_method_to_snake(stem))
    return out


def _collect_typescript_async_endpoints(
    ts_methods: dict[str, set[str]],
) -> set[str]:
    """Snake_case endpoint names whose `HistoricalView` napi class exposes a
    buffered `<endpoint>` query method.

    Every buffered TypeScript data method is an `async fn` returning a
    `Promise`, so the buffered endpoint method IS the async surface — there
    is no separate `_async` spelling. Reuses the already-collected
    `{class: {method, ...}}` map: take the `HistoricalView` methods, drop
    the `<endpoint>Stream` server-stream companions and the FPSS lifecycle
    methods, and snake-ify the remainder to recover the endpoint names.
    """
    out: set[str] = set()
    methods = ts_methods.get("HistoricalView", set())
    lifecycle = {"startStreaming", "stopStreaming", "isStreaming"}
    for method in methods:
        if method in lifecycle:
            continue
        if method.endswith("Stream") and len(method) > len("Stream"):
            continue
        out.add(_endpoint_method_to_snake(method))
    return out


def _collect_cpp_async_endpoints(cpp_methods: dict[str, set[str]]) -> set[str]:
    """Snake_case endpoint names whose C++ `Historical` view exposes an
    `<endpoint>_async` member.

    Reuses the already-collected C++ `{class: {method, ...}}` map. A member
    whose snake_case name ends in `_async` is a non-blocking query
    companion; strip the suffix to recover the endpoint name.
    """
    out: set[str] = set()
    methods = cpp_methods.get(_cpp_class_for("HistoricalView"), set())
    for method in methods:
        if method.endswith("_async") and len(method) > len("_async"):
            out.add(method[: -len("_async")])
    return out


def _check_historical_async_rows(
    rows: list[dict[str, Any]],
    rust_async: set[str],
    py_async: set[str],
    ts_async: set[str],
    cpp_async: set[str],
) -> list[str]:
    """Per-endpoint cross-binding gate for `[[historical_async]]` rows.

    Each row declares a snake_case endpoint `name` plus the expected async
    query presence on Rust / Python / TypeScript / C++. The checker compares
    the declared state against the actual surface state and returns a list of
    mismatch strings (empty when every row matches). The Rust column is the
    source of truth: every buffered endpoint in the registry carries a
    `HistoricalClient::<name>` async query method (the builder-await /
    `list_async` twin of the blocking collect), so a dropped or renamed Rust
    endpoint trips here even if a binding still declares it. There is no C
    ABI column — the async surface is a binding-layer concern over the
    blocking `_with_options` symbols (C has no awaitable type).

    Beyond the per-row check, the collected sets are reconciled against the
    union of declared row names: an endpoint that exposes an async query on
    ANY surface but has no row at all trips the gate, so a newly-async
    endpoint cannot slip in untracked.
    """
    errors: list[str] = []
    declared_names = {row.get("name") for row in rows if row.get("name")}
    for row in rows:
        name = row.get("name")
        if not name:
            errors.append(f"  [[historical_async]] row missing `name`: {row!r}")
            continue
        camel = _snake_to_camel(name)
        for lang, actual_set, hint in (
            ("rust", rust_async, f"`HistoricalClient::{name}` async query method (registry of record)"),
            ("python", py_async, f"`fn {name}_async` on the historical surface"),
            ("typescript", ts_async, f"`{camel}` async (Promise) method on `HistoricalView`"),
            ("cpp", cpp_async, f"`{name}_async(` on the C++ `Historical` view"),
        ):
            declared = row.get(lang, False)
            actual = name in actual_set
            if declared != actual:
                verb = "missing" if declared and not actual else "unexpected"
                errors.append(
                    f"  {name}.{lang}: declared={declared}, actual={actual} "
                    f"({verb} -- expected {hint})"
                )
    # Reverse-direction orphan check: any endpoint with an async query on a
    # surface but no row is undocumented drift.
    seen = rust_async | py_async | ts_async | cpp_async
    for endpoint in sorted(seen - declared_names):
        on = sorted(
            lang
            for lang, s in (
                ("rust", rust_async),
                ("python", py_async),
                ("typescript", ts_async),
                ("cpp", cpp_async),
            )
            if endpoint in s
        )
        errors.append(
            f"  {endpoint}: exposes an async query on {on} but has no "
            f"[[historical_async]] row. Add one declaring its "
            f"per-binding presence so the surface stays tracked."
        )
    return errors


# ─── Rust historical surface (registry of record) ────────────────────
#
# The historical-async / historical-streaming / historical-base families
# gate the managed bindings (Python / TypeScript / C++) and the C ABI, but
# the Rust core is the SOURCE OF TRUTH every one of them is generated from:
# the build pipeline reads `endpoint_surface.toml` and emits the
# `HistoricalClient::<endpoint>` buffered method, its async / streaming
# companions, and the `thetadatadx_<endpoint>_with_options` C-ABI base
# symbol. Without a Rust column + a collector that reads the actual Rust
# historical surface, a dropped or renamed Rust endpoint reaches none of
# the bindings yet trips no checker — the registry simply has one fewer
# entry and every downstream surface shrinks in lockstep, silently.
#
# The generated Rust method files live only in `OUT_DIR` (not committed),
# so the gate reads the registry of record directly — `endpoint_surface.toml`
# — which is the deterministic, no-build source the build pipeline itself
# consumes. Every `[[endpoints]]` entry generates a `HistoricalClient`
# method, so the registry IS the Rust historical surface.


def _collect_rust_buffered_endpoints(
    surface_toml: pathlib.Path,
) -> set[str]:
    """Snake_case names of every buffered historical endpoint in the
    registry of record.

    Parses `endpoint_surface.toml` and returns each `[[endpoints]]` `name`
    that is NOT a `*_stream` entry. The four `*_stream` entries are the
    FPSS real-time subscription endpoints (a distinct surface tracked by
    the streaming-client `[[method]]` rows); the remainder are the buffered
    historical endpoints (the 61-endpoint base surface). Each generates a
    `HistoricalClient::<name>` method on the Rust core, so this set is the
    Rust buffered + async query surface (every buffered endpoint carries an
    `.await` collect and the `list_async` / builder-await async twin).
    """
    if not surface_toml.is_file():
        return set()
    data = tomllib.loads(surface_toml.read_text(encoding="utf-8"))
    out: set[str] = set()
    for endpoint in data.get("endpoints", []):
        name = endpoint.get("name")
        if not name or name.endswith("_stream"):
            continue
        out.add(name)
    return out


def _endpoint_is_simple_list(endpoint: dict[str, Any]) -> bool:
    """True for a flat-list endpoint (`Vec<String>` return).

    Mirrors the build's `is_simple_list_endpoint` SSOT from the registry
    surface: a list endpoint declares a `list_column` (the field it
    projects) and/or returns the `StringList` collection. Flat lists return
    `Vec<String>`, not a typed row collection, so they get no server-stream
    terminal.
    """
    return "list_column" in endpoint or endpoint.get("returns") == "StringList"


def _endpoint_is_snapshot(endpoint: dict[str, Any]) -> bool:
    """True for a snapshot endpoint (bounded one-row-per-request result).

    Mirrors the build's `is_snapshot_endpoint` SSOT structurally from the
    registry: the snapshot endpoints carry the `_snapshot_` segment in their
    canonical name (`stock_snapshot_quote`, `option_snapshot_greeks_all`).
    A snapshot has nothing to drain incrementally, so it gets no
    server-stream terminal.
    """
    return "_snapshot_" in endpoint.get("name", "")


def _endpoint_is_calendar(endpoint: dict[str, Any]) -> bool:
    """True for a calendar endpoint (bounded handful of rows).

    Mirrors the build's calendar exclusion from the registry: the calendar
    endpoints are named under the `calendar_` prefix. Like snapshots, they
    return a bounded result and get no server-stream terminal.
    """
    return endpoint.get("name", "").startswith("calendar")


def _collect_rust_streaming_endpoints(
    surface_toml: pathlib.Path,
) -> set[str]:
    """Snake_case names of every buffered endpoint that carries a Rust
    server-stream terminal (`<Endpoint>Builder::stream`).

    Mirrors the build's `endpoint_streams` SSOT predicate from the registry
    of record: a buffered endpoint streams unless it is a flat list (returns
    `Vec<String>`, no typed row chunks), a snapshot, or a calendar (both
    bounded, nothing to drain). The multi-day / full-universe history pulls
    — the ones whose buffered collect can exhaust memory — are exactly the
    streamable set.

    This is the Rust streaming surface independent of the managed bindings:
    a Rust endpoint dropped from the registry vanishes from this set even if
    a binding still (wrongly) declares it, so the per-row gate trips. The
    classification is pinned against the live generated Python `fn stream`
    surface by `_case_hist_stream_rust_mirrors_generated` so a future change
    to the build SSOT cannot silently desync the gate's mirror.
    """
    if not surface_toml.is_file():
        return set()
    data = tomllib.loads(surface_toml.read_text(encoding="utf-8"))
    out: set[str] = set()
    for endpoint in data.get("endpoints", []):
        name = endpoint.get("name")
        if not name or name.endswith("_stream"):
            continue
        if _endpoint_is_simple_list(endpoint):
            continue
        if _endpoint_is_snapshot(endpoint):
            continue
        if _endpoint_is_calendar(endpoint):
            continue
        out.add(name)
    return out


def _collect_cabi_base_endpoints(with_options_inc: pathlib.Path) -> set[str]:
    """Snake_case endpoint names whose `thetadatadx_<endpoint>_with_options`
    base symbol is declared in the SHIPPED C-ABI header fragment.

    Reads `sdks/cpp/include/endpoint_with_options.h.inc` — the header
    `thetadatadx.h` includes — rather than the `ffi/src` source, so a stale
    regenerated header that dropped (or renamed) a base symbol relative to
    the Rust source of truth is caught. The base family cross-checks this
    set against the Rust registry, so a header/registry divergence in EITHER
    direction trips.
    """
    out: set[str] = set()
    if not with_options_inc.is_file():
        return out
    text = with_options_inc.read_text(encoding="utf-8")
    for m in re.finditer(r"\bthetadatadx_(\w+)_with_options\s*\(", text):
        out.add(m.group(1))
    return out


def _collect_ffi_base_endpoints(ffi_src: pathlib.Path) -> set[str]:
    """Snake_case endpoint names whose `thetadatadx_<endpoint>_with_options`
    base symbol is DEFINED in the `ffi/src` Rust source.

    The companion to `_collect_cabi_base_endpoints`: the shipped header
    declares the symbol, this source defines it. The base family asserts the
    two agree, so a header that declares a symbol the source never defines
    (a link-time failure invisible to a header-only scan), or a source
    symbol the header forgot to declare (invisible to `cargo build`), trips.
    """
    out: set[str] = set()
    if not ffi_src.is_dir():
        return out
    fn_re = re.compile(r"\bfn\s+thetadatadx_(\w+)_with_options\s*\(")
    for rs in ffi_src.rglob("*.rs"):
        text = rs.read_text(encoding="utf-8")
        for m in fn_re.finditer(text):
            out.add(m.group(1))
    return out


# ─── Historical buffered base surface ([[historical_base]]) ───────────
#
# Every buffered historical endpoint exposes a blocking query terminal on
# all five surfaces: the Rust `HistoricalClient::<endpoint>` method, the
# Python `<Endpoint>Builder.list()` collect, the TypeScript buffered
# `<endpoint>` method (it is itself async-returning, so the buffered and
# async surfaces coincide there), the C++ `Historical::<endpoint>(...)`
# member, and the C-ABI `thetadatadx_<endpoint>_with_options` base symbol.
#
# This is the core "every endpoint exists everywhere" guarantee. Before
# this family the base sync presence was asserted only TRANSITIVELY — via
# the async / stream companions on the managed bindings — and the 61 C-ABI
# `_with_options` base functions were checked by NO family at all. A
# `[[historical_base]]` row pins one endpoint's blocking-query presence
# across all five surfaces directly.


def _collect_python_buffered_endpoints(py_src: pathlib.Path) -> set[str]:
    """Snake_case endpoint names whose Python `<Endpoint>Builder` pyclass
    exposes a buffered `list` terminal.

    The Python buffered query surface is the `list()` collect on each
    endpoint's `<Endpoint>Builder` — the blocking twin of the awaitable
    `list_async()`. Walks every `impl <Name>Builder { ... }` block and
    records the builder's endpoint name (the CamelCase struct stem, lowered)
    when the body declares `fn list(`. Mirrors the async / stream collectors
    on the buffered terminal.
    """
    out: set[str] = set()
    if not py_src.is_dir():
        return out
    impl_re = re.compile(r"impl\s+(\w+)Builder\s*\{")
    for rs in py_src.rglob("*.rs"):
        text = rs.read_text(encoding="utf-8")
        for header in impl_re.finditer(text):
            stem = header.group(1)
            body = _balanced_body(text, header.end())
            if re.search(r"\bfn\s+list\s*\(", body):
                out.add(_endpoint_method_to_snake(stem))
    return out


def _check_historical_base_rows(
    rows: list[dict[str, Any]],
    rust_buffered: set[str],
    py_buffered: set[str],
    ts_buffered: set[str],
    cpp_buffered: set[str],
    cabi_base: set[str],
    ffi_base: set[str],
) -> list[str]:
    """Per-endpoint cross-binding gate for `[[historical_base]]` rows.

    Each row declares a snake_case endpoint `name` plus the expected
    buffered-query presence on all five surfaces: Rust (the registry-of-
    record buffered method), Python (`<Endpoint>Builder.list()`), TypeScript
    (the buffered `<endpoint>` method), C++ (`Historical::<endpoint>`), and
    the C-ABI `thetadatadx_<endpoint>_with_options` base symbol. The checker
    compares the declared state against the actual surface state and returns
    a list of mismatch strings (empty when every row matches).

    Two reconciliations beyond the per-row forward check:

    1. Reverse-direction orphan scan: an endpoint present on ANY surface but
       with no row at all trips, so a new endpoint cannot slip in untracked.
    2. Header/source/registry agreement: the shipped C-ABI header
       (`cabi_base`), the `ffi/src` source (`ffi_base`), and the Rust
       registry (`rust_buffered`) must declare the same base set. A stale
       header that drifted from the source of truth trips here, without
       duplicating the broader `.so`↔header completeness checker.
    """
    errors: list[str] = []
    declared_names = {row.get("name") for row in rows if row.get("name")}
    for row in rows:
        name = row.get("name")
        if not name:
            errors.append(f"  [[historical_base]] row missing `name`: {row!r}")
            continue
        for lang, actual_set, hint in (
            ("rust", rust_buffered, f"`HistoricalClient::{name}` buffered method (registry of record)"),
            ("python", py_buffered, f"`fn list` on the `{name}` builder pyclass"),
            ("typescript", ts_buffered, f"buffered `{_snake_to_camel(name)}` method on `HistoricalView`"),
            ("cpp", cpp_buffered, f"`{name}(` on the C++ `Historical` view"),
            ("ffi", cabi_base, f"`thetadatadx_{name}_with_options` extern \"C\" symbol"),
        ):
            declared = row.get(lang, False)
            actual = name in actual_set
            if declared != actual:
                verb = "missing" if declared and not actual else "unexpected"
                errors.append(
                    f"  {name}.{lang}: declared={declared}, actual={actual} "
                    f"({verb} -- expected {hint})"
                )

    # Reverse-direction orphan check: any endpoint present on a surface but
    # with no row is undocumented drift.
    seen = (
        rust_buffered | py_buffered | ts_buffered | cabi_base
    )
    # C++ buffered members co-mingle with unrelated wrapper helpers, so the
    # orphan scan uses the four cleanly-enumerable surfaces; the C++ column
    # is still pinned forward per row.
    for endpoint in sorted(seen - declared_names):
        on = sorted(
            lang
            for lang, s in (
                ("rust", rust_buffered),
                ("python", py_buffered),
                ("typescript", ts_buffered),
                ("ffi", cabi_base),
            )
            if endpoint in s
        )
        errors.append(
            f"  {endpoint}: present on {on} but has no [[historical_base]] "
            f"row. Add one declaring its per-surface presence so the "
            f"buffered base surface stays tracked."
        )

    # Header / source / registry agreement on the C-ABI base set. The
    # shipped header is what downstream C / C++ consumers compile against;
    # it must declare exactly the base symbols the `ffi/src` source defines
    # and the Rust registry generates. A divergence in any direction is a
    # stale-artifact defect that no per-row column would surface on its own.
    if cabi_base and ffi_base and cabi_base != ffi_base:
        for ep in sorted(ffi_base - cabi_base):
            errors.append(
                f"  {ep}: `thetadatadx_{ep}_with_options` is defined in ffi/src "
                f"but missing from the shipped header "
                f"sdks/cpp/include/endpoint_with_options.h.inc (stale header)."
            )
        for ep in sorted(cabi_base - ffi_base):
            errors.append(
                f"  {ep}: `thetadatadx_{ep}_with_options` is declared in the "
                f"shipped header but not defined in ffi/src (dangling header "
                f"declaration)."
            )
    if cabi_base and rust_buffered and cabi_base != rust_buffered:
        for ep in sorted(rust_buffered - cabi_base):
            errors.append(
                f"  {ep}: buffered endpoint in the Rust registry has no "
                f"`thetadatadx_{ep}_with_options` base symbol in the shipped "
                f"C-ABI header."
            )
        for ep in sorted(cabi_base - rust_buffered):
            errors.append(
                f"  {ep}: C-ABI base symbol `thetadatadx_{ep}_with_options` "
                f"has no matching buffered endpoint in the Rust registry "
                f"(endpoint_surface.toml)."
            )
    return errors


# ─── Client construction-from-file surface ([[from_file]]) ────────────
#
# Every standalone client class exposes a one-call file-construction
# convenience that loads credentials from a two-line file and connects.
# The entry point is not a data method the `[[method]]` rows cover, and
# its spelling differs per binding (`from_file` on Python / C++,
# `connectFromFile` on TypeScript, `thetadatadx_<stem>_connect_from_file` on the
# C ABI), so a single `[[method]]` row cannot express it. These
# collectors harvest each binding's file-construction surface so the
# `[[from_file]]` rows can pin the cross-binding roster.
#
# `name` is the cross-binding client class identifier. The C ABI symbol
# stem differs from the class name (`thetadatadx_client_connect_from_file` for
# `Client`, `thetadatadx_historical_connect_from_file` for
# `HistoricalClient`, `thetadatadx_streaming_connect_from_file` for `StreamingClient`); the stem
# table below bridges the two.
#
# The family governs exactly the standalone clients that connect to the
# servers via a `thetadatadx_<stem>_connect_from_file` C ABI symbol. It does NOT
# govern `Credentials.from_file` (a credentials factory that returns a
# `Credentials`, not a connected client, surfaced over the distinct
# `thetadatadx_credentials_from_file` symbol) nor the Python-only
# `AsyncClient.from_file` (no C ABI / managed-binding twin —
# its presence is tracked by the `AsyncClient` `[[class]]`
# row). Scoping the collectors to the governed roster keeps those
# unrelated `from_file` entry points out of this family while still
# tripping on a new governed client that forgets a row.


# Parity class name → C ABI symbol stem for the
# `thetadatadx_<stem>_connect_from_file` extern "C" symbol. The keys are the
# governed client roster: every class this family tracks, and the only
# classes the collectors below consider.
FROM_FILE_FFI_STEMS: dict[str, str] = {
    "Client": "client",
    "HistoricalClient": "historical",
    "StreamingClient": "streaming",
}

# The governed client roster (the C++ class spelling of each, so the
# C++ collector can match the harvested class name before folding it
# back to the cross-binding identifier).
_FROM_FILE_GOVERNED: frozenset[str] = frozenset(FROM_FILE_FFI_STEMS)


def _collect_python_from_file_classes(py_methods: dict[str, set[str]]) -> set[str]:
    """Governed client classes whose Python pyclass exposes a `from_file`
    staticmethod.

    Reuses the already-collected `{pyclass: {method, ...}}` map; a
    governed class carrying `from_file` exposes the file-construction
    convenience. Scoped to `_FROM_FILE_GOVERNED` so the credentials
    factory (`Credentials.from_file`) and the Python-only async twin are
    not mistaken for governed clients.
    """
    return {
        cls
        for cls, methods in py_methods.items()
        if cls in _FROM_FILE_GOVERNED and "from_file" in methods
    }


def _collect_typescript_from_file_classes(ts_methods: dict[str, set[str]]) -> set[str]:
    """Governed client classes whose TypeScript napi class exposes a
    `connectFromFile` factory.

    Reuses the already-collected `{class: {method, ...}}` map; the napi
    factory's `js_name` is the camelCase `connectFromFile`. Scoped to the
    governed roster (the `Credentials.fromFile` factory is excluded).
    """
    return {
        cls
        for cls, methods in ts_methods.items()
        if cls in _FROM_FILE_GOVERNED and "connectFromFile" in methods
    }


def _collect_cpp_from_file_classes(cpp_methods: dict[str, set[str]]) -> set[str]:
    """Governed client classes whose C++ wrapper exposes a `from_file`
    static member.

    Reuses the already-collected `{class: {method, ...}}` map (which
    inlines the generator-emitted `*.inc` member declarations), folds the
    C++ alias names back to the cross-binding class identifier, and scopes
    to the governed roster so `Credentials::from_file` is not counted.
    """
    reverse_alias = {v: k for k, v in CPP_ALIASES.items()}
    out: set[str] = set()
    for cls, methods in cpp_methods.items():
        if "from_file" in methods:
            canonical = reverse_alias.get(cls, cls)
            if canonical in _FROM_FILE_GOVERNED:
                out.add(canonical)
    return out


def _collect_ffi_from_file_stems(ffi_src: pathlib.Path) -> set[str]:
    """C ABI symbol stems whose `thetadatadx_<stem>_connect_from_file` extern "C"
    symbol exists in `ffi/src/`.

    Returns the bare stems (`client` / `historical` / `streaming`); the
    checker maps each parity class name to its stem via
    `FROM_FILE_FFI_STEMS`.
    """
    out: set[str] = set()
    if not ffi_src.is_dir():
        return out
    fn_re = re.compile(r"\bfn\s+thetadatadx_(\w+)_connect_from_file\s*\(")
    for rs in ffi_src.rglob("*.rs"):
        text = rs.read_text(encoding="utf-8")
        for m in fn_re.finditer(text):
            out.add(m.group(1))
    return out


def _check_from_file_rows(
    rows: list[dict[str, Any]],
    py_from_file: set[str],
    ts_from_file: set[str],
    cpp_from_file: set[str],
    ffi_stems: set[str],
) -> list[str]:
    """Per-client-class cross-binding gate for `[[from_file]]` rows.

    Each row declares a client class `name` plus the expected
    file-construction presence in Python / TypeScript / C++ / the C ABI.
    The checker verifies the actual binding state against the declared
    state and returns a list of mismatch strings (empty when every row
    matches).

    Beyond the per-row check, the collected sets are reconciled against
    the union of declared row names: a client that exposes
    file-construction on ANY binding but has no row at all trips the
    gate, so a newly-added `from_file` cannot slip in untracked.
    """
    errors: list[str] = []
    declared_names = {row.get("name") for row in rows if row.get("name")}
    for row in rows:
        name = row.get("name")
        if not name:
            errors.append(f"  [[from_file]] row missing `name`: {row!r}")
            continue
        stem = FROM_FILE_FFI_STEMS.get(name)
        if stem is None:
            errors.append(
                f"  [[from_file]] row `{name}` has no C ABI stem mapping; "
                f"add it to FROM_FILE_FFI_STEMS."
            )
            continue
        ffi_present = stem in ffi_stems
        for lang, actual, hint in (
            ("python", name in py_from_file, f"`from_file` staticmethod on the `{name}` pyclass"),
            (
                "typescript",
                name in ts_from_file,
                f"`connectFromFile` napi factory on the `{name}` class",
            ),
            ("cpp", name in cpp_from_file, f"`from_file(` static member on the `{name}` C++ class"),
            ("ffi", ffi_present, f"`thetadatadx_{stem}_connect_from_file` extern \"C\" symbol"),
        ):
            declared = row.get(lang, False)
            if declared != actual:
                verb = "missing" if declared and not actual else "unexpected"
                errors.append(
                    f"  {name}.{lang}: declared={declared}, actual={actual} "
                    f"({verb} -- expected {hint})"
                )
    # Reverse-direction orphan check: any client exposing file
    # construction on a binding but lacking a row is undocumented drift.
    ffi_classes = {
        cls for cls, stem in FROM_FILE_FFI_STEMS.items() if stem in ffi_stems
    }
    seen = py_from_file | ts_from_file | cpp_from_file | ffi_classes
    for client in sorted(seen - declared_names):
        on = sorted(
            lang
            for lang, s in (
                ("python", py_from_file),
                ("typescript", ts_from_file),
                ("cpp", cpp_from_file),
                ("ffi", ffi_classes),
            )
            if client in s
        )
        errors.append(
            f"  {client}: exposes file construction on {on} but has no "
            f"[[from_file]] row. Add one declaring its per-binding "
            f"presence so the surface stays tracked."
        )
    return errors


# ─── Client construction (connect) surface ([[connect]]) ──────────────
#
# The base construction entry point: connect to the servers with an
# in-memory `Credentials` + `Config`. The `[[from_file]]` family above
# pins the file-loading convenience; this family pins the construction
# call itself, which `[[method]]` rows cannot express because its
# spelling differs per binding:
#   * Python — a `#[new]` constructor (`Client(creds, config)` /
#     `HistoricalClient(...)` / `StreamingClient(...)`, plus the
#     Python-only `AsyncClient(...)`). The method collector filters
#     `new`/`__new__`, so the constructor needs its own detector.
#   * TypeScript — a `connect` static factory (`Client.connect(...)`,
#     async-shaped: it returns the connected client).
#   * C++ — a `connect` static member (`Client::connect(...)`).
#   * C ABI — a `thetadatadx_<stem>_connect` extern "C" symbol.
#
# The governed roster is the standalone clients reachable over a
# `thetadatadx_<stem>_connect` C symbol. `AsyncClient` is Python-only
# (it wraps `Client`); it has no C ABI / TS / C++ twin, so its row
# carries no stem and is gated on Python alone.

# Parity class name → C ABI symbol stem for the `thetadatadx_<stem>_connect`
# extern "C" symbol. `AsyncClient` has no stem (Python-only); it is held
# in the governed roster separately so its constructor is still scanned.
CONNECT_FFI_STEMS: dict[str, str] = {
    "Client": "client",
    "HistoricalClient": "historical",
    "StreamingClient": "streaming",
}

# Python-only governed client(s) with no C ABI stem. Tracked so the
# constructor orphan scan still enrols them, but gated on Python alone.
CONNECT_PY_ONLY: frozenset[str] = frozenset({"AsyncClient"})

# Full governed roster (C-ABI-backed clients + Python-only twins).
_CONNECT_GOVERNED: frozenset[str] = frozenset(CONNECT_FFI_STEMS) | CONNECT_PY_ONLY


def _collect_python_connect_classes(py_src: pathlib.Path) -> set[str]:
    """Governed client classes whose Python pyclass exposes a `#[new]`
    constructor.

    The cross-binding method collector filters `new`/`__new__`, so the
    construction entry point needs its own scan. Walks every `impl <Path>`
    block, and if its body carries a `#[new]` attribute records the bare
    last-segment class name. Scoped to `_CONNECT_GOVERNED` so a `#[new]`
    on `Credentials` / `Config` / a tick struct is not mistaken for a
    client constructor.
    """
    out: set[str] = set()
    if not py_src.is_dir():
        return out
    impl_re = re.compile(
        r"impl\s+(?:[A-Za-z_][A-Za-z0-9_]*::)*([A-Za-z_][A-Za-z0-9_]*)\s*\{"
    )
    for rs in py_src.rglob("*.rs"):
        text = rs.read_text(encoding="utf-8")
        for header in impl_re.finditer(text):
            class_name = header.group(1)
            if class_name not in _CONNECT_GOVERNED:
                continue
            body = _balanced_body(text, header.end())
            if "#[new]" in body:
                out.add(class_name)
    return out


def _collect_typescript_connect_classes(ts_methods: dict[str, set[str]]) -> set[str]:
    """Governed client classes whose TypeScript napi class exposes a
    `connect` static factory.

    Reuses the collected `{class: {method, ...}}` map; the napi factory's
    name is the bare `connect`. Scoped to the C-ABI-backed roster (the
    Python-only `AsyncClient` is never a TS class).
    """
    return {
        cls
        for cls, methods in ts_methods.items()
        if cls in CONNECT_FFI_STEMS and "connect" in methods
    }


def _collect_cpp_connect_classes(cpp_methods: dict[str, set[str]]) -> set[str]:
    """Governed client classes whose C++ wrapper exposes a `connect`
    static member.

    Folds the C++ alias names back to the cross-binding identifier and
    scopes to the C-ABI-backed roster.
    """
    reverse_alias = {v: k for k, v in CPP_ALIASES.items()}
    out: set[str] = set()
    for cls, methods in cpp_methods.items():
        if "connect" in methods:
            canonical = reverse_alias.get(cls, cls)
            if canonical in CONNECT_FFI_STEMS:
                out.add(canonical)
    return out


def _collect_ffi_connect_stems(ffi_src: pathlib.Path) -> set[str]:
    """C ABI symbol stems whose `thetadatadx_<stem>_connect` extern "C"
    symbol exists in `ffi/src/`.

    The `_connect_from_file` convenience shares the `_connect` prefix, so
    the regex anchors on a `(` immediately after `_connect` to match only
    the base construction symbol, not `_connect_from_file`.
    """
    out: set[str] = set()
    if not ffi_src.is_dir():
        return out
    fn_re = re.compile(r"\bfn\s+thetadatadx_(\w+?)_connect\s*\(")
    for rs in ffi_src.rglob("*.rs"):
        text = rs.read_text(encoding="utf-8")
        for m in fn_re.finditer(text):
            out.add(m.group(1))
    return out


def _check_connect_rows(
    rows: list[dict[str, Any]],
    py_connect: set[str],
    ts_connect: set[str],
    cpp_connect: set[str],
    ffi_stems: set[str],
) -> list[str]:
    """Per-client-class cross-binding gate for `[[connect]]` rows.

    Each row declares a client class `name` plus the expected construction
    presence in Python / TypeScript / C++ / the C ABI. A Python-only
    governed client (`AsyncClient`) carries no C ABI stem; its `ffi`
    column must be `false` and is gated on Python alone. The collected
    sets are reconciled against the declared row names so a client that
    constructs on ANY binding without a row trips the gate.
    """
    errors: list[str] = []
    declared_names = {row.get("name") for row in rows if row.get("name")}
    for row in rows:
        name = row.get("name")
        if not name:
            errors.append(f"  [[connect]] row missing `name`: {row!r}")
            continue
        if name not in _CONNECT_GOVERNED:
            errors.append(
                f"  [[connect]] row `{name}` is not a governed client; "
                f"add it to CONNECT_FFI_STEMS (C-ABI-backed) or "
                f"CONNECT_PY_ONLY (Python-only)."
            )
            continue
        stem = CONNECT_FFI_STEMS.get(name)
        ffi_present = stem in ffi_stems if stem is not None else False
        checks = [
            ("python", name in py_connect, f"`#[new]` constructor on the `{name}` pyclass"),
            (
                "typescript",
                name in ts_connect,
                f"`connect` static factory on the `{name}` napi class",
            ),
            ("cpp", name in cpp_connect, f"`connect(` static member on the `{name}` C++ class"),
            (
                "ffi",
                ffi_present,
                f"`thetadatadx_{stem}_connect` extern \"C\" symbol"
                if stem is not None
                else "no C ABI stem (Python-only client)",
            ),
        ]
        for lang, actual, hint in checks:
            declared = row.get(lang, False)
            if declared != actual:
                verb = "missing" if declared and not actual else "unexpected"
                errors.append(
                    f"  {name}.{lang}: declared={declared}, actual={actual} "
                    f"({verb} -- expected {hint})"
                )
    # Reverse-direction orphan check: any client constructing on a binding
    # but lacking a row is undocumented drift.
    ffi_classes = {
        cls for cls, stem in CONNECT_FFI_STEMS.items() if stem in ffi_stems
    }
    seen = py_connect | ts_connect | cpp_connect | ffi_classes
    for client in sorted(seen - declared_names):
        on = sorted(
            lang
            for lang, s in (
                ("python", py_connect),
                ("typescript", ts_connect),
                ("cpp", cpp_connect),
                ("ffi", ffi_classes),
            )
            if client in s
        )
        errors.append(
            f"  {client}: constructs a connected client on {on} but has no "
            f"[[connect]] row. Add one declaring its per-binding presence "
            f"so the construction surface stays tracked."
        )
    return errors


# ─── Main gate ──────────────────────────────────────────────────────


# Recognized suffixes for a dotted "documentation anchor" row — a row
# whose struct prefix is NOT a field-bearing config struct
# (`STRUCT_TO_PREFIX`). These rows record a cross-binding fact about a
# whole class (a tick wrapper tracked by the `*Tick` catch-all, or a known
# name divergence) rather than a per-field setter. The suffix must be one
# of these AND the struct part must name a real binding class, or the row
# is treated as a typo and fails the gate.
ANCHOR_ROW_SUFFIXES: frozenset[str] = frozenset(
    {
        "cross_binding_anchor",
        "cross_binding_name_divergence",
    }
)


def _check_dotted_rows(
    rows: list[dict[str, Any]],
    py_setters: set[str],
    ts_setters: set[str],
    cpp_setters: set[str],
    ffi_setters: set[str],
    anchor_classes: set[str] | None = None,
) -> list[str]:
    """Per-field / per-setter granularity (issue #595).

    Returns a list of human-readable error strings. An empty list
    means every dotted row in `parity.toml` matches the actual binding
    state of each SDK.

    `anchor_classes` is the universe of real binding class names (every
    pyclass / TS class / C++ class plus the implicitly-tracked tick
    wrappers). When provided, a dotted row whose struct prefix is not a
    field-bearing config struct is validated as a documentation-anchor row:
    its suffix must be in `ANCHOR_ROW_SUFFIXES` AND its struct part must
    name a class in `anchor_classes`. A row that satisfies neither is a
    probable typo (a misspelled struct, a stray dotted name) and fails the
    gate, closing the silent-skip blind spot. When `anchor_classes` is
    `None` (the selftest call shape), anchor rows are skipped as before so
    synthetic per-field matrices stay hermetic.
    """
    errors: list[str] = []
    for row in rows:
        name = row["name"]
        if "." not in name:
            continue
        struct_name, suffix = name.split(".", 1)
        prefix = STRUCT_TO_PREFIX.get(struct_name)
        if prefix is None:
            # Not a field-bearing config struct — this must be a
            # documentation-anchor row (a whole-class cross-binding fact,
            # e.g. `GreeksEodTick.cross_binding_anchor`). When the class
            # universe is known, validate it so a typo cannot slip through
            # silently; otherwise (selftest) skip as a non-field row.
            if anchor_classes is None:
                continue
            if suffix not in ANCHOR_ROW_SUFFIXES:
                errors.append(
                    f"  {name}: dotted row on non-config struct uses an "
                    f"unrecognized suffix `{suffix}`. A documentation-anchor "
                    f"row must use one of {sorted(ANCHOR_ROW_SUFFIXES)}; a "
                    f"field-level row must name a struct in STRUCT_TO_PREFIX. "
                    f"This is almost certainly a typo."
                )
                continue
            if struct_name not in anchor_classes:
                errors.append(
                    f"  {name}: anchor row names struct `{struct_name}`, which "
                    f"is not a known binding class. Fix the spelling or remove "
                    f"the row — a typo'd anchor silently asserts nothing."
                )
            continue
        # Allow rows to override the auto-derived setter name. Used
        # when a single struct has a mix of prefixed / unprefixed
        # binding-side names (e.g. `HistoricalConfig.host` binds as
        # `historical_host` because the bare `host` name would collide with
        # nothing meaningful and the `historical_` prefix clarifies intent).
        canonical = row.get("setter") or f"{prefix}{suffix}"

        rust_only = bool(row.get("rust_only", False))
        issue = row.get("issue")
        if rust_only and not issue:
            errors.append(
                f"  {name}: declared `rust_only = true` but missing "
                f"`issue = \"#N\"` field. Every Rust-only row must "
                f"cite a tracking issue number."
            )
            continue
        if issue and not rust_only:
            errors.append(
                f"  {name}: has `issue` field but is not `rust_only`. "
                f"Drop the `issue` field (no Rust-only contract is "
                f"being tracked) or flip `rust_only = true`."
            )

        if rust_only:
            # Documented Rust-only: no setter expected on any binding.
            # The class-level booleans must be false on every column.
            for lang in ("python", "typescript", "cpp"):
                if row.get(lang, False):
                    errors.append(
                        f"  {name}.{lang}: row is `rust_only = true` "
                        f"but declares `{lang} = true`. Pick one — "
                        f"either remove the Rust-only flag (and bind "
                        f"the field) or flip the binding column to "
                        f"false."
                    )
            continue

        for lang, lookup in (
            ("python", py_setters),
            ("typescript", ts_setters),
            ("cpp", cpp_setters),
        ):
            declared = row.get(lang, False)
            actual = _setter_present(canonical, lookup)
            if declared != actual:
                verb = "missing" if declared and not actual else "unexpected"
                errors.append(
                    f"  {name}.{lang}: declared={declared}, actual={actual} "
                    f"({verb} — canonical setter `{canonical}`)"
                )

        # FFI gate: C++ binding forwards through the C ABI, so a
        # bound C++ row requires the FFI symbol. Python (pyo3) and
        # TypeScript (napi) bindings mutate `DirectConfig` directly
        # through the inner mutex, so they do not require an FFI
        # symbol — a Python-only or TS-only setter is legal.
        if row.get("cpp", False):
            ffi_present = _setter_present(canonical, ffi_setters)
            if not ffi_present:
                errors.append(
                    f"  {name}.ffi: row declares `cpp = true` but the "
                    f"FFI symbol `thetadatadx_config_set_{canonical}` is "
                    f"absent. The C++ wrapper forwards through the C "
                    f"ABI; add the FFI pair before flipping the C++ "
                    f"column to `true`."
                )

    return errors


def _check_orphan_rust_fields(
    rust_fields: dict[str, set[str]],
    rows: list[dict[str, Any]],
) -> list[str]:
    """Reverse-direction check: every pub field on every scoped struct
    must have a corresponding parity row. Adding a new pub field
    without a parity row trips this gate so the cross-binding sweep
    cannot be silently skipped.
    """
    errors: list[str] = []
    declared_names: set[str] = {row["name"] for row in rows}
    for struct in SCOPED_STRUCTS:
        fields = rust_fields.get(struct, set())
        for field in sorted(fields):
            row_suffix = _rust_field_to_row_suffix(struct, field)
            row_name = f"{struct}.{row_suffix}"
            if row_name in declared_names:
                continue
            errors.append(
                f"  {row_name}: pub field on `{struct}` has no "
                f"parity-toml row. Either add a `[[class]]` row "
                f"declaring the field's binding state, or mark the "
                f"field as `rust_only = true, issue = \"#N\"`."
            )
    return errors


VALUE_FIELD_PY_SRC = REPO_ROOT / "sdks" / "python" / "src"
VALUE_FIELD_TS_SRC = REPO_ROOT / "sdks" / "typescript" / "src"


def _struct_field_type(src_dir: pathlib.Path, struct: str, field: str) -> str | None:
    """Declared Rust-side type of `field` on `struct` in a binding crate.

    Scans every `.rs` file (including `_generated/`) for the struct body
    and returns the type text of the named field, attribute prefixes
    (`#[pyo3(get)]`) stripped. Returns `None` when the struct or field
    is absent. Generated and hand-written sources are treated alike —
    the declared type IS the binding surface either way.
    """
    struct_re = re.compile(
        r"(?:pub(?:\(crate\))?\s+)?struct\s+" + re.escape(struct) + r"\s*\{(.*?)\n\}",
        re.S,
    )
    field_re = re.compile(
        r"(?:#\[[^\]]*\]\s*)*pub\s+" + re.escape(field) + r"\s*:\s*([^,\n]+)",
    )
    for path in sorted(src_dir.rglob("*.rs")):
        text = path.read_text(encoding="utf-8")
        for m in struct_re.finditer(text):
            fm = field_re.search(m.group(1))
            if fm:
                return fm.group(1).strip()
    return None


def _cpp_struct_field_type(hpp: pathlib.Path, struct: str, field: str) -> str | None:
    """Declared C++ type of `field` on `struct` in the C++ wrapper header.

    Mirrors [`_struct_field_type`] for the hand-written C++ value structs
    (`OptionContract`, etc.) whose field types live in `thetadatadx.hpp`
    rather than a Rust binding crate. Returns `None` when the struct or
    field is absent. A `cpp` key on a `[[value_field]]` row pins the
    type this returns, closing the gap that let a C++ value struct
    surface a raw wire integer the other bindings decode.
    """
    text = hpp.read_text(encoding="utf-8")
    struct_re = re.compile(
        r"struct\s+" + re.escape(struct) + r"\s*\{(.*?)\n\}",
        re.S,
    )
    field_re = re.compile(
        r"([A-Za-z_][\w:<>\s\*&]*?)\s+" + re.escape(field) + r"\s*;",
    )
    for m in struct_re.finditer(text):
        fm = field_re.search(m.group(1))
        if fm:
            return fm.group(1).strip()
    return None


# The generated C-ABI header fragment carrying the `#[repr(C)]` streaming
# value structs. Its types are declared in the `typedef struct { ... }
# <Name>;` C idiom, NOT the `struct <Name> { ... }` C++ idiom the wrapper
# header uses, so it needs its own reader. The streaming contract payload
# (`ThetaDataDxContract`) lives here and carries the unit-bearing wire
# fields (`strike` dollars + `strike_thousandths` the raw integer).
CPP_C_STRUCT_INC = REPO_ROOT / "sdks" / "cpp" / "include" / "fpss_event_structs.h.inc"

# Parity-toml value `class` → the generated C-ABI struct that backs it,
# for fields whose C-ABI shape is the source of truth rather than a C++
# wrapper struct. The streaming contract payload is the cross-binding
# `ContractRef` (Python) / `Contract` (TypeScript); both decode the same
# `#[repr(C)] ThetaDataDxContract` on the C side.
VALUE_FIELD_C_STRUCT_ALIASES: dict[str, str] = {
    "ContractRef": "ThetaDataDxContract",
    "Contract": "ThetaDataDxContract",
}


def _c_abi_struct_field_type(inc: pathlib.Path, struct: str, field: str) -> str | None:
    """Declared C type of `field` on a `typedef struct { ... } <struct>;`
    in the generated C-ABI header fragment.

    The streaming value structs are emitted in the C `typedef struct`
    idiom (the type name follows the closing brace), which
    `_cpp_struct_field_type`'s `struct <Name> {` regex cannot read. This
    reader matches the C form so a `cpp` key on a `[[value_field]]` row
    whose class is C-ABI-backed (`ContractRef` / `Contract`) is validated
    against the actual generated C struct member type — closing the gap
    that let the C side silently skip a unit-bearing field the other
    bindings pin. Returns `None` when the struct or field is absent.
    """
    if not inc.is_file():
        return None
    text = inc.read_text(encoding="utf-8")
    struct_re = re.compile(
        r"typedef\s+struct\s*\{(.*?)\}\s*" + re.escape(struct) + r"\s*;",
        re.S,
    )
    field_re = re.compile(
        r"([A-Za-z_][\w:<>\s\*&]*?)\s+" + re.escape(field) + r"\s*;",
    )
    for m in struct_re.finditer(text):
        fm = field_re.search(m.group(1))
        if fm:
            return fm.group(1).strip()
    return None


def _check_value_field_rows(rows: list[dict[str, Any]]) -> list[str]:
    """Field-level TYPE parity for `[[value_field]]` rows.

    Each row pins the declared Rust-side type of one field on one
    value class per binding:

        [[value_field]]
        class = "ContractRef"
        name = "strike"
        python = "Option<f64>"
        typescript = "Option<f64>"

    `python` / `typescript` are the Rust types in the pyclass / napi
    object struct (omit a key to skip that binding, e.g. a
    Python-only spelling like `lambda_`). A mismatch — the field
    missing, or declared under a different type — fails the gate, so a
    binding cannot silently drift a field's unit-bearing type (the
    strike-thousandths / right-as-int / ms_of_day2 defect class).
    """
    errors: list[str] = []
    for row in rows:
        cls, field = row["class"], row["name"]
        for lang, src_dir in (
            ("python", VALUE_FIELD_PY_SRC),
            ("typescript", VALUE_FIELD_TS_SRC),
        ):
            declared = row.get(lang)
            if declared is None:
                continue
            actual = _struct_field_type(src_dir, cls, field)
            if actual != declared:
                errors.append(
                    f"{cls}.{field}.{lang}: declared type `{declared}`, "
                    f"actual `{actual or '<field missing>'}`"
                )
        # C++ value structs declare their field types in the wrapper
        # header, not a Rust crate, so they get their own reader. A class
        # whose C-side shape is the generated `#[repr(C)]` struct (the
        # streaming contract payload) is read from the C-ABI header
        # fragment instead — the `typedef struct { ... } <Name>;` idiom the
        # C++-struct reader cannot parse.
        declared_cpp = row.get("cpp")
        if declared_cpp is not None:
            c_struct = VALUE_FIELD_C_STRUCT_ALIASES.get(cls)
            if c_struct is not None:
                actual_cpp = _c_abi_struct_field_type(CPP_C_STRUCT_INC, c_struct, field)
            else:
                actual_cpp = _cpp_struct_field_type(CPP_HPP, _cpp_class_for(cls), field)
            if actual_cpp != declared_cpp:
                errors.append(
                    f"{cls}.{field}.cpp: declared type `{declared_cpp}`, "
                    f"actual `{actual_cpp or '<field missing>'}`"
                )
    return errors


# ─── Value-field exhaustiveness (reverse-direction roster) ────────────
#
# The per-row `_check_value_field_rows` gate verifies each DECLARED field
# resolves to the right type. It does not gate the reverse direction: a
# unit- or identity-bearing field that lands on a binding value struct
# without a `[[value_field]]` row trips nothing, because the row simply
# does not exist (the exact `strike_thousandths` defect — the wire integer
# shipped on the streaming payloads with zero matrix rows). Two
# complementary scans close that blind spot without pinning every trivial
# column:
#
#  1. A roster check: the load-bearing value classes each carry a fixed
#     set of unit/identity-bearing fields that MUST be pinned. A missing
#     entry trips, so dropping a row for one of these protected surfaces
#     fails the gate.
#  2. A vocabulary scan: any binding struct field whose NAME matches the
#     unit/identity grammar (`strike` / `strike_thousandths` / `right` /
#     `*_timestamp_ms`) on a class already in the matrix, but which has no
#     `[[value_field]]` row under that name on ANY class, trips. A brand-new
#     unit-bearing field name (a future `settlement_timestamp_ms`, a
#     re-typed `strike_micros`) cannot ship untracked.
#
# Both scans are intentionally scoped to the unit/identity-bearing surface
# the matrix exists to protect — the flat data columns (`price`, `size`,
# the Greeks scalars) are projected from one schema source and stay in
# lockstep by construction, so they are out of scope here.

# Load-bearing value classes → the unit/identity-bearing fields that must
# carry a `[[value_field]]` row. Keyed by the cross-binding class name the
# matrix uses (`ContractRef` is the Python streaming payload, `Contract`
# the TypeScript one). Each listed `(class, field)` must appear in the
# matrix or the roster check trips.
VALUE_FIELD_ROSTER: dict[str, tuple[str, ...]] = {
    "ContractRef": ("strike", "strike_thousandths", "right"),
    "Contract": ("strike", "strike_thousandths", "right"),
    "OptionContract": ("right",),
    "TradeTick": ("strike", "right"),
    "EodTick": ("created_ms_of_day", "last_trade_ms_of_day"),
}

# The unit/identity-bearing field-name grammar the vocabulary scan
# protects. A field whose name matches this — and which has no
# `[[value_field]]` row under that name anywhere — is a new unit-bearing
# surface that must be enrolled.
_VALUE_FIELD_UNIT_NAME_RE = re.compile(
    r"^(?:strike|strike_thousandths|right)$|_timestamp_ms$|^timestamp_ms$"
)

# Field-name aliases between the Python source spelling and the matrix /
# TypeScript spelling. The Python keyword escape `lambda_` is the matrix
# `lambda` on the TS side; neither is unit-bearing, so this is only here
# to document the one cross-binding rename the scans must treat as equal
# should the grammar ever widen to cover it.
_VALUE_FIELD_NAME_ALIASES: dict[str, str] = {"lambda_": "lambda"}


def _collect_value_struct_fields(
    src_dir: pathlib.Path, struct: str
) -> set[str]:
    """Return the `pub` field names of `struct` across a binding crate.

    Mirrors `_struct_field_type`'s struct-body scan but harvests every
    field name rather than one field's type. Used by the reverse
    exhaustiveness scan to enumerate a value struct's actual surface.
    """
    out: set[str] = set()
    if not src_dir.is_dir():
        return out
    struct_re = re.compile(
        r"(?:pub(?:\(crate\))?\s+)?struct\s+" + re.escape(struct) + r"\s*\{(.*?)\n\}",
        re.S,
    )
    field_re = re.compile(r"(?:#\[[^\]]*\]\s*)*pub\s+(\w+)\s*:", re.M)
    for path in sorted(src_dir.rglob("*.rs")):
        text = path.read_text(encoding="utf-8")
        for m in struct_re.finditer(text):
            for fm in field_re.finditer(m.group(1)):
                out.add(fm.group(1))
    return out


def _check_value_field_roster(rows: list[dict[str, Any]]) -> list[str]:
    """Reverse-direction exhaustiveness for the `[[value_field]]` matrix.

    Two scans (see the section header):

      * roster — every `(class, field)` in `VALUE_FIELD_ROSTER` must have a
        matrix row;
      * vocabulary — every binding struct field matching the unit/identity
        grammar on a matrix class must have a row under that name somewhere.

    Returns human-readable error strings (empty when complete).
    """
    errors: list[str] = []
    present_pairs: set[tuple[str, str]] = {
        (row["class"], row["name"]) for row in rows
    }
    present_names: set[str] = {row["name"] for row in rows}

    for cls, fields in VALUE_FIELD_ROSTER.items():
        for field in fields:
            if (cls, field) not in present_pairs:
                errors.append(
                    f"  {cls}.{field}: load-bearing unit/identity field has "
                    f"no `[[value_field]]` row. Add one pinning its type on "
                    f"the bindings that carry it (the matrix exists to keep "
                    f"this surface honest)."
                )

    # Vocabulary scan: every class already in the matrix, every binding
    # struct field whose name matches the unit grammar, must have a row
    # under that name on some class.
    matrix_classes = sorted({row["class"] for row in rows})
    flagged: set[tuple[str, str]] = set()
    for cls in matrix_classes:
        for src_dir in (VALUE_FIELD_PY_SRC, VALUE_FIELD_TS_SRC):
            for field in _collect_value_struct_fields(src_dir, cls):
                canonical = _VALUE_FIELD_NAME_ALIASES.get(field, field)
                if not _VALUE_FIELD_UNIT_NAME_RE.search(canonical):
                    continue
                if canonical in present_names or field in present_names:
                    continue
                if (cls, field) in flagged:
                    continue
                flagged.add((cls, field))
                errors.append(
                    f"  {cls}.{field}: unit/identity-bearing field present on "
                    f"a binding value struct but no `[[value_field]]` row pins "
                    f"the name anywhere. Enroll it so its type cannot drift "
                    f"silently across bindings."
                )
    return errors


def main(argv: list[str] | None = None) -> int:
    argv = argv if argv is not None else sys.argv[1:]
    if "--selftest" in argv:
        return _run_selftest()

    if not PARITY_TOML.is_file():
        print(f"missing parity matrix: {PARITY_TOML}", file=sys.stderr)
        return 1

    data: dict[str, Any] = tomllib.loads(PARITY_TOML.read_text(encoding="utf-8"))
    rows: list[dict[str, Any]] = data.get("class", [])
    method_rows: list[dict[str, Any]] = data.get("method", [])
    value_field_rows: list[dict[str, Any]] = data.get("value_field", [])
    utility_rows: list[dict[str, Any]] = data.get("utility", [])
    historical_streaming_rows: list[dict[str, Any]] = data.get(
        "historical_streaming", []
    )
    historical_async_rows: list[dict[str, Any]] = data.get(
        "historical_async", []
    )
    historical_base_rows: list[dict[str, Any]] = data.get("historical_base", [])
    from_file_rows: list[dict[str, Any]] = data.get("from_file", [])
    connect_rows: list[dict[str, Any]] = data.get("connect", [])
    if not rows:
        print("parity.toml has no [[class]] rows", file=sys.stderr)
        return 1

    py_classes = collect_python_classes(PY_SRC)
    ts_classes = collect_typescript_classes(TS_DTS)
    cpp_classes = collect_cpp_classes(CPP_HPP)

    py_setters = _collect_python_setters(PY_SRC)
    ts_setters = _collect_typescript_setters(TS_SRC)
    cpp_setters = _collect_cpp_setters(CPP_HPP, CPP_H)
    ffi_setters = _collect_ffi_setters(FFI_SRC)

    rust_fields = _collect_rust_pub_fields(CONFIG_DIR)

    py_class_methods = _collect_python_class_methods(PY_SRC)
    ts_class_methods = _collect_typescript_class_methods(TS_SRC)
    cpp_class_methods = _collect_cpp_class_methods(CPP_HPP)

    declared_names: set[str] = {row["name"] for row in rows}

    # Class-level mismatches (non-dotted rows).
    class_mismatches: list[tuple[str, str, bool, bool]] = []
    for row in rows:
        name = row["name"]
        if "." in name:
            continue
        for lang, declared in (
            ("python", row["python"]),
            ("typescript", row["typescript"]),
            ("cpp", row["cpp"]),
        ):
            if lang == "python":
                actual = name in py_classes
            elif lang == "typescript":
                actual = name in ts_classes
            else:
                actual = cpp_has(name, cpp_classes)
            if actual != declared:
                class_mismatches.append((name, lang, declared, actual))

    # Field-level mismatches (dotted rows / #595). The class universe lets
    # the dotted-row check validate documentation-anchor rows (an anchor on
    # a typo'd / nonexistent struct fails instead of silently passing).
    anchor_classes = py_classes | ts_classes | cpp_classes
    field_errors = _check_dotted_rows(
        rows, py_setters, ts_setters, cpp_setters, ffi_setters, anchor_classes
    )

    # Method-level mismatches (per-method `[[method]]` rows on the
    # load-bearing user-facing classes — `Client`,
    # `StreamingClient`, `Credentials`, `Config`).
    method_errors = _check_method_rows(
        method_rows, py_class_methods, ts_class_methods, cpp_class_methods
    )

    # Reverse-direction orphan check on the core streaming surfaces: a
    # public observability accessor (counter / ring telemetry / the
    # slow-callback threshold setter) wired onto the core `StreamSurface`
    # view or the standalone `StreamingClient` MUST carry a `[[method]]`
    # row. Without this, a wired-but-unenrolled knob reaches none of the
    # bindings and no forward check fires, because the row simply does not
    # exist. This closes that blind spot at its source — the Rust surface.
    core_streaming_methods = _collect_core_streaming_observability_methods(
        CORE_CLIENT_RS, CORE_FPSS_MOD_RS
    )
    core_streaming_errors = _check_core_streaming_method_rows(
        core_streaming_methods, method_rows
    )

    # Orphan Rust pub fields (no parity row).
    orphan_errors = _check_orphan_rust_fields(rust_fields, rows)

    # Value-field TYPE parity ([[value_field]] rows).
    value_field_errors = _check_value_field_rows(value_field_rows)

    # Value-field exhaustiveness: the reverse direction of the per-row type
    # check. A load-bearing class missing a pinned unit/identity field, or a
    # new unit-bearing field name shipped on a binding value struct without
    # any enrolling row, trips here — the `strike_thousandths` defect class.
    value_field_roster_errors = _check_value_field_roster(value_field_rows)

    # Free-function (utility) parity ([[utility]] rows) — the offline
    # Greeks calculator (`all_greeks` / `implied_volatility`) is a free
    # function on every binding, tracked here because it is not a method
    # on any class the `[[method]]` rows cover.
    py_utils = _collect_python_utility_functions(PY_SRC)
    # The TS utility surface spans napi free functions (the calculators)
    # and the `Util` namespace-class static methods (the lookups); merge
    # both so every cross-binding row resolves regardless of TS shape.
    ts_utils = _ts_utility_surface(
        _collect_typescript_utility_functions(TS_SRC), ts_class_methods
    )
    cpp_utils = _collect_cpp_utility_functions(CPP_HPP)
    ffi_utils = _collect_ffi_utility_functions(FFI_SRC)
    utility_errors = _check_utility_rows(
        utility_rows, py_utils, ts_utils, cpp_utils, ffi_utils
    )
    # Reverse-direction orphan check: every standalone utility on the
    # cleanly-enumerable Python / TypeScript surfaces must be named by some
    # [[utility]] row (the conditions / exchange / calendar / sequence
    # roster that previously lived only as the `all_greeks` pair while a
    # dozen other utils drifted untracked).
    utility_roster_errors = _check_utility_roster_complete(
        utility_rows, py_utils, ts_utils
    )

    # Historical server-stream surface ([[historical_streaming]] rows) —
    # the `.stream(handler)` / `<endpoint>Stream` / `thetadatadx_<endpoint>_stream`
    # terminal per endpoint. These live on per-endpoint builders or as
    # endpoint-named methods, NOT on a class the `[[method]]` rows cover,
    # so they would otherwise drift silently across bindings.
    # The Rust historical surface is the registry of record
    # (`endpoint_surface.toml`): the build pipeline generates every binding's
    # historical method from it, so a dropped / renamed Rust endpoint must
    # trip the gate. The buffered set is the async + base surface; the
    # streamable subset (mirroring the build's `endpoint_streams` SSOT) is
    # the streaming surface.
    rust_buffered = _collect_rust_buffered_endpoints(ENDPOINT_SURFACE_TOML)
    rust_stream = _collect_rust_streaming_endpoints(ENDPOINT_SURFACE_TOML)

    py_stream = _collect_python_streaming_endpoints(PY_SRC)
    ts_stream = _collect_typescript_streaming_endpoints(ts_class_methods)
    cpp_stream = _collect_cpp_streaming_endpoints(cpp_class_methods)
    ffi_stream = _collect_ffi_streaming_endpoints(FFI_SRC)
    historical_streaming_errors = _check_historical_streaming_rows(
        historical_streaming_rows,
        rust_stream,
        py_stream,
        ts_stream,
        cpp_stream,
        ffi_stream,
    )

    # Historical async query surface ([[historical_async]] rows) — the
    # non-blocking `<endpoint>_async` / Promise companion per endpoint.
    # Python / C++ name an `<endpoint>_async` method; TypeScript's buffered
    # method is itself async (Promise). No C ABI row: the async surface is
    # a binding-layer concern over the existing blocking C symbols.
    py_async = _collect_python_async_endpoints(PY_SRC)
    ts_async = _collect_typescript_async_endpoints(ts_class_methods)
    cpp_async = _collect_cpp_async_endpoints(cpp_class_methods)
    historical_async_errors = _check_historical_async_rows(
        historical_async_rows, rust_buffered, py_async, ts_async, cpp_async
    )

    # Historical buffered base surface ([[historical_base]] rows) — the
    # blocking query terminal per endpoint on ALL FIVE surfaces: the Rust
    # `HistoricalClient::<endpoint>` method (registry of record), the Python
    # `<Endpoint>Builder.list()` collect, the buffered TypeScript method, the
    # C++ `Historical::<endpoint>` member, and the C-ABI
    # `thetadatadx_<endpoint>_with_options` base symbol read from the SHIPPED
    # header. This is the core "every endpoint exists everywhere" guarantee,
    # previously only implicit via the async / stream companions and unchecked
    # entirely on the C-ABI base.
    py_buffered = _collect_python_buffered_endpoints(PY_SRC)
    ts_buffered = _collect_typescript_async_endpoints(ts_class_methods)
    cpp_buffered = cpp_class_methods.get(_cpp_class_for("HistoricalView"), set())
    cabi_base = _collect_cabi_base_endpoints(ENDPOINT_WITH_OPTIONS_INC)
    ffi_base = _collect_ffi_base_endpoints(FFI_SRC)
    historical_base_errors = _check_historical_base_rows(
        historical_base_rows,
        rust_buffered,
        py_buffered,
        ts_buffered,
        cpp_buffered,
        cabi_base,
        ffi_base,
    )

    # Client construction-from-file surface ([[from_file]] rows) — the
    # one-call `from_file` / `connectFromFile` / `thetadatadx_*_connect_from_file`
    # convenience per standalone client class. Its spelling differs per
    # binding, so it cannot ride a `[[method]]` row; this family pins it
    # across Python / TypeScript / C++ / the C ABI.
    py_from_file = _collect_python_from_file_classes(py_class_methods)
    ts_from_file = _collect_typescript_from_file_classes(ts_class_methods)
    cpp_from_file = _collect_cpp_from_file_classes(cpp_class_methods)
    ffi_from_file_stems = _collect_ffi_from_file_stems(FFI_SRC)
    from_file_errors = _check_from_file_rows(
        from_file_rows, py_from_file, ts_from_file, cpp_from_file, ffi_from_file_stems
    )

    # Client construction surface ([[connect]] rows) — the base
    # `Client(creds, config)` / `Client.connect(...)` / `Client::connect(...)`
    # / `thetadatadx_<stem>_connect` entry point per standalone client. Its
    # spelling differs per binding (Python `#[new]` constructor vs the
    # `connect` factory elsewhere), so it cannot ride a `[[method]]` row;
    # this family pins it across Python / TypeScript / C++ / the C ABI plus
    # the Python-only `AsyncClient`.
    py_connect = _collect_python_connect_classes(PY_SRC)
    ts_connect = _collect_typescript_connect_classes(ts_class_methods)
    cpp_connect = _collect_cpp_connect_classes(cpp_class_methods)
    ffi_connect_stems = _collect_ffi_connect_stems(FFI_SRC)
    connect_errors = _check_connect_rows(
        connect_rows, py_connect, ts_connect, cpp_connect, ffi_connect_stems
    )

    # Public-surface vocabulary: no public client identifier may embed
    # one of OUR implementation-detail tokens (tokio / disruptor /
    # crossbeam / parking_lot / block_on / allow_threads / os_pipe).
    # Vendor protocol names (mdds / fpss) are allow-listed. This is the
    # structural counterpart to the text scrubber — it sees only public
    # API names, so it never false-positives on internal runtime use.
    surface_vocab_errors = _check_public_surface_vocab(
        py_classes,
        ts_classes,
        cpp_classes,
        py_setters,
        ts_setters,
        cpp_setters,
        ffi_setters,
        py_class_methods,
        ts_class_methods,
        cpp_class_methods,
    )

    # Client-facing setter-SET equality across Python / TS / C++ / the
    # C ABI after normalization (`_explicit` widened-ABI suffix and the
    # `flat_files`↔`flatfiles` camelCase split folded away). Catches a
    # knob bound on some bindings but silently absent from the matrix on
    # the others. Genuine per-language idioms are exempted in
    # `SETTER_PARITY_EXEMPT` with a written reason.
    setter_set_errors = _check_setter_set_parity(
        py_setters, ts_setters, cpp_setters, ffi_setters
    )

    # Client-facing read-back getter-SET equality across the four
    # bindings. The setter check covers the write side of the Config knob
    # roster; this covers the read side — a knob that grew a getter on
    # some bindings but not others (the read-back analogue of the
    # missing-on-TS setter defect) trips here.
    py_getters = _collect_python_getters(PY_SRC)
    ts_getters = _collect_typescript_getters(TS_SRC)
    cpp_getters = _collect_cpp_getters(CPP_HPP)
    ffi_getters = _collect_ffi_getters(FFI_SRC)
    getter_set_errors = _check_getter_set_parity(
        py_getters, ts_getters, cpp_getters, ffi_getters
    )

    # Subscription-kind label parity: every binding must stringify the
    # FPSS subscription kinds to exactly the canonical snake_case roster
    # (`quote` / `trade` / `open_interest` / `market_value` / `full_trades`
    # / `full_open_interest`). Asserts the actual emitted strings, not
    # method presence — the seam where a C ABI label silently differs, or
    # the C++ accessor invents a `full_quote` / `full_market_value` label
    # for a full-stream kind that does not exist on the wire.
    rust_kinds = _collect_rust_subscription_kinds(SUBSCRIPTION_RS)
    py_kinds = _collect_binding_subscription_kinds(PY_FLUENT_RS)
    ts_kinds = _collect_binding_subscription_kinds(TS_FLUENT_RS)
    cpp_kinds = _collect_cpp_subscription_kinds(CPP_HPP)
    ffi_kinds = _collect_ffi_subscription_kinds(CPP_H)
    subscription_kind_errors = _check_subscription_kind_parity(
        rust_kinds, py_kinds, ts_kinds, cpp_kinds, ffi_kinds
    )

    # Error-leaf mapping parity: every core `Error` variant must map to
    # the same leaf class in Python / TypeScript / C++ and the same
    # `THETADATADX_ERR_*` code in the C ABI. Asserts the full leaf roster + code
    # table — the seam where `FlatFilesUnavailable` / `PartialReconnect`
    # were invisible on Python / TypeScript, and where the `ConfigError`
    # leaf was missing.
    py_leaves = _collect_python_error_leaves(PY_ERRORS_RS)
    ts_leaves = _collect_typescript_error_leaves(TS_LIB_RS)
    cpp_leaves = _collect_cpp_error_leaves(CPP_HPP)
    ffi_codes = _collect_ffi_error_codes(FFI_ERROR_RS)
    ffi_codes_dispatched = _collect_ffi_error_codes_dispatched(FFI_ERROR_RS)
    cpp_codes = _collect_cpp_error_codes(CPP_H)
    error_leaf_errors = _check_error_leaf_parity(
        py_leaves,
        ts_leaves,
        cpp_leaves,
        ffi_codes,
        ffi_codes_dispatched,
        cpp_codes,
    )

    # Catch-all: every Python pyclass must be either tracked
    # explicitly or via the implicit pattern (mechanical parity).
    untracked: set[str] = {
        name
        for name in py_classes
        if name not in declared_names and not _is_implicitly_tracked(name)
    }

    had_errors = False
    if class_mismatches:
        had_errors = True
        print(
            f"check_binding_parity: {len(class_mismatches)} class-level "
            f"mismatch(es) vs sdks/parity.toml:"
        )
        for name, lang, declared, actual in class_mismatches:
            verb = "missing" if declared and not actual else "unexpected"
            print(f"  {name}.{lang}: declared={declared}, actual={actual} ({verb})")
        print()

    if field_errors:
        had_errors = True
        print(
            f"check_binding_parity: {len(field_errors)} field-level "
            f"mismatch(es) (#595 per-setter granularity):"
        )
        for e in field_errors:
            print(e)
        print()

    if method_errors:
        had_errors = True
        print(
            f"check_binding_parity: {len(method_errors)} method-level "
            f"mismatch(es) (per-method `[[method]]` granularity):"
        )
        for e in method_errors:
            print(e)
        print()

    if core_streaming_errors:
        had_errors = True
        print(
            f"check_binding_parity: {len(core_streaming_errors)} core "
            f"streaming observability accessor(s) lack a `[[method]]` row:"
        )
        for e in core_streaming_errors:
            print(e)
        print()

    if orphan_errors:
        had_errors = True
        print(
            f"check_binding_parity: {len(orphan_errors)} Rust pub "
            f"field(s) lack a parity-toml row:"
        )
        for e in orphan_errors:
            print(e)
        print()

    if value_field_errors:
        had_errors = True
        print(
            f"check_binding_parity: {len(value_field_errors)} value-field "
            f"TYPE mismatch(es) (per-field `[[value_field]]` granularity):"
        )
        for e in value_field_errors:
            print(f"  {e}")
        print()

    if value_field_roster_errors:
        had_errors = True
        print(
            f"check_binding_parity: {len(value_field_roster_errors)} "
            f"value-field roster gap(s) (unit/identity field unpinned):"
        )
        for e in value_field_roster_errors:
            print(e)
        print()

    if utility_errors:
        had_errors = True
        print(
            f"check_binding_parity: {len(utility_errors)} free-function "
            f"mismatch(es) (per-utility `[[utility]]` granularity):"
        )
        for e in utility_errors:
            print(e)
        print()

    if utility_roster_errors:
        had_errors = True
        print(
            f"check_binding_parity: {len(utility_roster_errors)} standalone "
            f"utility(ies) lack a `[[utility]]` row:"
        )
        for e in utility_roster_errors:
            print(e)
        print()

    if historical_streaming_errors:
        had_errors = True
        print(
            f"check_binding_parity: {len(historical_streaming_errors)} "
            f"historical-streaming mismatch(es) (per-endpoint "
            f"`[[historical_streaming]]` granularity):"
        )
        for e in historical_streaming_errors:
            print(e)
        print()

    if historical_async_errors:
        had_errors = True
        print(
            f"check_binding_parity: {len(historical_async_errors)} "
            f"historical-async mismatch(es) (per-endpoint "
            f"`[[historical_async]]` granularity):"
        )
        for e in historical_async_errors:
            print(e)
        print()

    if historical_base_errors:
        had_errors = True
        print(
            f"check_binding_parity: {len(historical_base_errors)} "
            f"historical-base mismatch(es) (per-endpoint "
            f"`[[historical_base]]` granularity):"
        )
        for e in historical_base_errors:
            print(e)
        print()

    if from_file_errors:
        had_errors = True
        print(
            f"check_binding_parity: {len(from_file_errors)} "
            f"client construction-from-file mismatch(es) (per-client "
            f"`[[from_file]]` granularity):"
        )
        for e in from_file_errors:
            print(e)
        print()

    if connect_errors:
        had_errors = True
        print(
            f"check_binding_parity: {len(connect_errors)} "
            f"client construction mismatch(es) (per-client "
            f"`[[connect]]` granularity):"
        )
        for e in connect_errors:
            print(e)
        print()

    if surface_vocab_errors:
        had_errors = True
        print(
            f"check_binding_parity: {len(surface_vocab_errors)} public "
            f"identifier(s) embed an implementation-detail token:"
        )
        for e in surface_vocab_errors:
            print(e)
        print()

    if setter_set_errors:
        had_errors = True
        print(
            f"check_binding_parity: {len(setter_set_errors)} client-facing "
            f"setter(s) diverge across bindings (set-level parity):"
        )
        for e in setter_set_errors:
            print(e)
        print()

    if getter_set_errors:
        had_errors = True
        print(
            f"check_binding_parity: {len(getter_set_errors)} client-facing "
            f"getter(s) diverge across bindings (set-level parity):"
        )
        for e in getter_set_errors:
            print(e)
        print()

    if subscription_kind_errors:
        had_errors = True
        print(
            f"check_binding_parity: {len(subscription_kind_errors)} "
            f"subscription-kind label divergence(s) across bindings:"
        )
        for e in subscription_kind_errors:
            print(e)
        print()

    if error_leaf_errors:
        had_errors = True
        print(
            f"check_binding_parity: {len(error_leaf_errors)} error-leaf "
            f"mapping divergence(s) across bindings:"
        )
        for e in error_leaf_errors:
            print(e)
        print()

    if untracked:
        had_errors = True
        print(
            f"check_binding_parity: {len(untracked)} pyclass(es) lack a "
            "parity row AND do not match any implicit pattern:"
        )
        for name in sorted(untracked):
            print(f"  {name}")
        print()

    if had_errors:
        print(
            "Fix: either land the missing binding, or update "
            "sdks/parity.toml to reflect the intended state. Every "
            "cross-binding asymmetry must be explicit + tracked."
        )
        return 1

    n_dotted = sum(1 for row in rows if "." in row["name"])
    n_class = len(rows) - n_dotted
    n_fields = sum(len(v) for v in rust_fields.values())
    n_methods = len(method_rows)
    n_value_fields = len(value_field_rows)
    n_utilities = len(utility_rows)
    n_hist_stream = len(historical_streaming_rows)
    n_hist_async = len(historical_async_rows)
    n_hist_base = len(historical_base_rows)
    n_from_file = len(from_file_rows)
    n_connect = len(connect_rows)
    print(
        f"check_binding_parity: clean "
        f"({n_class} class rows + {n_dotted} field rows + "
        f"{n_methods} method rows + {n_value_fields} value-field rows + "
        f"{n_utilities} utility rows + "
        f"{n_hist_stream} historical-streaming rows + "
        f"{n_hist_async} historical-async rows + "
        f"{n_hist_base} historical-base rows + "
        f"{n_from_file} from-file rows + "
        f"{n_connect} connect rows + "
        f"{n_fields} rust pub fields checked; "
        f"py_classes={len(py_classes)} ts_classes={len(ts_classes)} "
        f"cpp_classes={len(cpp_classes)} "
        f"py_setters={len(py_setters)} ts_setters={len(ts_setters)} "
        f"cpp_setters={len(cpp_setters)} ffi_setters={len(ffi_setters)}; "
        f"getters py={len(py_getters)} ts={len(ts_getters)} "
        f"cpp={len(cpp_getters)} ffi={len(ffi_getters)}; "
        f"kinds={len(CANONICAL_SUBSCRIPTION_KINDS)} "
        f"error_leaves={len(CANONICAL_ERROR_LEAVES)} "
        f"error_codes={len(CANONICAL_ERROR_CODES)})"
    )
    return 0


# ─── Selftest ───────────────────────────────────────────────────────


def _run_selftest() -> int:
    """In-process synthetic-source matrix covering the audit cases.

    Each test materialises a temporary tree with the binding sources
    needed to exercise one specific pass/fail axis, then invokes the
    parity-row evaluator. The selftest is intentionally hermetic — it
    does not touch the live `sdks/` tree, so running it never depends
    on the current state of the production bindings.
    """
    n_pass = 0
    n_fail = 0

    def _case(label: str, fn) -> None:
        nonlocal n_pass, n_fail
        try:
            fn()
        except AssertionError as e:
            n_fail += 1
            print(f"  selftest FAIL: {label}: {e}")
        else:
            n_pass += 1

    def _case_positive_all_bound() -> None:
        """All four bindings expose the field — gate is silent."""
        rows = [
            {
                "name": "FlatFilesConfig.max_attempts",
                "python": True,
                "typescript": True,
                "cpp": True,
            }
        ]
        py_setters = {"flatfiles_max_attempts"}
        ts_setters = {"flatfiles_max_attempts"}
        cpp_setters = {"flatfiles_max_attempts"}
        ffi_setters = {"flatfiles_max_attempts"}
        errors = _check_dotted_rows(rows, py_setters, ts_setters, cpp_setters, ffi_setters)
        assert errors == [], f"positive case must be silent; got {errors!r}"

    def _case_negative_missing_on_ts() -> None:
        """Python+C++ bound, TS missing — gate trips."""
        rows = [
            {
                "name": "FlatFilesConfig.max_attempts",
                "python": True,
                "typescript": True,
                "cpp": True,
            }
        ]
        py_setters = {"flatfiles_max_attempts"}
        ts_setters: set[str] = set()
        cpp_setters = {"flatfiles_max_attempts"}
        ffi_setters = {"flatfiles_max_attempts"}
        errors = _check_dotted_rows(rows, py_setters, ts_setters, cpp_setters, ffi_setters)
        assert any("typescript" in e and "missing" in e for e in errors), (
            f"negative TS case must surface missing setter; got {errors!r}"
        )

    def _case_negative_missing_on_cpp() -> None:
        rows = [
            {
                "name": "FlatFilesConfig.max_attempts",
                "python": True,
                "typescript": True,
                "cpp": True,
            }
        ]
        py_setters = {"flatfiles_max_attempts"}
        ts_setters = {"flatfiles_max_attempts"}
        cpp_setters: set[str] = set()
        ffi_setters = {"flatfiles_max_attempts"}
        errors = _check_dotted_rows(rows, py_setters, ts_setters, cpp_setters, ffi_setters)
        assert any("cpp" in e and "missing" in e for e in errors), (
            f"negative C++ case must surface missing setter; got {errors!r}"
        )

    def _case_negative_missing_on_ffi() -> None:
        """C++ claims bound but no FFI symbol — gate trips."""
        rows = [
            {
                "name": "FlatFilesConfig.max_attempts",
                "python": False,
                "typescript": False,
                "cpp": True,
            }
        ]
        py_setters: set[str] = set()
        ts_setters: set[str] = set()
        cpp_setters = {"flatfiles_max_attempts"}
        ffi_setters: set[str] = set()
        errors = _check_dotted_rows(rows, py_setters, ts_setters, cpp_setters, ffi_setters)
        assert any("ffi" in e for e in errors), (
            f"missing FFI symbol under cpp=true must trip the gate; got {errors!r}"
        )

    def _case_positive_python_only_no_ffi_required() -> None:
        """Python-only setter without FFI symbol must NOT trip the
        gate. Python (pyo3) mutates `DirectConfig` directly through
        the inner mutex; no FFI forwarding is required.
        """
        rows = [
            {
                "name": "HistoricalConfig.host",
                "python": True,
                "typescript": False,
                "cpp": False,
            }
        ]
        py_setters = {"host"}
        errors = _check_dotted_rows(rows, py_setters, set(), set(), set())
        assert errors == [], (
            f"Python-only setter must not require FFI symbol; got {errors!r}"
        )

    def _case_negative_unexpected_setter() -> None:
        """Row declares not-bound but binding setter exists — trips."""
        rows = [
            {
                "name": "FlatFilesConfig.max_attempts",
                "python": False,
                "typescript": False,
                "cpp": False,
                "rust_only": True,
                "issue": "#999",
            }
        ]
        py_setters = {"flatfiles_max_attempts"}  # unexpectedly bound
        # Rust-only path skips the per-language setter check; instead
        # the contract is: row is fully `false`. We fold this into the
        # `rust_only` consistency check by setting a column `true`
        # on a `rust_only` row → that's caught.
        errors = _check_dotted_rows(rows, py_setters, set(), set(), set())
        # The Rust-only case doesn't currently inspect actual setter
        # state (the row's contract is documentation-only). Still, a
        # `rust_only = true` row with a `true` column is the symmetric
        # mismatch covered by a separate selftest.
        assert errors == [], f"rust_only row must skip setter checks; got {errors!r}"

    def _case_negative_rust_only_without_issue() -> None:
        rows = [
            {
                "name": "StreamingConfig.timeout_ms",
                "python": False,
                "typescript": False,
                "cpp": False,
                "rust_only": True,
            }
        ]
        errors = _check_dotted_rows(rows, set(), set(), set(), set())
        assert any("issue" in e for e in errors), (
            f"rust_only without issue must trip; got {errors!r}"
        )

    def _case_negative_issue_without_rust_only() -> None:
        rows = [
            {
                "name": "StreamingConfig.timeout_ms",
                "python": False,
                "typescript": False,
                "cpp": False,
                "issue": "#999",
            }
        ]
        errors = _check_dotted_rows(rows, set(), set(), set(), set())
        assert any("not `rust_only`" in e for e in errors), (
            f"issue without rust_only must trip; got {errors!r}"
        )

    def _case_negative_rust_only_with_binding_true() -> None:
        rows = [
            {
                "name": "StreamingConfig.timeout_ms",
                "python": True,  # contradicts rust_only
                "typescript": False,
                "cpp": False,
                "rust_only": True,
                "issue": "#999",
            }
        ]
        errors = _check_dotted_rows(rows, set(), set(), set(), set())
        assert any("rust_only = true" in e for e in errors), (
            f"rust_only with binding=true must trip; got {errors!r}"
        )

    def _case_orphan_rust_field_trips() -> None:
        """A pub field with no parity row must surface a clear error."""
        with tempfile.TemporaryDirectory() as tmp:
            cfg_dir = pathlib.Path(tmp) / "config"
            cfg_dir.mkdir()
            (cfg_dir / "fake.rs").write_text(
                "pub struct FlatFilesConfig {\n"
                "    pub max_attempts: u32,\n"
                "    pub novel_field: u64,\n"
                "}\n",
                encoding="utf-8",
            )
            rust_fields = _collect_rust_pub_fields(cfg_dir)
            assert "max_attempts" in rust_fields["FlatFilesConfig"], (
                f"max_attempts must parse; got {rust_fields!r}"
            )
            assert "novel_field" in rust_fields["FlatFilesConfig"], (
                f"novel_field must parse; got {rust_fields!r}"
            )
            rows = [
                {
                    "name": "FlatFilesConfig.max_attempts",
                    "python": True,
                    "typescript": True,
                    "cpp": True,
                }
            ]
            errors = _check_orphan_rust_fields(rust_fields, rows)
            assert any("novel_field" in e for e in errors), (
                f"undocumented pub field must trip; got {errors!r}"
            )

    def _case_explicit_widened_abi_accepted() -> None:
        """`<canonical>_explicit` suffix counts as the same setter."""
        rows = [
            {
                "name": "RuntimeConfig.tokio_worker_threads",
                "python": True,
                "typescript": True,
                "cpp": True,
            }
        ]
        # FFI emits `thetadatadx_config_set_tokio_worker_threads_explicit`;
        # that must satisfy the `tokio_worker_threads` row.
        ffi_setters = {"tokio_worker_threads_explicit", "tokio_worker_threads"}
        py_setters = {"tokio_worker_threads"}
        ts_setters = {"tokio_worker_threads"}
        cpp_setters = {"tokio_worker_threads"}
        errors = _check_dotted_rows(rows, py_setters, ts_setters, cpp_setters, ffi_setters)
        assert errors == [], (
            f"_explicit widened-ABI shape must satisfy the row; got {errors!r}"
        )

    _case("positive — all four bindings expose the field", _case_positive_all_bound)
    _case("negative — TS setter missing", _case_negative_missing_on_ts)
    _case("negative — C++ setter missing", _case_negative_missing_on_cpp)
    _case("negative — FFI symbol missing under cpp=true", _case_negative_missing_on_ffi)
    _case("positive — Python-only setter does not require FFI symbol", _case_positive_python_only_no_ffi_required)
    _case("negative — rust_only row with stray setter is documented-only", _case_negative_unexpected_setter)
    _case("negative — rust_only without issue trips", _case_negative_rust_only_without_issue)
    _case("negative — issue without rust_only trips", _case_negative_issue_without_rust_only)
    _case("negative — rust_only with binding=true trips", _case_negative_rust_only_with_binding_true)
    _case("orphan — undocumented Rust pub field trips", _case_orphan_rust_field_trips)
    _case("positive — `_explicit` widened-ABI suffix accepted", _case_explicit_widened_abi_accepted)

    def _case_authconfig_metricsconfig_prefixes_resolve() -> None:
        """`AuthConfig` + `MetricsConfig` are in scope (issue #608).
        Dotted rows on these structs must resolve through the prefix
        table — not skip with `prefix is None` — so a future binding
        sweep can flip the rows from `rust_only = true` to fully-bound
        and the gate catches missing setters.
        """
        # Confirm both structs resolve to a known prefix (empty string
        # for `AuthConfig`, `metrics_` for `MetricsConfig`).
        assert STRUCT_TO_PREFIX.get("AuthConfig") is not None, (
            "AuthConfig must be in STRUCT_TO_PREFIX after #608"
        )
        assert STRUCT_TO_PREFIX.get("MetricsConfig") is not None, (
            "MetricsConfig must be in STRUCT_TO_PREFIX after #608"
        )
        # A rust_only row resolves cleanly through the new prefix.
        rows = [
            {
                "name": "AuthConfig.nexus_url",
                "python": False,
                "typescript": False,
                "cpp": False,
                "rust_only": True,
                "issue": "#608",
            },
            {
                "name": "MetricsConfig.port",
                "python": False,
                "typescript": False,
                "cpp": False,
                "rust_only": True,
                "issue": "#608",
            },
        ]
        errors = _check_dotted_rows(rows, set(), set(), set(), set())
        assert errors == [], (
            f"AuthConfig + MetricsConfig rust_only rows must be silent; got {errors!r}"
        )

    _case(
        "positive — AuthConfig + MetricsConfig dotted rows resolve through new prefixes",
        _case_authconfig_metricsconfig_prefixes_resolve,
    )

    # ── Method-level gate selftests ────────────────────────────────

    def _case_method_positive_all_three() -> None:
        """Method declared on Python + TS + C++ — gate is silent."""
        rows = [
            {
                "class": "Client",
                "name": "panicCount",
                "python": True,
                "typescript": True,
                "cpp": True,
            }
        ]
        py_methods = {"Client": {"panic_count"}}
        ts_methods = {"Client": {"panicCount"}}
        cpp_methods = {"Client": {"panic_count"}}
        errors = _check_method_rows(rows, py_methods, ts_methods, cpp_methods)
        assert errors == [], f"method positive case must be silent; got {errors!r}"

    def _case_method_python_missing() -> None:
        """Declared on Python but not present in source — trips."""
        rows = [
            {
                "class": "Client",
                "name": "panicCount",
                "python": True,
                "typescript": True,
                "cpp": True,
            }
        ]
        py_methods: dict[str, set[str]] = {"Client": set()}
        ts_methods = {"Client": {"panicCount"}}
        cpp_methods = {"Client": {"panic_count"}}
        errors = _check_method_rows(rows, py_methods, ts_methods, cpp_methods)
        assert any("python" in e and "missing" in e for e in errors), (
            f"missing Python method must trip the gate; got {errors!r}"
        )

    def _case_method_typescript_missing() -> None:
        """Declared on TS but no matching `js_name` in source — trips."""
        rows = [
            {
                "class": "Client",
                "name": "activeFullSubscriptions",
                "python": True,
                "typescript": True,
                "cpp": True,
            }
        ]
        py_methods = {"Client": {"active_full_subscriptions"}}
        ts_methods: dict[str, set[str]] = {}
        cpp_methods = {"Client": {"active_full_subscriptions"}}
        errors = _check_method_rows(rows, py_methods, ts_methods, cpp_methods)
        assert any("typescript" in e and "missing" in e for e in errors), (
            f"missing TS method must trip the gate; got {errors!r}"
        )

    def _case_method_cpp_alias_resolves() -> None:
        """C++ alias (`Contract` -> `FluentContract`) is honoured."""
        rows = [
            {
                "class": "Contract",
                "name": "quote",
                "python": True,
                "typescript": True,
                "cpp": True,
            }
        ]
        py_methods = {"Contract": {"quote"}}
        ts_methods = {"Contract": {"quote"}}
        # The row says `Contract` but the C++ class is named
        # `FluentContract` — the alias table must route the lookup.
        cpp_methods = {"FluentContract": {"quote"}}
        errors = _check_method_rows(rows, py_methods, ts_methods, cpp_methods)
        assert errors == [], (
            f"C++ alias must resolve to FluentContract; got {errors!r}"
        )

    def _case_method_cpp_get_prefix_resolves() -> None:
        """C++ readback getter with the `get_` prefix matches a bare row."""
        rows = [
            {
                "class": "Config",
                "name": "flushMode",
                "python": True,
                "typescript": True,
                "cpp": True,
            }
        ]
        py_methods = {"Config": {"flush_mode"}}
        ts_methods = {"Config": {"flushMode"}}
        # C++ exposes the readback getter as `get_flush_mode`; the gate
        # accepts the `get_`-prefixed convention against the bare row.
        cpp_methods = {"Config": {"get_flush_mode"}}
        errors = _check_method_rows(rows, py_methods, ts_methods, cpp_methods)
        assert errors == [], (
            f"C++ `get_`-prefixed getter must satisfy a bare row; got {errors!r}"
        )

    def _case_method_python_get_prefix_resolves() -> None:
        """Python `#[getter] fn get_<x>` satisfies a bare getter row.

        pyo3 strips the `get_` prefix so the Python property name stays
        bare (`config.flush_mode`), but the Rust fn name the collector
        harvests carries the prefix. The gate must accept `get_flush_mode`
        against the bare `flushMode` row, exactly as it does for C++.
        """
        rows = [
            {
                "class": "Config",
                "name": "flushMode",
                "python": True,
                "typescript": True,
                "cpp": True,
            }
        ]
        # Python exposes the readback getter as `fn get_flush_mode`.
        py_methods = {"Config": {"get_flush_mode"}}
        ts_methods = {"Config": {"flushMode"}}
        cpp_methods = {"Config": {"get_flush_mode"}}
        errors = _check_method_rows(rows, py_methods, ts_methods, cpp_methods)
        assert errors == [], (
            f"Python `get_`-prefixed getter must satisfy a bare row; got {errors!r}"
        )

    def _case_method_unexpected_extra() -> None:
        """Declared `false` but method exists on the source — trips."""
        rows = [
            {
                "class": "Client",
                "name": "panicCount",
                "python": False,
                "typescript": False,
                "cpp": False,
            }
        ]
        py_methods = {"Client": {"panic_count"}}
        ts_methods = {"Client": {"panicCount"}}
        cpp_methods = {"Client": {"panic_count"}}
        errors = _check_method_rows(rows, py_methods, ts_methods, cpp_methods)
        # All three columns are stale — every binding now exposes the
        # method but the row still says `false`.
        assert any("unexpected" in e for e in errors), (
            f"stale `false` rows must trip the gate; got {errors!r}"
        )

    def _case_method_row_missing_class_or_name() -> None:
        """Malformed row — gate surfaces a clear error."""
        rows = [
            {"class": "Client", "python": True},
            {"name": "panicCount", "python": True},
        ]
        errors = _check_method_rows(rows, {}, {}, {})
        assert len(errors) == 2, (
            f"malformed rows must each trip the gate; got {errors!r}"
        )

    def _case_method_class_scoping_isolates_classes() -> None:
        """A method present on ClassA must NOT count for ClassB.

        Previously the TS collector used a single universe set; now
        every method is scoped to its owning class. This protects
        against false-positive 'unexpected' verdicts when two classes
        coincidentally share a method name (`subscribe` on both
        `Client` and `Subscription` etc.).
        """
        rows = [
            {
                "class": "StreamingClient",  # StreamingClient not on TS
                "name": "subscribe",
                "python": True,
                "typescript": False,
                "cpp": True,
            }
        ]
        # `subscribe` exists on `Client` (TS) but NOT on
        # `StreamingClient` (TS). Class-scoped lookup must respect that.
        py_methods = {"StreamingClient": {"subscribe"}}
        ts_methods = {"Client": {"subscribe"}}
        cpp_methods = {"StreamingClient": {"subscribe"}}
        errors = _check_method_rows(rows, py_methods, ts_methods, cpp_methods)
        assert errors == [], (
            f"class-scoped TS lookup must not leak across classes; got {errors!r}"
        )

    def _case_core_streaming_positive_all_enrolled() -> None:
        """Every core observability accessor has a `[[method]]` row —
        gate is silent. Covers the `dropped_count` -> `droppedEventCount`
        and `set_slow_callback_threshold` -> `setSlowCallbackThresholdUs`
        renames plus the direct camelCase mappings."""
        core_methods = {
            "StreamSurface": {
                "dropped_event_count",
                "ring_occupancy",
                "ring_capacity",
                "panic_count",
                "slow_callback_count",
                "set_slow_callback_threshold",
            },
            "StreamingClient": {
                "dropped_count",
                "ring_occupancy",
                "ring_capacity",
                "panic_count",
                "slow_callback_count",
                "set_slow_callback_threshold",
            },
        }
        rows = [
            {"class": "StreamView", "name": n}
            for n in (
                "droppedEventCount",
                "ringOccupancy",
                "ringCapacity",
                "panicCount",
                "slowCallbackCount",
                "setSlowCallbackThresholdUs",
            )
        ] + [
            {"class": "StreamingClient", "name": n}
            for n in (
                "droppedEventCount",
                "ringOccupancy",
                "ringCapacity",
                "panicCount",
                "slowCallbackCount",
                "setSlowCallbackThresholdUs",
            )
        ]
        errors = _check_core_streaming_method_rows(core_methods, rows)
        assert errors == [], (
            f"fully-enrolled core observability surface must be silent; got {errors!r}"
        )

    def _case_core_streaming_negative_unenrolled_getter() -> None:
        """A wired core counter with no `[[method]]` row trips the gate —
        the exact blind spot this check closes."""
        core_methods = {"StreamSurface": {"slow_callback_count"}}
        rows: list[dict[str, Any]] = []  # no enrolling row
        errors = _check_core_streaming_method_rows(core_methods, rows)
        assert any("slow_callback_count" in e and "slowCallbackCount" in e for e in errors), (
            f"unenrolled core counter must trip the gate; got {errors!r}"
        )

    def _case_core_streaming_negative_unenrolled_setter() -> None:
        """A wired core threshold setter with no row trips, mapped to the
        unit-suffixed binding row name."""
        core_methods = {"StreamingClient": {"set_slow_callback_threshold"}}
        rows: list[dict[str, Any]] = []
        errors = _check_core_streaming_method_rows(core_methods, rows)
        assert any("setSlowCallbackThresholdUs" in e for e in errors), (
            f"unenrolled core setter must trip the gate; got {errors!r}"
        )

    def _case_core_streaming_internal_hook_ignored() -> None:
        """`record_panic` (the internal fault-injection hook) is not an
        observability accessor, so the harvester never surfaces it and it
        never needs a row. The predicate is the filter; assert it
        directly. Lifecycle / subscription methods are likewise excluded."""
        assert not _is_core_observability_accessor("record_panic"), (
            "record_panic must be excluded from the observability surface"
        )
        for non_obs in ("subscribe", "stop_streaming", "reconnect", "is_streaming"):
            assert not _is_core_observability_accessor(non_obs), (
                f"{non_obs} must not be treated as an observability accessor"
            )
        # The shape predicate accepts the genuine observability accessors.
        for obs in (
            "dropped_count",
            "ring_occupancy",
            "panic_count",
            "slow_callback_count",
            "set_slow_callback_threshold",
        ):
            assert _is_core_observability_accessor(obs), (
                f"{obs} must be treated as an observability accessor"
            )

    _case(
        "core-streaming positive — every observability accessor enrolled",
        _case_core_streaming_positive_all_enrolled,
    )
    _case(
        "core-streaming negative — unenrolled counter trips",
        _case_core_streaming_negative_unenrolled_getter,
    )
    _case(
        "core-streaming negative — unenrolled threshold setter trips",
        _case_core_streaming_negative_unenrolled_setter,
    )
    _case(
        "core-streaming positive — internal record_panic hook ignored",
        _case_core_streaming_internal_hook_ignored,
    )

    _case("method positive — declared and present on all three bindings", _case_method_positive_all_three)
    _case("method negative — declared Python but missing in source", _case_method_python_missing)
    _case("method negative — declared TS but missing js_name", _case_method_typescript_missing)
    _case("method positive — C++ alias routes Contract -> FluentContract", _case_method_cpp_alias_resolves)
    _case("method positive — C++ `get_` prefix satisfies a bare getter row", _case_method_cpp_get_prefix_resolves)
    _case("method positive — Python `get_` prefix satisfies a bare getter row", _case_method_python_get_prefix_resolves)
    _case("method negative — stale `false` row with method present", _case_method_unexpected_extra)
    _case("method negative — malformed row missing class or name", _case_method_row_missing_class_or_name)
    _case("method positive — class-scoped TS lookup isolates classes", _case_method_class_scoping_isolates_classes)

    def _case_flatfiles_namespace_fetch_resolves() -> None:
        """A `FlatFilesNamespace` fetch row resolves through the C++ alias to the
        `FlatFiles` class and against the snake/camel per-binding spellings."""
        rows = [
            {
                "class": "FlatFilesNamespace",
                "name": "optionTradeQuote",
                "python": True,
                "typescript": True,
                "cpp": True,
            }
        ]
        py_methods = {"FlatFilesNamespace": {"option_trade_quote"}}
        ts_methods = {"FlatFilesNamespace": {"optionTradeQuote"}}
        # The row says `FlatFilesNamespace`; the C++ class is `FlatFiles`.
        cpp_methods = {"FlatFiles": {"option_trade_quote"}}
        errors = _check_method_rows(rows, py_methods, ts_methods, cpp_methods)
        assert errors == [], (
            f"flat-file fetch row must resolve across bindings; got {errors!r}"
        )

    def _case_flatfiles_to_path_override_resolves() -> None:
        """The blob-to-disk helper resolves through `METHOD_BINDING_OVERRIDES`:
        Python `Client.flatfile_to_path`, TS `Client.flatFileToPath`, C++
        `FlatFiles::to_path` — three divergent home classes / names, one row."""
        rows = [
            {
                "class": "FlatFilesNamespace",
                "name": "flatFileToPath",
                "python": True,
                "typescript": True,
                "cpp": True,
            }
        ]
        py_methods = {"Client": {"flatfile_to_path"}}
        ts_methods = {"Client": {"flatFileToPath"}}
        cpp_methods = {"FlatFiles": {"to_path"}}
        errors = _check_method_rows(rows, py_methods, ts_methods, cpp_methods)
        assert errors == [], (
            f"to-path override must resolve each binding's home class; got {errors!r}"
        )

    def _case_flatfiles_to_path_override_drop_trips() -> None:
        """Dropping the C++ `to_path` member trips the overridden row — the
        override must still gate, not silently pass."""
        rows = [
            {
                "class": "FlatFilesNamespace",
                "name": "flatFileToPath",
                "python": True,
                "typescript": True,
                "cpp": True,
            }
        ]
        py_methods = {"Client": {"flatfile_to_path"}}
        ts_methods = {"Client": {"flatFileToPath"}}
        cpp_methods = {"FlatFiles": set()}  # `to_path` dropped on C++
        errors = _check_method_rows(rows, py_methods, ts_methods, cpp_methods)
        assert any("flatFileToPath" in e and ".cpp" in e for e in errors), (
            f"dropped C++ to_path must trip the overridden row; got {errors!r}"
        )

    def _case_flatfiles_namespace_orphan_trips() -> None:
        """A fetch method present on the namespace class with no enrolling row
        trips the reverse-orphan scan."""
        rows = [
            {
                "class": "FlatFilesNamespace",
                "name": "optionTradeQuote",
                "python": True,
                "typescript": True,
                "cpp": True,
            }
        ]
        # `indexEod` is present on the namespace but carries no row.
        py_methods = {"FlatFilesNamespace": {"option_trade_quote", "index_eod"}}
        ts_methods = {"FlatFilesNamespace": {"optionTradeQuote", "indexEod"}}
        cpp_methods = {"FlatFiles": {"option_trade_quote", "index_eod"}}
        errors = _check_method_rows(rows, py_methods, ts_methods, cpp_methods)
        assert any("index_eod" in e and "no `[[method]]` row" in e for e in errors), (
            f"unenrolled namespace fetch method must trip the gate; got {errors!r}"
        )

    def _case_flatfiles_namespace_artifacts_exempt() -> None:
        """Collector artifacts on the namespace class (C++ `handle_` / the FFI
        externs, Python `pull_decoded`, the override-enrolled C++ `to_path`) do
        NOT trip the reverse-orphan scan."""
        rows = [
            {"class": "FlatFilesNamespace", "name": n, "python": True, "typescript": True, "cpp": True}
            for n in sorted(FLATFILES_NAMESPACE_METHODS)
        ] + [
            {"class": "FlatFilesNamespace", "name": "flatFileToPath", "python": True, "typescript": True, "cpp": True}
        ]
        py_methods = {
            "FlatFilesNamespace": {_camel_to_snake(n) for n in FLATFILES_NAMESPACE_METHODS} | {"pull_decoded"},
            "Client": {"flatfile_to_path"},
        }
        ts_methods = {"FlatFilesNamespace": set(FLATFILES_NAMESPACE_METHODS), "Client": {"flatFileToPath"}}
        cpp_methods = {
            "FlatFiles": {_camel_to_snake(n) for n in FLATFILES_NAMESPACE_METHODS}
            | {"handle_", "to_path", "thetadatadx_flatfile_request_decoded", "thetadatadx_flatfile_request_to_path"},
        }
        errors = _check_method_rows(rows, py_methods, ts_methods, cpp_methods)
        assert errors == [], (
            f"namespace collector artifacts must stay exempt; got {errors!r}"
        )

    _case("flatfiles positive — namespace fetch row resolves via C++ alias", _case_flatfiles_namespace_fetch_resolves)
    _case("flatfiles positive — to-path override resolves divergent homes", _case_flatfiles_to_path_override_resolves)
    _case("flatfiles negative — dropped C++ to_path trips overridden row", _case_flatfiles_to_path_override_drop_trips)
    _case("flatfiles negative — unenrolled namespace fetch method trips", _case_flatfiles_namespace_orphan_trips)
    _case("flatfiles positive — namespace collector artifacts exempt", _case_flatfiles_namespace_artifacts_exempt)

    def _case_value_field_positive_matches() -> None:
        """Declared Rust + C++ field types match the sources — gate silent."""
        with tempfile.TemporaryDirectory() as tmp:
            py_dir = pathlib.Path(tmp) / "py"
            py_dir.mkdir()
            (py_dir / "gen.rs").write_text(
                "pub struct OptionContract {\n"
                "    #[pyo3(get)] pub right: String,\n"
                "}\n",
                encoding="utf-8",
            )
            hpp = pathlib.Path(tmp) / "thetadatadx.hpp"
            hpp.write_text(
                "struct OptionContract {\n    char right;\n}\n",
                encoding="utf-8",
            )
            assert _struct_field_type(py_dir, "OptionContract", "right") == "String"
            assert _cpp_struct_field_type(hpp, "OptionContract", "right") == "char"

    def _case_value_field_rust_type_mismatch_trips() -> None:
        """A Rust field whose type drifted from the declared one trips."""
        with tempfile.TemporaryDirectory() as tmp:
            py_dir = pathlib.Path(tmp) / "py"
            py_dir.mkdir()
            (py_dir / "gen.rs").write_text(
                "pub struct ContractRef {\n"
                "    #[pyo3(get)] pub strike: Option<i32>,\n"
                "}\n",
                encoding="utf-8",
            )
            # The declared type is dollars (f64); the source drifted to i32.
            actual = _struct_field_type(py_dir, "ContractRef", "strike")
            assert actual == "Option<i32>", f"reader must see the drift; got {actual!r}"
            assert actual != "Option<f64>", "the strike-units regression must not read as clean"

    def _case_value_field_cpp_type_mismatch_trips() -> None:
        """A C++ value struct that surfaces the raw integer trips."""
        with tempfile.TemporaryDirectory() as tmp:
            hpp = pathlib.Path(tmp) / "thetadatadx.hpp"
            hpp.write_text(
                "struct OptionContract {\n    int32_t right;\n}\n",
                encoding="utf-8",
            )
            actual = _cpp_struct_field_type(hpp, "OptionContract", "right")
            assert actual == "int32_t", f"reader must see the int; got {actual!r}"
            assert actual != "char", "the right-as-int regression must not read as clean"

    _case("value_field positive — Rust + C++ types match the declared", _case_value_field_positive_matches)
    _case("value_field negative — Rust strike type drift trips", _case_value_field_rust_type_mismatch_trips)
    _case("value_field negative — C++ right-as-int trips", _case_value_field_cpp_type_mismatch_trips)

    # ── Subscription-builder method resolution selftests ───────────

    def _case_builder_method_py_ts_aliases_resolve() -> None:
        """A `Contract` builder row resolves against the Python `PyContract`
        struct key and the TypeScript `ContractRef` impl key."""
        rows = [
            {
                "class": "Contract",
                "name": "quote",
                "python": True,
                "typescript": True,
                "cpp": True,
            }
        ]
        # Production collectors key Python by the Rust struct and TS by the
        # napi impl — the row uses the canonical `Contract` name.
        py_methods = {"PyContract": {"quote"}}
        ts_methods = {"ContractRef": {"quote"}}
        cpp_methods = {"FluentContract": {"quote"}}
        errors = _check_method_rows(rows, py_methods, ts_methods, cpp_methods)
        assert errors == [], (
            f"Contract builder must resolve through Py/TS aliases; got {errors!r}"
        )

    def _case_builder_method_sectype_full_stream_resolves() -> None:
        """`SecType.fullTrades` resolves on `PySecType` (py) + `SecType` (ts)."""
        rows = [
            {
                "class": "SecType",
                "name": "fullTrades",
                "python": True,
                "typescript": True,
                "cpp": True,
            }
        ]
        py_methods = {"PySecType": {"full_trades"}}
        ts_methods = {"SecType": {"fullTrades"}}
        cpp_methods = {"FluentSecType": {"full_trades"}}
        errors = _check_method_rows(rows, py_methods, ts_methods, cpp_methods)
        assert errors == [], (
            f"SecType full-stream builder must resolve; got {errors!r}"
        )

    def _case_builder_method_drop_trips() -> None:
        """Dropping a builder on one binding trips the per-method gate."""
        rows = [
            {
                "class": "Contract",
                "name": "quote",
                "python": True,
                "typescript": True,
                "cpp": True,
            }
        ]
        py_methods = {"PyContract": {"quote"}}
        ts_methods: dict[str, set[str]] = {"ContractRef": set()}  # dropped on TS
        cpp_methods = {"FluentContract": {"quote"}}
        errors = _check_method_rows(rows, py_methods, ts_methods, cpp_methods)
        assert any("typescript" in e and "missing" in e for e in errors), (
            f"a dropped builder must trip the gate; got {errors!r}"
        )

    _case("builder method — Contract Py/TS aliases resolve", _case_builder_method_py_ts_aliases_resolve)
    _case("builder method — SecType full-stream resolves", _case_builder_method_sectype_full_stream_resolves)
    _case("builder method — dropped builder on TS trips", _case_builder_method_drop_trips)

    # ── Client construction (connect) selftests ────────────────────

    def _case_connect_positive_all_bound() -> None:
        """A C-ABI-backed client present on every surface is silent."""
        rows = [
            {
                "name": "Client",
                "python": True,
                "typescript": True,
                "cpp": True,
                "ffi": True,
            }
        ]
        errors = _check_connect_rows(
            rows, {"Client"}, {"Client"}, {"Client"}, {"client"}
        )
        assert errors == [], f"all-bound connect row must be silent; got {errors!r}"

    def _case_connect_python_only_async_client() -> None:
        """`AsyncClient` is Python-only — no stem, ffi=false, silent."""
        rows = [
            {
                "name": "AsyncClient",
                "python": True,
                "typescript": False,
                "cpp": False,
                "ffi": False,
            }
        ]
        errors = _check_connect_rows(rows, {"AsyncClient"}, set(), set(), set())
        assert errors == [], (
            f"Python-only AsyncClient connect row must be silent; got {errors!r}"
        )

    def _case_connect_missing_python_constructor_trips() -> None:
        """Row claims a Python constructor but the pyclass has none — trips."""
        rows = [
            {
                "name": "Client",
                "python": True,
                "typescript": True,
                "cpp": True,
                "ffi": True,
            }
        ]
        errors = _check_connect_rows(
            rows, set(), {"Client"}, {"Client"}, {"client"}
        )
        assert any("python" in e and "missing" in e for e in errors), (
            f"a missing #[new] constructor must trip; got {errors!r}"
        )

    def _case_connect_orphan_untracked_trips() -> None:
        """A client constructing on a binding with no row is undocumented."""
        rows: list[dict[str, Any]] = []
        errors = _check_connect_rows(
            rows, {"Client"}, {"Client"}, set(), {"client"}
        )
        assert any("no [[connect]] row" in e for e in errors), (
            f"an untracked connect surface must trip; got {errors!r}"
        )

    def _case_connect_ffi_stem_collector_skips_from_file() -> None:
        """The FFI connect collector matches `_connect(` but not
        `_connect_from_file`."""
        with tempfile.TemporaryDirectory() as tmp:
            ffi_dir = pathlib.Path(tmp) / "ffi"
            ffi_dir.mkdir()
            (ffi_dir / "c.rs").write_text(
                'pub unsafe extern "C" fn thetadatadx_client_connect(a: i32) {}\n'
                'pub unsafe extern "C" fn thetadatadx_client_connect_from_file(p: i32) {}\n',
                encoding="utf-8",
            )
            stems = _collect_ffi_connect_stems(ffi_dir)
            assert "client" in stems, f"base connect stem must be seen; got {stems!r}"
            assert "client_connect_from" not in stems, (
                f"from_file must not leak into the connect stems; got {stems!r}"
            )

    _case("connect positive — all-bound client silent", _case_connect_positive_all_bound)
    _case("connect positive — Python-only AsyncClient silent", _case_connect_python_only_async_client)
    _case("connect negative — missing #[new] constructor trips", _case_connect_missing_python_constructor_trips)
    _case("connect negative — untracked connect surface trips", _case_connect_orphan_untracked_trips)
    _case("connect — FFI stem collector skips _connect_from_file", _case_connect_ffi_stem_collector_skips_from_file)

    # ── C-ABI value-field + roster selftests ───────────────────────

    def _case_c_abi_struct_reader_reads_typedef_struct() -> None:
        """The C-ABI reader parses `typedef struct {...} <Name>;`."""
        with tempfile.TemporaryDirectory() as tmp:
            inc = pathlib.Path(tmp) / "structs.h.inc"
            inc.write_text(
                "typedef struct {\n"
                "const char *symbol;\n"
                "double strike;\n"
                "int32_t strike_thousandths;\n"
                "} ThetaDataDxContract;\n",
                encoding="utf-8",
            )
            assert (
                _c_abi_struct_field_type(inc, "ThetaDataDxContract", "strike_thousandths")
                == "int32_t"
            )
            assert (
                _c_abi_struct_field_type(inc, "ThetaDataDxContract", "strike") == "double"
            )

    def _case_value_field_roster_missing_trips() -> None:
        """A load-bearing class missing its pinned field trips the roster."""
        # `OptionContract.right` is in VALUE_FIELD_ROSTER; an empty matrix
        # must surface it (plus the other roster entries) as a gap.
        errors = _check_value_field_roster([])
        assert any("OptionContract.right" in e for e in errors), (
            f"roster gap must surface the unpinned field; got {errors!r}"
        )

    def _case_value_field_roster_complete_silent_on_roster() -> None:
        """With every roster pair present, the roster scan adds nothing
        for those pairs (vocabulary scan reads the live tree, so only the
        roster half is asserted here against a synthetic matrix)."""
        rows = [
            {"class": cls, "name": field}
            for cls, fields in VALUE_FIELD_ROSTER.items()
            for field in fields
        ]
        errors = _check_value_field_roster(rows)
        # No roster-half error should mention a roster pair.
        for cls, fields in VALUE_FIELD_ROSTER.items():
            for field in fields:
                assert not any(
                    f"{cls}.{field}: load-bearing" in e for e in errors
                ), f"roster pair {cls}.{field} must not be flagged; got {errors!r}"

    _case("value_field — C-ABI typedef-struct reader", _case_c_abi_struct_reader_reads_typedef_struct)
    _case("value_field — roster gap trips on missing pin", _case_value_field_roster_missing_trips)
    _case("value_field — roster silent when complete", _case_value_field_roster_complete_silent_on_roster)

    # ── Dotted anchor-row typo selftests ───────────────────────────

    def _case_anchor_row_valid_passes() -> None:
        """A recognized anchor suffix on a real class passes."""
        rows = [{"name": "GreeksEodTick.cross_binding_anchor", "python": True}]
        errors = _check_dotted_rows(
            rows, set(), set(), set(), set(), {"GreeksEodTick"}
        )
        assert errors == [], f"valid anchor must pass; got {errors!r}"

    def _case_anchor_row_typod_struct_trips() -> None:
        """An anchor on a nonexistent (typo'd) struct fails."""
        rows = [{"name": "GreksEodTick.cross_binding_anchor", "python": True}]
        errors = _check_dotted_rows(
            rows, set(), set(), set(), set(), {"GreeksEodTick"}
        )
        assert any("not a known binding class" in e for e in errors), (
            f"a typo'd anchor struct must trip; got {errors!r}"
        )

    def _case_anchor_row_bad_suffix_trips() -> None:
        """A dotted row on a non-config struct with an unknown suffix fails."""
        rows = [{"name": "GreeksEodTick.bogus_suffix", "python": True}]
        errors = _check_dotted_rows(
            rows, set(), set(), set(), set(), {"GreeksEodTick"}
        )
        assert any("unrecognized suffix" in e for e in errors), (
            f"an unrecognized anchor suffix must trip; got {errors!r}"
        )

    def _case_anchor_row_skipped_without_universe() -> None:
        """Without a class universe (selftest shape), anchor rows skip."""
        rows = [{"name": "Whatever.cross_binding_anchor", "python": True}]
        errors = _check_dotted_rows(rows, set(), set(), set(), set())
        assert errors == [], (
            f"anchor rows must skip when no universe is given; got {errors!r}"
        )

    _case("anchor row — valid suffix + real class passes", _case_anchor_row_valid_passes)
    _case("anchor row — typo'd struct trips", _case_anchor_row_typod_struct_trips)
    _case("anchor row — unrecognized suffix trips", _case_anchor_row_bad_suffix_trips)
    _case("anchor row — skipped without class universe", _case_anchor_row_skipped_without_universe)

    # ── StreamingSession exemption selftests ───────────────────────

    def _case_streaming_session_dunders_exempt() -> None:
        """The async-iterator / context dunders carry no contract — silent."""
        rows: list[dict[str, Any]] = []
        py_methods = {
            "StreamingSession": {"__aiter__", "__anext__", "__aenter__", "__aexit__"}
        }
        errors = _check_method_rows(rows, py_methods, {}, {})
        assert not any("StreamingSession" in e for e in errors), (
            f"session dunders must be exempt; got {errors!r}"
        )

    def _case_streaming_session_first_class_method_trips() -> None:
        """A first-class session method with no row trips the orphan scan."""
        rows: list[dict[str, Any]] = []
        py_methods = {"StreamingSession": {"drain_now"}}
        errors = _check_method_rows(rows, py_methods, {}, {})
        assert any("StreamingSession.drain_now" in e for e in errors), (
            f"an unenrolled first-class session method must trip; got {errors!r}"
        )

    _case("StreamingSession — async/context dunders exempt", _case_streaming_session_dunders_exempt)
    _case("StreamingSession — unenrolled first-class method trips", _case_streaming_session_first_class_method_trips)

    # ── Free-function (utility) parity selftests ───────────────────

    def _case_utility_positive_all_four_bound() -> None:
        """All four bindings expose the calculator function — silent."""
        rows = [
            {
                "name": "all_greeks",
                "python": True,
                "typescript": True,
                "cpp": True,
                "ffi": True,
            }
        ]
        errors = _check_utility_rows(
            rows,
            {"all_greeks"},
            {"all_greeks"},
            {"all_greeks"},
            {"all_greeks"},
        )
        assert errors == [], f"positive case must be silent; got {errors!r}"

    def _case_utility_negative_missing_on_ts() -> None:
        """Declared on TypeScript but absent from the TS source — trips."""
        rows = [
            {
                "name": "all_greeks",
                "python": True,
                "typescript": True,
                "cpp": True,
                "ffi": True,
            }
        ]
        errors = _check_utility_rows(
            rows,
            {"all_greeks"},
            set(),  # TS missing — the exact gap this matrix closes
            {"all_greeks"},
            {"all_greeks"},
        )
        assert any("typescript" in e and "missing" in e for e in errors), (
            f"missing TS free function must trip; got {errors!r}"
        )

    def _case_utility_negative_unexpected() -> None:
        """Row says not-on-C++ but the C++ decl exists — trips."""
        rows = [
            {
                "name": "implied_volatility",
                "python": True,
                "typescript": True,
                "cpp": False,
                "ffi": True,
            }
        ]
        errors = _check_utility_rows(
            rows,
            {"implied_volatility"},
            {"implied_volatility"},
            {"implied_volatility"},  # present despite cpp=false
            {"implied_volatility"},
        )
        assert any("cpp" in e and "unexpected" in e for e in errors), (
            f"unexpected C++ decl must trip; got {errors!r}"
        )

    def _case_utility_ts_free_fn_collector_skips_methods() -> None:
        """The TS collector records free functions but not impl methods."""
        with tempfile.TemporaryDirectory() as tmp:
            ts_dir = pathlib.Path(tmp) / "ts"
            ts_dir.mkdir()
            (ts_dir / "gen.rs").write_text(
                '#[napi(js_name = "allGreeks")]\n'
                "pub fn all_greeks(spot: f64) -> napi::Result<AllGreeks> { todo!() }\n"
                "\n"
                "#[napi]\n"
                "impl Client {\n"
                '    #[napi(js_name = "isStreaming")]\n'
                "    pub fn is_streaming(&self) -> bool { true }\n"
                "}\n",
                encoding="utf-8",
            )
            found = _collect_typescript_utility_functions(ts_dir)
            assert "all_greeks" in found, f"free fn must be seen; got {found!r}"
            assert "is_streaming" not in found, (
                f"impl method must NOT be seen as a free fn; got {found!r}"
            )

    def _case_utility_ffi_collector_strips_prefix() -> None:
        """The FFI collector strips the `thetadatadx_` prefix to the bare name."""
        with tempfile.TemporaryDirectory() as tmp:
            ffi_dir = pathlib.Path(tmp) / "ffi"
            ffi_dir.mkdir()
            (ffi_dir / "utility.rs").write_text(
                'pub unsafe extern "C" fn thetadatadx_all_greeks() {}\n'
                'pub unsafe extern "C" fn thetadatadx_implied_volatility() {}\n',
                encoding="utf-8",
            )
            found = _collect_ffi_utility_functions(ffi_dir)
            assert {"all_greeks", "implied_volatility"} <= found, (
                f"thetadatadx_-prefixed symbols must map to bare names; got {found!r}"
            )

    _case("utility positive — all four bindings expose the calculator", _case_utility_positive_all_four_bound)
    _case("utility negative — calculator missing on TS trips", _case_utility_negative_missing_on_ts)
    _case("utility negative — unexpected C++ decl trips", _case_utility_negative_unexpected)
    _case("utility — TS collector skips impl methods", _case_utility_ts_free_fn_collector_skips_methods)
    _case("utility — FFI collector strips thetadatadx_ prefix", _case_utility_ffi_collector_strips_prefix)

    # ── Historical server-stream surface selftests ────────────────

    def _case_hist_stream_positive_all_bound() -> None:
        """An endpoint streaming on every declared surface is silent."""
        rows = [
            {
                "name": "option_history_trade",
                "rust": True,
                "python": True,
                "typescript": True,
                "cpp": True,
                "ffi": True,
            }
        ]
        s = {"option_history_trade"}
        errors = _check_historical_streaming_rows(rows, s, s, s, s, s)
        assert errors == [], f"all-bound row must be silent; got {errors!r}"

    def _case_hist_stream_missing_on_cpp_trips() -> None:
        """Row claims C++ streams but the C++ member is absent — trips."""
        rows = [
            {
                "name": "option_history_trade",
                "rust": True,
                "python": True,
                "typescript": True,
                "cpp": True,
                "ffi": True,
            }
        ]
        bound = {"option_history_trade"}
        errors = _check_historical_streaming_rows(
            rows, bound, bound, bound, set(), bound
        )
        assert any("cpp" in e and "missing" in e for e in errors), (
            f"missing C++ stream member must trip; got {errors!r}"
        )

    def _case_hist_stream_missing_on_rust_trips() -> None:
        """Row claims Rust streams but the registry has no such builder —
        the dropped / renamed Rust endpoint defect this column closes.
        """
        rows = [
            {
                "name": "option_history_trade",
                "rust": True,
                "python": True,
                "typescript": True,
                "cpp": True,
                "ffi": True,
            }
        ]
        bound = {"option_history_trade"}
        # Rust set is empty — the endpoint vanished from the registry of
        # record while the bindings still declare it.
        errors = _check_historical_streaming_rows(
            rows, set(), bound, bound, bound, bound
        )
        assert any("rust" in e and "missing" in e for e in errors), (
            f"a dropped Rust streaming endpoint must trip; got {errors!r}"
        )

    def _case_hist_stream_ts_only_state_is_silent() -> None:
        """The managed-only ship state (rust+py+ts true, cpp+ffi false) is
        silent when Rust + Python + TS stream and C++ + FFI do not — the
        documented `option_list_contracts` language-only variant the matrix
        tracks.
        """
        rows = [
            {
                "name": "option_list_contracts",
                "rust": True,
                "python": True,
                "typescript": True,
                "cpp": False,
                "ffi": False,
            }
        ]
        bound = {"option_list_contracts"}
        errors = _check_historical_streaming_rows(
            rows, bound, bound, bound, set(), set()
        )
        assert errors == [], f"managed-only state must be silent; got {errors!r}"

    def _case_hist_stream_untracked_orphan_trips() -> None:
        """An endpoint streaming on a surface with no row at all trips
        the reverse-direction orphan check.
        """
        errors = _check_historical_streaming_rows(
            [], {"option_history_trade"}, set(), set(), set(), set()
        )
        assert any(
            "option_history_trade" in e and "no [[historical_streaming]] row" in e
            for e in errors
        ), f"untracked streaming endpoint must trip; got {errors!r}"

    def _case_hist_stream_rust_mirrors_generated() -> None:
        """The Rust streaming classification (registry-of-record mirror of
        the build's `endpoint_streams` SSOT) must equal the live generated
        Python `fn stream` surface — both are emitted from the same
        registry, so any desync between the gate's mirror and the build's
        predicate is a real drift the gate must surface.
        """
        rust_stream = _collect_rust_streaming_endpoints(ENDPOINT_SURFACE_TOML)
        py_stream = _collect_python_streaming_endpoints(PY_SRC)
        assert rust_stream == py_stream, (
            f"Rust streaming mirror must equal the generated Python stream "
            f"surface; rust-only={sorted(rust_stream - py_stream)!r}, "
            f"py-only={sorted(py_stream - rust_stream)!r}"
        )

    def _case_hist_stream_initialism_inverse() -> None:
        """`stockHistoryEODStream` (TS) and `StockHistoryEod` (Python
        builder stem) both invert to the canonical `stock_history_eod`,
        so the two collectors agree on the row name.
        """
        assert _endpoint_method_to_snake("stockHistoryEOD") == "stock_history_eod"
        assert _endpoint_method_to_snake("StockHistoryEod") == "stock_history_eod"
        assert (
            _endpoint_method_to_snake("optionHistoryGreeksImpliedVolatility")
            == "option_history_greeks_implied_volatility"
        )
        assert _endpoint_method_to_snake("stockHistoryOHLCRange") == "stock_history_ohlc_range"

    _case("hist-stream positive — all five surfaces stream", _case_hist_stream_positive_all_bound)
    _case("hist-stream negative — missing C++ member trips", _case_hist_stream_missing_on_cpp_trips)
    _case("hist-stream negative — dropped Rust endpoint trips", _case_hist_stream_missing_on_rust_trips)
    _case("hist-stream positive — managed-only ship state is silent", _case_hist_stream_ts_only_state_is_silent)
    _case("hist-stream negative — untracked streaming endpoint trips", _case_hist_stream_untracked_orphan_trips)
    _case("hist-stream — Rust mirror equals generated Python stream surface", _case_hist_stream_rust_mirrors_generated)
    _case("hist-stream — initialism-aware inverse agrees across bindings", _case_hist_stream_initialism_inverse)

    # ── Historical async query surface selftests ──────────────────

    def _case_hist_async_positive_all_bound() -> None:
        """An endpoint with an async query on every declared surface is
        silent."""
        rows = [
            {
                "name": "stock_history_eod",
                "rust": True,
                "python": True,
                "typescript": True,
                "cpp": True,
            }
        ]
        s = {"stock_history_eod"}
        errors = _check_historical_async_rows(rows, s, s, s, s)
        assert errors == [], f"all-bound async row must be silent; got {errors!r}"

    def _case_hist_async_missing_on_cpp_trips() -> None:
        """Row claims C++ exposes the async query but the `_async` member is
        absent — trips."""
        rows = [
            {
                "name": "stock_history_eod",
                "rust": True,
                "python": True,
                "typescript": True,
                "cpp": True,
            }
        ]
        bound = {"stock_history_eod"}
        errors = _check_historical_async_rows(rows, bound, bound, bound, set())
        assert any("cpp" in e and "missing" in e for e in errors), (
            f"missing C++ async member must trip; got {errors!r}"
        )

    def _case_hist_async_missing_on_rust_trips() -> None:
        """Row claims Rust exposes the async query but the registry has no
        such buffered endpoint — the dropped / renamed Rust endpoint defect
        this column closes."""
        rows = [
            {
                "name": "stock_history_eod",
                "rust": True,
                "python": True,
                "typescript": True,
                "cpp": True,
            }
        ]
        bound = {"stock_history_eod"}
        errors = _check_historical_async_rows(rows, set(), bound, bound, bound)
        assert any("rust" in e and "missing" in e for e in errors), (
            f"a dropped Rust async endpoint must trip; got {errors!r}"
        )

    def _case_hist_async_untracked_orphan_trips() -> None:
        """An endpoint with an async query on a surface but no row at all
        trips the reverse-direction orphan check."""
        errors = _check_historical_async_rows(
            [], {"stock_history_eod"}, set(), set(), set()
        )
        assert any(
            "stock_history_eod" in e and "no [[historical_async]] row" in e
            for e in errors
        ), f"untracked async endpoint must trip; got {errors!r}"

    def _case_hist_async_cpp_collector_strips_suffix() -> None:
        """The C++ collector recovers the endpoint name from an `_async`
        member and ignores the blocking member of the same name."""
        cpp_methods = {
            "Historical": {"stock_history_eod", "stock_history_eod_async"}
        }
        found = _collect_cpp_async_endpoints(cpp_methods)
        assert found == {"stock_history_eod"}, (
            f"collector must strip `_async` and ignore the blocking twin; "
            f"got {found!r}"
        )

    _case("hist-async positive — all four surfaces expose async query", _case_hist_async_positive_all_bound)
    _case("hist-async negative — missing C++ member trips", _case_hist_async_missing_on_cpp_trips)
    _case("hist-async negative — dropped Rust endpoint trips", _case_hist_async_missing_on_rust_trips)
    _case("hist-async negative — untracked async endpoint trips", _case_hist_async_untracked_orphan_trips)
    _case("hist-async — C++ collector strips `_async` suffix", _case_hist_async_cpp_collector_strips_suffix)

    # ── Historical buffered base surface selftests ────────────────

    def _case_hist_base_positive_all_five() -> None:
        """An endpoint present on all five surfaces is silent."""
        rows = [
            {
                "name": "stock_history_eod",
                "rust": True,
                "python": True,
                "typescript": True,
                "cpp": True,
                "ffi": True,
            }
        ]
        s = {"stock_history_eod"}
        errors = _check_historical_base_rows(rows, s, s, s, s, s, s)
        assert errors == [], f"all-five-surface base row must be silent; got {errors!r}"

    def _case_hist_base_missing_on_cabi_trips() -> None:
        """Row claims the C-ABI base symbol exists but the shipped header
        does not declare it — the exact 61-symbol blind spot this family
        closes."""
        rows = [
            {
                "name": "stock_history_eod",
                "rust": True,
                "python": True,
                "typescript": True,
                "cpp": True,
                "ffi": True,
            }
        ]
        s = {"stock_history_eod"}
        # `cabi_base` AND `ffi_base` empty — the `_with_options` base symbol
        # is gone everywhere on the C side.
        errors = _check_historical_base_rows(rows, s, s, s, s, set(), set())
        assert any("ffi" in e and "missing" in e for e in errors), (
            f"missing C-ABI base symbol must trip; got {errors!r}"
        )

    def _case_hist_base_missing_on_rust_trips() -> None:
        """Row claims the Rust buffered method exists but the registry of
        record has no such endpoint — the dropped / renamed Rust endpoint
        defect."""
        rows = [
            {
                "name": "stock_history_eod",
                "rust": True,
                "python": True,
                "typescript": True,
                "cpp": True,
                "ffi": True,
            }
        ]
        s = {"stock_history_eod"}
        errors = _check_historical_base_rows(rows, set(), s, s, s, s, s)
        assert any("rust" in e and "missing" in e for e in errors), (
            f"a dropped Rust buffered endpoint must trip; got {errors!r}"
        )

    def _case_hist_base_header_source_divergence_trips() -> None:
        """A shipped header that dropped a base symbol the `ffi/src` source
        still defines (a stale regenerated header) trips, independent of any
        per-row column."""
        rows = [
            {
                "name": "stock_history_eod",
                "rust": True,
                "python": True,
                "typescript": True,
                "cpp": True,
                "ffi": True,
            }
        ]
        s = {"stock_history_eod"}
        # Header is missing `option_history_eod` that the source defines.
        cabi = {"stock_history_eod"}
        ffi = {"stock_history_eod", "option_history_eod"}
        errors = _check_historical_base_rows(rows, s, s, s, s, cabi, ffi)
        assert any(
            "option_history_eod" in e and "stale header" in e for e in errors
        ), f"a header/source divergence must trip; got {errors!r}"

    def _case_hist_base_untracked_orphan_trips() -> None:
        """An endpoint present on a surface but with no row at all trips the
        reverse-direction orphan scan."""
        errors = _check_historical_base_rows(
            [], {"stock_history_eod"}, set(), set(), set(), set(), set()
        )
        assert any(
            "stock_history_eod" in e and "no [[historical_base]] row" in e
            for e in errors
        ), f"untracked base endpoint must trip; got {errors!r}"

    def _case_hist_base_live_sources_clean() -> None:
        """The live buffered base surface is symmetric across all five
        surfaces: every one of the 61 endpoints present on Rust / Python /
        TypeScript / C++ / the C-ABI base, and the shipped header agrees with
        the `ffi/src` source and the Rust registry."""
        data = tomllib.loads(PARITY_TOML.read_text(encoding="utf-8"))
        rows = data.get("historical_base", [])
        assert rows, "live parity.toml must declare [[historical_base]] rows"
        ts_methods = _collect_typescript_class_methods(TS_SRC)
        cpp_methods = _collect_cpp_class_methods(CPP_HPP)
        errors = _check_historical_base_rows(
            rows,
            _collect_rust_buffered_endpoints(ENDPOINT_SURFACE_TOML),
            _collect_python_buffered_endpoints(PY_SRC),
            _collect_typescript_async_endpoints(ts_methods),
            cpp_methods.get(_cpp_class_for("HistoricalView"), set()),
            _collect_cabi_base_endpoints(ENDPOINT_WITH_OPTIONS_INC),
            _collect_ffi_base_endpoints(FFI_SRC),
        )
        assert errors == [], f"live buffered base surface must be clean; got {errors!r}"

    def _case_hist_base_registry_count() -> None:
        """The registry of record yields exactly the 61 buffered endpoints
        (the four `*_stream` FPSS subscription endpoints excluded), and the
        shipped C-ABI header declares the same 61 base symbols."""
        rust = _collect_rust_buffered_endpoints(ENDPOINT_SURFACE_TOML)
        cabi = _collect_cabi_base_endpoints(ENDPOINT_WITH_OPTIONS_INC)
        assert len(rust) == 61, f"registry must yield 61 buffered endpoints; got {len(rust)}"
        assert rust == cabi, (
            f"registry buffered set must equal the C-ABI base set; "
            f"rust-only={sorted(rust - cabi)!r}, cabi-only={sorted(cabi - rust)!r}"
        )

    _case("hist-base positive — all five surfaces present", _case_hist_base_positive_all_five)
    _case("hist-base negative — missing C-ABI base symbol trips", _case_hist_base_missing_on_cabi_trips)
    _case("hist-base negative — dropped Rust endpoint trips", _case_hist_base_missing_on_rust_trips)
    _case("hist-base negative — header/source divergence trips", _case_hist_base_header_source_divergence_trips)
    _case("hist-base negative — untracked endpoint trips", _case_hist_base_untracked_orphan_trips)
    _case("hist-base — live sources clean", _case_hist_base_live_sources_clean)
    _case("hist-base — registry yields 61 endpoints matching C-ABI base", _case_hist_base_registry_count)

    # ── Client construction-from-file surface selftests ───────────

    def _case_from_file_positive_all_bound() -> None:
        """A client exposing file construction on every declared binding
        (with the idiomatic per-binding spelling) is silent."""
        rows = [
            {
                "name": "HistoricalClient",
                "python": True,
                "typescript": True,
                "cpp": True,
                "ffi": True,
            }
        ]
        errors = _check_from_file_rows(
            rows,
            {"HistoricalClient"},
            {"HistoricalClient"},
            {"HistoricalClient"},
            {"historical"},
        )
        assert errors == [], f"all-bound row must be silent; got {errors!r}"

    def _case_from_file_missing_on_ffi_trips() -> None:
        """Row claims the C ABI exposes file construction but the
        `thetadatadx_<stem>_connect_from_file` symbol is absent — trips."""
        rows = [
            {
                "name": "StreamingClient",
                "python": True,
                "typescript": True,
                "cpp": True,
                "ffi": True,
            }
        ]
        errors = _check_from_file_rows(
            rows,
            {"StreamingClient"},
            {"StreamingClient"},
            {"StreamingClient"},
            set(),
        )
        assert any("ffi" in e and "missing" in e for e in errors), (
            f"missing C ABI symbol must trip; got {errors!r}"
        )

    def _case_from_file_untracked_orphan_trips() -> None:
        """A client exposing file construction on a binding with no row
        at all trips the reverse-direction orphan check."""
        errors = _check_from_file_rows(
            [], {"Client"}, set(), set(), set()
        )
        assert any(
            "Client" in e and "no [[from_file]] row" in e
            for e in errors
        ), f"untracked file-construction client must trip; got {errors!r}"

    def _case_from_file_ffi_stem_maps_class_name() -> None:
        """The FFI stem table bridges the class name to its C ABI symbol
        stem: `Client` resolves via `client`, not its own
        name. A row declaring ffi=true is silent only when the matching
        stem symbol exists."""
        rows = [
            {
                "name": "Client",
                "python": False,
                "typescript": False,
                "cpp": False,
                "ffi": True,
            }
        ]
        # The class name itself in the stem set must NOT satisfy the row;
        # only the mapped `client` stem does.
        errors_wrong = _check_from_file_rows(
            rows, set(), set(), set(), {"theta_data_dx"}
        )
        assert any("ffi" in e for e in errors_wrong), (
            f"class-name stem must not satisfy the row; got {errors_wrong!r}"
        )
        errors_right = _check_from_file_rows(rows, set(), set(), set(), {"client"})
        assert errors_right == [], (
            f"mapped `client` stem must satisfy the row; got {errors_right!r}"
        )

    def _case_from_file_live_sources_clean() -> None:
        """The shipped bindings expose `from_file` (idiomatic spelling) on
        every client the live `[[from_file]]` rows declare."""
        data = tomllib.loads(PARITY_TOML.read_text(encoding="utf-8"))
        rows = data.get("from_file", [])
        assert rows, "live parity.toml must declare [[from_file]] rows"
        py_methods = _collect_python_class_methods(PY_SRC)
        ts_methods = _collect_typescript_class_methods(TS_SRC)
        cpp_methods = _collect_cpp_class_methods(CPP_HPP)
        errors = _check_from_file_rows(
            rows,
            _collect_python_from_file_classes(py_methods),
            _collect_typescript_from_file_classes(ts_methods),
            _collect_cpp_from_file_classes(cpp_methods),
            _collect_ffi_from_file_stems(FFI_SRC),
        )
        assert errors == [], f"live from_file sources must be clean; got {errors!r}"

    _case("from-file positive — all four bindings construct", _case_from_file_positive_all_bound)
    _case("from-file negative — missing C ABI symbol trips", _case_from_file_missing_on_ffi_trips)
    _case("from-file negative — untracked client trips", _case_from_file_untracked_orphan_trips)
    _case("from-file — FFI stem table maps class name", _case_from_file_ffi_stem_maps_class_name)
    _case("from-file — live sources clean", _case_from_file_live_sources_clean)

    # ── Public-surface vocabulary guard selftests ──────────────────

    def _case_surface_vocab_flags_tokio_identifier() -> None:
        """An impl-detail token embedded in a public identifier trips,
        even though `\\btokio\\b` would not match it.
        """
        errors = _check_public_surface_vocab(
            {"Config"},
            set(),
            set(),
            {"tokio_worker_threads"},
            set(),
            set(),
            set(),
            {},
            {},
            {},
        )
        assert any("tokio" in e for e in errors), (
            f"embedded tokio token must trip the guard; got {errors!r}"
        )

    def _case_surface_vocab_flags_camelcase_export() -> None:
        """A camelCase export type embedding the token trips."""
        errors = _check_public_surface_vocab(
            set(),
            {"TokioWorkerThreadsSetting"},
            set(),
            set(),
            set(),
            set(),
            set(),
            {},
            {},
            {},
        )
        assert any("tokio" in e for e in errors), (
            f"camelCase Tokio export must trip; got {errors!r}"
        )

    def _case_surface_vocab_flags_other_impl_tokens() -> None:
        """The other OUR-impl tokens (crossbeam / parking_lot /
        disruptor / block_on / allow_threads / os_pipe) all trip when
        embedded in a public identifier, in both snake_case and
        camelCase spellings (the camelCase form collapses the
        underscore, so `parkingLotGuard` hits the `parkinglot` variant).
        """
        for ident in [
            "set_crossbeam_depth",
            "parkingLotGuard",
            "parking_lot_guard",
            "disruptorRingSize",
            "blockOnConnect",
            "block_on_connect",
            "allowThreadsFlag",
            "allow_threads_flag",
            "osPipeFd",
        ]:
            errors = _check_public_surface_vocab(
                set(), set(), set(), {ident}, set(), set(), set(), {}, {}, {}
            )
            assert any(ident in e for e in errors), (
                f"{ident!r} must trip the surface-vocab guard; got {errors!r}"
            )

    def _case_surface_vocab_allows_vendor_protocol_names() -> None:
        """Vendor protocol names (mdds / fpss) are allow-listed and must
        NEVER trip — `HistoricalClient`, `historical_host`,
        `setStreamingRingSize`, `streaming_ring_size` are all clean.
        """
        errors = _check_public_surface_vocab(
            {"HistoricalClient", "StreamingClient", "StreamEvent"},
            set(),
            set(),
            {"historical_host", "historical_port", "streaming_ring_size", "streaming_host_selection"},
            {"streaming_ring_size"},
            set(),
            set(),
            {"StreamingClient": {"subscribe"}},
            {},
            {},
        )
        assert errors == [], (
            f"vendor protocol names must be allow-listed; got {errors!r}"
        )

    def _case_surface_vocab_allows_neutral_names() -> None:
        """The renamed neutral knob (`worker_threads`) is clean."""
        errors = _check_public_surface_vocab(
            {"Config", "WorkerThreadsSetting"},
            set(),
            set(),
            {"worker_threads"},
            {"worker_threads_explicit"},
            {"worker_threads_explicit"},
            {"worker_threads_explicit"},
            {},
            {},
            {},
        )
        assert errors == [], (
            f"neutral worker_threads names must be clean; got {errors!r}"
        )

    _case("surface-vocab — embedded tokio token trips", _case_surface_vocab_flags_tokio_identifier)
    _case("surface-vocab — camelCase Tokio export trips", _case_surface_vocab_flags_camelcase_export)
    _case("surface-vocab — other impl tokens trip", _case_surface_vocab_flags_other_impl_tokens)
    _case("surface-vocab — vendor protocol names allow-listed", _case_surface_vocab_allows_vendor_protocol_names)
    _case("surface-vocab — neutral names clean", _case_surface_vocab_allows_neutral_names)

    # ── Setter normalizer + set-parity selftests ───────────────────

    def _case_normalizer_folds_explicit_and_flatfiles() -> None:
        """`_normalize_setter` folds the `_explicit` widened-ABI suffix
        and the `flat_files`→`flatfiles` camelCase split.
        """
        assert _normalize_setter("worker_threads_explicit") == "worker_threads"
        assert _normalize_setter("worker_threads") == "worker_threads"
        assert _normalize_setter("flat_files_max_attempts") == "flatfiles_max_attempts"
        assert _normalize_setter("flatfiles_max_attempts") == "flatfiles_max_attempts"
        assert _normalize_setter("streaming_host_shuffle_seed_explicit") == "streaming_host_shuffle_seed"

    def _case_setter_set_parity_positive_after_normalize() -> None:
        """The four sets, spelled in their per-binding idioms, compare
        equal after normalization — the gate is silent.
        """
        py = {"worker_threads", "flatfiles_jitter", "derive_ohlcvc"}
        ts = {"worker_threads_explicit", "flat_files_jitter", "flatfiles_jitter", "derive_ohlcvc"}
        cpp = {"worker_threads_explicit", "flatfiles_jitter", "derive_ohlcvc"}
        ffi = {"worker_threads_explicit", "flatfiles_jitter", "derive_ohlcvc"}
        errors = _check_setter_set_parity(py, ts, cpp, ffi, exempt={})
        assert errors == [], (
            f"normalized-equal sets must be silent; got {errors!r}"
        )

    def _case_setter_set_parity_missing_on_one_binding_trips() -> None:
        """A knob bound on three bindings but absent from TS trips — the
        `derive_ohlcvc`-missing-on-TS defect class.
        """
        py = {"derive_ohlcvc"}
        ts: set[str] = set()
        cpp = {"derive_ohlcvc"}
        ffi = {"derive_ohlcvc"}
        errors = _check_setter_set_parity(py, ts, cpp, ffi, exempt={})
        assert any("derive_ohlcvc" in e and "typescript" in e for e in errors), (
            f"missing-on-TS knob must trip the set-parity gate; got {errors!r}"
        )

    def _case_setter_set_parity_honours_exemption() -> None:
        """A Python-only knob listed in the exemption map does NOT trip
        — the documented per-language-idiom carve-out.
        """
        py = {"historical_host", "shared"}
        ts = {"shared"}
        cpp = {"shared"}
        ffi = {"shared"}
        errors = _check_setter_set_parity(
            py, ts, cpp, ffi, exempt={"historical_host": "Python-only advanced override"}
        )
        assert errors == [], (
            f"exempted Python-only knob must not trip; got {errors!r}"
        )

    def _case_setter_set_parity_stale_exemption_trips() -> None:
        """An exempted knob that is now uniformly bound on every binding
        is a stale carve-out and trips so the list never rots.
        """
        allfour = {"historical_host"}
        errors = _check_setter_set_parity(
            allfour,
            allfour,
            allfour,
            allfour,
            exempt={"historical_host": "Python-only advanced override"},
        )
        assert any("historical_host" in e and "stale" in e for e in errors), (
            f"uniformly-bound exemption must surface as stale; got {errors!r}"
        )

    def _case_setter_set_parity_shipped_exemption_is_live() -> None:
        """The shipped `SETTER_PARITY_EXEMPT` carve-outs must be live
        against the real binding sources — `historical_host` /
        `historical_port` present on every binding, so the carve-out map
        stays empty and the live gate stays silent on them.
        """
        py = _collect_python_setters(PY_SRC)
        ts = _collect_typescript_setters(TS_SRC)
        cpp = _collect_cpp_setters(CPP_HPP, CPP_H)
        ffi = _collect_ffi_setters(FFI_SRC)
        errors = _check_setter_set_parity(py, ts, cpp, ffi)
        assert errors == [], (
            f"live setter-set parity must be clean; got {errors!r}"
        )

    _case("normalizer — folds _explicit + flat_files", _case_normalizer_folds_explicit_and_flatfiles)
    _case("setter-set — normalized-equal sets are silent", _case_setter_set_parity_positive_after_normalize)
    _case("setter-set — missing-on-TS knob trips", _case_setter_set_parity_missing_on_one_binding_trips)
    _case("setter-set — Python-only exemption honoured", _case_setter_set_parity_honours_exemption)
    _case("setter-set — stale exemption trips", _case_setter_set_parity_stale_exemption_trips)
    _case("setter-set — shipped exemptions live against real sources", _case_setter_set_parity_shipped_exemption_is_live)

    # ── Config getter-set parity selftests ─────────────────────────

    def _case_getter_set_parity_positive() -> None:
        """A getter on all four bindings (with the `_explicit` idiom
        folded) is silent — the read-side analogue of the setter check.
        """
        errors = _check_getter_set_parity(
            {"reconnect_wait_ms", "worker_threads"},
            {"reconnect_wait_ms", "worker_threads_explicit"},
            {"reconnect_wait_ms", "worker_threads_explicit"},
            {"reconnect_wait_ms", "worker_threads_explicit"},
            exempt={},
        )
        assert errors == [], f"normalized-equal getter sets must be silent; got {errors!r}"

    def _case_getter_set_parity_missing_on_ffi_trips() -> None:
        """A read-back getter bound on Python/TS/C++ but absent from the C
        ABI trips — the read-side of the missing-binding defect class.
        """
        errors = _check_getter_set_parity(
            {"streaming_ring_size"},
            {"streaming_ring_size"},
            {"streaming_ring_size"},
            set(),
            exempt={},
        )
        assert any("streaming_ring_size" in e and "ffi" in e for e in errors), (
            f"getter missing on FFI must trip; got {errors!r}"
        )

    def _case_getter_set_parity_live_sources_clean() -> None:
        """The live Config getter roster is symmetric across all four
        bindings — every read-back accessor present in one is present in
        all (the seam the read-side check pins).
        """
        py = _collect_python_getters(PY_SRC)
        ts = _collect_typescript_getters(TS_SRC)
        cpp = _collect_cpp_getters(CPP_HPP)
        ffi = _collect_ffi_getters(FFI_SRC)
        errors = _check_getter_set_parity(py, ts, cpp, ffi)
        assert errors == [], f"live getter-set parity must be clean; got {errors!r}"

    def _case_getter_collectors_scope_to_config() -> None:
        """The getter collectors harvest only `impl Config` bodies, so a
        getter on an unrelated pyclass / napi class is not swept into the
        Config knob roster.
        """
        py_text = (
            "#[pymethods]\nimpl Config {\n    #[getter] fn get_streaming_ring_size(&self) -> usize { 0 }\n}\n"
            "#[pymethods]\nimpl QuoteTick {\n    #[getter] fn bid_price(&self) -> f64 { 0.0 }\n}\n"
        )
        bodies = _iter_impl_config_bodies(py_text)
        assert len(bodies) == 1, f"only the Config impl body must be picked; got {bodies!r}"
        assert "get_streaming_ring_size" in bodies[0]
        assert "bid_price" not in bodies[0]

    _case("getter-set — normalized-equal sets are silent", _case_getter_set_parity_positive)
    _case("getter-set — missing-on-FFI getter trips", _case_getter_set_parity_missing_on_ffi_trips)
    _case("getter-set — live sources clean", _case_getter_set_parity_live_sources_clean)
    _case("getter collectors — scope to impl Config only", _case_getter_collectors_scope_to_config)

    # ── Subscription-kind label parity selftests ───────────────────

    def _case_subscription_kind_positive() -> None:
        """Every binding emitting the full canonical set is silent."""
        full = set(CANONICAL_SUBSCRIPTION_KINDS)
        errors = _check_subscription_kind_parity(full, full, full, full, full)
        assert errors == [], f"all-canonical kind sets must be silent; got {errors!r}"

    def _case_subscription_kind_missing_label_trips() -> None:
        """A binding short one label (the C-ABI-collision class where a
        label silently differs) trips.
        """
        full = set(CANONICAL_SUBSCRIPTION_KINDS)
        short = full - {"market_value"}
        errors = _check_subscription_kind_parity(full, full, full, short, full)
        assert any("cpp" in e and "missing" in e and "market_value" in e for e in errors), (
            f"a dropped kind label must trip; got {errors!r}"
        )

    def _case_subscription_kind_fictitious_label_trips() -> None:
        """A binding emitting a non-canonical label (the C++
        `full_quote` / `full_market_value` defect, a full-stream kind that
        does not exist on the wire) trips.
        """
        full = set(CANONICAL_SUBSCRIPTION_KINDS)
        invented = full | {"full_quote"}
        errors = _check_subscription_kind_parity(full, full, full, invented, full)
        assert any("cpp" in e and "non-canonical" in e and "full_quote" in e for e in errors), (
            f"a fictitious kind label must trip; got {errors!r}"
        )

    def _case_subscription_kind_harvest_captures_fictitious() -> None:
        """The C++ harvester captures a `full_quote` / `full_market_value`
        literal inside `kind_string()` so the canonical-set assertion can
        flag it — the harvest filter must not silently drop them.
        """
        hpp_text = (
            "class FluentSubscription {\n"
            "  std::string kind_string() const {\n"
            "    if (full) {\n"
            '      switch (k) { case A: return "full_quote"; case B: return "full_trades"; }\n'
            "    }\n"
            '    return "quote";\n'
            "  }\n"
            "};\n"
        )
        import tempfile as _tmp
        with _tmp.NamedTemporaryFile("w", suffix=".hpp", delete=True) as f:
            f.write(hpp_text)
            f.flush()
            harvested = _collect_cpp_subscription_kinds(pathlib.Path(f.name))
        assert "full_quote" in harvested, (
            f"harvester must capture the fictitious label; got {harvested!r}"
        )
        assert "full_trades" in harvested and "quote" in harvested

    def _case_subscription_kind_live_sources_clean() -> None:
        """Every live binding emits exactly the canonical kind roster."""
        errors = _check_subscription_kind_parity(
            _collect_rust_subscription_kinds(SUBSCRIPTION_RS),
            _collect_binding_subscription_kinds(PY_FLUENT_RS),
            _collect_binding_subscription_kinds(TS_FLUENT_RS),
            _collect_cpp_subscription_kinds(CPP_HPP),
            _collect_ffi_subscription_kinds(CPP_H),
        )
        assert errors == [], f"live subscription-kind parity must be clean; got {errors!r}"

    _case("subscription-kind positive — all-canonical sets silent", _case_subscription_kind_positive)
    _case("subscription-kind negative — dropped label trips", _case_subscription_kind_missing_label_trips)
    _case("subscription-kind negative — fictitious label trips", _case_subscription_kind_fictitious_label_trips)
    _case("subscription-kind — C++ harvest captures fictitious label", _case_subscription_kind_harvest_captures_fictitious)
    _case("subscription-kind — live sources clean", _case_subscription_kind_live_sources_clean)

    # ── Error-leaf mapping parity selftests ────────────────────────

    def _case_error_leaf_positive() -> None:
        """Symmetric leaf rosters + matching code tables are silent."""
        leaves = set(CANONICAL_ERROR_LEAVES)
        errors = _check_error_leaf_parity(
            leaves,
            leaves,
            leaves,
            dict(CANONICAL_ERROR_CODES),
            set(CANONICAL_ERROR_CODES),
            dict(CANONICAL_ERROR_CODES),
        )
        assert errors == [], f"symmetric error mapping must be silent; got {errors!r}"

    def _case_error_leaf_missing_on_py_trips() -> None:
        """A leaf invisible on Python (the `FlatFilesUnavailable` /
        `PartialReconnect` → no `StreamError`, or a missing `ConfigError`
        defect) trips.
        """
        leaves = set(CANONICAL_ERROR_LEAVES)
        py_short = leaves - {"ConfigError"}
        errors = _check_error_leaf_parity(
            py_short,
            leaves,
            leaves,
            dict(CANONICAL_ERROR_CODES),
            set(CANONICAL_ERROR_CODES),
            dict(CANONICAL_ERROR_CODES),
        )
        assert any("python" in e and "ConfigError" in e for e in errors), (
            f"a leaf missing on Python must trip; got {errors!r}"
        )

    def _case_error_leaf_code_renumber_trips() -> None:
        """A renumbered FFI code (drift from the canonical table) trips."""
        leaves = set(CANONICAL_ERROR_LEAVES)
        bad_codes = dict(CANONICAL_ERROR_CODES)
        bad_codes["THETADATADX_ERR_STREAM"] = 99
        errors = _check_error_leaf_parity(
            leaves,
            leaves,
            leaves,
            bad_codes,
            set(CANONICAL_ERROR_CODES),
            bad_codes,
        )
        assert any("ffi" in e and "THETADATADX_ERR_STREAM" in e for e in errors), (
            f"a renumbered FFI code must trip; got {errors!r}"
        )

    def _case_error_leaf_header_drift_trips() -> None:
        """A C ABI header `#define` disagreeing with the FFI Rust constant
        (invisible to `cargo build`) trips.
        """
        leaves = set(CANONICAL_ERROR_LEAVES)
        header_codes = dict(CANONICAL_ERROR_CODES)
        header_codes["THETADATADX_ERR_CONFIG"] = 42
        errors = _check_error_leaf_parity(
            leaves,
            leaves,
            leaves,
            dict(CANONICAL_ERROR_CODES),
            set(CANONICAL_ERROR_CODES),
            header_codes,
        )
        assert any("cpp header" in e and "THETADATADX_ERR_CONFIG" in e for e in errors), (
            f"a C-header code drift must trip; got {errors!r}"
        )

    def _case_error_leaf_live_sources_symmetric() -> None:
        """The live error mapping is symmetric across all four bindings:
        identical leaf rosters on Python / TS / C++ and matching code
        tables in the FFI Rust constants and the C ABI header.
        """
        errors = _check_error_leaf_parity(
            _collect_python_error_leaves(PY_ERRORS_RS),
            _collect_typescript_error_leaves(TS_LIB_RS),
            _collect_cpp_error_leaves(CPP_HPP),
            _collect_ffi_error_codes(FFI_ERROR_RS),
            _collect_ffi_error_codes_dispatched(FFI_ERROR_RS),
            _collect_cpp_error_codes(CPP_H),
        )
        assert errors == [], f"live error-leaf parity must be symmetric; got {errors!r}"

    _case("error-leaf positive — symmetric rosters silent", _case_error_leaf_positive)
    _case("error-leaf negative — leaf missing on Python trips", _case_error_leaf_missing_on_py_trips)
    _case("error-leaf negative — renumbered FFI code trips", _case_error_leaf_code_renumber_trips)
    _case("error-leaf negative — C-header code drift trips", _case_error_leaf_header_drift_trips)
    _case("error-leaf — live sources symmetric", _case_error_leaf_live_sources_symmetric)

    # ── Utility-roster parity selftests ────────────────────────────

    def _case_utility_ffi_name_override_resolves() -> None:
        """A row whose C ABI symbol carries a disambiguating prefix
        resolves through `ffi_name` — `is_cancel` on Python/TS/C++ but
        `thetadatadx_condition_is_cancel` on the C ABI.
        """
        rows = [
            {
                "name": "is_cancel",
                "ffi_name": "condition_is_cancel",
                "python": True,
                "typescript": True,
                "cpp": True,
                "ffi": True,
            }
        ]
        errors = _check_utility_rows(
            rows,
            {"is_cancel"},
            {"is_cancel"},
            {"is_cancel"},
            {"condition_is_cancel"},
        )
        assert errors == [], f"ffi_name override must resolve; got {errors!r}"

    def _case_utility_ffi_name_missing_symbol_trips() -> None:
        """An `ffi_name` row whose C ABI symbol is absent trips."""
        rows = [
            {
                "name": "is_firm",
                "ffi_name": "quote_condition_is_firm",
                "python": True,
                "typescript": True,
                "cpp": True,
                "ffi": True,
            }
        ]
        errors = _check_utility_rows(
            rows,
            {"is_firm"},
            {"is_firm"},
            {"is_firm"},
            set(),  # the prefixed C ABI symbol is missing
        )
        assert any("is_firm" in e and "ffi" in e and "missing" in e for e in errors), (
            f"missing prefixed FFI symbol must trip; got {errors!r}"
        )

    def _case_utility_binding_specific_asserted() -> None:
        """A `binding_specific` row still asserts the declared per-binding
        booleans — a Python-only util must be present on Python and absent
        elsewhere, or the row trips.
        """
        rows = [
            {
                "name": "split_date_range",
                "binding_specific": "Python-only",
                "python": True,
                "typescript": False,
                "cpp": False,
                "ffi": False,
            }
        ]
        # Correct state: present on Python only.
        ok = _check_utility_rows(rows, {"split_date_range"}, set(), set(), set())
        assert ok == [], f"correct binding-specific state must be silent; got {ok!r}"
        # Drifted: the util appeared on TypeScript too.
        drift = _check_utility_rows(
            rows, {"split_date_range"}, {"split_date_range"}, set(), set()
        )
        assert any("split_date_range" in e and "typescript" in e for e in drift), (
            f"a binding-specific util appearing elsewhere must trip; got {drift!r}"
        )

    def _case_utility_roster_orphan_trips() -> None:
        """A utility on the Python surface with no `[[utility]]` row trips
        the roster orphan check.
        """
        rows = [{"name": "all_greeks", "python": True, "typescript": True, "cpp": True, "ffi": True}]
        errors = _check_utility_roster_complete(
            rows, {"all_greeks", "calendar_status_name"}, {"all_greeks"}
        )
        assert any("calendar_status_name" in e and "python" in e for e in errors), (
            f"an untracked Python utility must trip; got {errors!r}"
        )

    def _case_ts_utility_surface_filters_internal() -> None:
        """The TS utility surface merges `Util` methods and calculators but
        filters the internal arrow-IPC / coercion free functions.
        """
        surface = _ts_utility_surface(
            {"all_greeks", "quote_tick_to_arrow_ipc", "bigint_to_i32"},
            {"Util": {"conditionName", "isCancel"}},
        )
        assert "all_greeks" in surface
        assert "condition_name" in surface and "is_cancel" in surface
        assert "quote_tick_to_arrow_ipc" not in surface
        assert "bigint_to_i32" not in surface

    def _case_utility_roster_live_complete() -> None:
        """Every standalone utility on the live Python / TypeScript
        surfaces is named by a `[[utility]]` row (no untracked drift).
        """
        if not PARITY_TOML.is_file():
            return
        data = tomllib.loads(PARITY_TOML.read_text(encoding="utf-8"))
        rows = data.get("utility", [])
        py = _collect_python_utility_functions(PY_SRC)
        ts = _ts_utility_surface(
            _collect_typescript_utility_functions(TS_SRC),
            _collect_typescript_class_methods(TS_SRC),
        )
        errors = _check_utility_roster_complete(rows, py, ts)
        assert errors == [], f"live utility roster must be complete; got {errors!r}"

    _case("utility — ffi_name override resolves prefixed symbol", _case_utility_ffi_name_override_resolves)
    _case("utility — missing prefixed FFI symbol trips", _case_utility_ffi_name_missing_symbol_trips)
    _case("utility — binding_specific row asserts declared booleans", _case_utility_binding_specific_asserted)
    _case("utility — roster orphan (untracked util) trips", _case_utility_roster_orphan_trips)
    _case("utility — TS surface filters internal free fns", _case_ts_utility_surface_filters_internal)
    _case("utility — live roster complete", _case_utility_roster_live_complete)

    print(f"check_binding_parity --selftest: {n_pass} passed, {n_fail} failed")
    return 0 if n_fail == 0 else 1


if __name__ == "__main__":
    sys.exit(main())