aaos-logging-drive 0.1.0__tar.gz

aaos_logging_drive-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 devmcage
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

aaos_logging_drive-0.1.0/MANIFEST.in

@@ -0,0 +1,2 @@
+include LICENSE README.md
+recursive-include tests *.py

aaos_logging_drive-0.1.0/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: aaos-logging-drive
+Version: 0.1.0
+Summary: Read-only AAOS Logging Google Drive synchronization and recorded vehicle data processing
+Author: AAOS Logging contributors
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp<4,>=3.12
+Requires-Dist: tzdata>=2024.1
+Dynamic: license-file
+
+# AAOS Logging Drive Python library
+
+`aaos-logging-drive` is a standalone Python library for read-only access to AAOS
+Logging exports in Google Drive. The import name is `aaos_logging_drive`.
+Python 3.11 or newer is required. Home Assistant is **not** a dependency.
+
+Install version **0.1.0** from PyPI:
+
+```sh
+python -m pip install aaos-logging-drive==0.1.0
+```
+
+For local development, install from the source project instead:
+
+```sh
+python -m pip install ./packages/aaos-logging-drive
+```
+
+## Read recorded trips
+
+The caller supplies an `aiohttp.ClientSession` and an asynchronous token provider.
+Use a Google OAuth grant restricted to `https://www.googleapis.com/auth/drive.readonly`.
+The application owns consent, token storage and refresh; this library neither
+bundles credentials nor starts a hosted authentication service.
+
+```python
+import asyncio
+import os
+
+import aiohttp
+from aaos_logging_drive import AAOSDriveClient
+
+
+async def token_provider():
+    # For a long-running application, return a fresh OAuth access token here.
+    return os.environ["AAOS_DRIVE_ACCESS_TOKEN"]
+
+
+async def main():
+    async with aiohttp.ClientSession() as session:
+        client = AAOSDriveClient.from_google_drive(
+            session,
+            token_provider,
+            os.environ["AAOS_DRIVE_FOLDER"],  # Car folder ID or Drive folder URL.
+            history_path="car-history.sqlite",
+        )
+        snapshot = await client.refresh()
+        print(snapshot.manifest.raw["generationId"])
+        trips = await client.list_trips()
+        if trips:
+            trip = trips[-1]
+            page = await client.get_history(
+                "telemetry.speedKph", trip_id=trip["tripId"]
+            )
+            while True:
+                for point in page["points"]:
+                    print(point["time"], point["value"])
+                if page["next_cursor"] is None:
+                    break
+                page = await client.get_history(
+                    "telemetry.speedKph", trip_id=trip["tripId"],
+                    cursor=page["next_cursor"],
+                )
+
+
+asyncio.run(main())
+```
+
+`refresh()` selects a complete immutable Drive V3 generation, checks all artifact
+sizes/hashes and imports its detailed trip archives. Temporary publication races
+are retried. A failed import retains the preceding complete snapshot/history.
+Separate trips never share a power-estimation window. Missing data stays unknown.
+
+## API and persistence
+
+- `client.refresh()` returns a `Snapshot` with the latest recorded values and export metadata.
+- `client.history_fields()` returns field descriptions, units, counts and time bounds.
+- `client.list_trips(period="")` returns reviewed trip summaries; filter by `YYYY-MM` or `YYYY-MM-DD`.
+- `client.get_trip(trip_id="")` returns the exact original trip, including its arrays; blank selects latest.
+- `client.get_history(field, start=None, end=None, limit=2000, cursor=None, trip_id=None)` returns original-time readings with provenance and a continuation cursor. Bounds use Unix milliseconds.
+- `client.accepted_head` is a copy of the accepted generation checkpoint. Persist it in your application and pass it back as `accepted_head=` on restart to maintain rollback protection.
+
+For an established source, also persist `snapshot.manifest.raw["datasetId"]` and
+`["vehicleId"]`, and restore them as `expected_identity={"datasetId": ..., "vehicleId": ...}`.
+The library follows a changed identity only with a verified published merge;
+when local history exists, all previously imported trips must be preserved.
+Save checkpoints only after a successful `refresh()`. They contain source identity
+and hashes, not OAuth tokens. History can be queried offline after a previous
+complete import. Without `history_path`, only the validated current snapshot is available.
+
+The session is caller-owned and is never closed by the library. All SQLite and
+archive decoding work uses `asyncio.to_thread` by default. Applications can pass
+another asynchronous executor. Low-level `ReadOnlyDrive`, `DriveRepository`,
+`HistoryStore`, `Manifest`, `archive_trips`, `review_energy`, `capacity_telemetry`
+and `sync_history` are also available. `AAOSDriveClient(repository, history)`
+supports custom transports and an already initialized history store.
+
+## Supported data
+
+Drive sync V3, day-file format 1, trip schema 17 and the optional powertrain-v1
+extension are supported. Fuel/hybrid readings, nullable boolean states, route and
+weather samples, metadata, original trip JSON, and future export fields are retained.
+Fuel estimates exclude unobserved intervals and stationary use; hybrid battery
+energy remains separate. Battery-energy recovery is labeled as estimated, and
+capacity retention is not verified state of health. Historical recordings cannot
+acquire measurements that were never logged.
+
+The local history format and processing version are unchanged by the extraction
+from the Home Assistant integration. Applications must not use one history file
+concurrently from different processes. The generic hourly aggregation and opaque
+statistics checkpoint are available for adapters; this package does not register
+entities or write to Home Assistant Recorder.
+
+## Build and test
+
+```sh
+python -m pip install build twine
+python -m build packages/aaos-logging-drive --outdir dist
+python -m twine check dist/*
+python -m unittest discover -s packages/aaos-logging-drive/tests -v
+```
+
+The wheel and source distribution contain only this library, its license, and its
+standalone tests/documentation. They do not contain the Home Assistant wrapper,
+car data, authentication configuration or repository verification files.

