fleetpull 0.1.0__py3-none-any.whl

fleetpull/network/decoders/geotab.py

@@ -0,0 +1,309 @@
+# src/fleetpull/network/decoders/geotab.py
+"""GeoTab page decoders: GetFeed (toVersion cursor) and seek-paging Get.
+
+Feed pagination over JSON-RPC (scrubbed provider-behavior verification,
+June 2026): the request body's ``params`` carry ``typeName``,
+``resultsLimit``, and either ``search`` (the historical bootstrap) or
+``fromVersion`` (the resume cursor); the ``result`` is
+``{"data": [...], "toVersion": str}``. ``toVersion`` is the durable
+cursor and surfaces from every page including the terminal one.
+
+Seek paging over plain ``Get`` (captured 2026-07-09): ``Get`` silently
+hard-caps at 5,000 records with no continuation signal (``GetCountOf``
+5,666 vs the capped 5,000), so a capped entity pages by ``sort`` on
+``id`` ascending -- each advance sets ``sort.offset`` to the last
+returned record's ``id``; termination is the empty result list (a short
+page is NOT terminal, deliberately unlike the feed rule). The ``result``
+is a plain record list.
+
+Decoder logic deliberately resembles its siblings without sharing code
+across providers.
+"""
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Final
+
+from pydantic import Field
+
+from fleetpull.exceptions import ProviderResponseError
+from fleetpull.network.contract import (
+    DecodedPage,
+    PageAdvance,
+    RequestSpec,
+    StrictEnvelopeSlice,
+    validated_envelope_slice,
+)
+from fleetpull.vocabulary import JsonObject, JsonValue
+
+__all__: list[str] = ['GeotabFeedPageDecoder', 'GeotabGetPageDecoder']
+
+# Wire-protocol tokens: Final constants, not an enum. Deliberately unshared
+# with other providers' decoder modules.
+_PARAMS_KEY: Final[str] = 'params'
+_RESULTS_LIMIT_KEY: Final[str] = 'resultsLimit'
+_SEARCH_KEY: Final[str] = 'search'
+_FROM_VERSION_KEY: Final[str] = 'fromVersion'
+_SORT_KEY: Final[str] = 'sort'
+_OFFSET_KEY: Final[str] = 'offset'
+_ID_KEY: Final[str] = 'id'
+
+
+class _GeotabFeedResult(StrictEnvelopeSlice):
+    """GetFeed's result: the records and the durable cursor.
+
+    ``data`` is typed as a list of JSON objects so the decoder's
+    ``list[JsonObject]`` records return is honored at validation time.
+    """
+
+    data: list[JsonObject]
+    to_version: str = Field(alias='toVersion')
+
+
+class _GeotabFeedEnvelope(StrictEnvelopeSlice):
+    """Envelope slice: locates the feed result."""
+
+    result: _GeotabFeedResult
+
+
+def _params_from_body(
+    sent: RequestSpec, method_label: str
+) -> tuple[Mapping[str, JsonValue], Mapping[str, JsonValue], int]:
+    """Locate the sent spec's JSON-RPC body, ``params``, and ``resultsLimit``.
+
+    The sent body is fleetpull's own construction, not provider data, so
+    malformation here is a caller bug -- stdlib ``ValueError``, no slice
+    model -- and the body-is-present guard lives here too, stated once.
+    Shared by both GeoTab decoders (same module, same provider).
+
+    Args:
+        sent: The spec under inspection.
+        method_label: The method-class word for the error messages
+            (``'feed'`` / ``'Get'``).
+
+    Returns:
+        The JSON-RPC body, its ``params`` mapping, and the integer
+        ``resultsLimit``.
+
+    Raises:
+        ValueError: When the spec carries no JSON-RPC body, or ``params``
+            or ``resultsLimit`` is missing or mistyped.
+    """
+    if sent.json_body is None:
+        raise ValueError(f'GeoTab {method_label} requests require a JSON-RPC body')
+    sent_body: Mapping[str, JsonValue] = sent.json_body
+    params_value: JsonValue = sent_body.get(_PARAMS_KEY)
+    if not isinstance(params_value, Mapping):
+        raise ValueError(
+            f'GeoTab {method_label} request body must carry a {_PARAMS_KEY!r} mapping'
+        )
+    results_limit: JsonValue = params_value.get(_RESULTS_LIMIT_KEY)
+    # bool is a subclass of int; a True resultsLimit is a bug, not 1.
+    if not isinstance(results_limit, int) or isinstance(results_limit, bool):
+        raise ValueError(
+            f'GeoTab {method_label} request params must carry an integer '
+            f'{_RESULTS_LIMIT_KEY!r}'
+        )
+    return sent_body, params_value, results_limit
+
+
+@dataclass(frozen=True, slots=True)
+class GeotabFeedPageDecoder:
+    """Decode GeoTab GetFeed pages and advance by ``toVersion``.
+
+    No configuration fields: ``resultsLimit`` is read from the sent
+    body, so decoder-versus-endpoint divergence is structurally
+    impossible.
+    """
+
+    def first_request(self, spec: RequestSpec) -> RequestSpec:
+        """Return the spec unchanged.
+
+        The base spec already carries the bootstrap ``search.fromDate``
+        or resume ``fromVersion`` -- state-layer input, not the
+        decoder's concern.
+        """
+        return spec
+
+    def decode_page(self, sent: RequestSpec, envelope: JsonValue) -> DecodedPage:
+        """Extract the feed records and compute the version verdict.
+
+        Args:
+            sent: The spec that produced this page; its body supplies
+                ``resultsLimit`` and seeds the next page's body.
+            envelope: The parsed response body.
+
+        Returns:
+            The feed records and the verdict. ``durable_progress``
+            carries ``toVersion`` on EVERY page, terminal included.
+
+        Raises:
+            ProviderResponseError: When the feed result is structurally
+                violating.
+            ValueError: When ``sent`` is malformed for this decoder -- a
+                caller bug, deliberately stdlib.
+        """
+        sent_body, sent_params, results_limit = _params_from_body(sent, 'feed')
+        feed = validated_envelope_slice(_GeotabFeedEnvelope, envelope).result
+        if len(feed.data) < results_limit:
+            # The terminal page still carries the resume point.
+            return DecodedPage(
+                records=feed.data,
+                advance=PageAdvance(next_spec=None, durable_progress=feed.to_version),
+            )
+        # Advance by cursor: fromVersion replaces search. A full page
+        # whose toVersion equals the version it was asked from cannot
+        # advance -- continuing would refetch the identical page forever
+        # (unbounded duplicate growth at the append cell), so the
+        # forward-progress violation is surfaced loudly instead. Never
+        # observed live (probed full pages always advanced); the guard
+        # exists for wedged providers and replaying proxies.
+        if feed.to_version == sent_params.get(_FROM_VERSION_KEY):
+            raise ProviderResponseError(
+                detail=(
+                    f'GetFeed returned a full page without advancing '
+                    f'toVersion ({feed.to_version!r}) -- a stalled feed '
+                    f'would loop forever'
+                )
+            )
+        next_params: dict[str, JsonValue] = {
+            param_name: param_value
+            for param_name, param_value in sent_params.items()
+            if param_name != _SEARCH_KEY
+        }
+        next_params[_FROM_VERSION_KEY] = feed.to_version
+        next_body: dict[str, JsonValue] = {**sent_body, _PARAMS_KEY: next_params}
+        return DecodedPage(
+            records=feed.data,
+            advance=PageAdvance(
+                next_spec=sent.with_json_body(next_body),
+                durable_progress=feed.to_version,
+            ),
+        )
+
+
+class _GeotabGetEnvelope(StrictEnvelopeSlice):
+    """Envelope slice: ``Get`` returns records as a plain top-level list."""
+
+    result: list[JsonObject]
+
+
+def _sort_from_params(sent_params: Mapping[str, JsonValue]) -> Mapping[str, JsonValue]:
+    """Locate the Get request's ``sort`` mapping; its absence is a caller bug.
+
+    Args:
+        sent_params: The sent body's ``params`` mapping.
+
+    Returns:
+        The ``sort`` mapping the advance rewrites.
+
+    Raises:
+        ValueError: When ``sort`` is missing or not a mapping.
+    """
+    sort_value: JsonValue = sent_params.get(_SORT_KEY)
+    if not isinstance(sort_value, Mapping):
+        raise ValueError(
+            f'GeoTab Get request params must carry a {_SORT_KEY!r} mapping'
+        )
+    return sort_value
+
+
+def _last_record_id(records: list[JsonObject]) -> str:
+    """The last returned record's ``id`` -- the next page's seek offset.
+
+    Args:
+        records: The page's records, non-empty.
+
+    Returns:
+        The trailing record's string ``id``.
+
+    Raises:
+        ProviderResponseError: When the trailing record lacks a string
+            ``id`` -- provider data violating the seek contract, not a
+            caller bug.
+    """
+    last_id: JsonValue = records[-1].get(_ID_KEY)
+    if not isinstance(last_id, str):
+        raise ProviderResponseError(
+            detail=(
+                f'GeoTab Get seek paging requires a string {_ID_KEY!r} on '
+                f'every record; the last record of the page carries '
+                f'{type(last_id).__name__}'
+            )
+        )
+    return last_id
+
+
+@dataclass(frozen=True, slots=True)
+class GeotabGetPageDecoder:
+    """Decode plain ``Get`` pages and advance by id-sorted seek offset.
+
+    Plain ``Get`` silently hard-caps at 5,000 records with no
+    continuation signal (captured 2026-07-09), so the walk seeks: the
+    spec builder's first request sorts by ``id`` ascending with an
+    explicit null ``offset``, and each advance sets ``sort.offset`` to
+    the last returned record's ``id``. Termination is the EMPTY result
+    list only -- a short page still advances (unlike the feed rule),
+    because the cap makes page fullness meaningless as a completion
+    signal. ``lastId`` is never written, by construction: the probe
+    bodies carried ``"lastId": null`` (tolerated), but the settled
+    decision (DESIGN section 8, decision 1) is to never send the key --
+    the docs name it an ``ArgumentException`` beside id-sort.
+
+    No configuration fields: ``resultsLimit`` lives only in the sent
+    body, so decoder-versus-endpoint divergence is structurally
+    impossible (the feed precedent).
+    """
+
+    def first_request(self, spec: RequestSpec) -> RequestSpec:
+        """Return the spec unchanged.
+
+        The base spec already carries ``resultsLimit`` and the initial
+        ``sort`` (``sortBy: id``, explicit null ``offset``) -- the spec
+        builder's concern, not the decoder's.
+        """
+        return spec
+
+    def decode_page(self, sent: RequestSpec, envelope: JsonValue) -> DecodedPage:
+        """Extract the page's records and compute the seek verdict.
+
+        Args:
+            sent: The spec that produced this page; its body's ``sort``
+                seeds the next page's offset.
+            envelope: The parsed response body.
+
+        Returns:
+            The page's records and the verdict: an empty page
+            terminates; any records advance with ``sort.offset`` set to
+            the last record's ``id``. ``durable_progress`` is always
+            ``None`` -- the seek offset is fetch-private, never a resume
+            cursor.
+
+        Raises:
+            ProviderResponseError: When the envelope is structurally
+                violating, or a record lacks the string ``id`` the seek
+                contract stands on.
+            ValueError: When ``sent`` is malformed for this decoder -- a
+                caller bug, deliberately stdlib.
+        """
+        sent_body, sent_params, _results_limit = _params_from_body(sent, 'Get')
+        sent_sort = _sort_from_params(sent_params)
+        records = validated_envelope_slice(_GeotabGetEnvelope, envelope).result
+        if not records:
+            return DecodedPage(
+                records=[],
+                advance=PageAdvance(next_spec=None, durable_progress=None),
+            )
+        next_sort: dict[str, JsonValue] = {
+            **sent_sort,
+            _OFFSET_KEY: _last_record_id(records),
+        }
+        next_params: dict[str, JsonValue] = {**sent_params, _SORT_KEY: next_sort}
+        next_body: dict[str, JsonValue] = {**sent_body, _PARAMS_KEY: next_params}
+        return DecodedPage(
+            records=records,
+            advance=PageAdvance(
+                next_spec=sent.with_json_body(next_body),
+                durable_progress=None,
+            ),
+        )

