fleetpull 0.1.0__py3-none-any.whl

fleetpull/orchestrator/runner.py

@@ -0,0 +1,262 @@
+# src/fleetpull/orchestrator/runner.py
+"""The run executor: run one endpoint to completion, once per (endpoint, run).
+
+``EndpointRunner`` owns one endpoint's run and dispatches on its ``sync_mode``.
+The snapshot arm lives here: fetch once, full-replace, record the run. The
+watermark arm is the ``WatermarkDrive`` (``orchestrator/watermark_drive.py``:
+the plan-and-drive unit loop with the prefix-advance watermark rule) and the
+feed arm is the ``FeedDrive`` (``orchestrator/feed_drive.py``: the per-page
+parquet-before-token drive) -- both constructed in ``__init__`` from the same
+``RunnerSpine`` (``orchestrator/spine.py``): the four collaborators plus the
+runner-owned seams, the ONE writer-factory call site (``_writer_for``) and
+the post-commit ``metadata.json`` projection
+(``orchestrator/metadata_projection.py``). Every run-opening arm wraps its
+protected block in the shared ``recorded_run`` spine
+(``orchestrator/recording.py``), so a failure records the run failed without
+masking the original error. Request cardinality and batch granularity are
+the driver's; the runner is blind to both.
+
+``run`` takes an optional ``BatchObserver``: a generic hook handed each
+post-validation frame as the run streams. The runner knows nothing about what
+an observer does with the frames (the caller boundary uses it to tap feeder
+runs for roster reconciliation, but that knowledge lives entirely there) -- an
+observer exception fails the run like any other batch-processing failure.
+
+The runner depends on narrow Protocols rather than the concrete state and
+network classes -- ``ClientSource``, ``RunRecorder``, ``CursorAccess``, and
+``UnitQueue``, bundled as ``RunStateAccess`` (all on the spine module). It
+opens no clients and reads no credentials -- the already-open client source
+hands it the provider's client.
+"""
+
+import logging
+
+from fleetpull.config import FleetpullConfig
+from fleetpull.endpoints.shared import (
+    EndpointDefinition,
+    FeedMode,
+    SnapshotMode,
+    WatermarkMode,
+)
+from fleetpull.incremental import DateWindow
+from fleetpull.model_contract import ResponseModel
+from fleetpull.orchestrator.drivers import RequestDriver
+from fleetpull.orchestrator.feed_drive import FeedDrive
+from fleetpull.orchestrator.metadata_projection import (
+    MetadataProjection,
+    sync_mode_label,
+)
+from fleetpull.orchestrator.outcome import Executed, RunOutcome
+from fleetpull.orchestrator.recording import recorded_run
+from fleetpull.orchestrator.spine import ClientSource, RunnerSpine, RunStateAccess
+from fleetpull.orchestrator.streaming import (
+    BatchObserver,
+    drain_batches,
+    observe_batches,
+    stream_processed_batches,
+)
+from fleetpull.orchestrator.watermark_drive import WatermarkDrive
+from fleetpull.storage import DatasetWriter, select_writer
+from fleetpull.timing import Clock
+
+__all__: list[str] = ['EndpointRunner']
+
+logger = logging.getLogger(__name__)
+
+
+class EndpointRunner:
+    """Runs one endpoint to completion, dispatching on its sync mode.
+
+    Constructed once with its four collaborators (client source, the bundled
+    state surfaces, clock, the root config); ``run`` takes the endpoint and
+    its request driver, so one instance runs every endpoint. The snapshot
+    arm lives on the class; the watermark and feed arms are the two drive
+    classes built in ``__init__`` from the shared spine.
+    """
+
+    def __init__(
+        self,
+        client_source: ClientSource,
+        state: RunStateAccess,
+        clock: Clock,
+        config: FleetpullConfig,
+    ) -> None:
+        """
+        Args:
+            client_source: Hands out an open per-provider client (the registry).
+            state: The state-database surfaces -- the ledger, the cursor
+                store, and the work-unit queue.
+            clock: Supplies the run instant (trailing edge, future-event guard).
+            config: The root config -- the container its composition root
+                already holds. The runner reads the ``sync`` section (the
+                cold-start anchor, the unit width, and the unit worker
+                count, handed to the drives on the spine) plus two storage
+                values: ``storage.dataset_root`` (where the writers land)
+                and ``storage.drop_exact_duplicates`` (the writers'
+                exact-dedup switch).
+        """
+        self._dataset_root = config.storage.dataset_root
+        self._drop_duplicates = config.storage.drop_exact_duplicates
+        self._spine = RunnerSpine(
+            clients=client_source,
+            state=state,
+            clock=clock,
+            sync=config.sync,
+            make_writer=self._writer_for,
+            projection=MetadataProjection(
+                state.cursors, clock, config.storage.dataset_root
+            ),
+        )
+        self._watermark_drive = WatermarkDrive(self._spine)
+        self._feed_drive = FeedDrive(self._spine)
+
+    def run(
+        self,
+        definition: EndpointDefinition[ResponseModel],
+        driver: RequestDriver,
+        observer: BatchObserver | None = None,
+    ) -> RunOutcome:
+        """Run one endpoint to completion and report the outcome.
+
+        Narrates at INFO: one start line at entry (provider, endpoint, sync
+        mode) and, for an ``Executed`` outcome, one completion line with the
+        merged counts and the endpoint's elapsed seconds (a monotonic delta
+        captured at entry). A ``CaughtUp`` outcome narrates through the
+        watermark arm's own 'caught up' line instead.
+
+        Args:
+            definition: The endpoint to run.
+            driver: The request driver supplying the run's record batches.
+            observer: An optional generic hook handed each post-validation
+                frame as the run streams; the runner is blind to what it does.
+
+        Returns:
+            The run outcome -- ``Executed``, or ``CaughtUp`` when a windowed
+            run had nothing to drive.
+
+        Raises:
+            FleetpullError: A fetch, validation, or write failure -- the run is
+                recorded failed and the error propagates.
+        """
+        endpoint_started = self._spine.clock.monotonic_seconds()
+        logger.info(
+            'endpoint started: provider=%s endpoint=%s mode=%s',
+            definition.provider.value,
+            definition.name,
+            sync_mode_label(definition.sync_mode),
+        )
+        match definition.sync_mode:
+            case SnapshotMode():
+                outcome: RunOutcome = self._run_snapshot(definition, driver, observer)
+            case WatermarkMode() as mode:
+                outcome = self._watermark_drive.run(definition, driver, mode, observer)
+            case FeedMode():
+                outcome = self._feed_drive.run(definition, driver, observer)
+        if isinstance(outcome, Executed):
+            self._log_endpoint_complete(definition, outcome, endpoint_started)
+        return outcome
+
+    def _writer_for(
+        self,
+        definition: EndpointDefinition[ResponseModel],
+        window: DateWindow | None = None,
+    ) -> DatasetWriter:
+        """Construct the endpoint's writer -- the ONE ``select_writer`` call site.
+
+        Every arm's writer routes through here (the drives receive it as the
+        spine's ``make_writer``), with the dataset root and the exact-dedup
+        switch bound once at construction.
+
+        Args:
+            definition: The endpoint being run.
+            window: The run's resolved resume window, for the incremental
+                cells; ``None`` for the snapshot and feed cells.
+
+        Returns:
+            The endpoint's ``DatasetWriter`` for this run.
+        """
+        return select_writer(
+            definition,
+            self._dataset_root,
+            window=window,
+            drop_duplicates=self._drop_duplicates,
+        )
+
+    def _run_snapshot(
+        self,
+        definition: EndpointDefinition[ResponseModel],
+        driver: RequestDriver,
+        observer: BatchObserver | None,
+    ) -> RunOutcome:
+        """Run the snapshot arm: full fetch, full-replace write, record the run.
+
+        Resolves the provider's client, opens a snapshot run, drives the batches,
+        writes each, and completes the run with the fetched-row count. A snapshot has
+        no resume value and no cursor, so it passes ``resume=None`` and advances no
+        watermark. The client is resolved before the run is opened, so an
+        unconfigured provider opens no dangling run. ``complete_run`` runs inside the
+        protected block: a failure to record completion marks the run failed rather
+        than leaving a zombie ``running`` row. The ``metadata.json`` projection
+        writes after the protected block -- the run is committed by then, and a
+        post-commit projection failure must never mark a succeeded run failed.
+
+        Args:
+            definition: The snapshot endpoint to run.
+            driver: The shape-resolved request driver -- a
+                ``SingleRequestDriver`` for a single-fetch snapshot, a
+                ``FanOutRequestDriver`` for a ``ParamSweep`` one.
+            observer: The optional per-frame hook, handed each post-validation
+                frame as the run streams.
+
+        Returns:
+            ``Executed`` with the fetched-row count and the write report.
+
+        Raises:
+            FleetpullError: A fetch, validation, write, or completion failure -- the
+                run is recorded failed and the original error re-raised.
+        """
+        recorder = self._spine.state.recorder
+        client = self._spine.clients.client_for(definition.provider)
+        run_id = recorder.start_snapshot_run(definition.provider, definition.name)
+        with recorded_run(recorder, run_id):
+            writer = self._writer_for(definition)
+            batches = stream_processed_batches(
+                definition, driver, client, resume=None, context=None
+            )
+            records_fetched, _ = drain_batches(
+                observe_batches(batches, observer), writer
+            )
+            write = writer.finalize()
+            recorder.complete_run(run_id, row_count=records_fetched)
+        outcome = Executed(records_fetched=records_fetched, write=write)
+        self._spine.projection.project(definition, outcome, window=None)
+        return outcome
+
+    def _log_endpoint_complete(
+        self,
+        definition: EndpointDefinition[ResponseModel],
+        outcome: Executed,
+        endpoint_started: float,
+    ) -> None:
+        """Narrate a committed endpoint's counts and elapsed time at INFO.
+
+        Args:
+            definition: The endpoint that just ran.
+            outcome: The run's (merged) ``Executed`` outcome.
+            endpoint_started: The ``monotonic_seconds`` reading captured at
+                ``run()`` entry, so the elapsed value covers the whole
+                endpoint (both arms, metadata projection included).
+        """
+        logger.info(
+            'endpoint complete: provider=%s endpoint=%s records_fetched=%d '
+            'rows_written=%d duplicates_dropped=%d files_written=%d '
+            'deleted_partitions=%d elapsed_seconds=%.1f',
+            definition.provider.value,
+            definition.name,
+            outcome.records_fetched,
+            outcome.write.rows_written,
+            outcome.write.duplicates_dropped,
+            outcome.write.files_written,
+            len(outcome.write.deleted_partitions),
+            self._spine.clock.monotonic_seconds() - endpoint_started,
+        )

