@adtrackify/at-service-common 4.0.3 → 4.0.4

package/dist/esm/__tests__/identity-cache/trait-merging-and-staleness.spec.js

@@ -1,1059 +1,1059 @@
-import { ADDRESS_INFO_SOURCE } from '@adtrackify/at-tracking-event-types';
-import { mergeIdentityTraits } from '@adtrackify/at-shared-utils';
-import { isIdentityCacheStale, isClickInfosStale, IDENTITY_CACHE_STALENESS_TIER, } from '../../helpers/identity-cache-helper';
-describe('Identity Trait Merging Tests', () => {
-    afterEach(() => {
-        jest.resetModules();
-    });
-    describe('mergeIdentityTraits function', () => {
-        it('should merge simple string arrays correctly', () => {
-            const incomingTraits = {
-                emails: ['new@email.com'],
-                userIds: ['user1', 'user2'],
-            };
-            const cachedTraits = {
-                emails: ['existing@email.com'],
-                userIds: ['user2', 'user3'],
-                phones: ['+1234567890'],
-            };
-            const merged = mergeIdentityTraits(incomingTraits, cachedTraits);
-            expect(merged.emails).toEqual(['new@email.com', 'existing@email.com']);
-            expect(merged.userIds).toEqual(['user1', 'user2', 'user3']);
-            expect(merged.phones).toEqual(['+1234567890']);
-        });
-        it('should handle null and undefined values in arrays', () => {
-            const incomingTraits = {
-                emails: ['test@email.com', null, undefined],
-                userIds: ['user1'],
-            };
-            const cachedTraits = {
-                emails: [null, 'cached@email.com', undefined],
-                userIds: null,
-            };
-            const merged = mergeIdentityTraits(incomingTraits, cachedTraits);
-            expect(merged.emails).toContain('test@email.com');
-            expect(merged.emails).toContain('cached@email.com');
-            expect(merged.userIds).toEqual(['user1']);
-        });
-        it('should merge addresses correctly', () => {
-            const incomingTraits = {
-                addresses: [
-                    {
-                        city: 'New York',
-                        country: 'USA',
-                        countryCode: 'US',
-                        province: 'NY',
-                        provinceCode: '10001',
-                    },
-                ],
-            };
-            const cachedTraits = {
-                addresses: [
-                    {
-                        city: 'Los Angeles',
-                        country: 'USA',
-                        countryCode: 'US',
-                        province: 'CA',
-                        provinceCode: '90210',
-                    },
-                ],
-            };
-            const merged = mergeIdentityTraits(incomingTraits, cachedTraits);
-            expect(merged.addresses).toHaveLength(2);
-            expect(merged.addresses).toEqual(expect.arrayContaining([
-                expect.objectContaining({ city: 'New York' }),
-                expect.objectContaining({ city: 'Los Angeles' }),
-            ]));
-        });
-        it('should merge click information correctly', () => {
-            const incomingTraits = {
-                click: {
-                    fbp: 'fb.new.123',
-                    fbpCollectedAt: '2024-01-01T00:00:00.000Z',
-                    gclid: 'new_gclid',
-                },
-            };
-            const cachedTraits = {
-                click: {
-                    fbp: 'fb.old.456',
-                    fbpCollectedAt: '2023-12-01T00:00:00.000Z',
-                    fbclid: 'cached_fbclid',
-                },
-            };
-            const merged = mergeIdentityTraits(incomingTraits, cachedTraits);
-            expect(merged.click?.fbp).toBe('fb.new.123');
-            expect(merged.click?.gclid).toBe('new_gclid');
-            expect(merged.click?.fbpCollectedAt).toBe('2024-01-01T00:00:00.000Z');
-            expect(merged.click?.fbclid).toBeUndefined();
-        });
-        it('should handle empty traits correctly', () => {
-            const incomingTraits = {};
-            const cachedTraits = {
-                emails: ['cached@email.com'],
-                userIds: ['user1'],
-            };
-            const merged = mergeIdentityTraits(incomingTraits, cachedTraits);
-            expect(merged.emails).toEqual(['cached@email.com']);
-            expect(merged.userIds).toEqual(['user1']);
-        });
-        it('should handle undefined traits correctly', () => {
-            const merged1 = mergeIdentityTraits(undefined, { emails: ['test@email.com'] });
-            expect(merged1.emails).toEqual(['test@email.com']);
-            const merged2 = mergeIdentityTraits({ emails: ['test@email.com'] }, undefined);
-            expect(merged2.emails).toEqual(['test@email.com']);
-            const merged3 = mergeIdentityTraits(undefined, undefined);
-            expect(merged3).toEqual({});
-        });
-        it('should preserve version information', () => {
-            const incomingTraits = {
-                version: '3',
-                emails: ['new@email.com'],
-            };
-            const cachedTraits = {
-                version: '2',
-                emails: ['old@email.com'],
-            };
-            const merged = mergeIdentityTraits(incomingTraits, cachedTraits);
-            expect(merged.version).toBe('3');
-            expect(merged.emails).toEqual(['new@email.com', 'old@email.com']);
-        });
-        it('should handle complex nested objects', () => {
-            const incomingTraits = {
-                click: {
-                    googleClientInfos: [{ id: 'new1', clickId: 'click1', sessionId: 'session1' }],
-                },
-            };
-            const cachedTraits = {
-                click: {
-                    googleClientInfos: [{ id: 'cached1', clickId: 'click2', sessionId: 'session2' }],
-                },
-            };
-            const merged = mergeIdentityTraits(incomingTraits, cachedTraits);
-            expect(merged.click?.googleClientInfos).toBeDefined();
-            expect(Array.isArray(merged.click?.googleClientInfos)).toBe(true);
-            expect(merged.click?.googleClientInfos).toEqual([{ id: 'cached1', clickId: 'click2', sessionId: 'session2' }]);
-        });
-    });
-    describe('Integration: Merging + Staleness Checking', () => {
-        it('should not be stale when merged identity matches cached identity', () => {
-            const cachedIdentity = {
-                identityId: 'test-id-123',
-                traits: {
-                    emails: ['cached@email.com', 'shared@email.com'],
-                    userIds: ['user1', 'user2'],
-                    addresses: [
-                        {
-                            city: 'New York',
-                            country: 'USA',
-                            countryCode: 'US',
-                        },
-                    ],
-                    version: '2',
-                },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id-123',
-                traits: {
-                    emails: ['shared@email.com'],
-                    userIds: ['user1'],
-                    version: '2',
-                },
-            };
-            const mergedTraits = mergeIdentityTraits(incomingIdentity.traits, cachedIdentity.traits);
-            const mergedIdentity = { ...incomingIdentity, traits: mergedTraits };
-            const staleTracker = isIdentityCacheStale(cachedIdentity, mergedIdentity);
-            expect(staleTracker.isCacheStale).toBe(false);
-            expect(mergedIdentity.traits?.emails).toEqual(['shared@email.com', 'cached@email.com']);
-        });
-        it('should be stale when merged identity has new traits', () => {
-            const cachedIdentity = {
-                identityId: 'test-id-123',
-                traits: {
-                    emails: ['cached@email.com'],
-                    version: '2',
-                },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id-123',
-                traits: {
-                    emails: ['cached@email.com', 'new@email.com'],
-                    version: '2',
-                },
-            };
-            const mergedTraits = mergeIdentityTraits(incomingIdentity.traits, cachedIdentity.traits);
-            const mergedIdentity = { ...incomingIdentity, traits: mergedTraits };
-            const staleTracker = isIdentityCacheStale(cachedIdentity, mergedIdentity);
-            expect(staleTracker.isCacheStale).toBe(true);
-            expect(staleTracker.isEmailsStale).toBe(true);
-        });
-    });
-});
-describe('Identity Cache Staleness Tests', () => {
-    afterEach(() => {
-        jest.resetModules();
-    });
-    describe('isIdentityCacheStale function', () => {
-        it('should detect identity ID changes', () => {
-            const cachedIdentity = {
-                identityId: 'old-id',
-                traits: { emails: ['test@email.com'] },
-            };
-            const incomingIdentity = {
-                identityId: 'new-id',
-                traits: { emails: ['test@email.com'] },
-            };
-            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
-            expect(result.isCacheStale).toBe(true);
-            expect(result.isIdentityIdStale).toBe(true);
-        });
-        it('should detect new emails', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: { emails: ['old@email.com'] },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: { emails: ['old@email.com', 'new@email.com'] },
-            };
-            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
-            expect(result.isCacheStale).toBe(true);
-            expect(result.isEmailsStale).toBe(true);
-        });
-        it('should detect new user IDs', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: { userIds: ['user1'] },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: { userIds: ['user1', 'user2'] },
-            };
-            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
-            expect(result.isCacheStale).toBe(true);
-            expect(result.isUserIdsStale).toBe(true);
-        });
-        it('should detect new phones', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: { phones: ['+1234567890'] },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: { phones: ['+1234567890', '+9876543210'] },
-            };
-            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
-            expect(result.isCacheStale).toBe(true);
-            expect(result.isPhonesStale).toBe(true);
-        });
-        it('should detect new addresses (non-IP sourced)', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    addresses: [
-                        {
-                            city: 'New York',
-                            country: 'USA',
-                            s: ADDRESS_INFO_SOURCE.INPUT,
-                        },
-                    ],
-                },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    addresses: [
-                        { city: 'New York', country: 'USA', s: ADDRESS_INFO_SOURCE.INPUT },
-                        { city: 'Los Angeles', country: 'USA', s: ADDRESS_INFO_SOURCE.INPUT },
-                    ],
-                },
-            };
-            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
-            expect(result.isCacheStale).toBe(true);
-            expect(result.isAddressesStale).toBe(true);
-            expect(result.isNonIpAddressesStale).toBe(true);
-            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.ADDRESS_UPDATE);
-        });
-        it('should detect IP address changes but NOT mark cache stale (volatile trait)', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: { ipAddress: '192.168.1.1' },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: { ipAddress: '10.0.0.1' },
-            };
-            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
-            expect(result.isCacheStale).toBe(false);
-            expect(result.isIpAddressStale).toBe(true);
-            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.VOLATILE_ONLY);
-        });
-        it('should detect user agent changes but NOT mark cache stale (volatile trait)', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: { userAgent: 'Mozilla/5.0 (old browser)' },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: { userAgent: 'Mozilla/5.0 (new browser)' },
-            };
-            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
-            expect(result.isCacheStale).toBe(false);
-            expect(result.isUserAgentStale).toBe(true);
-            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.VOLATILE_ONLY);
-        });
-        it('should not be stale when no new information is provided', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    userIds: ['user1'],
-                    phones: ['+1234567890'],
-                },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    userIds: ['user1'],
-                },
-            };
-            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
-            expect(result.isCacheStale).toBe(false);
-        });
-        it('should handle empty traits gracefully', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {},
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {},
-            };
-            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
-            expect(result.isCacheStale).toBe(false);
-        });
-        it('should handle undefined traits gracefully', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-            };
-            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
-            expect(result.isCacheStale).toBe(false);
-        });
-        it('should detect multiple stale conditions (identity traits take priority over volatile)', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['old@email.com'],
-                    userIds: ['user1'],
-                    ipAddress: '192.168.1.1',
-                },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['old@email.com', 'new@email.com'],
-                    userIds: ['user1', 'user2'],
-                    ipAddress: '10.0.0.1',
-                },
-            };
-            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
-            expect(result.isCacheStale).toBe(true);
-            expect(result.isEmailsStale).toBe(true);
-            expect(result.isUserIdsStale).toBe(true);
-            expect(result.isIpAddressStale).toBe(true);
-            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.IDENTITY_STALE);
-        });
-    });
-    describe('isClickInfosStale function', () => {
-        it('should detect new FBC values', () => {
-            const cachedClick = {
-                fbc: 'fb.1.123.old_fbclid',
-            };
-            const incomingClick = {
-                fbc: 'fb.1.123.new_fbclid',
-            };
-            const result = isClickInfosStale(cachedClick, incomingClick);
-            expect(result).toBe(true);
-        });
-        it('should detect new click IDs', () => {
-            const cachedClick = {
-                gclid: 'old_gclid',
-            };
-            const incomingClick = {
-                gclid: 'new_gclid',
-            };
-            const result = isClickInfosStale(cachedClick, incomingClick);
-            expect(result).toBe(true);
-        });
-        it('should ignore collection timestamps', () => {
-            const cachedClick = {
-                fbp: 'fb.2.123.456',
-                fbpCollectedAt: '2023-01-01T00:00:00.000Z',
-            };
-            const incomingClick = {
-                fbp: 'fb.2.123.456',
-                fbpCollectedAt: '2024-01-01T00:00:00.000Z',
-            };
-            const result = isClickInfosStale(cachedClick, incomingClick);
-            expect(result).toBe(false);
-        });
-        it('should ignore googleClientInfos', () => {
-            const cachedClick = {
-                googleClientInfos: [{ id: 'old', clickId: 'old_click' }],
-            };
-            const incomingClick = {
-                googleClientInfos: [{ id: 'new', clickId: 'new_click' }],
-            };
-            const result = isClickInfosStale(cachedClick, incomingClick);
-            expect(result).toBe(false);
-        });
-        it('should handle empty click info', () => {
-            const result = isClickInfosStale({}, {});
-            expect(result).toBe(false);
-        });
-        it('should detect when incoming has new click info but cached is empty', () => {
-            const cachedClick = {};
-            const incomingClick = {
-                fbp: 'fb.2.123.456',
-            };
-            const result = isClickInfosStale(cachedClick, incomingClick);
-            expect(result).toBe(true);
-        });
-    });
-    describe('Edge Cases and Error Handling', () => {
-        it('should handle malformed FBC values gracefully', () => {
-            const cachedClick = {
-                fbc: 'malformed_fbc',
-            };
-            const incomingClick = {
-                fbc: 'also_malformed',
-            };
-            const result = isClickInfosStale(cachedClick, incomingClick);
-            expect(result).toBe(true);
-        });
-        it('should handle null/undefined arrays in traits', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: null,
-                    userIds: undefined,
-                },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['new@email.com'],
-                    userIds: ['user1'],
-                },
-            };
-            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
-            expect(result.isCacheStale).toBe(true);
-            expect(result.isEmailsStale).toBe(true);
-            expect(result.isUserIdsStale).toBe(true);
-        });
-        it('should handle arrays with null/undefined elements', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['valid@email.com', null, undefined],
-                },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['valid@email.com', null, undefined, 'new@email.com'],
-                },
-            };
-            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
-            expect(result.isCacheStale).toBe(true);
-            expect(result.isEmailsStale).toBe(true);
-        });
-        it('should handle error conditions gracefully', () => {
-            const result = isIdentityCacheStale(null, undefined);
-            expect(result.isCacheStale).toBe(false);
-        });
-    });
-    describe('Comprehensive Scenario Tests', () => {
-        it('should handle complex real-world scenario', () => {
-            const cachedIdentity = {
-                identityId: '01HXRZ27H4TXWBBTRK09Q7APDP',
-                traits: {
-                    emails: ['user@domain.com'],
-                    userIds: ['shopify_123'],
-                    addresses: [
-                        {
-                            city: 'New York',
-                            country: 'USA',
-                            countryCode: 'US',
-                            province: 'NY',
-                            provinceCode: '10001',
-                        },
-                    ],
-                    click: {
-                        fbp: 'fb.2.1715603578424.5068754021',
-                        fbpCollectedAt: '2024-05-13T12:32:58.424Z',
-                        gclid: 'original_gclid',
-                    },
-                    ipAddress: '192.168.1.100',
-                    version: '2',
-                },
-            };
-            const incomingIdentity = {
-                identityId: '01HXRZ27H4TXWBBTRK09Q7APDP',
-                traits: {
-                    emails: ['user@domain.com', 'user.secondary@domain.com'],
-                    phones: ['+1234567890'],
-                    addresses: [
-                        {
-                            city: 'New York',
-                            country: 'USA',
-                            countryCode: 'US',
-                            province: 'NY',
-                            provinceCode: '10001',
-                        },
-                    ],
-                    click: {
-                        fbp: 'fb.2.1715603578424.5068754021',
-                        fbpCollectedAt: '2024-05-13T15:30:00.000Z',
-                        gclid: 'updated_gclid',
-                    },
-                    ipAddress: '192.168.1.100',
-                    version: '2',
-                },
-            };
-            const mergedTraits = mergeIdentityTraits(cachedIdentity.traits, incomingIdentity.traits);
-            const mergedIdentity = { ...incomingIdentity, traits: mergedTraits };
-            const result = isIdentityCacheStale(cachedIdentity, mergedIdentity);
-            expect(result.isCacheStale).toBe(true);
-            expect(result.isEmailsStale).toBe(true);
-            expect(result.isPhonesStale).toBe(true);
-            expect(result.isClickInfosStale).toBe(true);
-            expect(result.isAddressesStale).toBe(false);
-            expect(result.isIpAddressStale).toBe(false);
-            expect(mergedIdentity.traits?.emails).toEqual(['user@domain.com', 'user.secondary@domain.com']);
-            expect(mergedIdentity.traits?.phones).toEqual(['+1234567890']);
-            expect(mergedIdentity.traits?.userIds).toEqual(['shopify_123']);
-            expect(mergedIdentity.traits?.click?.gclid).toEqual('updated_gclid');
-        });
-        it('should properly detect click staleness when click info actually differs', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    click: {
-                        gclid: 'original_gclid',
-                        gclidCollectedAt: '2024-05-15T12:32:58.424Z',
-                    },
-                },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    click: {
-                        gclid: 'completely_different_gclid',
-                        gclidCollectedAt: '2024-05-13T12:32:58.424Z',
-                    },
-                },
-            };
-            const mergedTraits = mergeIdentityTraits(cachedIdentity.traits, incomingIdentity.traits);
-            const mergedIdentity = { ...incomingIdentity, traits: mergedTraits };
-            const result = isIdentityCacheStale(cachedIdentity, mergedIdentity);
-            expect(mergedTraits?.click?.gclid).toEqual('original_gclid');
-            expect(result.isCacheStale).toBe(false);
-        });
-        it('should handle scenario where cache is fresh', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['user@domain.com', 'secondary@domain.com'],
-                    userIds: ['user1', 'user2'],
-                    phones: ['+1234567890'],
-                    version: '2',
-                },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['user@domain.com'],
-                    userIds: ['user1'],
-                    version: '2',
-                },
-            };
-            const mergedTraits = mergeIdentityTraits(cachedIdentity.traits, incomingIdentity.traits);
-            const mergedIdentity = { ...incomingIdentity, traits: mergedTraits };
-            const result = isIdentityCacheStale(cachedIdentity, mergedIdentity);
-            expect(result.isCacheStale).toBe(false);
-            expect(mergedIdentity.traits?.emails).toEqual(['user@domain.com', 'secondary@domain.com']);
-            expect(mergedIdentity.traits?.userIds).toEqual(['user1', 'user2']);
-            expect(mergedIdentity.traits?.phones).toEqual(['+1234567890']);
-        });
-    });
-});
-describe('Three-Tier Staleness Model Tests', () => {
-    afterEach(() => {
-        jest.resetModules();
-    });
-    describe('TIER 1: VOLATILE_ONLY (no action needed)', () => {
-        it('should return VOLATILE_ONLY tier when only ipAddress is stale', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    ipAddress: '192.168.1.1',
-                },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    ipAddress: '10.0.0.1',
-                },
-            };
-            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
-            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.VOLATILE_ONLY);
-            expect(result.isCacheStale).toBe(false);
-            expect(result.isIpAddressStale).toBe(true);
-        });
-        it('should return VOLATILE_ONLY tier when only userAgent is stale', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    userAgent: 'Mozilla/5.0 (old)',
-                },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    userAgent: 'Mozilla/5.0 (new)',
-                },
-            };
-            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
-            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.VOLATILE_ONLY);
-            expect(result.isCacheStale).toBe(false);
-            expect(result.isUserAgentStale).toBe(true);
-        });
-        it('should return VOLATILE_ONLY tier when only IP-sourced addresses are stale', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    addresses: [
-                        { city: 'New York', country: 'USA', s: ADDRESS_INFO_SOURCE.IP_ADDRESS },
-                    ],
-                },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    addresses: [
-                        { city: 'Los Angeles', country: 'USA', s: ADDRESS_INFO_SOURCE.IP_ADDRESS },
-                    ],
-                },
-            };
-            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
-            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.VOLATILE_ONLY);
-            expect(result.isCacheStale).toBe(false);
-            expect(result.isIpAddressesStale).toBe(true);
-            expect(result.isNonIpAddressesStale).toBe(false);
-        });
-        it('should return VOLATILE_ONLY tier when multiple volatile traits are stale', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    ipAddress: '192.168.1.1',
-                    userAgent: 'Mozilla/5.0 (old)',
-                    addresses: [
-                        { city: 'New York', s: ADDRESS_INFO_SOURCE.IP_ADDRESS },
-                    ],
-                },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    ipAddress: '10.0.0.1',
-                    userAgent: 'Mozilla/5.0 (new)',
-                    addresses: [
-                        { city: 'Chicago', s: ADDRESS_INFO_SOURCE.IP_ADDRESS },
-                    ],
-                },
-            };
-            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
-            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.VOLATILE_ONLY);
-            expect(result.isCacheStale).toBe(false);
-            expect(result.isIpAddressStale).toBe(true);
-            expect(result.isUserAgentStale).toBe(true);
-            expect(result.isIpAddressesStale).toBe(true);
-        });
-    });
-    describe('TIER 2: ADDRESS_UPDATE (cache write only, skip Neptune)', () => {
-        it('should return ADDRESS_UPDATE tier when non-IP address is new', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    addresses: [],
-                },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    addresses: [
-                        { city: 'Boston', province: 'MA', s: ADDRESS_INFO_SOURCE.INPUT },
-                    ],
-                },
-            };
-            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
-            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.ADDRESS_UPDATE);
-            expect(result.isCacheStale).toBe(true);
-            expect(result.isNonIpAddressesStale).toBe(true);
-        });
-        it('should return ADDRESS_UPDATE tier when new input address added', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    addresses: [
-                        { city: 'New York', s: ADDRESS_INFO_SOURCE.INPUT },
-                    ],
-                },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    addresses: [
-                        { city: 'New York', s: ADDRESS_INFO_SOURCE.INPUT },
-                        { city: 'Boston', s: ADDRESS_INFO_SOURCE.INPUT },
-                    ],
-                },
-            };
-            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
-            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.ADDRESS_UPDATE);
-            expect(result.isCacheStale).toBe(true);
-            expect(result.isNonIpAddressesStale).toBe(true);
-        });
-        it('should return ADDRESS_UPDATE tier even when volatile traits are also stale', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    ipAddress: '192.168.1.1',
-                    addresses: [],
-                },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    ipAddress: '10.0.0.1',
-                    addresses: [
-                        { city: 'Boston', s: ADDRESS_INFO_SOURCE.INPUT },
-                    ],
-                },
-            };
-            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
-            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.ADDRESS_UPDATE);
-            expect(result.isCacheStale).toBe(true);
-            expect(result.isIpAddressStale).toBe(true);
-            expect(result.isNonIpAddressesStale).toBe(true);
-        });
-    });
-    describe('TIER 3: IDENTITY_STALE (full Neptune resolution)', () => {
-        it('should return IDENTITY_STALE tier when email is new', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['old@email.com'],
-                },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['old@email.com', 'new@email.com'],
-                },
-            };
-            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
-            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.IDENTITY_STALE);
-            expect(result.isCacheStale).toBe(true);
-            expect(result.isEmailsStale).toBe(true);
-        });
-        it('should return IDENTITY_STALE tier when identityId changes', () => {
-            const cachedIdentity = {
-                identityId: 'old-id',
-                traits: { emails: ['test@email.com'] },
-            };
-            const incomingIdentity = {
-                identityId: 'new-id',
-                traits: { emails: ['test@email.com'] },
-            };
-            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
-            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.IDENTITY_STALE);
-            expect(result.isCacheStale).toBe(true);
-            expect(result.isIdentityIdStale).toBe(true);
-        });
-        it('should return IDENTITY_STALE tier when phone is new', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: { phones: ['+1234567890'] },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: { phones: ['+1234567890', '+9876543210'] },
-            };
-            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
-            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.IDENTITY_STALE);
-            expect(result.isCacheStale).toBe(true);
-            expect(result.isPhonesStale).toBe(true);
-        });
-        it('should return IDENTITY_STALE tier when click info changes', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    click: { gclid: 'old_gclid' },
-                },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    click: { gclid: 'new_gclid' },
-                },
-            };
-            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
-            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.IDENTITY_STALE);
-            expect(result.isCacheStale).toBe(true);
-            expect(result.isClickInfosStale).toBe(true);
-        });
-        it('should return IDENTITY_STALE tier when identity trait is stale even with ADDRESS_UPDATE', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['old@email.com'],
-                    addresses: [],
-                },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['old@email.com', 'new@email.com'],
-                    addresses: [
-                        { city: 'Boston', s: ADDRESS_INFO_SOURCE.INPUT },
-                    ],
-                },
-            };
-            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
-            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.IDENTITY_STALE);
-            expect(result.isCacheStale).toBe(true);
-            expect(result.isEmailsStale).toBe(true);
-            expect(result.isNonIpAddressesStale).toBe(true);
-        });
-        it('should return IDENTITY_STALE tier when identity trait is stale even with VOLATILE_ONLY', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['old@email.com'],
-                    ipAddress: '192.168.1.1',
-                },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['old@email.com', 'new@email.com'],
-                    ipAddress: '10.0.0.1',
-                },
-            };
-            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
-            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.IDENTITY_STALE);
-            expect(result.isCacheStale).toBe(true);
-            expect(result.isEmailsStale).toBe(true);
-            expect(result.isIpAddressStale).toBe(true);
-        });
-    });
-    describe('TIER NONE: No staleness', () => {
-        it('should return NONE tier when nothing is stale', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    phones: ['+1234567890'],
-                    ipAddress: '192.168.1.1',
-                },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    phones: ['+1234567890'],
-                    ipAddress: '192.168.1.1',
-                },
-            };
-            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
-            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.NONE);
-            expect(result.isCacheStale).toBe(false);
-        });
-        it('should return NONE tier when incoming is subset of cached', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['a@email.com', 'b@email.com'],
-                    phones: ['+1234567890', '+9876543210'],
-                },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['a@email.com'],
-                },
-            };
-            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
-            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.NONE);
-            expect(result.isCacheStale).toBe(false);
-        });
-    });
-    describe('Address source filtering', () => {
-        it('should correctly identify IP-sourced addresses', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    addresses: [
-                        { city: 'CachedCity', s: ADDRESS_INFO_SOURCE.IP_ADDRESS },
-                    ],
-                },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    addresses: [
-                        { city: 'NewCity', s: ADDRESS_INFO_SOURCE.IP_ADDRESS },
-                    ],
-                },
-            };
-            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
-            expect(result.isIpAddressesStale).toBe(true);
-            expect(result.isNonIpAddressesStale).toBe(false);
-            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.VOLATILE_ONLY);
-        });
-        it('should correctly identify INPUT-sourced addresses', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    addresses: [
-                        { city: 'CachedCity', s: ADDRESS_INFO_SOURCE.INPUT },
-                    ],
-                },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    addresses: [
-                        { city: 'CachedCity', s: ADDRESS_INFO_SOURCE.INPUT },
-                        { city: 'NewCity', s: ADDRESS_INFO_SOURCE.INPUT },
-                    ],
-                },
-            };
-            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
-            expect(result.isIpAddressesStale).toBe(false);
-            expect(result.isNonIpAddressesStale).toBe(true);
-            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.ADDRESS_UPDATE);
-        });
-        it('should handle mixed address sources correctly', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    addresses: [
-                        { city: 'IPCity', s: ADDRESS_INFO_SOURCE.IP_ADDRESS },
-                        { city: 'InputCity', s: ADDRESS_INFO_SOURCE.INPUT },
-                    ],
-                },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    addresses: [
-                        { city: 'NewIPCity', s: ADDRESS_INFO_SOURCE.IP_ADDRESS },
-                        { city: 'InputCity', s: ADDRESS_INFO_SOURCE.INPUT },
-                        { city: 'NewInputCity', s: ADDRESS_INFO_SOURCE.INPUT },
-                    ],
-                },
-            };
-            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
-            expect(result.isIpAddressesStale).toBe(true);
-            expect(result.isNonIpAddressesStale).toBe(true);
-            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.ADDRESS_UPDATE);
-            expect(result.isCacheStale).toBe(true);
-        });
-        it('should handle addresses without source field (default to IP based on PII)', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    addresses: [],
-                },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    addresses: [
-                        { city: 'NoSourceCity' },
-                    ],
-                },
-            };
-            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
-            expect(result.isIpAddressesStale).toBe(true);
-            expect(result.isNonIpAddressesStale).toBe(false);
-            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.VOLATILE_ONLY);
-            expect(result.isCacheStale).toBe(false);
-        });
-        it('should treat addresses without source but with PII as non-IP', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    addresses: [],
-                },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    addresses: [
-                        { city: 'InputCity', firstName: 'John' },
-                    ],
-                },
-            };
-            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
-            expect(result.isNonIpAddressesStale).toBe(true);
-            expect(result.isIpAddressesStale).toBe(false);
-            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.ADDRESS_UPDATE);
-            expect(result.isCacheStale).toBe(true);
-        });
-    });
-    describe('Backward compatibility', () => {
-        it('should maintain isAddressesStale for any address change', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    addresses: [
-                        { city: 'OldCity', s: ADDRESS_INFO_SOURCE.IP_ADDRESS },
-                    ],
-                },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    addresses: [
-                        { city: 'NewCity', s: ADDRESS_INFO_SOURCE.IP_ADDRESS },
-                    ],
-                },
-            };
-            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
-            expect(result.isAddressesStale).toBe(true);
-            expect(result.isCacheStale).toBe(false);
-        });
-    });
-});
+import { ADDRESS_INFO_SOURCE } from '@adtrackify/at-tracking-event-types';
+import { mergeIdentityTraits } from '@adtrackify/at-shared-utils';
+import { isIdentityCacheStale, isClickInfosStale, IDENTITY_CACHE_STALENESS_TIER, } from '../../helpers/identity-cache-helper';
+describe('Identity Trait Merging Tests', () => {
+    afterEach(() => {
+        jest.resetModules();
+    });
+    describe('mergeIdentityTraits function', () => {
+        it('should merge simple string arrays correctly', () => {
+            const incomingTraits = {
+                emails: ['new@email.com'],
+                userIds: ['user1', 'user2'],
+            };
+            const cachedTraits = {
+                emails: ['existing@email.com'],
+                userIds: ['user2', 'user3'],
+                phones: ['+1234567890'],
+            };
+            const merged = mergeIdentityTraits(incomingTraits, cachedTraits);
+            expect(merged.emails).toEqual(['new@email.com', 'existing@email.com']);
+            expect(merged.userIds).toEqual(['user1', 'user2', 'user3']);
+            expect(merged.phones).toEqual(['+1234567890']);
+        });
+        it('should handle null and undefined values in arrays', () => {
+            const incomingTraits = {
+                emails: ['test@email.com', null, undefined],
+                userIds: ['user1'],
+            };
+            const cachedTraits = {
+                emails: [null, 'cached@email.com', undefined],
+                userIds: null,
+            };
+            const merged = mergeIdentityTraits(incomingTraits, cachedTraits);
+            expect(merged.emails).toContain('test@email.com');
+            expect(merged.emails).toContain('cached@email.com');
+            expect(merged.userIds).toEqual(['user1']);
+        });
+        it('should merge addresses correctly', () => {
+            const incomingTraits = {
+                addresses: [
+                    {
+                        city: 'New York',
+                        country: 'USA',
+                        countryCode: 'US',
+                        province: 'NY',
+                        provinceCode: '10001',
+                    },
+                ],
+            };
+            const cachedTraits = {
+                addresses: [
+                    {
+                        city: 'Los Angeles',
+                        country: 'USA',
+                        countryCode: 'US',
+                        province: 'CA',
+                        provinceCode: '90210',
+                    },
+                ],
+            };
+            const merged = mergeIdentityTraits(incomingTraits, cachedTraits);
+            expect(merged.addresses).toHaveLength(2);
+            expect(merged.addresses).toEqual(expect.arrayContaining([
+                expect.objectContaining({ city: 'New York' }),
+                expect.objectContaining({ city: 'Los Angeles' }),
+            ]));
+        });
+        it('should merge click information correctly', () => {
+            const incomingTraits = {
+                click: {
+                    fbp: 'fb.new.123',
+                    fbpCollectedAt: '2024-01-01T00:00:00.000Z',
+                    gclid: 'new_gclid',
+                },
+            };
+            const cachedTraits = {
+                click: {
+                    fbp: 'fb.old.456',
+                    fbpCollectedAt: '2023-12-01T00:00:00.000Z',
+                    fbclid: 'cached_fbclid',
+                },
+            };
+            const merged = mergeIdentityTraits(incomingTraits, cachedTraits);
+            expect(merged.click?.fbp).toBe('fb.new.123');
+            expect(merged.click?.gclid).toBe('new_gclid');
+            expect(merged.click?.fbpCollectedAt).toBe('2024-01-01T00:00:00.000Z');
+            expect(merged.click?.fbclid).toBeUndefined();
+        });
+        it('should handle empty traits correctly', () => {
+            const incomingTraits = {};
+            const cachedTraits = {
+                emails: ['cached@email.com'],
+                userIds: ['user1'],
+            };
+            const merged = mergeIdentityTraits(incomingTraits, cachedTraits);
+            expect(merged.emails).toEqual(['cached@email.com']);
+            expect(merged.userIds).toEqual(['user1']);
+        });
+        it('should handle undefined traits correctly', () => {
+            const merged1 = mergeIdentityTraits(undefined, { emails: ['test@email.com'] });
+            expect(merged1.emails).toEqual(['test@email.com']);
+            const merged2 = mergeIdentityTraits({ emails: ['test@email.com'] }, undefined);
+            expect(merged2.emails).toEqual(['test@email.com']);
+            const merged3 = mergeIdentityTraits(undefined, undefined);
+            expect(merged3).toEqual({});
+        });
+        it('should preserve version information', () => {
+            const incomingTraits = {
+                version: '3',
+                emails: ['new@email.com'],
+            };
+            const cachedTraits = {
+                version: '2',
+                emails: ['old@email.com'],
+            };
+            const merged = mergeIdentityTraits(incomingTraits, cachedTraits);
+            expect(merged.version).toBe('3');
+            expect(merged.emails).toEqual(['new@email.com', 'old@email.com']);
+        });
+        it('should handle complex nested objects', () => {
+            const incomingTraits = {
+                click: {
+                    googleClientInfos: [{ id: 'new1', clickId: 'click1', sessionId: 'session1' }],
+                },
+            };
+            const cachedTraits = {
+                click: {
+                    googleClientInfos: [{ id: 'cached1', clickId: 'click2', sessionId: 'session2' }],
+                },
+            };
+            const merged = mergeIdentityTraits(incomingTraits, cachedTraits);
+            expect(merged.click?.googleClientInfos).toBeDefined();
+            expect(Array.isArray(merged.click?.googleClientInfos)).toBe(true);
+            expect(merged.click?.googleClientInfos).toEqual([{ id: 'cached1', clickId: 'click2', sessionId: 'session2' }]);
+        });
+    });
+    describe('Integration: Merging + Staleness Checking', () => {
+        it('should not be stale when merged identity matches cached identity', () => {
+            const cachedIdentity = {
+                identityId: 'test-id-123',
+                traits: {
+                    emails: ['cached@email.com', 'shared@email.com'],
+                    userIds: ['user1', 'user2'],
+                    addresses: [
+                        {
+                            city: 'New York',
+                            country: 'USA',
+                            countryCode: 'US',
+                        },
+                    ],
+                    version: '2',
+                },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id-123',
+                traits: {
+                    emails: ['shared@email.com'],
+                    userIds: ['user1'],
+                    version: '2',
+                },
+            };
+            const mergedTraits = mergeIdentityTraits(incomingIdentity.traits, cachedIdentity.traits);
+            const mergedIdentity = { ...incomingIdentity, traits: mergedTraits };
+            const staleTracker = isIdentityCacheStale(cachedIdentity, mergedIdentity);
+            expect(staleTracker.isCacheStale).toBe(false);
+            expect(mergedIdentity.traits?.emails).toEqual(['shared@email.com', 'cached@email.com']);
+        });
+        it('should be stale when merged identity has new traits', () => {
+            const cachedIdentity = {
+                identityId: 'test-id-123',
+                traits: {
+                    emails: ['cached@email.com'],
+                    version: '2',
+                },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id-123',
+                traits: {
+                    emails: ['cached@email.com', 'new@email.com'],
+                    version: '2',
+                },
+            };
+            const mergedTraits = mergeIdentityTraits(incomingIdentity.traits, cachedIdentity.traits);
+            const mergedIdentity = { ...incomingIdentity, traits: mergedTraits };
+            const staleTracker = isIdentityCacheStale(cachedIdentity, mergedIdentity);
+            expect(staleTracker.isCacheStale).toBe(true);
+            expect(staleTracker.isEmailsStale).toBe(true);
+        });
+    });
+});
+describe('Identity Cache Staleness Tests', () => {
+    afterEach(() => {
+        jest.resetModules();
+    });
+    describe('isIdentityCacheStale function', () => {
+        it('should detect identity ID changes', () => {
+            const cachedIdentity = {
+                identityId: 'old-id',
+                traits: { emails: ['test@email.com'] },
+            };
+            const incomingIdentity = {
+                identityId: 'new-id',
+                traits: { emails: ['test@email.com'] },
+            };
+            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
+            expect(result.isCacheStale).toBe(true);
+            expect(result.isIdentityIdStale).toBe(true);
+        });
+        it('should detect new emails', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: { emails: ['old@email.com'] },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: { emails: ['old@email.com', 'new@email.com'] },
+            };
+            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
+            expect(result.isCacheStale).toBe(true);
+            expect(result.isEmailsStale).toBe(true);
+        });
+        it('should detect new user IDs', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: { userIds: ['user1'] },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: { userIds: ['user1', 'user2'] },
+            };
+            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
+            expect(result.isCacheStale).toBe(true);
+            expect(result.isUserIdsStale).toBe(true);
+        });
+        it('should detect new phones', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: { phones: ['+1234567890'] },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: { phones: ['+1234567890', '+9876543210'] },
+            };
+            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
+            expect(result.isCacheStale).toBe(true);
+            expect(result.isPhonesStale).toBe(true);
+        });
+        it('should detect new addresses (non-IP sourced)', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    addresses: [
+                        {
+                            city: 'New York',
+                            country: 'USA',
+                            s: ADDRESS_INFO_SOURCE.INPUT,
+                        },
+                    ],
+                },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    addresses: [
+                        { city: 'New York', country: 'USA', s: ADDRESS_INFO_SOURCE.INPUT },
+                        { city: 'Los Angeles', country: 'USA', s: ADDRESS_INFO_SOURCE.INPUT },
+                    ],
+                },
+            };
+            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
+            expect(result.isCacheStale).toBe(true);
+            expect(result.isAddressesStale).toBe(true);
+            expect(result.isNonIpAddressesStale).toBe(true);
+            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.ADDRESS_UPDATE);
+        });
+        it('should detect IP address changes but NOT mark cache stale (volatile trait)', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: { ipAddress: '192.168.1.1' },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: { ipAddress: '10.0.0.1' },
+            };
+            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
+            expect(result.isCacheStale).toBe(false);
+            expect(result.isIpAddressStale).toBe(true);
+            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.VOLATILE_ONLY);
+        });
+        it('should detect user agent changes but NOT mark cache stale (volatile trait)', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: { userAgent: 'Mozilla/5.0 (old browser)' },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: { userAgent: 'Mozilla/5.0 (new browser)' },
+            };
+            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
+            expect(result.isCacheStale).toBe(false);
+            expect(result.isUserAgentStale).toBe(true);
+            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.VOLATILE_ONLY);
+        });
+        it('should not be stale when no new information is provided', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    userIds: ['user1'],
+                    phones: ['+1234567890'],
+                },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    userIds: ['user1'],
+                },
+            };
+            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
+            expect(result.isCacheStale).toBe(false);
+        });
+        it('should handle empty traits gracefully', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {},
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {},
+            };
+            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
+            expect(result.isCacheStale).toBe(false);
+        });
+        it('should handle undefined traits gracefully', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+            };
+            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
+            expect(result.isCacheStale).toBe(false);
+        });
+        it('should detect multiple stale conditions (identity traits take priority over volatile)', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['old@email.com'],
+                    userIds: ['user1'],
+                    ipAddress: '192.168.1.1',
+                },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['old@email.com', 'new@email.com'],
+                    userIds: ['user1', 'user2'],
+                    ipAddress: '10.0.0.1',
+                },
+            };
+            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
+            expect(result.isCacheStale).toBe(true);
+            expect(result.isEmailsStale).toBe(true);
+            expect(result.isUserIdsStale).toBe(true);
+            expect(result.isIpAddressStale).toBe(true);
+            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.IDENTITY_STALE);
+        });
+    });
+    describe('isClickInfosStale function', () => {
+        it('should detect new FBC values', () => {
+            const cachedClick = {
+                fbc: 'fb.1.123.old_fbclid',
+            };
+            const incomingClick = {
+                fbc: 'fb.1.123.new_fbclid',
+            };
+            const result = isClickInfosStale(cachedClick, incomingClick);
+            expect(result).toBe(true);
+        });
+        it('should detect new click IDs', () => {
+            const cachedClick = {
+                gclid: 'old_gclid',
+            };
+            const incomingClick = {
+                gclid: 'new_gclid',
+            };
+            const result = isClickInfosStale(cachedClick, incomingClick);
+            expect(result).toBe(true);
+        });
+        it('should ignore collection timestamps', () => {
+            const cachedClick = {
+                fbp: 'fb.2.123.456',
+                fbpCollectedAt: '2023-01-01T00:00:00.000Z',
+            };
+            const incomingClick = {
+                fbp: 'fb.2.123.456',
+                fbpCollectedAt: '2024-01-01T00:00:00.000Z',
+            };
+            const result = isClickInfosStale(cachedClick, incomingClick);
+            expect(result).toBe(false);
+        });
+        it('should ignore googleClientInfos', () => {
+            const cachedClick = {
+                googleClientInfos: [{ id: 'old', clickId: 'old_click' }],
+            };
+            const incomingClick = {
+                googleClientInfos: [{ id: 'new', clickId: 'new_click' }],
+            };
+            const result = isClickInfosStale(cachedClick, incomingClick);
+            expect(result).toBe(false);
+        });
+        it('should handle empty click info', () => {
+            const result = isClickInfosStale({}, {});
+            expect(result).toBe(false);
+        });
+        it('should detect when incoming has new click info but cached is empty', () => {
+            const cachedClick = {};
+            const incomingClick = {
+                fbp: 'fb.2.123.456',
+            };
+            const result = isClickInfosStale(cachedClick, incomingClick);
+            expect(result).toBe(true);
+        });
+    });
+    describe('Edge Cases and Error Handling', () => {
+        it('should handle malformed FBC values gracefully', () => {
+            const cachedClick = {
+                fbc: 'malformed_fbc',
+            };
+            const incomingClick = {
+                fbc: 'also_malformed',
+            };
+            const result = isClickInfosStale(cachedClick, incomingClick);
+            expect(result).toBe(true);
+        });
+        it('should handle null/undefined arrays in traits', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: null,
+                    userIds: undefined,
+                },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['new@email.com'],
+                    userIds: ['user1'],
+                },
+            };
+            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
+            expect(result.isCacheStale).toBe(true);
+            expect(result.isEmailsStale).toBe(true);
+            expect(result.isUserIdsStale).toBe(true);
+        });
+        it('should handle arrays with null/undefined elements', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['valid@email.com', null, undefined],
+                },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['valid@email.com', null, undefined, 'new@email.com'],
+                },
+            };
+            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
+            expect(result.isCacheStale).toBe(true);
+            expect(result.isEmailsStale).toBe(true);
+        });
+        it('should handle error conditions gracefully', () => {
+            const result = isIdentityCacheStale(null, undefined);
+            expect(result.isCacheStale).toBe(false);
+        });
+    });
+    describe('Comprehensive Scenario Tests', () => {
+        it('should handle complex real-world scenario', () => {
+            const cachedIdentity = {
+                identityId: '01HXRZ27H4TXWBBTRK09Q7APDP',
+                traits: {
+                    emails: ['user@domain.com'],
+                    userIds: ['shopify_123'],
+                    addresses: [
+                        {
+                            city: 'New York',
+                            country: 'USA',
+                            countryCode: 'US',
+                            province: 'NY',
+                            provinceCode: '10001',
+                        },
+                    ],
+                    click: {
+                        fbp: 'fb.2.1715603578424.5068754021',
+                        fbpCollectedAt: '2024-05-13T12:32:58.424Z',
+                        gclid: 'original_gclid',
+                    },
+                    ipAddress: '192.168.1.100',
+                    version: '2',
+                },
+            };
+            const incomingIdentity = {
+                identityId: '01HXRZ27H4TXWBBTRK09Q7APDP',
+                traits: {
+                    emails: ['user@domain.com', 'user.secondary@domain.com'],
+                    phones: ['+1234567890'],
+                    addresses: [
+                        {
+                            city: 'New York',
+                            country: 'USA',
+                            countryCode: 'US',
+                            province: 'NY',
+                            provinceCode: '10001',
+                        },
+                    ],
+                    click: {
+                        fbp: 'fb.2.1715603578424.5068754021',
+                        fbpCollectedAt: '2024-05-13T15:30:00.000Z',
+                        gclid: 'updated_gclid',
+                    },
+                    ipAddress: '192.168.1.100',
+                    version: '2',
+                },
+            };
+            const mergedTraits = mergeIdentityTraits(cachedIdentity.traits, incomingIdentity.traits);
+            const mergedIdentity = { ...incomingIdentity, traits: mergedTraits };
+            const result = isIdentityCacheStale(cachedIdentity, mergedIdentity);
+            expect(result.isCacheStale).toBe(true);
+            expect(result.isEmailsStale).toBe(true);
+            expect(result.isPhonesStale).toBe(true);
+            expect(result.isClickInfosStale).toBe(true);
+            expect(result.isAddressesStale).toBe(false);
+            expect(result.isIpAddressStale).toBe(false);
+            expect(mergedIdentity.traits?.emails).toEqual(['user@domain.com', 'user.secondary@domain.com']);
+            expect(mergedIdentity.traits?.phones).toEqual(['+1234567890']);
+            expect(mergedIdentity.traits?.userIds).toEqual(['shopify_123']);
+            expect(mergedIdentity.traits?.click?.gclid).toEqual('updated_gclid');
+        });
+        it('should properly detect click staleness when click info actually differs', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    click: {
+                        gclid: 'original_gclid',
+                        gclidCollectedAt: '2024-05-15T12:32:58.424Z',
+                    },
+                },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    click: {
+                        gclid: 'completely_different_gclid',
+                        gclidCollectedAt: '2024-05-13T12:32:58.424Z',
+                    },
+                },
+            };
+            const mergedTraits = mergeIdentityTraits(cachedIdentity.traits, incomingIdentity.traits);
+            const mergedIdentity = { ...incomingIdentity, traits: mergedTraits };
+            const result = isIdentityCacheStale(cachedIdentity, mergedIdentity);
+            expect(mergedTraits?.click?.gclid).toEqual('original_gclid');
+            expect(result.isCacheStale).toBe(false);
+        });
+        it('should handle scenario where cache is fresh', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['user@domain.com', 'secondary@domain.com'],
+                    userIds: ['user1', 'user2'],
+                    phones: ['+1234567890'],
+                    version: '2',
+                },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['user@domain.com'],
+                    userIds: ['user1'],
+                    version: '2',
+                },
+            };
+            const mergedTraits = mergeIdentityTraits(cachedIdentity.traits, incomingIdentity.traits);
+            const mergedIdentity = { ...incomingIdentity, traits: mergedTraits };
+            const result = isIdentityCacheStale(cachedIdentity, mergedIdentity);
+            expect(result.isCacheStale).toBe(false);
+            expect(mergedIdentity.traits?.emails).toEqual(['user@domain.com', 'secondary@domain.com']);
+            expect(mergedIdentity.traits?.userIds).toEqual(['user1', 'user2']);
+            expect(mergedIdentity.traits?.phones).toEqual(['+1234567890']);
+        });
+    });
+});
+describe('Three-Tier Staleness Model Tests', () => {
+    afterEach(() => {
+        jest.resetModules();
+    });
+    describe('TIER 1: VOLATILE_ONLY (no action needed)', () => {
+        it('should return VOLATILE_ONLY tier when only ipAddress is stale', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    ipAddress: '192.168.1.1',
+                },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    ipAddress: '10.0.0.1',
+                },
+            };
+            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
+            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.VOLATILE_ONLY);
+            expect(result.isCacheStale).toBe(false);
+            expect(result.isIpAddressStale).toBe(true);
+        });
+        it('should return VOLATILE_ONLY tier when only userAgent is stale', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    userAgent: 'Mozilla/5.0 (old)',
+                },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    userAgent: 'Mozilla/5.0 (new)',
+                },
+            };
+            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
+            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.VOLATILE_ONLY);
+            expect(result.isCacheStale).toBe(false);
+            expect(result.isUserAgentStale).toBe(true);
+        });
+        it('should return VOLATILE_ONLY tier when only IP-sourced addresses are stale', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    addresses: [
+                        { city: 'New York', country: 'USA', s: ADDRESS_INFO_SOURCE.IP_ADDRESS },
+                    ],
+                },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    addresses: [
+                        { city: 'Los Angeles', country: 'USA', s: ADDRESS_INFO_SOURCE.IP_ADDRESS },
+                    ],
+                },
+            };
+            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
+            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.VOLATILE_ONLY);
+            expect(result.isCacheStale).toBe(false);
+            expect(result.isIpAddressesStale).toBe(true);
+            expect(result.isNonIpAddressesStale).toBe(false);
+        });
+        it('should return VOLATILE_ONLY tier when multiple volatile traits are stale', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    ipAddress: '192.168.1.1',
+                    userAgent: 'Mozilla/5.0 (old)',
+                    addresses: [
+                        { city: 'New York', s: ADDRESS_INFO_SOURCE.IP_ADDRESS },
+                    ],
+                },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    ipAddress: '10.0.0.1',
+                    userAgent: 'Mozilla/5.0 (new)',
+                    addresses: [
+                        { city: 'Chicago', s: ADDRESS_INFO_SOURCE.IP_ADDRESS },
+                    ],
+                },
+            };
+            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
+            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.VOLATILE_ONLY);
+            expect(result.isCacheStale).toBe(false);
+            expect(result.isIpAddressStale).toBe(true);
+            expect(result.isUserAgentStale).toBe(true);
+            expect(result.isIpAddressesStale).toBe(true);
+        });
+    });
+    describe('TIER 2: ADDRESS_UPDATE (cache write only, skip Neptune)', () => {
+        it('should return ADDRESS_UPDATE tier when non-IP address is new', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    addresses: [],
+                },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    addresses: [
+                        { city: 'Boston', province: 'MA', s: ADDRESS_INFO_SOURCE.INPUT },
+                    ],
+                },
+            };
+            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
+            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.ADDRESS_UPDATE);
+            expect(result.isCacheStale).toBe(true);
+            expect(result.isNonIpAddressesStale).toBe(true);
+        });
+        it('should return ADDRESS_UPDATE tier when new input address added', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    addresses: [
+                        { city: 'New York', s: ADDRESS_INFO_SOURCE.INPUT },
+                    ],
+                },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    addresses: [
+                        { city: 'New York', s: ADDRESS_INFO_SOURCE.INPUT },
+                        { city: 'Boston', s: ADDRESS_INFO_SOURCE.INPUT },
+                    ],
+                },
+            };
+            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
+            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.ADDRESS_UPDATE);
+            expect(result.isCacheStale).toBe(true);
+            expect(result.isNonIpAddressesStale).toBe(true);
+        });
+        it('should return ADDRESS_UPDATE tier even when volatile traits are also stale', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    ipAddress: '192.168.1.1',
+                    addresses: [],
+                },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    ipAddress: '10.0.0.1',
+                    addresses: [
+                        { city: 'Boston', s: ADDRESS_INFO_SOURCE.INPUT },
+                    ],
+                },
+            };
+            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
+            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.ADDRESS_UPDATE);
+            expect(result.isCacheStale).toBe(true);
+            expect(result.isIpAddressStale).toBe(true);
+            expect(result.isNonIpAddressesStale).toBe(true);
+        });
+    });
+    describe('TIER 3: IDENTITY_STALE (full Neptune resolution)', () => {
+        it('should return IDENTITY_STALE tier when email is new', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['old@email.com'],
+                },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['old@email.com', 'new@email.com'],
+                },
+            };
+            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
+            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.IDENTITY_STALE);
+            expect(result.isCacheStale).toBe(true);
+            expect(result.isEmailsStale).toBe(true);
+        });
+        it('should return IDENTITY_STALE tier when identityId changes', () => {
+            const cachedIdentity = {
+                identityId: 'old-id',
+                traits: { emails: ['test@email.com'] },
+            };
+            const incomingIdentity = {
+                identityId: 'new-id',
+                traits: { emails: ['test@email.com'] },
+            };
+            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
+            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.IDENTITY_STALE);
+            expect(result.isCacheStale).toBe(true);
+            expect(result.isIdentityIdStale).toBe(true);
+        });
+        it('should return IDENTITY_STALE tier when phone is new', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: { phones: ['+1234567890'] },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: { phones: ['+1234567890', '+9876543210'] },
+            };
+            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
+            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.IDENTITY_STALE);
+            expect(result.isCacheStale).toBe(true);
+            expect(result.isPhonesStale).toBe(true);
+        });
+        it('should return IDENTITY_STALE tier when click info changes', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    click: { gclid: 'old_gclid' },
+                },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    click: { gclid: 'new_gclid' },
+                },
+            };
+            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
+            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.IDENTITY_STALE);
+            expect(result.isCacheStale).toBe(true);
+            expect(result.isClickInfosStale).toBe(true);
+        });
+        it('should return IDENTITY_STALE tier when identity trait is stale even with ADDRESS_UPDATE', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['old@email.com'],
+                    addresses: [],
+                },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['old@email.com', 'new@email.com'],
+                    addresses: [
+                        { city: 'Boston', s: ADDRESS_INFO_SOURCE.INPUT },
+                    ],
+                },
+            };
+            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
+            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.IDENTITY_STALE);
+            expect(result.isCacheStale).toBe(true);
+            expect(result.isEmailsStale).toBe(true);
+            expect(result.isNonIpAddressesStale).toBe(true);
+        });
+        it('should return IDENTITY_STALE tier when identity trait is stale even with VOLATILE_ONLY', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['old@email.com'],
+                    ipAddress: '192.168.1.1',
+                },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['old@email.com', 'new@email.com'],
+                    ipAddress: '10.0.0.1',
+                },
+            };
+            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
+            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.IDENTITY_STALE);
+            expect(result.isCacheStale).toBe(true);
+            expect(result.isEmailsStale).toBe(true);
+            expect(result.isIpAddressStale).toBe(true);
+        });
+    });
+    describe('TIER NONE: No staleness', () => {
+        it('should return NONE tier when nothing is stale', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    phones: ['+1234567890'],
+                    ipAddress: '192.168.1.1',
+                },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    phones: ['+1234567890'],
+                    ipAddress: '192.168.1.1',
+                },
+            };
+            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
+            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.NONE);
+            expect(result.isCacheStale).toBe(false);
+        });
+        it('should return NONE tier when incoming is subset of cached', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['a@email.com', 'b@email.com'],
+                    phones: ['+1234567890', '+9876543210'],
+                },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['a@email.com'],
+                },
+            };
+            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
+            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.NONE);
+            expect(result.isCacheStale).toBe(false);
+        });
+    });
+    describe('Address source filtering', () => {
+        it('should correctly identify IP-sourced addresses', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    addresses: [
+                        { city: 'CachedCity', s: ADDRESS_INFO_SOURCE.IP_ADDRESS },
+                    ],
+                },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    addresses: [
+                        { city: 'NewCity', s: ADDRESS_INFO_SOURCE.IP_ADDRESS },
+                    ],
+                },
+            };
+            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
+            expect(result.isIpAddressesStale).toBe(true);
+            expect(result.isNonIpAddressesStale).toBe(false);
+            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.VOLATILE_ONLY);
+        });
+        it('should correctly identify INPUT-sourced addresses', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    addresses: [
+                        { city: 'CachedCity', s: ADDRESS_INFO_SOURCE.INPUT },
+                    ],
+                },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    addresses: [
+                        { city: 'CachedCity', s: ADDRESS_INFO_SOURCE.INPUT },
+                        { city: 'NewCity', s: ADDRESS_INFO_SOURCE.INPUT },
+                    ],
+                },
+            };
+            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
+            expect(result.isIpAddressesStale).toBe(false);
+            expect(result.isNonIpAddressesStale).toBe(true);
+            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.ADDRESS_UPDATE);
+        });
+        it('should handle mixed address sources correctly', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    addresses: [
+                        { city: 'IPCity', s: ADDRESS_INFO_SOURCE.IP_ADDRESS },
+                        { city: 'InputCity', s: ADDRESS_INFO_SOURCE.INPUT },
+                    ],
+                },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    addresses: [
+                        { city: 'NewIPCity', s: ADDRESS_INFO_SOURCE.IP_ADDRESS },
+                        { city: 'InputCity', s: ADDRESS_INFO_SOURCE.INPUT },
+                        { city: 'NewInputCity', s: ADDRESS_INFO_SOURCE.INPUT },
+                    ],
+                },
+            };
+            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
+            expect(result.isIpAddressesStale).toBe(true);
+            expect(result.isNonIpAddressesStale).toBe(true);
+            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.ADDRESS_UPDATE);
+            expect(result.isCacheStale).toBe(true);
+        });
+        it('should handle addresses without source field (default to IP based on PII)', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    addresses: [],
+                },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    addresses: [
+                        { city: 'NoSourceCity' },
+                    ],
+                },
+            };
+            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
+            expect(result.isIpAddressesStale).toBe(true);
+            expect(result.isNonIpAddressesStale).toBe(false);
+            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.VOLATILE_ONLY);
+            expect(result.isCacheStale).toBe(false);
+        });
+        it('should treat addresses without source but with PII as non-IP', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    addresses: [],
+                },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    addresses: [
+                        { city: 'InputCity', firstName: 'John' },
+                    ],
+                },
+            };
+            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
+            expect(result.isNonIpAddressesStale).toBe(true);
+            expect(result.isIpAddressesStale).toBe(false);
+            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.ADDRESS_UPDATE);
+            expect(result.isCacheStale).toBe(true);
+        });
+    });
+    describe('Backward compatibility', () => {
+        it('should maintain isAddressesStale for any address change', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    addresses: [
+                        { city: 'OldCity', s: ADDRESS_INFO_SOURCE.IP_ADDRESS },
+                    ],
+                },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    addresses: [
+                        { city: 'NewCity', s: ADDRESS_INFO_SOURCE.IP_ADDRESS },
+                    ],
+                },
+            };
+            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
+            expect(result.isAddressesStale).toBe(true);
+            expect(result.isCacheStale).toBe(false);
+        });
+    });
+});
 //# sourceMappingURL=trait-merging-and-staleness.spec.js.map