aaos_logging_drive-0.1.0/README.md

@@ -0,0 +1,125 @@
+# AAOS Logging Drive Python library
+
+`aaos-logging-drive` is a standalone Python library for read-only access to AAOS
+Logging exports in Google Drive. The import name is `aaos_logging_drive`.
+Python 3.11 or newer is required. Home Assistant is **not** a dependency.
+
+Install version **0.1.0** from PyPI:
+
+```sh
+python -m pip install aaos-logging-drive==0.1.0
+```
+
+For local development, install from the source project instead:
+
+```sh
+python -m pip install ./packages/aaos-logging-drive
+```
+
+## Read recorded trips
+
+The caller supplies an `aiohttp.ClientSession` and an asynchronous token provider.
+Use a Google OAuth grant restricted to `https://www.googleapis.com/auth/drive.readonly`.
+The application owns consent, token storage and refresh; this library neither
+bundles credentials nor starts a hosted authentication service.
+
+```python
+import asyncio
+import os
+
+import aiohttp
+from aaos_logging_drive import AAOSDriveClient
+
+
+async def token_provider():
+    # For a long-running application, return a fresh OAuth access token here.
+    return os.environ["AAOS_DRIVE_ACCESS_TOKEN"]
+
+
+async def main():
+    async with aiohttp.ClientSession() as session:
+        client = AAOSDriveClient.from_google_drive(
+            session,
+            token_provider,
+            os.environ["AAOS_DRIVE_FOLDER"],  # Car folder ID or Drive folder URL.
+            history_path="car-history.sqlite",
+        )
+        snapshot = await client.refresh()
+        print(snapshot.manifest.raw["generationId"])
+        trips = await client.list_trips()
+        if trips:
+            trip = trips[-1]
+            page = await client.get_history(
+                "telemetry.speedKph", trip_id=trip["tripId"]
+            )
+            while True:
+                for point in page["points"]:
+                    print(point["time"], point["value"])
+                if page["next_cursor"] is None:
+                    break
+                page = await client.get_history(
+                    "telemetry.speedKph", trip_id=trip["tripId"],
+                    cursor=page["next_cursor"],
+                )
+
+
+asyncio.run(main())
+```
+
+`refresh()` selects a complete immutable Drive V3 generation, checks all artifact
+sizes/hashes and imports its detailed trip archives. Temporary publication races
+are retried. A failed import retains the preceding complete snapshot/history.
+Separate trips never share a power-estimation window. Missing data stays unknown.
+
+## API and persistence
+
+- `client.refresh()` returns a `Snapshot` with the latest recorded values and export metadata.
+- `client.history_fields()` returns field descriptions, units, counts and time bounds.
+- `client.list_trips(period="")` returns reviewed trip summaries; filter by `YYYY-MM` or `YYYY-MM-DD`.
+- `client.get_trip(trip_id="")` returns the exact original trip, including its arrays; blank selects latest.
+- `client.get_history(field, start=None, end=None, limit=2000, cursor=None, trip_id=None)` returns original-time readings with provenance and a continuation cursor. Bounds use Unix milliseconds.
+- `client.accepted_head` is a copy of the accepted generation checkpoint. Persist it in your application and pass it back as `accepted_head=` on restart to maintain rollback protection.
+
+For an established source, also persist `snapshot.manifest.raw["datasetId"]` and
+`["vehicleId"]`, and restore them as `expected_identity={"datasetId": ..., "vehicleId": ...}`.
+The library follows a changed identity only with a verified published merge;
+when local history exists, all previously imported trips must be preserved.
+Save checkpoints only after a successful `refresh()`. They contain source identity
+and hashes, not OAuth tokens. History can be queried offline after a previous
+complete import. Without `history_path`, only the validated current snapshot is available.
+
+The session is caller-owned and is never closed by the library. All SQLite and
+archive decoding work uses `asyncio.to_thread` by default. Applications can pass
+another asynchronous executor. Low-level `ReadOnlyDrive`, `DriveRepository`,
+`HistoryStore`, `Manifest`, `archive_trips`, `review_energy`, `capacity_telemetry`
+and `sync_history` are also available. `AAOSDriveClient(repository, history)`
+supports custom transports and an already initialized history store.
+
+## Supported data
+
+Drive sync V3, day-file format 1, trip schema 17 and the optional powertrain-v1
+extension are supported. Fuel/hybrid readings, nullable boolean states, route and
+weather samples, metadata, original trip JSON, and future export fields are retained.
+Fuel estimates exclude unobserved intervals and stationary use; hybrid battery
+energy remains separate. Battery-energy recovery is labeled as estimated, and
+capacity retention is not verified state of health. Historical recordings cannot
+acquire measurements that were never logged.
+
+The local history format and processing version are unchanged by the extraction
+from the Home Assistant integration. Applications must not use one history file
+concurrently from different processes. The generic hourly aggregation and opaque
+statistics checkpoint are available for adapters; this package does not register
+entities or write to Home Assistant Recorder.
+
+## Build and test
+
+```sh
+python -m pip install build twine
+python -m build packages/aaos-logging-drive --outdir dist
+python -m twine check dist/*
+python -m unittest discover -s packages/aaos-logging-drive/tests -v
+```
+
+The wheel and source distribution contain only this library, its license, and its
+standalone tests/documentation. They do not contain the Home Assistant wrapper,
+car data, authentication configuration or repository verification files.