fleetpull/orchestrator/shape_resolution.py

@@ -0,0 +1,221 @@
+# src/fleetpull/orchestrator/shape_resolution.py
+"""The shared shape-to-driver seam: one ``RequestShape`` match, one driver out.
+
+``resolve_request_driver`` is the single place a declared ``request_shape``
+becomes a ``RequestDriver`` -- both composition roots call it (the
+orchestration entry for sync, ``fetch`` for the in-memory verb), so a new
+cardinality pattern is a new union member plus its arm here, never a new
+field or a new branch anywhere else. The seam owns only the dispatch:
+supplying roster members for the roster-backed shapes (``RosterFanOut`` /
+``BatchedRosterFanOut``) -- registry lookup, refresh policy, store read,
+the empty-roster guard -- stays with the caller, which feeds them in
+through the ``RosterMemberSource`` callable. A stateless caller
+(``fetch``) passes ``roster_members=None`` and every stateless shape
+resolves; a roster-backed shape then fails loudly, because a roster is
+durable operational state the stateless composition deliberately lacks.
+"""
+
+from collections.abc import Callable, Sequence
+from typing import Protocol
+
+from fleetpull.endpoints.shared import (
+    BatchedRosterFanOut,
+    BisectedWindowFetch,
+    EndpointDefinition,
+    ParamSweep,
+    RosterFanOut,
+    SingleFetch,
+)
+from fleetpull.exceptions import ConfigurationError
+from fleetpull.model_contract import ResponseModel
+from fleetpull.orchestrator.bisection import BisectingWindowDriver
+from fleetpull.orchestrator.drivers import (
+    FanOutRequestDriver,
+    RequestDriver,
+    SingleRequestDriver,
+)
+from fleetpull.orchestrator.fanout import FetchPool
+from fleetpull.roster import RosterKey
+from fleetpull.vocabulary import Provider
+
+__all__: list[str] = [
+    'FetchPoolSource',
+    'RosterMemberSource',
+    'resolve_request_driver',
+]
+
+
+class FetchPoolSource(Protocol):
+    """The pool-lookup surface the resolution needs (``FetchPoolRegistry``'s shape)."""
+
+    def pool_for(self, provider: Provider) -> FetchPool:
+        """Return the fetch pool for a provider."""
+        ...
+
+
+# The caller's roster half of a roster-backed resolution: handed the
+# roster's key, it returns the refreshed membership (or raises the caller's
+# own roster failure). Both roster-backed shapes name their roster with the
+# same ``RosterKey``, so one key-shaped source serves them both -- one
+# roster machinery path, no second seam, no synthetic shape. None marks a
+# stateless caller with no roster state at all.
+type RosterMemberSource = Callable[[RosterKey], Sequence[str]]
+
+
+def resolve_request_driver(
+    definition: EndpointDefinition[ResponseModel],
+    *,
+    fetch_pools: FetchPoolSource,
+    roster_members: RosterMemberSource | None,
+) -> RequestDriver:
+    """Resolve a definition's declared request shape into a request driver.
+
+    Args:
+        definition: The endpoint whose ``request_shape`` routes.
+        fetch_pools: Supplies the provider's fetch pool for the fanned shapes
+            (``RosterFanOut`` / ``BatchedRosterFanOut`` / ``ParamSweep``);
+            never consulted for the single-chain shapes.
+        roster_members: The caller's roster membership source, invoked only
+            for the roster-backed shapes; ``None`` for a stateless caller
+            with no roster state.
+
+    Returns:
+        The ``SingleRequestDriver`` for ``SingleFetch``; the
+        ``BisectingWindowDriver`` for ``BisectedWindowFetch``; the
+        ``FanOutRequestDriver`` over the roster's members for
+        ``RosterFanOut``, over sorted comma-joined member batches for
+        ``BatchedRosterFanOut``, or over the declared values
+        (``member_key`` = ``param``) for ``ParamSweep`` -- the driver is
+        member-agnostic, so every fanned shape shares it.
+
+    Raises:
+        ConfigurationError: The shape is roster-backed (``RosterFanOut`` /
+            ``BatchedRosterFanOut``) and no roster source is available --
+            the stateless-caller case.
+        FleetpullError: Whatever the roster source raises resolving a
+            roster-backed shape (an unregistered or empty roster, a
+            cold-start refresh failure), propagated unswallowed.
+
+    Side Effects:
+        On the roster-backed paths: whatever the supplied source performs
+        (a feeder listing and a store write when stale).
+    """
+    match definition.request_shape:
+        case SingleFetch():
+            return SingleRequestDriver()
+        case BisectedWindowFetch() as shape:
+            return BisectingWindowDriver(shape=shape)
+        case ParamSweep() as sweep:
+            return FanOutRequestDriver(
+                members=sweep.values,
+                member_key=sweep.param,
+                fetch_pool=fetch_pools.pool_for(definition.provider),
+            )
+        case RosterFanOut() as fan_out:
+            return FanOutRequestDriver(
+                members=_require_roster_members(
+                    definition, roster_members, fan_out.roster
+                ),
+                member_key=fan_out.member_key,
+                fetch_pool=fetch_pools.pool_for(definition.provider),
+            )
+        case BatchedRosterFanOut() as batched:
+            # The batched shape is transport packing over the plain roster
+            # fan-out, so membership resolves through the identical source
+            # call -- the same roster key -- and only then chunks into
+            # comma-joined batch values. The driver stays member-agnostic:
+            # each batch is simply one member string.
+            members = _require_roster_members(
+                definition, roster_members, batched.roster
+            )
+            return FanOutRequestDriver(
+                members=_comma_joined_batches(members, batched.batch_size),
+                member_key=batched.member_key,
+                fetch_pool=fetch_pools.pool_for(definition.provider),
+            )
+
+
+def _require_roster_members(
+    definition: EndpointDefinition[ResponseModel],
+    roster_members: RosterMemberSource | None,
+    roster: RosterKey,
+) -> Sequence[str]:
+    """Resolve a roster-backed shape's membership, refusing a stateless caller.
+
+    Args:
+        definition: The endpoint being resolved, for the error context.
+        roster_members: The caller's roster membership source, or ``None``
+            for a stateless caller with no roster state.
+        roster: The roster the shape names -- a ``RosterFanOut``'s or a
+            ``BatchedRosterFanOut``'s ``roster`` key alike.
+
+    Returns:
+        The refreshed membership, exactly as the source supplies it.
+
+    Raises:
+        ConfigurationError: No roster source is available -- the
+            stateless-caller (in-memory ``fetch``) case.
+        FleetpullError: Whatever the source raises (an unregistered or
+            empty roster, a cold-start refresh failure), propagated
+            unswallowed.
+
+    Side Effects:
+        Whatever the supplied source performs (a feeder listing and a
+        store write when stale).
+    """
+    if roster_members is None:
+        raise ConfigurationError(
+            'no roster source for a roster fan-out endpoint',
+            provider=definition.provider.value,
+            endpoint=definition.name,
+            detail=(
+                f'the {roster.name!r} roster fan-out needs '
+                f'durable roster state, which this stateless '
+                f'composition (the in-memory fetch verb) deliberately '
+                f'lacks; run it through the config-driven sync path'
+            ),
+        )
+    return roster_members(roster)
+
+
+def _comma_joined_batches(members: Sequence[str], batch_size: int) -> tuple[str, ...]:
+    """Chunk members into sorted, comma-joined batch values, one per chain.
+
+    Deterministic by construction: members sort before chunking, so
+    identical rosters always produce identical batches regardless of the
+    source's ordering. Pure -- no state, no side effects; the batch is
+    transport packing only (records self-identify), so nothing here maps
+    a member back to its batch.
+
+    Args:
+        members: The roster's member values, in any order. A member
+            containing the join delimiter is rejected loudly: a comma
+            inside one member would silently widen the batch on the wire
+            (more ids than members -- past the API cap, or addressing an
+            unintended asset), and no provider's roster ids carry commas.
+        batch_size: The maximum members per batch; at least 1, enforced
+            by ``BatchedRosterFanOut`` at declaration.
+
+    Returns:
+        The comma-joined batch strings, in sorted-member order -- fewer
+        members than one batch yields a single batch.
+
+    Raises:
+        ConfigurationError: A member value contains a comma -- corrupt
+            roster data surfaced loudly, never packed onto the wire.
+    """
+    comma_carriers = [member for member in members if ',' in member]
+    if comma_carriers:
+        raise ConfigurationError(
+            'roster member contains the batch join delimiter',
+            detail=(
+                f'{len(comma_carriers)} member value(s) contain a comma '
+                f'(first: {comma_carriers[0]!r}); a comma-joined batch '
+                f'would carry more ids than members'
+            ),
+        )
+    ordered = sorted(members)
+    return tuple(
+        ','.join(ordered[start : start + batch_size])
+        for start in range(0, len(ordered), batch_size)
+    )

