fleetpull 0.1.0__py3-none-any.whl

fleetpull/incremental/window.py

@@ -0,0 +1,94 @@
+# src/fleetpull/incremental/window.py
+"""The half-open watermark resume window — the canonical internal fetch window.
+
+A pure, stdlib-only leaf beside the cursors (DESIGN §4). ``DateWindow`` is the
+*resume value* a watermark fetch is built from, distinct from the stored
+``DateWatermark`` cursor: the cursor records the maximum event timestamp seen, and
+the window is what the resume resolver derives from it (``watermark - lookback`` up
+to the trailing edge). A fetch is built from the window, never from the watermark
+directly.
+
+The window is half-open, ``[start, end)`` — start inclusive, end exclusive — and
+that is the canonical internal form: the half-open boundary is what lets storage's
+delete-by-window predicate (``>= start & < end``) and the start-anchored
+append-filter share one rule, so a cross-boundary event is never double-counted at
+a window edge (DESIGN §4). Unlike the pure ``cursor.py`` carriers, ``DateWindow``
+enforces one structural invariant on construction — ``start < end`` — because that
+ordering has no downstream enforcement; UTC validity, which does (the codec
+boundary), is deferred there exactly as ``DateWatermark`` defers it.
+"""
+
+from dataclasses import dataclass
+from datetime import date, datetime, timedelta
+
+__all__: list[str] = ['DateWindow']
+
+
+@dataclass(frozen=True, slots=True)
+class DateWindow:
+    """
+    The half-open ``[start, end)`` watermark resume window.
+
+    The resume value the spec-builder turns into a request, distinct from the
+    stored ``DateWatermark`` cursor — a fetch is built from this window, not from
+    the watermark. Half-open by definition: ``start`` inclusive, ``end`` exclusive.
+    The half-open boundary is the canonical internal convention that lets the
+    delete-by-window predicate and the start-anchored append-filter share one rule
+    (DESIGN §4); there is deliberately no ``contains`` / ``__contains__`` —
+    membership is storage's vectorized Polars ``>= start & < end``, never scalar
+    row-level.
+
+    Construction enforces the one structural invariant, ``start < end`` (strict,
+    well-ordered, mirroring the run ledger's window). It lives here on the type,
+    not deferred like ``DateWatermark``'s UTC check, because the ordering has no
+    downstream boundary to catch it — an inverted or empty window is a loud-failure
+    bug, not a value to carry; the resume resolver returns ``None`` for a caught-up
+    ``start >= end`` rather than constructing one, so this invariant now backstops a
+    direct construction bug. UTC validity is not checked here; it crosses the codec
+    boundary when a spec-builder serializes the bounds, and that boundary raises on
+    naive/non-UTC, exactly as for ``DateWatermark``.
+
+    Attributes:
+        start: The window's inclusive start, timezone-aware UTC.
+        end: The window's exclusive end, timezone-aware UTC; must be after
+            ``start``.
+    """
+
+    start: datetime
+    end: datetime
+
+    def __post_init__(self) -> None:
+        """
+        Enforce the ``start < end`` ordering invariant on construction.
+
+        Raises:
+            ValueError: ``start`` is not strictly before ``end`` (an inverted or
+                empty window); the message names both bounds.
+            TypeError: ``start`` and ``end`` mix naive and aware datetimes —
+                surfaced from the stdlib comparison, a loud failure (UTC validity
+                otherwise defers to the codec boundary).
+
+        Side Effects:
+            None — reads ``start`` / ``end`` and may raise.
+        """
+        if self.start >= self.end:
+            raise ValueError(
+                f'DateWindow requires start < end; got start={self.start!r}, '
+                f'end={self.end!r}'
+            )
+
+    @property
+    def last_covered_date(self) -> date:
+        """
+        The last calendar date the half-open window covers.
+
+        The ``(end - 1µs).date()`` derivation, stated once: the exclusive
+        ``end`` itself is not covered, so a window ending exactly at UTC
+        midnight does not cover that date while a mid-day ``end`` does. The
+        one-microsecond step back is exact because every datetime in
+        fleetpull is microsecond-precision UTC end to end (DESIGN §3/§4).
+
+        Returns:
+            The UTC calendar date of the last covered instant.
+        """
+        return (self.end - timedelta(microseconds=1)).date()

fleetpull/logger/__init__.py

