Orchestrator

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

CrossWatch runs sync work through an orchestrator.

It loads providers, builds inventories, plans changes, and applies writes.

It is pessimistic by design. It prefers to skip over deleting data.

Most orchestrator code lives under cw_platform/orchestrator/.

Quick mental model

• Providers expose inventories and writes via a common contract.

• Pairs describe source, target, and mode.

• Features are watchlist, ratings, history, playlists.

• Snapshots are provider inventories, normalized into canonical_key -> item.

• Plans are adds/removes (or rating upserts/unrates).

• State stores baselines, checkpoints, and guardrail internals.

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.

Core building blocks

Use these pages as the “deep dive index”.

Topic

Snapshots (inventories, checkpoints, drop guard)

Open

Snapshots

Topic

Planner (diff engine)

Open

Planner

Topic

Applier (write engine)

Open

Applier

Topic

State (baselines, checkpoints, guardrail internals)

Open

State

Topic

state.json schema and semantics

Open

State.json

Topic

One-way pipeline (src → dst)

Open

One-way sync

Topic

Two-way pipeline (A ↔ B)

Open

Two-way sync

Topic

Conflicts (two-way resolution)

Open

Conflicts

Topic

Guardrails (safety model)

Open

Guardrails

Topic

Tombstones (deletion memory)

Open

Tombstones

Topic

Blackbox (quarantine flapping items)

Open

Blackbox

Topic

Phantom Guard (ghost add protection)

Open

Phantom Guard

Topic

Unresolved (stop retrying known-bad items)

Open

Unresolved

Topic

Blocklists (how guards block planned adds)

Open

Blocklists

Topic

Scope (pair scoping of caches + guard state)

Open

Scope

Topic

Health (provider health gates)

Open

Health

Topic

Chunking (batch sizing + throttling)

Open

Chunking

Topic

Caching layers (where data can get stale)

Open

Caching layers

Topic

Eventing (UI stream + logs)

Open

Eventing

Topic

Runtime knobs (debug, caching, chunking)

Open

Runtime

Topic

Provider contract (InventoryOps)

Open

Provider contract

Topic

Provider specifics (real-world quirks)

Open

Provider specifics

Why it’s “overly cautious”

Orchestrator safety comes from a few blunt rules:

• If auth is broken, skip the pair.

• If a provider is down, skip writes to it.

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

• If a delete plan is huge, block it unless you opted in.

That’s why CrossWatch usually fails safe.

Related product docs

• End-user setup and concepts: Syncing

• UI pair configuration: Configure Pairs

• Adapter overview: Synchronization