nlalpha-data 0.3.0__py3-none-any.whl

nlalpha_data/server.py

@@ -0,0 +1,392 @@
+"""Application-scoped MCP data tools publishing immutable market-data artifacts."""
+
+from __future__ import annotations
+
+import asyncio
+import io
+import json
+import logging
+import os
+import time
+from contextlib import AsyncExitStack, asynccontextmanager
+from importlib import resources
+from importlib.metadata import version
+from pathlib import Path
+from typing import Any, Callable
+
+import pyarrow.parquet as pq
+import uvicorn
+from mcp.server.fastmcp import Context, FastMCP
+from mcp.server.transport_security import TransportSecuritySettings
+from starlette.applications import Starlette
+from starlette.responses import JSONResponse
+from starlette.routing import Route
+
+from nlalpha.core.artifact_config import ArtifactStoreConfig, create_data_artifact_store
+from nlalpha.core.data_artifacts import DataArtifactBackendError, DataArtifactStore
+from nlalpha.core.description import common_description, describe_document, markdown_sections
+from nlalpha.core.contracts.market import Bar
+from nlalpha.core.platform import HostIdentityConfig, resolve_allowed_hosts
+from nlalpha.core.result_contract import failure_response
+from nlalpha.core.telemetry import configure_telemetry, shutdown, get_meter, setup_logging, span, start_span
+from nlalpha_data.calendar_tools import (
+    confess as _confess,
+    get_trading_days as _get_trading_days,
+    is_trading_day as _is_trading_day,
+    list_trading_calendars as _list_trading_calendars,
+)
+from nlalpha_data.loader import DataLoader, LoadedBars
+from nlalpha_data.discovery import get_default_data_provider
+from nlalpha_data.store import BAR_CONTRACT, BAR_CONTRACT_KEY, TIME_CONTRACT_KEY, SOURCE_KEY, read_source_contract, _bars_to_table
+
+logger = logging.getLogger("nlalpha-data")
+
+
+def _serialize_bars(loaded: LoadedBars, symbol: str, interval: str) -> tuple[bytes, dict[str, Any]]:
+    """Serialize canonical bars and derive their response summary from the same table."""
+    table = _bars_to_table(loaded.bars, require_bounds=True)
+    table = table.replace_schema_metadata({
+        **(table.schema.metadata or {}), BAR_CONTRACT_KEY: BAR_CONTRACT,
+        SOURCE_KEY: json.dumps({"schema": "nlalpha.market.source.v1", "assets": {symbol: loaded.source}}, sort_keys=True).encode(),
+    })
+    summary = {
+        "symbol": symbol, "interval": interval, "bar_count": table.num_rows,
+        "time_contract": json.loads(table.schema.metadata[TIME_CONTRACT_KEY]),
+        "volume_unit": "instrument_quantity", "bar_contract": BAR_CONTRACT.decode("ascii"),
+        "source": read_source_contract(table)["assets"][symbol],
+    }
+    output = io.BytesIO()
+    pq.write_table(table, output)
+    return output.getvalue(), summary
+
+
+class DataService:
+    """Bind data tools to one provider, artifact store, and host identity policy."""
+
+    def __init__(
+        self, provider: DataLoader, artifact_store: DataArtifactStore,
+        identity: HostIdentityConfig,
+    ) -> None:
+        self.provider = provider
+        self.artifact_store = artifact_store
+        self.identity = identity
+        meter = get_meter()
+        self._load_duration = meter.create_histogram(
+            "nlalpha.data.load_duration", description="Data loading duration in seconds", unit="s",
+        )
+        self._load_size = meter.create_histogram(
+            "nlalpha.data.load_size", description="Loaded data size in bytes", unit="B",
+        )
+        self._load_counter = meter.create_counter(
+            "nlalpha.data.load_completed", description="Number of data load operations completed",
+        )
+
+    @span("data.list_providers")
+    async def list_data_providers(self) -> dict[str, Any]:
+        """List the providers assembled for this application and their availability."""
+        providers = self.provider.list_providers()
+        return {"providers": providers, "count": len(providers)}
+
+    async def diagnose_data_providers(self) -> dict[str, Any]:
+        """Report installed data sources that failed discovery or configuration."""
+        diagnostics = self.provider.diagnostics()
+        return {"diagnostics": diagnostics, "count": len(diagnostics)}
+
+    @span("data.check_coverage")
+    async def check_data_coverage(
+        self, symbol: str, interval: str, start: str, end: str,
+        provider_id: str | None = None, price_adjustment: str | None = None,
+    ) -> dict[str, Any]:
+        """Check returned bar counts and endpoints for the requested range."""
+        requested = {"symbol": symbol, "interval": interval, "requested_start": start, "requested_end": end}
+        try:
+            loaded = await self.provider.load_bars(symbol, interval, start, end, provider_id=provider_id, price_adjustment=price_adjustment)
+            bars = loaded.bars
+        except Exception as exc:
+            logger.warning("check_data_coverage failed | symbol=%s | error=%s", symbol, exc)
+            return {**failure_response(exc), **requested, "available": False, "bar_count": 0}
+        if not bars:
+            return {**requested, "available": False, "bar_count": 0, "source": loaded.source}
+        actual_start = bars[0].datetime.isoformat()
+        actual_end = bars[-1].datetime.isoformat()
+        return {
+            **requested, "available": True, "bar_count": len(bars),
+            "actual_start": actual_start, "actual_end": actual_end, "source": loaded.source,
+        }
+
+    @span("data.get_quality")
+    async def get_data_quality(
+        self, symbol: str, interval: str, start: str, end: str,
+        provider_id: str | None = None, price_adjustment: str | None = None,
+    ) -> dict[str, Any]:
+        """Check OHLC range consistency and zero-volume bars in a requested range."""
+        try:
+            loaded = await self.provider.load_bars(symbol, interval, start, end, provider_id=provider_id, price_adjustment=price_adjustment)
+            bars = loaded.bars
+        except Exception as exc:
+            logger.warning("get_data_quality failed | symbol=%s | error=%s", symbol, exc)
+            return {**failure_response(exc), "symbol": symbol, "interval": interval, "quality_score": "unknown"}
+        if not bars:
+            return {"symbol": symbol, "interval": interval, "bar_count": 0, "quality_score": "poor", "source": loaded.source}
+        ohlc_anomalies = 0
+        zero_volume = 0
+        for bar in bars:
+            if bar.high < bar.low or bar.close < bar.low or bar.close > bar.high:
+                ohlc_anomalies += 1
+            if bar.open < bar.low or bar.open > bar.high:
+                ohlc_anomalies += 1
+            if bar.volume == 0:
+                zero_volume += 1
+        return {
+            "symbol": symbol, "interval": interval, "bar_count": len(bars),
+            "ohlc_anomalies": ohlc_anomalies, "zero_volume_bars": zero_volume, "source": loaded.source,
+        }
+
+    async def load_bars(
+        self, symbol: str, interval: str, start: str, end: str, ctx: Context,
+        provider_id: str | None = None, price_adjustment: str | None = None,
+    ) -> dict[str, Any]:
+        """Publish canonical bars as an immutable caller-scoped artifact."""
+        started_at = time.monotonic()
+        status = "failed"
+        with start_span("data.load_bars", attributes={
+            "symbol": symbol, "interval": interval, "start": start, "end": end,
+        }) as trace:
+            try:
+                scope = self.identity.resolve(ctx)
+                loaded = await self.provider.load_bars(symbol, interval, start, end, provider_id=provider_id, price_adjustment=price_adjustment)
+                bars = loaded.bars
+                if not bars:
+                    status = "empty"
+                    return {"symbol": symbol, "interval": interval, "bar_count": 0, "source": loaded.source}
+                data, summary = await asyncio.to_thread(_serialize_bars, loaded, symbol, interval)
+                metadata = await self.artifact_store.publish(
+                    data, scope=scope, media_type="application/vnd.apache.parquet",
+                    schema=summary["bar_contract"],
+                )
+                summary["data_ref"] = metadata.data_ref
+                status = "completed"
+                trace.set_attribute("bar_count", summary["bar_count"])
+                trace.set_attribute("data_size", len(data))
+                self._load_size.record(len(data), {"status": status})
+                logger.info("load_bars published | symbol=%s | ref=%s | bars=%d", symbol, metadata.data_ref, summary["bar_count"])
+                return summary
+            except asyncio.CancelledError:
+                status = "cancelled"
+                raise
+            except Exception as exc:
+                trace.set_attribute("error", str(exc))
+                trace.record_exception(exc)
+                logger.warning("load_bars failed | symbol=%s | error=%s", symbol, exc)
+                return {**failure_response(exc), "symbol": symbol, "interval": interval}
+            finally:
+                trace.set_attribute("status", status)
+                self._load_duration.record(time.monotonic() - started_at, {"status": status})
+                self._load_counter.add(1, {"status": status})
+
+    @span("data.list_calendars")
+    async def list_trading_calendars(self) -> list[dict]:
+        """List available exchange calendars."""
+        return _list_trading_calendars()
+
+    @span("data.trading_days")
+    async def get_trading_days(self, calendar_id: str, start: str, end: str) -> dict:
+        """Return the trading-session count for a calendar and date range."""
+        return _get_trading_days(calendar_id, start, end)
+
+    @span("data.is_trading_day")
+    async def is_trading_day(self, calendar_id: str, date: str) -> dict:
+        """Report whether a date is a trading session for the selected calendar."""
+        return _is_trading_day(calendar_id, date)
+
+    @span("data.list_instruments")
+    async def list_instruments(self, asset: str, market: str | None = None,
+                               status: str | None = None) -> dict[str, Any]:
+        """List one asset class's instrument master from the selected source."""
+        try:
+            instruments, source = await self.provider.list_instruments(asset, market=market, status=status)
+            return {"asset": asset, "instruments": instruments, "count": len(instruments), "source": source}
+        except Exception as exc:
+            logger.warning("list_instruments failed | asset=%s | error=%s", asset, exc)
+            return {**failure_response(exc), "asset": asset}
+
+    @span("data.get_trading_calendar")
+    async def get_trading_calendar(self, exchange: str, start: str, end: str) -> dict[str, Any]:
+        """Return normalized exchange calendar days for a date range."""
+        try:
+            days, source = await self.provider.get_trading_calendar(exchange, start, end)
+            return {"exchange": exchange, "days": days, "count": len(days), "source": source}
+        except Exception as exc:
+            logger.warning("get_trading_calendar failed | exchange=%s | error=%s", exchange, exc)
+            return {**failure_response(exc), "exchange": exchange}
+
+    @span("data.get_daily_basic")
+    async def get_daily_basic(self, symbol: str, start: str, end: str) -> dict[str, Any]:
+        """Return daily fundamental metrics for a symbol."""
+        try:
+            rows, source = await self.provider.get_daily_basic(symbol, start, end)
+            return {"symbol": symbol, "rows": rows, "count": len(rows), "source": source}
+        except Exception as exc:
+            logger.warning("get_daily_basic failed | symbol=%s | error=%s", symbol, exc)
+            return {**failure_response(exc), "symbol": symbol}
+
+    @span("data.get_price_limits")
+    async def get_price_limits(self, symbol: str, start: str, end: str) -> dict[str, Any]:
+        """Return daily price limits for a symbol."""
+        try:
+            rows, source = await self.provider.get_price_limits(symbol, start, end)
+            return {"symbol": symbol, "rows": rows, "count": len(rows), "source": source}
+        except Exception as exc:
+            logger.warning("get_price_limits failed | symbol=%s | error=%s", symbol, exc)
+            return {**failure_response(exc), "symbol": symbol}
+
+    @span("data.get_suspensions")
+    async def get_suspensions(self, symbol: str, start: str, end: str) -> dict[str, Any]:
+        """Return daily suspension rows for a symbol."""
+        try:
+            rows, source = await self.provider.get_suspensions(symbol, start, end)
+            return {"symbol": symbol, "rows": rows, "count": len(rows), "source": source}
+        except Exception as exc:
+            logger.warning("get_suspensions failed | symbol=%s | error=%s", symbol, exc)
+            return {**failure_response(exc), "symbol": symbol}
+
+    @span("data.get_index_weights")
+    async def get_index_weights(self, index_code: str, start: str, end: str) -> dict[str, Any]:
+        """Return index constituent weights for an index code."""
+        try:
+            rows, source = await self.provider.get_index_weights(index_code, start, end)
+            return {"index_code": index_code, "rows": rows, "count": len(rows), "source": source}
+        except Exception as exc:
+            logger.warning("get_index_weights failed | index_code=%s | error=%s", index_code, exc)
+            return {**failure_response(exc), "index_code": index_code}
+
+    @span("data.about")
+    async def about(self, sections: list[str] | None = None) -> dict[str, Any]:
+        """Describe this application's sources, shared data contracts, and calendar tools."""
+        try:
+            return describe_document("service", "nlalpha-data", "nlalpha-data", version("nlalpha-data"), {
+                "principles": common_description(),
+                "navigation": {
+                    "about": "Read shared data, time, source, coverage, and calendar contracts.",
+                    "list_data_providers": "Discover sources available in this application.",
+                    "diagnose_data_providers": "Inspect installed sources that are unavailable or failed to load.",
+                    "confess": "Read one installed source's manifest and provider-authored guidance.",
+                    "load_bars": "Load canonical bars into a caller-scoped immutable artifact.",
+                    "check_data_coverage": "Inspect returned row counts and observed endpoints for a requested range.",
+                    "get_data_quality": "Inspect OHLC consistency and zero-volume rows.",
+                    "list_trading_calendars": "Discover calendar IDs in the installed calendar library.",
+                    "get_trading_days": "Count calendar sessions in a requested date range.",
+                    "is_trading_day": "Check whether one date is a calendar session.",
+                    "list_instruments": "List an asset class's instrument master from the selected source.",
+                    "get_trading_calendar": "Read normalized exchange calendar days for a date range.",
+                    "get_daily_basic": "Read daily fundamental metrics for a symbol.",
+                    "get_price_limits": "Read daily price limits for a symbol.",
+                    "get_suspensions": "Read daily suspension records for a symbol.",
+                    "get_index_weights": "Read index constituent weights for a date range.",
+                },
+                "providers": [record.summary() for record in self.provider.records],
+                "diagnostics": self.provider.diagnostics(),
+                "loading": markdown_sections(resources.files("nlalpha_data").joinpath("knowledge", "loading.md").read_text(encoding="utf-8")),
+                "calendars": _confess(),
+            }, sections)
+        except Exception as exc:
+            return failure_response(exc)
+
+    @span("data.confess")
+    async def confess(self, provider_id: str, sections: list[str] | None = None) -> dict[str, Any]:
+        """Describe one source from this application's cached manifest and declared guidance."""
+        try:
+            record = self.provider.get_record(provider_id)
+            document_sections = {"identity": record.summary(), "manifest": record.manifest}
+            if record.guidance is not None:
+                document_sections.update({f"notes-{name}": text for name, text in markdown_sections(record.guidance).items()})
+            return describe_document("data_provider", provider_id, record.package, record.version, document_sections, sections)
+        except Exception as exc:
+            return failure_response(exc)
+
+
+async def _health(request):
+    """Report application liveness."""
+    return JSONResponse({"status": "ok"})
+
+
+async def _ready(request):
+    """Report startup completion and current artifact backend availability."""
+    ready = request.app.state.ready
+    if ready:
+        try:
+            await request.app.state.service.artifact_store.check_health()
+        except DataArtifactBackendError:
+            logger.error("Artifact storage readiness check failed")
+            ready = False
+    return JSONResponse({"status": "ready" if ready else "not_ready"}, status_code=200 if ready else 503)
+
+
+def create_app(
+    *, provider: DataLoader | None = None,
+    artifact_store: DataArtifactStore | None = None,
+    artifact_config: ArtifactStoreConfig | None = None,
+    identity: HostIdentityConfig | None = None,
+    allowed_hosts: list[str] | tuple[str, ...] | None = None,
+    on_shutdown: Callable[[], None] | None = None,
+) -> Starlette:
+    """Create an isolated data application and its application-owned resources."""
+    if artifact_store is not None and artifact_config is not None:
+        raise ValueError("Provide artifact_store or artifact_config, not both")
+    hosts = resolve_allowed_hosts(allowed_hosts)
+    selected_identity = HostIdentityConfig.from_env() if identity is None else identity
+    if provider is None:
+        workspace = Path(os.getenv("NLALPHA_WORKSPACE_DIR", str(Path.cwd() / "workspace")))
+        provider = get_default_data_provider(
+            cache_dir=str(workspace / "cache"), local_data_dir=str(workspace / "data"),
+        )
+    store = create_data_artifact_store(artifact_config) if artifact_store is None else artifact_store
+    service = DataService(provider, store, selected_identity)
+    mcp = FastMCP("nlalpha-data")
+    mcp.settings.transport_security = TransportSecuritySettings(
+        enable_dns_rebinding_protection=True, allowed_hosts=hosts,
+    )
+    for tool in (
+        service.list_data_providers, service.diagnose_data_providers, service.check_data_coverage, service.get_data_quality,
+        service.load_bars, service.list_trading_calendars, service.get_trading_days,
+        service.is_trading_day, service.list_instruments, service.get_trading_calendar,
+        service.get_daily_basic, service.get_price_limits, service.get_suspensions,
+        service.get_index_weights, service.about, service.confess,
+    ):
+        mcp.add_tool(tool)
+
+    @asynccontextmanager
+    async def lifespan(app):
+        app.state.ready = False
+        async with AsyncExitStack() as resources:
+            if on_shutdown is not None:
+                resources.callback(on_shutdown)
+            resources.push_async_callback(service.provider.aclose)
+            resources.push_async_callback(store.aclose)
+            await store.start()
+            app.state.ready = True
+            try:
+                yield
+            finally:
+                app.state.ready = False
+
+    sse_app = mcp.sse_app()
+    app = Starlette(routes=[Route("/health", _health), Route("/ready", _ready), *sse_app.routes], lifespan=lifespan)
+    app.state.mcp = mcp
+    app.state.service = service
+    app.state.ready = False
+    return app
+
+
+def main() -> None:
+    """Run the data application using explicit host and port settings."""
+    try:
+        configure_telemetry()
+        setup_logging(level="INFO", json_format=True)
+        uvicorn.run(create_app(on_shutdown=shutdown), host=os.getenv("NLALPHA_HOST", "127.0.0.1"), port=int(os.getenv("NLALPHA_PORT", "8000")))
+    finally:
+        shutdown()
+
+
+if __name__ == "__main__":
+    main()

