fleetpull 0.1.0__py3-none-any.whl

fleetpull/models/geotab/fuel_and_energy_used.py

@@ -0,0 +1,81 @@
+# src/fleetpull/models/geotab/fuel_and_energy_used.py
+"""GeoTab FuelAndEnergyUsed response model (``GetFeed`` on that ``typeName``).
+
+Written from the 2026-07-21 live probe session, never from docs. A
+FuelAndEnergyUsed record is one provider-calculated per-trip fuel/energy
+usage total — a CALCULATED feed: past records re-emit under a higher
+``version`` on reprocessing, stored as emitted and reconciled by
+``(id, max version)`` (DESIGN §4).
+
+``FuelUsed`` is NOT ported: on the probed tenant it was observed
+IDENTICAL to this surface (same ids, same values, week-wide), and the
+provider documents this type as its successor — porting both would ship
+one dataset twice (DESIGN §8).
+
+THE ESTIMATES-ONLY-TENANT CAVEAT (DESIGN §8): the probed tenant has NO
+fuel-transaction (fuel-card) integration, so every fuel value on this
+surface is provider-derived from telemetry — estimates, not
+transactions. The census cannot speak for integrated tenants.
+
+Requiredness posture: the census is a large uniform whole-page total —
+2,000/2,000 records carried every key — so every field is required with
+no nullable arm (none was observed). The census is a TENANT-SCOPED
+observation. ``confidence`` observed ``'None'`` on 1,994/2,000 and
+``'FuelUsedInconsistent'`` on 6 — census-open, a plain str. Mixed
+int-or-float wire numerics (``totalFuelUsed``,
+``totalIdlingFuelUsedL``) are modeled ``float``; ``dateTime`` (the
+event time) is recovered tz-aware by validation, the GeoTab sibling
+idiom.
+"""
+
+from datetime import datetime
+
+from pydantic import ConfigDict
+from pydantic.alias_generators import to_camel
+
+from fleetpull.model_contract import ResponseModel
+
+__all__: list[str] = ['FuelAndEnergyUsed', 'FuelAndEnergyUsedDeviceRef']
+
+
+class FuelAndEnergyUsedDeviceRef(ResponseModel):
+    """The usage record's device reference: the id alone, on every record."""
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    id: str
+
+
+class FuelAndEnergyUsed(ResponseModel):
+    """One GeoTab per-trip fuel/energy usage total.
+
+    A pure mirror of the 2,000/2,000 whole-page census: seven keys, all
+    present and non-null on every record, so all seven are required.
+    The estimates-only-tenant caveat and the ``FuelUsed`` non-port are
+    the module docstring's.
+
+    Attributes:
+        confidence: The provider's confidence token — ``'None'`` on
+            nearly every census record, ``'FuelUsedInconsistent'`` on
+            the rest (census-open plain str).
+        date_time: The usage total's UTC instant — the endpoint's event
+            time.
+        device: The vehicle unit's reference.
+        id: GeoTab's record id.
+        total_fuel_used: Fuel used over the covered trip, liters (the wire key totalIdlingFuelUsedL's own L suffix -- unit evidence on the wire, not a docs assumption) (mixed
+            int-or-float on the wire, modeled float).
+        total_idling_fuel_used_l: Idling fuel used over the covered
+            trip, liters (mixed int-or-float, modeled float).
+        version: The record's version token — the calculated-feed
+            reconcile key beside ``id``.
+    """
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    confidence: str
+    date_time: datetime
+    device: FuelAndEnergyUsedDeviceRef
+    id: str
+    total_fuel_used: float
+    total_idling_fuel_used_l: float
+    version: str

fleetpull/models/geotab/fuel_tax_detail.py