aaos_logging_drive-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "aaos-logging-drive"
+version = "0.1.0"
+description = "Read-only AAOS Logging Google Drive synchronization and recorded vehicle data processing"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{name = "AAOS Logging contributors"}]
+dependencies = ["aiohttp>=3.12,<4", "tzdata>=2024.1"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+aaos_logging_drive = ["py.typed"]

aaos_logging_drive-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

aaos_logging_drive-0.1.0/src/aaos_logging_drive/__init__.py

@@ -0,0 +1,20 @@
+"""Read-only AAOS Logging Drive client and recorded vehicle data processing."""
+
+from .api import DriveAuthError, DriveError, DriveNotFoundError, ReadOnlyDrive, folder_id
+from .battery_capacity import capacity_telemetry
+from .client import AAOSDriveClient
+from .const import READ_SCOPE, readonly_grant
+from .energy import EnergyReview, effective_telemetry, review_energy
+from .history import HistoryStore, sync_history
+from .model import Artifact, ExportNotReady, InvalidExport, Manifest, Snapshot, archive_trips, trip_summary
+from .repository import DriveRepository
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AAOSDriveClient", "Artifact", "DriveAuthError", "DriveError", "DriveNotFoundError",
+    "DriveRepository", "EnergyReview", "ExportNotReady", "HistoryStore", "InvalidExport",
+    "Manifest", "READ_SCOPE", "ReadOnlyDrive", "Snapshot", "archive_trips",
+    "capacity_telemetry", "effective_telemetry", "folder_id", "readonly_grant",
+    "review_energy", "sync_history", "trip_summary",
+]

