fleetpull 0.1.0__py3-none-any.whl

fleetpull/endpoints/motive/driver_idle_rollups.py

@@ -0,0 +1,113 @@
+# src/fleetpull/endpoints/motive/driver_idle_rollups.py
+"""The Motive driver_idle_rollups binding: the driver arm of the
+window-grain utilization rollup pair (probe-settled 2026-07-21, DESIGN
+section 8). The legacy hub's ``driver_utilization``, shipped under the
+WIRE'S OWN envelope vocabulary -- the wrapper is
+``driver_idle_rollups``/``driver_idle_rollup``, a different vocabulary
+from its ``/v2/driver_utilization`` path, and the endpoint mirrors the
+wire (model ``DriverIdleRollup``; the legacy-name mapping is recorded
+in ``ENDPOINTS.md``).
+
+The vehicle arm's binding with the path, wrapper keys, and population
+swapped: the standard Motive wrapped-list envelope and offset
+pagination at the configured page size, but rows are the DRIVERS WITH
+ACTIVITY in the window (13 on a quiet single day, 653 across six days
+-- per-driver-per-window grain, unlike the vehicle arm's
+whole-fleet-every-window population), each attributed to the shared
+8-key ``UserSummary`` ``driver`` ref -- or to NULL on the unattributed
+rollup bucket row. Fleet-wide with per-record attribution, so no
+fan-out and no roster -- the default ``SingleFetch`` shape, declared by
+declaring nothing.
+
+The pair's window-grain facts are shared (vehicle_utilizations carries
+the full statement): the rollup grain is the request window, so
+``fixed_unit_days=1`` (the fuel-energy machinery's second consumer; the
+family precedent's do-not-sum posture rides the model docstring), the
+decoder-stamped ``window_start`` routes each day's rollup to its own
+partition, and the shared ``MotiveFleetDateRangeSpecBuilder`` maps the
+unit ``DateWindow`` to the INCLUSIVE ``start_date``/``end_date`` label
+pair -- interpreted in COMPANY-LOCAL days (the account's
+``/v1/companies`` zone at a UTC-5 offset), mirrored verbatim, never
+converted.
+"""
+
+from datetime import timedelta
+from typing import Final
+
+from fleetpull.config import MotiveConfig
+from fleetpull.endpoints.motive._spec_builders import MotiveFleetDateRangeSpecBuilder
+from fleetpull.endpoints.shared import (
+    EndpointDefinition,
+    StorageKind,
+    WatermarkMode,
+)
+from fleetpull.models.motive import DriverIdleRollup
+from fleetpull.network.decoders import MotiveWindowReportPageDecoder
+from fleetpull.vocabulary import Provider, QuotaScope
+
+__all__: list[str] = ['build_endpoint']
+
+_DRIVER_IDLE_ROLLUPS_PATH: Final[str] = '/v2/driver_utilization'
+
+# The wire's OWN envelope vocabulary -- NOT the path's: the wrapper keys
+# are driver_idle_rollups/driver_idle_rollup (captured 2026-07-21), and
+# the endpoint name follows the wire.
+_DRIVER_IDLE_ROLLUPS_LIST_KEY: Final[str] = 'driver_idle_rollups'
+_DRIVER_IDLE_ROLLUPS_ITEM_KEY: Final[str] = 'driver_idle_rollup'
+
+# The fixed work-unit width, in whole days -- the pair's window-grain
+# proof (module docstring; captured 2026-07-21): the unit width is part
+# of the row's meaning, pinned here rather than left to
+# sync.backfill_chunk_days (the fuel-energy machinery, DESIGN section 5).
+_FIXED_UNIT_DAYS: Final[int] = 1
+
+
+def build_endpoint(config: MotiveConfig) -> EndpointDefinition[DriverIdleRollup]:
+    """Build the Motive driver_idle_rollups watermark binding.
+
+    Per-driver idle rollups fetched incrementally at the fixed 1-day
+    unit width: the run resumes from a ``DateWindow`` (watermark with
+    the provider's late-arrival lookback from config), the planner tiles
+    it into exactly-one-day units (the declared ``fixed_unit_days`` --
+    module docstring for the window-grain statement), each unit's rows
+    are stamped with its window by the decoder and written to the
+    ``date=YYYY-MM-DD`` partition on ``window_start``, and each
+    refetched partition is replaced. Records arrive wrapped
+    (``{"driver_idle_rollups": [{"driver_idle_rollup": {...}}]}``)
+    under page-numbered pagination at the page size the config requests,
+    the ``start_date``/``end_date`` labels persisting across the walk.
+
+    Args:
+        config: The validated Motive configuration; supplies the base
+            URL the spec-builder joins to the utilization path, the page
+            size the decoder requests, and the lookback and cutoff the
+            watermark mode carries.
+
+    Returns:
+        The frozen driver_idle_rollups ``EndpointDefinition``.
+        Construction validates the ``WatermarkMode`` /
+        ``DATE_PARTITIONED`` / ``event_time_column`` triple against the
+        response model.
+    """
+    return EndpointDefinition(
+        provider=Provider.MOTIVE,
+        name='driver_idle_rollups',
+        spec_builder=MotiveFleetDateRangeSpecBuilder(
+            base_url=config.base_url,
+            path=_DRIVER_IDLE_ROLLUPS_PATH,
+        ),
+        page_decoder=MotiveWindowReportPageDecoder(
+            list_key=_DRIVER_IDLE_ROLLUPS_LIST_KEY,
+            item_key=_DRIVER_IDLE_ROLLUPS_ITEM_KEY,
+            per_page=config.records_per_page,
+        ),
+        response_model=DriverIdleRollup,
+        quota_scope=QuotaScope.MOTIVE,
+        storage_kind=StorageKind.DATE_PARTITIONED,
+        sync_mode=WatermarkMode(
+            lookback=timedelta(days=config.lookback_days),
+            cutoff=timedelta(days=config.cutoff_days),
+            fixed_unit_days=_FIXED_UNIT_DAYS,
+        ),
+        event_time_column='window_start',
+    )