@@ -0,0 +1,150 @@
+# src/fleetpull/models/geotab/fuel_tax_detail.py
+"""GeoTab FuelTaxDetail response model (``GetFeed`` on ``typeName: FuelTaxDetail``).
+
+Written from the 2026-07-21 live probe session, never from docs. A
+FuelTaxDetail is one provider-calculated IFTA jurisdiction segment — a
+vehicle's continuous travel within one jurisdiction, bracketed by its
+enter/exit instants and odometer readings — a CALCULATED feed, stored as
+emitted (DESIGN §4). Its version identity is a LIST: ``versions``
+carries 16-hex component version tokens (mirrored ``list[str]``, a
+§9-supported list-of-scalar) rather than the single ``version`` its
+feed siblings carry — the consumer's ``(id, max version)`` reconcile
+reads the re-emitted row's whole token list as the fresher edition.
+
+THE ESTIMATES-ONLY-TENANT CAVEAT (DESIGN §8): the probed tenant has NO
+fuel-transaction (fuel-card) integration, so every fuel value on this
+surface is provider-derived from telemetry — estimates, not
+transactions. The census cannot speak for integrated tenants.
+
+Requiredness posture: the census is a uniform whole-page total — every
+key present on all sampled records (100-300 per key across the probed
+pages) — so every field is required, with the arms exactly as observed:
+
+- ``driver`` arrives as either the object reference or the bare
+  ``"UnknownDriverId"`` sentinel string; the shared
+  ``bare_id_to_reference`` coercion (the shipped Trip mechanism) lifts
+  the bare form to ``{"id": <string>}``, so ``is_driver`` is null
+  exactly on sentinel rows.
+- The hourly arrays (``hourlyGpsOdometer``, ``hourlyLatitude``, and
+  kin) may be EMPTY lists — present on every record, sometimes with no
+  elements (``hasHourlyData`` false) — mirrored as list-of-scalar
+  fields, never demoted to nullable.
+
+``enterTime`` (the event time — the segment materializes where it
+begins) and ``exitTime`` are recovered tz-aware by validation, the
+GeoTab sibling idiom. Mixed int-or-float wire numerics
+(``enterOdometer``, ``exitOdometer``, the ``hourlyOdometer`` elements)
+are modeled ``float``. ``authority`` and ``jurisdiction`` are
+census-scoped open vocabularies — plain strs, never enums.
+"""
+
+from datetime import datetime
+from typing import Annotated
+
+from pydantic import BeforeValidator, ConfigDict
+from pydantic.alias_generators import to_camel
+
+from fleetpull.model_contract import ResponseModel
+from fleetpull.models.geotab.shared import bare_id_to_reference
+
+__all__: list[str] = [
+    'FuelTaxDetail',
+    'FuelTaxDetailDeviceRef',
+    'FuelTaxDetailDriverRef',
+]
+
+
+class FuelTaxDetailDeviceRef(ResponseModel):
+    """The segment's device reference: the id alone, on every record."""
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    id: str
+
+
+class FuelTaxDetailDriverRef(ResponseModel):
+    """The segment's driver reference.
+
+    Arrives as an object or the bare ``"UnknownDriverId"`` sentinel
+    string; the ``FuelTaxDetail.driver`` field's coercion lifts the
+    bare form to ``{"id": <string>}``, so ``is_driver`` is null exactly
+    on sentinel rows.
+    """
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    id: str
+    is_driver: bool | None = None
+
+
+class FuelTaxDetail(ResponseModel):
+    """One GeoTab IFTA jurisdiction segment.
+
+    A pure mirror of the whole-page census: every modeled key present on
+    every record, so everything is required; the observed arms (the
+    ``driver`` string-or-object sentinel, the possibly-empty hourly
+    arrays) are the module docstring's.
+
+    Attributes:
+        authority: The taxing authority token (census-open plain str).
+        device: The vehicle unit's reference.
+        driver: The driver reference; the bare ``"UnknownDriverId"``
+            sentinel lands as ``driver.id`` verbatim.
+        enter_gps_odometer: The GPS-derived odometer at segment entry.
+        enter_latitude: Latitude at segment entry.
+        enter_longitude: Longitude at segment entry.
+        enter_odometer: The odometer at segment entry.
+        enter_time: Segment entry (UTC) — the endpoint's event time.
+        exit_gps_odometer: The GPS-derived odometer at segment exit.
+        exit_latitude: Latitude at segment exit.
+        exit_longitude: Longitude at segment exit.
+        exit_odometer: The odometer at segment exit.
+        exit_time: Segment exit (UTC).
+        has_hourly_data: Whether the hourly arrays carry elements.
+        hourly_gps_odometer: Per-hour GPS-derived odometer readings
+            (may be empty).
+        hourly_is_odometer_interpolated: Per-hour interpolation flags
+            (may be empty).
+        hourly_latitude: Per-hour latitudes (may be empty).
+        hourly_longitude: Per-hour longitudes (may be empty).
+        hourly_odometer: Per-hour odometer readings (may be empty).
+        id: GeoTab's record id.
+        is_cluster_odometer: Whether the odometer is cluster-sourced.
+        is_enter_odometer_interpolated: Whether the entry odometer is
+            interpolated.
+        is_exit_odometer_interpolated: Whether the exit odometer is
+            interpolated.
+        is_negligible: The provider's negligible-segment flag.
+        jurisdiction: The jurisdiction token (census-open plain str).
+        versions: The 16-hex component version tokens — this type's
+            list-shaped version identity (the module docstring).
+    """
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    authority: str
+    device: FuelTaxDetailDeviceRef
+    driver: Annotated[FuelTaxDetailDriverRef, BeforeValidator(bare_id_to_reference)]
+    enter_gps_odometer: float
+    enter_latitude: float
+    enter_longitude: float
+    enter_odometer: float
+    enter_time: datetime
+    exit_gps_odometer: float
+    exit_latitude: float
+    exit_longitude: float
+    exit_odometer: float
+    exit_time: datetime
+    has_hourly_data: bool
+    hourly_gps_odometer: list[float]
+    hourly_is_odometer_interpolated: list[bool]
+    hourly_latitude: list[float]
+    hourly_longitude: list[float]
+    hourly_odometer: list[float]
+    id: str
+    is_cluster_odometer: bool
+    is_enter_odometer_interpolated: bool
+    is_exit_odometer_interpolated: bool
+    is_negligible: bool
+    jurisdiction: str
+    versions: list[str]