aaos_logging_drive-0.1.0/src/aaos_logging_drive/api.py

@@ -0,0 +1,134 @@
+"""Google Drive API reads only. OAuth token refresh belongs to the caller."""
+
+from __future__ import annotations
+
+import asyncio
+import random
+import re
+from typing import Awaitable, Callable
+
+import aiohttp
+
+from .const import API_ROOT, FOLDER_MIME, MAX_FILE_BYTES
+from .model import InvalidExport
+
+
+class DriveError(Exception):
+    """A transient Drive read failed."""
+
+
+class DriveAuthError(DriveError):
+    """The Drive grant needs renewed consent."""
+
+
+class DriveNotFoundError(DriveError):
+    """A file vanished or is not yet visible during a generation replacement."""
+
+
+class RetryableDriveError(DriveError):
+    """A rate limit or temporary Google service error."""
+
+    def __init__(self, message, retry_after=0):
+        super().__init__(message)
+        self.retry_after = retry_after
+
+
+def folder_id(value: str) -> str:
+    value = value.strip()
+    match = re.fullmatch(r"https://drive\.google\.com/drive/(?:u/\d+/)?folders/([\w-]+)(?:\?.*)?", value)
+    result = match[1] if match else value
+    if not re.fullmatch(r"[A-Za-z0-9_-]+", result):
+        raise InvalidExport("Enter a Google Drive folder ID or folder URL")
+    return result
+
+
+class ReadOnlyDrive:
+    def __init__(self, session: aiohttp.ClientSession, token: Callable[[], Awaitable[str]]):
+        self.session = session
+        self.token = token
+
+    async def _read(self, path: str, params: dict, limit: int, media: bool = False):
+        for attempt in range(3):
+            try:
+                return await self._read_once(path, params, limit, media)
+            except (RetryableDriveError, aiohttp.ClientError, TimeoutError) as err:
+                if attempt == 2:
+                    raise DriveError("Google Drive is temporarily unavailable after three read attempts") from err
+                delay = max(2 ** attempt + random.random(), getattr(err, "retry_after", 0))
+                await asyncio.sleep(min(delay, 60))
+
+    async def _read_once(self, path: str, params: dict, limit: int, media: bool = False):
+        access_token = await self.token()
+        async with self.session.get(
+            f"{API_ROOT}/{path}", params=params,
+            headers={"Authorization": f"Bearer {access_token}"},
+            timeout=aiohttp.ClientTimeout(total=180), allow_redirects=False,
+        ) as response:
+            if response.status == 401:
+                raise DriveAuthError("Google Drive authorization expired")
+            if response.status == 403:
+                # Quota exhaustion is transient; insufficient grants require reauth.
+                try:
+                    error = await response.json()
+                    reasons = {e.get("reason") for e in error.get("error", {}).get("errors", [])}
+                except (ValueError, aiohttp.ClientError):
+                    reasons = set()
+                if reasons & {"insufficientPermissions", "authError"}:
+                    raise DriveAuthError("Google Drive read-only permission is required")
+                if reasons & {"rateLimitExceeded", "userRateLimitExceeded"}:
+                    raise RetryableDriveError("Google Drive read rate limit reached")
+                raise DriveError("Google Drive denied the read (permission, API configuration or quota)")
+            if response.status in {429, 500, 502, 503, 504}:
+                try:
+                    retry_after = max(0, min(float(getattr(response, "headers", {}).get("Retry-After", "0")), 60))
+                except ValueError:
+                    retry_after = 0
+                raise RetryableDriveError(f"Temporary Google Drive HTTP {response.status}", retry_after)
+            if response.status == 404:
+                raise DriveNotFoundError("A Google Drive file is not visible or accessible")
+            if response.status >= 300:
+                raise DriveError(f"Google Drive read failed with HTTP {response.status}")
+            data = bytearray()
+            async for chunk in response.content.iter_chunked(64 * 1024):
+                data.extend(chunk)
+                if len(data) > limit:
+                    raise InvalidExport("Drive response exceeds the import limit")
+            if media:
+                return bytes(data)
+            from .model import json_object
+            return json_object(bytes(data))
+
+    async def metadata(self, file_id: str) -> dict:
+        return await self._read(f"files/{folder_id(file_id)}", {
+            "fields": "id,name,mimeType,size,sha256Checksum,trashed", "supportsAllDrives": "true",
+        }, 1024 * 1024)
+
+    async def children(self, parent: str) -> list[dict]:
+        parent = folder_id(parent)
+        result, page_token = [], None
+        while True:
+            params = {
+                "q": f"'{parent}' in parents and trashed = false", "spaces": "drive",
+                "fields": "nextPageToken,incompleteSearch,files(id,name,mimeType,size,sha256Checksum)",
+                "pageSize": "1000", "supportsAllDrives": "true", "includeItemsFromAllDrives": "true",
+            }
+            if page_token:
+                params["pageToken"] = page_token
+            page = await self._read("files", params, 8 * 1024 * 1024)
+            if page.get("incompleteSearch"):
+                raise DriveError("Drive returned an incomplete folder listing; retry later")
+            result.extend(page.get("files", []))
+            page_token = page.get("nextPageToken")
+            if not page_token:
+                return result
+
+    async def child_folder(self, parent: str, name: str) -> str:
+        matches = [f for f in await self.children(parent) if f.get("name") == name and f.get("mimeType") == FOLDER_MIME]
+        if len(matches) != 1:
+            raise InvalidExport(f"Expected one {name} folder; sync AAOS Logging V3 first")
+        return matches[0]["id"]
+
+    async def download(self, file_id: str, limit: int = MAX_FILE_BYTES) -> bytes:
+        return await self._read(f"files/{folder_id(file_id)}", {
+            "alt": "media", "supportsAllDrives": "true",
+        }, limit, media=True)

