PyPI - fleetpull - Versions diffs - 0.1.0__py3-none-any.whl - Mend

fleetpull 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (252) hide show

fleetpull/__init__.py +36 -0
fleetpull/api/__init__.py +32 -0
fleetpull/api/auth_ingress.py +216 -0
fleetpull/api/catalog.py +139 -0
fleetpull/api/fetch.py +229 -0
fleetpull/api/identity.py +90 -0
fleetpull/api/sync.py +735 -0
fleetpull/cli.py +146 -0
fleetpull/config/__init__.py +47 -0
fleetpull/config/base.py +18 -0
fleetpull/config/example.py +90 -0
fleetpull/config/geotab.py +78 -0
fleetpull/config/http.py +32 -0
fleetpull/config/loading.py +195 -0
fleetpull/config/logger.py +139 -0
fleetpull/config/providers.py +520 -0
fleetpull/config/rate_limit.py +50 -0
fleetpull/config/resolution.py +156 -0
fleetpull/config/retry.py +69 -0
fleetpull/config/root.py +157 -0
fleetpull/config/sections.py +146 -0
fleetpull/endpoints/__init__.py +24 -0
fleetpull/endpoints/geotab/__init__.py +12 -0
fleetpull/endpoints/geotab/_requests.py +427 -0
fleetpull/endpoints/geotab/annotation_logs.py +73 -0
fleetpull/endpoints/geotab/audits.py +70 -0
fleetpull/endpoints/geotab/devices.py +79 -0
fleetpull/endpoints/geotab/driver_changes.py +73 -0
fleetpull/endpoints/geotab/duty_status_logs.py +75 -0
fleetpull/endpoints/geotab/dvir_logs.py +76 -0
fleetpull/endpoints/geotab/exception_events.py +119 -0
fleetpull/endpoints/geotab/fault_data.py +72 -0
fleetpull/endpoints/geotab/fill_ups.py +79 -0
fleetpull/endpoints/geotab/fuel_and_energy_used.py +74 -0
fleetpull/endpoints/geotab/fuel_tax_details.py +75 -0
fleetpull/endpoints/geotab/log_records.py +74 -0
fleetpull/endpoints/geotab/media_files.py +74 -0
fleetpull/endpoints/geotab/shipment_logs.py +71 -0
fleetpull/endpoints/geotab/status_data.py +71 -0
fleetpull/endpoints/geotab/text_messages.py +77 -0
fleetpull/endpoints/geotab/trips.py +102 -0
fleetpull/endpoints/geotab/users.py +81 -0
fleetpull/endpoints/motive/__init__.py +12 -0
fleetpull/endpoints/motive/_spec_builders.py +94 -0
fleetpull/endpoints/motive/driver_idle_rollups.py +113 -0
fleetpull/endpoints/motive/driving_periods.py +85 -0
fleetpull/endpoints/motive/groups.py +61 -0
fleetpull/endpoints/motive/idle_events.py +94 -0
fleetpull/endpoints/motive/users.py +64 -0
fleetpull/endpoints/motive/vehicle_locations.py +170 -0
fleetpull/endpoints/motive/vehicle_utilizations.py +122 -0
fleetpull/endpoints/motive/vehicles.py +106 -0
fleetpull/endpoints/registry.py +280 -0
fleetpull/endpoints/samsara/__init__.py +12 -0
fleetpull/endpoints/samsara/_spec_builders.py +202 -0
fleetpull/endpoints/samsara/addresses.py +77 -0
fleetpull/endpoints/samsara/asset_locations.py +217 -0
fleetpull/endpoints/samsara/driver_fuel_energy_reports.py +124 -0
fleetpull/endpoints/samsara/driver_vehicle_assignments.py +211 -0
fleetpull/endpoints/samsara/drivers.py +169 -0
fleetpull/endpoints/samsara/engine_states.py +114 -0
fleetpull/endpoints/samsara/gps_readings.py +113 -0
fleetpull/endpoints/samsara/idling_events.py +195 -0
fleetpull/endpoints/samsara/odometer_readings.py +116 -0
fleetpull/endpoints/samsara/trips.py +217 -0
fleetpull/endpoints/samsara/vehicle_fuel_energy_reports.py +139 -0
fleetpull/endpoints/samsara/vehicles.py +121 -0
fleetpull/endpoints/shared/__init__.py +57 -0
fleetpull/endpoints/shared/base.py +529 -0
fleetpull/endpoints/shared/request_shape.py +227 -0
fleetpull/endpoints/shared/resume.py +74 -0
fleetpull/endpoints/shared/spec_builders.py +59 -0
fleetpull/endpoints/shared/sync_mode.py +159 -0
fleetpull/endpoints/shared/url_paths.py +149 -0
fleetpull/exceptions.py +320 -0
fleetpull/incremental/__init__.py +27 -0
fleetpull/incremental/cursor.py +66 -0
fleetpull/incremental/resolution.py +152 -0
fleetpull/incremental/seed.py +53 -0
fleetpull/incremental/window.py +94 -0
fleetpull/logger/__init__.py +5 -0
fleetpull/logger/setup.py +145 -0
fleetpull/model_contract/__init__.py +6 -0
fleetpull/model_contract/coercions.py +33 -0
fleetpull/model_contract/response.py +45 -0
fleetpull/models/__init__.py +7 -0
fleetpull/models/geotab/__init__.py +166 -0
fleetpull/models/geotab/annotation_log.py +109 -0
fleetpull/models/geotab/audit.py +56 -0
fleetpull/models/geotab/device.py +217 -0
fleetpull/models/geotab/driver_change.py +102 -0
fleetpull/models/geotab/duty_status_log.py +200 -0
fleetpull/models/geotab/dvir_log.py +184 -0
fleetpull/models/geotab/exception_event.py +135 -0
fleetpull/models/geotab/fault_data.py +168 -0
fleetpull/models/geotab/fill_up.py +189 -0
fleetpull/models/geotab/fuel_and_energy_used.py +81 -0
fleetpull/models/geotab/fuel_tax_detail.py +150 -0
fleetpull/models/geotab/log_record.py +68 -0
fleetpull/models/geotab/media_file.py +133 -0
fleetpull/models/geotab/shared.py +221 -0
fleetpull/models/geotab/shipment_log.py +105 -0
fleetpull/models/geotab/status_data.py +108 -0
fleetpull/models/geotab/text_message.py +125 -0
fleetpull/models/geotab/trip.py +162 -0
fleetpull/models/geotab/user.py +187 -0
fleetpull/models/motive/__init__.py +43 -0
fleetpull/models/motive/driver_idle_rollup.py +109 -0
fleetpull/models/motive/driving_period.py +82 -0
fleetpull/models/motive/group.py +49 -0
fleetpull/models/motive/idle_event.py +77 -0
fleetpull/models/motive/shared.py +192 -0
fleetpull/models/motive/user.py +217 -0
fleetpull/models/motive/vehicle.py +162 -0
fleetpull/models/motive/vehicle_location.py +127 -0
fleetpull/models/motive/vehicle_utilization.py +128 -0
fleetpull/models/samsara/__init__.py +108 -0
fleetpull/models/samsara/address.py +149 -0
fleetpull/models/samsara/asset_location.py +131 -0
fleetpull/models/samsara/driver.py +232 -0
fleetpull/models/samsara/driver_fuel_energy_report.py +153 -0
fleetpull/models/samsara/driver_vehicle_assignment.py +168 -0
fleetpull/models/samsara/engine_state.py +92 -0
fleetpull/models/samsara/gps_reading.py +146 -0
fleetpull/models/samsara/idling_event.py +174 -0
fleetpull/models/samsara/odometer_reading.py +90 -0
fleetpull/models/samsara/trip.py +199 -0
fleetpull/models/samsara/vehicle.py +167 -0
fleetpull/models/samsara/vehicle_fuel_energy_report.py +191 -0
fleetpull/network/__init__.py +9 -0
fleetpull/network/auth/__init__.py +15 -0
fleetpull/network/auth/authenticate.py +271 -0
fleetpull/network/auth/manager.py +223 -0
fleetpull/network/auth/models.py +57 -0
fleetpull/network/auth/strategies.py +169 -0
fleetpull/network/classifiers/__init__.py +11 -0
fleetpull/network/classifiers/geotab.py +145 -0
fleetpull/network/classifiers/motive.py +79 -0
fleetpull/network/classifiers/samsara.py +80 -0
fleetpull/network/client/__init__.py +25 -0
fleetpull/network/client/page.py +32 -0
fleetpull/network/client/profile.py +27 -0
fleetpull/network/client/registry.py +103 -0
fleetpull/network/client/registry_base.py +150 -0
fleetpull/network/client/runtime.py +44 -0
fleetpull/network/client/transport.py +381 -0
fleetpull/network/contract/__init__.py +50 -0
fleetpull/network/contract/auth.py +48 -0
fleetpull/network/contract/classifier.py +189 -0
fleetpull/network/contract/envelope_fetcher.py +33 -0
fleetpull/network/contract/envelopes.py +189 -0
fleetpull/network/contract/outcome.py +43 -0
fleetpull/network/contract/page_decoder.py +101 -0
fleetpull/network/contract/request.py +97 -0
fleetpull/network/decoders/__init__.py +40 -0
fleetpull/network/decoders/_window_stamp.py +78 -0
fleetpull/network/decoders/geotab.py +309 -0
fleetpull/network/decoders/motive.py +204 -0
fleetpull/network/decoders/motive_reports.py +114 -0
fleetpull/network/decoders/samsara.py +343 -0
fleetpull/network/decoders/samsara_reports.py +119 -0
fleetpull/network/decoders/single_page.py +55 -0
fleetpull/network/limits/__init__.py +13 -0
fleetpull/network/limits/bucket_math.py +58 -0
fleetpull/network/limits/limiter.py +153 -0
fleetpull/network/limits/registry.py +96 -0
fleetpull/network/posture/__init__.py +6 -0
fleetpull/network/posture/client_options.py +96 -0
fleetpull/network/retry/__init__.py +13 -0
fleetpull/network/retry/decision.py +155 -0
fleetpull/network/tls/__init__.py +5 -0
fleetpull/network/tls/truststore_context.py +35 -0
fleetpull/orchestrator/__init__.py +30 -0
fleetpull/orchestrator/backfill.py +127 -0
fleetpull/orchestrator/batch.py +155 -0
fleetpull/orchestrator/bisection.py +271 -0
fleetpull/orchestrator/drivers.py +350 -0
fleetpull/orchestrator/entry.py +347 -0
fleetpull/orchestrator/executors.py +128 -0
fleetpull/orchestrator/fanout.py +163 -0
fleetpull/orchestrator/feed_drive.py +266 -0
fleetpull/orchestrator/metadata_projection.py +195 -0
fleetpull/orchestrator/outcome.py +53 -0
fleetpull/orchestrator/recording.py +85 -0
fleetpull/orchestrator/resume.py +143 -0
fleetpull/orchestrator/roster_harvest.py +108 -0
fleetpull/orchestrator/roster_refresh.py +363 -0
fleetpull/orchestrator/runner.py +262 -0
fleetpull/orchestrator/shape_resolution.py +221 -0
fleetpull/orchestrator/spine.py +166 -0
fleetpull/orchestrator/streaming.py +153 -0
fleetpull/orchestrator/unit_loop.py +273 -0
fleetpull/orchestrator/watermark_drive.py +455 -0
fleetpull/paths/__init__.py +13 -0
fleetpull/paths/datasets.py +38 -0
fleetpull/paths/partitions.py +41 -0
fleetpull/paths/resolution.py +98 -0
fleetpull/polars_typing/__init__.py +20 -0
fleetpull/py.typed +0 -0
fleetpull/records/__init__.py +19 -0
fleetpull/records/convert.py +53 -0
fleetpull/records/dataframe.py +63 -0
fleetpull/records/event_time.py +70 -0
fleetpull/records/fields.py +190 -0
fleetpull/records/flatten.py +54 -0
fleetpull/records/roster_members.py +74 -0
fleetpull/records/schema.py +73 -0
fleetpull/records/validation.py +62 -0
fleetpull/resources/__init__.py +10 -0
fleetpull/resources/config.example.yaml +222 -0
fleetpull/roster/__init__.py +16 -0
fleetpull/roster/definition.py +46 -0
fleetpull/roster/key.py +40 -0
fleetpull/roster/registry.py +93 -0
fleetpull/state/__init__.py +36 -0
fleetpull/state/cursors.py +417 -0
fleetpull/state/database.py +463 -0
fleetpull/state/migrations.py +430 -0
fleetpull/state/reconcile.py +127 -0
fleetpull/state/rosters.py +159 -0
fleetpull/state/run_ledger.py +572 -0
fleetpull/state/work_units.py +648 -0
fleetpull/storage/__init__.py +30 -0
fleetpull/storage/append.py +187 -0
fleetpull/storage/atomic.py +161 -0
fleetpull/storage/files.py +176 -0
fleetpull/storage/frames.py +98 -0
fleetpull/storage/metadata.py +161 -0
fleetpull/storage/partitioned.py +205 -0
fleetpull/storage/pruning.py +169 -0
fleetpull/storage/read.py +35 -0
fleetpull/storage/result.py +34 -0
fleetpull/storage/single_file.py +130 -0
fleetpull/storage/splitting.py +88 -0
fleetpull/storage/staging.py +178 -0
fleetpull/storage/writers.py +145 -0
fleetpull/timing/__init__.py +21 -0
fleetpull/timing/canon.py +92 -0
fleetpull/timing/clock.py +192 -0
fleetpull/timing/codec.py +122 -0
fleetpull/timing/sleeper.py +65 -0
fleetpull/vocabulary/__init__.py +16 -0
fleetpull/vocabulary/json_types.py +20 -0
fleetpull/vocabulary/provider.py +29 -0
fleetpull/vocabulary/quota_scope.py +47 -0
fleetpull/vocabulary/response_category.py +32 -0
fleetpull-0.1.0.dist-info/METADATA +248 -0
fleetpull-0.1.0.dist-info/RECORD +252 -0
fleetpull-0.1.0.dist-info/WHEEL +5 -0
fleetpull-0.1.0.dist-info/entry_points.txt +2 -0
fleetpull-0.1.0.dist-info/licenses/LICENSE +202 -0
fleetpull-0.1.0.dist-info/top_level.txt +1 -0

