fleetpull 0.1.0__py3-none-any.whl

fleetpull/orchestrator/resume.py

@@ -0,0 +1,143 @@
+# src/fleetpull/orchestrator/resume.py
+"""The incremental arms' pure resume decisions: interpret the stored cursor.
+
+Pure functions, no I/O and no ``self``: ``resolve_watermark_start`` turns the
+stored cursor into resume arm 1 (the watermark less the lookback margin), carrying
+the future-watermark guard (Guard A) and the cross-mode rejection that
+``incremental/resolution.py`` deliberately omits (that module is cursor-free, so
+cursor interpretation and its guards are the orchestrator's policy);
+``resolve_feed_resume`` is the feed arm's mirror -- the stored token used
+directly, the cold-start ``FeedSeed`` when none is stored (the seed-once
+invariant's structural half, DESIGN section 14 I4), and the same cross-mode
+rejection in the other direction. The
+strictly-forward advance discipline that once lived beside them moved into the
+cursor store's atomic ``advance_watermark_forward`` with the prefix-advance rule
+(DESIGN section 5, 2026-07-20) -- concurrent unit completions cannot enforce
+monotonicity race-free from outside the statement. The runner reads and writes
+the cursor; this only computes and validates, following the ``batch.py``
+precedent that the runner's pure logic lives beside it, not on the class.
+"""
+
+from datetime import datetime, timedelta
+
+from fleetpull.exceptions import ConfigurationError
+from fleetpull.incremental import (
+    DateWatermark,
+    FeedResume,
+    FeedSeed,
+    FeedToken,
+    IncrementalCursor,
+)
+from fleetpull.vocabulary import Provider
+
+__all__: list[str] = ['resolve_feed_resume', 'resolve_watermark_start']
+
+
+def resolve_watermark_start(
+    stored: IncrementalCursor | None,
+    lookback: timedelta,
+    now: datetime,
+    provider: Provider,
+    endpoint: str,
+) -> datetime | None:
+    """Resolve resume arm 1 from the stored cursor, guarding a future date.
+
+    Arm 1 of the resume precedence (DESIGN section 4): the committed watermark less
+    the lookback re-fetch margin, or ``None`` when no watermark is committed (the
+    caller then falls through to the coverage frontier and the cold-start
+    anchor). The future-watermark guard (Guard A) and the cross-mode rejection
+    live here -- the resolution math in ``incremental/resolution.py`` is
+    deliberately cursor-free, so cursor interpretation and its guards are the
+    orchestrator's policy.
+
+    Args:
+        stored: The persisted cursor, or ``None`` when none is committed.
+        lookback: The watermark mode's late-arrival re-fetch margin.
+        now: The run's clock instant.
+        provider: The endpoint's provider (error context).
+        endpoint: The endpoint name (error context).
+
+    Returns:
+        The watermark instant less ``lookback`` when a ``DateWatermark`` is
+        stored, else ``None``. This is the datetime-granular arm-1 candidate;
+        ``resolve_resume_start`` floors whichever arm it picks to the UTC
+        midnight of its date (the floored-window invariant).
+
+    Raises:
+        ConfigurationError: The stored watermark is dated after ``now`` (Guard A
+            -- it would otherwise stall the endpoint as a permanent caught-up),
+            or a ``FeedToken`` is stored for this watermark endpoint (cross-mode
+            state corruption).
+
+    Side Effects:
+        None -- pure.
+    """
+    match stored:
+        case None:
+            return None
+        case DateWatermark(watermark=watermark):
+            if watermark > now:
+                raise ConfigurationError(
+                    'stored watermark is in the future',
+                    provider=provider.value,
+                    endpoint=endpoint,
+                    detail=(
+                        f'watermark {watermark.isoformat()} is after the '
+                        f'run clock {now.isoformat()}'
+                    ),
+                )
+            return watermark - lookback
+        case _:
+            raise ConfigurationError(
+                'feed cursor stored for a watermark endpoint',
+                provider=provider.value,
+                endpoint=endpoint,
+            )
+
+
+def resolve_feed_resume(
+    stored: IncrementalCursor | None,
+    default_start: datetime,
+    provider: Provider,
+    endpoint: str,
+) -> FeedResume:
+    """Resolve the feed arm's resume value from the stored cursor.
+
+    The feed mirror of ``resolve_watermark_start``: a stored ``FeedToken``
+    resumes directly (no transformation — DESIGN section 4), and no stored
+    cursor seeds the feed at the sync-wide cold-start anchor. Constructing
+    the ``FeedSeed`` here, and ONLY here, is the structural half of the
+    seed-once invariant (section 14's I4): a resumed run can never carry a
+    seed, because the seed exists only on the no-cursor branch. The
+    cross-mode rejection guards the other direction of the watermark
+    resolver's — a watermark stored for a feed endpoint is state corruption.
+
+    Args:
+        stored: The persisted cursor, or ``None`` when none is committed.
+        default_start: The sync-wide cold-start anchor
+            (``sync.default_start_datetime``) the seed carries.
+        provider: The endpoint's provider (error context).
+        endpoint: The endpoint name (error context).
+
+    Returns:
+        The stored ``FeedToken``, or a ``FeedSeed`` at ``default_start``
+        when no cursor is committed.
+
+    Raises:
+        ConfigurationError: A ``DateWatermark`` is stored for this feed
+            endpoint (cross-mode state corruption).
+
+    Side Effects:
+        None -- pure.
+    """
+    match stored:
+        case None:
+            return FeedSeed(start=default_start)
+        case FeedToken():
+            return stored
+        case _:
+            raise ConfigurationError(
+                'watermark cursor stored for a feed endpoint',
+                provider=provider.value,
+                endpoint=endpoint,
+            )

