# Orchestrator

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.

{% tabs %}
{% tab title="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

{% stepper %}
{% step %}

### Load providers

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

Each provider exports an `InventoryOps` implementation.
{% endstep %}

{% step %}

### Health pass

Each provider can report `ok/down/auth_failed`.

Auth failures skip pairs. Down providers skip writes.
{% endstep %}

{% step %}

### 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
  {% endstep %}

{% step %}

### Persist summaries

The run writes state and a `last_sync.json` summary.
{% endstep %}
{% endstepper %}

### 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](/getting-started/first-time-setup/what-do-you-need/syncing.md)
* Pair configuration: [Configure Pairs](/crosswatch/configure-pairs.md)
* Adapter overview: [Synchronization](/crosswatch/providers/synchronization.md)
  {% endtab %}

{% tab title="Power users" %}

### Code map

Most orchestrator code lives under:

* `cw_platform/orchestrator/`

### Core building blocks

Use these pages as the deep-dive index.

<table data-view="cards"><thead><tr><th>Topic</th><th data-card-target data-type="content-ref">Open</th></tr></thead><tbody><tr><td>Snapshots (inventories, checkpoints, drop guard)</td><td><a href="/spaces/3rh5THg1PdhVsBt3GALo/pages/zQ4XUsxclYjlv6NiKYDN">/spaces/3rh5THg1PdhVsBt3GALo/pages/zQ4XUsxclYjlv6NiKYDN</a></td></tr><tr><td>Planner (diff engine)</td><td><a href="/spaces/3rh5THg1PdhVsBt3GALo/pages/MCX2CnhexmZ152XSkUCa">/spaces/3rh5THg1PdhVsBt3GALo/pages/MCX2CnhexmZ152XSkUCa</a></td></tr><tr><td>Applier (write engine)</td><td><a href="/spaces/3rh5THg1PdhVsBt3GALo/pages/1qZ7r7y7Bdekdu8JvvrW">/spaces/3rh5THg1PdhVsBt3GALo/pages/1qZ7r7y7Bdekdu8JvvrW</a></td></tr><tr><td>State (baselines, checkpoints, guardrail internals)</td><td><a href="/spaces/3rh5THg1PdhVsBt3GALo/pages/a15hQCS2XtdMZzizOqbi">/spaces/3rh5THg1PdhVsBt3GALo/pages/a15hQCS2XtdMZzizOqbi</a></td></tr><tr><td>state.json schema and semantics</td><td><a href="/spaces/3rh5THg1PdhVsBt3GALo/pages/Z4QSDnQPvCnbbnL6jHKp">/spaces/3rh5THg1PdhVsBt3GALo/pages/Z4QSDnQPvCnbbnL6jHKp</a></td></tr><tr><td>One-way pipeline (src → dst)</td><td><a href="/spaces/3rh5THg1PdhVsBt3GALo/pages/c4ZzOhIGtLLdGbRtW59u">/spaces/3rh5THg1PdhVsBt3GALo/pages/c4ZzOhIGtLLdGbRtW59u</a></td></tr><tr><td>Two-way pipeline (A ↔ B)</td><td><a href="/spaces/3rh5THg1PdhVsBt3GALo/pages/RMf2mp4SIU4Ll3oBp2rY">/spaces/3rh5THg1PdhVsBt3GALo/pages/RMf2mp4SIU4Ll3oBp2rY</a></td></tr><tr><td>Conflicts (two-way resolution)</td><td><a href="/spaces/3rh5THg1PdhVsBt3GALo/pages/wKF2nlv3GlSiNlemxMri">/spaces/3rh5THg1PdhVsBt3GALo/pages/wKF2nlv3GlSiNlemxMri</a></td></tr><tr><td>Guardrails (safety model)</td><td><a href="/spaces/3rh5THg1PdhVsBt3GALo/pages/PLUzHHTi69SryahNZLpc">/spaces/3rh5THg1PdhVsBt3GALo/pages/PLUzHHTi69SryahNZLpc</a></td></tr><tr><td>Tombstones (deletion memory)</td><td><a href="/spaces/3rh5THg1PdhVsBt3GALo/pages/AbAHapoU4fVH9SPBWr36">/spaces/3rh5THg1PdhVsBt3GALo/pages/AbAHapoU4fVH9SPBWr36</a></td></tr><tr><td>Blackbox (quarantine flapping items)</td><td><a href="/spaces/3rh5THg1PdhVsBt3GALo/pages/V14K7oAKlQVLX9RCMLHx">/spaces/3rh5THg1PdhVsBt3GALo/pages/V14K7oAKlQVLX9RCMLHx</a></td></tr><tr><td>Phantom Guard (ghost add protection)</td><td><a href="/spaces/3rh5THg1PdhVsBt3GALo/pages/v5kstBTnHFLPb56jFq7a">/spaces/3rh5THg1PdhVsBt3GALo/pages/v5kstBTnHFLPb56jFq7a</a></td></tr><tr><td>Unresolved (stop retrying known-bad items)</td><td><a href="/spaces/3rh5THg1PdhVsBt3GALo/pages/KnMPtx1Y6mb3cXWb3723">/spaces/3rh5THg1PdhVsBt3GALo/pages/KnMPtx1Y6mb3cXWb3723</a></td></tr><tr><td>Blocklists (how guards block planned adds)</td><td><a href="/spaces/3rh5THg1PdhVsBt3GALo/pages/ZCP0BpNHARwYaQfxNBqr">/spaces/3rh5THg1PdhVsBt3GALo/pages/ZCP0BpNHARwYaQfxNBqr</a></td></tr><tr><td>Scope (pair scoping of caches + guard state)</td><td><a href="/spaces/3rh5THg1PdhVsBt3GALo/pages/AW0YhA9Rjjc0lx6UjKbg">/spaces/3rh5THg1PdhVsBt3GALo/pages/AW0YhA9Rjjc0lx6UjKbg</a></td></tr><tr><td>Health (provider health gates)</td><td><a href="/spaces/3rh5THg1PdhVsBt3GALo/pages/wb7Ll0gOfQcVcNezKShx">/spaces/3rh5THg1PdhVsBt3GALo/pages/wb7Ll0gOfQcVcNezKShx</a></td></tr><tr><td>Chunking (batch sizing + throttling)</td><td><a href="/spaces/3rh5THg1PdhVsBt3GALo/pages/GwGR7dqGHcqhXwsV1H5w">/spaces/3rh5THg1PdhVsBt3GALo/pages/GwGR7dqGHcqhXwsV1H5w</a></td></tr><tr><td>Caching layers (where data can get stale)</td><td><a href="/spaces/3rh5THg1PdhVsBt3GALo/pages/sXmNQGPmpKgsUrcxlrjP">/spaces/3rh5THg1PdhVsBt3GALo/pages/sXmNQGPmpKgsUrcxlrjP</a></td></tr><tr><td>Eventing (UI stream + logs)</td><td><a href="/spaces/3rh5THg1PdhVsBt3GALo/pages/VM7MMmJTEtteplXKtsL0">/spaces/3rh5THg1PdhVsBt3GALo/pages/VM7MMmJTEtteplXKtsL0</a></td></tr><tr><td>Runtime knobs (debug, caching, chunking)</td><td><a href="/spaces/3rh5THg1PdhVsBt3GALo/pages/m6d9opnFI1d5b6WDQCFY">/spaces/3rh5THg1PdhVsBt3GALo/pages/m6d9opnFI1d5b6WDQCFY</a></td></tr><tr><td>Provider contract (InventoryOps)</td><td><a href="/spaces/3rh5THg1PdhVsBt3GALo/pages/hu8h2Z0UY1qPrfuPatwn">/spaces/3rh5THg1PdhVsBt3GALo/pages/hu8h2Z0UY1qPrfuPatwn</a></td></tr><tr><td>Provider specifics (real-world quirks)</td><td><a href="/spaces/3rh5THg1PdhVsBt3GALo/pages/QIYFjuLYtkbmT4FbN0PO">/spaces/3rh5THg1PdhVsBt3GALo/pages/QIYFjuLYtkbmT4FbN0PO</a></td></tr></tbody></table>
{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://wiki.crosswatch.app/blueprint-architecture/orchestrator.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.