fleetpull/exceptions.py ADDED Viewed

@@ -0,0 +1,320 @@
+# src/fleetpull/exceptions.py
+"""The fleetpull exception hierarchy: operational errors consumers catch.
+The hierarchy mirrors the response-classification vocabulary
+(``ResponseCategory``) and inherits its closure invariant: a new
+exception type is admissible only if it demands a distinct consumer
+action. Programming errors stay stdlib ``ValueError`` /
+``RuntimeError`` — a hierarchy that absorbs caller bugs invites broad
+``except`` clauses that silence them.
+Every member is a plain data carrier: typed fields for programmatic
+handling, a composed human message for ``str()``. Instances never
+carry raw request or response material (headers, bodies, request
+specs, credentials-adjacent values) — every instance is safe to log.
+"""
+from dataclasses import dataclass
+from fleetpull.vocabulary import ResponseCategory
+__all__: list[str] = [
+    'AuthenticationError',
+    'ConfigurationError',
+    'EndpointFailure',
+    'FleetpullError',
+    'ProviderResponseError',
+    'RetriesExhaustedError',
+    'SyncFailuresError',
+    'UnknownQuotaScopeError',
+]
+def _compose_message(
+    head: str,
+    provider: str | None,
+    endpoint: str | None,
+    detail: str | None,
+) -> str:
+    """
+    Compose the human-readable message every hierarchy member carries.
+    Single composition point so all members read uniformly:
+    ``<head> [provider=..., endpoint=...]: <detail>``, with absent
+    fields omitted.
+    Args:
+        head: Summary phrase supplied by the concrete class.
+        provider: Provider name, when known.
+        endpoint: Endpoint name, when known.
+        detail: Human-readable context; programmatic handling never
+            reads it.
+    Returns:
+        The composed message.
+    """
+    message: str = head
+    context_parts: list[str] = []
+    if provider is not None:
+        context_parts.append(f'provider={provider}')
+    if endpoint is not None:
+        context_parts.append(f'endpoint={endpoint}')
+    if context_parts:
+        message = f'{message} [{", ".join(context_parts)}]'
+    if detail is not None:
+        message = f'{message}: {detail}'
+    return message
+class FleetpullError(Exception):
+    """
+    Root of the hierarchy. Never raised directly — raise the concrete
+    member whose consumer action matches. Catching this means "any
+    operational fleetpull failure."
+    Attributes:
+        provider: Provider name, when known.
+        endpoint: Endpoint name, when known.
+        detail: Human-readable context for the failure. Programmatic
+            handling never reads it.
+    """
+    provider: str | None
+    endpoint: str | None
+    detail: str | None
+    def __init__(
+        self,
+        message: str,
+        *,
+        provider: str | None = None,
+        endpoint: str | None = None,
+        detail: str | None = None,
+    ) -> None:
+        """
+        Store the shared fields and compose the ``str()`` message.
+        Keyword-only fields keep raise sites self-describing. The
+        signature breaks ``BaseException``'s default pickle round-trip
+        (which replays positional ``args``); pickling is deliberately
+        unsupported — fleetpull concurrency is threads, and exceptions
+        never cross a process boundary in this package.
+        Args:
+            message: Summary phrase; the concrete class supplies it.
+            provider: Provider name, when known.
+            endpoint: Endpoint name, when known.
+            detail: Human-readable context; never read programmatically.
+        """
+        super().__init__(_compose_message(message, provider, endpoint, detail))
+        self.provider = provider
+        self.endpoint = endpoint
+        self.detail = detail
+class ConfigurationError(FleetpullError):
+    """
+    Local configuration or wiring is wrong; fix it before rerunning.
+    The message is caller-supplied because configuration failures are
+    bespoke by nature. Inherits the base ``__init__`` unchanged.
+    """
+class UnknownQuotaScopeError(ConfigurationError):
+    """
+    A request named a quota scope the registry was never configured
+    with — a configuration bug. No defaults, no fallbacks.
+    Attributes:
+        scope: The unconfigured quota scope.
+    """
+    scope: str
+    def __init__(self, scope: str, *, detail: str | None = None) -> None:
+        """
+        Compose the message from the offending scope.
+        Args:
+            scope: The unconfigured quota scope.
+            detail: Human-readable context (e.g. the configured
+                scopes); never read programmatically.
+        """
+        super().__init__(f'unknown quota scope: {scope!r}', detail=detail)
+        self.scope = scope
+class AuthenticationError(FleetpullError):
+    """
+    Authentication failed fatally: bad credentials or revoked access.
+    Rerunning without fixing credentials cannot succeed.
+    Raised when the one-retry-per-attempt-sequence auth path fails a
+    second time, or when the authentication call itself is rejected.
+    """
+    def __init__(
+        self,
+        *,
+        provider: str | None = None,
+        endpoint: str | None = None,
+        detail: str | None = None,
+    ) -> None:
+        """
+        Compose the fixed head with the shared context fields.
+        Args:
+            provider: Provider name, when known.
+            endpoint: Endpoint name, when known.
+            detail: Human-readable context; never read programmatically.
+        """
+        super().__init__(
+            'authentication failed',
+            provider=provider,
+            endpoint=endpoint,
+            detail=detail,
+        )
+class ProviderResponseError(FleetpullError):
+    """
+    The provider returned a response that fleetpull classified as
+    non-retryable or contract-violating.
+    Covers both definitive refusals and structurally unusable
+    responses: malformed envelopes, bodies that violate the provider
+    contract, unrecognized failure types, unexpected status codes.
+    Attributes:
+        status_code: HTTP status of the offending response, when one
+            exists. A ``category`` field is deliberately absent: every
+            raise of this class corresponds to the FATAL
+            classification, so the field would carry no information.
+    """
+    status_code: int | None
+    def __init__(
+        self,
+        *,
+        provider: str | None = None,
+        endpoint: str | None = None,
+        detail: str | None = None,
+        status_code: int | None = None,
+    ) -> None:
+        """
+        Compose the head, folding in the status code when present.
+        Args:
+            provider: Provider name, when known.
+            endpoint: Endpoint name, when known.
+            detail: Human-readable context; never read programmatically.
+            status_code: HTTP status of the offending response, when
+                one exists.
+        """
+        head: str = 'non-retryable provider response'
+        if status_code is not None:
+            head = f'{head} (HTTP {status_code})'
+        super().__init__(head, provider=provider, endpoint=endpoint, detail=detail)
+        self.status_code = status_code
+class RetriesExhaustedError(FleetpullError):
+    """
+    A retryable classification kept recurring until its attempt budget
+    ran out. Rerunning later is reasonable.
+    A ``status_code`` field is deliberately absent, mirroring the
+    ``ProviderResponseError`` precedent: ``category`` subsumes the raw
+    status's programmatic value, and the final attempt's specifics are
+    diagnostics — ``detail``'s job, folded in by the raise site.
+    Attributes:
+        category: The classification that exhausted its budget
+            (TRANSIENT or RATE_LIMITED).
+        attempt_count: Attempts made before giving up.
+    """
+    category: ResponseCategory | None
+    attempt_count: int | None
+    def __init__(
+        self,
+        *,
+        provider: str | None = None,
+        endpoint: str | None = None,
+        detail: str | None = None,
+        category: ResponseCategory | None = None,
+        attempt_count: int | None = None,
+    ) -> None:
+        """
+        Compose the head from the attempt count and category.
+        Args:
+            provider: Provider name, when known.
+            endpoint: Endpoint name, when known.
+            detail: Human-readable context; never read programmatically.
+            category: The classification that exhausted its budget.
+            attempt_count: Attempts made before giving up.
+        """
+        head: str = 'retry budget exhausted'
+        if attempt_count is not None:
+            head = f'{head} after {attempt_count} attempts'
+        if category is not None:
+            head = f'{head} ({category} responses)'
+        super().__init__(head, provider=provider, endpoint=endpoint, detail=detail)
+        self.category = category
+        self.attempt_count = attempt_count
+@dataclass(frozen=True, slots=True)
+class EndpointFailure:
+    """One endpoint's failure inside a sync run, as the aggregate carries it.
+    Attributes:
+        provider: The failed endpoint's provider name (the lowercase value).
+        endpoint: The failed endpoint's name.
+        error: The caught operational failure, unmodified.
+    """
+    provider: str
+    endpoint: str
+    error: FleetpullError
+class SyncFailuresError(FleetpullError):
+    """
+    One or more endpoints failed inside a sync run that let its
+    siblings continue. Raised after every selected endpoint has run;
+    each carried failure is itself a public-family exception.
+    Deliberately not an ``ExceptionGroup``: the documented catch
+    contract stays ``except FleetpullError:``, which a group would
+    silently bypass.
+    Attributes:
+        failures: The per-endpoint failures, in queue order within each
+            provider -- feeders then consumers, config order within each
+            -- providers in config order (a sync runs one staged queue
+            per provider, the queues concurrent).
+    """
+    failures: tuple[EndpointFailure, ...]
+    def __init__(self, failures: tuple[EndpointFailure, ...]) -> None:
+        """
+        Compose the message from the failed endpoints.
+        Args:
+            failures: The per-endpoint failures, in queue order within
+                each provider, providers in config order.
+        """
+        failed_names = ', '.join(
+            f'{failure.provider}.{failure.endpoint}' for failure in failures
+        )
+        super().__init__(
+            f'sync failed for {len(failures)} endpoint(s)',
+            detail=failed_names,
+        )
+        self.failures = failures

