fleetpull 0.1.0__py3-none-any.whl

fleetpull/endpoints/shared/request_shape.py

@@ -0,0 +1,227 @@
+# src/fleetpull/endpoints/shared/request_shape.py
+"""Request cardinality as one closed axis: the ``RequestShape`` union.
+
+How one endpoint run decomposes into request chains is a single concept
+and a single closed choice, exactly like ``SyncMode`` -- so it is one
+tagged union, not a field per pattern. ``EndpointDefinition`` declares
+exactly one member on ``request_shape``; the orchestrator's shape
+resolution (``orchestrator/shape_resolution.py``) matches over the union
+to pick the request driver. A future cardinality pattern is a new union
+member plus its resolution arm -- the definition's field set never
+changes for one again (unified 2026-07-20; DESIGN section 14 carries the
+decision record).
+
+Members: ``SingleFetch`` (one chain -- the default), ``RosterFanOut``
+(one chain per roster member), ``BatchedRosterFanOut`` (one chain per
+fixed-size batch of roster members, the batch comma-joined into one
+query-parameter value), ``BisectedWindowFetch`` (the unit window
+fetched whole, halved adaptively on the capped-response overflow
+signal), and ``ParamSweep`` (one chain per declared query-parameter
+value).
+"""
+
+from dataclasses import dataclass
+from datetime import timedelta
+
+from fleetpull.roster import RosterKey
+
+__all__: list[str] = [
+    'BatchedRosterFanOut',
+    'BisectedWindowFetch',
+    'ParamSweep',
+    'RequestShape',
+    'RosterFanOut',
+    'SingleFetch',
+]
+
+
+@dataclass(frozen=True, slots=True)
+class SingleFetch:
+    """One request chain: the default request shape, a marker.
+
+    The endpoint's whole run is one chain -- the spec-builder's first
+    request plus every page the decoder walks. Declared implicitly:
+    ``EndpointDefinition.request_shape`` defaults to this marker, so a
+    single-chain leaf declares nothing.
+    """
+
+
+@dataclass(frozen=True, slots=True)
+class RosterFanOut:
+    """One request chain per roster member.
+
+    The shape for endpoints that fan a request out over per-entity keys
+    (the per-vehicle ``vehicle_locations`` endpoint). Names only a
+    ``RosterKey``: the consumer knows *that* a roster of its keys
+    exists, never where those keys come from. The source endpoint and
+    column -- and so the feeder -- live in the ``RosterDefinition`` the
+    ``RosterRegistry`` holds, keyed by that ``RosterKey``; the
+    orchestration entry reads the members from the ``RosterStore``, also
+    keyed by it. That indirection keeps the consumer ignorant of the
+    feeder: ``vehicle_locations`` references
+    ``RosterKey(MOTIVE, 'vehicle_ids')`` and nothing about ``vehicles``.
+
+    Attributes:
+        roster: The roster supplying this endpoint's fan-out members --
+            the opaque handle; the source endpoint and column live in
+            the registry's ``RosterDefinition``, not here.
+        member_key: The key under which each member lands in the
+            spec-builder's ``member_values``. The spec builder owns the
+            interpretation; for URL-path endpoints it is the path
+            template placeholder (e.g. ``'vehicle_id'`` for
+            ``'/v3/vehicle_locations/{vehicle_id}'``), which the strict
+            renderer enforces at request build.
+    """
+
+    roster: RosterKey
+    member_key: str
+
+
+@dataclass(frozen=True, slots=True)
+class BatchedRosterFanOut:
+    """One request chain per fixed-size batch of roster members.
+
+    The shape for surfaces that REQUIRE a member-id filter and enforce a
+    batch cap on it (first consumer: Samsara asset_locations, where an
+    id-less request is a loud HTTP 400 and 51+ comma-joined ids another
+    -- the API-enforced 50-id cap, captured 2026-07-20). The roster
+    indirection is ``RosterFanOut``'s verbatim: only the ``RosterKey``
+    is named here, and the shape resolution reads the membership through
+    the same refresh-then-read machinery path.
+
+    The batch is TRANSPORT PACKING only: each chain fetches a batch's
+    records in one walk, and every record self-identifies its member
+    (per-record asset attribution on the wire), so no member attribution
+    rides on the request mapping -- unlike a ``RosterFanOut`` chain,
+    whose responses may not echo the requested member. Batches are
+    deterministic: members are sorted before chunking, so identical
+    rosters always produce identical batches.
+
+    Attributes:
+        roster: The roster supplying the members packed into batches --
+            the opaque handle, exactly ``RosterFanOut.roster``.
+        member_key: The key each batch's comma-joined member string
+            binds under in the spec-builder's ``member_values`` -- for a
+            query-parameter surface, the verbatim wire parameter (e.g.
+            ``'ids'``). The spec builder owns the interpretation.
+        batch_size: The maximum members per chain -- the provider's
+            API-enforced cap, declared from probe evidence. At least 1;
+            a roster smaller than one batch fans a single chain.
+    """
+
+    roster: RosterKey
+    member_key: str
+    batch_size: int
+
+    def __post_init__(self) -> None:
+        """Reject a batch size that could not pack a request.
+
+        Raises:
+            ValueError: ``batch_size`` is less than 1 -- a zero or
+                negative batch packs nothing and would silently fetch
+                nothing, a declaration bug rejected at construction.
+
+        Side Effects:
+            None -- reads fields and may raise.
+        """
+        if self.batch_size < 1:
+            raise ValueError(
+                f'BatchedRosterFanOut({self.roster.name!r}): batch_size must '
+                f'be >= 1, got {self.batch_size} -- a batch that packs no '
+                f'members is a declaration bug, not an empty fan-out.'
+            )
+
+
+@dataclass(frozen=True, slots=True)
+class BisectedWindowFetch:
+    """The unit window fetched whole, halved adaptively on overflow.
+
+    The shape for a capped, unsortable Get endpoint (GeoTab
+    ExceptionEvent: the silent 5,000 cap plus id-sort rejected outright
+    -- DESIGN section 8, captured 2026-07-15): fetch the window whole; a
+    response of exactly the declared limit is the overflow signal;
+    discard it, halve the window, recurse; a floor-width window still
+    coming back full fails loudly. Executed by the orchestrator's
+    ``BisectingWindowDriver`` -- this declaration carries the provider
+    facts the provider-agnostic driver cannot know.
+
+    Attributes:
+        results_limit: The per-request record limit the endpoint's spec
+            builder writes; a response of exactly this many records is
+            the overflow signal. Sound only where the provider's silent
+            cap is Captured at or above this value for the entity type
+            (a lower cap would make every page look partial and overflow
+            undetectable).
+        floor: The minimum window width. A floor-width window still
+            returning ``results_limit`` records raises loudly -- the
+            data is denser than windowed fetching can enumerate, or more
+            than ``results_limit`` records overlap a single instant,
+            which no window width resolves.
+        event_time_wire_key: The raw wire key carrying each record's
+            owning timestamp (e.g. ``'activeFrom'``) -- pre-model, so the
+            driver can assign each record to exactly one leaf window
+            under overlap-matched retrieval instead of leaning on
+            write-time dedup for correctness.
+    """
+
+    results_limit: int
+    floor: timedelta
+    event_time_wire_key: str
+
+
+@dataclass(frozen=True, slots=True)
+class ParamSweep:
+    """One request chain per declared query-parameter value.
+
+    The shape for endpoints whose provider partitions the population
+    behind a mandatory closed-enum filter with no all-values request
+    (first consumer: Samsara drivers, where the default listing is only
+    the active set). The union of the sweeps is the endpoint's one
+    complete dataset -- the sweep is completeness machinery, never a
+    member filter.
+
+    Attributes:
+        param: The member key the spec builder merges as a query
+            parameter -- each sweep value lands in ``member_values``
+            under this key.
+        values: The closed, ordered value set, one chain each. Never
+            empty and never duplicated -- either is a wiring bug
+            rejected at construction.
+    """
+
+    param: str
+    values: tuple[str, ...]
+
+    def __post_init__(self) -> None:
+        """Reject a sweep that could not be a complete dataset.
+
+        Raises:
+            ValueError: ``values`` is empty (a sweep over nothing fetches
+                nothing and would silently emit an empty dataset) or
+                carries a duplicate (the same partition fetched twice is
+                a declaration typo, not a wider sweep).
+
+        Side Effects:
+            None -- reads fields and may raise.
+        """
+        if not self.values:
+            raise ValueError(
+                f'ParamSweep({self.param!r}): values must not be empty -- '
+                f'a sweep over nothing is a wiring bug, not an empty dataset.'
+            )
+        if len(set(self.values)) != len(self.values):
+            raise ValueError(
+                f'ParamSweep({self.param!r}): values carry a duplicate -- '
+                f'each declared value is one partition of the population, '
+                f'fetched exactly once.'
+            )
+
+
+# The endpoint's request-cardinality declaration (config): the shape
+# resolution matches on it to pick the request driver -- SingleFetch ->
+# SingleRequestDriver, RosterFanOut / BatchedRosterFanOut / ParamSweep ->
+# FanOutRequestDriver, BisectedWindowFetch -> BisectingWindowDriver. One
+# declared member per endpoint; mutual exclusion is structural.
+type RequestShape = (
+    SingleFetch | RosterFanOut | BatchedRosterFanOut | BisectedWindowFetch | ParamSweep
+)

