nlalpha-data 0.3.0__py3-none-any.whl

nlalpha_data/local_provider.py

@@ -0,0 +1,407 @@
+"""本地文件数据提供者（CSV / Excel）。
+
+支持从本地 CSV 和 Excel 文件加载历史 K 线数据。
+
+文件查找规则（按优先级）：
+1. {data_dir}/{symbol}.csv
+2. {data_dir}/{symbol}.xlsx
+3. {data_dir}/{symbol}.xls
+
+CSV 读取：标准库 csv.DictReader（零额外依赖）
+Excel 读取：懒导入 pandas（如果未安装，Excel 不可用但 CSV 仍可用）
+
+列名自动映射：
+- 日期列：datetime / date / trade_date / 日期 / 交易日期
+- 开盘列：open / 开盘 / 开盘价
+- 最高列：high / 最高 / 最高价
+- 最低列：low / 最低 / 最低价
+- 收盘列：close / 收盘 / 收盘价
+- 成交量列：volume / vol / 成交量
+
+用法：
+    provider = LocalFileDataProvider("workspace/data")
+    bars = provider.load_bars("000300.SH", "1d", "2023-01-01", "2023-06-30")
+"""
+
+import asyncio
+import csv
+import json
+import math
+import re
+from datetime import date, datetime
+from pathlib import Path
+from typing import Any
+
+from nlalpha.core.contracts.market import Bar
+from nlalpha.core.errors import DataError
+from nlalpha.core.contracts.time import get_timezone, normalize_utc, timezone_metadata
+from nlalpha_data.calendar_base import exchange_calendar, session_bounds
+from nlalpha_data.base import _interval_delta
+from nlalpha_data.store import filter_bar_dates
+
+
+# 列名映射表：所有可能的列名 -> 标准列名
+_COLUMN_ALIASES = {
+    # 日期
+    "datetime": "datetime",
+    "date": "session_date",
+    "trade_date": "session_date",
+    "日期": "session_date",
+    "交易日期": "session_date",
+    "open_time": "open_time",
+    "close_time": "close_time",
+    "session_date": "session_date",
+    "open_interest": "open_interest",
+    "oi": "open_interest",
+    # 开盘
+    "open": "open",
+    "开盘": "open",
+    "开盘价": "open",
+    # 最高
+    "high": "high",
+    "最高": "high",
+    "最高价": "high",
+    # 最低
+    "low": "low",
+    "最低": "low",
+    "最低价": "low",
+    # 收盘
+    "close": "close",
+    "收盘": "close",
+    "收盘价": "close",
+    # 成交量
+    "volume": "volume",
+    "vol": "volume",
+    "成交量": "volume",
+}
+
+
+def _normalize_columns(headers: list[str]) -> dict[str, str]:
+    """将原始列名映射为标准列名。
+
+    返回 {标准列名: 原始列名} 的映射字典。
+    如果某个标准列名找不到，对应的值为空字符串。
+    """
+    # 建立原始列名 -> 标准列名的映射（小写匹配）
+    raw_to_std = {}
+    for h in headers:
+        lower = h.strip().lower()
+        if lower in _COLUMN_ALIASES:
+            raw_to_std[h] = _COLUMN_ALIASES[lower]
+
+    # 反向映射：标准列名 -> 原始列名（取第一个匹配的）
+    std_to_raw = {}
+    for raw, std in raw_to_std.items():
+        if std not in std_to_raw:
+            std_to_raw[std] = raw
+
+    return std_to_raw
+
+
+def _parse_datetime(value: Any) -> datetime:
+    """Parse exact microseconds and whole-second source UTC offsets."""
+    if not isinstance(value, datetime):
+        if not isinstance(value, str):
+            raise DataError(f"Invalid local datetime: {value!r}.", details={"time_contract": True})
+        value = value.strip()
+        if any(any(digit != "0" for digit in match.group(1)[6:]) for match in re.finditer(r"[.,](\d+)", value)):
+            raise DataError("Local Bar transport cannot truncate sub-microsecond timestamps.", details={"time_contract": True})
+        try:
+            parsed = datetime.fromisoformat(value)
+        except ValueError:
+            parsed = None
+            for pattern in ("%Y%m%d", "%Y/%m/%d"):
+                try:
+                    parsed = datetime.strptime(value, pattern)
+                    break
+                except ValueError:
+                    continue
+            if parsed is None:
+                raise DataError(f"Unable to parse datetime: {value!r}.", details={"time_contract": True})
+        value = parsed
+    if getattr(value, "nanosecond", 0):
+        raise DataError("Local Bar transport cannot truncate sub-microsecond timestamps.", details={"time_contract": True})
+    offset = value.utcoffset()
+    if offset is not None and offset.microseconds:
+        raise DataError("Local source UTC offset must use whole seconds.", details={"time_contract": True})
+    return value.to_pydatetime() if hasattr(value, "to_pydatetime") else value
+
+
+def _parse_session_date(value: Any) -> date:
+    """Parse an actual date label without discarding a clock component."""
+    if isinstance(value, datetime):
+        if getattr(value, "nanosecond", 0) or value.time() != datetime.min.time() or value.tzinfo is not None:
+            raise DataError("Trading date labels must contain only a civil date.", details={"time_contract": True})
+        return value.date()
+    if isinstance(value, date):
+        return value
+    if not isinstance(value, str):
+        raise DataError(f"Invalid trading date: {value!r}.", details={"time_contract": True})
+    for pattern in ("%Y-%m-%d", "%Y%m%d", "%Y/%m/%d"):
+        try:
+            return datetime.strptime(value.strip(), pattern).date()
+        except ValueError:
+            continue
+    raise DataError(f"Invalid trading date: {value!r}.", details={"time_contract": True})
+
+
+def _parse_float(value: Any, *, optional: bool = False) -> float | None:
+    """Require a finite numeric price, volume, or optional open interest."""
+    if value is None or value == "":
+        if optional:
+            return None
+        raise DataError("Missing required numeric local bar value.")
+    try:
+        result = float(str(value).replace(",", "").strip())
+    except (ValueError, TypeError) as exc:
+        raise DataError(f"Invalid numeric local bar value: {value!r}.") from exc
+    if not math.isfinite(result):
+        raise DataError(f"Non-finite numeric local bar value: {value!r}.")
+    return result
+
+
+class LocalFileDataProvider:
+    """本地文件数据提供者。"""
+
+    def __init__(self, data_dir: str | Path = "workspace/data", *, time_contracts: dict[str, dict] | None = None,
+                 price_adjustments: dict[str, str] | None = None):
+        self.data_dir = Path(data_dir).resolve()
+        self.time_contracts = dict(time_contracts or {})
+        if price_adjustments is not None and (not isinstance(price_adjustments, dict) or any(
+            not isinstance(symbol, str) or not symbol or symbol != symbol.strip()
+            or not isinstance(value, str) or value not in {"unadjusted", "forward", "backward"}
+            for symbol, value in price_adjustments.items()
+        )):
+            raise DataError("Local price_adjustments must map symbols to unadjusted, forward, or backward.")
+        self.price_adjustments = dict(price_adjustments or {})
+
+    def cache_identity(self) -> dict:
+        """Declare local storage and host configuration used to isolate cached bars."""
+        return {"data_dir": str(self.data_dir), "time_contracts": self.time_contracts,
+                "price_adjustments": self.price_adjustments}
+
+    async def describe_request(self, symbol: str, interval: str,
+                               price_adjustment: str | None = None) -> dict:
+        """Declare host-configured price adjustment for the requested symbol."""
+        if symbol in self.price_adjustments:
+            return {"price_adjustment": self.price_adjustments[symbol],
+                    "evidence": {"type": "host_declaration", "reference": f"local.price_adjustments[{symbol}]"}}
+        return {"price_adjustment": "unknown", "evidence": {"type": "unknown", "reference": "No host price-adjustment declaration."}}
+
+    def is_available(self) -> bool:
+        """检查数据目录是否存在。"""
+        return self.data_dir.exists() and self.data_dir.is_dir()
+
+    async def load_bars(self, symbol: str, interval: str, start: str, end: str, *,
+                        price_adjustment: str | None = None) -> list[Bar]:
+        """从本地文件加载 K 线数据。
+
+        Args:
+            symbol: 品种代码（用于查找文件）
+            interval: 周期（当前不用于文件筛选，仅做接口兼容）
+            start: 开始日期 "YYYY-MM-DD"
+            end: 结束日期 "YYYY-MM-DD"
+            price_adjustment: 仅做接口兼容；文件按宿主声明的复权属性原样返回
+
+        Returns:
+            按时间升序排列的 Bar 列表
+        """
+        file_path = self._find_file(symbol)
+
+        if file_path.suffix.lower() == ".csv":
+            rows = await self._read_csv_async(file_path)
+        elif file_path.suffix.lower() in (".xlsx", ".xls"):
+            # Excel 读取依赖 pandas，无原生 async 支持，使用线程池
+            rows = await asyncio.to_thread(self._read_excel, file_path)
+        else:
+            raise DataError(f"Unsupported file format: {file_path.suffix}")
+
+        bars = self._rows_to_bars(rows, symbol, interval, self._time_contract(symbol))
+        bars = self._filter_by_date(bars, start, end)
+        bars.sort(key=lambda b: b.datetime)
+        return bars
+
+    def _find_file(self, symbol: str) -> Path:
+        """查找品种对应的数据文件。"""
+        # 安全处理：替换文件系统不友好字符
+        safe_symbol = symbol.replace("/", "_").replace("\\", "_")
+        candidates = [
+            self.data_dir / f"{safe_symbol}.csv",
+            self.data_dir / f"{safe_symbol}.xlsx",
+            self.data_dir / f"{safe_symbol}.xls",
+        ]
+        for c in candidates:
+            if c.exists():
+                return c
+        raise DataError(
+            f"No data file found for symbol '{symbol}' in {self.data_dir}. "
+            f"Expected: {safe_symbol}.csv / {safe_symbol}.xlsx"
+        )
+
+    def _read_csv(self, path: Path) -> list[dict]:
+        """读取 CSV 文件（sync 版本，供线程池回退使用）。"""
+        try:
+            # 尝试 UTF-8（优先，处理 BOM）
+            with open(path, "r", encoding="utf-8-sig", newline="") as f:
+                reader = csv.DictReader(f)
+                return list(reader)
+        except UnicodeDecodeError:
+            # fallback 到 GBK（中文 Windows 常见编码）
+            with open(path, "r", encoding="gbk", newline="") as f:
+                reader = csv.DictReader(f)
+                return list(reader)
+
+    async def _read_csv_async(self, path: Path) -> list[dict]:
+        """读取 CSV 文件（async 版本，使用 aiofiles）。"""
+        try:
+            import aiofiles
+        except ImportError:
+            # aiofiles 未安装时回退到 sync 版本
+            return await asyncio.to_thread(self._read_csv, path)
+
+        async def _read_with_encoding(encoding: str) -> list[dict]:
+            async with aiofiles.open(path, "r", encoding=encoding, newline="") as f:
+                content = await f.read()
+            # csv.DictReader 需要文件对象，从内存字符串构建
+            from io import StringIO
+            reader = csv.DictReader(StringIO(content))
+            return list(reader)
+
+        try:
+            return await _read_with_encoding("utf-8-sig")
+        except UnicodeDecodeError:
+            return await _read_with_encoding("gbk")
+
+    def _read_excel(self, path: Path) -> list[dict]:
+        """读取 Excel 文件（懒导入 pandas）。"""
+        try:
+            import pandas as pd
+        except ImportError as e:
+            raise DataError(
+                "pandas is required for Excel support. "
+                "Install it with: pip install pandas openpyxl"
+            ) from e
+
+        try:
+            df = pd.read_excel(path)
+            return df.to_dict("records")
+        except Exception as e:
+            raise DataError(f"Failed to read Excel {path}: {e}") from e
+
+    def _time_contract(self, symbol: str) -> dict:
+        """Load one explicit source declaration from configuration or sidecar."""
+        configured = self.time_contracts.get(symbol)
+        safe_symbol = symbol.replace("/", "_").replace("\\", "_")
+        path = self.data_dir / f"{safe_symbol}.time.json"
+        sidecar = None
+        if path.exists():
+            try:
+                sidecar = json.loads(path.read_text(encoding="utf-8"))
+            except (ValueError, OSError) as exc:
+                raise DataError(f"Cannot read source time contract {path}: {exc}", details={"time_contract": True}) from exc
+        if configured is not None and sidecar is not None and configured != sidecar:
+            raise DataError("Configured time contract contradicts the symbol sidecar.", details={"time_contract": True})
+        contract = configured if configured is not None else sidecar
+        if contract is None:
+            return {}
+        return self._validate_time_contract(contract)
+
+    @staticmethod
+    def _validate_time_contract(contract: dict) -> dict:
+        """Validate source timezone, semantics, and calendar consistency."""
+        if not isinstance(contract, dict) or set(contract) - {"timezone", "timestamp_semantics", "calendar_id"}:
+            raise DataError("Local time contract accepts timezone, timestamp_semantics, and calendar_id.", details={"time_contract": True})
+        zone = contract.get("timezone")
+        if zone is not None:
+            get_timezone(zone)
+        semantics = contract.get("timestamp_semantics")
+        if semantics is not None and semantics not in {"open", "close", "trading_date"}:
+            raise DataError("Invalid local timestamp_semantics.", details={"time_contract": True})
+        calendar_id = contract.get("calendar_id")
+        if calendar_id is not None:
+            calendar_zone = str(exchange_calendar(calendar_id).tz)
+            if zone is not None and timezone_metadata(zone)["tzif_sha256"] != timezone_metadata(calendar_zone)["tzif_sha256"]:
+                raise DataError("Local source timezone contradicts the declared session calendar.", details={"time_contract": True})
+        return dict(contract)
+
+    def _rows_to_bars(self, rows: list[dict], symbol: str, interval: str = "1d", contract: dict | None = None) -> list[Bar]:
+        """Resolve source timestamps and reject malformed rows explicitly."""
+        if not rows:
+            return []
+        contract = self._validate_time_contract(contract) if contract is not None else self._time_contract(symbol)
+        mapping = _normalize_columns(list(rows[0]))
+        missing = {"open", "high", "low", "close", "volume"} - set(mapping)
+        if missing:
+            raise DataError(f"Missing local OHLCV columns: {sorted(missing)}.")
+        explicit_bounds = "open_time" in mapping and "close_time" in mapping
+        if ("open_time" in mapping) != ("close_time" in mapping):
+            raise DataError("Local data must provide both open_time and close_time.", details={"time_contract": True})
+        if not explicit_bounds and "datetime" not in mapping and "session_date" not in mapping:
+            raise DataError("Local data requires explicit bounds, a datetime, or a declared trading date.", details={"time_contract": True})
+        bars = []
+        for number, row in enumerate(rows, 1):
+            try:
+                zone = contract.get("timezone")
+                semantics = contract.get("timestamp_semantics")
+                calendar_id = contract.get("calendar_id")
+                session = _parse_session_date(row[mapping["session_date"]]) if "session_date" in mapping else None
+                original = None
+                if explicit_bounds:
+                    if semantics == "trading_date" and session is None:
+                        raise DataError("trading_date semantics requires a session_date label.", details={"time_contract": True})
+                    original = _parse_datetime(row[mapping["close_time"]])
+                    begin = normalize_utc(_parse_datetime(row[mapping["open_time"]]), source_timezone=zone)
+                    finish = normalize_utc(original, source_timezone=zone)
+                    semantics = semantics or "close"
+                elif session is not None and "datetime" not in mapping:
+                    if semantics != "trading_date" or calendar_id is None:
+                        raise DataError("Date-only data requires timestamp_semantics=trading_date and an explicit calendar_id.", details={"time_contract": True})
+                    begin, finish = session_bounds(calendar_id, session)
+                    zone = zone or str(exchange_calendar(calendar_id).tz)
+                else:
+                    raw = row[mapping["datetime"]]
+                    is_date_only = isinstance(raw, date) and not isinstance(raw, datetime)
+                    is_date_only |= isinstance(raw, str) and re.fullmatch(r"\d{4}[-/]\d{2}[-/]\d{2}|\d{8}", raw.strip()) is not None
+                    if is_date_only or semantics == "trading_date":
+                        if semantics != "trading_date" or calendar_id is None:
+                            raise DataError("Date-only datetime requires trading_date semantics and an explicit calendar_id.", details={"time_contract": True})
+                        raw_session = _parse_session_date(raw)
+                        if session is not None and session != raw_session:
+                            raise DataError("Trading date columns contradict one another.", details={"time_contract": True})
+                        session = raw_session
+                        begin, finish = session_bounds(calendar_id, session)
+                        zone = zone or str(exchange_calendar(calendar_id).tz)
+                    else:
+                        if semantics not in {"open", "close"}:
+                            raise DataError("One datetime column requires explicit open/close timestamp_semantics.", details={"time_contract": True})
+                        original = _parse_datetime(raw)
+                        instant = normalize_utc(original, source_timezone=zone)
+                        width = _interval_delta(interval)
+                        begin, finish = (instant, instant + width) if semantics == "open" else (instant - width, instant)
+                source_offset = None
+                if original is not None and original.tzinfo is not None and original.utcoffset() is not None:
+                    source_offset = int(original.utcoffset().total_seconds())
+                    zone = zone or getattr(original.tzinfo, "key", None)
+                    if zone is None and source_offset == 0:
+                        zone = "UTC"
+                elif zone is not None:
+                    source_instant = begin if semantics == "open" else finish
+                    source_offset = int(source_instant.astimezone(get_timezone(zone)).utcoffset().total_seconds())
+                bars.append(Bar(
+                    symbol=symbol, datetime=finish, open_time=begin, session_date=session,
+                    source_timezone=zone, source_utc_offset_seconds=source_offset,
+                    source_timestamp_semantics=semantics, calendar_id=calendar_id,
+                    open=_parse_float(row[mapping["open"]]), high=_parse_float(row[mapping["high"]]),
+                    low=_parse_float(row[mapping["low"]]), close=_parse_float(row[mapping["close"]]),
+                    volume=_parse_float(row[mapping["volume"]]),
+                    open_interest=_parse_float(row.get(mapping.get("open_interest", "")), optional=True),
+                ))
+            except Exception as exc:
+                details = dict(exc.details) if isinstance(exc, DataError) else {}
+                details["time_contract"] = True
+                raise DataError(f"Invalid local bar row {number} for {symbol}: {exc}", details=details) from exc
+        return sorted(bars, key=lambda bar: bar.datetime)
+
+    def _filter_by_date(self, bars: list[Bar], start: str, end: str) -> list[Bar]:
+        """Filter inclusive dates according to the original source contract."""
+        return filter_bar_dates(bars, start, end)

