mt5cli 1.4.1__tar.gz → 1.4.2__tar.gz

{mt5cli-1.4.1 → mt5cli-1.4.2}/.agents/skills/local-qa/scripts/qa.sh

@@ -9,6 +9,7 @@ export NPM_CONFIG_MIN_RELEASE_AGE="${COOLDOWN_DAYS}"
 export PNPM_CONFIG_MINIMUM_RELEASE_AGE=$((COOLDOWN_DAYS * 24 * 60))
 
 # Python
+uv sync
 uv run ruff format .
 uv run ruff check --fix .
 uv run pyright .

{mt5cli-1.4.1 → mt5cli-1.4.2}/.agents/skills/mt5cli/SKILL.md

@@ -41,8 +41,10 @@ Global options MUST precede the subcommand.
 
 ### Parameter value formats
 
-- **Datetimes** (`--date-from`, `--date-to`): ISO 8601 (`2024-01-01` or
-  `2024-01-01T12:00:00+00:00`). Naive values are treated as UTC.
+- **Datetimes** (`--date-from`, `--date-to`): offset-free ISO 8601 values
+  (`2024-01-01` or `2024-01-01T12:00:00`). MT5 bounds are timezone-naive
+  trade-server wall-clock values; offset-bearing values are rejected and no
+  UTC-to-server-time conversion is inferred.
 - **Timeframe** (`--timeframe`): `M1`, `M2`, `M3`, `M4`, `M5`, `M6`, `M10`,
   `M12`, `M15`, `M20`, `M30`, `H1`, `H2`, `H3`, `H4`, `H6`, `H8`, `H12`,
   `D1`, `W1`, `MN1`, or the raw integer.