fleetpull/endpoints/shared/resume.py

@@ -0,0 +1,74 @@
+# src/fleetpull/endpoints/shared/resume.py
+"""The shared resume-value type guards.
+
+Every incremental spec-builder's first act is the same proof: the
+``ResumeValue`` it was handed is the shape its endpoint always resumes from
+-- the ``DateWindow`` for a watermark endpoint, a ``FeedToken`` or
+``FeedSeed`` for a feed endpoint -- and anything else is a wiring bug that
+must fail loudly before a request is built. The guards are pure type
+narrowings with no provider-specific behavior, so they live on the shared
+surface -- placement here couples nothing.
+"""
+
+from fleetpull.endpoints.shared.base import ResumeValue
+from fleetpull.incremental import DateWindow, FeedResume, FeedSeed, FeedToken
+
+__all__: list[str] = ['require_date_window', 'require_feed_resume']
+
+
+def require_date_window(resume: ResumeValue, requirer: str) -> DateWindow:
+    """Narrow a resume value to the ``DateWindow`` a watermark run carries.
+
+    Args:
+        resume: The resume value handed to a spec-builder -- a
+            ``DateWindow`` for a watermark endpoint; any other value is a
+            wiring bug.
+        requirer: The name blamed in the error, conventionally the
+            calling builder's class name.
+
+    Returns:
+        ``resume``, narrowed to ``DateWindow``.
+
+    Raises:
+        TypeError: ``resume`` is not a ``DateWindow``.
+
+    Side Effects:
+        None.
+    """
+    if not isinstance(resume, DateWindow):
+        raise TypeError(
+            f'{requirer} requires a DateWindow resume, got {type(resume).__name__}.'
+        )
+    return resume
+
+
+def require_feed_resume(resume: ResumeValue, requirer: str) -> FeedResume:
+    """Narrow a resume value to the seed-or-token a feed run carries.
+
+    A feed endpoint always resumes from something -- the cold-start
+    ``FeedSeed`` on the tokenless first run, the stored ``FeedToken`` on
+    every run after -- so ``None`` (like any other shape) is a wiring bug,
+    not a bootstrap case.
+
+    Args:
+        resume: The resume value handed to a spec-builder -- a ``FeedSeed``
+            or ``FeedToken`` for a feed endpoint; any other value is a
+            wiring bug.
+        requirer: The name blamed in the error, conventionally the
+            calling builder's class name.
+
+    Returns:
+        ``resume``, narrowed to ``FeedSeed | FeedToken``.
+
+    Raises:
+        TypeError: ``resume`` is neither a ``FeedSeed`` nor a ``FeedToken``.
+
+    Side Effects:
+        None.
+    """
+    if not isinstance(resume, FeedSeed | FeedToken):
+        raise TypeError(
+            f'{requirer} requires a FeedSeed or FeedToken resume, '
+            f'got {type(resume).__name__}.'
+        )
+    return resume

