fleetpull 0.1.0__py3-none-any.whl

fleetpull/storage/single_file.py

@@ -0,0 +1,130 @@
+# src/fleetpull/storage/single_file.py
+"""The single-file writer family: one ``data.parquet`` rewritten each run.
+
+``SingleFileWriter`` is the family's shared substance -- accumulate the run's
+frames, then dedup the subclass's finalized frame and atomically rewrite the
+single file -- and ``SnapshotWriter`` is the shipped ``(SINGLE, SnapshotMode)``
+cell (full replacement, the prior file never read). The unbuilt single-file
+date-window cell will join this family as the combine subclass (DESIGN §3).
+``select_writer`` (``storage/writers.py``) is the routing face that constructs
+these.
+"""
+
+from abc import ABC, abstractmethod
+from pathlib import Path
+
+import polars as pl
+
+from fleetpull.storage.atomic import atomic_write_parquet
+from fleetpull.storage.files import data_file
+from fleetpull.storage.frames import dedup_counting
+from fleetpull.storage.result import WriteResult
+
+__all__: list[str] = ['SingleFileWriter', 'SnapshotWriter']
+
+
+class SingleFileWriter(ABC):
+    """Writers whose dataset is one ``data.parquet`` rewritten each run.
+
+    Shared substance: accumulate the run's frames, and on ``finalize`` dedup the
+    subclass's finalized frame and atomically rewrite the single file. Subclasses
+    supply ``_finalize_frame`` -- the per-cell write semantic, which decides
+    whether the prior file is read at all. A snapshot does not read it (it
+    replaces); the unbuilt watermark single-file cell will (it combines with
+    prior rows), reading through ``read_parquet_if_exists`` itself. The
+    base never reads -- the read is opt-in by the subclass.
+    """
+
+    def __init__(self, target_dir: Path, *, drop_duplicates: bool = True) -> None:
+        """Bind the writer to an endpoint directory.
+
+        Args:
+            target_dir: The endpoint directory holding ``data.parquet``.
+            drop_duplicates: Whether ``finalize`` drops exact-duplicate rows
+                (``storage.drop_exact_duplicates``, default on).
+
+        Side Effects:
+            None.
+        """
+        self._target_dir = target_dir
+        self._drop_duplicates = drop_duplicates
+        self._frames: list[pl.DataFrame] = []
+
+    def write(self, frame: pl.DataFrame) -> None:
+        """Accumulate one frame for this run.
+
+        Args:
+            frame: A validated, flattened frame for this endpoint.
+
+        Side Effects:
+            Holds a reference to ``frame`` until ``finalize``.
+        """
+        self._frames.append(frame)
+
+    def finalize(self) -> WriteResult:
+        """Dedup (unless off) the subclass's finalized frame and write it.
+
+        Returns:
+            The write report (``files_written`` is always ``1``).
+
+        Side Effects:
+            Atomically rewrites ``data.parquet`` under the endpoint directory.
+        """
+        written, duplicates_dropped = dedup_counting(
+            self._finalize_frame(), enabled=self._drop_duplicates
+        )
+        atomic_write_parquet(written, data_file(self._target_dir))
+        return WriteResult(
+            rows_written=written.height,
+            duplicates_dropped=duplicates_dropped,
+            files_written=1,
+        )
+
+    @abstractmethod
+    def _finalize_frame(self) -> pl.DataFrame:
+        """Produce the frame to dedup and write for this run.
+
+        The per-cell write semantic. A replace cell returns its accumulated frame;
+        a combine cell reads the prior file (via ``read_parquet_if_exists``) and
+        merges it with the accumulated frame. Reading the prior file is the
+        subclass's choice -- the base never reads.
+
+        Returns:
+            The frame to dedup and write.
+
+        Side Effects:
+            A combine subclass reads ``data.parquet``; a replace subclass does not.
+        """
+        ...
+
+    def _accumulated(self) -> pl.DataFrame:
+        """This run's accumulated ``write`` frames as one frame.
+
+        Returns:
+            The concatenation of every frame passed to ``write``. ``write`` must
+            have been called at least once.
+
+        Side Effects:
+            None.
+        """
+        return pl.concat(self._frames)
+
+
+class SnapshotWriter(SingleFileWriter):
+    """``snapshot`` + ``single``: full replacement of the current-state dataset.
+
+    A snapshot re-fetches its whole current-state dataset every run, so the result
+    is just this run's accumulated frame and the prior file is never read -- it is
+    overwritten by the atomic rename (DESIGN §3).
+    """
+
+    def _finalize_frame(self) -> pl.DataFrame:
+        """Return this run's accumulated frame; the prior file is not read.
+
+        Returns:
+            The accumulated frame, replacing the prior dataset wholesale.
+
+        Side Effects:
+            None -- the prior ``data.parquet`` is overwritten without being read.
+        """
+        return self._accumulated()

