Rulesets

Configure playlist synchronization behavior and advanced rules.

Rulesets control direction, membership, ordering, aggregation, partitioning, capacities, and assignment.

Use Direct sync for most setups. Choose Custom only when you need detailed settings.

Presets

• Direct sync — One-way, direct, managed membership, unordered, one target.
• Mirror source — One-way, direct, mirrored membership, preserved order.
• Split large playlists — Partitioned writes with capacity and stable assignments.
• Merge playlists — Aggregate reads with direct writes.
• Limited account sharing — Bidirectional aggregate reads and partitioned writes.
• Custom — Exposes detailed ruleset fields.

Membership

Add only

Adds missing source items to the destination. It never removes destination items.

Use it when you also manage destination items manually.

Managed only

Adds missing source items and removes items CrossWatch previously managed.

It leaves destination-only items unchanged. This is the normal Direct sync behavior.

Mirror

Makes destination membership match the source. It can remove destination items absent from the source.

Use Mirror only when the source fully controls the destination.

Ordering

Use Preserve to request the source order on the destination.

If reordering is unsupported, CrossWatch reports a warning. Mappings reject preserve when a destination is known to be unordered.

Schema

The current ruleset schema version is 1.

direction: one_way | bidirectional
initial_sync: source_authoritative
read_mode: direct | aggregate
write_mode: direct | partition
membership: add_only | managed_only | mirror
order: ignore | preserve
deduplicate: canonical_id
allocation: stable_first_fit
rebalance: never
overflow: block

Numeric fields:

per_endpoint_capacity
aggregate_capacity
maximum_targets

track_assignments controls stable item placement between runs.

Aggregate, partition, and capacity

Aggregate mode treats several playlist resources as one logical inventory.

Partition mode distributes managed items across target endpoints.

Advanced execution requires aggregate reads with partitioned writes.

stable_first_fit assigns items predictably. track_assignments preserves those placements.

rebalance = never avoids moving assigned items only to equalize targets.

overflow = block prevents silently exceeding logical capacity.

per_endpoint_capacity limits each target. aggregate_capacity limits all targets. maximum_targets limits target count.

These values are ruleset controls, not provider guarantees.

Built-in TraktFree ruleset

TraktFree uses:

direction = bidirectional
initial_sync = source_authoritative
read_mode = aggregate
write_mode = partition
membership = managed_only
order = ignore
deduplicate = canonical_id
allocation = stable_first_fit
rebalance = never
overflow = block
per_endpoint_capacity = 250
aggregate_capacity = 1000
maximum_targets = 5
track_assignments = true

These capacities describe CrossWatch configuration. They do not guarantee provider plan limits.

Safety and execution

Large removal plans use the shared mass-delete guard.

The decision uses suspect thresholds and allow_mass_delete.

Verify both snapshots, profile selection, and baseline before allowing mass deletion.

Dry runs calculate additions, removals, and ordering without provider writes.

Use dry runs after changing topology or destructive rulesets.

Plans track source, target, resolved, unresolved, addition, removal, reorder, and warning counts.

Applied results are stored as last_result and shown in the UI.

Unresolved items do not always fail the entire run. They could not be safely written.

Recommended approach

1. Start with Direct sync and managed_only.
2. Run a dry run after ruleset or topology changes.
3. Review unresolved items before allowing stricter removals.
4. Use Mirror only when destination-only items should be removed.
5. Use aggregate and partition rulesets only for real capacity constraints.