fleetpull/endpoints/shared/spec_builders.py

@@ -0,0 +1,59 @@
+# src/fleetpull/endpoints/shared/spec_builders.py
+"""Shared spec-builders: SpecBuilder implementations with no per-provider
+or per-endpoint behavior.
+
+A snapshot endpoint's first request is just ``GET base_url + path``: it
+translates no resume value (``SnapshotMode`` always passes
+``resume=None``) and binds no member, so its spec-builder carries
+no provider- or endpoint-specific logic and is shared across every
+snapshot binding. Per-provider resume translation -- watermark windows,
+feed tokens -- lives in dedicated builders beside their bindings, never
+here.
+"""
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+from fleetpull.endpoints.shared.base import ResumeValue
+from fleetpull.network.contract import HttpMethod, RequestSpec
+
+__all__: list[str] = ['StaticGetSpecBuilder']
+
+
+@dataclass(frozen=True, slots=True)
+class StaticGetSpecBuilder:
+    """Build a fixed ``GET base_url + path`` first request.
+
+    The spec-builder for endpoints with no resume value and no per-chain
+    member binding (single-chain snapshots). Both ``build_spec`` arguments
+    are accepted to satisfy the ``SpecBuilder`` protocol but are
+    intentionally unused: a snapshot resumes from nothing, and a
+    single-chain endpoint binds no member.
+
+    Attributes:
+        base_url: Root of the provider API, trailing-slash-normalized by
+            the provider config so a leading-slash path joins directly.
+        path: The endpoint's leading-slash request path (e.g.
+            ``'/v1/vehicles'``).
+    """
+
+    base_url: str
+    path: str
+
+    def build_spec(
+        self, resume: ResumeValue, member_values: Mapping[str, str]
+    ) -> RequestSpec:
+        """Build the fixed first request.
+
+        Args:
+            resume: Accepted to satisfy the protocol; unused -- a snapshot
+                resumes from nothing.
+            member_values: Accepted to satisfy the protocol; unused -- a
+                single-chain endpoint binds no member.
+
+        Returns:
+            A credential-less ``GET`` for ``base_url + path``. Auth headers
+            are layered on by the client's ``ProviderProfile``; pagination
+            parameters are injected by the page decoder's ``first_request``.
+        """
+        return RequestSpec(method=HttpMethod.GET, url=f'{self.base_url}{self.path}')