fleetpull/models/geotab/log_record.py

@@ -0,0 +1,68 @@
+# src/fleetpull/models/geotab/log_record.py
+"""GeoTab LogRecord response model (``GetFeed`` on ``typeName: LogRecord``).
+
+Written from the 2026-07-21 live probe session, never from docs. A
+LogRecord is one GPS reading from a device's telemetry stream — the
+ACTIVE feed archetype: records are emitted once, never re-emitted, and
+carry NO per-record ``version`` (unlike every calculated feed and unlike
+the otherwise-parallel ``StatusData``), so append-only storage is
+trivially complete and the consumer reconciles by ``id`` alone
+(DESIGN §4).
+
+Requiredness posture: the census is a large uniform whole-page total —
+2,000/2,000 records carried every key — so every field is required with
+no nullable arm (none was observed). The census is a TENANT-SCOPED
+observation (DESIGN §8): it proves this tenant's shapes at capture time,
+never other tenants'. Volume on the probed tenant exceeds 50,000
+records/day (a 50,000-record page did not cover one day), which is why
+the leaf declares the 50,000 protocol-maximum ``resultsLimit``.
+
+``dateTime`` (the event time) arrives as an RFC3339 ``Z`` string and is
+recovered tz-aware by validation, the GeoTab sibling idiom; ``speed`` is
+a bare int on all 2,000 census records and is mirrored verbatim (the
+odometer_readings bare-int precedent — an integral wire value is not
+widened speculatively).
+"""
+
+from datetime import datetime
+
+from pydantic import ConfigDict
+from pydantic.alias_generators import to_camel
+
+from fleetpull.model_contract import ResponseModel
+
+__all__: list[str] = ['LogRecord', 'LogRecordDeviceRef']
+
+
+class LogRecordDeviceRef(ResponseModel):
+    """The reading's device reference: the id alone, on every record."""
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    id: str
+
+
+class LogRecord(ResponseModel):
+    """One GeoTab GPS reading from the LogRecord feed.
+
+    A pure mirror of the 2,000/2,000 whole-page census: six keys, all
+    present and non-null on every record, so all six are required.
+
+    Attributes:
+        date_time: The reading's UTC instant — the endpoint's event time.
+        device: The emitting vehicle unit's reference.
+        id: GeoTab's record id (ids and feed versions share one counter
+            space — DESIGN §8).
+        latitude: GPS latitude in decimal degrees.
+        longitude: GPS longitude in decimal degrees.
+        speed: Speed in km/h (the provider speed-unit settlement: the Trip delta-arithmetic check, DESIGN section 8, 2026-07-13 -- same provider telemetry family, not a docs assumption) — a bare int on the wire, mirrored verbatim.
+    """
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    date_time: datetime
+    device: LogRecordDeviceRef
+    id: str
+    latitude: float
+    longitude: float
+    speed: int