@@ -0,0 +1,5 @@
+"""Package logging setup, driven by a validated LoggerConfig."""
+
+from fleetpull.logger.setup import setup_logger
+
+__all__: list[str] = ['setup_logger']

fleetpull/logger/setup.py

@@ -0,0 +1,145 @@
+# src/fleetpull/logger/setup.py
+"""Logging configuration for the fleetpull package.
+
+Provides centralized logging setup so every module that calls
+``logging.getLogger(__name__)`` inherits the same level, format, and
+handler configuration. Users drive the setup from a validated
+``LoggerConfig`` — no ad-hoc level parsing or path expansion happens
+here; that is the configuration layer's job.
+
+Library convention:
+    fleetpull attaches no handlers at import time and registers no
+    ``NullHandler``. When a consuming application never configures
+    logging, Python's ``lastResort`` handler surfaces WARNING-and-above
+    records on stderr — for a data-fetching library, warnings (rate
+    limit penalties, session invalidations) should be visible by
+    default, not swallowed. Applications that want full control
+    configure the ``'fleetpull'`` logger with stdlib tools or call
+    :func:`setup_logger`.
+
+Timestamps:
+    All log timestamps are UTC with a ``Z`` suffix. fleetpull's data
+    semantics are UTC end to end; log time matches data time so
+    incident correlation never crosses a timezone boundary.
+"""
+
+import logging
+import sys
+import time
+from typing import Final, TextIO
+
+from fleetpull.config import LoggerConfig
+
+__all__: list[str] = ['setup_logger']
+
+# Name of the package's root logger; every fleetpull module logger
+# (logging.getLogger(__name__)) is a descendant and inherits this
+# configuration.
+_PACKAGE_LOGGER_NAME: Final[str] = 'fleetpull'
+
+# Shared format and date-format for every handler this module attaches.
+# Module-level constants so tests can assert against them by identity
+# rather than re-typing the literals.
+_LOG_FORMAT: Final[str] = (
+    '%(asctime)s - %(levelname)-8s - [%(threadName)s] - [%(name)s] - %(message)s'
+)
+_DATE_FORMAT: Final[str] = '%Y-%m-%dT%H:%M:%SZ'
+
+
+def setup_logger(config: LoggerConfig) -> None:
+    """
+    Configure the fleetpull package logger from a ``LoggerConfig``.
+
+    Clears any handlers already attached to the ``fleetpull`` logger,
+    installs a console handler (always) and an optional file handler,
+    and sets the package logger's level so that neither handler is
+    starved by an ancestor filter. All module loggers created with
+    ``logging.getLogger(__name__)`` inside fleetpull inherit the result
+    automatically.
+
+    The function is idempotent: calling it twice produces the same
+    handler count as one call. The second call's ``LoggerConfig`` fully
+    supersedes the first.
+
+    Args:
+        config: Validated ``LoggerConfig``. ``console_level`` drives
+            stderr output; ``file_path``, when set, enables file
+            logging at ``file_level``.
+
+    Returns:
+        None. Matches the stdlib convention (``logging.basicConfig``
+        and friends all return None); module loggers inherit the
+        configuration automatically, so no handle is useful.
+
+    Side Effects:
+        - Closes and replaces the ``fleetpull`` logger's existing
+          handlers (closing releases the previous configuration's file
+          descriptors).
+        - Sets the ``fleetpull`` logger's level (the minimum of the
+          active handler levels, so no record is filtered at the
+          logger before reaching a handler).
+        - Sets ``propagate = False`` on the ``fleetpull`` logger so a
+          hosting application that configures the root logger does not
+          see duplicate records.
+        - Creates the parent directory of ``file_path`` if file
+          logging is enabled and the directory does not exist.
+        - Emits a single INFO-level record confirming the
+          configuration, through the just-installed handlers.
+    """
+    package_logger: logging.Logger = logging.getLogger(_PACKAGE_LOGGER_NAME)
+
+    # Close, then clear, existing handlers: closing releases the file
+    # descriptors (and Windows file locks) a previous configuration
+    # holds; clearing makes the call idempotent so a caller can
+    # reconfigure at runtime without accumulating duplicates. Closing
+    # a StreamHandler never closes its underlying stream, so stderr is
+    # safe.
+    for previous_handler in package_logger.handlers:
+        previous_handler.close()
+    package_logger.handlers.clear()
+
+    # A hosting application may configure the root logger; disabling
+    # propagation prevents every fleetpull record from being emitted
+    # twice.
+    package_logger.propagate = False
+
+    log_formatter: logging.Formatter = logging.Formatter(
+        fmt=_LOG_FORMAT,
+        datefmt=_DATE_FORMAT,
+    )
+    # UTC timestamps: see the module docstring. The converter applies
+    # to asctime only; record.created remains an epoch float.
+    log_formatter.converter = time.gmtime
+
+    console_handler: logging.StreamHandler[TextIO] = logging.StreamHandler(sys.stderr)
+    console_handler.setFormatter(log_formatter)
+    console_handler.setLevel(config.console_level)
+    package_logger.addHandler(console_handler)
+
+    if config.file_path is not None:
+        config.file_path.parent.mkdir(parents=True, exist_ok=True)
+
+        file_handler: logging.FileHandler = logging.FileHandler(
+            filename=config.file_path,
+            mode='a',
+            encoding='utf-8',
+        )
+        file_handler.setFormatter(log_formatter)
+        file_handler.setLevel(config.file_level)
+        package_logger.addHandler(file_handler)
+
+    # The logger's own level must not filter records before they reach
+    # any handler. file_level participates only when a file handler is
+    # actually attached; otherwise it is inert by design.
+    effective_level: int = (
+        min(config.console_level, config.file_level)
+        if config.file_path is not None
+        else config.console_level
+    )
+    package_logger.setLevel(effective_level)
+
+    package_logger.info(
+        'Logging configured: console_level=%s%s',
+        logging.getLevelName(config.console_level),
+        f', file={config.file_path}' if config.file_path is not None else '',
+    )