fleetpull/orchestrator/roster_harvest.py

@@ -0,0 +1,108 @@
+# src/fleetpull/orchestrator/roster_harvest.py
+"""Roster harvest: a feeder's complete current membership as a set of strings.
+
+``harvest_roster_members`` drives a feeder endpoint to a full listing and returns
+the distinct values of its roster column -- the complete current membership the
+refresh hands to ``reconcile``. It drives ``stream_processed_batches`` over the
+feeder (validate-and-frame only, no window filter, no write) and unions
+``extract_roster_members`` across the streamed batches.
+
+The harvest is always a full listing: ``reconcile`` diffs the complete membership
+against the stored roster (anything absent from the listing increments toward
+eviction), so a partial listing would not under-update the roster -- it would evict
+live members. ``resume`` and ``context`` are therefore fixed at ``None`` (the
+validate-and-frame-only path that preserves every row); they are not parameters,
+because a windowed harvest is not a harvest. The feeder must be a full-listing
+(snapshot) endpoint for the same reason; the coordinator that resolves the feeder
+binding guards that, so this stays ``sync_mode``-blind, driving whatever binding it
+is handed.
+
+This owns no state and resolves no client or binding: the coordinator resolves the
+roster's ``source_endpoint`` to its ``EndpointDefinition``, builds the
+``SingleRequestDriver``, opens the provider's client, and calls this.
+"""
+
+from fleetpull.endpoints.shared import EndpointDefinition, SnapshotMode
+from fleetpull.exceptions import ConfigurationError
+from fleetpull.model_contract import ResponseModel
+from fleetpull.network.client import TransportClient
+from fleetpull.orchestrator.drivers import RequestDriver
+from fleetpull.orchestrator.streaming import stream_processed_batches
+from fleetpull.records import extract_roster_members
+
+__all__: list[str] = ['harvest_roster_members', 'require_snapshot_feeder']
+
+
+def require_snapshot_feeder(
+    definition: EndpointDefinition[ResponseModel], source_endpoint: str
+) -> None:
+    """Reject a roster feeder that is not a snapshot endpoint.
+
+    The full-listing requirement, stated once for BOTH reconcile routes --
+    the orchestration entry's feeder tap and the refresh coordinator's
+    harvest: ``reconcile`` is only correct over a complete listing, which
+    only a snapshot-mode feeder produces (a windowed run's partial listing
+    would mass-count absences against every member outside the window). A
+    non-snapshot feeder is a wiring bug, raised loudly before anything runs.
+
+    Args:
+        definition: The feeder endpoint's resolved binding.
+        source_endpoint: The feeder's endpoint name, for the error context.
+
+    Raises:
+        ConfigurationError: The feeder is not snapshot-mode.
+    """
+    if not isinstance(definition.sync_mode, SnapshotMode):
+        raise ConfigurationError(
+            'roster feeder is not a snapshot endpoint',
+            provider=definition.provider.value,
+            endpoint=source_endpoint,
+            detail=(
+                'a roster source must be a full-listing (snapshot) endpoint: '
+                'reconcile is only correct over a complete listing'
+            ),
+        )
+
+
+def harvest_roster_members(
+    definition: EndpointDefinition[ResponseModel],
+    driver: RequestDriver,
+    client: TransportClient,
+    column: str,
+) -> set[str]:
+    """Harvest a feeder's complete current membership as a set of strings.
+
+    Drives the feeder to a full listing and returns the distinct stringified values
+    of ``column`` across every batch -- the complete membership ``reconcile``
+    consumes. The stream runs validate-and-frame only (``resume`` and ``context``
+    ``None``), so no row is filtered out and the listing stays complete.
+
+    Args:
+        definition: The resolved feeder binding to list (its response model, spec
+            builder, and page decoder). Must be a full-listing endpoint; the
+            coordinator guards that before calling.
+        driver: The request driver the feeder is listed with -- a
+            ``SingleRequestDriver`` for the full single-chain listing.
+        client: The feeder provider's open transport client.
+        column: The feeder-frame column whose distinct values are the members (the
+            roster's ``source_column``).
+
+    Returns:
+        The complete current membership -- the distinct values of ``column`` as
+        strings, unioned across batches; empty when the feeder lists nothing.
+
+    Raises:
+        ValueError: ``column`` is absent from a feeder frame (from
+            ``extract_roster_members``) -- surfaced to the coordinator, whose
+            best-effort refresh keeps the existing roster on failure. Null and
+            empty-string values do not raise; the extractor filters them loudly.
+        FleetpullError: A fetch, validation, or framing failure from the stream.
+
+    Side Effects:
+        Issues the feeder's request chain through ``client`` (network I/O); writes
+        nothing.
+    """
+    members: set[str] = set()
+    for batch in stream_processed_batches(definition, driver, client, None, None):
+        members |= extract_roster_members(batch.frame, column)
+    return members

