mt5cli 1.2.2__tar.gz → 1.2.4__tar.gz

{mt5cli-1.2.2 → mt5cli-1.2.4}/.github/workflows/ci.yml

@@ -50,6 +50,21 @@ jobs:
     with:
       package-path: .
       runs-on: windows-latest
+  minimum-dependency-smoke-test:
+    if: >
+      github.event_name == 'push'
+      || github.event_name == 'pull_request'
+      || (github.event_name == 'workflow_dispatch' && inputs.workflow == 'lint-and-test')
+    permissions:
+      contents: read
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v6.0.2
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@f98e06938123ccabd21905ea5d0069192241f9f1  # v8.3.1
+      - name: Check CLI help with minimum Click and Typer versions
+        run: uv run --with click==8.4.0 --with typer==0.26.0 mt5cli --help
   python-docs-deploy:
     if: >
       github.event_name == 'push'

{mt5cli-1.2.2 → mt5cli-1.2.4}/AGENTS.md

@@ -26,7 +26,7 @@ Apply KISS, DRY, and YAGNI when changing code. Prefer the simplest implementatio
 
 ## Testing Guidelines
 
-Tests use pytest, pytest-mock, doctests, and pytest-cov. Test files should match `tests/test_*.py`, classes `Test*`, and functions `test_*`. Coverage is configured with `fail_under = 100`, so add focused tests for every behavior change. Mock MT5/pdmt5 boundaries; do not require a live MetaTrader terminal in unit tests.
+Tests use pytest, pytest-mock, doctests, and pytest-cov. Test files should match `tests/test_*.py`, classes `Test*`, and functions `test_*`. Parametrize unit tests with `pytest.mark.parametrize` when the same behavior needs coverage across multiple inputs. Coverage is configured with `fail_under = 100`, so add focused tests for every behavior change. Mock MT5/pdmt5 boundaries; do not require a live MetaTrader terminal in unit tests.
 
 ## Commit & Pull Request Guidelines
 