fleetpull/model_contract/__init__.py

@@ -0,0 +1,6 @@
+"""The response-model contract: the config-policy base and type-recovery coercion."""
+
+from fleetpull.model_contract.coercions import empty_str_to_none
+from fleetpull.model_contract.response import ResponseModel
+
+__all__: list[str] = ['ResponseModel', 'empty_str_to_none']

fleetpull/model_contract/coercions.py

@@ -0,0 +1,33 @@
+# src/fleetpull/model_contract/coercions.py
+"""Type-recovery coercion for stringly wire values.
+
+Value-level wire-cleaning on a model is allowed only where recovering
+the declared type is structural (DESIGN section 9): a field typed
+``int`` receiving ``""`` cannot validate at all, so a before-validator
+lifts the empty string ahead of parsing (Motive ``VehicleSummary.year``
+is the shipped case). String fields never use this — models preserve
+``""`` faithfully from the wire, and empty strings normalize to null
+once, at the DataFrame boundary (``records.normalize_empty_strings``).
+A formatted value someone chose (``"22.3 mi"``) is never touched
+anywhere: parsing it would presume a use case.
+"""
+
+__all__: list[str] = ['empty_str_to_none']
+
+
+# A BeforeValidator receives the raw wire value, and the layering
+# contract bars model_contract from vocabulary's JsonValue.
+# typing-justified: object is the strictest annotation available here.
+def empty_str_to_none(value: object) -> object:
+    """Lift a bare empty string to ``None``; everything else passes through.
+
+    Args:
+        value: The raw wire value, ahead of field validation.
+
+    Returns:
+        ``None`` when ``value`` is exactly ``''``; otherwise ``value``
+        unchanged.
+    """
+    if value == '':
+        return None
+    return value

fleetpull/model_contract/response.py