{mt5cli-1.4.1 → mt5cli-1.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mt5cli
-Version: 1.4.1
+Version: 1.4.2
 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>
@@ -50,7 +50,7 @@ Built on top of [pdmt5](https://github.com/dceoy/pdmt5), a pandas-based data han
 - **Comprehensive data access**: Rates, ticks, account info, symbols, orders, positions, and trading history
 - **Flexible timeframes**: Named timeframes (M1, H1, D1, etc.) and numeric values
 - **Connection management**: Optional credentials, server, and timeout configuration
-- **SQLite rate loading**: Load mt5cli-managed rate tables/views for offline workflows
+- **SQLite rate loading**: Load canonical normalized `rates` storage for offline workflows
 
 ## Installation
 
@@ -69,7 +69,7 @@ pip install -U "mt5cli[parquet]" MetaTrader5
 Import `MT5Client` for generic MT5 data access, schema normalization, and optional order primitives.
 
 ```python
-from datetime import UTC, datetime
+from datetime import datetime
 from pathlib import Path
 
 from mt5cli import (
@@ -103,8 +103,8 @@ export_dataframe(closed_rates, Path("rates.csv"), "csv")
 collect_history(
     Path("history.db"),
     symbols=["EURUSD"],
-    date_from=datetime(2024, 1, 1, tzinfo=UTC),
-    date_to=datetime(2024, 2, 1, tzinfo=UTC),
+    date_from=datetime(2024, 1, 1),
+    date_to=datetime(2024, 2, 1),
     datasets={Dataset.rates, Dataset.history_deals},
 )
 
@@ -113,9 +113,16 @@ update_history_with_config(
     output="history.db",
     symbols=["EURUSD"],
     config=build_config(login=12345),
+    date_to=datetime(2024, 2, 1),
 )
 ```
 
+MT5 query bounds are timezone-naive trade-server wall-clock datetimes, as
+required by pdmt5. Incremental history updates require an explicit `date_to`
+because mt5cli cannot determine the current trade-server time. Offset-bearing
+strings and timezone-aware `datetime` objects are rejected; mt5cli does not
+infer or strip offsets to perform a conversion.
+
 Schema contracts live in `mt5cli.schemas` (`DataKind`, `validate_schema`, `normalize_dataframe`). Export and storage helpers are in `mt5cli.utils` (`Dataset`, `export_dataframe`) and `mt5cli.history`.
 
 `MT5Client.order_send()` is a live execution primitive: it can place real trades on the connected account. mt5cli does not implement strategy logic, signal generation, backtesting, or optimization — downstream applications must gate live execution explicitly.
@@ -335,6 +342,8 @@ OpenTelemetry metrics are documented in [`docs/api/telemetry.md`](docs/api/telem
 For automated pipelines, use the importable incremental API instead of re-fetching fixed date ranges:
 
 ```python
+from datetime import datetime
+
 from pdmt5 import Mt5Config
 from mt5cli import update_history_with_config
 from mt5cli.utils import Dataset
@@ -347,19 +356,17 @@ update_history_with_config(
     datasets={Dataset.rates, Dataset.history_deals},
     timeframes=["M1", "H1"],  # default: all fixed MT5 timeframes
     lookback_hours=24,
-    create_rate_views=True,
+    date_to=datetime(2024, 2, 1),
     with_views=True,
     include_account_events=True,
 )
 ```
 
 - **`collect-history`**: explicit date-range export into SQLite.
-- **`update_history`**: incremental append based on existing SQLite `MAX(time)` per symbol (and timeframe for rates); account-level deals use a separate cursor when `include_account_events=True`.
+- **`update_history`**: incremental append based on existing SQLite `MAX(time)` per symbol (and timeframe for rates); account-level deals use a separate cursor when `include_account_events=True`. Pass an explicit naive trade-server `date_to`; mt5cli cannot determine the current server time. Rates are persisted only in the canonical normalized `rates` table.
 - **`rates` table**: normalized storage with `symbol` and `timeframe` columns.
-- **Rate compatibility views**: mt5cli manages all `rate_*` views. Naming is `rate_<symbol>__<timeframe>` when a symbol has one timeframe, otherwise `rate_<symbol>__<granularity>_<timeframe>` (for example `rate_EURUSD__M1_1`). Stale `rate_*` views are dropped and recreated when rates change for offline downstream tools.
-- **Rate view resolution**: use `resolve_rate_view_name()` / `resolve_rate_view_names()` to map symbols and granularities to existing SQLite compatibility views without creating databases. Both accept `None` (or a missing path) and return deterministic default names unless `require_existing=True`.
-- **Rate view loading**: use `load_rate_data()` / `load_rate_data_from_connection()` to load a SQLite rate table or view into a `DatetimeIndex` DataFrame.
-- **Multi-series rate loading**: use `build_rate_targets()` to build neutral `RateTarget(symbol, timeframe)` pairs, `resolve_rate_tables()` to map them to table/view names (pass `require_existing=True` for strict resolution), and `load_rate_series_from_sqlite()` to load them into a mapping keyed by `(symbol, integer timeframe)`. The loader requires existing managed views unless `explicit_tables` is supplied, and rejects duplicate `(symbol, timeframe)` targets.
+- **Explicit table loading**: use `load_rate_data()` / `load_rate_data_from_connection()` for intentionally named custom SQLite rate tables.
+- **Multi-series rate loading**: use `build_rate_targets()` to build neutral `RateTarget(symbol, timeframe)` pairs and `load_rate_series_from_sqlite()` to load canonical `rates` rows into a mapping keyed by `(symbol, integer timeframe)`. Pass `explicit_tables` only for intentionally named custom tables; duplicate `(symbol, timeframe)` targets are rejected.
 - **Multi-account latest rates**: use `collect_latest_rates_for_accounts()` with `AccountSpec` to read the latest bars for several account groups, merged into a `(symbol, integer timeframe)` mapping. For long-running pollers, `collect_latest_rates_for_accounts_with_retries()` adds bounded exponential backoff that retries only recoverable MT5 errors and re-raises once `retry_count` is exhausted.
 - **Latest closed bars**: use `collect_latest_closed_rates_for_accounts()` when downstream logic must exclude the still-forming current bar. It fetches `count + 1` bars at `start_pos=0`, drops the last row with `drop_forming_rate_bar()`, and validates each series is non-empty. `collect_latest_closed_rates_by_granularity()` returns the same data keyed by `(symbol, granularity_name)` such as `("EURUSD", "M1")`.
 
@@ -376,7 +383,7 @@ eurusd_m1 = rates["EURUSD", "M1"]  # closed bars only
 ```
 
 - **Credential resolution**: use `resolve_account_spec()` / `resolve_account_specs()` to merge explicit override values over `AccountSpec` fields and expand `${ENV_VAR}` placeholders (via `substitute_env_placeholders()`), raising `ValueError` for missing variables. This keeps secrets out of plan/config files without coupling to any strategy code. For config dicts or nested structures loaded from YAML/TOML, use `substitute_mapping_values(data, keys={"login", "password"})` to expand placeholders only for caller-specified keys — key names are never hard-coded in mt5cli.
-- **Throttled history updates**: use `ThrottledHistoryUpdater` to wrap `update_history()` with a minimum `interval_seconds` between successful runs (monotonic clock). Call `should_update()` / `update(client, symbols)` from an application loop; errors propagate by default, or pass `suppress_errors=True` to swallow recoverable `Mt5*Error`, `sqlite3.Error`, `ValueError`, and `OSError` without advancing the throttle (`AttributeError` / `TypeError` always propagate, since the client passed to `update()` must implement the canonical `HistoryClient` method names). Pass `update_backend` to inject a custom history update callable (same keyword arguments as `update_history`) instead of monkey-patching `mt5cli.history.update_history`.
+- **Throttled history updates**: use `ThrottledHistoryUpdater` to wrap `update_history()` with a minimum `interval_seconds` between successful runs (monotonic clock). Call `should_update()` / `update(client, symbols, date_to=...)` from an application loop; errors propagate by default, or pass `suppress_errors=True` to swallow recoverable `Mt5*Error`, `sqlite3.Error`, `ValueError`, and `OSError` without advancing the throttle (`AttributeError` / `TypeError` always propagate, since the client passed to `update()` must implement the canonical `HistoryClient` method names). Pass `update_backend` to inject a custom history update callable (same keyword arguments as `update_history`) instead of monkey-patching `mt5cli.history.update_history`.
 - **Trading helpers**: use `mt5_session()` for both market data and generic execution helpers. It owns initialization and shutdown for sessions it creates; caller-supplied clients remain caller-owned.
 - **Granularity-keyed rate loading**: `load_rate_series_by_granularity()` builds targets with `build_rate_targets()`, loads them with `load_rate_series_from_sqlite()`, and returns a mapping keyed by `(symbol | None, granularity_name)` such as `("EURUSD", "M1")` to reduce downstream boilerplate.
 - **MT5 session helper**: use the `mt5_session()` context manager to attach to (or, when `Mt5Config.path` is set, launch) an MT5 terminal, log in, and yield a connected `MT5Client` that shuts down on exit.
@@ -434,7 +441,7 @@ updater = ThrottledHistoryUpdater(
     output="history.db", interval_seconds=60, suppress_errors=True
 )
 with mt5_session(Mt5Config(login=login)) as client:
-    updater.update(client, ["EURUSD"])
+    updater.update(client, ["EURUSD"], date_to="2024-02-01")
 ```
 
 Read-only collectors can keep using `mt5_session()` and `MT5Client`.

{mt5cli-1.4.1 → mt5cli-1.4.2}/README.md

@@ -21,7 +21,7 @@ Built on top of [pdmt5](https://github.com/dceoy/pdmt5), a pandas-based data han
 - **Comprehensive data access**: Rates, ticks, account info, symbols, orders, positions, and trading history
 - **Flexible timeframes**: Named timeframes (M1, H1, D1, etc.) and numeric values
 - **Connection management**: Optional credentials, server, and timeout configuration
-- **SQLite rate loading**: Load mt5cli-managed rate tables/views for offline workflows
+- **SQLite rate loading**: Load canonical normalized `rates` storage for offline workflows
 
 ## Installation
 
@@ -40,7 +40,7 @@ pip install -U "mt5cli[parquet]" MetaTrader5
 Import `MT5Client` for generic MT5 data access, schema normalization, and optional order primitives.
 
 ```python
-from datetime import UTC, datetime
+from datetime import datetime
 from pathlib import Path
 
 from mt5cli import (
@@ -74,8 +74,8 @@ export_dataframe(closed_rates, Path("rates.csv"), "csv")
 collect_history(
     Path("history.db"),
     symbols=["EURUSD"],
-    date_from=datetime(2024, 1, 1, tzinfo=UTC),
-    date_to=datetime(2024, 2, 1, tzinfo=UTC),
+    date_from=datetime(2024, 1, 1),
+    date_to=datetime(2024, 2, 1),
     datasets={Dataset.rates, Dataset.history_deals},
 )
 
@@ -84,9 +84,16 @@ update_history_with_config(
     output="history.db",
     symbols=["EURUSD"],
     config=build_config(login=12345),
+    date_to=datetime(2024, 2, 1),
 )
 ```
 
+MT5 query bounds are timezone-naive trade-server wall-clock datetimes, as
+required by pdmt5. Incremental history updates require an explicit `date_to`
+because mt5cli cannot determine the current trade-server time. Offset-bearing
+strings and timezone-aware `datetime` objects are rejected; mt5cli does not
+infer or strip offsets to perform a conversion.
+
 Schema contracts live in `mt5cli.schemas` (`DataKind`, `validate_schema`, `normalize_dataframe`). Export and storage helpers are in `mt5cli.utils` (`Dataset`, `export_dataframe`) and `mt5cli.history`.
 
 `MT5Client.order_send()` is a live execution primitive: it can place real trades on the connected account. mt5cli does not implement strategy logic, signal generation, backtesting, or optimization — downstream applications must gate live execution explicitly.
@@ -306,6 +313,8 @@ OpenTelemetry metrics are documented in [`docs/api/telemetry.md`](docs/api/telem
 For automated pipelines, use the importable incremental API instead of re-fetching fixed date ranges:
 
 ```python
+from datetime import datetime
+
 from pdmt5 import Mt5Config
 from mt5cli import update_history_with_config
 from mt5cli.utils import Dataset
@@ -318,19 +327,17 @@ update_history_with_config(
     datasets={Dataset.rates, Dataset.history_deals},
     timeframes=["M1", "H1"],  # default: all fixed MT5 timeframes
     lookback_hours=24,
-    create_rate_views=True,
+    date_to=datetime(2024, 2, 1),
     with_views=True,
     include_account_events=True,
 )
 ```
 
 - **`collect-history`**: explicit date-range export into SQLite.
-- **`update_history`**: incremental append based on existing SQLite `MAX(time)` per symbol (and timeframe for rates); account-level deals use a separate cursor when `include_account_events=True`.
+- **`update_history`**: incremental append based on existing SQLite `MAX(time)` per symbol (and timeframe for rates); account-level deals use a separate cursor when `include_account_events=True`. Pass an explicit naive trade-server `date_to`; mt5cli cannot determine the current server time. Rates are persisted only in the canonical normalized `rates` table.
 - **`rates` table**: normalized storage with `symbol` and `timeframe` columns.
-- **Rate compatibility views**: mt5cli manages all `rate_*` views. Naming is `rate_<symbol>__<timeframe>` when a symbol has one timeframe, otherwise `rate_<symbol>__<granularity>_<timeframe>` (for example `rate_EURUSD__M1_1`). Stale `rate_*` views are dropped and recreated when rates change for offline downstream tools.
-- **Rate view resolution**: use `resolve_rate_view_name()` / `resolve_rate_view_names()` to map symbols and granularities to existing SQLite compatibility views without creating databases. Both accept `None` (or a missing path) and return deterministic default names unless `require_existing=True`.
-- **Rate view loading**: use `load_rate_data()` / `load_rate_data_from_connection()` to load a SQLite rate table or view into a `DatetimeIndex` DataFrame.
-- **Multi-series rate loading**: use `build_rate_targets()` to build neutral `RateTarget(symbol, timeframe)` pairs, `resolve_rate_tables()` to map them to table/view names (pass `require_existing=True` for strict resolution), and `load_rate_series_from_sqlite()` to load them into a mapping keyed by `(symbol, integer timeframe)`. The loader requires existing managed views unless `explicit_tables` is supplied, and rejects duplicate `(symbol, timeframe)` targets.
+- **Explicit table loading**: use `load_rate_data()` / `load_rate_data_from_connection()` for intentionally named custom SQLite rate tables.
+- **Multi-series rate loading**: use `build_rate_targets()` to build neutral `RateTarget(symbol, timeframe)` pairs and `load_rate_series_from_sqlite()` to load canonical `rates` rows into a mapping keyed by `(symbol, integer timeframe)`. Pass `explicit_tables` only for intentionally named custom tables; duplicate `(symbol, timeframe)` targets are rejected.
 - **Multi-account latest rates**: use `collect_latest_rates_for_accounts()` with `AccountSpec` to read the latest bars for several account groups, merged into a `(symbol, integer timeframe)` mapping. For long-running pollers, `collect_latest_rates_for_accounts_with_retries()` adds bounded exponential backoff that retries only recoverable MT5 errors and re-raises once `retry_count` is exhausted.
 - **Latest closed bars**: use `collect_latest_closed_rates_for_accounts()` when downstream logic must exclude the still-forming current bar. It fetches `count + 1` bars at `start_pos=0`, drops the last row with `drop_forming_rate_bar()`, and validates each series is non-empty. `collect_latest_closed_rates_by_granularity()` returns the same data keyed by `(symbol, granularity_name)` such as `("EURUSD", "M1")`.
 
@@ -347,7 +354,7 @@ eurusd_m1 = rates["EURUSD", "M1"]  # closed bars only
 ```
 
 - **Credential resolution**: use `resolve_account_spec()` / `resolve_account_specs()` to merge explicit override values over `AccountSpec` fields and expand `${ENV_VAR}` placeholders (via `substitute_env_placeholders()`), raising `ValueError` for missing variables. This keeps secrets out of plan/config files without coupling to any strategy code. For config dicts or nested structures loaded from YAML/TOML, use `substitute_mapping_values(data, keys={"login", "password"})` to expand placeholders only for caller-specified keys — key names are never hard-coded in mt5cli.
-- **Throttled history updates**: use `ThrottledHistoryUpdater` to wrap `update_history()` with a minimum `interval_seconds` between successful runs (monotonic clock). Call `should_update()` / `update(client, symbols)` from an application loop; errors propagate by default, or pass `suppress_errors=True` to swallow recoverable `Mt5*Error`, `sqlite3.Error`, `ValueError`, and `OSError` without advancing the throttle (`AttributeError` / `TypeError` always propagate, since the client passed to `update()` must implement the canonical `HistoryClient` method names). Pass `update_backend` to inject a custom history update callable (same keyword arguments as `update_history`) instead of monkey-patching `mt5cli.history.update_history`.
+- **Throttled history updates**: use `ThrottledHistoryUpdater` to wrap `update_history()` with a minimum `interval_seconds` between successful runs (monotonic clock). Call `should_update()` / `update(client, symbols, date_to=...)` from an application loop; errors propagate by default, or pass `suppress_errors=True` to swallow recoverable `Mt5*Error`, `sqlite3.Error`, `ValueError`, and `OSError` without advancing the throttle (`AttributeError` / `TypeError` always propagate, since the client passed to `update()` must implement the canonical `HistoryClient` method names). Pass `update_backend` to inject a custom history update callable (same keyword arguments as `update_history`) instead of monkey-patching `mt5cli.history.update_history`.
 - **Trading helpers**: use `mt5_session()` for both market data and generic execution helpers. It owns initialization and shutdown for sessions it creates; caller-supplied clients remain caller-owned.
 - **Granularity-keyed rate loading**: `load_rate_series_by_granularity()` builds targets with `build_rate_targets()`, loads them with `load_rate_series_from_sqlite()`, and returns a mapping keyed by `(symbol | None, granularity_name)` such as `("EURUSD", "M1")` to reduce downstream boilerplate.
 - **MT5 session helper**: use the `mt5_session()` context manager to attach to (or, when `Mt5Config.path` is set, launch) an MT5 terminal, log in, and yield a connected `MT5Client` that shuts down on exit.
@@ -405,7 +412,7 @@ updater = ThrottledHistoryUpdater(
     output="history.db", interval_seconds=60, suppress_errors=True
 )
 with mt5_session(Mt5Config(login=login)) as client:
-    updater.update(client, ["EURUSD"])
+    updater.update(client, ["EURUSD"], date_to="2024-02-01")
 ```
 
 Read-only collectors can keep using `mt5_session()` and `MT5Client`.

{mt5cli-1.4.1 → mt5cli-1.4.2}/docs/api/history.md

@@ -20,6 +20,13 @@ append using dataset-specific keys (for example `ticket` on history tables, or
 Optional views are created when `--with-views` is set and the `history-deals` dataset
 was written.
 
+All MT5 history query bounds are timezone-naive trade-server wall-clock
+datetimes, matching pdmt5. Offset-bearing strings and timezone-aware
+`datetime` values are rejected; incremental cursors and returned history
+frames use the same naive contract, and no broker-time conversion is inferred.
+Incremental updates require an explicit `date_to` because mt5cli cannot
+determine the current MT5 trade-server time.
+
 `ticks` and `symbols` are opt-in datasets (pass `--dataset ticks` /
 `--dataset symbols`); they are excluded from the default `rates`,
 `history-orders`, `history-deals` selection. Unlike the other datasets,
@@ -157,135 +164,56 @@ when required columns are missing.
 
 ### Incremental collection
 
-The `update_history` SDK path uses the same base tables and optional
-`cash_events` / `positions_reconstructed` views. It additionally maintains
-`rate_<symbol>__<timeframe>` compatibility views when `create_rate_views=True`.
-
-### Rate view resolution
-
-Downstream tools can resolve mt5cli-managed compatibility view names from an
-existing SQLite history database without creating files or guessing naming
-schemes:
-
-```python
-from pathlib import Path
-
-from mt5cli.history import resolve_rate_view_name, resolve_rate_view_names
-
-# Single symbol and granularity
-view = resolve_rate_view_name(Path("history.db"), "EURUSD", "M1")
-
-# Batch resolution in row-major order
-views = resolve_rate_view_names(
-    Path("history.db"),
-    ["EURUSD", "GBPUSD"],
-    ["M1", "H1"],
-)
-```
-
-Resolution rules:
-
-- Returns `rate_<symbol>__<timeframe>` when a symbol stores one timeframe.
-- Returns `rate_<symbol>__<granularity>_<timeframe>` when multiple timeframes
-  are stored for the same symbol.
-- When multiple naming candidates apply, prefers an existing managed
-  `rate_*__*` view from the candidate list.
-- Falls back to single-timeframe naming when the database path is missing or
-  `rates` metadata is unavailable.
-- Pass `require_existing=True` to raise `ValueError` instead of returning a
-  best-guess name when the database or view is missing.
-- Accepts either a SQLite path or an open `sqlite3.Connection`.
+The package-root `mt5cli.update_history` SDK path uses the normalized `rates`
+table and optional `cash_events` / `positions_reconstructed` views. It writes the canonical normalized `rates` table directly and does not
+maintain per-series compatibility views.
 
 ### Rate data loading
 
-The canonical normalized rate table is `rates`; compatibility views are named
-with `rate_<symbol>__<timeframe>` for single-timeframe symbols or
-`rate_<symbol>__<granularity>_<timeframe>` when a symbol has multiple stored
-timeframes. `resolve_rate_table_name()` returns `rates`, while
-`resolve_rate_view_name()` returns the per-symbol compatibility view name.
+The canonical managed rate store is the normalized `rates` table. Stable
+symbol/timeframe reads query that table directly; mt5cli does not create,
+discover, resolve, or maintain per-series `rate_*` compatibility views.
 
-Use `load_rate_data()` or `load_rate_series_from_sqlite(..., table=...)` to load
-a single table or view from a SQLite path. Use
-`load_rate_series_by_granularity()` to load multiple instrument/granularity
-targets without hard-coding view names:
+Use `load_rate_series_from_sqlite()` or
+`load_rate_series_by_granularity()` for canonical managed data:
 
 ```python
 from pathlib import Path
 
 from mt5cli import (
+    build_rate_targets,
     load_rate_series_by_granularity,
     load_rate_series_from_sqlite,
 )
-from mt5cli.history import (
-    load_rate_data,
-    resolve_rate_table_name,
-    resolve_rate_view_name,
-)
 
-view = resolve_rate_view_name(Path("history.db"), "EURUSD", "M1", require_existing=True)
-rates = load_rate_data(Path("history.db"), view, count=1000)
-same_rates = load_rate_series_from_sqlite(Path("history.db"), table=view, count=1000)
+path = Path("history.db")
+targets = build_rate_targets(["EURUSD", "GBPUSD"], ["M1", "H1"])
+series = load_rate_series_from_sqlite(path, targets, count=1000)
+eurusd_m1 = series["EURUSD", 1]
 
-table = resolve_rate_table_name("EURUSD", "M1")  # "rates"
-series = load_rate_series_by_granularity(
-    Path("history.db"),
+by_name = load_rate_series_by_granularity(
+    path,
     symbols=["EURUSD", "GBPUSD"],
     granularities=["M1", "H1"],
     count=500,
 )
+eurusd_m1_named = by_name["EURUSD", "M1"]
 ```
 
-`count` returns the latest rows while preserving chronological order. Missing
-tables/views and mismatched `explicit_tables` lengths raise `ValueError` with
-the requested database target in the message.
-
-The loader accepts close-based OHLC rate data or tick-like bid/ask data. It
-validates that `time` exists, parses timestamps with pandas, and returns a
-DataFrame indexed by ascending `DatetimeIndex` named `time`.
-
-### Multi-series rate loading
-
-For loading many rate series at once, build neutral `RateTarget` pairs and load
-them from SQLite in one call. View names are resolved via the same
-compatibility-view rules, or you can pass `explicit_tables` to bypass resolution:
-
-```python
-from pathlib import Path
-
-from mt5cli import build_rate_targets, load_rate_series_from_sqlite
+Canonical reads apply `count` in SQLite and return the selected rows in
+chronological order. Each returned series uses an ascending `DatetimeIndex`
+named `time`. Timezone-naive MT5 trade-server wall-clock timestamps remain
+naive; explicitly timezone-aware timestamps preserve their instant and are
+normalized to UTC.
 
-targets = build_rate_targets(["EURUSD", "GBPUSD"], ["M1", "H1"])
-series = load_rate_series_from_sqlite(Path("history.db"), targets, count=1000)
-frame = series["EURUSD", 1]  # keyed by (symbol, integer timeframe)
-```
+`explicit_tables` and the single-table `table=` form are reserved for
+intentionally named custom tables. They do not discover or fall back to
+managed per-series views. Explicit table counts must match target counts, and
+duplicate `(symbol, timeframe)` targets are rejected.
 
-- `build_rate_targets()` returns `RateTarget(symbol, timeframe)` pairs in
-  row-major order, normalizing timeframe names such as `"M1"` to their integer
-  values; set `allow_missing_symbol=True` to address series solely by
-  `explicit_tables` (targets carry `symbol=None`).
-- `resolve_rate_tables()` maps targets to table or view names and validates that
-  any `explicit_tables` count matches the target count. Pass
-  `require_existing=True` to raise `ValueError` instead of returning a
-  best-guess name when the database or managed view is missing. When
-  `explicit_tables` is provided, names are returned as-is and
-  `require_existing` is ignored.
-- `load_rate_series_from_sqlite()` returns a mapping keyed by
-  `(symbol, integer timeframe)`. Unless `explicit_tables` is supplied, it
-  requires existing managed `rate_*__*` compatibility views and raises
-  `ValueError` when they are missing. Duplicate `(symbol, timeframe)` targets
-  are rejected.
-- `load_rate_series_by_granularity()` is a thin wrapper that builds the targets,
-  loads the series, and rekeys the result by granularity name to avoid
-  converting integer timeframes downstream:
-
-  ```python
-  from mt5cli import load_rate_series_by_granularity
-
-  series = load_rate_series_by_granularity(
-      "history.db", ["EURUSD"], ["M1", "H1"], count=1000
-  )
-  frame = series["EURUSD", "M1"]  # keyed by (symbol | None, granularity_name)
-  ```
+`load_rate_data()` / `load_rate_data_from_connection()` remain available for
+low-level explicit-table reads. These helpers validate that `time` exists and
+return an ascending `DatetimeIndex` named `time`.
 
 ## Throttled incremental history updates
 
@@ -294,6 +222,8 @@ between successful runs (using a monotonic clock), so an application loop can
 call it every iteration without over-fetching.
 
 ```python
+from datetime import datetime
+
 from pdmt5 import Mt5Config
 
 from mt5cli import ThrottledHistoryUpdater, mt5_session
@@ -308,7 +238,11 @@ updater = ThrottledHistoryUpdater(
 
 with mt5_session(Mt5Config(login=12345)) as client:
     while True:
-        updater.update(client, ["EURUSD", "GBPUSD"])  # no-op until 60s elapse
+        updater.update(
+            client,
+            ["EURUSD", "GBPUSD"],
+            date_to=datetime(2024, 2, 1),
+        )  # no-op until 60s elapse
         # ... do other work; break when shutting down ...
 ```
 
@@ -316,7 +250,7 @@ Pass `update_backend` to substitute the default `update_history` implementation
 without monkey-patching `mt5cli.history.update_history`. The callable receives the
 same keyword arguments as `update_history` (`client`, `output`, `symbols`,
 `datasets`, `timeframes`, `flags`, `lookback_hours`, `with_views`,
-`include_account_events`). The resolved backend is stored on
+`date_to`, `include_account_events`). The resolved backend is stored on
 `updater.update_backend` for inspection or subclassing.
 
 ```python

{mt5cli-1.4.1 → mt5cli-1.4.2}/docs/api/public-contract.md

@@ -23,7 +23,7 @@ Note: the former `mt5cli` re-export `TICK_FLAG_MAP` corresponds to `COPY_TICKS_M
 in pdmt5 — the name changed, it was not simply moved.
 
 Downstream packages should import from the package root (`from mt5cli import
-...`). The contract set `STABLE_SDK_EXPORTS` in `mt5cli.contract` enumerates
+...`). The authoritative SDK declaration in `mt5cli.sdk` enumerates
 every package-root symbol. Helpers promoted for downstream use, including selected configuration and
 parsing utilities, history timeframe resolution, and Grafana schema setup, are
 part of that root contract. Other low-level
@@ -32,20 +32,23 @@ from their owning modules.
 
 ### Module responsibility map
 
-`mt5cli.sdk` has been removed. Each capability now has exactly one owning
-module:
-
-| Module                 | Owns                                                                                                                                            |
-| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| `mt5cli.client`        | Connection lifecycle (`build_config`, `mt5_session`, `MT5Client`); the sole session factory                                                     |
-| `mt5cli.marketdata`    | Stateless one-off market-data reads and multi-account rate collection (`AccountSpec`, `collect_latest_rates_for_accounts`, etc.)                |
-| `mt5cli.history`       | History collection, incremental updates, and SQLite storage (`collect_history`, `update_history`, `write_*_dataset`, `ThrottledHistoryUpdater`) |
-| `mt5cli.observability` | Observability snapshot orchestration (`update_observability`, `update_observability_with_config`)                                               |
-| `mt5cli.grafana`       | Grafana schema, views, and snapshot persistence                                                                                                 |
-| `mt5cli.trading`       | Order preparation, broker-facing calculations, and normalized execution receipts                                                                |
-| `mt5cli.contract`      | `STABLE_SDK_EXPORTS` and the internal `HistoryClient` / `ObservabilityClient` protocols                                                         |
-| `mt5cli.cli`           | Typer/Click adapters; no MT5 operational logic of its own                                                                                       |
-| `mt5cli.utils`         | Generic conversion, parsing, and file/SQLite export helpers, independent of the MT5 connection lifecycle                                        |
+`mt5cli.sdk` is the internal source of truth for the stable package-root
+exports. Downstream code should import stable names from `mt5cli`; each
+operational capability still has exactly one owning module:
+
+| Module                 | Owns                                                                                                                                        |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `mt5cli.client`        | Connection lifecycle (`build_config`, `mt5_session`, `MT5Client`); the sole session factory                                                 |
+| `mt5cli.marketdata`    | Stateless one-off market-data reads and multi-account rate collection (`AccountSpec`, `collect_latest_rates_for_accounts`, etc.)            |
+| `mt5cli.history`       | Legacy history collection, incremental updates, and SQLite storage (`collect_history`, `update_history`, `write_*_dataset`)                 |
+| `mt5cli.rates`         | Canonical rate persistence/loading and stable update wrappers (`load_rate_series_from_sqlite`, `update_history`, `ThrottledHistoryUpdater`) |
+| `mt5cli.observability` | Observability snapshot orchestration (`update_observability`, `update_observability_with_config`)                                           |
+| `mt5cli.grafana`       | Grafana schema, views, and snapshot persistence                                                                                             |
+| `mt5cli.trading`       | Order preparation, broker-facing calculations, and normalized execution receipts                                                            |
+| `mt5cli.contract`      | The internal `HistoryClient` / `ObservabilityClient` protocols                                                                              |
+| `mt5cli.sdk`           | Authoritative stable package-root export declaration; no separate connection lifecycle                                                      |
+| `mt5cli.cli`           | Typer/Click adapters; no MT5 operational logic of its own                                                                                   |
+| `mt5cli.utils`         | Generic conversion, parsing, and file/SQLite export helpers, independent of the MT5 connection lifecycle                                    |
 
 No module combines connection lifecycle, history collection, observability,
 telemetry, SQLite orchestration, and CLI-adjacent concerns.
@@ -53,7 +56,7 @@ telemetry, SQLite orchestration, and CLI-adjacent concerns.
 ## Stable downstream SDK API
 
 These names are exported from `mt5cli` and enumerated in
-`mt5cli.STABLE_SDK_EXPORTS` (defined in `mt5cli.contract`).
+`mt5cli.STABLE_SDK_EXPORTS` (defined by `mt5cli.sdk`).
 
 ### Session lifecycle and configuration
 
@@ -63,6 +66,7 @@ These names are exported from `mt5cli` and enumerated in
 | `build_config`                                  | Build the underlying MT5 connection config from connection fields; `login` accepts `int \| str \| None` — numeric strings are coerced to `int`, blank strings are treated as unset, and `${ENV_VAR}` / `$ENV_NAME` placeholders in string parameters are expanded when `allow_whole_dollar_env=True` |
 | `substitute_mapping_values`                     | Generic selected-key environment substitution for downstream configuration adapters                                                                                                                                                                                                                  |
 | `mt5_session`                                   | Canonical context manager: initialize/login once, yield `MT5Client`, shut down once; a supplied `client=` remains caller-owned.                                                                                                                                                                      |
+| `Mt5Config`                                     | Canonical pdmt5 connection configuration type returned by `build_config` and accepted by managed-session wrappers                                                                                                                                                                                    |
 | `AccountSpec`                                   | Generic account group: symbols plus optional credentials                                                                                                                                                                                                                                             |
 | `resolve_account_spec`, `resolve_account_specs` | Merge overrides and expand `${ENV_VAR}` placeholders; opt-in `allow_whole_dollar_env` for bare `$NAME`                                                                                                                                                                                               |
 
@@ -83,17 +87,16 @@ timestamp normalization in downstream apps.
 
 ### SQLite history collection and rate loading
 
-| Symbol                                                            | Role                                                                                         |
-| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
-| `collect_history`                                                 | One-shot date-range export into SQLite                                                       |
-| `report_rate_gaps`                                                | SQLite-only one-row-per-gap report for a rate table or compatibility view                    |
-| `update_history`, `update_history_with_config`                    | Incremental append from `MAX(time)` cursors                                                  |
-| `ThrottledHistoryUpdater`                                         | Minimum interval between successful incremental updates; optional `update_backend` injection |
-| `RateTarget`, `build_rate_targets`                                | Neutral `(symbol, timeframe)` series descriptors                                             |
-| `load_rate_series_from_sqlite`, `load_rate_series_by_granularity` | Load one or many series; fail clearly when managed views are missing                         |
+| Symbol                                                            | Role                                                                                                             |
+| ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `collect_history`                                                 | One-shot date-range export into SQLite                                                                           |
+| `report_rate_gaps`                                                | SQLite-only one-row-per-gap report for the canonical rates table or an explicit custom table                     |
+| `update_history`, `update_history_with_config`                    | Incremental append from `MAX(time)` cursors; explicit naive trade-server `date_to` required                      |
+| `ThrottledHistoryUpdater`                                         | Minimum interval between successful incremental updates; explicit `date_to`; optional `update_backend` injection |
+| `RateTarget`, `build_rate_targets`                                | Neutral `(symbol, timeframe)` series descriptors                                                                 |
+| `load_rate_series_from_sqlite`, `load_rate_series_by_granularity` | Load normalized `rates` series or explicit custom tables; reject invalid targets clearly                         |
 
-See [History Collection (SQLite)](history.md) for schema, view naming, and ER
-diagrams.
+See [History Collection (SQLite)](history.md) for the canonical schema, loading contract, and ER diagrams.
 
 Shared package-root helpers used by downstream adapters include `Dataset`,
 `parse_timeframe`, and `resolve_history_timeframes`. These are stable exports;
@@ -168,17 +171,11 @@ retrieve deal history through `client.history_deals()` or
 `client.recent_history_deals()`. Consume execution receipt attributes instead
 of parsing a raw broker response or assuming requested volume was filled.
 
-`mt5cli.sdk` has been removed entirely, along with its duplicate
-`mt5_session()` context manager (which used to yield a private
-read-only-only client type) and the `Mt5CliClient` name. `from mt5cli import
-MT5Client, mt5_session` remains the only supported way to obtain a connected
-client — there is no alternate public session factory or client type. Code
-that imported market-data or history functions from `mt5cli.sdk` should import
-them from `mt5cli.marketdata` or `mt5cli.history` instead (or, for stable
-names, from the package root). Code that imported `update_observability` /
-`update_observability_with_config` from `mt5cli.sdk` should import them from
-`mt5cli.observability` instead. No compatibility shims are provided for any of
-these removed import paths.
+`mt5cli.sdk` is an internal source-of-truth module for the stable package-root
+exports. It does not provide a second connection lifecycle or alternate public
+client type; `from mt5cli import MT5Client, mt5_session` remains the supported
+way to obtain a connected client. Downstream code should import stable names
+from the package root and capability-specific helpers from their owning modules.
 
 ### Grafana observability (SQLite read model)
 
@@ -289,11 +286,10 @@ of the package-root stable surface. Import them directly when needed:
 | Module              | Examples                                                                                                                                                                    |
 | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `mt5cli.grafana`    | `ensure_grafana_schema`, `create_grafana_views`, `create_grafana_indexes`, `create_snapshot_tables`, `start_snapshot_run`, `insert_account_snapshot`, `record_snapshot_run` |
-| `mt5cli.history`    | `resolve_rate_view_name`, `resolve_rate_tables`, `load_rate_data`, `build_rate_view_name`                                                                                   |
 | `mt5cli.marketdata` | `copy_rates_from`, `copy_ticks_from`, `account_info`, `symbols`, `mt5_summary`, `latest_rates`                                                                              |
 | `mt5cli.schemas`    | `DataKind`, `normalize_dataframe`, `validate_schema`, `DEDUP_KEYS`                                                                                                          |
 | `mt5cli.utils`      | `Dataset`, `IfExists`, `detect_format`, `export_dataframe`, `export_dataframe_to_sqlite`                                                                                    |
-| `mt5cli.converters` | `normalize_symbol`, `ensure_utc`, `parse_date_range`, `granularity_name`                                                                                                    |
+| `mt5cli.converters` | `normalize_symbol`, `ensure_utc`, `ensure_trade_server_time`, `parse_date_range`, `granularity_name`                                                                        |
 | `mt5cli.exceptions` | `normalize_mt5_exception`, `call_with_normalized_errors`, `is_recoverable_mt5_error`                                                                                        |
 
 ## CLI commands
@@ -333,9 +329,9 @@ resolved per symbol with `resolve_broker_filling_mode()` so closes are not
 rejected on brokers whose symbols do not support IOC.
 
 `history-gaps` reads an existing SQLite history database and exports one row
-per detected gap from managed rate compatibility views. It never initializes
-MT5. Pass `--granularity-seconds` for custom tables or views whose bar spacing
-cannot be inferred from the name.
+per detected gap from the canonical `rates` table or an explicitly named custom
+table. It never initializes MT5. Pass `--granularity-seconds` for custom tables
+whose bar spacing cannot be inferred from timeframe metadata.
 
 ## Internal helpers (not stable)