fleetpull/endpoints/motive/driving_periods.py

@@ -0,0 +1,85 @@
+# src/fleetpull/endpoints/motive/driving_periods.py
+"""The Motive driving_periods watermark binding.
+
+A fleet-wide driving-event endpoint: one date-range request covers every
+vehicle, offset-paginated through the shared wrapped-list decoder. Window
+matching is START-anchored on UTC days (DESIGN §8, captured 2026-07-15):
+retrieval anchor and partition-routing anchor coincide natively, so the
+builder maps the resume window to the wire dates with no pad.
+
+The provider enforces a loud 30-day range cap — HTTP 400, ``"Date range
+cannot be greater than 30 days"`` — counting the date delta. Steady-state
+windows sit far inside it; a backfill configured with chunks wider than
+30 days fails loudly on the first request rather than losing data
+silently, and the fix is a smaller chunk width.
+"""
+
+from datetime import timedelta
+from typing import Final
+
+from fleetpull.config import MotiveConfig
+from fleetpull.endpoints.motive._spec_builders import MotiveFleetDateRangeSpecBuilder
+from fleetpull.endpoints.shared import (
+    EndpointDefinition,
+    StorageKind,
+    WatermarkMode,
+)
+from fleetpull.models.motive import DrivingPeriod
+from fleetpull.network.decoders import MotiveWrappedListPageDecoder
+from fleetpull.vocabulary import Provider, QuotaScope
+
+__all__: list[str] = ['build_endpoint']
+
+_DRIVING_PERIODS_PATH: Final[str] = '/v1/driving_periods'
+_DRIVING_PERIODS_LIST_KEY: Final[str] = 'driving_periods'
+_DRIVING_PERIODS_ITEM_KEY: Final[str] = 'driving_period'
+
+# The page size sent on every request. Captured honored at 100
+# (2026-07-15); larger values are unprobed. A strong candidate for a
+# user config knob — promotion is one new MotiveConfig field passed
+# where this constant is passed.
+_PER_PAGE: Final[int] = 100
+
+
+def build_endpoint(config: MotiveConfig) -> EndpointDefinition[DrivingPeriod]:
+    """Build the Motive driving_periods watermark binding.
+
+    Fleet-wide driving spans fetched incrementally: the run resumes from
+    a ``DateWindow`` (watermark with the provider's late-arrival lookback
+    from config — which also refetches yesterday's in-progress records
+    once they complete), the fetched whole days are written to
+    ``date=YYYY-MM-DD`` partitions on ``start_time``, and each refetched
+    partition is replaced. Records arrive wrapped and offset-paginated
+    (``{"driving_periods": [{"driving_period": {...}}], "pagination":
+    {...}}``).
+
+    Args:
+        config: The validated Motive configuration; supplies the base URL
+            and the lookback and cutoff the watermark mode carries.
+
+    Returns:
+        The frozen driving_periods ``EndpointDefinition``. Construction
+        validates the ``WatermarkMode`` / ``DATE_PARTITIONED`` /
+        ``event_time_column`` triple against the response model.
+    """
+    return EndpointDefinition(
+        provider=Provider.MOTIVE,
+        name='driving_periods',
+        spec_builder=MotiveFleetDateRangeSpecBuilder(
+            base_url=config.base_url,
+            path=_DRIVING_PERIODS_PATH,
+        ),
+        page_decoder=MotiveWrappedListPageDecoder(
+            list_key=_DRIVING_PERIODS_LIST_KEY,
+            item_key=_DRIVING_PERIODS_ITEM_KEY,
+            per_page=_PER_PAGE,
+        ),
+        response_model=DrivingPeriod,
+        quota_scope=QuotaScope.MOTIVE,
+        storage_kind=StorageKind.DATE_PARTITIONED,
+        sync_mode=WatermarkMode(
+            lookback=timedelta(days=config.lookback_days),
+            cutoff=timedelta(days=config.cutoff_days),
+        ),
+        event_time_column='start_time',
+    )