aaos_logging_drive-0.1.0/src/aaos_logging_drive/battery_capacity.py

@@ -0,0 +1,27 @@
+"""Paired, timestamped usable-capacity estimate; never a certified SoH sensor."""
+
+from math import isfinite
+
+FIELDS = frozenset({"batteryCurrentCapacityWh", "batteryNominalCapacityWh", "batteryCapacityRetentionPercent"})
+NOTICE = ("Estimated battery capacity retention, not verified battery state of health. "
+          "Current usable capacity / nominal usable capacity when new × 100. "
+          "Temperature and battery-management estimates affect this value; it does not measure permanent degradation. "
+          "Values above 100% are not capped. Missing capacities are not inferred from charge level, range or remaining energy.")
+
+
+def positive(value):
+    try:
+        return value if type(value) in (int, float) and isfinite(value) and value > 0 else None
+    except OverflowError:
+        return None
+
+
+def capacity_telemetry(point):
+    """Return a derived view, without modifying the original exported trip."""
+    result = dict(point)
+    current = positive(point.get("batteryCurrentCapacityWh"))
+    nominal = positive(point.get("batteryNominalCapacityWh"))
+    ratio = current / nominal * 100 if current is not None and nominal is not None else None
+    result.update(batteryCurrentCapacityWh=current, batteryNominalCapacityWh=nominal,
+                  batteryCapacityRetentionPercent=positive(ratio))
+    return result

aaos_logging_drive-0.1.0/src/aaos_logging_drive/client.py

