Orchestrator

How the orchestrator runtime loads providers, plans changes, applies writes, and persists state safely.

This section documents the orchestrator runtime under cw_platform/orchestrator/.

It loads providers, builds snapshots, plans diffs, and applies writes.

It is pessimistic by design. It prefers skipping deletes.

End users

What it is

The orchestrator is the engine that runs sync work.

It coordinates providers, pairs, and safety checks.

Quick mental model

• Providers expose inventories and writes.

• Pairs describe source, target, and mode.

• Features are watchlist, ratings, history, playlists.

• Snapshots are inventories keyed by canonical_key.

• Plans are adds/removes or upserts/unrates.

• State stores baselines and checkpoints.

What happens in a run

1

Load providers

Providers are loaded from providers/sync/_mod_*.py.

Each provider exports an InventoryOps implementation.

2

Health pass

Each provider can report ok/down/auth_failed.

Auth failures skip pairs. Down providers skip writes.

3

Run pairs and features

For each enabled pair and feature:

• build source and destination snapshots

• apply guardrails

• plan diffs

• apply writes (chunked, retried)

• persist baselines and checkpoints

4

Persist summaries

The run writes state and a last_sync.json summary.

Why it’s cautious

The orchestrator fails safe by default:

• If auth is broken, it skips the pair.

• If a provider is down, it skips writes.

• If a snapshot looks wrong, it treats it as suspect.

• If a delete plan is huge, it blocks it by default.

Related product docs

• End-user setup and concepts: Syncing

• Pair configuration: Configure Pairs

• Adapter overview: Synchronization

Power users