fleetpull/endpoints/shared/sync_mode.py

@@ -0,0 +1,159 @@
+# src/fleetpull/endpoints/shared/sync_mode.py
+"""The sync-mode and storage-layout declaration family.
+
+The two declared axes every ``EndpointDefinition`` carries (the
+``request_shape.py`` family precedent -- one declaration family per file):
+``StorageKind`` is the §3 storage *layout* (where the bytes live), and the
+``SyncMode`` union (``SnapshotMode`` / ``WatermarkMode`` / ``FeedMode``) is
+the resume-and-write *semantic* (how a run resumes and what its write does to
+the data). The two are orthogonal; the valid pairings are validated on the
+binding (``base.py``) at construction.
+"""
+
+from dataclasses import dataclass
+from datetime import timedelta
+from enum import StrEnum
+
+__all__: list[str] = [
+    'FeedMode',
+    'SnapshotMode',
+    'StorageKind',
+    'SyncMode',
+    'WatermarkMode',
+]
+
+
+class StorageKind(StrEnum):
+    """
+    The §3 storage *layout* an endpoint declares: one parquet file vs hive
+    partitions. Layout only — *where* the bytes live, not how they merge.
+
+    ``SINGLE`` is one ``data.parquet``; ``DATE_PARTITIONED`` is hive
+    ``date=YYYY-MM-DD`` partitions; ``APPEND_LOG`` is hive ``date=`` partitions
+    holding numbered ``part-NNNNN.parquet`` files that only ever accumulate —
+    the feed arm's append-only layout, where nothing is ever deleted or
+    replaced. The caller dispatches on it to pick the storage path —
+    read-the-whole-file for ``SINGLE``, touch-only-overlapping-partitions for
+    ``DATE_PARTITIONED``, append-new-parts-only for ``APPEND_LOG``. What that
+    write *does* to the data — full-replace, delete-by-window-then-append, or
+    append — is the ``SyncMode``'s concern, not the layout's; the two are
+    orthogonal axes the storage layer combines (``APPEND_LOG`` pairs only with
+    ``FeedMode``, validated at construction: append-only is the feed stream's
+    write semantic, and every windowed or snapshot semantic would corrupt an
+    accumulate-only layout).
+
+    It lives here beside the binding, not in ``vocabulary/``: unlike
+    ``QuotaScope``
+    (which config validates against, so it must sit in a leaf config can import),
+    ``StorageKind`` has no low-layer consumer — it travels with the
+    ``EndpointDefinition`` it configures.
+    """
+
+    SINGLE = 'single'
+    DATE_PARTITIONED = 'date_partitioned'
+    APPEND_LOG = 'append_log'
+
+
+@dataclass(frozen=True, slots=True)
+class SnapshotMode:
+    """
+    Snapshot sync declaration (config): a marker carrying no configuration.
+
+    The endpoint re-fetches its full current-state dataset every run and has no
+    resume — its spec-builder always receives ``resume=None`` (no window, no
+    token). Its write semantic is *full replacement* of the endpoint's current-
+    state dataset. A marker member of ``SyncMode``. Snapshot has no event-time
+    dimension to partition on, so a snapshot endpoint must be laid out
+    ``SINGLE`` — ``EndpointDefinition`` enforces that pairing at construction,
+    since ``DATE_PARTITIONED`` would have no event-time column to split on.
+    """
+
+
+@dataclass(frozen=True, slots=True)
+class WatermarkMode:
+    """
+    Watermark sync declaration (config): the late-arrival lookback margin.
+
+    The endpoint's sync *declaration*, distinct from the runtime
+    ``IncrementalCursor`` *state* in ``incremental/``: this configures how a fetch
+    resumes; the cursor is what it resumes from. Its write semantic is
+    *delete-by-window, then append* — the refetched window is cleared and replaced,
+    so late arrivals and in-window corrections land cleanly. ``lookback`` is the
+    margin the resume resolver subtracts from the stored watermark (§4) so late-
+    arriving records inside it are re-fetched; the resolver then floors the
+    start to its UTC midnight, so a lookback of N days re-covers N whole days
+    before the watermark's day. ``cutoff`` is the complementary
+    trailing-edge holdback: the window's end is held back this far from the clock
+    so a still-arriving day is never frozen as a complete partition. Both express
+    one physical concern -- provider data latency -- from opposite ends, so both
+    are sourced from the provider config (``lookback_days`` / ``cutoff_days``),
+    not defaulted on the mode.
+
+    Attributes:
+        lookback: How far before the watermark each resume re-fetches, to recover
+            records that landed after their event-time day.
+        cutoff: How far the window's end is held back from the clock, so the most
+            recent written partition is always a complete day. Day-granular; zero
+            adds no holdback beyond the resolver's own date alignment.
+        fixed_unit_days: The endpoint's fixed work-unit width in whole days, or
+            ``None`` (the default) to tile at ``sync.backfill_chunk_days``. Set
+            only by endpoints whose rows are per-request-window rollups: the
+            provider aggregates over exactly the requested window, so the unit
+            width is part of the ROW'S MEANING and must never float with user
+            configuration — the Samsara fuel-energy probe proved day rollups are
+            NOT a lossless decomposition of wider windows (summing two adjacent
+            day windows reproduced the two-day rollup on only 178 of 267
+            vehicles; DESIGN §8, 2026-07-21). When set, the window planner tiles
+            this endpoint's resume window into units of exactly this many days,
+            ignoring ``sync.backfill_chunk_days``; the config knob remains the
+            default for every endpoint that leaves this ``None``. Validated
+            >= 1 at construction.
+    """
+
+    lookback: timedelta
+    cutoff: timedelta
+    fixed_unit_days: int | None = None
+
+    def __post_init__(self) -> None:
+        """Validate the fixed unit width when one is declared.
+
+        Raises:
+            ValueError: ``fixed_unit_days`` is set but not >= 1 — a
+                zero-or-negative unit width can tile nothing.
+
+        Side Effects:
+            None -- reads fields and may raise.
+        """
+        if self.fixed_unit_days is not None and self.fixed_unit_days < 1:
+            raise ValueError(
+                f'fixed_unit_days must be >= 1 when set, got {self.fixed_unit_days}.'
+            )
+
+
+@dataclass(frozen=True, slots=True)
+class FeedMode:
+    """
+    Feed sync declaration (config): a marker carrying no configuration.
+
+    The feed arm needs no config — its resume value is the stored ``FeedToken``
+    used directly (no lookback, no window), or a ``FeedSeed`` from the sync-wide
+    cold-start anchor on the tokenless first run. Its write semantic is
+    *append-only*: the feed is a forward-only version stream stored as emitted
+    — every run appends new numbered part files into the event-date partitions
+    its records belong to, and nothing is ever deleted or replaced (DESIGN §4).
+    Re-emitted versions and crash-window duplicates land as new rows; the
+    consumer reconciles calculated feeds by ``(id, max version)`` and active
+    feeds by ``id``. A ``FeedMode`` endpoint therefore requires the
+    ``APPEND_LOG`` layout and an ``event_time_column`` (the records' own event
+    dates route the partitions), both validated at construction. A marker
+    member of ``SyncMode``, distinct from the runtime ``FeedToken`` cursor
+    state in ``incremental/``.
+    """
+
+
+# The endpoint's sync-mode declaration (config): the caller matches on it to drive
+# both resume and write semantics — SnapshotMode -> no resume + full replace,
+# WatermarkMode -> resume resolver + delete-by-window-then-append, FeedMode -> the
+# stored token (or cold-start seed) + append-only. Storage layout (StorageKind) is
+# the orthogonal axis.
+type SyncMode = SnapshotMode | WatermarkMode | FeedMode