fleetpull/incremental/__init__.py ADDED Viewed

@@ -0,0 +1,27 @@
+# src/fleetpull/incremental/__init__.py
+"""Per-endpoint incremental resume state: the cursors, the resume values (the watermark window and the feed seed), and the pure functions that resolve them."""
+from fleetpull.incremental.cursor import (
+    DateWatermark,
+    FeedToken,
+    IncrementalCursor,
+)
+from fleetpull.incremental.resolution import (
+    resolve_resume_start,
+    resolve_trailing_edge,
+    window_or_none,
+)
+from fleetpull.incremental.seed import FeedResume, FeedSeed
+from fleetpull.incremental.window import DateWindow
+__all__: list[str] = [
+    'DateWatermark',
+    'DateWindow',
+    'FeedResume',
+    'FeedSeed',
+    'FeedToken',
+    'IncrementalCursor',
+    'resolve_resume_start',
+    'resolve_trailing_edge',
+    'window_or_none',
+]

fleetpull/incremental/cursor.py ADDED Viewed

@@ -0,0 +1,66 @@
+# src/fleetpull/incremental/cursor.py
+"""Per-endpoint incremental resume state: the cursor a fetch resumes from.
+A pure, dependency-free leaf: ``DateWatermark`` imports only stdlib
+``datetime``; ``FeedToken`` imports nothing. The two members are the closed
+set of incremental strategies (DESIGN §4):
+    - ``DateWatermark`` (Motive/Samsara) — the maximum event timestamp seen.
+      The next fetch resumes from ``watermark - lookback`` (the orchestrator's
+      arithmetic, not this module's).
+    - ``FeedToken`` (GeoTab GetFeed) — the opaque ``toVersion`` cursor, sent
+      back as ``fromVersion``. fleetpull never interprets it.
+Pure data, no behavior. Resume arithmetic is the orchestrator's,
+resume-param construction is the endpoint's, and serialization is the state
+layer's (it owns the SQLite representation and calls ``timing`` to turn a
+watermark into ISO text) — keeping all three out of here is what lets the
+cursor import nothing internal.
+An endpoint with no incremental state has no cursor — absence, handled at the
+endpoint/orchestrator layer, not a third union member. The set is exactly
+two.
+"""
+from dataclasses import dataclass
+from datetime import datetime
+__all__: list[str] = [
+    'DateWatermark',
+    'FeedToken',
+    'IncrementalCursor',
+]
+@dataclass(frozen=True, slots=True)
+class DateWatermark:
+    """
+    Date-windowed resume state (Motive/Samsara).
+    Attributes:
+        watermark: The maximum event timestamp seen in the data fetched so
+            far, timezone-aware UTC. The next fetch resumes from
+            ``watermark - lookback``; that arithmetic belongs to the
+            orchestrator, and UTC validity is enforced at the codec
+            serialization boundary, so this carrier neither computes nor
+            re-checks.
+    """
+    watermark: datetime
+@dataclass(frozen=True, slots=True)
+class FeedToken:
+    """
+    Feed-cursor resume state (GeoTab GetFeed).
+    Attributes:
+        from_version: The opaque version cursor — GeoTab's ``toVersion`` from
+            the last page, sent back as ``fromVersion`` to resume. fleetpull
+            never parses or orders it; it is a token, not a timestamp.
+    """
+    from_version: str
+type IncrementalCursor = DateWatermark | FeedToken