fleetpull/storage/splitting.py

@@ -0,0 +1,88 @@
+# src/fleetpull/storage/splitting.py
+"""Date-partition splitting: group a records frame into per-UTC-date sub-frames.
+
+The write-unit decomposition the date-partitioned layout (the ``StorageKind``
+date_partitioned arm) iterates over. A fetch arrives as one frame whose rows may
+span several calendar dates; the date-partitioned layout writes one parquet file
+per date (``date=YYYY-MM-DD/part.parquet``), so something must say which rows
+belong to which date's file. That is this module's only job: read the event-time
+column, take the UTC calendar date off each row, and group the rows by it.
+
+A pure leaf -- stdlib ``date`` and Polars only, nothing internal. It does not
+touch the filesystem, does not know what a partition path looks like, does not
+read existing data, and does not merge, dedup, or filter by window; those are the
+layout's and the merge's concerns. Pure frame -> list of (date, frame).
+
+The date is the UTC calendar date, because every timestamp in fleetpull is UTC
+end to end; the partition boundary is therefore UTC midnight, which lines the
+partitions up exactly with the half-open ``[start, end)`` fetch window so no
+event double-counts at an edge. Row order within a partition is the input's order
+unchanged -- this function imposes no sort, that being out of scope (parquet is
+order-indifferent and the end use is not fleetpull's to anticipate).
+"""
+
+from datetime import date
+
+import polars as pl
+
+__all__: list[str] = ['split_by_date']
+
+_PARTITION_DATE_COLUMN: str = '_partition_date'
+
+
+def split_by_date(
+    frame: pl.DataFrame, event_time_column: str
+) -> list[tuple[date, pl.DataFrame]]:
+    """Group a frame's rows into per-UTC-date sub-frames.
+
+    Derives the UTC calendar date of each row from ``event_time_column`` and
+    partitions the frame on it, returning one ``(date, sub_frame)`` pair per
+    distinct date present. The derived date is dropped from each sub-frame before
+    return -- the date lives in the partition path (hive ``date=YYYY-MM-DD``), not
+    inside the file, so storing it would be redundant and could collide with the
+    path-derived column on read. Every other column, and the precise
+    ``event_time_column`` value itself, is carried through unchanged.
+
+    An empty frame yields an empty list: an empty frame has no dates, hence zero
+    partitions, so the caller writes nothing and no empty ``date=.../`` directory
+    is created -- a missing date in the on-disk tree therefore always reflects a
+    real absence of data, never a silent gap.
+
+    Args:
+        frame: The records frame to split; ``event_time_column`` must be a UTC
+            datetime column. Expected to hold one fetch's worth of records (e.g.
+            one vehicle's locations over a window), kept small upstream so the
+            materialized per-date sub-frames stay small.
+        event_time_column: Name of the UTC datetime column whose calendar date
+            keys the partitions (e.g. ``'located_at'``).
+
+    Returns:
+        One ``(date, sub_frame)`` pair per distinct UTC date, each key a
+        ``datetime.date`` and each sub-frame that date's rows with the derived
+        date column removed. Empty when ``frame`` is empty. Rows within a
+        sub-frame keep their input order; the order of the pairs is unspecified
+        beyond being deterministic for a given input.
+
+    Raises:
+        polars.exceptions.ColumnNotFoundError: ``event_time_column`` is absent
+            from ``frame`` -- a caller bug, surfaced unguarded by Polars.
+        polars.exceptions.PolarsError: ``event_time_column`` is not a temporal
+            dtype, so the date accessor cannot apply -- a caller bug, left to
+            propagate as Polars' own error.
+
+    Side Effects:
+        None -- pure function; ``frame`` is not mutated.
+    """
+    if frame.height == 0:
+        return []
+    with_partition_date = frame.with_columns(
+        pl.col(event_time_column).dt.date().alias(_PARTITION_DATE_COLUMN)
+    )
+    partitions = with_partition_date.partition_by(
+        _PARTITION_DATE_COLUMN, maintain_order=True
+    )
+    result: list[tuple[date, pl.DataFrame]] = []
+    for partition_frame in partitions:
+        partition_date: date = partition_frame.get_column(_PARTITION_DATE_COLUMN)[0]
+        result.append((partition_date, partition_frame.drop(_PARTITION_DATE_COLUMN)))
+    return result