fleetpull/orchestrator/spine.py

@@ -0,0 +1,166 @@
+# src/fleetpull/orchestrator/spine.py
+"""The run executor's shared spine: its narrow protocols and drive bundle.
+
+The narrow Protocols the run executor and its drive arms depend on instead of
+the concrete state and network classes -- ``ClientSource`` (the registry's
+``client_for``; the roster refresh coordinator shares this one declaration),
+``RunRecorder`` (the ledger's lifecycle methods), and ``CursorAccess`` (the
+cursor store's read and its two kind-guarded writes) -- with the three
+state-database surfaces bundled as ``RunStateAccess`` and the whole drive kit
+bundled as ``RunnerSpine``: the collaborators plus the runner-owned seams
+(the one writer-factory call site, the metadata projection) every arm runs
+through. They live here, below the runner and the drive modules alike, so the
+runner can construct the drives without an import cycle.
+"""
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Protocol
+
+from fleetpull.config import SyncConfig
+from fleetpull.endpoints.shared import EndpointDefinition
+from fleetpull.incremental import DateWindow, IncrementalCursor
+from fleetpull.model_contract import ResponseModel
+from fleetpull.network.client import TransportClient
+from fleetpull.orchestrator.metadata_projection import MetadataProjection
+from fleetpull.orchestrator.unit_loop import UnitQueue
+from fleetpull.storage import DatasetWriter
+from fleetpull.timing import Clock
+from fleetpull.vocabulary import Provider
+
+__all__: list[str] = [
+    'ClientSource',
+    'CursorAccess',
+    'RunRecorder',
+    'RunStateAccess',
+    'RunnerSpine',
+    'WriterFactory',
+]
+
+
+class ClientSource(Protocol):
+    """The client-lookup surface the executor needs (a subset of the registry)."""
+
+    def client_for(self, provider: Provider) -> TransportClient:
+        """Return the open transport client for a provider."""
+        ...
+
+
+class RunRecorder(Protocol):
+    """The run-recording surface the executor needs (a subset of RunLedger)."""
+
+    def start_snapshot_run(self, provider: Provider, endpoint: str) -> int:
+        """Open a snapshot run and return its id."""
+        ...
+
+    def complete_run(
+        self, run_id: int, *, row_count: int, to_version: str | None = None
+    ) -> None:
+        """Close a run as succeeded with its row count (and a feed run's token)."""
+        ...
+
+    def fail_run(self, run_id: int, *, error_detail: str) -> None:
+        """Close a run as failed with an error detail."""
+        ...
+
+    def start_window_run(
+        self, provider: Provider, endpoint: str, *, window: DateWindow
+    ) -> int:
+        """Open a watermark run for a window and return its id."""
+        ...
+
+    def start_feed_run(
+        self, provider: Provider, endpoint: str, *, from_version: str
+    ) -> int:
+        """Open a feed run resuming from a token (or seed label) and return its id."""
+        ...
+
+    def coverage_frontier(self, provider: Provider, endpoint: str) -> datetime | None:
+        """Return the furthest window end a succeeded run has covered, if any."""
+        ...
+
+
+class CursorAccess(Protocol):
+    """The cursor surface the incremental arms need (a subset of CursorStore)."""
+
+    def get_cursor(self, provider: Provider, endpoint: str) -> IncrementalCursor | None:
+        """Return the persisted cursor for a (provider, endpoint), or None."""
+        ...
+
+    def advance_watermark_forward(
+        self, provider: Provider, endpoint: str, observed: datetime
+    ) -> bool:
+        """Atomically advance the date watermark iff strictly forward."""
+        ...
+
+    def commit_feed_token(
+        self, provider: Provider, endpoint: str, to_version: str
+    ) -> None:
+        """Commit the feed cursor, kind-guarded last-write-wins."""
+        ...
+
+
+@dataclass(frozen=True, slots=True)
+class RunStateAccess:
+    """The three state-database surfaces one endpoint run commits through.
+
+    They always travel together -- the composition root builds all three
+    over the one state database and the runner's per-unit crash order
+    sequences them (parquet -> ledger completion -> unit done-mark ->
+    watermark prefix commit) -- so they ride as one collaborator (the
+    bundle rule).
+
+    Attributes:
+        recorder: The run ledger's lifecycle surface.
+        cursors: The cursor store's read and kind-guarded-write surface.
+        units: The work-unit claim queue.
+    """
+
+    recorder: RunRecorder
+    cursors: CursorAccess
+    units: UnitQueue
+
+
+class WriterFactory(Protocol):
+    """The runner's ONE writer-construction seam, as the drives receive it.
+
+    A bound view of the runner's ``select_writer`` call site (dataset root
+    and dedup switch already closed over), so every arm constructs its
+    writer through one place and the routing face is called exactly once
+    in the orchestration layer.
+    """
+
+    def __call__(
+        self,
+        definition: EndpointDefinition[ResponseModel],
+        window: DateWindow | None = None,
+    ) -> DatasetWriter:
+        """Construct the endpoint's writer for this run (and window, if any)."""
+        ...
+
+
+@dataclass(frozen=True, slots=True)
+class RunnerSpine:
+    """The whole drive kit: collaborators plus the runner-owned seams.
+
+    What the snapshot arm and both drive classes (the watermark and feed
+    drives) run through, bundled once (the bundle rule) so the drives
+    construct from a single parameter in ``EndpointRunner.__init__``.
+
+    Attributes:
+        clients: Hands out an open per-provider client (the registry).
+        state: The state-database surfaces -- ledger, cursor store, unit
+            queue.
+        clock: Supplies the run instant (trailing edge, future-event guard).
+        sync: The sync section -- the cold-start anchor, the unit width,
+            and the unit worker count.
+        make_writer: The runner's one writer-factory call site, bound.
+        projection: The post-commit ``metadata.json`` projection.
+    """
+
+    clients: ClientSource
+    state: RunStateAccess
+    clock: Clock
+    sync: SyncConfig
+    make_writer: WriterFactory
+    projection: MetadataProjection