{mt5cli-1.2.2 → mt5cli-1.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mt5cli
-Version: 1.2.2
+Version: 1.2.4
 Summary: Generic MT5 data and execution infrastructure for Python applications
 Project-URL: Repository, https://github.com/dceoy/mt5cli.git
 Author-email: dceoy <dceoy@users.noreply.github.com>
@@ -16,10 +16,9 @@ Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: Office/Business :: Financial :: Investment
 Requires-Python: <3.14,>=3.11
-Requires-Dist: click>=8.1.0
 Requires-Dist: pandas>=2.2.2
 Requires-Dist: pdmt5>=1.2.0
-Requires-Dist: typer>=0.15.0
+Requires-Dist: typer>=0.26.0
 Provides-Extra: otel
 Requires-Dist: opentelemetry-api; extra == 'otel'
 Requires-Dist: opentelemetry-exporter-otlp-proto-http; extra == 'otel'

{mt5cli-1.2.2 → mt5cli-1.2.4}/docs/api/trading.md

@@ -202,19 +202,24 @@ or `None` result from the underlying client is normalized to an empty DataFrame.
 Downstream packages own all strategy-specific transformations. mt5cli does not
 provide entry-deal classification, Kelly sizing, or any betting-specific helpers.
 
-## Broker server clock offset
+## Timestamp sources and broker clock offsets
 
-MT5 tick, bar, and deal timestamps are epoch values labeled in the broker
-server's wall clock, which is commonly UTC+2 or UTC+3 rather than true UTC.
-Any code that mixes those timestamps with true UTC (freshness checks,
-trailing history windows) silently inherits the broker's offset as a bias
-unless it is measured and applied explicitly.
+The MT5 Python documentation describes tick and bar data copied by the
+`copy_ticks_*` and `copy_rates_*` functions as UTC. It does not document a
+different timezone contract for `symbol_info_tick()`, nor should deal epochs
+be assumed to use a broker wall clock without source-specific evidence.
+
+`get_tick_snapshot()` preserves the numeric MT5 epoch value in `time`; it does
+not expose pdmt5's timezone-naive `Timestamp` conversion or alter the instant.
+Any broker-specific offset handling therefore requires evidence from the live
+data source in use and must be applied separately. Do not subtract a presumed
+UTC+2 or UTC+3 offset from timestamps that are already UTC.
 
 `estimate_server_clock_offset_seconds()` reads the latest tick for a symbol
 and returns the broker's clock offset from true UTC, rounded to the nearest
-half hour, or `None` when no valid tick time is available. Apply the result in
-the downstream time-window calculation when comparing broker timestamps to
-true UTC.
+half hour, or `None` when no valid tick time is available. Use it to validate a
+suspected offset for the live `symbol_info_tick()` source before applying the
+result in downstream time-window calculations.
 
 No offset is applied automatically by history retrieval helpers.
 

{mt5cli-1.2.2 → mt5cli-1.2.4}/mt5cli/cli.py

@@ -6,11 +6,10 @@ import json
 import logging
 from contextlib import closing
 from dataclasses import dataclass
-from datetime import datetime
+from datetime import datetime  # noqa: TC003
 from pathlib import Path  # noqa: TC003
 from typing import TYPE_CHECKING, Annotated, Any, cast
 
-import click
 import pandas as pd
 import typer
 
@@ -46,125 +45,34 @@ if TYPE_CHECKING:
 
 logger = logging.getLogger(__name__)
 
-# ---------------------------------------------------------------------------
-# Click parameter types
-# ---------------------------------------------------------------------------
 
+def _parse_datetime_parameter(value: str) -> datetime:
+    try:
+        return parse_datetime(value)
+    except ValueError as exc:
+        raise typer.BadParameter(str(exc)) from exc
+
+
+def _parse_timeframe_parameter(value: str) -> int:
+    try:
+        return parse_timeframe(value)
+    except ValueError as exc:
+        raise typer.BadParameter(str(exc)) from exc
+
+
+def _parse_tick_flags_parameter(value: str) -> int:
+    try:
+        return parse_tick_flags(value)
+    except ValueError as exc:
+        raise typer.BadParameter(str(exc)) from exc
+
+
+def _parse_request_parameter(value: str) -> dict[str, Any]:
+    try:
+        return parse_request(value)
+    except ValueError as exc:
+        raise typer.BadParameter(str(exc)) from exc
 
-class _DateTimeType(click.ParamType):
-    """Click parameter type for ISO 8601 datetime strings."""
-
-    name = "DATETIME"
-
-    def convert(
-        self,
-        value: object,
-        param: click.Parameter | None,
-        ctx: click.Context | None,
-    ) -> datetime:
-        """Convert a string value to a timezone-aware datetime.
-
-        Args:
-            value: Raw value from the command line.
-            param: Click parameter instance.
-            ctx: Click context.
-
-        Returns:
-            Parsed datetime.
-        """
-        if isinstance(value, datetime):
-            return value
-        try:
-            return parse_datetime(str(value))
-        except ValueError as exc:
-            self.fail(str(exc), param, ctx)
-
-
-class _TimeframeType(click.ParamType):
-    """Click parameter type for MT5 timeframe values."""
-
-    name = "TIMEFRAME"
-
-    def convert(
-        self,
-        value: object,
-        param: click.Parameter | None,
-        ctx: click.Context | None,
-    ) -> int:
-        """Convert a string or integer value to a timeframe integer.
-
-        Args:
-            value: Raw value from the command line.
-            param: Click parameter instance.
-            ctx: Click context.
-
-        Returns:
-            Integer timeframe value.
-        """
-        try:
-            return parse_timeframe(value)
-        except ValueError as exc:
-            self.fail(str(exc), param, ctx)
-
-
-class _TickFlagsType(click.ParamType):
-    """Click parameter type for MT5 tick copy flags."""
-
-    name = "FLAGS"
-
-    def convert(
-        self,
-        value: object,
-        param: click.Parameter | None,
-        ctx: click.Context | None,
-    ) -> int:
-        """Convert a string or integer value to a tick flags integer.
-
-        Args:
-            value: Raw value from the command line.
-            param: Click parameter instance.
-            ctx: Click context.
-
-        Returns:
-            Integer tick flag value.
-        """
-        try:
-            return parse_tick_flags(value)
-        except ValueError as exc:
-            self.fail(str(exc), param, ctx)
-
-
-class _RequestType(click.ParamType):
-    """Click parameter type for JSON order requests."""
-
-    name = "REQUEST"
-
-    def convert(
-        self,
-        value: object,
-        param: click.Parameter | None,
-        ctx: click.Context | None,
-    ) -> dict[str, Any]:
-        """Convert a raw CLI value to an order request dictionary.
-
-        Args:
-            value: Raw value from the command line.
-            param: Click parameter instance.
-            ctx: Click context.
-
-        Returns:
-            Parsed request dictionary.
-        """
-        try:
-            return parse_request(str(value))
-        except ValueError as exc:
-            self.fail(str(exc), param, ctx)
-
-
-DATETIME_TYPE = _DateTimeType()
-TIMEFRAME_TYPE = _TimeframeType()
-TICK_FLAGS_TYPE = _TickFlagsType()
-REQUEST_TYPE = _RequestType()
 
 # ---------------------------------------------------------------------------
 # Export context
@@ -363,14 +271,14 @@ def rates_from(
     timeframe: Annotated[
         int,
         typer.Option(
-            click_type=TIMEFRAME_TYPE,
+            parser=_parse_timeframe_parameter,
             help="Timeframe (e.g., M1, H1, D1, or integer).",
         ),
     ],
     date_from: Annotated[
         datetime,
         typer.Option(
-            click_type=DATETIME_TYPE,
+            parser=_parse_datetime_parameter,
             help="Start date in ISO 8601 format.",
         ),
     ],
@@ -390,7 +298,7 @@ def rates_from_pos(
     timeframe: Annotated[
         int,
         typer.Option(
-            click_type=TIMEFRAME_TYPE,
+            parser=_parse_timeframe_parameter,
             help="Timeframe.",
         ),
     ],
@@ -416,7 +324,7 @@ def latest_rates(
     timeframe: Annotated[
         int,
         typer.Option(
-            click_type=TIMEFRAME_TYPE,
+            parser=_parse_timeframe_parameter,
             help="Timeframe.",
         ),
     ],
@@ -445,17 +353,17 @@ def rates_range(
     timeframe: Annotated[
         int,
         typer.Option(
-            click_type=TIMEFRAME_TYPE,
+            parser=_parse_timeframe_parameter,
             help="Timeframe.",
         ),
     ],
     date_from: Annotated[
         datetime,
-        typer.Option(click_type=DATETIME_TYPE, help="Start date."),
+        typer.Option(parser=_parse_datetime_parameter, help="Start date."),
     ],
     date_to: Annotated[
         datetime,
-        typer.Option(click_type=DATETIME_TYPE, help="End date."),
+        typer.Option(parser=_parse_datetime_parameter, help="End date."),
     ],
 ) -> None:
     """Export rates for a date range."""
@@ -471,13 +379,13 @@ def ticks_from(
     symbol: Annotated[str, typer.Option(help="Symbol name.")],
     date_from: Annotated[
         datetime,
-        typer.Option(click_type=DATETIME_TYPE, help="Start date."),
+        typer.Option(parser=_parse_datetime_parameter, help="Start date."),
     ],
     count: Annotated[int, typer.Option(help="Number of ticks.")],
     flags: Annotated[
         int,
         typer.Option(
-            click_type=TICK_FLAGS_TYPE,
+            parser=_parse_tick_flags_parameter,
             help="Tick flags (ALL, INFO, TRADE, or integer).",
         ),
     ],
@@ -495,15 +403,15 @@ def ticks_range(
     symbol: Annotated[str, typer.Option(help="Symbol name.")],
     date_from: Annotated[
         datetime,
-        typer.Option(click_type=DATETIME_TYPE, help="Start date."),
+        typer.Option(parser=_parse_datetime_parameter, help="Start date."),
     ],
     date_to: Annotated[
         datetime,
-        typer.Option(click_type=DATETIME_TYPE, help="End date."),
+        typer.Option(parser=_parse_datetime_parameter, help="End date."),
     ],
     flags: Annotated[
         int,
-        typer.Option(click_type=TICK_FLAGS_TYPE, help="Tick flags."),
+        typer.Option(parser=_parse_tick_flags_parameter, help="Tick flags."),
     ],
 ) -> None:
     """Export ticks for a date range."""
@@ -523,7 +431,7 @@ def ticks_recent(
     ],
     date_to: Annotated[
         datetime | None,
-        typer.Option(click_type=DATETIME_TYPE, help="Window end date."),
+        typer.Option(parser=_parse_datetime_parameter, help="Window end date."),
     ] = None,
     count: Annotated[
         int,
@@ -532,7 +440,7 @@ def ticks_recent(
     flags: Annotated[
         int,
         typer.Option(
-            click_type=TICK_FLAGS_TYPE,
+            parser=_parse_tick_flags_parameter,
             help="Tick flags (ALL, INFO, TRADE, or integer).",
         ),
     ] = "ALL",  # pyright: ignore[reportArgumentType]
@@ -625,11 +533,11 @@ def history_orders(
     ctx: typer.Context,
     date_from: Annotated[
         datetime | None,
-        typer.Option(click_type=DATETIME_TYPE, help="Start date."),
+        typer.Option(parser=_parse_datetime_parameter, help="Start date."),
     ] = None,
     date_to: Annotated[
         datetime | None,
-        typer.Option(click_type=DATETIME_TYPE, help="End date."),
+        typer.Option(parser=_parse_datetime_parameter, help="End date."),
     ] = None,
     group: Annotated[str | None, typer.Option(help="Group filter.")] = None,
     symbol: Annotated[str | None, typer.Option(help="Symbol filter.")] = None,
@@ -655,11 +563,11 @@ def history_deals(
     ctx: typer.Context,
     date_from: Annotated[
         datetime | None,
-        typer.Option(click_type=DATETIME_TYPE, help="Start date."),
+        typer.Option(parser=_parse_datetime_parameter, help="Start date."),
     ] = None,
     date_to: Annotated[
         datetime | None,
-        typer.Option(click_type=DATETIME_TYPE, help="End date."),
+        typer.Option(parser=_parse_datetime_parameter, help="End date."),
     ] = None,
     group: Annotated[str | None, typer.Option(help="Group filter.")] = None,
     symbol: Annotated[str | None, typer.Option(help="Symbol filter.")] = None,
@@ -686,7 +594,7 @@ def recent_history_deals(
     hours: Annotated[float, typer.Option(help="Lookback window in hours.")],
     date_to: Annotated[
         datetime | None,
-        typer.Option(click_type=DATETIME_TYPE, help="Window end date."),
+        typer.Option(parser=_parse_datetime_parameter, help="Window end date."),
     ] = None,
     group: Annotated[str | None, typer.Option(help="Group filter.")] = None,
     symbol: Annotated[str | None, typer.Option(help="Symbol filter.")] = None,
@@ -744,7 +652,7 @@ def order_check(
     ctx: typer.Context,
     request: Annotated[
         dict[str, Any],
-        typer.Option(click_type=REQUEST_TYPE, help=_REQUEST_OPTION_HELP),
+        typer.Option(parser=_parse_request_parameter, help=_REQUEST_OPTION_HELP),
     ],
 ) -> None:
     """Check funds sufficiency for a trading operation."""
@@ -756,7 +664,7 @@ def order_send(
     ctx: typer.Context,
     request: Annotated[
         dict[str, Any],
-        typer.Option(click_type=REQUEST_TYPE, help=_REQUEST_OPTION_HELP),
+        typer.Option(parser=_parse_request_parameter, help=_REQUEST_OPTION_HELP),
     ],
     yes: Annotated[
         bool,
@@ -995,11 +903,11 @@ def collect_history(
     ],
     date_from: Annotated[
         datetime,
-        typer.Option(click_type=DATETIME_TYPE, help="Start date."),
+        typer.Option(parser=_parse_datetime_parameter, help="Start date."),
     ],
     date_to: Annotated[
         datetime,
-        typer.Option(click_type=DATETIME_TYPE, help="End date."),
+        typer.Option(parser=_parse_datetime_parameter, help="End date."),
     ],
     dataset: Annotated[
         list[Dataset] | None,
@@ -1016,14 +924,14 @@ def collect_history(
     timeframe: Annotated[
         int,
         typer.Option(
-            click_type=TIMEFRAME_TYPE,
+            parser=_parse_timeframe_parameter,
             help="Rates timeframe (e.g., M1, H1, D1).",
         ),
     ] = 1,
     flags: Annotated[
         int,
         typer.Option(
-            click_type=TICK_FLAGS_TYPE,
+            parser=_parse_tick_flags_parameter,
             help="Tick copy flags (ALL, INFO, TRADE, or integer).",
         ),
     ] = "ALL",  # pyright: ignore[reportArgumentType]

{mt5cli-1.2.2 → mt5cli-1.2.4}/mt5cli/client.py

@@ -355,12 +355,14 @@ def _shutdown_client(client: Mt5DataClient, *, raise_on_error: bool) -> None:
     failure is raised as the stable normalized exception. When False (an
     initialization or session-body exception is already propagating), the
     failure is logged so the primary exception passes through unchanged.
-    """  # noqa: DOC501
+
+    """
     try:
         client.shutdown()
     except Exception as exc:
         if raise_on_error:
-            raise normalize_mt5_exception(exc) from exc
+            normalized = normalize_mt5_exception(exc)
+            raise normalized from exc
         logger.warning("MT5 shutdown failed during cleanup", exc_info=True)
 
 
@@ -385,7 +387,7 @@ def _connected_client(
     Yields:
         Connected ``Mt5DataClient`` instance.
 
-    """  # noqa: DOC501
+    """
     client = (
         Mt5DataClient(config=config)
         if retry_count is None
@@ -395,7 +397,8 @@ def _connected_client(
         client.initialize_and_login_mt5()
     except Exception as exc:
         _shutdown_client(client, raise_on_error=False)
-        raise normalize_mt5_exception(exc) from exc
+        normalized = normalize_mt5_exception(exc)
+        raise normalized from exc
     try:
         yield client
     except BaseException:
@@ -420,12 +423,14 @@ def _run_with_client(
 
     Returns:
         Value returned by ``fetch_fn``.
-    """  # noqa: DOC501
+
+    """
     with _connected_client(config, retry_count=retry_count) as client:
         try:
             return fetch_fn(client)
         except Mt5RuntimeError as exc:
-            raise normalize_mt5_exception(exc) from exc
+            normalized = normalize_mt5_exception(exc)
+            raise normalized from exc
 
 
 class _BaseMT5Client:
@@ -480,7 +485,8 @@ class _BaseMT5Client:
 
         Returns:
             This client instance.
-        """  # noqa: DOC501
+
+        """
         if self._client is not None:
             return self
         client = Mt5DataClient(config=self._config, retry_count=self._retry_count)
@@ -488,7 +494,8 @@ class _BaseMT5Client:
             client.initialize_and_login_mt5()
         except Exception as exc:
             _shutdown_client(client, raise_on_error=False)
-            raise normalize_mt5_exception(exc) from exc
+            normalized = normalize_mt5_exception(exc)
+            raise normalized from exc
         self._client = client
         self._owns_client = True  # only set when this method created the client
         return self
@@ -787,6 +794,31 @@ class _BaseMT5Client:
         """Return the last tick for a symbol."""
         return self._fetch(lambda c: c.symbol_info_tick_as_df(symbol=symbol))
 
+    def symbol_info_tick_as_dict(
+        self,
+        symbol: str,
+        *,
+        skip_to_datetime: bool = False,
+    ) -> dict[str, object]:
+        """Return the last tick as a plain mapping.
+
+        Args:
+            symbol: Symbol name.
+            skip_to_datetime: Preserve numeric MT5 time fields when ``True``.
+
+        Returns:
+            Tick fields using the underlying pdmt5 conversion behavior.
+        """
+        return self._fetch_value(
+            lambda c: cast(
+                "dict[str, object]",
+                c.symbol_info_tick_as_dict(
+                    symbol=symbol,
+                    skip_to_datetime=skip_to_datetime,
+                ),
+            )
+        )
+
     def market_book(self, symbol: str) -> pd.DataFrame:
         """Return market depth for a symbol."""
         return self._fetch(lambda c: c.market_book_get_as_df(symbol=symbol))

{mt5cli-1.2.2 → mt5cli-1.2.4}/mt5cli/history.py

@@ -2755,11 +2755,7 @@ class ThrottledHistoryUpdater:
             When ``suppress_errors`` is False, recoverable update failures
             propagate to the caller.
 
-        Raises:
-            Mt5ConnectionError: When ``suppress_errors`` is False and the
-                update fails with a recoverable MT5, SQLite, validation, or
-                I/O error.
-        """  # noqa: DOC502
+        """
         if not self.should_update():
             return False
         try:

{mt5cli-1.2.2 → mt5cli-1.2.4}/mt5cli/trading.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import logging
 from dataclasses import asdict, dataclass
 from datetime import UTC, datetime
+from inspect import signature
 from math import floor, isfinite
 from numbers import Integral, Real
 from typing import TYPE_CHECKING, Literal, Protocol, TypedDict, cast
@@ -20,6 +21,7 @@ if TYPE_CHECKING:
     from typing import Any
 
 _logger = logging.getLogger(__name__)
+_DATETIME_TYPES = (datetime, pd.Timestamp)
 
 
 class _Mt5ClientProtocol(Protocol):
@@ -801,16 +803,57 @@ def get_tick_snapshot(
     client: _Mt5ClientProtocol,
     symbol: str,
 ) -> dict[str, float | int | None]:
-    """Return normalized latest tick data, including bid, ask, and timestamp."""
+    """Return normalized latest tick data with a numeric MT5 timestamp.
+
+    The numeric ``time`` preserves the original value returned by MT5 without
+    applying timezone or server-offset correction.
+    """
     method = getattr(client, "symbol_info_tick_as_dict", None)
-    value = (
-        method(symbol=symbol) if callable(method) else client.symbol_info_tick(symbol)
-    )
+    if callable(method):
+        try:
+            signature(method).bind(symbol=symbol, skip_to_datetime=True)
+        except (TypeError, ValueError):
+            value = method(symbol=symbol)
+        else:
+            value = method(symbol=symbol, skip_to_datetime=True)
+    else:
+        value = client.symbol_info_tick(symbol)
     snapshot = _snapshot_from_value(value, _TICK_SNAPSHOT_FIELDS)
     snapshot["symbol"] = snapshot.get("symbol") or symbol
+    snapshot["time"] = _numeric_tick_time(snapshot.get("time"))
     return cast("dict[str, float | int | None]", snapshot)
 
 
+def _numeric_tick_time(value: object) -> float | int | None:
+    """Normalize an MT5 timestamp to its numeric epoch representation.
+
+    Returns:
+        The numeric timestamp, or ``None`` for an unsupported value.
+    """
+    numeric: float | None
+    if value is None or isinstance(value, bool):
+        numeric = None
+    elif isinstance(value, _DATETIME_TYPES):
+        if pd.isna(value):
+            return None
+        timestamp = pd.Timestamp(value)
+        if timestamp.tzinfo is None:
+            timestamp = timestamp.tz_localize(UTC)
+        numeric = timestamp.timestamp()
+    elif isinstance(value, Integral):
+        return int(value)
+    elif isinstance(value, Real):
+        numeric = float(value)
+    elif isinstance(value, str):
+        try:
+            numeric = float(value)
+        except ValueError:
+            return None
+    else:
+        numeric = None
+    return numeric if numeric is not None and isfinite(numeric) else None
+
+
 _SERVER_CLOCK_OFFSET_ROUNDING_SECONDS = 1800.0
 _MAX_PLAUSIBLE_SERVER_CLOCK_OFFSET_SECONDS = 14 * 3600.0
 
@@ -821,12 +864,12 @@ def estimate_server_clock_offset_seconds(
 ) -> float | None:
     """Estimate the broker server clock offset from true UTC.
 
-    MT5 tick, bar, and deal timestamps are epoch values labeled in the
-    broker server's wall clock, which is commonly UTC+2 or UTC+3 rather
-    than true UTC. This reads the latest tick for ``symbol`` and compares
-    its timestamp to the current UTC time, rounding to the nearest half
-    hour: server offsets are whole or half-hour multiples, and rounding
-    absorbs a few minutes of real tick staleness.
+    MT5 documents copied tick and bar data as UTC, while the timezone contract
+    for ``symbol_info_tick()`` is not explicit. This helper reads the latest
+    tick for ``symbol`` to validate a suspected broker-specific clock offset
+    before downstream correction. It compares the tick timestamp to the
+    current UTC time and rounds to the nearest half hour, absorbing a few
+    minutes of real tick staleness.
 
     On a closed market, weekend, holiday, or illiquid symbol the latest tick
     can be hours or days old, in which case the tick-vs-now delta reflects