nlalpha_data/mock_provider.py

@@ -0,0 +1,123 @@
+"""Generate interval-aligned synthetic OHLCV bars for strategy validation."""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+from decimal import Decimal
+import math
+
+from nlalpha.core.contracts.market import Bar
+
+from nlalpha_data.base import _interval_delta
+
+
+class MockDataProvider:
+    """Generate mock bars for each configured universe symbol."""
+
+    def __init__(self, envelope, instruments=None):
+        self._envelope = envelope
+        self._bars: list[Bar] | None = None
+        universe = envelope.universe if hasattr(envelope, "universe") else {}
+        self._symbols = list(universe.get("symbols", []))
+        if not self._symbols:
+            self._symbols = [leg.get("symbol") for leg in universe.get("legs", [])]
+        if (
+            not self._symbols
+            or any(
+                not isinstance(symbol, str) or not symbol or symbol != symbol.strip()
+                for symbol in self._symbols
+            )
+            or len(set(self._symbols)) != len(self._symbols)
+        ):
+            raise ValueError("mock validation requires unique configured universe symbols")
+        data = envelope.data if hasattr(envelope, "data") else {}
+        execution = envelope.execution if hasattr(envelope, "execution") else {}
+        self._interval = _interval_delta(data.get("interval") or execution.get("bar_interval"))
+        contract = getattr(envelope, "contract", {}) or {}
+        self._instruments = instruments or contract.get("instruments", {})
+        if not hasattr(self._instruments, "get"):
+            raise ValueError("mock instrument settings must be a symbol mapping")
+
+    @staticmethod
+    def _common_increment(*values: object) -> Decimal:
+        """Return an increment that is a multiple of all configured steps."""
+        increments = [Decimal(str(value)) for value in values if value is not None]
+        increments = [value for value in increments if value > 0]
+        if not increments:
+            return Decimal(1)
+        scale = max(max(0, -value.as_tuple().exponent) for value in increments)
+        scaled = [int(value.scaleb(scale)) for value in increments]
+        common = math.lcm(*scaled)
+        return Decimal(common).scaleb(-scale)
+
+    def _instrument_steps(self, symbol: str) -> tuple[Decimal, Decimal]:
+        instrument = self._instruments.get(symbol, {})
+        if not hasattr(instrument, "get"):
+            raise ValueError(f"mock instrument settings for {symbol!r} must be a mapping")
+        kind = instrument.get("instrument_type")
+        default_price_precision = 5 if kind == "currency_pair" else 2
+        price_precision = instrument.get("price_precision", default_price_precision)
+        if isinstance(price_precision, bool) or not isinstance(price_precision, int) or not 0 <= price_precision <= 12:
+            raise ValueError(f"mock price_precision for {symbol!r} must be an integer in [0, 12]")
+        price_step = self._common_increment(
+            instrument.get("price_increment"), Decimal(1).scaleb(-price_precision)
+        )
+
+        default_size_precision = 0 if kind in {"equity", "futures", None} else 8
+        size_precision = instrument.get("size_precision", default_size_precision)
+        if isinstance(size_precision, bool) or not isinstance(size_precision, int) or not 0 <= size_precision <= 12:
+            raise ValueError(f"mock size_precision for {symbol!r} must be an integer in [0, 12]")
+        configured_size_increment = instrument.get("size_increment")
+        if configured_size_increment is None:
+            configured_size_increment = Decimal(1).scaleb(-size_precision)
+        volume_step = self._common_increment(
+            configured_size_increment,
+            instrument.get("lot_size"),
+            Decimal(1).scaleb(-size_precision),
+        )
+        return price_step, volume_step
+
+    def is_available(self) -> bool:
+        return True
+
+    async def load_bars(self, symbol: str, interval: str, start: str, end: str) -> list[Bar]:
+        """Return all generated bars or the requested symbol's bars."""
+        if self._bars is None:
+            self._bars = self._generate()
+        if symbol:
+            if symbol not in self._symbols:
+                raise ValueError(f"mock data does not include symbol {symbol!r}")
+            return [bar for bar in self._bars if bar.symbol == symbol]
+        return list(self._bars)
+
+    def _generate(self) -> list[Bar]:
+        """Generate deterministic bars using each instrument's increments."""
+        flat_bars: list[Bar] = []
+        base_price = 100.0
+        dt = datetime(2023, 1, 1, 9, 30, tzinfo=timezone.utc) + self._interval
+
+        for seed, symbol in enumerate(self._symbols):
+            price_step, volume_step = self._instrument_steps(symbol)
+            base_ticks = max(1000, int(Decimal(str(base_price + seed * 10)) / price_step))
+            for i in range(200):
+                close_ticks = base_ticks + (i % 20)
+                close = price_step * close_ticks
+                open_p = price_step * (close_ticks - 1)
+                high = price_step * (close_ticks + 1)
+                low = price_step * (close_ticks - 2)
+                flat_bars.append(Bar(
+                    symbol=symbol,
+                    datetime=dt + self._interval * i,
+                    open_time=dt + self._interval * (i - 1),
+                    source_timezone="UTC",
+                    source_timestamp_semantics="close",
+                    open=float(open_p),
+                    high=float(high),
+                    low=float(low),
+                    close=float(close),
+                    volume=float(volume_step * (1000 + i)),
+                ))
+
+        order = {symbol: index for index, symbol in enumerate(self._symbols)}
+        flat_bars.sort(key=lambda bar: (bar.datetime, order[bar.symbol]))
+        return flat_bars

