A sync ledger is only useful when it leads to a safe next step

Plekt — Mon, 19 Oct 2026 14:23:03 +0000

In my earlier post about designing an explainable sync ledger, I argued that one synced or failed flag hides too much. The implementation raises another question: after recording a result, can someone tell what to do safely?

One title, several outcomes

A movie or episode may succeed on two destinations and need attention on a third. A single global result loses that detail.

Plekt's Sync Activity groups history by movie or show while keeping each destination's result available behind the group. It records reasons for skipped destinations, exposes Fix match for unresolved cross-platform matches, and targets retries at failed destinations. Expected missing-library skips are excluded from retries. Group logs can be downloaded for investigation.

Those outcomes need different recovery paths:

An unresolved identity needs a match decision.
A failed destination may be retried.
An expected missing-library skip should remain a skip.

Treating each as the same kind of failure would repeat work without resolving the underlying cause.

Fresh evidence before changing watch state

Some problems start before delivery. In v2.1.1, the Plex watch-state path preserves completed state across stale resume data and protects against unwatch races. Suspected Plex unwatches are rechecked against live metadata, and cached episode state is kept aligned so stale reports do not reach manual watch review.

These are targeted safeguards, not a claim that every provider-history edge case is solved. They address one important boundary: check that a signal is current before interpreting it as a change to watch history.

The question I keep asking

For each item, can someone see what happened, which destination received it or why it did not, and whether the safe next step is to retry, fix a match, review, or leave it alone?

That is the difference between a history table and an operational tool. The row is not the goal. A clear explanation and a safe recovery path are.

This follows the original design post. The v2.1.1 release notes include the Plex changes and the current known limitations.

I'd be interested in how other media integrations distinguish a real unwatch from stale resume data.

Try Plekt

Plekt is open source and self-hosted: project and source, website, live demo, Discord community, and r/plekt.

Disclosure: I maintain Plekt. I used AI assistance to draft this post under my direction, checked the technical details against the current release notes and project docs, and AI is not part of the application at runtime.

Designing an explainable sync ledger for watch state across media servers

Plekt — Thu, 10 Sep 2026 10:23:06 +0000

Update (27 October 2026): Replaced older screenshots with current Plekt UI captures.

Watch-state synchronization looks simple until the same episode has four provider identities, a rebuilt library, a delayed webhook, and a user who watched it twice.

A boolean watched flag is not enough to explain what happened. A useful sync system needs a canonical record, an event lifecycle, per-destination evidence, and a recovery path that a person can understand.

Why watched and unwatched are insufficient

A destination can be behind, unavailable, ambiguous, or based on a different item identity. Treating the latest provider response as absolute truth makes a sync layer overwrite information without showing why.

A better model keeps the canonical record separate from delivery state. The canonical record answers what the local system believes. Delivery records answer what each destination received, when it was attempted, and why a retry is or is not needed.

Canonical identity and event lifecycle

The first hard problem is identity. A movie or episode can be represented differently after a library rebuild or across Plex, Emby, Jellyfin, and Trakt. The sync layer needs a stable internal identity and an explicit review path when a match is uncertain.

The second hard problem is lifecycle. A play can be new, repeated, partially watched, completed, corrected, or superseded by a newer state. Each transition should be idempotent so retrying a delivery does not create a second play by accident.

Per-destination delivery results

A single sync status hides too much. For each destination, record the source event, destination, outcome, reason, attempt time, and retry context. This turns a vague failure into an actionable answer such as a missing match, a rate limit, a provider outage, or a deliberate manual review.

That record is the basis of Plekt's Sync Activity view. It is designed as an operational ledger, not a green checkmark that asks the user to trust an invisible process.

Conflicts, rewatches, and rebuilt libraries

Conflict handling needs to be explicit. When two sources disagree, the system should preserve the evidence, identify the newer or stronger signal, and explain the choice. Rewatches need their own event semantics so a repeat play is not mistaken for a duplicate import.

A rebuilt library is a recovery case, not just another sync. Matching should be conservative, surface uncertainty, and let a person review before a large batch changes history.

Backup and recovery boundaries

Backups are part of the feature. A safe workflow starts with a backup and a small library, then expands after the Sync Activity results look correct. Recovery documentation should state what can be restored, what needs to be reconnected, and which provider actions are not reversible.

Testing provider integrations

Integration tests cover request and response handling, but browser flows matter too. A practical test pass checks onboarding, manual watch review, retries, backups, metadata, and the visible reason attached to each delivery outcome. The test data should include missing matches, provider failures, duplicate plays, partial progress, and a rebuilt library.

AI assistance and review

Plekt was heavily AI-assisted under my direction. I reviewed the generated changes, tested the integrations and browser flows, and maintain the project. AI is not required at runtime. This article is a technical explanation of the design and its trade-offs, not a claim that the difficult edge cases are solved.

Back up first and test with a small library.

DEV Community: Plekt