@webex/plugin-meetings 3.12.0-next.7 → 3.12.0-next.70

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

@@ -1,12 +1,18 @@
 import HashTreeParser, {
   LocusInfoUpdateType,
   MeetingEndedError,
+  LocusNotFoundError,
+  SyncAllBackoffType,
 } from '@webex/plugin-meetings/src/hashTree/hashTreeParser';
 import HashTree from '@webex/plugin-meetings/src/hashTree/hashTree';
 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 testUtils from '@webex/plugin-meetings/test/utils/testUtils';
+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';
 
@@ -111,6 +117,7 @@ function createDataSet(name: string, leafCount: number, version = 1) {
     name,
     idleMs: 1000,
     backoff: {maxMs: 1000, exponent: 2},
+    heartbeatIntervalMs: 5000,
   };
 }
 
@@ -151,16 +158,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 +563,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 +576,11 @@ describe('HashTreeParser', () => {
           },
           data: {info: {id: 'some-fake-locus-info'}},
         },
+      ],
+    });
+
+    assert.calledWith(callback, {updateType: LocusInfoUpdateType.OBJECTS_UPDATED,
+      updatedObjects: [
         {
           htMeta: {
             elementId: {
@@ -596,6 +611,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: [],
@@ -636,8 +712,11 @@ describe('HashTreeParser', () => {
       assert.notCalled(callback);
     });
 
-    [404, 409].forEach((errorCode) => {
-      it(`emits MeetingEndedError if getting visible datasets returns ${errorCode}`, async () => {
+    [
+      {errorCode: 404, expectedError: LocusNotFoundError},
+      {errorCode: 409, expectedError: MeetingEndedError},
+    ].forEach(({errorCode, expectedError}) => {
+      it(`throws ${expectedError.name} if getting visible datasets returns ${errorCode}`, async () => {
         const minimalInitialLocus = {
           dataSets: [],
           locus: null,
@@ -660,7 +739,6 @@ describe('HashTreeParser', () => {
           )
           .rejects(error);
 
-        // initializeFromMessage should throw MeetingEndedError
         let thrownError;
         try {
           await parser.initializeFromMessage({
@@ -672,7 +750,7 @@ describe('HashTreeParser', () => {
           thrownError = e;
         }
 
-        expect(thrownError).to.be.instanceOf(MeetingEndedError);
+        expect(thrownError).to.be.instanceOf(expectedError);
       });
     });
   });
@@ -788,7 +866,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: {
@@ -919,7 +997,7 @@ describe('HashTreeParser', () => {
         {type: 'ControlEntry', id: 10101, version: 100}
       ]);
 
-      assert.calledOnceWithExactly(callback, LocusInfoUpdateType.OBJECTS_UPDATED, {
+      assert.calledOnceWithExactly(callback, {updateType: LocusInfoUpdateType.OBJECTS_UPDATED,
         updatedObjects: [
           {
             htMeta: {
@@ -1009,7 +1087,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: {
@@ -1109,7 +1187,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:
           {
@@ -1270,7 +1348,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: {
@@ -1498,7 +1576,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: {
@@ -1563,9 +1641,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) => {
@@ -1587,9 +1663,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) => {
@@ -1685,7 +1759,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: {
@@ -1698,12 +1772,10 @@ describe('HashTreeParser', () => {
         });
       });
 
-      describe('emits MEETING_ENDED', () => {
-        [404, 409].forEach((statusCode) => {
-          it(`when /hashtree returns ${statusCode}`, async () => {
+      describe('emits MEETING_ENDED when 409/2403004 is returned', () => {
+          it('when /hashtree returns 409', async () => {
             const parser = createHashTreeParser();
 
-            // Send a message to trigger sync algorithm
             const message = {
               dataSets: [createDataSet('main', 16, 1100)],
               visibleDataSetsUrl,
@@ -1728,12 +1800,9 @@ describe('HashTreeParser', () => {
 
             const mainDataSetUrl = parser.dataSets.main.url;
 
-            // Mock getHashesFromLocus to reject with the sentinel error
-            const error: any = new Error(`Request failed with status ${statusCode}`);
-            error.statusCode = statusCode;
-            if (statusCode === 409) {
-              error.body = {errorCode: 2403004};
-            }
+            const error: any = new Error('Request failed with status 409');
+            error.statusCode = 409;
+            error.body = {errorCode: 2403004};
             webexRequest
               .withArgs(
                 sinon.match({
@@ -1743,13 +1812,120 @@ describe('HashTreeParser', () => {
               )
               .rejects(error);
 
-            // Trigger sync by advancing time
             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});
+
+            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 409', async () => {
+            const parser = createHashTreeParser();
+
+            const message = {
+              dataSets: [createDataSet('main', 16, 1100)],
+              visibleDataSetsUrl,
+              locusUrl,
+              locusStateElements: [
+                {
+                  htMeta: {
+                    elementId: {
+                      type: 'locus' as const,
+                      id: 0,
+                      version: 201,
+                    },
+                    dataSetNames: ['main'],
+                  },
+                  data: {info: {id: 'initial-update'}},
+                },
+              ],
+            };
+
+            parser.handleMessage(message, 'initial message');
+            callback.resetHistory();
+
+            const mainDataSetUrl = parser.dataSets.main.url;
+
+            mockGetHashesFromLocusResponse(
+              mainDataSetUrl,
+              new Array(16).fill('00000000000000000000000000000000'),
+              createDataSet('main', 16, 1101)
+            );
+
+            const error: any = new Error('Request failed with status 409');
+            error.statusCode = 409;
+            error.body = {errorCode: 2403004};
+            webexRequest
+              .withArgs(
+                sinon.match({
+                  method: 'POST',
+                  uri: `${mainDataSetUrl}/sync`,
+                })
+              )
+              .rejects(error);
+
+            await clock.tickAsync(1000);
+
+            assert.calledOnceWithExactly(callback, {updateType: LocusInfoUpdateType.MEETING_ENDED});
+
+            Object.values(parser.dataSets).forEach((ds: any) => {
+              assert.isUndefined(ds.timer);
+              assert.isUndefined(ds.heartbeatWatchdogTimer);
             });
+          });
+      });
+
+      describe('emits LOCUS_NOT_FOUND and stops parser when 404 is returned', () => {
+          it('when /hashtree returns 404', async () => {
+            const parser = createHashTreeParser();
+
+            const message = {
+              dataSets: [createDataSet('main', 16, 1100)],
+              visibleDataSetsUrl,
+              locusUrl,
+              locusStateElements: [
+                {
+                  htMeta: {
+                    elementId: {
+                      type: 'locus' as const,
+                      id: 0,
+                      version: 201,
+                    },
+                    dataSetNames: ['main'],
+                  },
+                  data: {info: {id: 'initial-update'}},
+                },
+              ],
+            };
+
+            parser.handleMessage(message, 'initial message');
+            callback.resetHistory();
+
+            const mainDataSetUrl = parser.dataSets.main.url;
+
+            const error: any = new Error('Request failed with status 404');
+            error.statusCode = 404;
+            webexRequest
+              .withArgs(
+                sinon.match({
+                  method: 'GET',
+                  uri: `${mainDataSetUrl}/hashtree`,
+                })
+              )
+              .rejects(error);
+
+            await clock.tickAsync(1000);
+
+            assert.calledOnceWithExactly(callback, {updateType: LocusInfoUpdateType.LOCUS_NOT_FOUND});
+
+            // Verify parser is stopped
+            expect(parser.state).to.equal('stopped');
 
             // Verify all timers are stopped
             Object.values(parser.dataSets).forEach((ds: any) => {
@@ -1758,10 +1934,9 @@ describe('HashTreeParser', () => {
             });
           });
 
-          it(`when /sync returns ${statusCode}`, async () => {
+          it('when /sync returns 404', async () => {
             const parser = createHashTreeParser();
 
-            // Send a message to trigger sync algorithm
             const message = {
               dataSets: [createDataSet('main', 16, 1100)],
               visibleDataSetsUrl,
@@ -1786,19 +1961,14 @@ describe('HashTreeParser', () => {
 
             const mainDataSetUrl = parser.dataSets.main.url;
 
-            // Mock getHashesFromLocus to succeed
             mockGetHashesFromLocusResponse(
               mainDataSetUrl,
               new Array(16).fill('00000000000000000000000000000000'),
               createDataSet('main', 16, 1101)
             );
 
-            // Mock sendSyncRequestToLocus to reject with the sentinel error
-            const error: any = new Error(`Request failed with status ${statusCode}`);
-            error.statusCode = statusCode;
-            if (statusCode === 409) {
-              error.body = {errorCode: 2403004};
-            }
+            const error: any = new Error('Request failed with status 404');
+            error.statusCode = 404;
             webexRequest
               .withArgs(
                 sinon.match({
@@ -1808,21 +1978,22 @@ describe('HashTreeParser', () => {
               )
               .rejects(error);
 
-            // Trigger sync by advancing time
             await clock.tickAsync(1000);
 
-            // Verify callback was called with MEETING_ENDED
-            assert.calledOnceWithExactly(callback, LocusInfoUpdateType.MEETING_ENDED, {
-              updatedObjects: undefined,
-            });
+            assert.calledOnceWithExactly(callback, {updateType: LocusInfoUpdateType.LOCUS_NOT_FOUND});
+
+            // Verify parser is stopped
+            expect(parser.state).to.equal('stopped');
 
             // 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('requests only mismatched hashes during sync', async () => {
@@ -1993,79 +2164,299 @@ 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)],
+        // 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,
-          locusStateElements: [
+        };
+
+        parser.handleMessage(heartbeatMessage, 'heartbeat with mismatch');
+
+        // The sync timer should be set
+        expect(parser.dataSets.main.timer).to.not.be.undefined;
+
+        // 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);
+
+        // Advance time to fire the sync timer (idleMs=1000 + backoff=0)
+        await clock.tickAsync(1000);
+
+        // Verify sync was triggered
+        assert.calledWith(
+          webexRequest,
+          sinon.match({
+            method: 'POST',
+            uri: `${mainDataSetUrl}/sync`,
+          })
+        );
+
+        // 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;
+
+        // 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: [
             {
-              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);
+        const mainDataSetUrl = parser.dataSets.main.url;
+        const newLeafCount = 32;
 
-        // 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',
-                  },
-                  {
+        // 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',
                   },
@@ -2172,7 +2563,99 @@ describe('HashTreeParser', () => {
         await checkAsyncDatasetInitialization(parser, newDataSet);
       });
 
-      it('emits MEETING_ENDED if async init of a new visible dataset fails with 404', async () => {
+      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 LOCUS_NOT_FOUND if async init of a new visible dataset fails with 404', async () => {
         const parser = createHashTreeParser();
 
         // Stub updateItems on self hash tree to return true
@@ -2237,10 +2720,8 @@ describe('HashTreeParser', () => {
         // Wait for the async initialization (queueMicrotask) to complete
         await clock.tickAsync(0);
 
-        // Verify callback was called with MEETING_ENDED
-        assert.calledOnceWithExactly(callback, LocusInfoUpdateType.MEETING_ENDED, {
-          updatedObjects: undefined,
-        });
+        // Verify callback was called with LOCUS_NOT_FOUND (404 means locus URL is stale, not necessarily meeting ended)
+        assert.calledOnceWithExactly(callback, {updateType: LocusInfoUpdateType.LOCUS_NOT_FOUND});
       });
 
       it('handles removal of visible data set', async () => {
@@ -2303,7 +2784,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: {
@@ -2400,38 +2881,182 @@ describe('HashTreeParser', () => {
         // Verify callback was NOT called (no updates for non-visible datasets)
         assert.notCalled(callback);
       });
-    });
 
-    describe('heartbeat watchdog', () => {
-      it('initiates sync immediately only for the specific data set whose heartbeat watchdog fires', async () => {
-        const parser = createHashTreeParser();
-        const heartbeatIntervalMs = 5000;
+      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'],
+              },
+            },
+          },
+        };
 
-        // Send initial heartbeat message for 'main' only
-        const heartbeatMessage = {
-          dataSets: [
-            {
-              ...createDataSet('main', 16, 1100),
-              root: parser.dataSets.main.hashTree.getRootHash(),
+        const metadata = {
+          htMeta: {
+            elementId: {
+              type: 'metadata',
+              id: 5,
+              version: 50,
             },
+            dataSetNames: ['self'],
+          },
+          visibleDataSets: [
+            {name: 'self', url: selfDataSet.url},
+            {name: 'unjoined', url: unjoinedDataSet.url},
           ],
-          visibleDataSetsUrl,
-          locusUrl,
-          heartbeatIntervalMs,
         };
 
-        parser.handleMessage(heartbeatMessage, 'initial heartbeat');
+        const parser = createHashTreeParser(initialLocus, metadata);
 
-        // Verify only 'main' watchdog timer is set
-        expect(parser.dataSets.main.heartbeatWatchdogTimer).to.not.be.undefined;
-        expect(parser.dataSets.self.heartbeatWatchdogTimer).to.be.undefined;
-        expect(parser.dataSets['atd-unmuted'].heartbeatWatchdogTimer).to.be.undefined;
+        // 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);
 
-        // Mock responses for performSync (GET hashtree then POST sync for leafCount > 1)
-        const mainDataSetUrl = parser.dataSets.main.url;
-        mockGetHashesFromLocusResponse(
-          mainDataSetUrl,
-          new Array(16).fill('00000000000000000000000000000000'),
+        // 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', () => {
+      it('initiates sync immediately only for the specific data set whose heartbeat watchdog fires', async () => {
+        const parser = createHashTreeParser();
+        const heartbeatIntervalMs = 5000;
+
+        // Send initial heartbeat message for 'main' only
+        const heartbeatMessage = {
+          dataSets: [
+            {
+              ...createDataSet('main', 16, 1100),
+              root: parser.dataSets.main.hashTree.getRootHash(),
+            },
+          ],
+          visibleDataSetsUrl,
+          locusUrl,
+        };
+
+        parser.handleMessage(heartbeatMessage, 'initial heartbeat');
+
+        // Verify only 'main' watchdog timer is set
+        expect(parser.dataSets.main.heartbeatWatchdogTimer).to.not.be.undefined;
+        expect(parser.dataSets.self.heartbeatWatchdogTimer).to.be.undefined;
+        expect(parser.dataSets['atd-unmuted'].heartbeatWatchdogTimer).to.be.undefined;
+
+        // Mock responses for performSync (GET hashtree then POST sync for leafCount > 1)
+        const mainDataSetUrl = parser.dataSets.main.url;
+        mockGetHashesFromLocusResponse(
+          mainDataSetUrl,
+          new Array(16).fill('00000000000000000000000000000000'),
           createDataSet('main', 16, 1101)
         );
         mockSendSyncRequestResponse(mainDataSetUrl, null);
@@ -2449,6 +3074,12 @@ describe('HashTreeParser', () => {
           })
         );
 
+        // Verify behavioral metric was sent for the watchdog expiration
+        assert.calledWith(metricsStub, BEHAVIORAL_METRICS.HASH_TREE_HEARTBEAT_WATCHDOG_EXPIRED, {
+          debugId: 'test',
+          dataSetName: 'main',
+        });
+
         // Verify no sync requests were sent for other datasets
         assert.neverCalledWith(
           webexRequest,
@@ -2481,7 +3112,6 @@ describe('HashTreeParser', () => {
           ],
           visibleDataSetsUrl,
           locusUrl,
-          heartbeatIntervalMs,
         };
 
         parser.handleMessage(heartbeatMessage, 'self heartbeat');
@@ -2492,6 +3122,12 @@ describe('HashTreeParser', () => {
         // Advance time past watchdog delay
         await clock.tickAsync(heartbeatIntervalMs);
 
+        // Verify behavioral metric was sent for the watchdog expiration
+        assert.calledWith(metricsStub, BEHAVIORAL_METRICS.HASH_TREE_HEARTBEAT_WATCHDOG_EXPIRED, {
+          debugId: 'test',
+          dataSetName: 'self',
+        });
+
         // For leafCount === 1, performSync skips GET hashtree and goes straight to POST sync
         assert.neverCalledWith(
           webexRequest,
@@ -2511,7 +3147,6 @@ describe('HashTreeParser', () => {
 
       it('sets watchdog timers for each data set in the message', async () => {
         const parser = createHashTreeParser();
-        const heartbeatIntervalMs = 5000;
 
         // Send heartbeat with multiple datasets
         const heartbeatMessage = {
@@ -2528,7 +3163,6 @@ describe('HashTreeParser', () => {
           ],
           visibleDataSetsUrl,
           locusUrl,
-          heartbeatIntervalMs,
         };
 
         parser.handleMessage(heartbeatMessage, 'multi-dataset heartbeat');
@@ -2542,7 +3176,6 @@ describe('HashTreeParser', () => {
 
       it('resets the watchdog timer for a specific data set when a new heartbeat for it is received', async () => {
         const parser = createHashTreeParser();
-        const heartbeatIntervalMs = 5000;
 
         // Send first heartbeat for 'main'
         const heartbeat1 = {
@@ -2554,7 +3187,6 @@ describe('HashTreeParser', () => {
           ],
           visibleDataSetsUrl,
           locusUrl,
-          heartbeatIntervalMs,
         };
 
         parser.handleMessage(heartbeat1, 'first heartbeat');
@@ -2575,7 +3207,6 @@ describe('HashTreeParser', () => {
           ],
           visibleDataSetsUrl,
           locusUrl,
-          heartbeatIntervalMs,
         };
 
         parser.handleMessage(heartbeat2, 'second heartbeat');
@@ -2594,7 +3225,6 @@ describe('HashTreeParser', () => {
 
       it('resets the watchdog timer when a normal message (with locusStateElements) is received', async () => {
         const parser = createHashTreeParser();
-        const heartbeatIntervalMs = 5000;
 
         // Send initial heartbeat to start the watchdog for 'main'
         const heartbeat = {
@@ -2606,7 +3236,6 @@ describe('HashTreeParser', () => {
           ],
           visibleDataSetsUrl,
           locusUrl,
-          heartbeatIntervalMs,
         };
 
         parser.handleMessage(heartbeat, 'initial heartbeat');
@@ -2634,7 +3263,6 @@ describe('HashTreeParser', () => {
               data: {someData: 'value'},
             },
           ],
-          heartbeatIntervalMs,
         };
 
         parser.handleMessage(normalMessage, 'normal message');
@@ -2648,12 +3276,17 @@ describe('HashTreeParser', () => {
         const parser = createHashTreeParser();
 
         // Send a heartbeat message without heartbeatIntervalMs
-        const heartbeatMessage = createHeartbeatMessage(
-          'main',
-          16,
-          1100,
-          parser.dataSets.main.hashTree.getRootHash()
-        );
+        const heartbeatMessage = {
+          dataSets: [
+            {
+              ...createDataSet('main', 16, 1100),
+              root: parser.dataSets.main.hashTree.getRootHash(),
+              heartbeatIntervalMs: undefined,
+            },
+          ],
+          visibleDataSetsUrl,
+          locusUrl,
+        };
 
         parser.handleMessage(heartbeatMessage, 'heartbeat without interval');
 
@@ -2662,7 +3295,6 @@ describe('HashTreeParser', () => {
 
       it('stops all watchdog timers when meeting ends via sentinel message', async () => {
         const parser = createHashTreeParser();
-        const heartbeatIntervalMs = 5000;
 
         // Send heartbeat for multiple datasets
         const heartbeat = {
@@ -2679,7 +3311,6 @@ describe('HashTreeParser', () => {
           ],
           visibleDataSetsUrl,
           locusUrl,
-          heartbeatIntervalMs,
         };
 
         parser.handleMessage(heartbeat, 'initial heartbeat');
@@ -2730,7 +3361,6 @@ describe('HashTreeParser', () => {
         };
 
         const parser = createHashTreeParser(initialLocus, metadata);
-        const heartbeatIntervalMs = 5000;
 
         // Set Math.random to return 1 so that backoff = 1^exponent * maxMs = maxMs
         mathRandomStub.returns(1);
@@ -2752,7 +3382,6 @@ describe('HashTreeParser', () => {
           ],
           visibleDataSetsUrl,
           locusUrl,
-          heartbeatIntervalMs,
         };
 
         parser.handleMessage(heartbeat, 'heartbeat');
@@ -2802,7 +3431,6 @@ describe('HashTreeParser', () => {
 
       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
@@ -2816,7 +3444,6 @@ describe('HashTreeParser', () => {
           ],
           visibleDataSetsUrl,
           locusUrl,
-          heartbeatIntervalMs,
         };
 
         parser.handleMessage(heartbeatMessage, 'heartbeat with non-visible dataset');
@@ -2825,7 +3452,192 @@ describe('HashTreeParser', () => {
         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,
+        };
+
+        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: `${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);
+
+        // Advance time again to fire the watchdog a second time
+        await clock.tickAsync(heartbeatIntervalMs);
+
+        // Verify a second sync was triggered
+        assert.calledWith(
+          webexRequest,
+          sinon.match({
+            method: 'GET',
+            uri: `${mainDataSetUrl}/hashtree`,
+          })
+        );
+
+        // And the watchdog should still be running
+        expect(parser.dataSets.main.heartbeatWatchdogTimer).to.not.be.undefined;
+      });
+
+      it('uses dataset-level heartbeatIntervalMs over top-level value', async () => {
+        const parser = createHashTreeParser();
+        const datasetLevelInterval = 3000;
+        const topLevelInterval = 8000;
+
+        // Send heartbeat with both top-level and dataset-level heartbeatIntervalMs
+        const heartbeatMessage = {
+          dataSets: [
+            {
+              ...createDataSet('main', 16, 1100),
+              root: parser.dataSets.main.hashTree.getRootHash(),
+              heartbeatIntervalMs: datasetLevelInterval,
+            },
+          ],
+          visibleDataSetsUrl,
+          locusUrl,
+          heartbeatIntervalMs: topLevelInterval,
+        };
+
+        parser.handleMessage(heartbeatMessage, 'heartbeat with both levels');
+
+        expect(parser.dataSets.main.heartbeatWatchdogTimer).to.not.be.undefined;
+
+        // Mock sync responses
+        const mainDataSetUrl = parser.dataSets.main.url;
+        mockGetHashesFromLocusResponse(
+          mainDataSetUrl,
+          new Array(16).fill('00000000000000000000000000000000'),
+          createDataSet('main', 16, 1101)
+        );
+        mockSendSyncRequestResponse(mainDataSetUrl, null);
+
+        // Watchdog should NOT fire at the top-level interval (8000ms)
+        // It should fire at the dataset-level interval (3000ms)
+        await clock.tickAsync(datasetLevelInterval - 1);
+        assert.notCalled(webexRequest);
+
+        await clock.tickAsync(1);
+        // Now at datasetLevelInterval, watchdog should have fired
+        assert.calledWith(
+          webexRequest,
+          sinon.match({
+            method: 'GET',
+            uri: `${mainDataSetUrl}/hashtree`,
+          })
+        );
+      });
+
+      it('falls back to top-level heartbeatIntervalMs when dataset-level is missing', async () => {
+        const parser = createHashTreeParser();
+        const topLevelInterval = 7000;
+
+        // Send heartbeat with top-level heartbeatIntervalMs but no dataset-level
+        const heartbeatMessage = {
+          dataSets: [
+            {
+              ...createDataSet('main', 16, 1100),
+              root: parser.dataSets.main.hashTree.getRootHash(),
+              heartbeatIntervalMs: undefined,
+            },
+          ],
+          visibleDataSetsUrl,
+          locusUrl,
+          heartbeatIntervalMs: topLevelInterval,
+        };
+
+        parser.handleMessage(heartbeatMessage, 'heartbeat with top-level only');
+
+        expect(parser.dataSets.main.heartbeatWatchdogTimer).to.not.be.undefined;
+
+        // Mock sync responses
+        const mainDataSetUrl = parser.dataSets.main.url;
+        mockGetHashesFromLocusResponse(
+          mainDataSetUrl,
+          new Array(16).fill('00000000000000000000000000000000'),
+          createDataSet('main', 16, 1101)
+        );
+        mockSendSyncRequestResponse(mainDataSetUrl, null);
+
+        // Should fire at the top-level interval
+        await clock.tickAsync(topLevelInterval - 1);
+        assert.notCalled(webexRequest);
+
+        await clock.tickAsync(1);
+        assert.calledWith(
+          webexRequest,
+          sinon.match({
+            method: 'GET',
+            uri: `${mainDataSetUrl}/hashtree`,
+          })
+        );
+      });
+
+      it('does not start watchdog when dataset-level heartbeatIntervalMs is 0 even if top-level is set', async () => {
+        const parser = createHashTreeParser();
+
+        // Send heartbeat with dataset-level 0 and a top-level value
+        const heartbeatMessage = {
+          dataSets: [
+            {
+              ...createDataSet('main', 16, 1100),
+              root: parser.dataSets.main.hashTree.getRootHash(),
+              heartbeatIntervalMs: 0,
+            },
+          ],
+          visibleDataSetsUrl,
+          locusUrl,
+          heartbeatIntervalMs: 5000,
+        };
+
+        parser.handleMessage(heartbeatMessage, 'heartbeat with dataset-level 0');
+
+        // Dataset-level 0 means no watchdog, should NOT fall back to top-level
+        expect(parser.dataSets.main.heartbeatWatchdogTimer).to.be.undefined;
+      });
     });
+
   });
 
   describe('#callLocusInfoUpdateCallback filtering', () => {
@@ -2922,7 +3734,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: {
@@ -2993,7 +3805,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: {
@@ -3128,7 +3940,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: {
@@ -3282,6 +4094,9 @@ describe('HashTreeParser', () => {
       parser.handleMessage(emptyMessage, 'empty elements');
 
       assert.notCalled(callback);
+      assert.calledWith(metricsStub, BEHAVIORAL_METRICS.HASH_TREE_EMPTY_LOCUS_STATE_ELEMENTS, {
+        debugId: 'test',
+      });
     });
 
     it('always calls callback for MEETING_ENDED regardless of filtering', () => {
@@ -3306,9 +4121,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});
     });
   });
 
@@ -3514,7 +4327,7 @@ describe('HashTreeParser', () => {
     });
   });
 
-  describe('#resume', () => {
+  describe('#resumeFromMessage', () => {
     const createResumeMessage = (visibleDataSets?, dataSets?) => ({
       locusUrl,
       visibleDataSetsUrl,
@@ -3541,7 +4354,7 @@ describe('HashTreeParser', () => {
 
       expect(parser.state).to.equal('stopped');
 
-      parser.resume(createResumeMessage());
+      parser.resumeFromMessage(createResumeMessage());
 
       expect(parser.state).to.equal('active');
     });
@@ -3550,7 +4363,7 @@ describe('HashTreeParser', () => {
       const parser = createHashTreeParser();
       parser.stop();
 
-      parser.resume({
+      parser.resumeFromMessage({
         locusUrl,
         visibleDataSetsUrl,
         dataSets: [createDataSet('main', 16, 2000)],
@@ -3569,7 +4382,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);
@@ -3591,7 +4404,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);
@@ -3605,7 +4418,7 @@ describe('HashTreeParser', () => {
       const handleMessageStub = sinon.stub(parser, 'handleMessage');
 
       const message = createResumeMessage();
-      parser.resume(message);
+      parser.resumeFromMessage(message);
 
       assert.calledOnceWithExactly(handleMessageStub, message, 'on resume');
     });
@@ -3625,7 +4438,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;
@@ -3633,21 +4446,82 @@ describe('HashTreeParser', () => {
     });
   });
 
-  describe('#handleLocusUpdate when stopped', () => {
-    it('should return early without processing when parser is stopped', () => {
+  describe('#resumeFromApiResponse', () => {
+    const exampleLocus = {
+      participants: [],
+    } as any;
+
+    it('should set state to active', async () => {
       const parser = createHashTreeParser();
       parser.stop();
 
-      parser.handleLocusUpdate({
-        dataSets: [createDataSet('main', 16, 2000)],
-        locus: {participants: []},
-      });
+      expect(parser.state).to.equal('stopped');
 
-      assert.notCalled(callback);
+      sinon.stub(parser, 'initializeFromGetLociResponse').resolves();
+
+      await parser.resumeFromApiResponse(exampleLocus);
+
+      expect(parser.state).to.equal('active');
     });
-  });
 
-  describe('#handleMessage when stopped', () => {
+    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();
+      parser.stop();
+
+      parser.handleLocusUpdate({
+        dataSets: [createDataSet('main', 16, 2000)],
+        locus: {participants: []},
+      });
+
+      assert.notCalled(callback);
+    });
+  });
+
+  describe('#handleMessage when stopped', () => {
     it('should return early without processing when parser is stopped', () => {
       const parser = createHashTreeParser();
       parser.stop();
@@ -3667,4 +4541,788 @@ 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 syncAllBackoffType is reset
+      expect(parser.syncAllBackoffType).to.equal(SyncAllBackoffType.NONE);
+    });
+
+    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 sync only LLM datasets when onlyLLM=true', async () => {
+      const parser = createHashTreeParser();
+
+      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: [],
+      });
+
+      await parser.syncAllDatasets({onlyLLM: true});
+
+      // main is an LLM dataset, so it should have been synced
+      assert.calledWith(webexRequest, sinon.match({method: 'GET', uri: `${mainUrl}/hashtree`}));
+
+      // self is NOT an LLM dataset, so it should NOT have been synced
+      assert.neverCalledWith(webexRequest, sinon.match({method: 'POST', uri: `${selfUrl}/sync`}));
+      assert.neverCalledWith(webexRequest, sinon.match({method: 'GET', uri: `${selfUrl}/hashtree`}));
+    });
+
+    it('should upgrade scope from onlyLLM=true to all datasets when onlyLLM=false call arrives during backoff', async () => {
+      // Make Math.random return 1 so backoff = 1^2 * 1000 = 1000ms (non-zero delay for interleaving)
+      mathRandomStub.returns(1);
+
+      const parser = createHashTreeParser();
+
+      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: [],
+      });
+
+      // First call with onlyLLM=true starts backoff
+      const promise1 = parser.syncAllDatasets({onlyLLM: true});
+      expect(parser.syncAllBackoffType).to.equal(SyncAllBackoffType.ONLY_LLM);
+
+      // Second call with onlyLLM=false upgrades the scope during backoff
+      const promise2 = parser.syncAllDatasets({onlyLLM: false});
+      expect(parser.syncAllBackoffType).to.equal(SyncAllBackoffType.ALL);
+
+      // Advance clock past the backoff delay (1000ms)
+      await clock.tickAsync(1000);
+
+      await promise1;
+      await promise2;
+
+      // Both main (LLM) and self (non-LLM) should have been synced
+      assert.calledWith(webexRequest, sinon.match({method: 'GET', uri: `${mainUrl}/hashtree`}));
+      assert.calledWith(webexRequest, sinon.match({method: 'POST', uri: `${selfUrl}/sync`}));
+    });
+
+    it('should not downgrade scope from onlyLLM=false when onlyLLM=true call arrives during backoff', async () => {
+      // Make Math.random return 1 so backoff = 1^2 * 1000 = 1000ms (non-zero delay for interleaving)
+      mathRandomStub.returns(1);
+
+      const parser = createHashTreeParser();
+
+      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: [],
+      });
+
+      // First call with onlyLLM=false starts backoff with all-datasets scope
+      const promise1 = parser.syncAllDatasets({onlyLLM: false});
+      expect(parser.syncAllBackoffType).to.equal(SyncAllBackoffType.ALL);
+
+      // Second call with onlyLLM=true should NOT downgrade the scope
+      const promise2 = parser.syncAllDatasets({onlyLLM: true});
+      expect(parser.syncAllBackoffType).to.equal(SyncAllBackoffType.ALL);
+
+      // Advance clock past the backoff delay (1000ms)
+      await clock.tickAsync(1000);
+
+      await promise1;
+      await promise2;
+
+      // Both main (LLM) and self (non-LLM) should have been synced (scope was not downgraded)
+      assert.calledWith(webexRequest, sinon.match({method: 'GET', uri: `${mainUrl}/hashtree`}));
+      assert.calledWith(webexRequest, sinon.match({method: 'POST', uri: `${selfUrl}/sync`}));
+    });
+
+    it('should skip datasets that received messages during the backoff sleep', async () => {
+      // Make Math.random return 1 so backoff = 1^2 * 1000 = 1000ms
+      mathRandomStub.returns(1);
+
+      const parser = createHashTreeParser();
+
+      const mainUrl = parser.dataSets.main.url;
+      const selfUrl = parser.dataSets.self.url;
+      const atdUnmutedUrl = parser.dataSets['atd-unmuted'].url;
+
+      // Setup mocks only for self (main and atd-unmuted should be skipped)
+      mockSendSyncRequestResponse(selfUrl, {
+        dataSets: [createDataSet('self', 1, 2100)],
+        visibleDataSetsUrl,
+        locusUrl,
+        locusStateElements: [],
+      });
+
+      // Start syncAllDatasets - begins backoff sleep
+      const promise = parser.syncAllDatasets();
+      expect(parser.syncAllBackoffType).to.equal(SyncAllBackoffType.ALL);
+
+      // Simulate a normal message arriving for "main" during the backoff sleep
+      parser.handleMessage({
+        dataSets: [createDataSet('main', 16, 1100)],
+        visibleDataSetsUrl,
+        locusUrl,
+        locusStateElements: [
+          {
+            htMeta: {
+              elementId: {type: 'locus' as const, id: 0, version: 201},
+              dataSetNames: ['main'],
+            },
+            data: {someData: 'value'},
+          },
+        ],
+      });
+
+      // Simulate a heartbeat message arriving for "atd-unmuted" during the backoff sleep
+      parser.handleMessage(
+        createHeartbeatMessage('atd-unmuted', 1, 1100, parser.dataSets['atd-unmuted'].root)
+      );
+
+      // Advance clock past the backoff delay
+      await clock.tickAsync(1000);
+      await promise;
+
+      // main should NOT have been synced (it received a normal message during backoff)
+      assert.neverCalledWith(webexRequest, sinon.match({method: 'GET', uri: `${mainUrl}/hashtree`}));
+      assert.neverCalledWith(webexRequest, sinon.match({method: 'POST', uri: `${mainUrl}/sync`}));
+
+      // atd-unmuted should NOT have been synced (it received a heartbeat during backoff)
+      assert.neverCalledWith(webexRequest, sinon.match({method: 'GET', uri: `${atdUnmutedUrl}/hashtree`}));
+      assert.neverCalledWith(webexRequest, sinon.match({method: 'POST', uri: `${atdUnmutedUrl}/sync`}));
+
+      // self SHOULD have been synced (no messages received for it during backoff)
+      assert.calledWith(webexRequest, sinon.match({method: 'POST', uri: `${selfUrl}/sync`}));
+    });
+
+    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('#performSync abort controller', () => {
+    it('should reuse an existing syncAbortController if one is already set on the dataset', async () => {
+      const parser = createHashTreeParser();
+      const mainUrl = parser.dataSets.main.url;
+
+      // Pre-set an AbortController on the dataset before sync starts
+      const existingController = new AbortController();
+      parser.dataSets.main.syncAbortController = existingController;
+
+      // Use a deferred promise for GET hashtree so we can inspect the controller mid-sync
+      let resolveGetHashtree;
+      webexRequest.withArgs(sinon.match({method: 'GET', uri: `${mainUrl}/hashtree`})).callsFake(
+        () =>
+          new Promise((resolve) => {
+            resolveGetHashtree = resolve;
+          })
+      );
+
+      // Trigger sync for main
+      parser.handleMessage(
+        createHeartbeatMessage('main', 16, 1100, 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa1'),
+        'trigger main sync'
+      );
+
+      await clock.tickAsync(1000);
+
+      // While sync is in-flight, verify the controller is the same one we pre-set
+      expect(parser.dataSets.main.syncAbortController).to.equal(existingController);
+
+      // Resolve GET hashtree with matching hashes (no sync needed)
+      resolveGetHashtree({body: {}});
+      await testUtils.flushPromises();
+
+      // After sync completes, syncAbortController is cleared in finally
+      expect(parser.dataSets.main.syncAbortController).to.be.undefined;
+    });
+
+    it('should abort the sync before /sync request when the controller is aborted during getHashesFromLocus', async () => {
+      const parser = createHashTreeParser();
+      const mainUrl = parser.dataSets.main.url;
+
+      // Use a deferred promise for GET hashtree so we can abort while it's pending
+      let resolveGetHashtree;
+      webexRequest.withArgs(sinon.match({method: 'GET', uri: `${mainUrl}/hashtree`})).callsFake(
+        () =>
+          new Promise((resolve) => {
+            resolveGetHashtree = resolve;
+          })
+      );
+
+      // Mock POST sync - should NOT be called if abort works
+      mockSendSyncRequestResponse(mainUrl, null);
+
+      // Trigger sync for main via heartbeat with mismatched root hash
+      parser.handleMessage(
+        createHeartbeatMessage('main', 16, 1100, 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa1'),
+        'trigger main sync'
+      );
+
+      // Fire the timer to start the sync
+      await clock.tickAsync(1000);
+
+      // Now abort the controller while getHashesFromLocus is pending
+      expect(parser.dataSets.main.syncAbortController).to.not.be.undefined;
+      parser.dataSets.main.syncAbortController.abort();
+
+      // Resolve GET hashtree with mismatched hashes so the code would normally proceed to /sync
+      resolveGetHashtree({
+        body: {
+          hashes: new Array(16).fill('aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa1'),
+          dataSet: createDataSet('main', 16, 1100),
+        },
+      });
+
+      await testUtils.flushPromises();
+
+      // POST sync should NOT have been called because the controller was aborted
+      assert.neverCalledWith(webexRequest, sinon.match({method: 'POST', uri: `${mainUrl}/sync`}));
+    });
+
+    it('should abort the sync before /sync request when the controller is aborted for leafCount === 1 datasets', async () => {
+      const parser = createHashTreeParser();
+      const selfUrl = parser.dataSets.self.url;
+
+      // Pre-set an already-aborted controller so performSync picks it up via ??
+      const abortedController = new AbortController();
+      abortedController.abort();
+      parser.dataSets.self.syncAbortController = abortedController;
+
+      // Mock POST sync - should NOT be called
+      mockSendSyncRequestResponse(selfUrl, null);
+
+      // Trigger sync for self via heartbeat with mismatched root hash
+      parser.handleMessage(
+        {
+          dataSets: [
+            {
+              ...createDataSet('self', 1, 2100),
+              url: parser.dataSets.self.url,
+              root: 'bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb1',
+            },
+          ],
+          visibleDataSetsUrl,
+          locusUrl,
+        },
+        'trigger self sync'
+      );
+
+      // Fire the timer to start the sync
+      await clock.tickAsync(1000);
+
+      // GET hashtree should NOT have been called (leafCount === 1 skips it)
+      assert.neverCalledWith(webexRequest, sinon.match({method: 'GET', uri: `${selfUrl}/hashtree`}));
+
+      // POST sync should NOT have been called because the controller was already aborted
+      assert.neverCalledWith(webexRequest, sinon.match({method: 'POST', uri: `${selfUrl}/sync`}));
+    });
+
+    it('should unconditionally clear syncAbortController in the finally block', async () => {
+      const parser = createHashTreeParser();
+      const mainUrl = parser.dataSets.main.url;
+
+      // Mock GET hashtree to return matching hashes (early return, no sync needed)
+      webexRequest
+        .withArgs(sinon.match({method: 'GET', uri: `${mainUrl}/hashtree`}))
+        .resolves({body: {}});
+
+      // Trigger sync for main
+      parser.handleMessage(
+        createHeartbeatMessage('main', 16, 1100, 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa1'),
+        'trigger main sync'
+      );
+
+      await clock.tickAsync(1000);
+
+      // After sync completes (even via early return), syncAbortController should be cleared
+      expect(parser.dataSets.main.syncAbortController).to.be.undefined;
+    });
+
+    it('should unconditionally clear syncAbortController even when sync throws an error', async () => {
+      const parser = createHashTreeParser();
+      const mainUrl = parser.dataSets.main.url;
+
+      // Mock GET hashtree to reject with a non-409 error
+      webexRequest
+        .withArgs(sinon.match({method: 'GET', uri: `${mainUrl}/hashtree`}))
+        .rejects({statusCode: 500, message: 'Internal Server Error'});
+
+      // Trigger sync for main
+      parser.handleMessage(
+        createHeartbeatMessage('main', 16, 1100, 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa1'),
+        'trigger main sync'
+      );
+
+      await clock.tickAsync(1000);
+
+      // After sync completes with error, syncAbortController should still be cleared
+      expect(parser.dataSets.main.syncAbortController).to.be.undefined;
+    });
+
+    it('should reuse a pre-existing abort controller and respect its aborted state', async () => {
+      const parser = createHashTreeParser();
+      const mainUrl = parser.dataSets.main.url;
+
+      // Pre-set an AbortController and abort it before sync starts
+      const preAbortedController = new AbortController();
+      preAbortedController.abort();
+      parser.dataSets.main.syncAbortController = preAbortedController;
+
+      // Mock GET hashtree to return mismatched hashes
+      mockGetHashesFromLocusResponse(
+        mainUrl,
+        new Array(16).fill('aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa1'),
+        createDataSet('main', 16, 1100)
+      );
+
+      // Mock POST sync - should NOT be called
+      mockSendSyncRequestResponse(mainUrl, null);
+
+      // Trigger sync for main
+      parser.handleMessage(
+        createHeartbeatMessage('main', 16, 1100, 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa1'),
+        'trigger main sync'
+      );
+
+      await clock.tickAsync(1000);
+
+      // POST sync should NOT have been called because the reused controller was already aborted
+      assert.neverCalledWith(webexRequest, sinon.match({method: 'POST', uri: `${mainUrl}/sync`}));
+
+      // syncAbortController should be cleaned up
+      expect(parser.dataSets.main.syncAbortController).to.be.undefined;
+    });
+
+    it('should allow cancelPendingSyncsForDataSets to abort an in-flight sync via the shared controller', async () => {
+      const parser = createHashTreeParser();
+      const mainUrl = parser.dataSets.main.url;
+
+      // Use a deferred promise for GET hashtree
+      let resolveGetHashtree;
+      webexRequest.withArgs(sinon.match({method: 'GET', uri: `${mainUrl}/hashtree`})).callsFake(
+        () =>
+          new Promise((resolve) => {
+            resolveGetHashtree = resolve;
+          })
+      );
+
+      mockSendSyncRequestResponse(mainUrl, null);
+
+      // Trigger sync for main
+      parser.handleMessage(
+        createHeartbeatMessage('main', 16, 1100, 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa1'),
+        'trigger main sync'
+      );
+
+      // Fire the timer to start sync
+      await clock.tickAsync(1000);
+
+      // Verify controller is set
+      expect(parser.dataSets.main.syncAbortController).to.not.be.undefined;
+
+      // Simulate a new heartbeat arriving that cancels the in-flight sync
+      // (this is what happens in production via parseMessage -> cancelPendingSyncsForDataSets)
+      parser.handleMessage(
+        {
+          dataSets: [
+            {
+              ...createDataSet('main', 16, 1101),
+              root: parser.dataSets.main.hashTree.getRootHash(), // matching hash so no new sync
+            },
+          ],
+          visibleDataSetsUrl,
+          locusUrl,
+        },
+        'new heartbeat cancels sync'
+      );
+
+      // Resolve the pending GET hashtree with mismatched hashes
+      resolveGetHashtree({
+        body: {
+          hashes: new Array(16).fill('aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa1'),
+          dataSet: createDataSet('main', 16, 1101),
+        },
+      });
+
+      await testUtils.flushPromises();
+
+      // POST sync should NOT have been called because cancelPendingSyncsForDataSets aborted the controller
+      assert.neverCalledWith(webexRequest, sinon.match({method: 'POST', uri: `${mainUrl}/sync`}));
+    });
+  });
+
+  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,
+        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({});
+    });
+  });
 });