fleetpull/storage/staging.py

@@ -0,0 +1,178 @@
+# src/fleetpull/storage/staging.py
+"""Date-partition staging and compaction: the write half of the date-partitioned
+path (the prune in ``pruning.py`` is the delete half).
+
+A date-partitioned watermark endpoint fans out -- the writer receives this run's
+records one piece at a time. ``stage_shard`` lands each piece immediately as date-split shards under
+``date=YYYY-MM-DD/staging/``, so no piece is held in memory waiting for the rest;
+``compact_partition`` folds each date's shards into that date's single
+``part.parquet``; ``clear_partition_staging`` removes staging the writer is done with
+-- at construction a crashed run's stale shards, at finalize the shards just folded.
+Three stateless functions, each one concern; the partitioned writer family
+(``partitioned.py``) orchestrates
+them and decides per cell whether compaction folds in the existing partition and
+whether the run prunes (DESIGN §3).
+
+Shards carry a ``.shard`` extension, not ``.parquet``, so a hive read of the live
+dataset (``scan_parquet`` globbing ``**/*.parquet``, a BigQuery external table)
+never picks up a half-staged partition's shards mid-run -- the queryable surface is
+the ``part.parquet`` files alone. Compaction reads the shards back by explicit
+path, which is format-driven, not extension-driven.
+
+Memory is bounded by the chunk, not the endpoint (DESIGN §3): a partition holds one
+chunk's rows for one date, materialized only at compaction and released after.
+High-volume endpoints stay in bounds by a smaller date-chunk, not by streaming.
+"""
+
+import shutil
+from collections.abc import Collection
+from dataclasses import dataclass
+from datetime import date
+from pathlib import Path
+
+import polars as pl
+
+from fleetpull.storage.atomic import atomic_write_parquet
+from fleetpull.storage.files import (
+    partition_dir,
+    partition_part_file,
+    partition_staging_dir,
+    partition_staging_shard,
+)
+from fleetpull.storage.frames import dedup_counting
+from fleetpull.storage.splitting import split_by_date
+
+__all__: list[str] = [
+    'CompactionResult',
+    'clear_partition_staging',
+    'compact_partition',
+    'stage_shard',
+]
+
+
+@dataclass(frozen=True, slots=True)
+class CompactionResult:
+    """The row counts from compacting one partition.
+
+    Attributes:
+        rows_written: Rows in the written ``part.parquet`` (after dedup).
+        duplicates_dropped: Exact-duplicate rows removed during compaction.
+    """
+
+    rows_written: int
+    duplicates_dropped: int
+
+
+def stage_shard(
+    endpoint_dir: Path, frame: pl.DataFrame, event_time_column: str
+) -> set[date]:
+    """Land one fetched piece as date-split shards under the partitions' staging.
+
+    Splits ``frame`` by the UTC date of ``event_time_column`` and writes each
+    date's rows as a uniquely-named ``.shard`` file under that date's ``staging/``
+    directory, atomically. An empty frame writes nothing. Returns the dates
+    touched so the writer knows which partitions to compact.
+
+    Args:
+        endpoint_dir: The endpoint directory holding the ``date=`` partitions.
+        frame: One fetched piece (e.g. one vehicle's rows over the window).
+        event_time_column: The UTC datetime column whose date keys the partitions.
+
+    Returns:
+        The set of UTC dates that received a shard (empty for an empty frame).
+
+    Side Effects:
+        Writes one ``.shard`` file per date present, creating staging directories
+        as needed.
+    """
+    touched: set[date] = set()
+    for partition_date, sub_frame in split_by_date(frame, event_time_column):
+        atomic_write_parquet(
+            sub_frame, partition_staging_shard(endpoint_dir, partition_date)
+        )
+        touched.add(partition_date)
+    return touched
+
+
+def compact_partition(
+    endpoint_dir: Path,
+    partition_date: date,
+    existing: pl.DataFrame | None,
+    *,
+    drop_duplicates: bool = True,
+) -> CompactionResult:
+    """Fold one date's staged shards into its ``part.parquet``.
+
+    Reads every ``.shard`` under the date's ``staging/`` directory, concatenates
+    them (and ``existing`` if the cell folds in the prior partition), drops exact
+    duplicates unless the flag turns that off, and writes the result atomically
+    to ``part.parquet``, replacing any prior file. The whole partition is
+    materialized here; it is bounded by the chunk (DESIGN §3), not the endpoint.
+    Folds and nothing else -- the writer clears the staging afterward
+    (``clear_partition_staging``), keeping this single-concern.
+
+    Args:
+        endpoint_dir: The endpoint directory holding the ``date=`` partitions.
+        partition_date: The date whose staged shards to compact; its ``staging/``
+            directory must hold at least one shard.
+        existing: The prior ``part.parquet`` contents to fold in (append cells), or
+            ``None`` to replace the partition wholesale (watermark cells).
+        drop_duplicates: Whether to drop exact-duplicate rows (DESIGN §6 --
+            ``storage.drop_exact_duplicates``, default on). ``False`` writes the
+            combined rows byte-for-byte.
+
+    Returns:
+        The written partition's row counts.
+
+    Side Effects:
+        Writes ``part.parquet``. Leaves the staging shards in place for the caller
+        to clear.
+    """
+    staging_dir = partition_staging_dir(endpoint_dir, partition_date)
+    shard_frames = [
+        pl.read_parquet(shard) for shard in sorted(staging_dir.glob('*.shard'))
+    ]
+    if existing is not None:
+        shard_frames.append(existing)
+    combined = pl.concat(shard_frames)
+    written, duplicates_dropped = dedup_counting(combined, enabled=drop_duplicates)
+    atomic_write_parquet(written, partition_part_file(endpoint_dir, partition_date))
+    return CompactionResult(
+        rows_written=written.height, duplicates_dropped=duplicates_dropped
+    )
+
+
+def clear_partition_staging(
+    endpoint_dir: Path, partition_dates: Collection[date]
+) -> None:
+    """Remove these dates' staging, dropping any ``date=`` directory it empties.
+
+    For each date: remove its ``staging/`` directory if present, then remove the
+    enclosing ``date=`` directory if that left it empty. The writer calls this in two
+    places. At construction, to sweep a crashed prior run's stale shards before
+    staging anything, so a later ``compact_partition`` folds only the live run's
+    shards; a date that died after ``stage_shard`` but before any ``part.parquet``
+    holds only ``staging/``, and an empty ``date=`` directory must not survive (it
+    would read as a partition with no data, the invariant ``delete_partition``
+    upholds), so it goes too. At finalize, to clear the shards ``compact_partition``
+    just folded; that date now holds a ``part.parquet``, so its directory survives.
+    Only a genuinely empty directory is removed -- a ``part.parquet`` or a crashed
+    atomic-write temp keeps it. Lenient on a missing ``staging/``: a date with none
+    is a no-op, not an error (DESIGN §3/§14).
+
+    Args:
+        endpoint_dir: The endpoint directory holding the ``date=`` partitions.
+        partition_dates: The dates whose staging to clear.
+
+    Side Effects:
+        Removes any ``staging/`` directory under those dates, and any ``date=``
+        directory left empty by that removal.
+    """
+    for partition_date in partition_dates:
+        staging_dir = partition_staging_dir(endpoint_dir, partition_date)
+        if not staging_dir.exists():
+            continue
+        shutil.rmtree(staging_dir)
+        date_dir = partition_dir(endpoint_dir, partition_date)
+        if not any(date_dir.iterdir()):
+            date_dir.rmdir()

