mt5cli 1.4.1__tar.gz → 1.5.0__tar.gz

{mt5cli-1.4.1 → mt5cli-1.5.0}/.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 .
@@ -31,9 +32,9 @@ case "${OSTYPE}" in
       | xargs -0 -t shellcheck
 
     # GitHub Actions
-    zizmor --fix=safe .github/workflows
+    uvx zizmor --fix=safe .github/workflows
     git ls-files -z -- '.github/workflows/*.yml' | xargs -0 -t actionlint
-    checkov --framework=all --output=github_failed_only --directory=.
+    uvx checkov --framework=all --output=github_failed_only --directory=.
     ;;
   *)
     echo 'GitHub Actions and shell script linting is only supported on Linux and macOS.'

{mt5cli-1.4.1 → mt5cli-1.5.0}/.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.5.0}/.github/workflows/claude.yml

@@ -27,8 +27,7 @@ jobs:
     if: >
       github.event_name == 'pull_request'
       && (! github.event.pull_request.draft)
-      && (! startsWith(github.head_ref, 'dependabot/'))
-      && (! startsWith(github.head_ref, 'renovate/'))
+      && github.event.pull_request.user.type != 'Bot'
     permissions:
       contents: read
       pull-requests: write
@@ -46,7 +45,7 @@ jobs:
       || (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude'))
       || (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
     permissions:
-      contents: read
+      contents: write
       pull-requests: write
       issues: write
       id-token: write

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: mt5cli
-Version: 1.4.1
+Version: 1.5.0
 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.5.0}/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.5.0}/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