@@ -0,0 +1,45 @@
+# src/fleetpull/model_contract/response.py
+"""The shared config-policy base every per-record response model extends.
+
+Carries only configuration — no fields, no methods, no schema-derivation helpers
+(those are the records layer's concern, §9, and attach when it is built). Models
+that extend ``ResponseModel`` stay pure API mirrors.
+"""
+
+from pydantic import BaseModel, ConfigDict
+
+__all__: list[str] = ['ResponseModel']
+
+
+class ResponseModel(BaseModel):
+    """
+    Config-policy base for response models; subclasses add only fields.
+
+    Each ``model_config`` setting is deliberate:
+
+    - ``frozen=True`` — verified inbound data is immutable once validated.
+    - ``extra='ignore'`` — response models mirror evolving provider APIs, so a
+      field a provider adds is dropped, not a crash (records derives the Polars
+      schema from declared fields, so an unknown field has nowhere to land
+      anyway). A deliberate departure from the house ``extra='forbid'`` default,
+      justified for inbound mirrors specifically.
+    - non-strict (the absence of ``strict=True``) — Pydantic's lax coercion turns
+      Motive's stringly-typed numerics into typed values; ``strict=True`` would
+      reject them, and the §9 coercion overrides only handle what lax cannot. (The
+      GeoTab auth slice models use ``strict=True`` because auth responses are
+      well-typed — the opposite case.)
+    - ``populate_by_name=True`` — models alias camelCase wire keys to snake_case
+      fields; this lets construction by either the alias or the field name
+      succeed.
+    - ``str_strip_whitespace=True`` — trims incoming strings as structural
+      hygiene, never a semantic transform.
+    - ``validate_default=True`` — house standard.
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra='ignore',
+        populate_by_name=True,
+        str_strip_whitespace=True,
+        validate_default=True,
+    )

fleetpull/models/__init__.py

@@ -0,0 +1,7 @@
+"""Pydantic response models, one subpackage per provider.
+
+``ResponseModel`` (the config-policy base) lives in ``fleetpull.model_contract``;
+provider model packages import it from there directly.
+"""
+
+__all__: list[str] = []

fleetpull/models/geotab/__init__.py

@@ -0,0 +1,166 @@
+# src/fleetpull/models/geotab/__init__.py
+"""GeoTab response models; the face re-exports each endpoint module's models."""
+
+from fleetpull.models.geotab.annotation_log import (
+    AnnotationLog,
+    AnnotationLogDriverRef,
+    AnnotationLogDutyStatusLogRef,
+)
+from fleetpull.models.geotab.audit import Audit
+from fleetpull.models.geotab.device import CustomFeatures, Device, DeviceFlags
+from fleetpull.models.geotab.driver_change import (
+    DriverChange,
+    DriverChangeDeviceRef,
+    DriverChangeDriverRef,
+)
+from fleetpull.models.geotab.duty_status_log import (
+    DutyStatusLog,
+    DutyStatusLogDeviceRef,
+    DutyStatusLogDriverRef,
+)
+from fleetpull.models.geotab.dvir_log import (
+    DvirLog,
+    DvirLogDefectList,
+    DvirLogDeviceRef,
+    DvirLogDriverRef,
+    DvirLogTrailerRef,
+)
+from fleetpull.models.geotab.exception_event import (
+    ExceptionEvent,
+    ExceptionEventDeviceRef,
+    ExceptionEventDiagnosticRef,
+    ExceptionEventDriverRef,
+    ExceptionEventRuleRef,
+)
+from fleetpull.models.geotab.fault_data import (
+    FaultData,
+    FaultDataControllerRef,
+    FaultDataDeviceRef,
+    FaultDataDiagnosticRef,
+    FaultDataFailureModeRef,
+    FaultDataFaultStates,
+)
+from fleetpull.models.geotab.fill_up import (
+    FillUp,
+    FillUpDeviceRef,
+    FillUpDriverRef,
+    FillUpLocation,
+    FillUpTankCapacity,
+    FillUpTankLevelExtrema,
+    FillUpTankLevelPoint,
+)
+from fleetpull.models.geotab.fuel_and_energy_used import (
+    FuelAndEnergyUsed,
+    FuelAndEnergyUsedDeviceRef,
+)
+from fleetpull.models.geotab.fuel_tax_detail import (
+    FuelTaxDetail,
+    FuelTaxDetailDeviceRef,
+    FuelTaxDetailDriverRef,
+)
+from fleetpull.models.geotab.log_record import LogRecord, LogRecordDeviceRef
+from fleetpull.models.geotab.media_file import (
+    MediaFile,
+    MediaFileDeviceRef,
+    MediaFileDriverRef,
+)
+from fleetpull.models.geotab.shared import (
+    GeotabAddressedLocation,
+    GeotabCoordinate,
+    GeotabPostalAddress,
+    GeotabTimeSpan,
+    bare_id_to_reference,
+    parse_timespan,
+)
+from fleetpull.models.geotab.shipment_log import (
+    ShipmentLog,
+    ShipmentLogDeviceRef,
+    ShipmentLogDriverRef,
+)
+from fleetpull.models.geotab.status_data import (
+    StatusData,
+    StatusDataDeviceRef,
+    StatusDataDiagnosticRef,
+)
+from fleetpull.models.geotab.text_message import (
+    TextMessage,
+    TextMessageContent,
+    TextMessageDeviceRef,
+)
+from fleetpull.models.geotab.trip import (
+    Trip,
+    TripDeviceRef,
+    TripDriverRef,
+    TripStopPoint,
+)
+from fleetpull.models.geotab.user import User, UserAccessGroupFilterRef
+
+__all__: list[str] = [
+    'AnnotationLog',
+    'AnnotationLogDriverRef',
+    'AnnotationLogDutyStatusLogRef',
+    'Audit',
+    'CustomFeatures',
+    'Device',
+    'DeviceFlags',
+    'DriverChange',
+    'DriverChangeDeviceRef',
+    'DriverChangeDriverRef',
+    'DutyStatusLog',
+    'DutyStatusLogDeviceRef',
+    'DutyStatusLogDriverRef',
+    'DvirLog',
+    'DvirLogDefectList',
+    'DvirLogDeviceRef',
+    'DvirLogDriverRef',
+    'DvirLogTrailerRef',
+    'ExceptionEvent',
+    'ExceptionEventDeviceRef',
+    'ExceptionEventDiagnosticRef',
+    'ExceptionEventDriverRef',
+    'ExceptionEventRuleRef',
+    'FaultData',
+    'FaultDataControllerRef',
+    'FaultDataDeviceRef',
+    'FaultDataDiagnosticRef',
+    'FaultDataFailureModeRef',
+    'FaultDataFaultStates',
+    'FillUp',
+    'FillUpDeviceRef',
+    'FillUpDriverRef',
+    'FillUpLocation',
+    'FillUpTankCapacity',
+    'FillUpTankLevelExtrema',
+    'FillUpTankLevelPoint',
+    'FuelAndEnergyUsed',
+    'FuelAndEnergyUsedDeviceRef',
+    'FuelTaxDetail',
+    'FuelTaxDetailDeviceRef',
+    'FuelTaxDetailDriverRef',
+    'GeotabAddressedLocation',
+    'GeotabCoordinate',
+    'GeotabPostalAddress',
+    'GeotabTimeSpan',
+    'LogRecord',
+    'LogRecordDeviceRef',
+    'MediaFile',
+    'MediaFileDeviceRef',
+    'MediaFileDriverRef',
+    'ShipmentLog',
+    'ShipmentLogDeviceRef',
+    'ShipmentLogDriverRef',
+    'StatusData',
+    'StatusDataDeviceRef',
+    'StatusDataDiagnosticRef',
+    'TextMessage',
+    'TextMessageContent',
+    'TextMessageDeviceRef',
+    'Trip',
+    'TripDeviceRef',
+    'TripDriverRef',
+    'TripStopPoint',
+    'User',
+    'UserAccessGroupFilterRef',
+    'bare_id_to_reference',
+    'parse_timespan',
+]