fleetpull/endpoints/motive/groups.py

@@ -0,0 +1,61 @@
+# src/fleetpull/endpoints/motive/groups.py
+"""The Motive groups binding: a factory composing the groups snapshot
+EndpointDefinition from resolved Motive configuration.
+
+The vehicles template verbatim, bound to ``/v1/groups`` (probed
+2026-07-21): a full-population wrapped-list snapshot on the shared
+static-GET builder and the existing Motive offset-pagination decoder, at
+the configured page size (``per_page`` 50 and 100 both honored live). No
+roster is sourced or consumed.
+"""
+
+from typing import Final
+
+from fleetpull.config import MotiveConfig
+from fleetpull.endpoints.shared import (
+    EndpointDefinition,
+    SnapshotMode,
+    StaticGetSpecBuilder,
+    StorageKind,
+)
+from fleetpull.models.motive import Group
+from fleetpull.network.decoders import MotiveWrappedListPageDecoder
+from fleetpull.vocabulary import Provider, QuotaScope
+
+__all__: list[str] = ['build_endpoint']
+
+_GROUPS_PATH: Final[str] = '/v1/groups'
+_GROUPS_LIST_KEY: Final[str] = 'groups'
+_GROUPS_ITEM_KEY: Final[str] = 'group'
+
+
+def build_endpoint(config: MotiveConfig) -> EndpointDefinition[Group]:
+    """Build the Motive groups snapshot binding.
+
+    A full-dataset snapshot of the company's group tree: no resume, a
+    single parquet file, full replacement each run. Records arrive
+    wrapped (``{"groups": [{"group": {...}}]}``) under page-numbered
+    pagination, at the page size the config requests.
+
+    Args:
+        config: The validated Motive configuration; supplies the base URL
+            the spec-builder joins to the groups path and the page size
+            the decoder requests.
+
+    Returns:
+        The frozen groups ``EndpointDefinition``.
+    """
+    return EndpointDefinition(
+        provider=Provider.MOTIVE,
+        name='groups',
+        spec_builder=StaticGetSpecBuilder(base_url=config.base_url, path=_GROUPS_PATH),
+        page_decoder=MotiveWrappedListPageDecoder(
+            list_key=_GROUPS_LIST_KEY,
+            item_key=_GROUPS_ITEM_KEY,
+            per_page=config.records_per_page,
+        ),
+        response_model=Group,
+        quota_scope=QuotaScope.MOTIVE,
+        storage_kind=StorageKind.SINGLE,
+        sync_mode=SnapshotMode(),
+    )