fleetpull/network/decoders/motive.py

@@ -0,0 +1,204 @@
+# src/fleetpull/network/decoders/motive.py
+"""Motive page decoders: wrapped-list records, paginated and single-page
+(sources: scrubbed provider-behavior verification, June 2026).
+
+Records arrive as a list of single-key wrappers under a per-endpoint
+top-level key -- ``{"vehicles": [{"vehicle": {...}}, ...]}`` -- and the
+``pagination`` block carries ``page_no``/``per_page``/``total``. Decoder
+logic deliberately resembles its siblings without sharing code:
+provider decoders evolve independently (blast-radius over DRY). WITHIN
+this module the wrapped-list extraction and the offset-page verdict are
+each written once (``_unwrap_wrapped_list`` / ``_offset_page_advance``)
+and shared by every decoder that speaks them.
+
+The window-stamping report composition for the utilization rollup
+surfaces (``MotiveWindowReportPageDecoder``) lives in
+``motive_reports.py``, delegating to this module's wrapped-list decoder.
+"""
+
+from dataclasses import dataclass
+from typing import Final
+
+from fleetpull.network.contract import (
+    DecodedPage,
+    PageAdvance,
+    RequestSpec,
+    StrictEnvelopeSlice,
+    require_record_list,
+    unwrap_record_objects,
+    validated_envelope_slice,
+)
+from fleetpull.vocabulary import JsonObject, JsonValue
+
+__all__: list[str] = [
+    'MotiveWrappedListPageDecoder',
+    'MotiveWrappedSinglePageDecoder',
+]
+
+# Wire-protocol tokens: Final constants, not an enum -- nothing
+# dispatches over these. Per-provider and deliberately unshared.
+_PAGE_NO_PARAM: Final[str] = 'page_no'
+_PER_PAGE_PARAM: Final[str] = 'per_page'
+
+
+class _MotivePageEcho(StrictEnvelopeSlice):
+    """The pagination block Motive returns on every page."""
+
+    page_no: int
+    per_page: int
+    total: int
+
+
+class _MotiveEnvelope(StrictEnvelopeSlice):
+    """Envelope slice: locates the echo; the record key is ignored."""
+
+    pagination: _MotivePageEcho
+
+
+def _unwrap_wrapped_list(
+    envelope: JsonValue, list_key: str, item_key: str
+) -> list[JsonObject]:
+    """Extract and unwrap one page's wrapped-list records.
+
+    The one Motive record-bearing shape, written once for the decoders
+    in this module (a same-file extraction, not a cross-provider
+    abstraction): the wrapper list under ``list_key``, each wrapper's
+    record under ``item_key``.
+
+    Args:
+        envelope: The parsed response body.
+        list_key: The top-level key holding the wrapper list.
+        item_key: The key inside each wrapper holding the record.
+
+    Returns:
+        The unwrapped record objects.
+
+    Raises:
+        ProviderResponseError: The record-bearing shape is structurally
+            violating (missing list key, non-list value, missing item
+            key, or a non-object record).
+    """
+    wrappers = require_record_list(envelope, list_key)
+    return unwrap_record_objects(wrappers, item_key)
+
+
+def _offset_page_advance(sent: RequestSpec, envelope: JsonValue) -> PageAdvance:
+    """Compute one page's offset verdict from its ``pagination`` echo.
+
+    The one page-numbered cursor contract every paginated Motive walk
+    shares, written once for the decoders in this module: terminal when
+    ``page_no * per_page >= total``; otherwise ``page_no + 1`` at the
+    echoed size merges onto the SENT spec, so every first-request
+    parameter (a window, a fixed selector) persists across the whole
+    walk. ``durable_progress`` is always ``None`` -- Motive offsets are
+    fetch-private.
+
+    Args:
+        sent: The spec that produced this page.
+        envelope: The parsed response body.
+
+    Returns:
+        The page's pagination verdict.
+
+    Raises:
+        ProviderResponseError: The ``pagination`` block is structurally
+            violating.
+    """
+    echo = validated_envelope_slice(_MotiveEnvelope, envelope).pagination
+    if echo.page_no * echo.per_page >= echo.total:
+        return PageAdvance(next_spec=None, durable_progress=None)
+    next_spec = sent.with_merged_params(
+        {
+            _PAGE_NO_PARAM: str(echo.page_no + 1),
+            _PER_PAGE_PARAM: str(echo.per_page),
+        }
+    )
+    return PageAdvance(next_spec=next_spec, durable_progress=None)
+
+
+@dataclass(frozen=True, slots=True)
+class MotiveWrappedListPageDecoder:
+    """Decode Motive's wrapped-list pages and page-numbered cursor.
+
+    Attributes:
+        list_key: The top-level key holding the wrapper list.
+        item_key: The key inside each wrapper holding the record.
+        per_page: The page size sent on the first request.
+    """
+
+    list_key: str
+    item_key: str
+    per_page: int
+
+    def first_request(self, spec: RequestSpec) -> RequestSpec:
+        """Send page one with ``page_no=1`` and the configured size."""
+        return spec.with_merged_params(
+            {_PAGE_NO_PARAM: '1', _PER_PAGE_PARAM: str(self.per_page)}
+        )
+
+    def decode_page(self, sent: RequestSpec, envelope: JsonValue) -> DecodedPage:
+        """Extract the wrapped records and compute the page verdict.
+
+        Args:
+            sent: The spec that produced this page.
+            envelope: The parsed response body.
+
+        Returns:
+            The unwrapped records and the pagination verdict.
+
+        Raises:
+            ProviderResponseError: When the record-bearing shape or the
+                pagination block is structurally violating.
+        """
+        records = _unwrap_wrapped_list(envelope, self.list_key, self.item_key)
+        return DecodedPage(
+            records=records, advance=_offset_page_advance(sent, envelope)
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class MotiveWrappedSinglePageDecoder:
+    """Decode a single unpaginated page of Motive's wrapped-list records.
+
+    The non-paginated sibling of ``MotiveWrappedListPageDecoder``: the same
+    wrapped-list shape (a list of single-key wrappers under ``list_key``, each
+    holding the record under ``item_key``), but the endpoint returns one page and
+    no ``pagination`` block, so the first request is the base spec unchanged and
+    every page is terminal. ``SinglePageDecoder`` does not fit -- it reads a
+    top-level record list and never strips the per-item wrapper.
+
+    Attributes:
+        list_key: The top-level key holding the wrapper list.
+        item_key: The key inside each wrapper holding the record.
+    """
+
+    list_key: str
+    item_key: str
+
+    def first_request(self, spec: RequestSpec) -> RequestSpec:
+        """Return the base spec unchanged -- the endpoint is unpaginated."""
+        return spec
+
+    def decode_page(self, sent: RequestSpec, envelope: JsonValue) -> DecodedPage:
+        """Unwrap the wrapped records; the page is always terminal.
+
+        Args:
+            sent: The spec that produced this page (unused; no continuation).
+            envelope: The parsed response body.
+
+        Returns:
+            The unwrapped records and a terminal verdict.
+
+        Raises:
+            ProviderResponseError: When the record-bearing shape is structurally
+                violating (missing list key, non-list value, missing item key, or
+                a non-object record).
+
+        Side Effects:
+            None.
+        """
+        records = _unwrap_wrapped_list(envelope, self.list_key, self.item_key)
+        return DecodedPage(
+            records=records,
+            advance=PageAdvance(next_spec=None, durable_progress=None),
+        )

fleetpull/network/decoders/motive_reports.py

@@ -0,0 +1,114 @@
+# src/fleetpull/network/decoders/motive_reports.py
+"""The Motive window-report decoder family: the utilization rollup surfaces.
+
+``MotiveWindowReportPageDecoder`` decodes the utilization rollup surfaces
+(``/v2/vehicle_utilization``, ``/v2/driver_utilization``; probe-settled
+2026-07-21, DESIGN section 8), whose rows carry NO event-time key of any kind
+-- each row is the provider's rollup over exactly the requested window, so the
+decoder stamps every unwrapped record with the window the SENT spec asked for.
+Envelope extraction and pagination are the sibling wrapped-list decoder's
+(``motive.py``), composed by delegation; the window stamp is the shared
+provider-uniform vocabulary (``_window_stamp.py``).
+"""
+
+from dataclasses import dataclass
+from typing import Final
+
+from fleetpull.network.contract import DecodedPage, RequestSpec
+from fleetpull.network.decoders._window_stamp import window_stamp_from_sent_spec
+from fleetpull.network.decoders.motive import MotiveWrappedListPageDecoder
+from fleetpull.vocabulary import JsonValue
+
+__all__: list[str] = ['MotiveWindowReportPageDecoder']
+
+# The utilization report surfaces' window wire params (2026-07-21
+# capture): the day-granular date-label pair every windowed Motive
+# surface takes, inclusive on both ends and interpreted on COMPANY-LOCAL
+# day boundaries on these surfaces. The shared window-stamp helper
+# (`_window_stamp.py`) reads them back off the SENT spec to stamp each
+# rollup row with the provider-uniform synthesized keys.
+_WINDOW_START_PARAM: Final[str] = 'start_date'
+_WINDOW_END_PARAM: Final[str] = 'end_date'
+
+
+@dataclass(frozen=True, slots=True)
+class MotiveWindowReportPageDecoder:
+    """Decode window-grain rollup pages into window-stamped records.
+
+    The decoder for ``GET /v2/vehicle_utilization`` and
+    ``GET /v2/driver_utilization`` (probe-settled 2026-07-21, DESIGN
+    section 8): the standard Motive wrapped-list envelope and
+    page-numbered cursor -- composed by DELEGATION to an inner
+    ``MotiveWrappedListPageDecoder`` (the Samsara series-decoder
+    pattern), which handles ``first_request`` and the whole
+    extraction-and-verdict pass verbatim -- plus
+    the window-grain difference the Samsara fuel-energy pair
+    established, applied to the inner page's records:
+
+    **The rollup grain is the request window.** Rows carry NO date or
+    time identity of any kind; each row is the provider's aggregate over
+    exactly the requested inclusive ``start_date``/``end_date`` label
+    pair (a 1-day and a 6-day request each returned one rollup row per
+    entity). So the decoder stamps every unwrapped record with the
+    synthesized ``windowStartDate``/``windowEndDate`` keys, copied
+    verbatim from the SENT spec's own ``start_date``/``end_date`` params
+    -- the shared window-stamp vocabulary (``_window_stamp.py``),
+    sourced from the sent spec rather than the record. The stamp wins
+    any (census-impossible) key collision: it is the row's REQUIRED time
+    identity, and a colliding future wire key must never silently
+    supplant what was actually asked of the provider. A sent spec
+    lacking either param raises loudly -- a wiring bug surfaced, never
+    silently unstamped rows.
+
+    Attributes:
+        list_key: The top-level key holding the wrapper list
+            (``'vehicle_utilizations'`` / ``'driver_idle_rollups'``).
+        item_key: The key inside each wrapper holding the record
+            (``'vehicle_utilization'`` / ``'driver_idle_rollup'``).
+        per_page: The page size sent on the first request.
+    """
+
+    list_key: str
+    item_key: str
+    per_page: int
+
+    def _list_decoder(self) -> MotiveWrappedListPageDecoder:
+        """The inner wrapped-list decoder extraction and pagination delegate to."""
+        return MotiveWrappedListPageDecoder(
+            list_key=self.list_key, item_key=self.item_key, per_page=self.per_page
+        )
+
+    def first_request(self, spec: RequestSpec) -> RequestSpec:
+        """Delegate page one verbatim to the inner wrapped-list decoder.
+
+        The offset advance merges onto the sent spec, so the builder's
+        ``start_date``/``end_date`` window persists across every page --
+        and with it, the stamp.
+        """
+        return self._list_decoder().first_request(spec)
+
+    def decode_page(self, sent: RequestSpec, envelope: JsonValue) -> DecodedPage:
+        """Stamp the inner page's unwrapped records with the sent window.
+
+        Args:
+            sent: The spec that produced this page.
+            envelope: The parsed response body.
+
+        Returns:
+            One record per rollup row, each carrying the synthesized
+            ``windowStartDate``/``windowEndDate`` keys (class
+            docstring); the pagination advance passes through the inner
+            decoder untouched.
+
+        Raises:
+            ProviderResponseError: The sent spec lacks a window param
+                (a wiring bug -- never silently unstamped rows), the
+                record-bearing shape is structurally violating, or the
+                pagination block is.
+        """
+        window_stamp = window_stamp_from_sent_spec(
+            sent, start_param=_WINDOW_START_PARAM, end_param=_WINDOW_END_PARAM
+        )
+        inner_page = self._list_decoder().decode_page(sent, envelope)
+        stamped = [{**record, **window_stamp} for record in inner_page.records]
+        return DecodedPage(records=stamped, advance=inner_page.advance)