fleetpull/models/geotab/media_file.py

@@ -0,0 +1,133 @@
+# src/fleetpull/models/geotab/media_file.py
+"""GeoTab MediaFile response model (``GetFeed`` on ``typeName: MediaFile``).
+
+Written from the 2026-07-21 feed wave three SCALE census (walked at
+scale at the probed tenant), never from docs. A MediaFile is one media
+attachment (image, video, ...) captured by a device or driver — a
+versioned feed, so re-emission under newer ``version`` tokens is
+expected and the consumer reconciles by ``(id, max version)``
+(DESIGN §4).
+
+THIN EVIDENCE CAVEAT: only 55 records over a 730-day window at this
+tenant — genuinely thin data. The model is conservative accordingly;
+every arm below is what those 55 records showed, and the census cannot
+speak for a tenant that uses media at volume.
+
+NO ``dateTime`` key — the event time is ``fromDate`` (the media start,
+55/55), so the binding anchors ``event_time_column='from_date'`` and
+``from_date`` is a REQUIRED datetime (storage partitions on it).
+
+Requiredness posture (the wave-two conservative stance, DESIGN §8):
+structural requiredness is limited to the record identity — ``id``,
+``fromDate`` (the event time), and ``version`` — and every other field
+is optional. Both ``device`` and ``driver`` are OPTIONAL: a media
+file's primary entity is ambiguous — it may attach to a device or a
+driver — so neither is promoted to a required primary ref. The observed
+arms and exclusions:
+
+- ``device`` is PROVEN MIXED object-or-string (42 string / 13 object at
+  scale); ``driver`` was string-only observed (55/55). Both ride the
+  shared ``bare_id_to_reference`` lift, so both land as ``*__id`` —
+  the mixed ``device`` because the census proved both arms, the
+  string-only ``driver`` defensively (the census-scope lesson: a
+  tenant census cannot prove the object arm absent either).
+- THREE DOCUMENTED EXCLUSIONS (the ``defectList.children`` doctrine,
+  DESIGN §8): ``metaData`` (empty object on all 55), ``tags`` (empty
+  list on all 55), and ``thumbnails`` (empty list on all 55). Their
+  element/content shape is unobservable at this tenant, the records
+  layer supports only observable shapes, and ``extra='ignore'`` absorbs
+  them wire-side (pinned: a record populating any of the three still
+  validates). REVISIT when a tenant populates them: capture the shape
+  and model it then.
+
+``fromDate`` and ``toDate`` are recovered tz-aware by validation, the
+GeoTab sibling idiom. ``mediaType``, ``name``, ``solutionId``, and
+``status`` are census-open strings.
+"""
+
+from datetime import datetime
+from typing import Annotated
+
+from pydantic import BeforeValidator, ConfigDict
+from pydantic.alias_generators import to_camel
+
+from fleetpull.model_contract import ResponseModel
+from fleetpull.models.geotab.shared import bare_id_to_reference
+
+__all__: list[str] = [
+    'MediaFile',
+    'MediaFileDeviceRef',
+    'MediaFileDriverRef',
+]
+
+
+class MediaFileDeviceRef(ResponseModel):
+    """The capturing device's reference.
+
+    PROVEN mixed on this census (42 bare-string / 13 ``{id}`` object);
+    the shared coercion lifts the bare form to ``{"id": <string>}``, so
+    both arms land as ``device__id``.
+    """
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    id: str
+
+
+class MediaFileDriverRef(ResponseModel):
+    """The capturing driver's reference.
+
+    String-only observed at scale (55/55 bare strings); the shared
+    coercion lifts the bare form, and an unobserved object arm would
+    pass through defensively (the census-scope lesson). Both arms land
+    as ``driver__id``.
+    """
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    id: str
+
+
+class MediaFile(ResponseModel):
+    """One GeoTab media attachment from the MediaFile feed.
+
+    The wave-two conservative mirror on thin evidence (the module
+    docstring's posture): ``id`` / ``from_date`` / ``version`` required,
+    both refs and everything else optional; ``metaData`` / ``tags`` /
+    ``thumbnails`` documented-excluded.
+
+    Attributes:
+        device: The capturing device's reference — proven
+            object-or-string, both arms landing as ``device__id``.
+            Optional (the ambiguous-primary-entity choice).
+        driver: The capturing driver's reference (string-only observed;
+            defensively lifted). Optional (the ambiguous-primary-entity
+            choice).
+        from_date: The media's UTC start — the endpoint's event time (in
+            place of the absent ``dateTime``).
+        id: GeoTab's record id.
+        media_type: The media type token (census-open str).
+        name: The media file name (census-open str).
+        solution_id: The originating solution id (census-open str).
+        status: The media status token (census-open str).
+        to_date: The media's UTC end.
+        version: The record's version token — the reconcile key beside
+            ``id``.
+    """
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    device: Annotated[
+        MediaFileDeviceRef | None, BeforeValidator(bare_id_to_reference)
+    ] = None
+    driver: Annotated[
+        MediaFileDriverRef | None, BeforeValidator(bare_id_to_reference)
+    ] = None
+    from_date: datetime
+    id: str
+    media_type: str | None = None
+    name: str | None = None
+    solution_id: str | None = None
+    status: str | None = None
+    to_date: datetime | None = None
+    version: str