fleetpull/endpoints/shared/url_paths.py

@@ -0,0 +1,149 @@
+# src/fleetpull/endpoints/shared/url_paths.py
+"""Strict URL-path template rendering for endpoint fan-out paths.
+
+A pure leaf -- stdlib only, imports nothing internal. It renders a small, closed
+template dialect: a URL path may carry named ``{placeholder}`` segments and
+nothing else. Python's general ``str.format`` grammar (format specs, conversions,
+attribute/item access, ``{{`` escapes) is deliberately not borrowed -- defining
+the tiny dialect we want is less surface than subtracting the features we do not
+from a large one.
+
+Strict both ways and loud on any mismatch: the placeholder set must equal the
+supplied-value key set (a missing or unused key is a binding/fan-out bug), no
+value may be empty, and a template with malformed braces is rejected. Substituted
+values are URL-encoded as a single path segment (``quote(..., safe='')``), so a
+value like ``'abc/123'`` becomes ``'abc%2F123'`` and can never restructure the
+path. That encoding is also load-bearing for safety: because an encoded value can
+contain neither ``{`` nor ``}``, the literal placeholder replacement below can
+never have a substituted value forge a second placeholder.
+
+Errors are ``UrlPathTemplateError`` (a ``ValueError`` subclass defined here,
+importing nothing internal) -- a template/key mismatch is a programmer bug with no
+user input in the loop, so it raises and stays stdlib-typed, exactly as the timing
+codec does.
+"""
+
+import re
+from collections.abc import Mapping
+from urllib.parse import quote
+
+__all__: list[str] = ['UrlPathTemplateError', 'render_url_path_template']
+
+_PLACEHOLDER_PATTERN = re.compile(r'\{([A-Za-z_][A-Za-z0-9_]*)\}')
+
+
+class UrlPathTemplateError(ValueError):
+    """Raised when a URL-path template or its supplied values are invalid."""
+
+
+def render_url_path_template(path_template: str, path_values: Mapping[str, str]) -> str:
+    """Render a strict URL-path template, URL-encoding each substituted value.
+
+    Args:
+        path_template: A URL path with zero or more named ``{placeholder}``
+            segments (e.g. ``'/v3/vehicle_locations/{vehicle_id}'``). Only named
+            placeholders are supported; format specs, conversions, attribute or
+            item access, and escaped braces are not.
+        path_values: The substitution values. Its key set must exactly equal the
+            template's placeholder set, and no value may be empty.
+
+    Returns:
+        The rendered path with every placeholder replaced by its URL-encoded
+        (single-segment) value. A template with no placeholders and an empty
+        mapping is returned unchanged.
+
+    Raises:
+        UrlPathTemplateError: The template has malformed or unsupported braces;
+            the value keys do not exactly match the placeholders (missing or
+            unused keys); or a supplied value is empty.
+
+    Side Effects:
+        None -- pure function.
+    """
+    placeholder_names = _extract_placeholder_names(path_template)
+
+    expected = set(placeholder_names)
+    supplied = set(path_values)
+    if expected != supplied:
+        raise UrlPathTemplateError(
+            _mismatch_message(
+                path_template=path_template,
+                missing=expected - supplied,
+                unused=supplied - expected,
+            )
+        )
+
+    rendered = path_template
+    for placeholder_name in placeholder_names:
+        value = path_values[placeholder_name]
+        if value == '':
+            raise UrlPathTemplateError(
+                f'URL path value {placeholder_name!r} must not be empty.'
+            )
+        # safe='' encodes every reserved character, so the value is a single
+        # inert path segment. The literal replace below relies on this: an
+        # encoded value contains no braces, so it cannot forge a placeholder.
+        rendered = rendered.replace(f'{{{placeholder_name}}}', quote(value, safe=''))
+    return rendered
+
+
+def _extract_placeholder_names(path_template: str) -> tuple[str, ...]:
+    """Extract a template's placeholder names in first-seen order.
+
+    A repeated placeholder is returned once -- it must take a single value. Any
+    brace left after removing every valid placeholder means the template has
+    malformed or unsupported brace syntax, which raises.
+
+    Args:
+        path_template: The template to inspect.
+
+    Returns:
+        The distinct placeholder names, in first-seen order.
+
+    Raises:
+        UrlPathTemplateError: The template contains malformed or unsupported brace
+            syntax (a dangling brace, or a non-named-placeholder use).
+
+    Side Effects:
+        None -- pure function.
+    """
+    residual = _PLACEHOLDER_PATTERN.sub('', path_template)
+    if '{' in residual or '}' in residual:
+        raise UrlPathTemplateError(
+            'URL path template has malformed or unsupported brace syntax: '
+            f"{path_template!r}. Only named placeholders like '{{vehicle_id}}' "
+            'are supported.'
+        )
+
+    seen: set[str] = set()
+    ordered_names: list[str] = []
+    for match in _PLACEHOLDER_PATTERN.finditer(path_template):
+        name = match.group(1)
+        if name not in seen:
+            seen.add(name)
+            ordered_names.append(name)
+    return tuple(ordered_names)
+
+
+def _mismatch_message(path_template: str, missing: set[str], unused: set[str]) -> str:
+    """Build a precise placeholder/value mismatch message.
+
+    Args:
+        path_template: The template being rendered.
+        missing: Placeholder names the template needs but the values omit.
+        unused: Value keys the caller supplied but the template never uses.
+
+    Returns:
+        A human-readable validation message naming the missing and unused keys.
+
+    Side Effects:
+        None -- pure function.
+    """
+    parts = [f'URL path values do not match placeholders for {path_template!r}.']
+    if missing:
+        names = ', '.join(repr(name) for name in sorted(missing))
+        parts.append(f'Missing: {names}.')
+    if unused:
+        names = ', '.join(repr(name) for name in sorted(unused))
+        parts.append(f'Unused: {names}.')
+    return ' '.join(parts)