nlalpha_data/sqlite_store.py

@@ -0,0 +1,174 @@
+"""Store canonical UTC bars with instrument quantity volume in SQLite's v2 table."""
+
+from __future__ import annotations
+
+from datetime import date
+from pathlib import Path
+import asyncio
+
+from nlalpha.core.contracts.market import Bar
+from nlalpha.core.contracts.time import datetime_to_ns, ns_to_datetime
+from nlalpha.core.errors import DataError
+from nlalpha_data.store import BaseBarStore, BarOverview, bar_source_date, BAR_CACHE_SCHEMA_VERSION
+
+try:
+    import aiosqlite
+except ImportError:
+    aiosqlite = None
+
+_TABLE = f"bar_data_v{BAR_CACHE_SCHEMA_VERSION}"
+
+_COLUMNS = (
+    "symbol", "interval", "timestamp_ns", "open_timestamp_ns", "open", "high", "low",
+    "close", "volume", "open_interest", "session_date", "source_timezone",
+    "source_utc_offset_seconds", "source_timestamp_semantics", "calendar_id", "source_date",
+)
+
+
+class SQLiteBarStore(BaseBarStore):
+    """Persist exact microsecond Bar values as UTC nanosecond integers."""
+
+    def __init__(self, db_path: str | None = None) -> None:
+        self._db_path = db_path or str(Path("workspace/bar_data.db").resolve())
+        self._conn = None
+        self._schema_ready = False
+        self._schema_lock = asyncio.Lock()
+
+    async def _ensure_conn(self):
+        """Open the async SQLite connection on demand."""
+        if self._conn is None:
+            if aiosqlite is None:
+                raise DataError("SQLiteBarStore requires aiosqlite.")
+            Path(self._db_path).parent.mkdir(parents=True, exist_ok=True)
+            self._conn = await aiosqlite.connect(self._db_path)
+            self._conn.row_factory = aiosqlite.Row
+        return self._conn
+
+    async def _ensure_schema(self) -> None:
+        """Create the current bar contract namespace and validate its columns."""
+        async with self._schema_lock:
+            if self._schema_ready:
+                return
+            conn = await self._ensure_conn()
+            async with conn.execute(f"PRAGMA table_info({_TABLE})") as cursor:
+                existing = await cursor.fetchall()
+            if existing and tuple(row["name"] for row in existing) != _COLUMNS:
+                raise DataError(
+                    f"SQLite {_TABLE} has no exact UTC/source contract.",
+                    details={"time_contract": True},
+                )
+            await conn.execute(f"""
+                CREATE TABLE IF NOT EXISTS {_TABLE} (
+                    symbol TEXT NOT NULL,
+                    interval TEXT NOT NULL,
+                    timestamp_ns INTEGER NOT NULL,
+                    open_timestamp_ns INTEGER,
+                    open REAL NOT NULL, high REAL NOT NULL, low REAL NOT NULL,
+                    close REAL NOT NULL, volume REAL NOT NULL, open_interest REAL,
+                    session_date TEXT, source_timezone TEXT,
+                    source_utc_offset_seconds INTEGER,
+                    source_timestamp_semantics TEXT NOT NULL,
+                    calendar_id TEXT,
+                    source_date TEXT NOT NULL,
+                    PRIMARY KEY (symbol, interval, timestamp_ns)
+                )
+            """)
+            await conn.execute(f"CREATE INDEX IF NOT EXISTS idx_{_TABLE}_range ON {_TABLE}(symbol, interval, timestamp_ns)")
+            await conn.execute(f"CREATE INDEX IF NOT EXISTS idx_{_TABLE}_source_date ON {_TABLE}(symbol, interval, source_date)")
+            await conn.commit()
+            self._schema_ready = True
+
+    async def save(self, bars: list[Bar], symbol: str = "", interval: str = "", start: str = "", end: str = "") -> int:
+        """Insert canonical bars with complete source metadata."""
+        if not bars:
+            return 0
+        key_symbol = symbol or bars[0].symbol
+        if any(bar.symbol != key_symbol for bar in bars):
+            raise DataError("SQLite cache key contradicts bar symbols.")
+        key_interval = interval or "1d"
+        await self._ensure_schema()
+        conn = await self._ensure_conn()
+        values = []
+        for bar in sorted(bars, key=lambda row: row.datetime):
+            close_ns = datetime_to_ns(bar.datetime)
+            open_ns = datetime_to_ns(bar.open_time) if bar.open_time is not None else None
+            if not -(1 << 63) <= close_ns < (1 << 63) or (open_ns is not None and not -(1 << 63) <= open_ns < (1 << 63)):
+                raise DataError("SQLite UTC nanosecond key is outside signed 64-bit range.", details={"time_contract": True})
+            values.append((
+                key_symbol, key_interval, close_ns, open_ns,
+                bar.open, bar.high, bar.low, bar.close, bar.volume, bar.open_interest,
+                bar.session_date.isoformat() if bar.session_date is not None else None,
+                bar.source_timezone, bar.source_utc_offset_seconds,
+                bar.source_timestamp_semantics, bar.calendar_id,
+                bar_source_date(bar).isoformat(),
+            ))
+        columns = ", ".join(_COLUMNS)
+        placeholders = ", ".join("?" for _ in _COLUMNS)
+        async with conn.executemany(f"INSERT OR IGNORE INTO {_TABLE} ({columns}) VALUES ({placeholders})", values) as cursor:
+            inserted = cursor.rowcount
+        await conn.commit()
+        return inserted
+
+    async def load(self, symbol: str, interval: str, start: str, end: str) -> list[Bar]:
+        """Load by inclusive source session dates or declared local civil dates."""
+        await self._ensure_schema()
+        conn = await self._ensure_conn()
+        begin, finish = date.fromisoformat(start), date.fromisoformat(end)
+        if begin > finish:
+            raise DataError("Requested start date is after end date.")
+        async with conn.execute(f"""
+            SELECT * FROM {_TABLE}
+            WHERE symbol = ? AND interval = ? AND source_date BETWEEN ? AND ?
+            ORDER BY timestamp_ns
+        """, (symbol, interval, begin.isoformat(), finish.isoformat())) as cursor:
+            rows = await cursor.fetchall()
+        bars = [Bar(
+            symbol=row["symbol"], datetime=ns_to_datetime(row["timestamp_ns"]),
+            open_time=ns_to_datetime(row["open_timestamp_ns"]) if row["open_timestamp_ns"] is not None else None,
+            open=row["open"], high=row["high"], low=row["low"], close=row["close"],
+            volume=row["volume"], open_interest=row["open_interest"],
+            session_date=date.fromisoformat(row["session_date"]) if row["session_date"] is not None else None,
+            source_timezone=row["source_timezone"], source_utc_offset_seconds=row["source_utc_offset_seconds"],
+            source_timestamp_semantics=row["source_timestamp_semantics"], calendar_id=row["calendar_id"],
+        ) for row in rows]
+        for bar, row in zip(bars, rows):
+            if bar_source_date(bar).isoformat() != row["source_date"]:
+                raise DataError("SQLite source_date contradicts its bar time contract.", details={"time_contract": True})
+        return bars
+
+    async def delete(self, symbol: str, interval: str) -> int:
+        """Delete one symbol and interval from the validated cache."""
+        await self._ensure_schema()
+        conn = await self._ensure_conn()
+        async with conn.execute(f"DELETE FROM {_TABLE} WHERE symbol = ? AND interval = ?", (symbol, interval)) as cursor:
+            deleted = cursor.rowcount
+        await conn.commit()
+        return deleted
+
+    async def get_overview(self) -> list[BarOverview]:
+        """Return exact UTC close-time ranges for stored series."""
+        await self._ensure_schema()
+        conn = await self._ensure_conn()
+        async with conn.execute(f"""
+            SELECT symbol, interval, COUNT(*) AS count,
+                   MIN(timestamp_ns) AS start, MAX(timestamp_ns) AS end
+            FROM {_TABLE} GROUP BY symbol, interval ORDER BY symbol, interval
+        """) as cursor:
+            rows = await cursor.fetchall()
+        return [BarOverview(symbol=row["symbol"], interval=row["interval"], count=row["count"],
+                            start=ns_to_datetime(row["start"]), end=ns_to_datetime(row["end"])) for row in rows]
+
+    async def close(self) -> None:
+        """Close the connection and reset its schema state."""
+        if self._conn is not None:
+            await self._conn.close()
+            self._conn = None
+            self._schema_ready = False
+
+    async def __aenter__(self):
+        await self._ensure_schema()
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        await self.close()
+        return False