fleetpull/models/geotab/shared.py

@@ -0,0 +1,221 @@
+# src/fleetpull/models/geotab/shared.py
+"""Shared GeoTab boundary-model machinery: TimeSpan parsing, reference
+coercion, and the nested-location model trio.
+
+GeoTab serializes every duration as a .NET TimeSpan string
+(``[d.]hh:mm:ss[.f{1,7}]`` -- captured 2026-07-13: ``"00:05:01"``,
+``"00:03:42.3630000"``, ``"4.16:41:16"``, ``"21:04:17"``), and reference
+fields may arrive as either a bare known-id sentinel string
+(``"UnknownDriverId"``) or an object (``{"id": ..., "isDriver": true}``).
+Both shapes are structural wire facts shared across many GeoTab entities
+(any model with a duration or a reference field), so their coercions
+live here beside each other, consumed through ``Annotated`` field
+aliases -- never as per-model parsing logic. The consumer set is not
+enumerated here: it grows with every ported entity, so the list of
+importers (``grep`` for ``bare_id_to_reference`` / ``GeotabTimeSpan``)
+is the source of truth, not a snapshot that goes stale.
+
+The nested-location trio (``GeotabAddressedLocation`` wrapping an
+optional ``GeotabCoordinate`` and an optional ``GeotabPostalAddress``)
+is the third shared shape, consumed on ``DutyStatusLog`` and ``DVIRLog``
+-- two consumers at birth, so it lives here (the second-consumer
+threshold) rather than per-model. The wrapper carries the DOUBLE-NESTED
+``{location: {x, y}}`` COORDINATE arm OR an ``{address:
+{formattedAddress}}`` arm: the 2026-07-21 feed-wave-two census (nested
+blocks sampled at 200) saw only the coordinate arm, but a 24,860-block
+LIVE-PROOF walk (2026-07-21) found the wrapper carries the coordinate
+arm on 24,846 blocks and the address arm on 14 (mutually exclusive at
+that scale) -- the fourth time an at-scale walk found an arm a bounded
+census missed (the ``StatusData.controller`` lesson). Both arms are
+optional on the wrapper; a wrapper with neither is unobserved but
+representable.
+
+``GeotabTimeSpan`` deliberately bakes nullability into the alias
+(``Annotated[timedelta | None, ...]`` rather than
+``Annotated[timedelta, ...] | None``): Pydantic lifts ``Annotated``
+metadata into ``FieldInfo`` only when it is the annotation's top level,
+so this form is the one where the records field walk sees the bare
+``timedelta | None`` leaf it derives a ``Duration`` column from --
+union-nesting the ``Annotated`` would hide the leaf inside metadata the
+walk rejects. Every union-of-observed-fields model wants the
+nullability anyway.
+"""
+
+import re
+from datetime import timedelta
+from typing import Annotated, Final
+
+from pydantic import BeforeValidator, Field
+
+from fleetpull.model_contract import ResponseModel
+from fleetpull.vocabulary import JsonValue
+
+__all__: list[str] = [
+    'GeotabAddressedLocation',
+    'GeotabCoordinate',
+    'GeotabPostalAddress',
+    'GeotabTimeSpan',
+    'bare_id_to_reference',
+    'parse_timespan',
+]
+
+
+class GeotabCoordinate(ResponseModel):
+    """The inner coordinate block of a nested GeoTab location.
+
+    GeoTab's ``x`` is LONGITUDE and ``y`` is LATITUDE (the provider's
+    map-plane convention, consistent with the shipped ``FillUp``
+    location); both arrive as floats (bare-int arms lift losslessly
+    under lax coercion). Required within the block: a coordinate block
+    without its coordinates is a shape change and must fail loudly.
+    """
+
+    x: float
+    y: float
+
+
+class GeotabPostalAddress(ResponseModel):
+    """The inner address block of a nested GeoTab location.
+
+    The wrapper's address arm, observed only on ``DutyStatusLog`` in
+    the 24,860-block live-proof walk (14 blocks). Only
+    ``formattedAddress`` was observed on the block; other GeoTab
+    address keys (city, state, ...) are absorbed by ``extra='ignore'``
+    until a walk observes them. Required within the block on the same
+    loud-failure logic as the coordinates: a present address block
+    missing its one observed key is a shape change.
+    """
+
+    formatted_address: str = Field(alias='formattedAddress')
+
+
+class GeotabAddressedLocation(ResponseModel):
+    """The nested GeoTab location wrapper: a coordinate arm or an address arm.
+
+    Carries the double-nested ``{location: {x, y}}`` coordinate block
+    (``location``) OR the ``{address: {formattedAddress}}`` block
+    (``address``) -- both optional, mutually exclusive at the observed
+    scale (module docstring: the live-proof walk found 24,846
+    coordinate arms and 14 address arms, none carrying both). The
+    consuming models (``DutyStatusLog``, ``DVIRLog``) carry the wrapper
+    itself as an optional field.
+    """
+
+    location: GeotabCoordinate | None = None
+    address: GeotabPostalAddress | None = None
+
+
+# The .NET TimeSpan grammar: optional day prefix, exactly-two-digit
+# fields, 1-7 fractional digits (100 ns ticks). Range checks (hh <= 23,
+# mm/ss <= 59) are numeric, below -- a regex range would misread 29.
+_TIMESPAN_PATTERN: Final[re.Pattern[str]] = re.compile(
+    r'^(?:(?P<days>\d+)\.)?'
+    r'(?P<hours>\d{2}):(?P<minutes>\d{2}):(?P<seconds>\d{2})'
+    r'(?:\.(?P<ticks>\d{1,7}))?$'
+)
+
+_MAX_HOURS: Final[int] = 23
+_MAX_MINUTES: Final[int] = 59
+_MAX_SECONDS: Final[int] = 59
+
+# One microsecond is ten 100 ns ticks; a 7-digit fraction is a full
+# tick count, shorter fractions right-pad to it.
+_TICK_DIGITS: Final[int] = 7
+_TICKS_PER_MICROSECOND: Final[int] = 10
+
+
+def parse_timespan(value: str) -> timedelta:
+    """Parse a .NET TimeSpan string into a ``timedelta``.
+
+    Accepts exactly the grammar ``[d.]hh:mm:ss[.f{1,7}]`` -- a
+    non-negative day count, two-digit hours 00-23, two-digit minutes and
+    seconds 00-59, and 1-7 fractional digits of decimal seconds (100 ns
+    ticks, truncated to microseconds; every captured seventh digit is
+    zero, so no observed value loses precision). Anything else --
+    negative spans, malformed shapes, empty strings -- fails loudly: a
+    duration this parser has never seen should fail validation, not
+    pass mangled.
+
+    Args:
+        value: The wire TimeSpan string.
+
+    Returns:
+        The equivalent ``timedelta``.
+
+    Raises:
+        ValueError: ``value`` does not match the grammar or a field is
+            out of range; the message names the offending string.
+    """
+    match = _TIMESPAN_PATTERN.match(value)
+    if match is None:
+        raise ValueError(f'not a .NET TimeSpan string: {value!r}')
+    hours = int(match['hours'])
+    minutes = int(match['minutes'])
+    seconds = int(match['seconds'])
+    if hours > _MAX_HOURS or minutes > _MAX_MINUTES or seconds > _MAX_SECONDS:
+        raise ValueError(f'TimeSpan field out of range: {value!r}')
+    ticks_text = match['ticks']
+    microseconds = (
+        int(ticks_text.ljust(_TICK_DIGITS, '0')) // _TICKS_PER_MICROSECOND
+        if ticks_text is not None
+        else 0
+    )
+    return timedelta(
+        days=int(match['days'] or 0),
+        hours=hours,
+        minutes=minutes,
+        seconds=seconds,
+        microseconds=microseconds,
+    )
+
+
+def _coerce_timespan(value: JsonValue | timedelta) -> timedelta | None:
+    """The ``GeotabTimeSpan`` ingress: parse strings, pass parsed values.
+
+    Args:
+        value: The raw wire value, or an already-validated value on a
+            Pydantic revalidation path.
+
+    Returns:
+        ``None`` for ``None`` (the alias is nullable), a ``timedelta``
+        passthrough (idempotent validation), or the parsed string.
+
+    Raises:
+        ValueError: A string that is not a TimeSpan, or any other type.
+    """
+    if value is None:
+        return None
+    if isinstance(value, timedelta):
+        return value
+    if isinstance(value, str):
+        return parse_timespan(value)
+    raise ValueError(f'expected a .NET TimeSpan string, got {type(value).__name__}')
+
+
+# The duration field type every GeoTab model uses. Plain assignment, not
+# a `type` statement: Pydantic must evaluate the Annotated form eagerly
+# for the metadata lift the module docstring describes.
+GeotabTimeSpan = Annotated[timedelta | None, BeforeValidator(_coerce_timespan)]
+
+
+def bare_id_to_reference(value: JsonValue) -> JsonValue:
+    """Lift a bare reference-id string into the object form.
+
+    GeoTab reference fields carry either an object (``{"id": ...}``,
+    possibly with siblings) or a bare known-id sentinel string
+    (``"UnknownDriverId"``). This coercion is structural and
+    sentinel-agnostic: ANY bare string becomes ``{"id": <string>}``,
+    the string preserved verbatim, so the sentinel lands as the
+    reference's id and the object form passes through untouched.
+
+    Args:
+        value: The raw wire value of a reference field.
+
+    Returns:
+        ``{'id': value}`` for a bare string; ``value`` unchanged
+        otherwise (objects validate against the reference model, and
+        anything else fails there, loudly).
+    """
+    if isinstance(value, str):
+        return {'id': value}
+    return value