Designing an explainable sync ledger for watch state across media servers

Description and use

Watch-state sync across media servers is complicated by differing IDs, library rebuilds, and rewatches. The solution is a canonical event record, per-destination delivery logs, and an operational ledger that explains each outcome and supports recovery.

Problem

Synchronizing watch state across multiple media servers is complicated by differing provider identities, library rebuilds, delayed webhooks, and repeated watches, making a simple watched flag insufficient.

Outcome

The system now provides transparent, recoverable watch state synchronization across multiple media servers, with clear evidence for each delivery outcome and a robust recovery workflow.

Workflow

• 1. Create a stable internal identity for each media item to decouple from provider-specific IDs.
• 2. Record a canonical watch event with explicit lifecycle states (new, repeated, partial, completed, corrected).
• 3. For each destination, log a delivery record containing source event, destination, outcome, reason, attempt time, and retry context.
• 4. When conflicts arise, preserve evidence, identify the stronger signal, and document the decision.
• 5. Handle rewatches with distinct event semantics to avoid duplicate imports.
• 6. For library rebuilds, perform conservative matching, surface uncertainty, and require manual review before bulk changes.
• 7. Back up the system before major changes, test with a small library, and expand after verifying Sync Activity results.
• 8. Run integration tests covering onboarding, manual review, retries, backups, metadata, and visible reasons for each outcome.
• 9. Use AI assistance during development to generate changes, but not at runtime.
• 10. Provide documentation for recovery steps and provider actions that are irreversible.

Evidence

A boolean watched flag is not enough to explain what happened.

Source

The sync layer needs a stable internal identity and an explicit review path when a match is uncertain.

Source

The record is the basis of Plembfin's Sync Activity view.

Source