fleetpull/endpoints/motive/idle_events.py

@@ -0,0 +1,94 @@
+# src/fleetpull/endpoints/motive/idle_events.py
+"""The Motive idle_events watermark binding.
+
+A fleet-wide idle-event endpoint: one date-range request covers every
+vehicle, offset-paginated through the shared wrapped-list decoder. Unlike
+its driving_periods sibling, window matching here is OVERLAP-anchored on
+**company-local** day boundaries, not UTC (DESIGN §8, captured
+2026-07-15, prediction-confirmed): the wire dates are interpreted in the
+account's configured timezone. The binding therefore pads the wire window
+one day on each side — covering any account timezone — and the true UTC
+window does the trimming: the post-fetch window filter keeps only records
+whose ``start_time`` falls in the resume window, and the writer's
+partition tripwire enforces it. Every record lands in exactly one chunk;
+the pad widens only what is fetched, never what is written.
+
+The 30-day range cap is NOT enforced here (a 35-day window was honored
+end-to-end in capture) — but chunking stays bounded with the sibling's
+cap anyway, keeping wide-window latency (observed 12-18 s) inside the
+configured HTTP read timeout.
+"""
+
+from datetime import timedelta
+from typing import Final
+
+from fleetpull.config import MotiveConfig
+from fleetpull.endpoints.motive._spec_builders import MotiveFleetDateRangeSpecBuilder
+from fleetpull.endpoints.shared import (
+    EndpointDefinition,
+    StorageKind,
+    WatermarkMode,
+)
+from fleetpull.models.motive import IdleEvent
+from fleetpull.network.decoders import MotiveWrappedListPageDecoder
+from fleetpull.vocabulary import Provider, QuotaScope
+
+__all__: list[str] = ['build_endpoint']
+
+_IDLE_EVENTS_PATH: Final[str] = '/v1/idle_events'
+_IDLE_EVENTS_LIST_KEY: Final[str] = 'idle_events'
+_IDLE_EVENTS_ITEM_KEY: Final[str] = 'idle_event'
+
+# The page size sent on every request. Captured honored at 100
+# (2026-07-15); larger values are unprobed. A strong candidate for a
+# user config knob — promotion is one new MotiveConfig field passed
+# where this constant is passed.
+_PER_PAGE: Final[int] = 100
+
+# One whole day each side: the timezone-agnostic cover for the
+# company-local overlap matching described in the module docstring.
+_WINDOW_PAD_DAYS: Final[int] = 1
+
+
+def build_endpoint(config: MotiveConfig) -> EndpointDefinition[IdleEvent]:
+    """Build the Motive idle_events watermark binding.
+
+    Fleet-wide idle intervals fetched incrementally: the run resumes from
+    a ``DateWindow`` (watermark with the provider's late-arrival lookback
+    from config), the wire window is padded per the module docstring, the
+    kept records are written to ``date=YYYY-MM-DD`` partitions on
+    ``start_time``, and each refetched partition is replaced. Records
+    arrive wrapped and offset-paginated (``{"idle_events":
+    [{"idle_event": {...}}], "pagination": {...}}``).
+
+    Args:
+        config: The validated Motive configuration; supplies the base URL
+            and the lookback and cutoff the watermark mode carries.
+
+    Returns:
+        The frozen idle_events ``EndpointDefinition``. Construction
+        validates the ``WatermarkMode`` / ``DATE_PARTITIONED`` /
+        ``event_time_column`` triple against the response model.
+    """
+    return EndpointDefinition(
+        provider=Provider.MOTIVE,
+        name='idle_events',
+        spec_builder=MotiveFleetDateRangeSpecBuilder(
+            base_url=config.base_url,
+            path=_IDLE_EVENTS_PATH,
+            window_pad_days=_WINDOW_PAD_DAYS,
+        ),
+        page_decoder=MotiveWrappedListPageDecoder(
+            list_key=_IDLE_EVENTS_LIST_KEY,
+            item_key=_IDLE_EVENTS_ITEM_KEY,
+            per_page=_PER_PAGE,
+        ),
+        response_model=IdleEvent,
+        quota_scope=QuotaScope.MOTIVE,
+        storage_kind=StorageKind.DATE_PARTITIONED,
+        sync_mode=WatermarkMode(
+            lookback=timedelta(days=config.lookback_days),
+            cutoff=timedelta(days=config.cutoff_days),
+        ),
+        event_time_column='start_time',
+    )