fleetpull/orchestrator/roster_refresh.py

@@ -0,0 +1,363 @@
+# src/fleetpull/orchestrator/roster_refresh.py
+"""The roster refresh coordinator: make a stale roster's membership current.
+
+The coupling rule this module upholds (with the orchestration entry's feeder
+tap): **every execution of a feeder endpoint updates its rosters and records a
+run in the ledger**; parquet is written only when the user asked for that
+endpoint. A coordinator harvest is such an execution -- it fetches, reconciles
+the roster, and records a ``runs`` row for ``(provider, source_endpoint)`` --
+so ``RunLedger.last_success_at`` is a sound staleness key in both directions:
+a harvest is visible to the next staleness check, and a runner-driven feeder
+run (which the entry taps into ``apply_listing``) never leaves the roster
+behind the ledger. A run row certifies execution of the endpoint, not parquet
+freshness.
+
+``refresh_if_stale`` is the demand-driven refresh a fan-out consumer calls
+before it reads a roster. Given the roster's ``RosterDefinition`` -- the
+caller resolves the ``RosterKey`` against the roster registry, the same way
+the run executor is handed an already-resolved ``EndpointDefinition`` -- it
+asks the ledger when the feeder last succeeded, and only if a refresh is due
+(``is_roster_stale``, or an empty stored roster, which is stale regardless of
+the ledger verdict -- ledger history may predate the harvest/ledger coupling)
+re-lists the feeder, reconciles the listing against the stored roster, applies
+the delta, and completes the run. ``apply_listing`` is the feeder-tap handoff
+and the reconcile choke point: the entry collects a successful feeder run's
+listed members and hands them here, and the harvest routes its own listing
+through the same method -- so the reconcile guard (a roster is never
+reconciled to empty; an empty listing is a failed refresh, not a membership
+fact) covers both routes once. Staleness gates only whether the coordinator
+*initiates* a harvest, never whether an executed run's non-empty listing is
+applied; the run row on the tap path was already recorded by the run
+executor.
+
+The full-listing requirement lives here: a roster needs its feeder's complete
+current membership each refresh, so the feeder must be a snapshot endpoint. The
+coordinator resolves the definition's ``source_endpoint`` to the feeder binding and
+guards that (``ConfigurationError`` on a non-snapshot feeder) before harvesting; the
+harvester itself stays ``sync_mode``-blind.
+
+``refresh_if_stale`` is single-flight per roster key (added with the
+intra-provider grain, DESIGN section 7, 2026-07-20): concurrent consumers of
+one stale roster -- both cold-starting with their feeder unselected -- would
+each harvest, wasting quota and recording duplicate ledger snapshot runs.
+The coordinator therefore holds a per-``RosterKey`` lock across the method's
+whole body (an outer lock guards get-or-create of the per-key locks), so the
+second entrant re-runs the freshness check under the lock and returns early
+on the now-fresh roster. Holding the lock across the harvest network call is
+intended -- the waiting consumer needs the membership before it can fan out
+-- and no lock nests inside (the store and ledger are
+connection-per-operation), so there is no deadlock surface. Locks are
+per-key: distinct rosters refresh concurrently.
+
+Failure is best-effort with one loud exception. A harvest ``FleetpullError`` (the
+feeder is unreachable, or a page fails to validate) or ``ValueError`` (a missing
+source column) marks the run failed and degrades to the existing
+roster -- a stale verdict is a refresh *attempt*, not a barrier to the fan-out. The
+exception is cold start: when the store holds no members for the key, there is
+nothing to fall back to and a silent empty roster would fan out over nothing, so the
+failure re-raises (still marking the run failed). Wiring errors -- no feeder
+registered for the ``source_endpoint``, a non-snapshot feeder -- raise before any
+run row is opened; they are bugs, not executions. The crash order inside a
+successful refresh mirrors the run executor's output-first discipline:
+``RosterStore.apply`` (one transaction) lands before ``complete_run``, so a crash
+between the two leaves the roster current and the run merely ``running`` -- the
+next check re-harvests idempotently, never the reverse mode where a fresh ledger
+masks a stale roster.
+
+Collaborators are injected, not assembled: the pure ``reconcile`` /
+``is_roster_stale`` are called directly; the ``EndpointRegistry`` is the immutable
+catalog passed concrete; the stateful surfaces are narrow Protocols (``RosterAccess``,
+``FeederRunLedger``, and the spine's shared ``ClientSource``) the composition
+root satisfies with the real store, ledger, and client registry.
+"""
+
+import logging
+import threading
+from datetime import datetime
+from functools import partial
+from typing import Protocol
+
+from fleetpull.endpoints import EndpointRegistry
+from fleetpull.exceptions import FleetpullError, ProviderResponseError
+from fleetpull.orchestrator.drivers import SingleRequestDriver
+from fleetpull.orchestrator.recording import record_failure_safely
+from fleetpull.orchestrator.roster_harvest import (
+    harvest_roster_members,
+    require_snapshot_feeder,
+)
+from fleetpull.orchestrator.spine import ClientSource
+from fleetpull.roster import RosterDefinition, RosterKey
+from fleetpull.state import RosterDelta, is_roster_stale, reconcile
+from fleetpull.timing import Clock
+from fleetpull.vocabulary import Provider
+
+__all__: list[str] = [
+    'FeederRunLedger',
+    'RosterAccess',
+    'RosterRefreshCoordinator',
+]
+
+logger = logging.getLogger(__name__)
+
+
+class RosterAccess(Protocol):
+    """The roster store surface the coordinator needs (a subset of RosterStore)."""
+
+    def read_counts(self, key: RosterKey) -> dict[str, int]:
+        """Return the roster as ``{member: absence_count}``."""
+        ...
+
+    def apply(self, key: RosterKey, delta: RosterDelta) -> None:
+        """Apply a reconciliation delta in one transaction."""
+        ...
+
+
+class FeederRunLedger(Protocol):
+    """The ledger surface the coordinator needs (a subset of ``RunLedger``).
+
+    ``last_success_at`` keys the staleness decision; the run-recording trio
+    makes a coordinator harvest visible to that same key -- every execution of
+    a feeder endpoint records a run, so the freshness signal and the freshness
+    events cannot diverge.
+    """
+
+    def last_success_at(self, provider: Provider, endpoint: str) -> datetime | None:
+        """Return the feeder's latest successful run end, or ``None``."""
+        ...
+
+    def start_snapshot_run(self, provider: Provider, endpoint: str) -> int:
+        """Open a snapshot run for a harvest and return its id."""
+        ...
+
+    def complete_run(self, run_id: int, *, row_count: int) -> None:
+        """Close a run as succeeded with its row count."""
+        ...
+
+    def fail_run(self, run_id: int, *, error_detail: str) -> None:
+        """Close a run as failed with an error detail."""
+        ...
+
+
+class RosterRefreshCoordinator:
+    """Refresh a roster's stored membership when its feeder listing has gone stale.
+
+    Built once with the endpoint catalog and the store / ledger / client surfaces, it
+    answers ``refresh_if_stale(definition)``. Beyond the per-key single-flight
+    locks (the coordinator is the stateful orchestrator here, so the lock map
+    lives on it) it holds no per-refresh state and opens no clients -- the
+    injected client source hands it the feeder provider's open client.
+
+    Args:
+        endpoint_registry: Resolves the feeder's ``(provider, name)`` to its binding.
+        store: The roster store (read counts, apply a delta).
+        ledger: The feeder's ledger surface -- the last-success read for the
+            staleness decision, and the run recording a harvest performs.
+        client_source: The open transport client per provider.
+        clock: The clock supplying ``now`` for the staleness decision.
+    """
+
+    def __init__(
+        self,
+        endpoint_registry: EndpointRegistry,
+        store: RosterAccess,
+        ledger: FeederRunLedger,
+        client_source: ClientSource,
+        clock: Clock,
+    ) -> None:
+        self._endpoint_registry = endpoint_registry
+        self._store = store
+        self._ledger = ledger
+        self._client_source = client_source
+        self._clock = clock
+        self._key_locks_guard = threading.Lock()
+        self._key_locks: dict[RosterKey, threading.Lock] = {}
+
+    def refresh_if_stale(self, definition: RosterDefinition) -> None:
+        """Re-list the feeder, reconcile the roster, and record the run, if stale.
+
+        Single-flight per roster key: the whole body runs under the key's
+        lock, so of two concurrent consumers hitting the same stale roster,
+        exactly one harvests -- the second re-runs the freshness check under
+        the lock and returns early on the now-fresh roster. The lock is held
+        across the harvest network call deliberately (the waiting consumer
+        needs the membership before it can fan out), and distinct keys never
+        contend.
+
+        Returns early when the roster is fresh -- non-empty and inside the
+        staleness bound. An empty stored roster is stale regardless of the
+        ledger verdict (ledger history may predate the harvest/ledger
+        coupling, and a fresh ledger must not mask a roster with nothing to
+        fan out over). When a refresh is due, the harvest is an execution of
+        the feeder endpoint: it opens a snapshot run, harvests the complete
+        membership, applies the reconciliation, and completes the run -- store
+        before ledger, so a crash between the two re-harvests rather than
+        masking. A harvest failure marks the run failed and degrades to the
+        existing roster, unless the store is empty (cold start), where it
+        re-raises.
+
+        Args:
+            definition: The roster to refresh -- its key, feeder ``source_endpoint``
+                and ``source_column``, and staleness / eviction policy. The caller
+                resolved it from a ``RosterKey`` against the roster registry.
+
+        Raises:
+            ConfigurationError: No feeder is registered for ``source_endpoint``, or the
+                resolved feeder is not a snapshot endpoint -- wiring bugs, raised
+                loudly before any run row is opened.
+            FleetpullError: The harvest failed on a cold start (no existing roster to
+                fall back to); the underlying failure propagates.
+            ValueError: The harvest failed on a cold start with a missing source
+                column; the underlying failure propagates.
+
+        Side Effects:
+            Holds the roster's single-flight lock for the duration. On a due
+            refresh: issues the feeder's request chain and records a run in
+            the ledger; on success, also writes the reconciled delta to the
+            store. Otherwise touches nothing.
+        """
+        with self._refresh_lock(definition.key):
+            self._refresh_if_due(definition)
+
+    def _refresh_lock(self, key: RosterKey) -> threading.Lock:
+        """Get or create the roster's single-flight lock.
+
+        Args:
+            key: The roster whose lock to return (hashable frozen identity).
+
+        Returns:
+            The per-key lock, created on first use under the outer guard.
+        """
+        with self._key_locks_guard:
+            return self._key_locks.setdefault(key, threading.Lock())
+
+    def _refresh_if_due(self, definition: RosterDefinition) -> None:
+        """The refresh body ``refresh_if_stale`` runs under the key's lock."""
+        provider = definition.key.provider
+        current = self._store.read_counts(definition.key)
+        last_success = self._ledger.last_success_at(
+            provider, definition.source_endpoint
+        )
+        now = self._clock.now_utc()
+        if current and not is_roster_stale(last_success, now, definition.max_age):
+            return
+        feeder = self._endpoint_registry.get(provider, definition.source_endpoint)
+        require_snapshot_feeder(feeder, definition.source_endpoint)
+        client = self._client_source.client_for(provider)
+        logger.info(
+            'roster refresh started: provider=%s roster=%s feeder=%s members_held=%d',
+            provider.value,
+            definition.key.name,
+            definition.source_endpoint,
+            len(current),
+        )
+        run_id = self._ledger.start_snapshot_run(provider, definition.source_endpoint)
+        try:
+            listed = harvest_roster_members(
+                feeder, SingleRequestDriver(), client, definition.source_column
+            )
+            # Routed through the shared reconcile body so its guard (a
+            # roster is never reconciled to empty) covers the harvest inside
+            # this same failed-refresh path: an empty listing marks the run
+            # failed and degrades exactly like a failed HTTP refresh. The
+            # key's single-flight lock is already held here, so the locked
+            # ``apply_listing`` wrapper would deadlock.
+            self._reconcile_listing(definition, listed)
+        except (FleetpullError, ValueError) as failure:
+            record_failure_safely(
+                partial(self._ledger.fail_run, run_id, error_detail=str(failure)),
+                f'harvest run {run_id}',
+            )
+            if not current:
+                raise
+            logger.warning(
+                'roster %s/%s refresh failed; keeping %d existing members: %s',
+                provider.value,
+                definition.key.name,
+                len(current),
+                failure,
+            )
+            return
+        # A harvest run's row count is the distinct-member count of the
+        # listing -- the rows this execution produced for its consumer.
+        self._ledger.complete_run(run_id, row_count=len(listed))
+        logger.info(
+            'roster refreshed: provider=%s roster=%s members=%d',
+            provider.value,
+            definition.key.name,
+            len(listed),
+        )
+
+    def apply_listing(self, definition: RosterDefinition, listed: set[str]) -> None:
+        """Reconcile an executed feeder run's listed membership into the store.
+
+        The feeder tap's route into the reconcile choke point
+        (``_reconcile_listing``): the orchestration entry hands a successful
+        runner-driven feeder run's distinct ``source_column`` values here.
+        Runs under the roster key's single-flight lock -- the same lock
+        ``refresh_if_stale`` holds around its harvest -- so every reconcile
+        for one key serializes, whichever route wrote it: two
+        read-reconcile-write sequences on one roster can never interleave
+        and corrupt absence counts. Records no ledger row: the tap route's
+        run was recorded by the run executor.
+
+        Args:
+            definition: The sourced roster -- its key and eviction policy.
+            listed: The feeder run's complete listed membership.
+
+        Raises:
+            ProviderResponseError: ``listed`` is empty (the reconcile guard);
+                the store is untouched.
+
+        Side Effects:
+            Holds the roster's single-flight lock for the duration; writes
+            the reconciled delta to the store (one transaction).
+        """
+        with self._refresh_lock(definition.key):
+            self._reconcile_listing(definition, listed)
+
+    def _reconcile_listing(
+        self, definition: RosterDefinition, listed: set[str]
+    ) -> None:
+        """The reconcile body both write routes run under the key's lock.
+
+        The reconcile guard lives here so both routes -- the feeder tap
+        (``apply_listing``) and the coordinator's own harvest
+        (``_refresh_if_due``, which already holds the lock) -- are covered
+        once: **a roster is never reconciled to empty**. An empty listing --
+        the provider returned nothing, or every record's member value
+        filtered out -- is a failed refresh, not a membership fact:
+        reconciling it would mass-increment absence counts and, with an
+        eviction threshold, evict the entire roster through systematic
+        provider garbage. The prior roster stays intact and the caller's
+        failed-refresh semantics apply (the harvest degrades exactly like a
+        failed HTTP refresh; the tap propagates, failing the endpoint
+        loudly). A non-empty listing is applied whole -- staleness gates
+        only whether the coordinator *initiates* a harvest, never whether an
+        executed run's complete listing is reconciled.
+
+        Args:
+            definition: The sourced roster -- its key and eviction policy.
+            listed: The feeder run's complete listed membership.
+
+        Raises:
+            ProviderResponseError: ``listed`` is empty (the reconcile guard);
+                the store is untouched.
+
+        Side Effects:
+            Writes the reconciled delta to the store (one transaction).
+        """
+        if not listed:
+            raise ProviderResponseError(
+                provider=definition.key.provider.value,
+                endpoint=definition.source_endpoint,
+                detail=(
+                    f'feeder listed no members for roster '
+                    f'{definition.key.name!r}; a roster is never reconciled '
+                    f'to empty -- the prior membership stands'
+                ),
+            )
+        current = self._store.read_counts(definition.key)
+        self._store.apply(
+            definition.key,
+            reconcile(current, listed, definition.eviction_threshold),
+        )