fleetpull/storage/writers.py

@@ -0,0 +1,145 @@
+# src/fleetpull/storage/writers.py
+"""The dataset-writer contract and its routing face.
+
+A ``DatasetWriter`` accepts this run's records in one or more pieces and finalizes
+them onto disk as the endpoint's dataset. Each ``(StorageKind, SyncMode)`` cell is
+its own writer, because the write semantics are not freely composable across the
+two axes -- a floored watermark write *replaces* under date partitioning but
+*clears and appends* under a single file, so the semantic depends on both axes at
+once. The writer families live with their layouts -- the single-file family in
+``storage/single_file.py``, the date-partitioned family in
+``storage/partitioned.py``, the append-log feed cell in ``storage/append.py`` --
+and this module owns the contract (``DatasetWriter``) and the one routing point
+(``select_writer``).
+
+The orchestrator drives every endpoint identically: ``select_writer`` returns the
+cell's writer, the orchestrator calls ``write`` for each frame it has (once for a
+snapshot, once per fanned-out unit for a partitioned watermark endpoint), then
+``finalize`` once. The single-file date-window cell remains unbuilt.
+"""
+
+from typing import Protocol
+
+import polars as pl
+
+from fleetpull.endpoints.shared import (
+    EndpointDefinition,
+    FeedMode,
+    SnapshotMode,
+    StorageKind,
+    WatermarkMode,
+)
+from fleetpull.incremental import DateWindow
+from fleetpull.model_contract import ResponseModel
+from fleetpull.paths import PathInput, endpoint_directory
+from fleetpull.storage.append import FeedAppendWriter
+from fleetpull.storage.partitioned import WatermarkPartitionedWriter
+from fleetpull.storage.result import WriteResult
+from fleetpull.storage.single_file import SnapshotWriter
+
+__all__: list[str] = ['DatasetWriter', 'select_writer']
+
+
+class DatasetWriter(Protocol):
+    """The storage write surface: accept records in pieces, finalize to disk.
+
+    An implementation is constructed for one endpoint's one run, with any runtime
+    context that run needs (e.g. an incremental ``window``). The orchestrator calls
+    ``write`` for each frame it has, then ``finalize`` once. A plain Protocol --
+    composed and called through ``select_writer``, never dynamically verified.
+    """
+
+    def write(self, frame: pl.DataFrame) -> None:
+        """Accept one piece of this run's records.
+
+        Args:
+            frame: A validated, flattened frame for this endpoint. Called at least
+                once per run (a zero-row but typed frame is valid).
+        """
+        ...
+
+    def finalize(self) -> WriteResult:
+        """Finalize the accepted records onto disk and report the write.
+
+        Returns:
+            The write report.
+        """
+        ...
+
+
+def select_writer(
+    definition: EndpointDefinition[ResponseModel],
+    dataset_root: PathInput,
+    *,
+    window: DateWindow | None = None,
+    drop_duplicates: bool = True,
+) -> DatasetWriter:
+    """Construct the writer for an endpoint's ``(StorageKind, SyncMode)`` cell.
+
+    The single routing point. Resolves the endpoint directory under
+    ``dataset_root`` and returns the cell's writer, constructed with the runtime
+    context that cell needs. ``window`` is the run's resume window -- consumed by
+    the incremental writers (the prune, the window-clear) and forbidden for the
+    snapshot cell, which has no resume.
+
+    Args:
+        definition: The endpoint binding; supplies the provider / endpoint
+            directory names and the storage-kind / sync-mode cell.
+        dataset_root: The dataset root directory.
+        window: The run's half-open resume window, for incremental cells.
+        drop_duplicates: Whether the writer's compaction drops exact-duplicate
+            rows (``storage.drop_exact_duplicates``, default on).
+
+    Returns:
+        The cell's ``DatasetWriter``.
+
+    Raises:
+        ValueError: A ``window`` was supplied for the snapshot or feed cell.
+        RuntimeError: An event-time-requiring cell carries no
+            ``event_time_column`` (via ``required_event_time_column`` --
+            impossible past construction validation).
+        NotImplementedError: The endpoint's cell is not yet built (the
+            single-file date-window cell).
+
+    Side Effects:
+        None.
+    """
+    target_dir = endpoint_directory(
+        dataset_root, definition.provider.value, definition.name
+    )
+    match (definition.storage_kind, definition.sync_mode):
+        case (StorageKind.SINGLE, SnapshotMode()):
+            if window is not None:
+                raise ValueError(
+                    f'{definition.provider.value}.{definition.name}: snapshot '
+                    f'endpoints have no resume window.'
+                )
+            return SnapshotWriter(target_dir, drop_duplicates=drop_duplicates)
+        case (StorageKind.APPEND_LOG, FeedMode()):
+            if window is not None:
+                raise ValueError(
+                    f'{definition.provider.value}.{definition.name}: feed '
+                    f'endpoints have no resume window.'
+                )
+            # drop_duplicates is deliberately not threaded: the append-log
+            # cell performs no write-time dedup by design (stored-as-emitted,
+            # DESIGN section 4; storage/append.py carries the rationale).
+            return FeedAppendWriter(target_dir, definition.required_event_time_column)
+        case (StorageKind.DATE_PARTITIONED, WatermarkMode()):
+            if window is None:
+                raise ValueError(
+                    f'{definition.provider.value}.{definition.name}: a watermark '
+                    f'date-partitioned endpoint requires a resume window.'
+                )
+            return WatermarkPartitionedWriter(
+                target_dir,
+                definition.required_event_time_column,
+                window,
+                drop_duplicates=drop_duplicates,
+            )
+        case _:
+            raise NotImplementedError(
+                f'no writer for storage_kind={definition.storage_kind} '
+                f'sync_mode={type(definition.sync_mode).__name__} yet '
+                f'(the single-file watermark cell is not built)'
+            )