fleetpull/endpoints/motive/users.py

@@ -0,0 +1,64 @@
+# src/fleetpull/endpoints/motive/users.py
+"""The Motive users binding: a factory composing the users snapshot
+EndpointDefinition from resolved Motive configuration.
+
+The vehicles template verbatim, bound to ``/v1/users`` (probed
+2026-07-21): a full-population wrapped-list snapshot on the shared
+static-GET builder and the existing Motive offset-pagination decoder, at
+the configured page size (``per_page`` 50 and 100 both honored live).
+Only the pagination parameters are sent — the unfiltered listing is the
+complete population, one dataset despite the role-partitioned record
+shape: the ``role`` column carries the split (DESIGN section 8). No
+roster is sourced or consumed.
+"""
+
+from typing import Final
+
+from fleetpull.config import MotiveConfig
+from fleetpull.endpoints.shared import (
+    EndpointDefinition,
+    SnapshotMode,
+    StaticGetSpecBuilder,
+    StorageKind,
+)
+from fleetpull.models.motive import User
+from fleetpull.network.decoders import MotiveWrappedListPageDecoder
+from fleetpull.vocabulary import Provider, QuotaScope
+
+__all__: list[str] = ['build_endpoint']
+
+_USERS_PATH: Final[str] = '/v1/users'
+_USERS_LIST_KEY: Final[str] = 'users'
+_USERS_ITEM_KEY: Final[str] = 'user'
+
+
+def build_endpoint(config: MotiveConfig) -> EndpointDefinition[User]:
+    """Build the Motive users snapshot binding.
+
+    A full-dataset snapshot of every account — drivers, admins, and
+    fleet users: no resume, a single parquet file, full replacement each
+    run. Records arrive wrapped (``{"users": [{"user": {...}}]}``) under
+    page-numbered pagination, at the page size the config requests.
+
+    Args:
+        config: The validated Motive configuration; supplies the base URL
+            the spec-builder joins to the users path and the page size
+            the decoder requests.
+
+    Returns:
+        The frozen users ``EndpointDefinition``.
+    """
+    return EndpointDefinition(
+        provider=Provider.MOTIVE,
+        name='users',
+        spec_builder=StaticGetSpecBuilder(base_url=config.base_url, path=_USERS_PATH),
+        page_decoder=MotiveWrappedListPageDecoder(
+            list_key=_USERS_LIST_KEY,
+            item_key=_USERS_ITEM_KEY,
+            per_page=config.records_per_page,
+        ),
+        response_model=User,
+        quota_scope=QuotaScope.MOTIVE,
+        storage_kind=StorageKind.SINGLE,
+        sync_mode=SnapshotMode(),
+    )

fleetpull/endpoints/motive/vehicle_locations.py

