@adtrackify/at-service-common 5.0.0 → 5.0.2

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

@@ -1,1769 +1,1769 @@
-import { ADDRESS_INFO_SOURCE } from '@adtrackify/at-tracking-event-types';
-import { mergeIdentityTraits, isIdentityCacheStale, isClickInfosStale, IDENTITY_CACHE_STALENESS_TIER, extractStaleTraitNames, mergeAndComputeIdentityStaleness, } from '@adtrackify/at-shared-utils';
-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);
-        });
-    });
-});
-describe('extractStaleTraitNames function', () => {
-    it('should return empty array when nothing is stale', () => {
-        const cachedIdentity = {
-            identityId: 'test-id',
-            traits: { emails: ['test@email.com'] },
-        };
-        const incomingIdentity = {
-            identityId: 'test-id',
-            traits: { emails: ['test@email.com'] },
-        };
-        const tracker = isIdentityCacheStale(cachedIdentity, incomingIdentity);
-        const staleTraits = extractStaleTraitNames(tracker);
-        expect(staleTraits).toEqual([]);
-    });
-    it('should return identity-defining trait names when stale', () => {
-        const cachedIdentity = {
-            identityId: 'test-id',
-            traits: { emails: ['old@email.com'] },
-        };
-        const incomingIdentity = {
-            identityId: 'test-id',
-            traits: { emails: ['old@email.com', 'new@email.com'] },
-        };
-        const tracker = isIdentityCacheStale(cachedIdentity, incomingIdentity);
-        const staleTraits = extractStaleTraitNames(tracker);
-        expect(staleTraits).toContain('emails');
-    });
-    it('should return multiple stale trait names', () => {
-        const cachedIdentity = {
-            identityId: 'test-id',
-            traits: {
-                emails: ['old@email.com'],
-                phones: ['+1234567890'],
-            },
-        };
-        const incomingIdentity = {
-            identityId: 'test-id',
-            traits: {
-                emails: ['old@email.com', 'new@email.com'],
-                phones: ['+1234567890', '+9876543210'],
-            },
-        };
-        const tracker = isIdentityCacheStale(cachedIdentity, incomingIdentity);
-        const staleTraits = extractStaleTraitNames(tracker);
-        expect(staleTraits).toContain('emails');
-        expect(staleTraits).toContain('phones');
-    });
-    it('should return volatile trait names when stale', () => {
-        const cachedIdentity = {
-            identityId: 'test-id',
-            traits: {
-                ipAddress: '192.168.1.1',
-                userAgent: 'old-agent',
-            },
-        };
-        const incomingIdentity = {
-            identityId: 'test-id',
-            traits: {
-                ipAddress: '10.0.0.1',
-                userAgent: 'new-agent',
-            },
-        };
-        const tracker = isIdentityCacheStale(cachedIdentity, incomingIdentity);
-        const staleTraits = extractStaleTraitNames(tracker);
-        expect(staleTraits).toContain('ipAddress');
-        expect(staleTraits).toContain('userAgent');
-    });
-});
-describe('mergeAndComputeIdentityStaleness function', () => {
-    describe('NONE tier - cache is fresh', () => {
-        it('should return NONE tier when incoming is subset of cached', () => {
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: { emails: ['shared@email.com'] },
-            };
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['shared@email.com', 'other@email.com'],
-                    phones: ['+1234567890'],
-                },
-            };
-            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
-            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.NONE);
-            expect(result.isCacheStale).toBe(false);
-            expect(result.staleTraits).toEqual([]);
-            expect(result.mergedIdentity.traits?.emails).toEqual(['shared@email.com', 'other@email.com']);
-            expect(result.mergedIdentity.traits?.phones).toEqual(['+1234567890']);
-        });
-        it('should return NONE tier when identities are identical', () => {
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    phones: ['+1234567890'],
-                },
-            };
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    phones: ['+1234567890'],
-                },
-            };
-            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
-            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.NONE);
-            expect(result.isCacheStale).toBe(false);
-            expect(result.staleTraits).toEqual([]);
-        });
-        it('should return NONE tier with identical click info', () => {
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    click: { gclid: 'same_gclid', fbp: 'fb.1.123.456' },
-                },
-            };
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    click: { gclid: 'same_gclid', fbp: 'fb.1.123.456' },
-                },
-            };
-            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
-            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.NONE);
-            expect(result.isCacheStale).toBe(false);
-        });
-    });
-    describe('VOLATILE_ONLY tier - treat as cache hit', () => {
-        it('should return VOLATILE_ONLY tier when only ipAddress is new', () => {
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    ipAddress: '10.0.0.1',
-                },
-            };
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                },
-            };
-            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
-            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.VOLATILE_ONLY);
-            expect(result.isCacheStale).toBe(false);
-            expect(result.staleTraits).toContain('ipAddress');
-        });
-        it('should return VOLATILE_ONLY tier when only userAgent is new', () => {
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    userAgent: 'new-agent',
-                },
-            };
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                },
-            };
-            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
-            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.VOLATILE_ONLY);
-            expect(result.isCacheStale).toBe(false);
-            expect(result.staleTraits).toContain('userAgent');
-        });
-        it('should return VOLATILE_ONLY tier when only IP-sourced address is new', () => {
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    addresses: [{ city: 'NewIPCity', s: ADDRESS_INFO_SOURCE.IP_ADDRESS }],
-                },
-            };
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    addresses: [],
-                },
-            };
-            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
-            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.VOLATILE_ONLY);
-            expect(result.isCacheStale).toBe(false);
-        });
-    });
-    describe('ADDRESS_UPDATE tier - cache write only, skip Neptune', () => {
-        it('should return ADDRESS_UPDATE tier when non-IP address is new', () => {
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    addresses: [{ city: 'Boston', s: ADDRESS_INFO_SOURCE.INPUT }],
-                },
-            };
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    addresses: [],
-                },
-            };
-            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
-            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.ADDRESS_UPDATE);
-            expect(result.isCacheStale).toBe(true);
-            expect(result.staleTraits).toContain('addresses');
-        });
-        it('should return ADDRESS_UPDATE even with volatile traits stale', () => {
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    ipAddress: '10.0.0.1',
-                    addresses: [{ city: 'Boston', s: ADDRESS_INFO_SOURCE.INPUT }],
-                },
-            };
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    ipAddress: '192.168.1.1',
-                    addresses: [],
-                },
-            };
-            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
-            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.ADDRESS_UPDATE);
-            expect(result.isCacheStale).toBe(true);
-        });
-    });
-    describe('IDENTITY_STALE tier - full Neptune resolution', () => {
-        it('should return IDENTITY_STALE tier when email is new', () => {
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: { emails: ['old@email.com', 'new@email.com'] },
-            };
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: { emails: ['old@email.com'] },
-            };
-            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
-            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.IDENTITY_STALE);
-            expect(result.isCacheStale).toBe(true);
-            expect(result.staleTraits).toContain('emails');
-        });
-        it('should return IDENTITY_STALE tier when phone is new', () => {
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: { phones: ['+1234567890', '+9876543210'] },
-            };
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: { phones: ['+1234567890'] },
-            };
-            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
-            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.IDENTITY_STALE);
-            expect(result.isCacheStale).toBe(true);
-            expect(result.staleTraits).toContain('phones');
-        });
-        it('should return IDENTITY_STALE tier when identityId changes', () => {
-            const incomingIdentity = {
-                identityId: 'new-id',
-                traits: { emails: ['test@email.com'] },
-            };
-            const cachedIdentity = {
-                identityId: 'old-id',
-                traits: { emails: ['test@email.com'] },
-            };
-            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
-            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.IDENTITY_STALE);
-            expect(result.isCacheStale).toBe(true);
-            expect(result.staleTraits).toContain('identityId');
-        });
-        it('should return IDENTITY_STALE tier when click info is new', () => {
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: { click: { gclid: 'new_gclid' } },
-            };
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {},
-            };
-            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
-            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.IDENTITY_STALE);
-            expect(result.isCacheStale).toBe(true);
-            expect(result.staleTraits).toContain('clickInfos');
-        });
-        it('should return IDENTITY_STALE even with ADDRESS_UPDATE also present', () => {
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['old@email.com', 'new@email.com'],
-                    addresses: [{ city: 'Boston', s: ADDRESS_INFO_SOURCE.INPUT }],
-                },
-            };
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['old@email.com'],
-                    addresses: [],
-                },
-            };
-            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
-            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.IDENTITY_STALE);
-            expect(result.isCacheStale).toBe(true);
-            expect(result.staleTraits).toContain('emails');
-            expect(result.staleTraits).toContain('addresses');
-        });
-    });
-    describe('Merged identity structure', () => {
-        it('should preserve incoming identityId in merged identity', () => {
-            const incomingIdentity = {
-                identityId: 'incoming-id',
-                traits: { emails: ['test@email.com'] },
-            };
-            const cachedIdentity = {
-                identityId: 'cached-id',
-                traits: { phones: ['+1234567890'] },
-            };
-            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
-            expect(result.mergedIdentity.identityId).toBe('incoming-id');
-        });
-        it('should merge traits from both incoming and cached', () => {
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['incoming@email.com'],
-                    userIds: ['user1'],
-                },
-            };
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['cached@email.com'],
-                    phones: ['+1234567890'],
-                },
-            };
-            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
-            expect(result.mergedIdentity.traits?.emails).toContain('incoming@email.com');
-            expect(result.mergedIdentity.traits?.emails).toContain('cached@email.com');
-            expect(result.mergedIdentity.traits?.userIds).toEqual(['user1']);
-            expect(result.mergedIdentity.traits?.phones).toEqual(['+1234567890']);
-        });
-    });
-    describe('staleTracker output', () => {
-        it('should include full staleTracker with all flags', () => {
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['old@email.com', 'new@email.com'],
-                    ipAddress: '10.0.0.1',
-                },
-            };
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['old@email.com'],
-                },
-            };
-            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
-            expect(result.staleTracker).toBeDefined();
-            expect(result.staleTracker.isEmailsStale).toBe(true);
-            expect(result.staleTracker.isIpAddressStale).toBe(true);
-            expect(result.staleTracker.isPhonesStale).toBe(false);
-        });
-    });
-    describe('Edge cases - empty traits', () => {
-        it('should handle empty traits on incoming identity', () => {
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {},
-            };
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['cached@email.com'],
-                    phones: ['+1234567890'],
-                    userIds: ['user1'],
-                },
-            };
-            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
-            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.NONE);
-            expect(result.isCacheStale).toBe(false);
-            expect(result.staleTraits).toEqual([]);
-            expect(result.mergedIdentity.traits?.emails).toEqual(['cached@email.com']);
-            expect(result.mergedIdentity.traits?.phones).toEqual(['+1234567890']);
-            expect(result.mergedIdentity.traits?.userIds).toEqual(['user1']);
-        });
-        it('should handle empty traits on cached identity', () => {
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['new@email.com'],
-                    phones: ['+1234567890'],
-                },
-            };
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {},
-            };
-            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
-            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.IDENTITY_STALE);
-            expect(result.isCacheStale).toBe(true);
-            expect(result.staleTraits).toContain('emails');
-            expect(result.staleTraits).toContain('phones');
-            expect(result.mergedIdentity.traits?.emails).toEqual(['new@email.com']);
-            expect(result.mergedIdentity.traits?.phones).toEqual(['+1234567890']);
-        });
-        it('should handle both identities with empty traits', () => {
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {},
-            };
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {},
-            };
-            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
-            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.NONE);
-            expect(result.isCacheStale).toBe(false);
-            expect(result.staleTraits).toEqual([]);
-        });
-    });
-    describe('Edge cases - null/undefined handling', () => {
-        it('should handle undefined traits on incoming identity', () => {
-            const incomingIdentity = {
-                identityId: 'test-id',
-            };
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['cached@email.com'],
-                },
-            };
-            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
-            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.NONE);
-            expect(result.isCacheStale).toBe(false);
-        });
-        it('should handle undefined traits on cached identity', () => {
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['new@email.com'],
-                },
-            };
-            const cachedIdentity = {
-                identityId: 'test-id',
-            };
-            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
-            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.IDENTITY_STALE);
-            expect(result.isCacheStale).toBe(true);
-            expect(result.staleTraits).toContain('emails');
-        });
-        it('should handle both identities with undefined traits', () => {
-            const incomingIdentity = {
-                identityId: 'test-id',
-            };
-            const cachedIdentity = {
-                identityId: 'test-id',
-            };
-            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
-            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.NONE);
-            expect(result.isCacheStale).toBe(false);
-            expect(result.staleTraits).toEqual([]);
-        });
-        it('should handle null values in array traits gracefully', () => {
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['valid@email.com', null, 'new@email.com'],
-                },
-            };
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['valid@email.com'],
-                },
-            };
-            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
-            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.IDENTITY_STALE);
-            expect(result.isCacheStale).toBe(true);
-        });
-    });
-    describe('Edge cases - click trait merging', () => {
-        it('should detect staleness when incoming has new click info', () => {
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    click: {
-                        gclid: 'new_gclid',
-                        fbp: 'fb.1.new.123',
-                    },
-                },
-            };
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {},
-            };
-            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
-            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.IDENTITY_STALE);
-            expect(result.isCacheStale).toBe(true);
-            expect(result.staleTraits).toContain('clickInfos');
-        });
-        it('should preserve cached click info when merging', () => {
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    click: {
-                        gclid: 'incoming_gclid',
-                    },
-                },
-            };
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    click: {
-                        gclid: 'cached_gclid',
-                        fbp: 'fb.1.cached.456',
-                    },
-                },
-            };
-            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
-            expect(result.mergedIdentity.traits?.click?.gclid).toBe('cached_gclid');
-            expect(result.mergedIdentity.traits?.click?.fbp).toBe('fb.1.cached.456');
-        });
-        it('should not be stale when click timestamps differ but values are same', () => {
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    click: {
-                        fbp: 'fb.1.same.123',
-                        fbpCollectedAt: '2024-06-01T00:00:00Z',
-                    },
-                },
-            };
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    click: {
-                        fbp: 'fb.1.same.123',
-                        fbpCollectedAt: '2024-01-01T00:00:00Z',
-                    },
-                },
-            };
-            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
-            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.NONE);
-            expect(result.isCacheStale).toBe(false);
-        });
-        it('should detect staleness when fbc changes (incoming has new fbc, cached has none)', () => {
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    click: {
-                        fbc: 'fb.1.1234.new_fbclid',
-                    },
-                },
-            };
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    click: {},
-                },
-            };
-            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
-            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.IDENTITY_STALE);
-            expect(result.isCacheStale).toBe(true);
-            expect(result.staleTraits).toContain('clickInfos');
-        });
-    });
-    describe('staleTraits extraction comprehensive tests', () => {
-        it('should return empty array when NONE tier', () => {
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: { emails: ['test@email.com'] },
-            };
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: { emails: ['test@email.com', 'other@email.com'] },
-            };
-            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
-            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.NONE);
-            expect(result.staleTraits).toEqual([]);
-        });
-        it('should return volatile trait names for VOLATILE_ONLY tier', () => {
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    ipAddress: '10.0.0.1',
-                    userAgent: 'new-agent',
-                },
-            };
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                },
-            };
-            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
-            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.VOLATILE_ONLY);
-            expect(result.staleTraits).toContain('ipAddress');
-            expect(result.staleTraits).toContain('userAgent');
-            expect(result.staleTraits).not.toContain('emails');
-        });
-        it('should return address trait name for ADDRESS_UPDATE tier', () => {
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    addresses: [{ city: 'Boston', s: ADDRESS_INFO_SOURCE.INPUT }],
-                },
-            };
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    addresses: [],
-                },
-            };
-            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
-            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.ADDRESS_UPDATE);
-            expect(result.staleTraits).toContain('addresses');
-        });
-        it('should return all stale identity trait names for IDENTITY_STALE tier', () => {
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['old@email.com', 'new@email.com'],
-                    phones: ['+1234567890', '+9876543210'],
-                    userIds: ['user1', 'user2'],
-                },
-            };
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['old@email.com'],
-                    phones: ['+1234567890'],
-                    userIds: ['user1'],
-                },
-            };
-            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
-            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.IDENTITY_STALE);
-            expect(result.staleTraits).toContain('emails');
-            expect(result.staleTraits).toContain('phones');
-            expect(result.staleTraits).toContain('userIds');
-        });
-    });
-    describe('Merge behavior verification', () => {
-        it('should merge incoming and cached array traits (emails, phones, userIds)', () => {
-            const incomingIdentity = {
-                identityId: 'incoming-id',
-                traits: {
-                    emails: ['incoming@email.com', 'shared@email.com'],
-                    userIds: ['incominguser'],
-                },
-            };
-            const cachedIdentity = {
-                identityId: 'cached-id',
-                traits: {
-                    emails: ['cached@email.com', 'shared@email.com'],
-                    phones: ['+1234567890'],
-                    userIds: ['cacheduser'],
-                },
-            };
-            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
-            expect(result.mergedIdentity.traits?.emails).toContain('incoming@email.com');
-            expect(result.mergedIdentity.traits?.emails).toContain('cached@email.com');
-            expect(result.mergedIdentity.traits?.emails).toContain('shared@email.com');
-            expect(result.mergedIdentity.traits?.phones).toEqual(['+1234567890']);
-            expect(result.mergedIdentity.traits?.userIds).toContain('incominguser');
-            expect(result.mergedIdentity.traits?.userIds).toContain('cacheduser');
-        });
-        it('should preserve identityId from incoming identity', () => {
-            const incomingIdentity = {
-                identityId: 'incoming-id-123',
-                traits: { emails: ['test@email.com'] },
-            };
-            const cachedIdentity = {
-                identityId: 'cached-id-456',
-                traits: { phones: ['+1234567890'] },
-            };
-            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
-            expect(result.mergedIdentity.identityId).toBe('incoming-id-123');
-        });
-        it('should merge addresses from both identities', () => {
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    addresses: [
-                        { city: 'IncomingCity', s: ADDRESS_INFO_SOURCE.INPUT },
-                    ],
-                },
-            };
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    addresses: [
-                        { city: 'CachedCity', s: ADDRESS_INFO_SOURCE.INPUT },
-                    ],
-                },
-            };
-            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
-            expect(result.mergedIdentity.traits?.addresses).toHaveLength(2);
-            expect(result.mergedIdentity.traits?.addresses).toEqual(expect.arrayContaining([
-                expect.objectContaining({ city: 'IncomingCity' }),
-                expect.objectContaining({ city: 'CachedCity' }),
-            ]));
-        });
-    });
-});
+import { ADDRESS_INFO_SOURCE } from '@adtrackify/at-tracking-event-types';
+import { mergeIdentityTraits, isIdentityCacheStale, isClickInfosStale, IDENTITY_CACHE_STALENESS_TIER, extractStaleTraitNames, mergeAndComputeIdentityStaleness, } from '@adtrackify/at-shared-utils';
+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);
+        });
+    });
+});
+describe('extractStaleTraitNames function', () => {
+    it('should return empty array when nothing is stale', () => {
+        const cachedIdentity = {
+            identityId: 'test-id',
+            traits: { emails: ['test@email.com'] },
+        };
+        const incomingIdentity = {
+            identityId: 'test-id',
+            traits: { emails: ['test@email.com'] },
+        };
+        const tracker = isIdentityCacheStale(cachedIdentity, incomingIdentity);
+        const staleTraits = extractStaleTraitNames(tracker);
+        expect(staleTraits).toEqual([]);
+    });
+    it('should return identity-defining trait names when stale', () => {
+        const cachedIdentity = {
+            identityId: 'test-id',
+            traits: { emails: ['old@email.com'] },
+        };
+        const incomingIdentity = {
+            identityId: 'test-id',
+            traits: { emails: ['old@email.com', 'new@email.com'] },
+        };
+        const tracker = isIdentityCacheStale(cachedIdentity, incomingIdentity);
+        const staleTraits = extractStaleTraitNames(tracker);
+        expect(staleTraits).toContain('emails');
+    });
+    it('should return multiple stale trait names', () => {
+        const cachedIdentity = {
+            identityId: 'test-id',
+            traits: {
+                emails: ['old@email.com'],
+                phones: ['+1234567890'],
+            },
+        };
+        const incomingIdentity = {
+            identityId: 'test-id',
+            traits: {
+                emails: ['old@email.com', 'new@email.com'],
+                phones: ['+1234567890', '+9876543210'],
+            },
+        };
+        const tracker = isIdentityCacheStale(cachedIdentity, incomingIdentity);
+        const staleTraits = extractStaleTraitNames(tracker);
+        expect(staleTraits).toContain('emails');
+        expect(staleTraits).toContain('phones');
+    });
+    it('should return volatile trait names when stale', () => {
+        const cachedIdentity = {
+            identityId: 'test-id',
+            traits: {
+                ipAddress: '192.168.1.1',
+                userAgent: 'old-agent',
+            },
+        };
+        const incomingIdentity = {
+            identityId: 'test-id',
+            traits: {
+                ipAddress: '10.0.0.1',
+                userAgent: 'new-agent',
+            },
+        };
+        const tracker = isIdentityCacheStale(cachedIdentity, incomingIdentity);
+        const staleTraits = extractStaleTraitNames(tracker);
+        expect(staleTraits).toContain('ipAddress');
+        expect(staleTraits).toContain('userAgent');
+    });
+});
+describe('mergeAndComputeIdentityStaleness function', () => {
+    describe('NONE tier - cache is fresh', () => {
+        it('should return NONE tier when incoming is subset of cached', () => {
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: { emails: ['shared@email.com'] },
+            };
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['shared@email.com', 'other@email.com'],
+                    phones: ['+1234567890'],
+                },
+            };
+            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
+            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.NONE);
+            expect(result.isCacheStale).toBe(false);
+            expect(result.staleTraits).toEqual([]);
+            expect(result.mergedIdentity.traits?.emails).toEqual(['shared@email.com', 'other@email.com']);
+            expect(result.mergedIdentity.traits?.phones).toEqual(['+1234567890']);
+        });
+        it('should return NONE tier when identities are identical', () => {
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    phones: ['+1234567890'],
+                },
+            };
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    phones: ['+1234567890'],
+                },
+            };
+            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
+            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.NONE);
+            expect(result.isCacheStale).toBe(false);
+            expect(result.staleTraits).toEqual([]);
+        });
+        it('should return NONE tier with identical click info', () => {
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    click: { gclid: 'same_gclid', fbp: 'fb.1.123.456' },
+                },
+            };
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    click: { gclid: 'same_gclid', fbp: 'fb.1.123.456' },
+                },
+            };
+            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
+            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.NONE);
+            expect(result.isCacheStale).toBe(false);
+        });
+    });
+    describe('VOLATILE_ONLY tier - treat as cache hit', () => {
+        it('should return VOLATILE_ONLY tier when only ipAddress is new', () => {
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    ipAddress: '10.0.0.1',
+                },
+            };
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                },
+            };
+            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
+            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.VOLATILE_ONLY);
+            expect(result.isCacheStale).toBe(false);
+            expect(result.staleTraits).toContain('ipAddress');
+        });
+        it('should return VOLATILE_ONLY tier when only userAgent is new', () => {
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    userAgent: 'new-agent',
+                },
+            };
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                },
+            };
+            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
+            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.VOLATILE_ONLY);
+            expect(result.isCacheStale).toBe(false);
+            expect(result.staleTraits).toContain('userAgent');
+        });
+        it('should return VOLATILE_ONLY tier when only IP-sourced address is new', () => {
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    addresses: [{ city: 'NewIPCity', s: ADDRESS_INFO_SOURCE.IP_ADDRESS }],
+                },
+            };
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    addresses: [],
+                },
+            };
+            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
+            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.VOLATILE_ONLY);
+            expect(result.isCacheStale).toBe(false);
+        });
+    });
+    describe('ADDRESS_UPDATE tier - cache write only, skip Neptune', () => {
+        it('should return ADDRESS_UPDATE tier when non-IP address is new', () => {
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    addresses: [{ city: 'Boston', s: ADDRESS_INFO_SOURCE.INPUT }],
+                },
+            };
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    addresses: [],
+                },
+            };
+            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
+            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.ADDRESS_UPDATE);
+            expect(result.isCacheStale).toBe(true);
+            expect(result.staleTraits).toContain('addresses');
+        });
+        it('should return ADDRESS_UPDATE even with volatile traits stale', () => {
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    ipAddress: '10.0.0.1',
+                    addresses: [{ city: 'Boston', s: ADDRESS_INFO_SOURCE.INPUT }],
+                },
+            };
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    ipAddress: '192.168.1.1',
+                    addresses: [],
+                },
+            };
+            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
+            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.ADDRESS_UPDATE);
+            expect(result.isCacheStale).toBe(true);
+        });
+    });
+    describe('IDENTITY_STALE tier - full Neptune resolution', () => {
+        it('should return IDENTITY_STALE tier when email is new', () => {
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: { emails: ['old@email.com', 'new@email.com'] },
+            };
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: { emails: ['old@email.com'] },
+            };
+            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
+            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.IDENTITY_STALE);
+            expect(result.isCacheStale).toBe(true);
+            expect(result.staleTraits).toContain('emails');
+        });
+        it('should return IDENTITY_STALE tier when phone is new', () => {
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: { phones: ['+1234567890', '+9876543210'] },
+            };
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: { phones: ['+1234567890'] },
+            };
+            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
+            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.IDENTITY_STALE);
+            expect(result.isCacheStale).toBe(true);
+            expect(result.staleTraits).toContain('phones');
+        });
+        it('should return IDENTITY_STALE tier when identityId changes', () => {
+            const incomingIdentity = {
+                identityId: 'new-id',
+                traits: { emails: ['test@email.com'] },
+            };
+            const cachedIdentity = {
+                identityId: 'old-id',
+                traits: { emails: ['test@email.com'] },
+            };
+            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
+            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.IDENTITY_STALE);
+            expect(result.isCacheStale).toBe(true);
+            expect(result.staleTraits).toContain('identityId');
+        });
+        it('should return IDENTITY_STALE tier when click info is new', () => {
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: { click: { gclid: 'new_gclid' } },
+            };
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {},
+            };
+            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
+            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.IDENTITY_STALE);
+            expect(result.isCacheStale).toBe(true);
+            expect(result.staleTraits).toContain('clickInfos');
+        });
+        it('should return IDENTITY_STALE even with ADDRESS_UPDATE also present', () => {
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['old@email.com', 'new@email.com'],
+                    addresses: [{ city: 'Boston', s: ADDRESS_INFO_SOURCE.INPUT }],
+                },
+            };
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['old@email.com'],
+                    addresses: [],
+                },
+            };
+            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
+            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.IDENTITY_STALE);
+            expect(result.isCacheStale).toBe(true);
+            expect(result.staleTraits).toContain('emails');
+            expect(result.staleTraits).toContain('addresses');
+        });
+    });
+    describe('Merged identity structure', () => {
+        it('should preserve incoming identityId in merged identity', () => {
+            const incomingIdentity = {
+                identityId: 'incoming-id',
+                traits: { emails: ['test@email.com'] },
+            };
+            const cachedIdentity = {
+                identityId: 'cached-id',
+                traits: { phones: ['+1234567890'] },
+            };
+            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
+            expect(result.mergedIdentity.identityId).toBe('incoming-id');
+        });
+        it('should merge traits from both incoming and cached', () => {
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['incoming@email.com'],
+                    userIds: ['user1'],
+                },
+            };
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['cached@email.com'],
+                    phones: ['+1234567890'],
+                },
+            };
+            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
+            expect(result.mergedIdentity.traits?.emails).toContain('incoming@email.com');
+            expect(result.mergedIdentity.traits?.emails).toContain('cached@email.com');
+            expect(result.mergedIdentity.traits?.userIds).toEqual(['user1']);
+            expect(result.mergedIdentity.traits?.phones).toEqual(['+1234567890']);
+        });
+    });
+    describe('staleTracker output', () => {
+        it('should include full staleTracker with all flags', () => {
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['old@email.com', 'new@email.com'],
+                    ipAddress: '10.0.0.1',
+                },
+            };
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['old@email.com'],
+                },
+            };
+            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
+            expect(result.staleTracker).toBeDefined();
+            expect(result.staleTracker.isEmailsStale).toBe(true);
+            expect(result.staleTracker.isIpAddressStale).toBe(true);
+            expect(result.staleTracker.isPhonesStale).toBe(false);
+        });
+    });
+    describe('Edge cases - empty traits', () => {
+        it('should handle empty traits on incoming identity', () => {
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {},
+            };
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['cached@email.com'],
+                    phones: ['+1234567890'],
+                    userIds: ['user1'],
+                },
+            };
+            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
+            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.NONE);
+            expect(result.isCacheStale).toBe(false);
+            expect(result.staleTraits).toEqual([]);
+            expect(result.mergedIdentity.traits?.emails).toEqual(['cached@email.com']);
+            expect(result.mergedIdentity.traits?.phones).toEqual(['+1234567890']);
+            expect(result.mergedIdentity.traits?.userIds).toEqual(['user1']);
+        });
+        it('should handle empty traits on cached identity', () => {
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['new@email.com'],
+                    phones: ['+1234567890'],
+                },
+            };
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {},
+            };
+            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
+            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.IDENTITY_STALE);
+            expect(result.isCacheStale).toBe(true);
+            expect(result.staleTraits).toContain('emails');
+            expect(result.staleTraits).toContain('phones');
+            expect(result.mergedIdentity.traits?.emails).toEqual(['new@email.com']);
+            expect(result.mergedIdentity.traits?.phones).toEqual(['+1234567890']);
+        });
+        it('should handle both identities with empty traits', () => {
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {},
+            };
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {},
+            };
+            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
+            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.NONE);
+            expect(result.isCacheStale).toBe(false);
+            expect(result.staleTraits).toEqual([]);
+        });
+    });
+    describe('Edge cases - null/undefined handling', () => {
+        it('should handle undefined traits on incoming identity', () => {
+            const incomingIdentity = {
+                identityId: 'test-id',
+            };
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['cached@email.com'],
+                },
+            };
+            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
+            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.NONE);
+            expect(result.isCacheStale).toBe(false);
+        });
+        it('should handle undefined traits on cached identity', () => {
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['new@email.com'],
+                },
+            };
+            const cachedIdentity = {
+                identityId: 'test-id',
+            };
+            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
+            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.IDENTITY_STALE);
+            expect(result.isCacheStale).toBe(true);
+            expect(result.staleTraits).toContain('emails');
+        });
+        it('should handle both identities with undefined traits', () => {
+            const incomingIdentity = {
+                identityId: 'test-id',
+            };
+            const cachedIdentity = {
+                identityId: 'test-id',
+            };
+            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
+            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.NONE);
+            expect(result.isCacheStale).toBe(false);
+            expect(result.staleTraits).toEqual([]);
+        });
+        it('should handle null values in array traits gracefully', () => {
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['valid@email.com', null, 'new@email.com'],
+                },
+            };
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['valid@email.com'],
+                },
+            };
+            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
+            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.IDENTITY_STALE);
+            expect(result.isCacheStale).toBe(true);
+        });
+    });
+    describe('Edge cases - click trait merging', () => {
+        it('should detect staleness when incoming has new click info', () => {
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    click: {
+                        gclid: 'new_gclid',
+                        fbp: 'fb.1.new.123',
+                    },
+                },
+            };
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {},
+            };
+            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
+            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.IDENTITY_STALE);
+            expect(result.isCacheStale).toBe(true);
+            expect(result.staleTraits).toContain('clickInfos');
+        });
+        it('should preserve cached click info when merging', () => {
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    click: {
+                        gclid: 'incoming_gclid',
+                    },
+                },
+            };
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    click: {
+                        gclid: 'cached_gclid',
+                        fbp: 'fb.1.cached.456',
+                    },
+                },
+            };
+            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
+            expect(result.mergedIdentity.traits?.click?.gclid).toBe('cached_gclid');
+            expect(result.mergedIdentity.traits?.click?.fbp).toBe('fb.1.cached.456');
+        });
+        it('should not be stale when click timestamps differ but values are same', () => {
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    click: {
+                        fbp: 'fb.1.same.123',
+                        fbpCollectedAt: '2024-06-01T00:00:00Z',
+                    },
+                },
+            };
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    click: {
+                        fbp: 'fb.1.same.123',
+                        fbpCollectedAt: '2024-01-01T00:00:00Z',
+                    },
+                },
+            };
+            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
+            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.NONE);
+            expect(result.isCacheStale).toBe(false);
+        });
+        it('should detect staleness when fbc changes (incoming has new fbc, cached has none)', () => {
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    click: {
+                        fbc: 'fb.1.1234.new_fbclid',
+                    },
+                },
+            };
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    click: {},
+                },
+            };
+            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
+            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.IDENTITY_STALE);
+            expect(result.isCacheStale).toBe(true);
+            expect(result.staleTraits).toContain('clickInfos');
+        });
+    });
+    describe('staleTraits extraction comprehensive tests', () => {
+        it('should return empty array when NONE tier', () => {
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: { emails: ['test@email.com'] },
+            };
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: { emails: ['test@email.com', 'other@email.com'] },
+            };
+            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
+            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.NONE);
+            expect(result.staleTraits).toEqual([]);
+        });
+        it('should return volatile trait names for VOLATILE_ONLY tier', () => {
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    ipAddress: '10.0.0.1',
+                    userAgent: 'new-agent',
+                },
+            };
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                },
+            };
+            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
+            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.VOLATILE_ONLY);
+            expect(result.staleTraits).toContain('ipAddress');
+            expect(result.staleTraits).toContain('userAgent');
+            expect(result.staleTraits).not.toContain('emails');
+        });
+        it('should return address trait name for ADDRESS_UPDATE tier', () => {
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    addresses: [{ city: 'Boston', s: ADDRESS_INFO_SOURCE.INPUT }],
+                },
+            };
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    addresses: [],
+                },
+            };
+            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
+            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.ADDRESS_UPDATE);
+            expect(result.staleTraits).toContain('addresses');
+        });
+        it('should return all stale identity trait names for IDENTITY_STALE tier', () => {
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['old@email.com', 'new@email.com'],
+                    phones: ['+1234567890', '+9876543210'],
+                    userIds: ['user1', 'user2'],
+                },
+            };
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['old@email.com'],
+                    phones: ['+1234567890'],
+                    userIds: ['user1'],
+                },
+            };
+            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
+            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.IDENTITY_STALE);
+            expect(result.staleTraits).toContain('emails');
+            expect(result.staleTraits).toContain('phones');
+            expect(result.staleTraits).toContain('userIds');
+        });
+    });
+    describe('Merge behavior verification', () => {
+        it('should merge incoming and cached array traits (emails, phones, userIds)', () => {
+            const incomingIdentity = {
+                identityId: 'incoming-id',
+                traits: {
+                    emails: ['incoming@email.com', 'shared@email.com'],
+                    userIds: ['incominguser'],
+                },
+            };
+            const cachedIdentity = {
+                identityId: 'cached-id',
+                traits: {
+                    emails: ['cached@email.com', 'shared@email.com'],
+                    phones: ['+1234567890'],
+                    userIds: ['cacheduser'],
+                },
+            };
+            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
+            expect(result.mergedIdentity.traits?.emails).toContain('incoming@email.com');
+            expect(result.mergedIdentity.traits?.emails).toContain('cached@email.com');
+            expect(result.mergedIdentity.traits?.emails).toContain('shared@email.com');
+            expect(result.mergedIdentity.traits?.phones).toEqual(['+1234567890']);
+            expect(result.mergedIdentity.traits?.userIds).toContain('incominguser');
+            expect(result.mergedIdentity.traits?.userIds).toContain('cacheduser');
+        });
+        it('should preserve identityId from incoming identity', () => {
+            const incomingIdentity = {
+                identityId: 'incoming-id-123',
+                traits: { emails: ['test@email.com'] },
+            };
+            const cachedIdentity = {
+                identityId: 'cached-id-456',
+                traits: { phones: ['+1234567890'] },
+            };
+            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
+            expect(result.mergedIdentity.identityId).toBe('incoming-id-123');
+        });
+        it('should merge addresses from both identities', () => {
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    addresses: [
+                        { city: 'IncomingCity', s: ADDRESS_INFO_SOURCE.INPUT },
+                    ],
+                },
+            };
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    addresses: [
+                        { city: 'CachedCity', s: ADDRESS_INFO_SOURCE.INPUT },
+                    ],
+                },
+            };
+            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
+            expect(result.mergedIdentity.traits?.addresses).toHaveLength(2);
+            expect(result.mergedIdentity.traits?.addresses).toEqual(expect.arrayContaining([
+                expect.objectContaining({ city: 'IncomingCity' }),
+                expect.objectContaining({ city: 'CachedCity' }),
+            ]));
+        });
+    });
+});
 //# sourceMappingURL=trait-merging-and-staleness.spec.js.map