fleetpull/models/geotab/annotation_log.py

@@ -0,0 +1,109 @@
+# src/fleetpull/models/geotab/annotation_log.py
+"""GeoTab AnnotationLog response model (``GetFeed`` on ``typeName: AnnotationLog``).
+
+Written from the 2026-07-21 feed wave three SCALE census (walked at
+scale at the probed tenant), never from docs. An AnnotationLog is one
+free-text annotation attached to an HOS duty-status log — a versioned
+feed (annotations are user-editable), so re-emission under newer
+``version`` tokens is expected and the consumer reconciles by
+``(id, max version)`` (DESIGN §4).
+
+This vertical COMPLETES the wave-two ``duty_status_logs`` loop: a
+DutyStatusLog carries an ``annotations`` id-list (the strict
+``list[str]`` reduction), and each AnnotationLog's ``dutyStatusLog.id``
+points BACK to the DutyStatusLog it annotates — a bidirectional join
+across the two verticals (``annotation_logs.duty_status_log__id`` ↔
+``duty_status_logs.annotations``).
+
+Requiredness posture (the wave-two conservative stance, DESIGN §8): the
+census is a TENANT-SCOPED observation (8,857 records), so structural
+requiredness is limited to the record identity — ``id``, ``dateTime``
+(the event time), ``version``, and the primary entity ref
+(``dutyStatusLog``, the annotated log — the annotation's subject) — and
+every other field is optional EVEN where the census was total. The
+observed arms:
+
+- ``dutyStatusLog`` and ``driver`` were object-only (``{id}``) at
+  scale; both ride the shared ``bare_id_to_reference`` lift regardless
+  (the census-scope lesson, DESIGN §8: a tenant census cannot prove
+  the string arm absent, and the lift is structural and
+  sentinel-agnostic).
+
+``dateTime`` is recovered tz-aware by validation, the GeoTab sibling
+idiom. ``comment`` is a census-open free-text string.
+"""
+
+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] = [
+    'AnnotationLog',
+    'AnnotationLogDriverRef',
+    'AnnotationLogDutyStatusLogRef',
+]
+
+
+class AnnotationLogDriverRef(ResponseModel):
+    """The annotating driver's reference.
+
+    Census-observed as an ``{id}`` object at scale; the shared coercion
+    lifts a bare string defensively (the census-scope lesson).
+    """
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    id: str
+
+
+class AnnotationLogDutyStatusLogRef(ResponseModel):
+    """The annotated duty-status log's reference — the annotation's subject.
+
+    The BACK-REFERENCE completing the wave-two loop: ``id`` points to
+    the ``duty_status_logs`` record this annotation belongs to.
+    Census-observed as an ``{id}`` object at scale; the shared coercion
+    lifts a bare string defensively (the census-scope lesson).
+    """
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    id: str
+
+
+class AnnotationLog(ResponseModel):
+    """One GeoTab duty-status-log annotation from the AnnotationLog feed.
+
+    The wave-two conservative mirror (the module docstring's posture):
+    ``id`` / ``date_time`` / ``version`` / ``duty_status_log`` required,
+    everything else optional even where census-total.
+
+    Attributes:
+        comment: The annotation's free text (census-open str).
+        date_time: The annotation's UTC instant — the endpoint's event
+            time.
+        driver: The annotating driver's reference (object-only at scale;
+            defensively lifted).
+        duty_status_log: The annotated duty-status log's reference — the
+            back-reference to the ``duty_status_logs`` vertical.
+        id: GeoTab's record id.
+        version: The record's version token — the reconcile key beside
+            ``id``.
+    """
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    comment: str | None = None
+    date_time: datetime
+    driver: Annotated[
+        AnnotationLogDriverRef | None, BeforeValidator(bare_id_to_reference)
+    ] = None
+    duty_status_log: Annotated[
+        AnnotationLogDutyStatusLogRef, BeforeValidator(bare_id_to_reference)
+    ]
+    id: str
+    version: str