fleetpull/incremental/resolution.py ADDED Viewed

@@ -0,0 +1,152 @@
+# src/fleetpull/incremental/resolution.py
+"""Pure window-resolution helpers: the stateless pieces that compute a run's window.
+The three pure functions a watermark run's window is built from, composed by the
+(stateful) orchestrator -- which does the SQLite reads and the clock read and feeds
+the values in. Each is single-concern and individually testable; none touches a
+clock, a cursor store, a run ledger, or any I/O.
+    - ``resolve_trailing_edge`` -- the window's end: the current UTC day floored to
+      midnight, held back by the configured cutoff.
+    - ``resolve_resume_start`` -- the window's start, by the resume precedence
+      (DESIGN section 4): the watermark-derived start if one exists, else the
+      coverage frontier, else the cold-start default -- the chosen arm floored
+      to the UTC midnight of its date.
+    - ``window_or_none`` -- the assembly: a ``DateWindow`` when ``start < end``, else
+      ``None`` (caught up -- no work this run, not an error).
+Together they are the watermark resume mechanism (DESIGN section 4): the resolver
+day-aligns both bounds -- the start floored to its UTC midnight, the trailing edge
+floored and held back -- and returns ``None`` for a caught-up window
+(``start >= end``) rather than raising, so a watermark sitting inside the
+still-arriving day is a "no work this run" verdict, not an error. Day alignment
+is the floored-window invariant the date-partitioned writers document: requests
+and partitions are day-granular, so every covered date must be refetched in
+full for wholesale partition replacement and the prune to be safe.
+The start candidates are pre-resolved datetimes, not cursors: the orchestrator
+extracts the watermark moment and subtracts the lookback (arm 1's one line) before
+calling, so this module stays pure datetime math with no cursor dependency. The
+cutoff is expected to be a whole-day ``timedelta`` (its only source is
+``timedelta(days=cutoff_days)``), which keeps the trailing edge date-aligned -- the
+partition-wholeness invariant storage relies on. UTC validity is not checked here;
+the bounds cross the codec boundary when a spec-builder serializes them, and that
+boundary raises on naive/non-UTC, exactly as for ``DateWindow``.
+"""
+from datetime import UTC, datetime, time, timedelta
+from fleetpull.incremental.window import DateWindow
+__all__: list[str] = [
+    'resolve_resume_start',
+    'resolve_trailing_edge',
+    'window_or_none',
+]
+def _utc_midnight(moment: datetime) -> datetime:
+    """The UTC midnight beginning ``moment``'s UTC date (the day-alignment floor)."""
+    return datetime.combine(moment.date(), time.min, tzinfo=UTC)
+def resolve_trailing_edge(now: datetime, cutoff: timedelta) -> datetime:
+    """
+    Compute the window's exclusive end: today's UTC midnight, less the cutoff.
+    Floors ``now`` to the start of its UTC day (the most recent midnight at or before
+    ``now``) so the still-arriving current day is never inside the window, then holds
+    the edge back by ``cutoff`` for providers whose data settles later. With
+    ``cutoff`` zero the end is today's midnight, covering through yesterday -- the
+    last complete day.
+    Args:
+        now: The current instant, timezone-aware UTC (the caller reads it from its
+            ``Clock``); its UTC date is the day floored to.
+        cutoff: Trailing-edge holdback, a whole-day ``timedelta`` (zero or more);
+            whole days keep the returned edge midnight-aligned.
+    Returns:
+        The exclusive end, a UTC-midnight datetime with ``tzinfo`` ``datetime.UTC``.
+    Side Effects:
+        None -- pure function.
+    """
+    return _utc_midnight(now) - cutoff
+def resolve_resume_start(
+    watermark_start: datetime | None,
+    frontier: datetime | None,
+    default_start: datetime,
+) -> datetime:
+    """
+    Pick the window's inclusive start by the resume precedence, floored to
+    the UTC midnight of its date.
+    First present wins (DESIGN section 4): the watermark-derived start when a
+    committed watermark exists, else the coverage frontier (the furthest forward a
+    succeeded run has covered, even empty), else the cold-start default anchor.
+    ``default_start`` is never ``None``, so a start is always produced.
+    The chosen start is floored to its UTC midnight because day-granular
+    endpoints request and replace whole days: the effective window must be
+    day-aligned on both bounds so every covered date is refetched in full --
+    the floored-window invariant the date-partitioned writers' wholesale
+    replacement and prune are safe under. Unfloored, a watermark's
+    ``23:59:59`` less the lookback covers its boundary date by a seconds-wide
+    sliver: the day-granular request fetches the whole day, the window filter
+    keeps only the sliver, and replacement/prune then destroy the boundary
+    partition (the live 6-row sliver defect). Floored, lookback reads as
+    "re-cover N whole days before the watermark's day". Arms 2 and 3 are
+    midnight-aligned by construction, so the floor is idempotent there and
+    load-bearing on arm 1. This rule is for snapshot/point-event endpoints
+    (each record a single point in time); duration/span endpoints (e.g. HOS
+    periods crossing midnight) need their own boundary policy when they
+    arrive and must not blindly reuse it.
+    Args:
+        watermark_start: The watermark moment less the lookback (arm 1), or ``None``
+            when no watermark is committed. Pre-computed by the caller.
+        frontier: The coverage frontier (arm 2), or ``None`` when no succeeded run
+            has covered anything yet.
+        default_start: The cold-start anchor (arm 3); always present.
+    Returns:
+        The chosen start floored to the UTC midnight beginning its date,
+        timezone-aware UTC.
+    Side Effects:
+        None -- pure function.
+    """
+    if watermark_start is not None:
+        return _utc_midnight(watermark_start)
+    if frontier is not None:
+        return _utc_midnight(frontier)
+    return _utc_midnight(default_start)
+def window_or_none(start: datetime, end: datetime) -> DateWindow | None:
+    """
+    Assemble the window, or ``None`` when there is no work this run.
+    Returns ``DateWindow(start, end)`` when ``start < end``. When ``start >= end`` the
+    resume point has reached or passed the trailing edge -- caught up -- and the
+    result is ``None``: a verdict ("nothing to fetch"), not an error. An inverted
+    window is therefore never constructed through this path, so ``DateWindow``'s own
+    ``start < end`` invariant is a backstop for a direct construction bug, never
+    tripped here.
+    Args:
+        start: The window's inclusive start, timezone-aware UTC.
+        end: The window's exclusive end, timezone-aware UTC.
+    Returns:
+        The ``DateWindow`` when ``start < end``, else ``None``.
+    Side Effects:
+        None -- pure function.
+    """
+    if start < end:
+        return DateWindow(start=start, end=end)
+    return None