nlalpha_data/parquet_store.py

@@ -0,0 +1,134 @@
+"""Store canonical bars atomically with exact query and source metadata."""
+
+import asyncio
+import json
+import os
+from pathlib import Path
+import tempfile
+
+from nlalpha.core.contracts.market import Bar
+from nlalpha.core.errors import DataError
+from nlalpha_data.store import (
+    BaseBarStore, BarOverview, _cache_path, _bars_to_table, _table_to_bars,
+    BAR_CACHE_NAMESPACE, BAR_CONTRACT_KEY, BAR_CONTRACT, SOURCE_KEY, QUERY_KEY, read_source_contract,
+)
+
+
+class ParquetBarStore(BaseBarStore):
+    """Persist exact bar queries inside one source-specific cache directory."""
+
+    def __init__(self, cache_dir: str | Path = "workspace/cache", *, source: dict | None = None):
+        self.cache_dir = Path(cache_dir) / BAR_CACHE_NAMESPACE
+        self.source = json.loads(json.dumps(source)) if source is not None else None
+
+    async def save(self, bars: list[Bar], symbol: str = "", interval: str = "", start: str = "", end: str = "") -> int:
+        """Publish a complete Parquet file with an atomic same-directory rename."""
+        if not bars:
+            return 0
+        return await asyncio.to_thread(self._save, bars, symbol, interval, start, end)
+
+    def _save(self, bars, symbol, interval, start, end):
+        import pyarrow.parquet as pq
+        if not symbol or not interval:
+            raise DataError("Cache writes require explicit symbol and interval.")
+        if any(bar.symbol != symbol for bar in bars):
+            raise DataError("Cache bars must match the requested symbol.", details={"cache_contract": True})
+        query = [symbol, interval, start, end]
+        table = _bars_to_table(sorted(bars, key=lambda bar: bar.datetime))
+        metadata = {**(table.schema.metadata or {}), BAR_CONTRACT_KEY: BAR_CONTRACT,
+                    QUERY_KEY: json.dumps(query).encode()}
+        if self.source is not None:
+            contract = {"schema": "nlalpha.market.source.v1", "assets": {symbol: {**self.source, "cache_hit": False}}}
+            metadata[SOURCE_KEY] = json.dumps(contract, sort_keys=True).encode()
+            read_source_contract(table.replace_schema_metadata(metadata))
+        self.cache_dir.mkdir(parents=True, exist_ok=True)
+        target = _cache_path(*query, self.cache_dir)
+        descriptor, filename = tempfile.mkstemp(prefix=".bars-", suffix=".tmp", dir=self.cache_dir)
+        try:
+            with os.fdopen(descriptor, "wb") as output:
+                pq.write_table(table.replace_schema_metadata(metadata), output)
+                output.flush()
+                os.fsync(output.fileno())
+            os.replace(filename, target)
+        finally:
+            Path(filename).unlink(missing_ok=True)
+        return len(bars)
+
+    def _read(self, path: Path, expected_query=None):
+        import pyarrow.parquet as pq
+        try:
+            table = pq.read_table(path)
+        except FileNotFoundError:
+            raise
+        except Exception as exc:
+            raise DataError(f"Cannot read Parquet cache: {exc}", details={"cache_contract": True}) from exc
+        bars = _cache_table_to_bars(table)
+        try:
+            metadata = table.schema.metadata or {}
+            query = json.loads(metadata[QUERY_KEY])
+            if (not isinstance(query, list) or len(query) != 4
+                    or any(not isinstance(value, str) for value in query) or not query[0] or not query[1]):
+                raise ValueError("Invalid cached query")
+            contract = read_source_contract(table)
+            entry = None if contract is None else contract["assets"][query[0]]
+            source = None if entry is None else {key: value for key, value in entry.items() if key != "cache_hit"}
+            if path.name != _cache_path(*query, self.cache_dir).name:
+                raise ValueError("Cache filename contradicts query metadata")
+            if expected_query is not None and query != list(expected_query):
+                raise ValueError("Cache query mismatch")
+            if any(bar.symbol != query[0] for bar in bars):
+                raise ValueError("Cache bars contradict query symbol")
+            if source != self.source:
+                raise ValueError("Cache source declaration mismatch")
+        except (KeyError, ValueError, TypeError) as exc:
+            raise DataError(f"Invalid Parquet cache metadata: {exc}", details={"cache_contract": True}) from exc
+        return bars, query
+
+    async def load(self, symbol: str, interval: str, start: str, end: str) -> list[Bar]:
+        """Read an exact query; only a missing file represents a cache miss."""
+        query = (symbol, interval, start, end)
+        bars, _ = await asyncio.to_thread(self._read, _cache_path(*query, self.cache_dir), query)
+        return bars
+
+    async def delete(self, symbol: str, interval: str) -> int:
+        """Delete matching exact-query files using their original metadata."""
+        return await asyncio.to_thread(self._delete, symbol, interval)
+
+    def _delete(self, symbol, interval):
+        deleted = 0
+        for path in self.cache_dir.glob("*.parquet"):
+            _, query = self._read(path)
+            if query[:2] == [symbol, interval]:
+                path.unlink()
+                deleted += 1
+        return deleted
+
+    async def get_overview(self) -> list[BarOverview]:
+        """Read all stored series without guessing original symbols from filenames."""
+        return await asyncio.to_thread(self._overview)
+
+    def _overview(self):
+        overviews = {}
+        for path in self.cache_dir.glob("*.parquet"):
+            bars, query = self._read(path)
+            if not bars:
+                continue
+            key = tuple(query[:2])
+            previous = overviews.get(key)
+            if previous is None:
+                overviews[key] = BarOverview(*key, count=len(bars), start=bars[0].datetime, end=bars[-1].datetime)
+            else:
+                previous.count += len(bars)
+                previous.start = min(previous.start, bars[0].datetime)
+                previous.end = max(previous.end, bars[-1].datetime)
+        return list(overviews.values())
+
+    async def aclose(self) -> None:
+        """Release the file store's resource scope."""
+
+
+def _cache_table_to_bars(table, fallback_symbol: str = "") -> list[Bar]:
+    """Validate cached volume semantics before restoring canonical bars."""
+    if (table.schema.metadata or {}).get(BAR_CONTRACT_KEY) != BAR_CONTRACT:
+        raise DataError("Parquet cache requires the current instrument-quantity bar contract.", details={"cache_contract": True})
+    return _table_to_bars(table, fallback_symbol=fallback_symbol)