fleetpull/models/geotab/audit.py

@@ -0,0 +1,56 @@
+# src/fleetpull/models/geotab/audit.py
+"""GeoTab Audit response model (``GetFeed`` on ``typeName: Audit``).
+
+Written from the 2026-07-21 feed wave three SCALE census (walked at
+scale at the probed tenant), never from docs. An Audit is one
+configuration-change audit-trail entry — a versioned feed, so
+re-emission under newer ``version`` tokens is expected and the consumer
+reconciles by ``(id, max version)`` (DESIGN §4).
+
+The SIMPLEST feed vertical: NO reference fields at all (no ref models),
+six flat keys. Requiredness posture (the wave-two conservative stance,
+DESIGN §8): the census is a TENANT-SCOPED observation (20,000 records),
+so structural requiredness is limited to the record identity — ``id``,
+``dateTime`` (the event time), and ``version`` — and every other field
+is optional EVEN where the census was total.
+
+``dateTime`` is recovered tz-aware by validation, the GeoTab sibling
+idiom. ``comment``, ``name``, and ``userName`` are census-open
+free-text strings.
+"""
+
+from datetime import datetime
+
+from pydantic import ConfigDict
+from pydantic.alias_generators import to_camel
+
+from fleetpull.model_contract import ResponseModel
+
+__all__: list[str] = ['Audit']
+
+
+class Audit(ResponseModel):
+    """One GeoTab audit-trail entry from the Audit feed.
+
+    The wave-two conservative mirror (the module docstring's posture):
+    ``id`` / ``date_time`` / ``version`` required, everything else
+    optional even where census-total.
+
+    Attributes:
+        comment: The audit entry's free text (census-open str).
+        date_time: The entry's UTC instant — the endpoint's event time.
+        id: GeoTab's record id.
+        name: The audited object's name (census-open str).
+        user_name: The acting user's name (census-open str).
+        version: The record's version token — the reconcile key beside
+            ``id``.
+    """
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    comment: str | None = None
+    date_time: datetime
+    id: str
+    name: str | None = None
+    user_name: str | None = None
+    version: str