fleetpull/incremental/seed.py ADDED Viewed

@@ -0,0 +1,53 @@
+# src/fleetpull/incremental/seed.py
+"""The feed arm's cold-start resume value — the historical seed.
+A pure, stdlib-only leaf beside the cursors and the window (DESIGN §4).
+``FeedSeed`` is the resume value a tokenless feed endpoint's FIRST request is
+built from: the spec-builder renders it as ``search.fromDate``, which starts
+the feed at a version covering all entities with date >= that instant
+(wire-proven 2026-07-21 — the probe record in §4). It is never persisted —
+the moment the first page returns, the page's ``toVersion`` commits as the
+``FeedToken`` cursor and the seed is gone forever, which is what makes the
+seed-once invariant (§14's I4) structural: only a run that read no stored
+token can ever construct one.
+``FeedResume`` is the union a feed spec-builder consumes — the seed on the
+cold first run, the stored token on every run after. There is no ``None``
+arm: a feed endpoint always resumes from something, so an absent resume
+reaching a feed builder is a wiring bug the shared guard
+(``require_feed_resume``) rejects loudly.
+"""
+from dataclasses import dataclass
+from datetime import datetime
+from fleetpull.incremental.cursor import FeedToken
+__all__: list[str] = ['FeedResume', 'FeedSeed']
+@dataclass(frozen=True, slots=True)
+class FeedSeed:
+    """
+    The feed arm's cold-start resume value: seed the feed at a date.
+    Rendered by the spec-builder as the first request's ``search.fromDate``
+    (and never a ``fromVersion``); superseded by the ``FeedToken`` cursor the
+    moment the first page commits. UTC validity defers to the codec boundary
+    when the builder serializes ``start``, exactly as ``DateWatermark`` and
+    ``DateWindow`` defer it.
+    Attributes:
+        start: The instant the feed's history begins from — the run's
+            configured cold-start anchor (``sync.default_start_date``),
+            timezone-aware UTC.
+    """
+    start: datetime
+# The resume value a feed spec-builder consumes: the cold-start seed, or the
+# stored token. Deliberately no None arm — a feed endpoint always resumes
+# from one of the two (the runner constructs the seed exactly when no token
+# is stored).
+type FeedResume = FeedSeed | FeedToken