@@ -0,0 +1,170 @@
+# src/fleetpull/endpoints/motive/vehicle_locations.py
+"""The Motive vehicle_locations watermark spec-builder and roster fan-out shape.
+
+A per-vehicle breadcrumb endpoint. The binding declares its request shape
+(``request_shape=RosterFanOut(...)``) naming the ``vehicle_ids`` roster by its
+opaque ``RosterKey`` -- this module knows nothing about the roster's feeder.
+The orchestration entry (``orchestrator/entry.py``) resolves that key through
+the ``RosterRegistry`` to its ``RosterDefinition``, refreshes the stored
+membership via the ``RosterRefreshCoordinator`` when stale, reads the members
+from the ``RosterStore``, and feeds the shape-resolution seam, which builds
+the ``FanOutRequestDriver`` -- that driver then calls ``build_spec`` once per
+member, passing that vehicle's id in ``member_values`` and the run's resume
+``DateWindow`` as ``resume``. The builder renders the per-vehicle path and
+maps the window to Motive's ``start_date`` / ``end_date`` query parameters.
+
+Motive's ``start_date`` / ``end_date`` are inclusive on both ends and day-granular,
+anchored on ``located_at`` -- the endpoint returns every breadcrumb whose date falls
+in ``[start_date, end_date]`` (confirmed against the predecessor's production
+fetcher, whose comment records that Motive "returns full days"). The date-partitioned
+watermark path wants exactly those whole days -- each ``date=`` partition is replaced
+wholesale -- so unlike the predecessor (which post-filtered to an exact datetime
+range for its single-file output), this builder does not trim: it fetches the whole
+days and lets the writer replace whole partitions.
+
+The mapping aligns with the storage layer's covered dates (``window_dates``):
+``start_date`` is the UTC date of ``window.start`` and ``end_date`` is the window's
+``last_covered_date`` (the one-microsecond derivation is stated once, on
+``DateWindow``). So what
+this builder fetches equals what the writer replaces and prunes: the same date set,
+no edge double-count, idempotent on refetch.
+
+This is the dedicated builder for vehicle_locations specifically -- a date-range
+fetch plus a per-vehicle path fan-out. The fleet-wide Motive date-range endpoints
+(driving_periods, idle_events) share ``MotiveFleetDateRangeSpecBuilder``
+(``endpoints/motive/_spec_builders.py``); this one stays separate because it renders
+the per-vehicle path.
+"""
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from datetime import timedelta
+from typing import Final
+
+from fleetpull.config import MotiveConfig
+from fleetpull.endpoints.shared import (
+    EndpointDefinition,
+    ResumeValue,
+    RosterFanOut,
+    StorageKind,
+    WatermarkMode,
+    render_url_path_template,
+    require_date_window,
+)
+from fleetpull.models.motive import VehicleLocation
+from fleetpull.network.contract import HttpMethod, RequestSpec
+from fleetpull.network.decoders import MotiveWrappedSinglePageDecoder
+from fleetpull.roster import RosterKey
+from fleetpull.timing import to_utc_date_string
+from fleetpull.vocabulary import Provider, QuotaScope
+
+__all__: list[str] = [
+    'MotiveVehicleLocationsSpecBuilder',
+    'build_endpoint',
+]
+
+_VEHICLE_LOCATIONS_PATH: Final[str] = '/v3/vehicle_locations/{vehicle_id}'
+_VEHICLE_LOCATIONS_LIST_KEY: Final[str] = 'vehicle_locations'
+_VEHICLE_LOCATIONS_ITEM_KEY: Final[str] = 'vehicle_location'
+
+
+@dataclass(frozen=True, slots=True)
+class MotiveVehicleLocationsSpecBuilder:
+    """Build the per-vehicle, date-windowed first request for vehicle_locations.
+
+    The ``SpecBuilder`` for the Motive vehicle_locations watermark endpoint:
+    renders the per-vehicle path and injects the resume window as Motive's
+    ``start_date`` / ``end_date`` parameters. The endpoint is not paginated, so this
+    first request is the only request; the page decoder returns no successor.
+
+    Attributes:
+        base_url: Root of the Motive API, trailing-slash-normalized by the provider
+            config so the leading-slash path joins directly.
+        path_template: The per-vehicle request path with the ``{vehicle_id}``
+            placeholder (``'/v3/vehicle_locations/{vehicle_id}'``).
+    """
+
+    base_url: str
+    path_template: str
+
+    def build_spec(
+        self, resume: ResumeValue, member_values: Mapping[str, str]
+    ) -> RequestSpec:
+        """Build the per-vehicle, date-windowed GET.
+
+        Args:
+            resume: The run's resume window. Must be a ``DateWindow`` -- a watermark
+                endpoint always resumes from one; any other value is a wiring bug.
+            member_values: The fan-out member binding; must carry ``vehicle_id``
+                (the strict template renderer rejects a missing or extra key).
+
+        Returns:
+            A credential-less ``GET`` for the per-vehicle URL, carrying
+            ``start_date`` / ``end_date`` for the window's covered dates. Auth
+            headers are layered on by the client's ``ProviderProfile``.
+
+        Raises:
+            TypeError: ``resume`` is not a ``DateWindow``.
+            UrlPathTemplateError: ``member_values`` does not match the template's
+                placeholders, or a value is empty.
+
+        Side Effects:
+            None.
+        """
+        resume_window = require_date_window(resume, type(self).__name__)
+        rendered_path = render_url_path_template(self.path_template, member_values)
+        url = f'{self.base_url}{rendered_path}'
+        start_date = to_utc_date_string(resume_window.start)
+        end_date = resume_window.last_covered_date.isoformat()
+        params = {'start_date': start_date, 'end_date': end_date}
+        return RequestSpec(method=HttpMethod.GET, url=url, params=params)
+
+
+def build_endpoint(config: MotiveConfig) -> EndpointDefinition[VehicleLocation]:
+    """Build the Motive vehicle_locations watermark binding.
+
+    A per-vehicle breadcrumb history fetched incrementally: the run resumes from a
+    ``DateWindow`` (watermark with the provider's late-arrival lookback from config),
+    the fetched whole days are written to ``date=YYYY-MM-DD`` partitions, and each
+    refetched partition is replaced. Records arrive wrapped and unpaginated
+    (``{"vehicle_locations": [{"vehicle_location": {...}}]}``). The
+    ``request_shape`` declaration (``RosterFanOut``) names the ``vehicle_ids``
+    roster; the orchestration entry resolves it to members and fans one request
+    chain per vehicle, passing each ``vehicle_id`` to the spec-builder's
+    ``member_values`` — this binding only declares the strategies and the
+    roster key, never the roster's feeder.
+
+    Args:
+        config: The validated Motive configuration; supplies the base URL the
+            spec-builder joins to the per-vehicle path and the lookback and
+            cutoff the watermark mode carry.
+
+    Returns:
+        The frozen vehicle_locations ``EndpointDefinition``. Construction validates
+        the ``WatermarkMode`` / ``DATE_PARTITIONED`` / ``event_time_column`` triple
+        against the response model.
+    """
+    return EndpointDefinition(
+        provider=Provider.MOTIVE,
+        name='vehicle_locations',
+        spec_builder=MotiveVehicleLocationsSpecBuilder(
+            base_url=config.base_url,
+            path_template=_VEHICLE_LOCATIONS_PATH,
+        ),
+        page_decoder=MotiveWrappedSinglePageDecoder(
+            list_key=_VEHICLE_LOCATIONS_LIST_KEY,
+            item_key=_VEHICLE_LOCATIONS_ITEM_KEY,
+        ),
+        response_model=VehicleLocation,
+        quota_scope=QuotaScope.MOTIVE,
+        storage_kind=StorageKind.DATE_PARTITIONED,
+        sync_mode=WatermarkMode(
+            lookback=timedelta(days=config.lookback_days),
+            cutoff=timedelta(days=config.cutoff_days),
+        ),
+        event_time_column='located_at',
+        request_shape=RosterFanOut(
+            roster=RosterKey(Provider.MOTIVE, 'vehicle_ids'),
+            member_key='vehicle_id',
+        ),
+    )