@@ -0,0 +1,116 @@
+"""Framework-independent synchronization and local-history API."""
+
+from __future__ import annotations
+
+import asyncio
+from copy import deepcopy
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+import aiohttp
+
+from .api import DriveNotFoundError, ReadOnlyDrive, folder_id
+from .history import HistoryStore, sync_history
+from .model import ExportNotReady, Snapshot
+from .repository import DriveRepository
+
+
+class AAOSDriveClient:
+    """Coordinate complete imports, without owning credentials or HTTP sessions.
+
+    The low-level constructor accepts a repository and an initialized optional
+    HistoryStore. Use from_google_drive for automatic history initialization.
+    Persist accepted_head in the host application to retain rollback protection
+    across restarts; restore it through the factory's accepted_head argument.
+    """
+
+    def __init__(self, repository: DriveRepository, history: HistoryStore | None = None,
+                 *, executor=asyncio.to_thread):
+        self.repository = repository
+        self.history = history
+        self.executor = executor
+        self._lock = asyncio.Lock()
+        self._initialize_history = False
+
+    @classmethod
+    def from_google_drive(cls, session: aiohttp.ClientSession, token_provider, vehicle_folder: str,
+                          *, history_path: str | Path | None = None,
+                          expected_identity: dict | None = None, accepted_head: dict | None = None,
+                          executor=asyncio.to_thread) -> AAOSDriveClient:
+        """Use a caller-owned aiohttp session and async access-token provider.
+
+        Google OAuth consent and token refresh remain the caller's responsibility.
+        No credential is written to the local history database.
+        """
+        repository = DriveRepository(ReadOnlyDrive(session, token_provider), folder_id(vehicle_folder),
+                                     executor, expected_identity)
+        repository.accepted_head = dict(accepted_head) if accepted_head else None
+        history = HistoryStore(history_path) if history_path is not None else None
+        client = cls(repository, history, executor=executor)
+        client._initialize_history = history is not None
+        return client
+
+    @property
+    def snapshot(self) -> Snapshot | None:
+        return self.repository.snapshot
+
+    @property
+    def accepted_head(self) -> dict | None:
+        head = self.repository.accepted_head
+        return deepcopy(head) if head else None
+
+    async def refresh(self) -> Snapshot:
+        """Read the latest complete generation and retain old data on failure.
+
+        Publication races are retried three times. A generation is accepted only
+        after every required archive is validated and local history is complete.
+        """
+        async with self._lock:
+            if self._initialize_history:
+                await self.executor(self.history.initialize)
+                self._initialize_history = False
+            for attempt in range(3):
+                try:
+                    snapshot = await self.repository.refresh(accept=False)
+                    if self.history is not None:
+                        await sync_history(self.history, self.repository, snapshot, self.executor)
+                    break
+                except (ExportNotReady, DriveNotFoundError):
+                    if attempt == 2:
+                        raise
+                    await asyncio.sleep(2 ** attempt)
+            self.repository.accept_snapshot(snapshot)
+            snapshot.checked_at = datetime.now(timezone.utc)
+            if snapshot.previous_identity is not None:
+                self.repository.expected_identity = {
+                    key: snapshot.manifest.raw[key] for key in ("datasetId", "vehicleId")
+                }
+            return snapshot
+
+    async def _query(self, method: str, *args) -> Any:
+        async with self._lock:
+            if self.history is None:
+                raise ValueError("Configure history_path to query complete recorded history")
+            if self._initialize_history:
+                await self.executor(self.history.initialize)
+                self._initialize_history = False
+            if not (await self.executor(self.history.state))["generation_id"]:
+                raise ValueError("Import a complete generation before querying history")
+            return await self.executor(getattr(self.history, method), *args)
+
+    async def history_fields(self) -> dict:
+        return await self._query("overview")
+
+    async def list_trips(self, period: str = "") -> list[dict]:
+        return await self._query("summaries", period)
+
+    async def get_trip(self, trip_id: str = "") -> dict:
+        """Return the exact original trip, including its raw sample arrays."""
+        return await self._query("trip", trip_id)
+
+    async def get_history(self, field: str, *, start: int | None = None, end: int | None = None,
+                          limit: int = 2000, cursor: dict | None = None,
+                          trip_id: str | None = None) -> dict:
+        """Return timestamped readings and a generation-bound next_cursor."""
+        return await self._query("points", field, start, end, limit, cursor, trip_id)