fleetpull/timing/__init__.py

@@ -0,0 +1,21 @@
+# src/fleetpull/timing/__init__.py
+"""Injectable time abstraction (Clock, Sleeper), pure UTC datetime conversions,
+and the canonical-UTC surface (ensure_utc / require_utc)."""
+
+from fleetpull.timing.canon import ensure_utc, require_utc
+from fleetpull.timing.clock import Clock, FrozenClock, SystemClock
+from fleetpull.timing.codec import from_iso8601, to_iso8601, to_utc_date_string
+from fleetpull.timing.sleeper import Sleeper, SystemSleeper
+
+__all__: list[str] = [
+    'Clock',
+    'FrozenClock',
+    'Sleeper',
+    'SystemClock',
+    'SystemSleeper',
+    'ensure_utc',
+    'from_iso8601',
+    'require_utc',
+    'to_iso8601',
+    'to_utc_date_string',
+]

fleetpull/timing/canon.py

@@ -0,0 +1,92 @@
+# src/fleetpull/timing/canon.py
+"""The canonical-UTC surface: normalize at ingress, require in the interior.
+
+The canonical interior temporal form is exactly one: a timezone-aware
+``datetime`` whose ``tzinfo is datetime.UTC`` -- identity, not offset-equality.
+``datetime.date`` serves calendar concepts (timezone-free by nature); strings
+exist only at wire/storage edges via the codec. Two verbs enforce the form:
+
+    - **Ingress normalizes** (``ensure_utc``): any function bringing a temporal
+      value into the domain -- from a string, from a Polars frame, from config
+      -- converts it to canonical form, rejecting only the genuinely ambiguous
+      (a naive value is never assumed UTC). ``from_iso8601`` is the string
+      twin of this datetime-object verb.
+    - **Interior and egress require** (``require_utc``): strict identity
+      checks, never loosened. A strict failure in the interior means an
+      ingress was missed -- the fix is adding the missing ``ensure_utc``
+      boundary, never weakening the guard.
+
+Identity rather than offset-equality is deliberate: a zero-offset foreign
+tzinfo (Polars materializes ``zoneinfo.ZoneInfo('UTC')``; pydantic-core tags
+its own ``TzInfo``) is the fingerprint of a value that entered the domain
+without normalizing. An offset-equality check would accept it and mask the
+missed ingress; the identity check finds it -- it is what caught the live
+watermark-serialization crash.
+
+Bad input raises stdlib ``ValueError``, never a ``FleetpullError`` -- a bad
+temporal value is a caller bug or malformed input, and keeping the raise
+stdlib is what lets ``timing`` stay a leaf below ``exceptions``, importing
+nothing internal (the codec stance).
+"""
+
+from datetime import UTC, datetime
+
+__all__: list[str] = [
+    'ensure_utc',
+    'require_utc',
+]
+
+
+def ensure_utc(moment: datetime) -> datetime:
+    """
+    Normalize an aware datetime to canonical UTC; reject a naive one.
+
+    The ingress verb: converts via ``astimezone(UTC)`` so the result's tzinfo
+    *is* ``datetime.UTC`` regardless of the source tag (a foreign
+    ``ZoneInfo('UTC')``, a fixed offset). A naive datetime is ambiguous and is
+    rejected, never assumed UTC -- the ``from_iso8601`` stance.
+
+    Args:
+        moment: The aware datetime to normalize.
+
+    Returns:
+        The same instant with ``tzinfo`` ``datetime.UTC``.
+
+    Raises:
+        ValueError: If ``moment`` is naive.
+    """
+    if moment.tzinfo is None:
+        raise ValueError(
+            'datetime must be timezone-aware to normalize; got a naive value '
+            '(never assumed UTC)'
+        )
+    return moment.astimezone(UTC)
+
+
+def require_utc(moment: datetime) -> datetime:
+    """
+    Validate that ``moment`` is canonical UTC; return it unchanged.
+
+    The guard verb: the check is identity against ``datetime.UTC``. The whole
+    codebase produces UTC datetimes via ``datetime.UTC`` / ``tz=UTC``, so a
+    different tzinfo -- even a zero-offset one -- signals a value that did not
+    pass an ingress (``ensure_utc`` / ``from_iso8601``) and is rejected rather
+    than silently coerced.
+
+    Args:
+        moment: The datetime to validate.
+
+    Returns:
+        ``moment`` unchanged, once validated.
+
+    Raises:
+        ValueError: If ``moment`` is naive, or its tzinfo is not
+            ``datetime.UTC``.
+    """
+    if moment.tzinfo is None:
+        raise ValueError('datetime must be timezone-aware (UTC); got a naive value')
+    if moment.tzinfo is not UTC:
+        raise ValueError(
+            f'datetime must use datetime.UTC; got tzinfo={moment.tzinfo!r}'
+        )
+    return moment