@webex/plugin-meetings 3.12.0-next.5 → 3.12.0-next.50

package/test/unit/spec/hashTree/hashTreeParser.ts

@@ -7,6 +7,9 @@ import {expect} from '@webex/test-helper-chai';
 import sinon from 'sinon';
 import {assert} from '@webex/test-helper-chai';
 import {EMPTY_HASH} from '@webex/plugin-meetings/src/hashTree/constants';
+import { some } from 'lodash';
+import Metrics from '@webex/plugin-meetings/src/metrics';
+import BEHAVIORAL_METRICS from '@webex/plugin-meetings/src/metrics/constants';
 
 const visibleDataSetsUrl = 'https://locus-a.wbx2.com/locus/api/v1/loci/97d64a5f/visibleDataSets';
 
@@ -151,16 +154,19 @@ describe('HashTreeParser', () => {
   let webexRequest: sinon.SinonStub;
   let callback: sinon.SinonStub;
   let mathRandomStub: sinon.SinonStub;
+  let metricsStub: sinon.SinonStub;
 
   beforeEach(() => {
     clock = sinon.useFakeTimers();
     webexRequest = sinon.stub();
     callback = sinon.stub();
     mathRandomStub = sinon.stub(Math, 'random').returns(0);
+    metricsStub = sinon.stub(Metrics, 'sendBehavioralMetric');
   });
   afterEach(() => {
     clock.restore();
     mathRandomStub.restore();
+    metricsStub.restore();
   });
 
   // Helper to create a HashTreeParser instance with common defaults
@@ -553,7 +559,7 @@ describe('HashTreeParser', () => {
     );
 
     // Verify callback was called with OBJECTS_UPDATED and correct updatedObjects list
-    assert.calledWith(callback, LocusInfoUpdateType.OBJECTS_UPDATED, {
+    assert.calledWith(callback, {updateType: LocusInfoUpdateType.OBJECTS_UPDATED,
       updatedObjects: [
         {
           htMeta: {
@@ -566,6 +572,11 @@ describe('HashTreeParser', () => {
           },
           data: {info: {id: 'some-fake-locus-info'}},
         },
+      ],
+    });
+
+    assert.calledWith(callback, {updateType: LocusInfoUpdateType.OBJECTS_UPDATED,
+      updatedObjects: [
         {
           htMeta: {
             elementId: {
@@ -596,6 +607,67 @@ describe('HashTreeParser', () => {
       });
     });
 
+    it('initializes "main" before "self" regardless of order from Locus', async () => {
+      const parser = createHashTreeParser({dataSets: [], locus: null}, null);
+
+      // Locus returns datasets in non-priority order: atd-active, main, self
+      const atdActiveDataSet = createDataSet('atd-active', 4, 500);
+      const mainDataSet = createDataSet('main', 16, 1100);
+      const selfDataSet = createDataSet('self', 1, 2100);
+
+      mockGetAllDataSetsMetadata(webexRequest, visibleDataSetsUrl, [
+        atdActiveDataSet,
+        mainDataSet,
+        selfDataSet,
+      ]);
+
+      mockSyncRequest(webexRequest, selfDataSet.url);
+      mockSyncRequest(webexRequest, mainDataSet.url);
+      mockSyncRequest(webexRequest, atdActiveDataSet.url);
+
+      await parser.initializeFromMessage({
+        dataSets: [],
+        visibleDataSetsUrl,
+        locusUrl,
+      });
+
+      // Verify sync requests were sent in priority order: main, self, then atd-active
+      const syncCalls = webexRequest
+        .getCalls()
+        .filter((call) => call.args[0]?.method === 'POST' && call.args[0]?.uri?.endsWith('/sync'));
+
+      expect(syncCalls).to.have.lengthOf(3);
+      expect(syncCalls[0].args[0].uri).to.equal(`${mainDataSet.url}/sync`);
+      expect(syncCalls[1].args[0].uri).to.equal(`${selfDataSet.url}/sync`);
+      expect(syncCalls[2].args[0].uri).to.equal(`${atdActiveDataSet.url}/sync`);
+    });
+
+    it('sends leafCount=1 with a single empty leaf for initialization sync, regardless of actual dataset leafCount', async () => {
+      const parser = createHashTreeParser({dataSets: [], locus: null}, null);
+
+      // Use a dataset with leafCount=16 to verify the initialization sync always uses leafCount=1
+      const mainDataSet = createDataSet('main', 16, 1100);
+
+      mockGetAllDataSetsMetadata(webexRequest, visibleDataSetsUrl, [mainDataSet]);
+      mockSyncRequest(webexRequest, mainDataSet.url);
+
+      await parser.initializeFromMessage({
+        dataSets: [],
+        visibleDataSetsUrl,
+        locusUrl,
+      });
+
+      assert.calledWith(webexRequest, {
+        method: 'POST',
+        uri: `${mainDataSet.url}/sync`,
+        qs: {rootHash: sinon.match.string},
+        body: {
+          leafCount: 1,
+          leafDataEntries: [{leafIndex: 0, elementIds: []}],
+        },
+      });
+    });
+
     it('handles sync response that has locusStateElements undefined', async () => {
       const minimalInitialLocus = {
         dataSets: [],
@@ -788,7 +860,7 @@ describe('HashTreeParser', () => {
       expect(parser.dataSets.self.version).to.equal(2100);
       expect(parser.dataSets['atd-unmuted'].version).to.equal(3100);
 
-      assert.calledOnceWithExactly(callback, LocusInfoUpdateType.OBJECTS_UPDATED, {
+      assert.calledOnceWithExactly(callback, {updateType: LocusInfoUpdateType.OBJECTS_UPDATED,
         updatedObjects: [
           {
             htMeta: {
@@ -861,6 +933,116 @@ describe('HashTreeParser', () => {
       });
     });
 
+    it('handles updates to control entries correctly', () => {
+      const parser = createHashTreeParser();
+
+      const mainPutItemsSpy = sinon.spy(parser.dataSets.main.hashTree, 'putItems');
+
+      // Create a locus update with new htMeta information for some things
+      const locusUpdate = {
+        dataSets: [
+          createDataSet('main', 16, 1100),
+        ],
+        locus: {
+          url: 'https://locus-a.wbx2.com/locus/api/v1/loci/97d64a5f',
+          htMeta: {
+            elementId: {
+              type: 'locus',
+              id: 0,
+              version: 200, // same version
+            },
+            dataSetNames: ['main'],
+          },
+          participants: [],
+          controls: {
+            lock: {
+              locked: true,
+              htMeta: {
+                elementId: {
+                  type: 'ControlEntry',
+                  id: 10100,
+                  version: 100,
+                },
+                dataSetNames: ['main'],
+              },
+            },
+            stream: {
+              streaming: true,
+              htMeta: {
+                elementId: {
+                  type: 'ControlEntry',
+                  id: 10101,
+                  version: 100,
+                },
+                dataSetNames: ['main'],
+              },
+            } 
+          }
+        },
+      };
+
+      // Call handleLocusUpdate
+      parser.handleLocusUpdate(locusUpdate);
+
+      // Verify putItems was called on main hash tree with correct data
+      assert.calledOnceWithExactly(mainPutItemsSpy, [
+        {type: 'locus', id: 0, version: 200},
+        {type: 'ControlEntry', id: 10100, version: 100},
+        {type: 'ControlEntry', id: 10101, version: 100}
+      ]);
+
+      assert.calledOnceWithExactly(callback, {updateType: LocusInfoUpdateType.OBJECTS_UPDATED,
+        updatedObjects: [
+          {
+            htMeta: {
+              elementId: {
+                type: 'ControlEntry',
+                id: 10100,
+                version: 100,
+              },
+              dataSetNames: ['main'],
+            },
+            data: {
+              lock: {
+                locked: true,
+                htMeta: {
+                  elementId: {
+                    type: 'ControlEntry',
+                    id: 10100,
+                    version: 100,
+                  },
+                  dataSetNames: ['main'],
+                },
+              },
+            },
+          },
+          {
+            htMeta: {
+              elementId: {
+                type: 'ControlEntry',
+                id: 10101,
+                version: 100,
+              },
+              dataSetNames: ['main'],
+            },
+            data: {
+              stream: {
+                streaming: true,
+                htMeta: {
+                  elementId: {
+                    type: 'ControlEntry',
+                    id: 10101,
+                    version: 100,
+                  },
+                  dataSetNames: ['main'],
+                },
+              },
+            },
+          }
+        ],
+      });
+    });
+
     it('handles unknown datasets gracefully', () => {
       const parser = createHashTreeParser();
 
@@ -899,7 +1081,7 @@ describe('HashTreeParser', () => {
       assert.calledOnceWithExactly(mainPutItemsSpy, [{type: 'locus', id: 0, version: 201}]);
 
       // Verify callback was called only for known dataset
-      assert.calledOnceWithExactly(callback, LocusInfoUpdateType.OBJECTS_UPDATED, {
+      assert.calledOnceWithExactly(callback, {updateType: LocusInfoUpdateType.OBJECTS_UPDATED,
         updatedObjects: [
           {
             htMeta: {
@@ -999,7 +1181,7 @@ describe('HashTreeParser', () => {
       assert.calledOnceWithExactly(selfPutItemSpy, {type: 'metadata', id: 5, version: 51});
 
       // Verify callback was called with metadata object and removed dataset objects
-      assert.calledOnceWithExactly(callback, LocusInfoUpdateType.OBJECTS_UPDATED, {
+      assert.calledOnceWithExactly(callback, {updateType: LocusInfoUpdateType.OBJECTS_UPDATED,
         updatedObjects: [
           // updated metadata object:
           {
@@ -1160,7 +1342,7 @@ describe('HashTreeParser', () => {
       assert.notCalled(atdUnmutedPutItemsSpy);
 
       // Verify callback was called with the updated object
-      assert.calledOnceWithExactly(callback, LocusInfoUpdateType.OBJECTS_UPDATED, {
+      assert.calledOnceWithExactly(callback, {updateType: LocusInfoUpdateType.OBJECTS_UPDATED,
         updatedObjects: [
           {
             htMeta: {
@@ -1388,7 +1570,7 @@ describe('HashTreeParser', () => {
       ]);
 
       // Verify callback was called with OBJECTS_UPDATED and all updated objects
-      assert.calledOnceWithExactly(callback, LocusInfoUpdateType.OBJECTS_UPDATED, {
+      assert.calledOnceWithExactly(callback, {updateType: LocusInfoUpdateType.OBJECTS_UPDATED,
         updatedObjects: [
           {
             htMeta: {
@@ -1453,9 +1635,7 @@ describe('HashTreeParser', () => {
           parser.handleMessage(sentinelMessage, 'sentinel message');
 
           // Verify callback was called with MEETING_ENDED
-          assert.calledOnceWithExactly(callback, LocusInfoUpdateType.MEETING_ENDED, {
-            updatedObjects: undefined,
-          });
+          assert.calledOnceWithExactly(callback, {updateType: LocusInfoUpdateType.MEETING_ENDED});
 
           // Verify that all timers were stopped
           Object.values(parser.dataSets).forEach((ds: any) => {
@@ -1477,9 +1657,7 @@ describe('HashTreeParser', () => {
         parser.handleMessage(sentinelMessage, 'sentinel message');
 
         // Verify callback was called with MEETING_ENDED
-        assert.calledOnceWithExactly(callback, LocusInfoUpdateType.MEETING_ENDED, {
-          updatedObjects: undefined,
-        });
+        assert.calledOnceWithExactly(callback, {updateType: LocusInfoUpdateType.MEETING_ENDED});
 
         // Verify that all timers were stopped
         Object.values(parser.dataSets).forEach((ds: any) => {
@@ -1575,7 +1753,7 @@ describe('HashTreeParser', () => {
         );
 
         // Verify that callback was called with synced objects
-        assert.calledOnceWithExactly(callback, LocusInfoUpdateType.OBJECTS_UPDATED, {
+        assert.calledOnceWithExactly(callback, {updateType: LocusInfoUpdateType.OBJECTS_UPDATED,
           updatedObjects: [
             {
               htMeta: {
@@ -1637,15 +1815,16 @@ describe('HashTreeParser', () => {
             await clock.tickAsync(1000);
 
             // Verify callback was called with MEETING_ENDED
-            assert.calledOnceWithExactly(callback, LocusInfoUpdateType.MEETING_ENDED, {
-              updatedObjects: undefined,
-            });
+            assert.calledOnceWithExactly(callback, {updateType: LocusInfoUpdateType.MEETING_ENDED});
 
             // Verify all timers are stopped
             Object.values(parser.dataSets).forEach((ds: any) => {
               assert.isUndefined(ds.timer);
               assert.isUndefined(ds.heartbeatWatchdogTimer);
             });
+
+            // Verify no sync failure metric was sent for end-meeting sentinel
+            assert.notCalled(metricsStub);
           });
 
           it(`when /sync returns ${statusCode}`, async () => {
@@ -1702,15 +1881,16 @@ describe('HashTreeParser', () => {
             await clock.tickAsync(1000);
 
             // Verify callback was called with MEETING_ENDED
-            assert.calledOnceWithExactly(callback, LocusInfoUpdateType.MEETING_ENDED, {
-              updatedObjects: undefined,
-            });
+            assert.calledOnceWithExactly(callback, {updateType: LocusInfoUpdateType.MEETING_ENDED});
 
             // Verify all timers are stopped
             Object.values(parser.dataSets).forEach((ds: any) => {
               assert.isUndefined(ds.timer);
               assert.isUndefined(ds.heartbeatWatchdogTimer);
             });
+
+            // Verify no sync failure metric was sent for end-meeting sentinel
+            assert.notCalled(metricsStub);
           });
         });
       });
@@ -1883,144 +2063,364 @@ describe('HashTreeParser', () => {
           },
         });
       });
-    });
 
-    describe('handles visible data sets changes correctly', () => {
-      it('handles addition of visible data set (one that does not require async initialization)', async () => {
-        // Create a parser with visible datasets
+      it('restarts the sync timer when sync response is empty so that a future sync can be triggered', async () => {
         const parser = createHashTreeParser();
 
-        // Stub updateItems on self hash tree to return true
-        sinon.stub(parser.dataSets.self.hashTree, 'updateItems').returns([true]);
-
-        // Send a message with Metadata object that has a new visibleDataSets list
-        const message = {
-          dataSets: [createDataSet('self', 1, 2100), createDataSet('attendees', 8, 4000)],
-          visibleDataSetsUrl,
-          locusUrl,
-          locusStateElements: [
+        // Send a heartbeat with a mismatched root hash to trigger runSyncAlgorithm
+        const heartbeatMessage = {
+          dataSets: [
             {
-              htMeta: {
-                elementId: {
-                  type: 'metadata' as const,
-                  id: 5,
-                  version: 51,
-                },
-                dataSetNames: ['self'],
-              },
-              data: {
-                visibleDataSets: [
-                  {
-                    name: 'main',
-                    url: 'https://locus-a.wbx2.com/locus/api/v1/loci/97d64a5f/datasets/main',
-                  },
-                  {
-                    name: 'self',
-                    url: 'https://locus-a.wbx2.com/locus/api/v1/loci/97d64a5f/participant/713e9f99/datasets/self',
-                  },
-                  {
-                    name: 'atd-unmuted',
-                    url: 'https://locus-a.wbx2.com/locus/api/v1/loci/97d64a5f/datasets/atd-unmuted',
-                  },
-                  {
-                    name: 'attendees',
-                    url: 'https://locus-a.wbx2.com/locus/api/v1/loci/97d64a5f/datasets/attendees',
-                  },
-                ], // added 'attendees'
-              },
+              ...createDataSet('main', 16, 1100),
+              root: 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa1', // different from ours
             },
           ],
+          visibleDataSetsUrl,
+          locusUrl,
         };
 
-        parser.handleMessage(message, 'add visible dataset');
+        parser.handleMessage(heartbeatMessage, 'heartbeat with mismatch');
 
-        // Verify that 'attendees' was added to visibleDataSets
-        expect(parser.visibleDataSets.some((vds) => vds.name === 'attendees')).to.be.true;
+        // The sync timer should be set
+        expect(parser.dataSets.main.timer).to.not.be.undefined;
 
-        // Verify that a hash tree was created for 'attendees'
-        assert.exists(parser.dataSets.attendees.hashTree);
-        assert.equal(parser.dataSets.attendees.hashTree.numLeaves, 8);
+        // Mock responses for the first sync - return null (204/empty body)
+        const mainDataSetUrl = parser.dataSets.main.url;
+        mockGetHashesFromLocusResponse(
+          mainDataSetUrl,
+          new Array(16).fill('00000000000000000000000000000000'),
+          {
+            ...createDataSet('main', 16, 1101),
+            root: 'bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb', // still mismatched
+          }
+        );
+        mockSendSyncRequestResponse(mainDataSetUrl, null);
 
-        // Verify callback was called with the metadata update (appears twice - processed once for visible dataset changes, once in main loop)
-        assert.calledOnceWithExactly(callback, LocusInfoUpdateType.OBJECTS_UPDATED, {
-          updatedObjects: [
-            {
-              htMeta: {
-                elementId: {type: 'metadata', id: 5, version: 51},
-                dataSetNames: ['self'],
-              },
-              data: {
-                visibleDataSets: [
-                  {
-                    name: 'main',
-                    url: 'https://locus-a.wbx2.com/locus/api/v1/loci/97d64a5f/datasets/main',
-                  },
-                  {
-                    name: 'self',
-                    url: 'https://locus-a.wbx2.com/locus/api/v1/loci/97d64a5f/participant/713e9f99/datasets/self',
-                  },
-                  {
-                    name: 'atd-unmuted',
-                    url: 'https://locus-a.wbx2.com/locus/api/v1/loci/97d64a5f/datasets/atd-unmuted',
-                  },
-                  {
-                    name: 'attendees',
-                    url: 'https://locus-a.wbx2.com/locus/api/v1/loci/97d64a5f/datasets/attendees',
-                  },
-                ],
-              },
-            },
-            {
-              htMeta: {
-                elementId: {type: 'metadata', id: 5, version: 51},
-                dataSetNames: ['self'],
-              },
-              data: {
-                visibleDataSets: [
-                  {
-                    name: 'main',
-                    url: 'https://locus-a.wbx2.com/locus/api/v1/loci/97d64a5f/datasets/main',
-                  },
-                  {
-                    name: 'self',
-                    url: 'https://locus-a.wbx2.com/locus/api/v1/loci/97d64a5f/participant/713e9f99/datasets/self',
-                  },
-                  {
-                    name: 'atd-unmuted',
-                    url: 'https://locus-a.wbx2.com/locus/api/v1/loci/97d64a5f/datasets/atd-unmuted',
-                  },
-                  {
-                    name: 'attendees',
-                    url: 'https://locus-a.wbx2.com/locus/api/v1/loci/97d64a5f/datasets/attendees',
-                  },
-                ],
-              },
-            },
-          ],
-        });
-      });
+        // Advance time to fire the sync timer (idleMs=1000 + backoff=0)
+        await clock.tickAsync(1000);
 
-      it('handles addition of visible data set (one that requires async initialization)', async () => {
-        // Create a parser with visible datasets
-        const parser = createHashTreeParser();
+        // Verify sync was triggered
+        assert.calledWith(
+          webexRequest,
+          sinon.match({
+            method: 'POST',
+            uri: `${mainDataSetUrl}/sync`,
+          })
+        );
 
-        // Stub updateItems on self hash tree to return true
-        sinon.stub(parser.dataSets.self.hashTree, 'updateItems').returns([true]);
+        // After empty response, runSyncAlgorithm should have been called,
+        // setting a new sync timer as a safety net
+        expect(parser.dataSets.main.timer).to.not.be.undefined;
 
-        // Send a message with Metadata object that has a new visibleDataSets list (adding 'new-dataset')
-        // but WITHOUT providing info about the new dataset in dataSets array
-        const message = {
-          dataSets: [createDataSet('self', 1, 2100)],
-          visibleDataSetsUrl,
-          locusUrl,
-          locusStateElements: [
-            {
-              htMeta: {
-                elementId: {
-                  type: 'metadata' as const,
-                  id: 5,
-                  version: 51,
-                },
+        // Reset and set up mocks for the second sync
+        webexRequest.resetHistory();
+        mockGetHashesFromLocusResponse(
+          mainDataSetUrl,
+          new Array(16).fill('00000000000000000000000000000000'),
+          {
+            ...createDataSet('main', 16, 1102),
+            root: 'cccccccccccccccccccccccccccccccc', // still mismatched
+          }
+        );
+        mockSendSyncRequestResponse(mainDataSetUrl, null);
+
+        // Advance time again to fire the second sync timer
+        await clock.tickAsync(1000);
+
+        // Verify a second sync was triggered
+        assert.calledWith(
+          webexRequest,
+          sinon.match({
+            method: 'POST',
+            uri: `${mainDataSetUrl}/sync`,
+          })
+        );
+      });
+
+      it('updates dataSet.leafCount when hash tree is resized during sync so that the sync request has the correct leafCount', async () => {
+        const parser = createHashTreeParser();
+
+        // Send a heartbeat with a mismatched root hash to trigger runSyncAlgorithm
+        const heartbeatMessage = {
+          dataSets: [
+            {
+              ...createDataSet('main', 16, 1100),
+              root: 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa1', // different from ours
+            },
+          ],
+          visibleDataSetsUrl,
+          locusUrl,
+        };
+
+        parser.handleMessage(heartbeatMessage, 'heartbeat with mismatch');
+
+        // The sync timer should be set
+        expect(parser.dataSets.main.timer).to.not.be.undefined;
+
+        const mainDataSetUrl = parser.dataSets.main.url;
+        const newLeafCount = 32;
+
+        // Mock getHashesFromLocus response with a DIFFERENT leafCount (32 instead of 16)
+        mockGetHashesFromLocusResponse(
+          mainDataSetUrl,
+          new Array(newLeafCount).fill('00000000000000000000000000000000'),
+          createDataSet('main', newLeafCount, 1101)
+        );
+
+        // Mock the sync request - use matching root hash
+        const syncResponseDataSet = createDataSet('main', newLeafCount, 1102);
+        syncResponseDataSet.root = parser.dataSets.main.hashTree.getRootHash();
+        mockSendSyncRequestResponse(mainDataSetUrl, {
+          dataSets: [syncResponseDataSet],
+          visibleDataSetsUrl,
+          locusUrl,
+          locusStateElements: [],
+        });
+
+        // Advance time to fire the sync timer (idleMs=1000 + backoff=0)
+        await clock.tickAsync(1000);
+
+        // Verify the sync request was sent with the NEW leafCount (32), not the old one (16)
+        assert.calledWith(
+          webexRequest,
+          sinon.match({
+            method: 'POST',
+            uri: `${mainDataSetUrl}/sync`,
+            body: sinon.match({
+              leafCount: newLeafCount,
+            }),
+          })
+        );
+      });
+
+      it('sends HASH_TREE_SYNC_FAILURE metric when GET /hashtree request fails', async () => {
+        const parser = createHashTreeParser();
+
+        // Send a heartbeat with a mismatched root hash to trigger runSyncAlgorithm
+        const heartbeatMessage = {
+          dataSets: [
+            {
+              ...createDataSet('main', 16, 1100),
+              root: 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa1',
+            },
+          ],
+          visibleDataSetsUrl,
+          locusUrl,
+        };
+
+        parser.handleMessage(heartbeatMessage, 'heartbeat with mismatch');
+
+        const mainDataSetUrl = parser.dataSets.main.url;
+        const hashTreeError = new Error('server error') as any;
+        hashTreeError.statusCode = 500;
+
+        webexRequest
+          .withArgs(
+            sinon.match({
+              method: 'GET',
+              uri: `${mainDataSetUrl}/hashtree`,
+            })
+          )
+          .rejects(hashTreeError);
+
+        await clock.tickAsync(1000);
+
+        assert.calledOnceWithExactly(metricsStub, BEHAVIORAL_METRICS.HASH_TREE_SYNC_FAILURE, {
+          debugId: 'test',
+          dataSetName: 'main',
+          request: 'GET /hashtree',
+          statusCode: 500,
+          reason: 'server error',
+        });
+      });
+
+      it('sends HASH_TREE_SYNC_FAILURE metric when POST /sync request fails', async () => {
+        const parser = createHashTreeParser();
+
+        // Send a heartbeat with a mismatched root hash to trigger runSyncAlgorithm
+        const heartbeatMessage = {
+          dataSets: [
+            {
+              ...createDataSet('main', 16, 1100),
+              root: 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa1',
+            },
+          ],
+          visibleDataSetsUrl,
+          locusUrl,
+        };
+
+        parser.handleMessage(heartbeatMessage, 'heartbeat with mismatch');
+
+        const mainDataSetUrl = parser.dataSets.main.url;
+
+        // Mock getHashesFromLocus to succeed
+        mockGetHashesFromLocusResponse(
+          mainDataSetUrl,
+          new Array(16).fill('00000000000000000000000000000000'),
+          createDataSet('main', 16, 1101)
+        );
+
+        // Mock sendSyncRequestToLocus to fail
+        const syncError = new Error('sync failed') as any;
+        syncError.statusCode = 500;
+
+        webexRequest
+          .withArgs(
+            sinon.match({
+              method: 'POST',
+              uri: `${mainDataSetUrl}/sync`,
+            })
+          )
+          .rejects(syncError);
+
+        await clock.tickAsync(1000);
+
+        assert.calledOnceWithExactly(metricsStub, BEHAVIORAL_METRICS.HASH_TREE_SYNC_FAILURE, {
+          debugId: 'test',
+          dataSetName: 'main',
+          request: 'POST /sync',
+          statusCode: 500,
+          reason: 'sync failed',
+        });
+      });
+    });
+
+    describe('handles visible data sets changes correctly', () => {
+      it('handles addition of visible data set (one that does not require async initialization)', async () => {
+        // Create a parser with visible datasets
+        const parser = createHashTreeParser();
+
+        // Stub updateItems on self hash tree to return true
+        sinon.stub(parser.dataSets.self.hashTree, 'updateItems').returns([true]);
+
+        // Send a message with Metadata object that has a new visibleDataSets list
+        const message = {
+          dataSets: [createDataSet('self', 1, 2100), createDataSet('attendees', 8, 4000)],
+          visibleDataSetsUrl,
+          locusUrl,
+          locusStateElements: [
+            {
+              htMeta: {
+                elementId: {
+                  type: 'metadata' as const,
+                  id: 5,
+                  version: 51,
+                },
+                dataSetNames: ['self'],
+              },
+              data: {
+                visibleDataSets: [
+                  {
+                    name: 'main',
+                    url: 'https://locus-a.wbx2.com/locus/api/v1/loci/97d64a5f/datasets/main',
+                  },
+                  {
+                    name: 'self',
+                    url: 'https://locus-a.wbx2.com/locus/api/v1/loci/97d64a5f/participant/713e9f99/datasets/self',
+                  },
+                  {
+                    name: 'atd-unmuted',
+                    url: 'https://locus-a.wbx2.com/locus/api/v1/loci/97d64a5f/datasets/atd-unmuted',
+                  },
+                  {
+                    name: 'attendees',
+                    url: 'https://locus-a.wbx2.com/locus/api/v1/loci/97d64a5f/datasets/attendees',
+                  },
+                ], // added 'attendees'
+              },
+            },
+          ],
+        };
+
+        parser.handleMessage(message, 'add visible dataset');
+
+        // Verify that 'attendees' was added to visibleDataSets
+        expect(parser.visibleDataSets.some((vds) => vds.name === 'attendees')).to.be.true;
+
+        // Verify that a hash tree was created for 'attendees'
+        assert.exists(parser.dataSets.attendees.hashTree);
+        assert.equal(parser.dataSets.attendees.hashTree.numLeaves, 8);
+
+        // Verify callback was called with the metadata update (appears twice - processed once for visible dataset changes, once in main loop)
+        assert.calledOnceWithExactly(callback, {updateType: LocusInfoUpdateType.OBJECTS_UPDATED,
+          updatedObjects: [
+            {
+              htMeta: {
+                elementId: {type: 'metadata', id: 5, version: 51},
+                dataSetNames: ['self'],
+              },
+              data: {
+                visibleDataSets: [
+                  {
+                    name: 'main',
+                    url: 'https://locus-a.wbx2.com/locus/api/v1/loci/97d64a5f/datasets/main',
+                  },
+                  {
+                    name: 'self',
+                    url: 'https://locus-a.wbx2.com/locus/api/v1/loci/97d64a5f/participant/713e9f99/datasets/self',
+                  },
+                  {
+                    name: 'atd-unmuted',
+                    url: 'https://locus-a.wbx2.com/locus/api/v1/loci/97d64a5f/datasets/atd-unmuted',
+                  },
+                  {
+                    name: 'attendees',
+                    url: 'https://locus-a.wbx2.com/locus/api/v1/loci/97d64a5f/datasets/attendees',
+                  },
+                ],
+              },
+            },
+            {
+              htMeta: {
+                elementId: {type: 'metadata', id: 5, version: 51},
+                dataSetNames: ['self'],
+              },
+              data: {
+                visibleDataSets: [
+                  {
+                    name: 'main',
+                    url: 'https://locus-a.wbx2.com/locus/api/v1/loci/97d64a5f/datasets/main',
+                  },
+                  {
+                    name: 'self',
+                    url: 'https://locus-a.wbx2.com/locus/api/v1/loci/97d64a5f/participant/713e9f99/datasets/self',
+                  },
+                  {
+                    name: 'atd-unmuted',
+                    url: 'https://locus-a.wbx2.com/locus/api/v1/loci/97d64a5f/datasets/atd-unmuted',
+                  },
+                  {
+                    name: 'attendees',
+                    url: 'https://locus-a.wbx2.com/locus/api/v1/loci/97d64a5f/datasets/attendees',
+                  },
+                ],
+              },
+            },
+          ],
+        });
+      });
+
+      it('handles addition of visible data set (one that requires async initialization)', async () => {
+        // Create a parser with visible datasets
+        const parser = createHashTreeParser();
+
+        // Stub updateItems on self hash tree to return true
+        sinon.stub(parser.dataSets.self.hashTree, 'updateItems').returns([true]);
+
+        // Send a message with Metadata object that has a new visibleDataSets list (adding 'new-dataset')
+        // but WITHOUT providing info about the new dataset in dataSets array
+        const message = {
+          dataSets: [createDataSet('self', 1, 2100)],
+          visibleDataSetsUrl,
+          locusUrl,
+          locusStateElements: [
+            {
+              htMeta: {
+                elementId: {
+                  type: 'metadata' as const,
+                  id: 5,
+                  version: 51,
+                },
                 dataSetNames: ['self'],
               },
               data: {
@@ -2062,6 +2462,98 @@ describe('HashTreeParser', () => {
         await checkAsyncDatasetInitialization(parser, newDataSet);
       });
 
+      it('initializes new visible data sets in priority order', async () => {
+        // Create a parser that only has "self" as visible (no "main")
+        const initialLocusWithoutMain = {
+          dataSets: [createDataSet('self', 1, 2000)],
+          locus: {
+            ...exampleInitialLocus.locus,
+          },
+        };
+        const metadataWithoutMain = {
+          ...exampleMetadata,
+          visibleDataSets: [
+            {
+              name: 'self',
+              url: 'https://locus-a.wbx2.com/locus/api/v1/loci/97d64a5f/participant/713e9f99/datasets/self',
+            },
+          ],
+        };
+        const parser = createHashTreeParser(initialLocusWithoutMain, metadataWithoutMain);
+
+        // Verify "main" is not visible initially
+        expect(parser.visibleDataSets.some((vds) => vds.name === 'main')).to.be.false;
+
+        // Stub updateItems on self hash tree to return true
+        sinon.stub(parser.dataSets.self.hashTree, 'updateItems').returns([true]);
+
+        // Send a message that adds "main" and "atd-active" as new visible datasets.
+        // Neither has info in dataSets, so both require async initialization.
+        const newMainDataSet = createDataSet('main', 16, 6000);
+        const newAtdActiveDataSet = createDataSet('atd-active', 4, 7000);
+
+        const message = {
+          dataSets: [createDataSet('self', 1, 2100)],
+          visibleDataSetsUrl,
+          locusUrl,
+          locusStateElements: [
+            {
+              htMeta: {
+                elementId: {
+                  type: 'metadata' as const,
+                  id: 5,
+                  version: 51,
+                },
+                dataSetNames: ['self'],
+              },
+              data: {
+                visibleDataSets: [
+                  {
+                    name: 'self',
+                    url: 'https://locus-a.wbx2.com/locus/api/v1/loci/97d64a5f/participant/713e9f99/datasets/self',
+                  },
+                  // listed in non-priority order: atd-active before main
+                  {name: 'atd-active', url: newAtdActiveDataSet.url},
+                  {name: 'main', url: newMainDataSet.url},
+                ],
+              },
+            },
+          ],
+        };
+
+        // Mock getAllVisibleDataSetsFromLocus to return both new datasets (in non-priority order)
+        mockGetAllDataSetsMetadata(webexRequest, visibleDataSetsUrl, [
+          newAtdActiveDataSet,
+          newMainDataSet,
+        ]);
+        mockSyncRequest(webexRequest, newMainDataSet.url);
+        mockSyncRequest(webexRequest, newAtdActiveDataSet.url);
+
+        parser.handleMessage(message, 'add main and atd-active datasets');
+
+        // Wait for the async initialization (queueMicrotask) to complete
+        await clock.tickAsync(0);
+
+        // Verify both datasets are initialized
+        expect(parser.dataSets.main?.hashTree).to.exist;
+        expect(parser.dataSets['atd-active']?.hashTree).to.exist;
+
+        // Verify sync requests were sent in priority order: "main" before "atd-active",
+        // even though atd-active was listed first in both the message and the Locus response
+        const syncCalls = webexRequest
+          .getCalls()
+          .filter(
+            (call) =>
+              call.args[0]?.method === 'POST' &&
+              call.args[0]?.uri?.endsWith('/sync') &&
+              (call.args[0]?.uri?.includes('/main/') || call.args[0]?.uri?.includes('/atd-active/'))
+          );
+
+        expect(syncCalls).to.have.lengthOf(2);
+        expect(syncCalls[0].args[0].uri).to.equal(`${newMainDataSet.url}/sync`);
+        expect(syncCalls[1].args[0].uri).to.equal(`${newAtdActiveDataSet.url}/sync`);
+      });
+
       it('emits MEETING_ENDED if async init of a new visible dataset fails with 404', async () => {
         const parser = createHashTreeParser();
 
@@ -2128,9 +2620,7 @@ describe('HashTreeParser', () => {
         await clock.tickAsync(0);
 
         // Verify callback was called with MEETING_ENDED
-        assert.calledOnceWithExactly(callback, LocusInfoUpdateType.MEETING_ENDED, {
-          updatedObjects: undefined,
-        });
+        assert.calledOnceWithExactly(callback, {updateType: LocusInfoUpdateType.MEETING_ENDED});
       });
 
       it('handles removal of visible data set', async () => {
@@ -2193,7 +2683,7 @@ describe('HashTreeParser', () => {
         assert.isUndefined(parser.dataSets['atd-unmuted'].timer);
 
         // Verify callback was called with the metadata update and the removed objects (metadata appears twice - processed once for dataset changes, once in main loop)
-        assert.calledOnceWithExactly(callback, LocusInfoUpdateType.OBJECTS_UPDATED, {
+        assert.calledOnceWithExactly(callback, {updateType: LocusInfoUpdateType.OBJECTS_UPDATED,
           updatedObjects: [
             {
               htMeta: {
@@ -2290,6 +2780,151 @@ describe('HashTreeParser', () => {
         // Verify callback was NOT called (no updates for non-visible datasets)
         assert.notCalled(callback);
       });
+
+      it('reports update for object that moves from removed visible dataset to new visible dataset even if version is unchanged', async () => {
+        // The purpose of this test is to verify that when an object
+        // moves from one visible dataset to another without version change,
+        // the parser still reports it as an update.
+        // Locus has some additional signalling for this - the "view" property in htMeta.elementId.
+        // When a view changes, the contents of the object may change even if version doesn't.
+        // HashTreeParser doesn't use the "view" property, because it doesn't need to -
+        // the same functionality is achieved thanks to the fact that a new visible data set means
+        // a new hash tree is created, so HashTreeParser still detects the change as new
+        // object is added to the new hash tree.
+
+        // Setup: parser with visible datasets "self" and "unjoined"
+        const unjoinedDataSet = createDataSet('unjoined', 4, 3000);
+        const selfDataSet = createDataSet('self', 1, 2000);
+
+        // start with Locus that has "info" in both "unjoined" and "main" datasets,
+        // but only "unjoined" is visible.
+        const initialLocus = {
+          dataSets: [selfDataSet, unjoinedDataSet],
+          locus: {
+            url: 'https://locus-a.wbx2.com/locus/api/v1/loci/97d64a5f',
+            links: {resources: {visibleDataSets: {url: visibleDataSetsUrl}}},
+            // info object in "unjoined" dataset with version 500
+            info: {
+              htMeta: {
+                elementId: {
+                  type: 'info',
+                  id: 42,
+                  version: 500,
+                  view: ['unjoined'], // not used by our code, but here for completeness - that's what real Locus would send
+                },
+                dataSetNames: ['main', 'unjoined'],
+              },
+              someField: 'some-initial-value',
+            },
+            self: {
+              htMeta: {
+                elementId: {
+                  type: 'self',
+                  id: 4,
+                  version: 100,
+                },
+                dataSetNames: ['self'],
+              },
+            },
+          },
+        };
+
+        const metadata = {
+          htMeta: {
+            elementId: {
+              type: 'metadata',
+              id: 5,
+              version: 50,
+            },
+            dataSetNames: ['self'],
+          },
+          visibleDataSets: [
+            {name: 'self', url: selfDataSet.url},
+            {name: 'unjoined', url: unjoinedDataSet.url},
+          ],
+        };
+
+        const parser = createHashTreeParser(initialLocus, metadata);
+
+        // Verify initial state: unjoined is visible and has the info object
+        expect(parser.visibleDataSets.some((vds) => vds.name === 'unjoined')).to.be.true;
+        assert.exists(parser.dataSets.unjoined.hashTree);
+        assert.equal(parser.dataSets.unjoined.hashTree?.getItemVersion(42, 'info'), 500);
+
+        // Stub updateItems on self hash tree to return true for metadata update
+        sinon.stub(parser.dataSets.self.hashTree, 'updateItems').returns([true]);
+
+        // Now send a message that:
+        // 1. Changes visible datasets: removes "unjoined", adds "main"
+        // 2. Contains the same info object (same id=42, same version=500) but we see the view from "main" dataset
+        const mainDataSet = createDataSet('main', 16, 1000);
+
+        const message = {
+          dataSets: [selfDataSet, mainDataSet],
+          visibleDataSetsUrl,
+          locusUrl,
+          locusStateElements: [
+            {
+              htMeta: {
+                elementId: {
+                  type: 'metadata' as const,
+                  id: 5,
+                  version: 51,
+                },
+                dataSetNames: ['self'],
+              },
+              data: {
+                visibleDataSets: [
+                  {name: 'self', url: selfDataSet.url},
+                  {name: 'main', url: mainDataSet.url},
+                  // "unjoined" is no longer here
+                ],
+              },
+            },
+            {
+              htMeta: {
+                elementId: {
+                  type: 'info' as const,
+                  id: 42,
+                  version: 500, // same version as before
+                  view: ['main'], // now points to "main" instead of "unjoined"
+                },
+                dataSetNames: ['main', 'unjoined'], // still in both datasets, but only "main" is visible now
+              },
+              data: {someNewField: 'some-value'},
+            },
+          ],
+        };
+
+        parser.handleMessage(message, 'visible dataset swap with same-version object');
+
+        // Verify "unjoined" is no longer visible and "main" is now visible
+        expect(parser.visibleDataSets.some((vds) => vds.name === 'unjoined')).to.be.false;
+        expect(parser.visibleDataSets.some((vds) => vds.name === 'main')).to.be.true;
+
+        // Verify the info object is now in the "main" hash tree
+        assert.exists(parser.dataSets.main.hashTree);
+        assert.equal(parser.dataSets.main.hashTree?.getItemVersion(42, 'info'), 500);
+
+        // The key assertion: callback should be called with the info object update even though
+        // its version hasn't changed - because visible datasets changed (moved from unjoined to main)
+        assert.calledOnce(callback);
+        const callbackArgs = callback.firstCall.args[0];
+        assert.equal(callbackArgs.updateType, LocusInfoUpdateType.OBJECTS_UPDATED);
+
+        // Should contain the info object update (with data)
+        const infoUpdate = callbackArgs.updatedObjects.find(
+          (obj) => obj.htMeta.elementId.type === 'info' && obj.htMeta.elementId.id === 42
+        );
+        assert.exists(infoUpdate);
+        assert.deepEqual(infoUpdate.htMeta.elementId, {
+          type: 'info',
+          id: 42,
+          version: 500,
+          view: ['main'],
+        });
+        assert.deepEqual(infoUpdate.data, {someNewField: 'some-value'});
+      });
     });
 
     describe('heartbeat watchdog', () => {
@@ -2666,56 +3301,126 @@ describe('HashTreeParser', () => {
         // At 5500ms, 'main' watchdog fires and performSync runs immediately
         await clock.tickAsync(1);
 
-        // main sync should have triggered immediately (GET hashtree + POST sync)
+        // main sync should have triggered immediately (GET hashtree + POST sync)
+        assert.calledWith(
+          webexRequest,
+          sinon.match({
+            method: 'GET',
+            uri: `${parser.dataSets.main.url}/hashtree`,
+          })
+        );
+
+        webexRequest.resetHistory();
+
+        // At 7000ms, 'self' watchdog fires and performSync runs immediately
+        await clock.tickAsync(1500);
+
+        // self sync should have also triggered (POST sync only, leafCount === 1)
+        assert.calledWith(
+          webexRequest,
+          sinon.match({
+            method: 'POST',
+            uri: `${parser.dataSets.self.url}/sync`,
+          })
+        );
+      });
+
+      it('does not set watchdog for data sets without a hash tree', async () => {
+        const parser = createHashTreeParser();
+        const heartbeatIntervalMs = 5000;
+
+        // 'atd-active' is in the initial locus but is not visible (no hash tree)
+        // Send heartbeat mentioning a non-visible dataset
+        const heartbeatMessage = {
+          dataSets: [
+            {
+              ...createDataSet('main', 16, 1100),
+              root: parser.dataSets.main.hashTree.getRootHash(),
+            },
+            createDataSet('atd-active', 16, 4000),
+          ],
+          visibleDataSetsUrl,
+          locusUrl,
+          heartbeatIntervalMs,
+        };
+
+        parser.handleMessage(heartbeatMessage, 'heartbeat with non-visible dataset');
+
+        // Watchdog set for main (visible) but not for atd-active (no hash tree)
+        expect(parser.dataSets.main.heartbeatWatchdogTimer).to.not.be.undefined;
+        expect(parser.dataSets['atd-active']?.heartbeatWatchdogTimer).to.be.undefined;
+      });
+
+      it('restarts the watchdog timer after it fires so that future missed heartbeats still trigger syncs', async () => {
+        const parser = createHashTreeParser();
+        const heartbeatIntervalMs = 5000;
+
+        // Send initial heartbeat for 'main'
+        const heartbeatMessage = {
+          dataSets: [
+            {
+              ...createDataSet('main', 16, 1100),
+              root: parser.dataSets.main.hashTree.getRootHash(),
+            },
+          ],
+          visibleDataSetsUrl,
+          locusUrl,
+          heartbeatIntervalMs,
+        };
+
+        parser.handleMessage(heartbeatMessage, 'initial heartbeat');
+        expect(parser.dataSets.main.heartbeatWatchdogTimer).to.not.be.undefined;
+
+        // Mock responses for performSync - return null (204/empty body)
+        const mainDataSetUrl = parser.dataSets.main.url;
+        mockGetHashesFromLocusResponse(
+          mainDataSetUrl,
+          new Array(16).fill('00000000000000000000000000000000'),
+          createDataSet('main', 16, 1101)
+        );
+        mockSendSyncRequestResponse(mainDataSetUrl, null);
+
+        // Advance time past heartbeatIntervalMs to fire the watchdog
+        await clock.tickAsync(heartbeatIntervalMs);
+
+        // Verify sync was triggered
         assert.calledWith(
           webexRequest,
           sinon.match({
             method: 'GET',
-            uri: `${parser.dataSets.main.url}/hashtree`,
+            uri: `${mainDataSetUrl}/hashtree`,
           })
         );
 
+        // The watchdog timer should have been restarted after firing
+        expect(parser.dataSets.main.heartbeatWatchdogTimer).to.not.be.undefined;
+
+        // Reset call history and set up new mock responses for the second sync
         webexRequest.resetHistory();
+        mockGetHashesFromLocusResponse(
+          mainDataSetUrl,
+          new Array(16).fill('00000000000000000000000000000000'),
+          createDataSet('main', 16, 1102)
+        );
+        mockSendSyncRequestResponse(mainDataSetUrl, null);
 
-        // At 7000ms, 'self' watchdog fires and performSync runs immediately
-        await clock.tickAsync(1500);
+        // Advance time again to fire the watchdog a second time
+        await clock.tickAsync(heartbeatIntervalMs);
 
-        // self sync should have also triggered (POST sync only, leafCount === 1)
+        // Verify a second sync was triggered
         assert.calledWith(
           webexRequest,
           sinon.match({
-            method: 'POST',
-            uri: `${parser.dataSets.self.url}/sync`,
+            method: 'GET',
+            uri: `${mainDataSetUrl}/hashtree`,
           })
         );
-      });
-
-      it('does not set watchdog for data sets without a hash tree', async () => {
-        const parser = createHashTreeParser();
-        const heartbeatIntervalMs = 5000;
-
-        // 'atd-active' is in the initial locus but is not visible (no hash tree)
-        // Send heartbeat mentioning a non-visible dataset
-        const heartbeatMessage = {
-          dataSets: [
-            {
-              ...createDataSet('main', 16, 1100),
-              root: parser.dataSets.main.hashTree.getRootHash(),
-            },
-            createDataSet('atd-active', 16, 4000),
-          ],
-          visibleDataSetsUrl,
-          locusUrl,
-          heartbeatIntervalMs,
-        };
 
-        parser.handleMessage(heartbeatMessage, 'heartbeat with non-visible dataset');
-
-        // Watchdog set for main (visible) but not for atd-active (no hash tree)
+        // And the watchdog should still be running
         expect(parser.dataSets.main.heartbeatWatchdogTimer).to.not.be.undefined;
-        expect(parser.dataSets['atd-active']?.heartbeatWatchdogTimer).to.be.undefined;
       });
     });
+
   });
 
   describe('#callLocusInfoUpdateCallback filtering', () => {
@@ -2812,7 +3517,7 @@ describe('HashTreeParser', () => {
       parser.handleMessage(updateMessage, 'update with newer version');
 
       // Callback should be called with the update
-      assert.calledOnceWithExactly(callback, LocusInfoUpdateType.OBJECTS_UPDATED, {
+      assert.calledOnceWithExactly(callback, {updateType: LocusInfoUpdateType.OBJECTS_UPDATED,
         updatedObjects: [
           {
             htMeta: {
@@ -2883,7 +3588,7 @@ describe('HashTreeParser', () => {
       parser.handleMessage(removalMessage, 'removal of non-existent object');
 
       // Callback should be called with the removal
-      assert.calledOnceWithExactly(callback, LocusInfoUpdateType.OBJECTS_UPDATED, {
+      assert.calledOnceWithExactly(callback, {updateType: LocusInfoUpdateType.OBJECTS_UPDATED,
         updatedObjects: [
           {
             htMeta: {
@@ -3018,7 +3723,7 @@ describe('HashTreeParser', () => {
       parser.handleMessage(mixedMessage, 'mixed updates');
 
       // Callback should be called with only the valid updates (participant 1 v110 and participant 3 v10)
-      assert.calledOnceWithExactly(callback, LocusInfoUpdateType.OBJECTS_UPDATED, {
+      assert.calledOnceWithExactly(callback, {updateType: LocusInfoUpdateType.OBJECTS_UPDATED,
         updatedObjects: [
           {
             htMeta: {
@@ -3196,9 +3901,7 @@ describe('HashTreeParser', () => {
       parser.handleMessage(sentinelMessage as any, 'sentinel message');
 
       // Callback should be called with MEETING_ENDED
-      assert.calledOnceWithExactly(callback, LocusInfoUpdateType.MEETING_ENDED, {
-        updatedObjects: undefined,
-      });
+      assert.calledOnceWithExactly(callback, {updateType: LocusInfoUpdateType.MEETING_ENDED});
     });
   });
 
@@ -3404,7 +4107,7 @@ describe('HashTreeParser', () => {
     });
   });
 
-  describe('#resume', () => {
+  describe('#resumeFromMessage', () => {
     const createResumeMessage = (visibleDataSets?, dataSets?) => ({
       locusUrl,
       visibleDataSetsUrl,
@@ -3431,7 +4134,7 @@ describe('HashTreeParser', () => {
 
       expect(parser.state).to.equal('stopped');
 
-      parser.resume(createResumeMessage());
+      parser.resumeFromMessage(createResumeMessage());
 
       expect(parser.state).to.equal('active');
     });
@@ -3440,7 +4143,7 @@ describe('HashTreeParser', () => {
       const parser = createHashTreeParser();
       parser.stop();
 
-      parser.resume({
+      parser.resumeFromMessage({
         locusUrl,
         visibleDataSetsUrl,
         dataSets: [createDataSet('main', 16, 2000)],
@@ -3459,7 +4162,7 @@ describe('HashTreeParser', () => {
         createDataSet('self', 2, 6000),
       ];
 
-      parser.resume(createResumeMessage(undefined, newDataSets));
+      parser.resumeFromMessage(createResumeMessage(undefined, newDataSets));
 
       expect(Object.keys(parser.dataSets)).to.have.lengthOf(2);
       expect(parser.dataSets.main.leafCount).to.equal(8);
@@ -3481,7 +4184,7 @@ describe('HashTreeParser', () => {
         {name: 'self', url: 'https://locus-a.wbx2.com/locus/api/v1/loci/97d64a5f/participant/713e9f99/datasets/self'},
       ];
 
-      parser.resume(createResumeMessage(visibleDataSets, dataSets));
+      parser.resumeFromMessage(createResumeMessage(visibleDataSets, dataSets));
 
       expect(parser.dataSets.main.hashTree).to.be.instanceOf(HashTree);
       expect(parser.dataSets.self.hashTree).to.be.instanceOf(HashTree);
@@ -3495,7 +4198,7 @@ describe('HashTreeParser', () => {
       const handleMessageStub = sinon.stub(parser, 'handleMessage');
 
       const message = createResumeMessage();
-      parser.resume(message);
+      parser.resumeFromMessage(message);
 
       assert.calledOnceWithExactly(handleMessageStub, message, 'on resume');
     });
@@ -3515,7 +4218,7 @@ describe('HashTreeParser', () => {
         {name: 'atd-unmuted', url: 'https://locus-a.wbx2.com/locus/api/v1/loci/97d64a5f/datasets/atd-unmuted'},
       ];
 
-      parser.resume(createResumeMessage(visibleDataSets, dataSets));
+      parser.resumeFromMessage(createResumeMessage(visibleDataSets, dataSets));
 
       expect(parser.visibleDataSets.some((vds) => vds.name === 'atd-unmuted')).to.be.false;
       expect(parser.visibleDataSets.some((vds) => vds.name === 'main')).to.be.true;
@@ -3523,6 +4226,67 @@ describe('HashTreeParser', () => {
     });
   });
 
+  describe('#resumeFromApiResponse', () => {
+    const exampleLocus = {
+      participants: [],
+    } as any;
+
+    it('should set state to active', async () => {
+      const parser = createHashTreeParser();
+      parser.stop();
+
+      expect(parser.state).to.equal('stopped');
+
+      sinon.stub(parser, 'initializeFromGetLociResponse').resolves();
+
+      await parser.resumeFromApiResponse(exampleLocus);
+
+      expect(parser.state).to.equal('active');
+    });
+
+    it('should reset dataSets to empty', async () => {
+      const parser = createHashTreeParser();
+
+      expect(Object.keys(parser.dataSets).length).to.be.greaterThan(0);
+
+      parser.stop();
+
+      sinon.stub(parser, 'initializeFromGetLociResponse').resolves();
+
+      await parser.resumeFromApiResponse(exampleLocus);
+
+      expect(parser.dataSets).to.deep.equal({});
+    });
+
+    it('should call initializeFromGetLociResponse with the provided locus', async () => {
+      const parser = createHashTreeParser();
+      parser.stop();
+
+      const initStub = sinon.stub(parser, 'initializeFromGetLociResponse').resolves();
+
+      await parser.resumeFromApiResponse(exampleLocus);
+
+      assert.calledOnceWithExactly(initStub, exampleLocus);
+    });
+
+    it('should propagate errors from initializeFromGetLociResponse', async () => {
+      const parser = createHashTreeParser();
+      parser.stop();
+
+      const error = new Error('initialization failed');
+      const initStub = sinon.stub(parser, 'initializeFromGetLociResponse').rejects(error);
+
+      let caughtError: Error | undefined;
+      try {
+        await parser.resumeFromApiResponse(exampleLocus);
+      } catch (e) {
+        caughtError = e;
+      }
+
+      expect(caughtError).to.equal(error);
+    });
+  });
+
   describe('#handleLocusUpdate when stopped', () => {
     it('should return early without processing when parser is stopped', () => {
       const parser = createHashTreeParser();
@@ -3557,4 +4321,343 @@ describe('HashTreeParser', () => {
       assert.notCalled(callback);
     });
   });
+
+  describe('#syncAllDatasets', () => {
+    it('should sync all datasets that have hash trees in priority order', async () => {
+      const parser = createHashTreeParser();
+
+      // parser starts with main (leafCount=16) and self (leafCount=1) as visible datasets with hash trees
+      // atd-unmuted has no hash tree (not visible)
+      expect(parser.dataSets.main.hashTree).to.be.instanceOf(HashTree);
+      expect(parser.dataSets.self.hashTree).to.be.instanceOf(HashTree);
+
+      const mainUrl = parser.dataSets.main.url;
+      const selfUrl = parser.dataSets.self.url;
+
+      // Mock GET hashtree for main (leafCount > 1, so it does GET first)
+      mockGetHashesFromLocusResponse(
+        mainUrl,
+        new Array(16).fill(EMPTY_HASH),
+        createDataSet('main', 16, 1100)
+      );
+
+      // Mock POST sync for main - return matching root hash so no further sync needed
+      const mainSyncDataSet = createDataSet('main', 16, 1100);
+      mainSyncDataSet.root = parser.dataSets.main.hashTree.getRootHash();
+      mockSendSyncRequestResponse(mainUrl, {
+        dataSets: [mainSyncDataSet],
+        visibleDataSetsUrl,
+        locusUrl,
+        locusStateElements: [],
+      });
+
+      // Mock POST sync for self (leafCount=1, skips GET hashtree)
+      const selfSyncDataSet = createDataSet('self', 1, 2100);
+      selfSyncDataSet.root = parser.dataSets.self.hashTree.getRootHash();
+      mockSendSyncRequestResponse(selfUrl, {
+        dataSets: [selfSyncDataSet],
+        visibleDataSetsUrl,
+        locusUrl,
+        locusStateElements: [],
+      });
+
+      await parser.syncAllDatasets();
+
+      // Verify GET hashtree was called for main only (not self, because leafCount=1)
+      assert.calledWith(webexRequest, sinon.match({method: 'GET', uri: `${mainUrl}/hashtree`}));
+      assert.neverCalledWith(webexRequest, sinon.match({method: 'GET', uri: `${selfUrl}/hashtree`}));
+
+      // Verify POST sync was called for both
+      assert.calledWith(webexRequest, sinon.match({method: 'POST', uri: `${mainUrl}/sync`}));
+      assert.calledWith(webexRequest, sinon.match({method: 'POST', uri: `${selfUrl}/sync`}));
+
+      // Verify main was synced before self (priority order)
+      const mainSyncCallIndex = webexRequest.args.findIndex(
+        (args) => args[0]?.method === 'GET' && args[0]?.uri === `${mainUrl}/hashtree`
+      );
+      const selfSyncCallIndex = webexRequest.args.findIndex(
+        (args) => args[0]?.method === 'POST' && args[0]?.uri === `${selfUrl}/sync`
+      );
+      expect(mainSyncCallIndex).to.be.lessThan(selfSyncCallIndex);
+
+      // Verify isSyncAllInProgress is reset
+      expect(parser.isSyncAllInProgress).to.be.false;
+    });
+
+    it('should return immediately when state is stopped', async () => {
+      const parser = createHashTreeParser();
+      parser.stop();
+
+      await parser.syncAllDatasets();
+
+      // No sync requests should have been made (only the initial sync from constructor)
+      // Reset history to clear constructor calls then verify
+      const callCountBefore = webexRequest.callCount;
+      await parser.syncAllDatasets();
+      assert.equal(webexRequest.callCount, callCountBefore);
+    });
+
+    it('should guard against concurrent calls', async () => {
+      const parser = createHashTreeParser();
+
+      const mainUrl = parser.dataSets.main.url;
+      const selfUrl = parser.dataSets.self.url;
+
+      // Use a deferred promise for the main sync to control timing
+      let resolveMainSync;
+      webexRequest
+        .withArgs(sinon.match({method: 'GET', uri: `${mainUrl}/hashtree`}))
+        .returns(new Promise((resolve) => { resolveMainSync = resolve; }));
+
+      mockSendSyncRequestResponse(mainUrl, {
+        dataSets: [createDataSet('main', 16, 1100)],
+        visibleDataSetsUrl,
+        locusUrl,
+        locusStateElements: [],
+      });
+
+      mockSendSyncRequestResponse(selfUrl, {
+        dataSets: [createDataSet('self', 1, 2100)],
+        visibleDataSetsUrl,
+        locusUrl,
+        locusStateElements: [],
+      });
+
+      // Start first call
+      const promise1 = parser.syncAllDatasets();
+      // Start second call while first is in progress
+      const promise2 = parser.syncAllDatasets();
+
+      // Resolve the pending request
+      resolveMainSync({
+        body: {
+          hashes: new Array(16).fill(EMPTY_HASH),
+          dataSet: createDataSet('main', 16, 1100),
+        },
+      });
+
+      await promise1;
+      await promise2;
+
+      // GET hashtree for main should only be called once (second syncAllDatasets returned immediately)
+      const getHashtreeCalls = webexRequest.args.filter(
+        (args) => args[0]?.method === 'GET' && args[0]?.uri === `${mainUrl}/hashtree`
+      );
+      expect(getHashtreeCalls).to.have.lengthOf(1);
+    });
+
+    it('should skip datasets that do not have a hash tree', async () => {
+      // Create parser with metadata that only has main and self as visible (not atd-unmuted)
+      const metadataWithoutAtd = {
+        ...exampleMetadata,
+        visibleDataSets: exampleMetadata.visibleDataSets.filter((ds) => ds.name !== 'atd-unmuted'),
+      };
+      const parser = createHashTreeParser(exampleInitialLocus, metadataWithoutAtd);
+
+      // atd-unmuted is in dataSets but has no hashTree (not visible)
+      expect(parser.dataSets['atd-unmuted']).to.exist;
+      expect(parser.dataSets['atd-unmuted'].hashTree).to.be.undefined;
+
+      const atdUrl = parser.dataSets['atd-unmuted'].url;
+      const mainUrl = parser.dataSets.main.url;
+      const selfUrl = parser.dataSets.self.url;
+
+      mockGetHashesFromLocusResponse(
+        mainUrl,
+        new Array(16).fill(EMPTY_HASH),
+        createDataSet('main', 16, 1100)
+      );
+
+      const mainSyncDs = createDataSet('main', 16, 1100);
+      mainSyncDs.root = parser.dataSets.main.hashTree.getRootHash();
+      mockSendSyncRequestResponse(mainUrl, {
+        dataSets: [mainSyncDs],
+        visibleDataSetsUrl,
+        locusUrl,
+        locusStateElements: [],
+      });
+
+      const selfSyncDs = createDataSet('self', 1, 2100);
+      selfSyncDs.root = parser.dataSets.self.hashTree.getRootHash();
+      mockSendSyncRequestResponse(selfUrl, {
+        dataSets: [selfSyncDs],
+        visibleDataSetsUrl,
+        locusUrl,
+        locusStateElements: [],
+      });
+
+      await parser.syncAllDatasets();
+
+      // No requests should have been made for atd-unmuted
+      assert.neverCalledWith(webexRequest, sinon.match({uri: sinon.match(atdUrl)}));
+    });
+  });
+
+  describe('#handleMessage sync queue', () => {
+    it('should deduplicate: not sync the same dataset twice when enqueued multiple times', async () => {
+      const parser = createHashTreeParser();
+
+      const mainUrl = parser.dataSets.main.url;
+
+      // Setup mocks before triggering syncs
+      mockGetHashesFromLocusResponse(
+        mainUrl,
+        new Array(16).fill(EMPTY_HASH),
+        createDataSet('main', 16, 1101)
+      );
+
+      const mainSyncDs = createDataSet('main', 16, 1101);
+      mainSyncDs.root = parser.dataSets.main.hashTree.getRootHash();
+      mockSendSyncRequestResponse(mainUrl, {
+        dataSets: [mainSyncDs],
+        visibleDataSetsUrl,
+        locusUrl,
+        locusStateElements: [],
+      });
+
+      // Send two heartbeat messages (no locusStateElements) with different root hashes for main
+      parser.handleMessage(createHeartbeatMessage('main', 16, 1100, 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa1'), 'first');
+      parser.handleMessage(createHeartbeatMessage('main', 16, 1101, 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa2'), 'second');
+
+      // The second call resets the timer. After 1000ms, only one sync fires.
+      await clock.tickAsync(1000);
+
+      // Only one GET hashtree call should have been made for main
+      const getHashtreeCalls = webexRequest.args.filter(
+        (args) => args[0]?.method === 'GET' && args[0]?.uri === `${mainUrl}/hashtree`
+      );
+      expect(getHashtreeCalls).to.have.lengthOf(1);
+    });
+
+    it('should stop processing the sync queue when parser is stopped mid-queue', async () => {
+      const parser = createHashTreeParser();
+
+      const mainUrl = parser.dataSets.main.url;
+      const selfUrl = parser.dataSets.self.url;
+
+      // Mock main GET hashtree with a deferred promise so we can control when it resolves
+      let resolveMainHashtree;
+      webexRequest
+        .withArgs(sinon.match({method: 'GET', uri: `${mainUrl}/hashtree`}))
+        .callsFake(() => new Promise((resolve) => { resolveMainHashtree = resolve; }));
+
+      // Send a heartbeat message that triggers sync timers for both main and self
+      parser.handleMessage(
+        createHeartbeatMessage('main', 16, 1100, 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa1'),
+        'trigger main sync'
+      );
+      parser.handleMessage(
+        createHeartbeatMessage('self', 1, 2100, 'bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb1'),
+        'trigger self sync'
+      );
+
+      // Fire the timers - main sync starts (calls GET hashtree, which blocks)
+      await clock.tickAsync(1000);
+
+      // Stop the parser while main sync is in progress
+      parser.stop();
+
+      // Resolve the pending main GET request
+      resolveMainHashtree({
+        body: {
+          hashes: new Array(16).fill(EMPTY_HASH),
+          dataSet: createDataSet('main', 16, 1100),
+        },
+      });
+
+      await clock.tickAsync(0);
+
+      // Self sync should NOT have been triggered because parser was stopped
+      assert.neverCalledWith(webexRequest, sinon.match({method: 'POST', uri: `${selfUrl}/sync`}));
+      assert.neverCalledWith(webexRequest, sinon.match({method: 'GET', uri: `${selfUrl}/hashtree`}));
+    });
+  });
+
+  describe('#stop sync queue', () => {
+    it('should clear the syncQueue when stopped so remaining queued items are not processed', async () => {
+      const parser = createHashTreeParser();
+
+      const mainUrl = parser.dataSets.main.url;
+      const selfUrl = parser.dataSets.self.url;
+
+      // Mock main GET hashtree with a deferred promise so we can control when it resolves
+      let resolveMainHashtree;
+      webexRequest
+        .withArgs(sinon.match({method: 'GET', uri: `${mainUrl}/hashtree`}))
+        .callsFake(() => new Promise((resolve) => { resolveMainHashtree = resolve; }));
+
+      // Enqueue syncs for both main and self by sending heartbeat messages
+      parser.handleMessage(
+        createHeartbeatMessage('main', 16, 1100, 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa1'),
+        'trigger main sync'
+      );
+      parser.handleMessage(
+        createHeartbeatMessage('self', 1, 2100, 'bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb1'),
+        'trigger self sync'
+      );
+
+      // Fire the timers - main sync starts and blocks on GET hashtree
+      await clock.tickAsync(1000);
+
+      // Verify that self is still in the queue (main is being processed, self is waiting)
+      // Now stop the parser - this should clear the syncQueue
+      parser.stop();
+
+      // Resolve the pending main GET request so the in-flight sync can finish
+      resolveMainHashtree({
+        body: {
+          hashes: new Array(16).fill(EMPTY_HASH),
+          dataSet: createDataSet('main', 16, 1100),
+        },
+      });
+
+      await clock.tickAsync(0);
+
+      // Self should never have been synced because stop() cleared the queue
+      const selfGetCalls = webexRequest.args.filter(
+        (args) => args[0]?.method === 'GET' && args[0]?.uri === `${selfUrl}/hashtree`
+      );
+      expect(selfGetCalls).to.have.lengthOf(0);
+    });
+  });
+
+  describe('#cleanUp', () => {
+    it('should stop the parser, clear all timers and clear all dataSets', () => {
+      const parser = createHashTreeParser();
+
+      // Send a message to set up sync timers via runSyncAlgorithm
+      const message = {
+        dataSets: [
+          {
+            ...createDataSet('main', 16, 1100),
+            root: 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa1',
+          },
+        ],
+        visibleDataSetsUrl,
+        locusUrl,
+        heartbeatIntervalMs: 5000,
+        locusStateElements: [
+          {
+            htMeta: {
+              elementId: {type: 'locus' as const, id: 0, version: 201},
+              dataSetNames: ['main'],
+            },
+            data: {someData: 'value'},
+          },
+        ],
+      };
+
+      parser.handleMessage(message, 'setup timers');
+
+      // Verify timers were set by handleMessage
+      expect(parser.dataSets.main.timer).to.not.be.undefined;
+      expect(parser.dataSets.main.heartbeatWatchdogTimer).to.not.be.undefined;
+
+      parser.cleanUp();
+
+      expect(parser.state).to.equal('stopped');
+      expect(parser.visibleDataSets).to.deep.equal([]);
+      expect(parser.dataSets).to.deep.equal({});
+    });
+  });
 });