@adtrackify/at-service-common 4.0.4 → 4.0.5

package/dist/esm/__tests__/identity-cache/volatile-traits-optimization.spec.js

@@ -1,817 +1,817 @@
-import { ADDRESS_INFO_SOURCE } from '@adtrackify/at-tracking-event-types';
-import { isIdentityCacheStale, IDENTITY_CACHE_STALENESS_TIER } from '../../helpers/identity-cache-helper';
-describe('Volatile Traits Optimization - Tier Classification', () => {
-    afterEach(() => {
-        jest.resetModules();
-    });
-    describe('TIER: NONE — Cache is fresh', () => {
-        it('should return NONE when cached and incoming are identical', () => {
-            const identity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    phones: ['+1234567890'],
-                    ipAddress: '192.168.1.1',
-                    userAgent: 'Mozilla/5.0',
-                    addresses: [{ city: 'New York', s: ADDRESS_INFO_SOURCE.INPUT }],
-                },
-            };
-            const result = isIdentityCacheStale(identity, identity);
-            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.NONE);
-            expect(result.isCacheStale).toBe(false);
-            expect(result.isIpAddressStale).toBe(false);
-            expect(result.isUserAgentStale).toBe(false);
-            expect(result.isEmailsStale).toBe(false);
-            expect(result.isAddressesStale).toBe(false);
-        });
-        it('should return NONE when incoming is subset of cached', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['a@email.com', 'b@email.com'],
-                    phones: ['+1234567890', '+9876543210'],
-                    userIds: ['user1', 'user2'],
-                },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['a@email.com'],
-                    phones: ['+1234567890'],
-                },
-            };
-            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
-            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.NONE);
-            expect(result.isCacheStale).toBe(false);
-        });
-    });
-    describe('TIER: VOLATILE_ONLY — Only session traits changed', () => {
-        it('should return VOLATILE_ONLY 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);
-            expect(result.isUserAgentStale).toBe(false);
-        });
-        it('should return VOLATILE_ONLY when only userAgent is stale', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    userAgent: 'Mozilla/5.0 (Windows NT 10.0)',
-                },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    userAgent: 'Mozilla/5.0 (Macintosh; Intel Mac OS X)',
-                },
-            };
-            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);
-            expect(result.isIpAddressStale).toBe(false);
-        });
-        it('should return VOLATILE_ONLY 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 when ipAddress AND userAgent are both stale', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    ipAddress: '192.168.1.1',
-                    userAgent: 'Mozilla/5.0 (Windows)',
-                },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    ipAddress: '10.0.0.1',
-                    userAgent: 'Mozilla/5.0 (Mac)',
-                },
-            };
-            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);
-        });
-        it('should return VOLATILE_ONLY when ipAddress AND IP-sourced address are both stale', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    ipAddress: '192.168.1.1',
-                    addresses: [{ city: 'Chicago', s: ADDRESS_INFO_SOURCE.IP_ADDRESS }],
-                },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    ipAddress: '10.0.0.1',
-                    addresses: [{ city: 'Denver', 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.isIpAddressesStale).toBe(true);
-        });
-        it('should return VOLATILE_ONLY when all volatile traits are stale but no identity traits', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    ipAddress: '192.168.1.1',
-                    userAgent: 'Mozilla/5.0 (Windows)',
-                    addresses: [{ city: 'Seattle', s: ADDRESS_INFO_SOURCE.IP_ADDRESS }],
-                },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    ipAddress: '172.16.0.1',
-                    userAgent: 'Chrome/120.0',
-                    addresses: [{ city: 'Portland', 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: ADDRESS_UPDATE — Non-IP address changed', () => {
-        it('should return ADDRESS_UPDATE when only 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);
-            expect(result.isIpAddressesStale).toBe(false);
-        });
-        it('should return ADDRESS_UPDATE when non-IP address AND volatile traits are both stale', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    ipAddress: '192.168.1.1',
-                    userAgent: 'Mozilla/5.0',
-                    addresses: [],
-                },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    ipAddress: '10.0.0.1',
-                    userAgent: 'Chrome/120.0',
-                    addresses: [{ city: 'Austin', firstName: 'John', 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);
-            expect(result.isIpAddressStale).toBe(true);
-            expect(result.isUserAgentStale).toBe(true);
-        });
-        it('should return ADDRESS_UPDATE when new input address added to existing addresses', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    addresses: [{ city: 'Miami', s: ADDRESS_INFO_SOURCE.INPUT }],
-                },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    addresses: [
-                        { city: 'Miami', s: ADDRESS_INFO_SOURCE.INPUT },
-                        { city: 'Tampa', 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 when address with PII (no source field) is added', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    addresses: [],
-                },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    addresses: [{ city: 'Dallas', firstName: 'Jane', lastName: 'Doe' }],
-                },
-            };
-            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);
-        });
-    });
-    describe('TIER: IDENTITY_STALE — Identity-defining traits changed', () => {
-        it('should return IDENTITY_STALE when emails are 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 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 when phones are stale', () => {
-            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 when userIds are stale', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: { userIds: ['user1'] },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: { userIds: ['user1', 'user2'] },
-            };
-            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
-            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.IDENTITY_STALE);
-            expect(result.isCacheStale).toBe(true);
-            expect(result.isUserIdsStale).toBe(true);
-        });
-        it('should return IDENTITY_STALE when clickInfos are stale', () => {
-            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 when identityId is stale', () => {
-            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 when emails stale AND volatile traits stale (highest tier wins)', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['old@email.com'],
-                    ipAddress: '192.168.1.1',
-                    userAgent: 'Mozilla/5.0',
-                },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['old@email.com', 'new@email.com'],
-                    ipAddress: '10.0.0.1',
-                    userAgent: 'Chrome/120.0',
-                },
-            };
-            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);
-            expect(result.isUserAgentStale).toBe(true);
-        });
-        it('should return IDENTITY_STALE when emails stale AND non-IP address stale (highest tier wins)', () => {
-            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: 'Phoenix', 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);
-        });
-    });
-});
-describe('Volatile Traits Optimization - Address Source Filtering', () => {
-    afterEach(() => {
-        jest.resetModules();
-    });
-    describe('isAddressIpSourced inference', () => {
-        it('should treat address with s: IP_ADDRESS as IP-sourced', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: { addresses: [] },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    addresses: [{ city: 'Atlanta', 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 treat address with s: INPUT as non-IP-sourced', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: { addresses: [] },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    addresses: [{ city: 'Houston', s: ADDRESS_INFO_SOURCE.INPUT }],
-                },
-            };
-            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);
-        });
-        it('should treat address without s but with firstName/lastName as non-IP (inferred input)', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: { addresses: [] },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    addresses: [{ city: 'San Diego', firstName: 'Alice', lastName: 'Smith' }],
-                },
-            };
-            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);
-        });
-        it('should treat address without s but with email as non-IP (inferred input)', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: { addresses: [] },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    addresses: [{ city: 'Sacramento', email: 'addr@email.com' }],
-                },
-            };
-            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
-            expect(result.isNonIpAddressesStale).toBe(true);
-            expect(result.isIpAddressesStale).toBe(false);
-        });
-        it('should treat address without s but with phone as non-IP (inferred input)', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: { addresses: [] },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    addresses: [{ city: 'San Jose', phone: '+15551234567' }],
-                },
-            };
-            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
-            expect(result.isNonIpAddressesStale).toBe(true);
-            expect(result.isIpAddressesStale).toBe(false);
-        });
-        it('should treat address without s and without PII as IP-sourced (inferred IP)', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: { addresses: [] },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    addresses: [{ city: 'Oakland', country: 'USA', countryCode: 'US' }],
-                },
-            };
-            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);
-        });
-    });
-    describe('filterAddressesBySource behavior', () => {
-        it('should correctly separate IP and non-IP addresses when mixed', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    addresses: [
-                        { city: 'IP City 1', s: ADDRESS_INFO_SOURCE.IP_ADDRESS },
-                        { city: 'Input City 1', s: ADDRESS_INFO_SOURCE.INPUT },
-                    ],
-                },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    addresses: [
-                        { city: 'New IP City', s: ADDRESS_INFO_SOURCE.IP_ADDRESS },
-                        { city: 'Input City 1', s: ADDRESS_INFO_SOURCE.INPUT },
-                        { city: 'New Input City', 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);
-        });
-    });
-    describe('hasNewNonIpAddress detection', () => {
-        it('should detect new input address as stale', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    addresses: [{ city: 'Old City', s: ADDRESS_INFO_SOURCE.INPUT }],
-                },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    addresses: [
-                        { city: 'Old City', s: ADDRESS_INFO_SOURCE.INPUT },
-                        { city: 'New City', s: ADDRESS_INFO_SOURCE.INPUT },
-                    ],
-                },
-            };
-            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
-            expect(result.isNonIpAddressesStale).toBe(true);
-            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.ADDRESS_UPDATE);
-        });
-        it('should NOT mark non-IP stale when only IP address is new', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    addresses: [
-                        { city: 'IP City', s: ADDRESS_INFO_SOURCE.IP_ADDRESS },
-                        { city: 'Input City', s: ADDRESS_INFO_SOURCE.INPUT },
-                    ],
-                },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    addresses: [
-                        { city: 'New IP City', s: ADDRESS_INFO_SOURCE.IP_ADDRESS },
-                        { city: 'Input City', s: ADDRESS_INFO_SOURCE.INPUT },
-                    ],
-                },
-            };
-            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);
-        });
-    });
-    describe('hasNewIpAddress detection', () => {
-        it('should detect new IP address for tracking purposes', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    addresses: [{ city: 'Old IP City', s: ADDRESS_INFO_SOURCE.IP_ADDRESS }],
-                },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    addresses: [{ city: 'New IP City', s: ADDRESS_INFO_SOURCE.IP_ADDRESS }],
-                },
-            };
-            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
-            expect(result.isIpAddressesStale).toBe(true);
-            expect(result.isAddressesStale).toBe(true);
-        });
-    });
-    describe('Empty addresses edge cases', () => {
-        it('should return ADDRESS_UPDATE when cached empty and incoming has non-IP address', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: { addresses: [] },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    addresses: [{ city: 'Memphis', 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 VOLATILE_ONLY when cached empty and incoming has only IP address', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: { addresses: [] },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    addresses: [{ city: 'Detroit', 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 NONE when both cached and incoming have empty addresses', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: { addresses: [] },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: { addresses: [] },
-            };
-            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
-            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.NONE);
-            expect(result.isAddressesStale).toBe(false);
-        });
-    });
-    describe('All addresses have s field explicitly set', () => {
-        it('should correctly identify source when all addresses have explicit s field', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    addresses: [
-                        { city: 'IP1', s: ADDRESS_INFO_SOURCE.IP_ADDRESS },
-                        { city: 'IN1', s: ADDRESS_INFO_SOURCE.INPUT },
-                    ],
-                },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    addresses: [
-                        { city: 'IP1', s: ADDRESS_INFO_SOURCE.IP_ADDRESS },
-                        { city: 'IN1', s: ADDRESS_INFO_SOURCE.INPUT },
-                        { city: 'IP2', s: ADDRESS_INFO_SOURCE.IP_ADDRESS },
-                        { city: 'IN2', 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);
-        });
-    });
-    describe('Mixed addresses: some IP, some input — only input changes', () => {
-        it('should return ADDRESS_UPDATE when only input address changes', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    addresses: [
-                        { city: 'IP City', s: ADDRESS_INFO_SOURCE.IP_ADDRESS },
-                        { city: 'Input City', s: ADDRESS_INFO_SOURCE.INPUT },
-                    ],
-                },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    addresses: [
-                        { city: 'IP City', s: ADDRESS_INFO_SOURCE.IP_ADDRESS },
-                        { city: 'Input City', s: ADDRESS_INFO_SOURCE.INPUT },
-                        { city: 'New Input City', 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);
-        });
-    });
-});
-describe('Volatile Traits Optimization - checkScalarTraitChanged behavior', () => {
-    afterEach(() => {
-        jest.resetModules();
-    });
-    it('should NOT mark stale when incoming is empty/undefined but cached has value', () => {
-        const cachedIdentity = {
-            identityId: 'test-id',
-            traits: {
-                ipAddress: '192.168.1.1',
-                userAgent: 'Mozilla/5.0',
-            },
-        };
-        const incomingIdentity = {
-            identityId: 'test-id',
-            traits: {},
-        };
-        const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
-        expect(result.isIpAddressStale).toBe(false);
-        expect(result.isUserAgentStale).toBe(false);
-        expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.NONE);
-    });
-    it('should mark stale when cached is undefined but incoming has value', () => {
-        const cachedIdentity = {
-            identityId: 'test-id',
-            traits: {},
-        };
-        const incomingIdentity = {
-            identityId: 'test-id',
-            traits: {
-                ipAddress: '192.168.1.1',
-                userAgent: 'Mozilla/5.0',
-            },
-        };
-        const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
-        expect(result.isIpAddressStale).toBe(true);
-        expect(result.isUserAgentStale).toBe(true);
-        expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.VOLATILE_ONLY);
-    });
-    it('should mark stale when both have values but they differ', () => {
-        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.isIpAddressStale).toBe(true);
-    });
-});
-describe('Volatile Traits Optimization - Error Handling', () => {
-    afterEach(() => {
-        jest.resetModules();
-    });
-    it('should return NONE when both identities have same identityId but malformed traits', () => {
-        const result = isIdentityCacheStale({ identityId: 'test', traits: 'not-an-object' }, { identityId: 'test', traits: 123 });
-        expect(result.isCacheStale).toBe(false);
-        expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.NONE);
-    });
-    it('should return IDENTITY_STALE when cached identity is null but incoming has identityId', () => {
-        const result = isIdentityCacheStale(null, { identityId: 'test', traits: {} });
-        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 when cached identity is undefined but incoming has identityId', () => {
-        const result = isIdentityCacheStale(undefined, { identityId: 'test', traits: {} });
-        expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.IDENTITY_STALE);
-        expect(result.isCacheStale).toBe(true);
-        expect(result.isIdentityIdStale).toBe(true);
-    });
-});
-describe('Volatile Traits Optimization - Backward Compatibility', () => {
-    afterEach(() => {
-        jest.resetModules();
-    });
-    it('should maintain isAddressesStale=true when either IP or non-IP addresses are stale', () => {
-        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.isIpAddressesStale).toBe(true);
-        expect(result.isNonIpAddressesStale).toBe(false);
-    });
-    it('should include all stale trait tracker fields', () => {
-        const cachedIdentity = {
-            identityId: 'test-id',
-            traits: {},
-        };
-        const incomingIdentity = {
-            identityId: 'test-id',
-            traits: {},
-        };
-        const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
-        expect(result).toHaveProperty('cachedTraits');
-        expect(result).toHaveProperty('incomingTraits');
-        expect(result).toHaveProperty('isIdentityIdStale');
-        expect(result).toHaveProperty('isUserIdsStale');
-        expect(result).toHaveProperty('isIdsStale');
-        expect(result).toHaveProperty('isEmailsStale');
-        expect(result).toHaveProperty('isPhonesStale');
-        expect(result).toHaveProperty('isShopifyYIdsStale');
-        expect(result).toHaveProperty('isGendersStale');
-        expect(result).toHaveProperty('isDobsStale');
-        expect(result).toHaveProperty('isAddressesStale');
-        expect(result).toHaveProperty('isIpAddressesStale');
-        expect(result).toHaveProperty('isNonIpAddressesStale');
-        expect(result).toHaveProperty('isClickInfosStale');
-        expect(result).toHaveProperty('isIpAddressStale');
-        expect(result).toHaveProperty('isUserAgentStale');
-        expect(result).toHaveProperty('isThirdPartyContactsStale');
-        expect(result).toHaveProperty('isCacheStale');
-        expect(result).toHaveProperty('staleTier');
-    });
-});
+import { ADDRESS_INFO_SOURCE } from '@adtrackify/at-tracking-event-types';
+import { isIdentityCacheStale, IDENTITY_CACHE_STALENESS_TIER } from '../../helpers/identity-cache-helper';
+describe('Volatile Traits Optimization - Tier Classification', () => {
+    afterEach(() => {
+        jest.resetModules();
+    });
+    describe('TIER: NONE — Cache is fresh', () => {
+        it('should return NONE when cached and incoming are identical', () => {
+            const identity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    phones: ['+1234567890'],
+                    ipAddress: '192.168.1.1',
+                    userAgent: 'Mozilla/5.0',
+                    addresses: [{ city: 'New York', s: ADDRESS_INFO_SOURCE.INPUT }],
+                },
+            };
+            const result = isIdentityCacheStale(identity, identity);
+            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.NONE);
+            expect(result.isCacheStale).toBe(false);
+            expect(result.isIpAddressStale).toBe(false);
+            expect(result.isUserAgentStale).toBe(false);
+            expect(result.isEmailsStale).toBe(false);
+            expect(result.isAddressesStale).toBe(false);
+        });
+        it('should return NONE when incoming is subset of cached', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['a@email.com', 'b@email.com'],
+                    phones: ['+1234567890', '+9876543210'],
+                    userIds: ['user1', 'user2'],
+                },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['a@email.com'],
+                    phones: ['+1234567890'],
+                },
+            };
+            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
+            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.NONE);
+            expect(result.isCacheStale).toBe(false);
+        });
+    });
+    describe('TIER: VOLATILE_ONLY — Only session traits changed', () => {
+        it('should return VOLATILE_ONLY 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);
+            expect(result.isUserAgentStale).toBe(false);
+        });
+        it('should return VOLATILE_ONLY when only userAgent is stale', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    userAgent: 'Mozilla/5.0 (Windows NT 10.0)',
+                },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    userAgent: 'Mozilla/5.0 (Macintosh; Intel Mac OS X)',
+                },
+            };
+            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);
+            expect(result.isIpAddressStale).toBe(false);
+        });
+        it('should return VOLATILE_ONLY 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 when ipAddress AND userAgent are both stale', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    ipAddress: '192.168.1.1',
+                    userAgent: 'Mozilla/5.0 (Windows)',
+                },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    ipAddress: '10.0.0.1',
+                    userAgent: 'Mozilla/5.0 (Mac)',
+                },
+            };
+            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);
+        });
+        it('should return VOLATILE_ONLY when ipAddress AND IP-sourced address are both stale', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    ipAddress: '192.168.1.1',
+                    addresses: [{ city: 'Chicago', s: ADDRESS_INFO_SOURCE.IP_ADDRESS }],
+                },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    ipAddress: '10.0.0.1',
+                    addresses: [{ city: 'Denver', 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.isIpAddressesStale).toBe(true);
+        });
+        it('should return VOLATILE_ONLY when all volatile traits are stale but no identity traits', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    ipAddress: '192.168.1.1',
+                    userAgent: 'Mozilla/5.0 (Windows)',
+                    addresses: [{ city: 'Seattle', s: ADDRESS_INFO_SOURCE.IP_ADDRESS }],
+                },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    ipAddress: '172.16.0.1',
+                    userAgent: 'Chrome/120.0',
+                    addresses: [{ city: 'Portland', 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: ADDRESS_UPDATE — Non-IP address changed', () => {
+        it('should return ADDRESS_UPDATE when only 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);
+            expect(result.isIpAddressesStale).toBe(false);
+        });
+        it('should return ADDRESS_UPDATE when non-IP address AND volatile traits are both stale', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    ipAddress: '192.168.1.1',
+                    userAgent: 'Mozilla/5.0',
+                    addresses: [],
+                },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    ipAddress: '10.0.0.1',
+                    userAgent: 'Chrome/120.0',
+                    addresses: [{ city: 'Austin', firstName: 'John', 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);
+            expect(result.isIpAddressStale).toBe(true);
+            expect(result.isUserAgentStale).toBe(true);
+        });
+        it('should return ADDRESS_UPDATE when new input address added to existing addresses', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    addresses: [{ city: 'Miami', s: ADDRESS_INFO_SOURCE.INPUT }],
+                },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    addresses: [
+                        { city: 'Miami', s: ADDRESS_INFO_SOURCE.INPUT },
+                        { city: 'Tampa', 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 when address with PII (no source field) is added', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    addresses: [],
+                },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    addresses: [{ city: 'Dallas', firstName: 'Jane', lastName: 'Doe' }],
+                },
+            };
+            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);
+        });
+    });
+    describe('TIER: IDENTITY_STALE — Identity-defining traits changed', () => {
+        it('should return IDENTITY_STALE when emails are 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 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 when phones are stale', () => {
+            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 when userIds are stale', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: { userIds: ['user1'] },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: { userIds: ['user1', 'user2'] },
+            };
+            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
+            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.IDENTITY_STALE);
+            expect(result.isCacheStale).toBe(true);
+            expect(result.isUserIdsStale).toBe(true);
+        });
+        it('should return IDENTITY_STALE when clickInfos are stale', () => {
+            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 when identityId is stale', () => {
+            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 when emails stale AND volatile traits stale (highest tier wins)', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['old@email.com'],
+                    ipAddress: '192.168.1.1',
+                    userAgent: 'Mozilla/5.0',
+                },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['old@email.com', 'new@email.com'],
+                    ipAddress: '10.0.0.1',
+                    userAgent: 'Chrome/120.0',
+                },
+            };
+            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);
+            expect(result.isUserAgentStale).toBe(true);
+        });
+        it('should return IDENTITY_STALE when emails stale AND non-IP address stale (highest tier wins)', () => {
+            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: 'Phoenix', 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);
+        });
+    });
+});
+describe('Volatile Traits Optimization - Address Source Filtering', () => {
+    afterEach(() => {
+        jest.resetModules();
+    });
+    describe('isAddressIpSourced inference', () => {
+        it('should treat address with s: IP_ADDRESS as IP-sourced', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: { addresses: [] },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    addresses: [{ city: 'Atlanta', 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 treat address with s: INPUT as non-IP-sourced', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: { addresses: [] },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    addresses: [{ city: 'Houston', s: ADDRESS_INFO_SOURCE.INPUT }],
+                },
+            };
+            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);
+        });
+        it('should treat address without s but with firstName/lastName as non-IP (inferred input)', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: { addresses: [] },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    addresses: [{ city: 'San Diego', firstName: 'Alice', lastName: 'Smith' }],
+                },
+            };
+            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);
+        });
+        it('should treat address without s but with email as non-IP (inferred input)', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: { addresses: [] },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    addresses: [{ city: 'Sacramento', email: 'addr@email.com' }],
+                },
+            };
+            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
+            expect(result.isNonIpAddressesStale).toBe(true);
+            expect(result.isIpAddressesStale).toBe(false);
+        });
+        it('should treat address without s but with phone as non-IP (inferred input)', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: { addresses: [] },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    addresses: [{ city: 'San Jose', phone: '+15551234567' }],
+                },
+            };
+            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
+            expect(result.isNonIpAddressesStale).toBe(true);
+            expect(result.isIpAddressesStale).toBe(false);
+        });
+        it('should treat address without s and without PII as IP-sourced (inferred IP)', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: { addresses: [] },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    addresses: [{ city: 'Oakland', country: 'USA', countryCode: 'US' }],
+                },
+            };
+            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);
+        });
+    });
+    describe('filterAddressesBySource behavior', () => {
+        it('should correctly separate IP and non-IP addresses when mixed', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    addresses: [
+                        { city: 'IP City 1', s: ADDRESS_INFO_SOURCE.IP_ADDRESS },
+                        { city: 'Input City 1', s: ADDRESS_INFO_SOURCE.INPUT },
+                    ],
+                },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    addresses: [
+                        { city: 'New IP City', s: ADDRESS_INFO_SOURCE.IP_ADDRESS },
+                        { city: 'Input City 1', s: ADDRESS_INFO_SOURCE.INPUT },
+                        { city: 'New Input City', 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);
+        });
+    });
+    describe('hasNewNonIpAddress detection', () => {
+        it('should detect new input address as stale', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    addresses: [{ city: 'Old City', s: ADDRESS_INFO_SOURCE.INPUT }],
+                },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    addresses: [
+                        { city: 'Old City', s: ADDRESS_INFO_SOURCE.INPUT },
+                        { city: 'New City', s: ADDRESS_INFO_SOURCE.INPUT },
+                    ],
+                },
+            };
+            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
+            expect(result.isNonIpAddressesStale).toBe(true);
+            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.ADDRESS_UPDATE);
+        });
+        it('should NOT mark non-IP stale when only IP address is new', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    addresses: [
+                        { city: 'IP City', s: ADDRESS_INFO_SOURCE.IP_ADDRESS },
+                        { city: 'Input City', s: ADDRESS_INFO_SOURCE.INPUT },
+                    ],
+                },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    addresses: [
+                        { city: 'New IP City', s: ADDRESS_INFO_SOURCE.IP_ADDRESS },
+                        { city: 'Input City', s: ADDRESS_INFO_SOURCE.INPUT },
+                    ],
+                },
+            };
+            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);
+        });
+    });
+    describe('hasNewIpAddress detection', () => {
+        it('should detect new IP address for tracking purposes', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    addresses: [{ city: 'Old IP City', s: ADDRESS_INFO_SOURCE.IP_ADDRESS }],
+                },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    addresses: [{ city: 'New IP City', s: ADDRESS_INFO_SOURCE.IP_ADDRESS }],
+                },
+            };
+            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
+            expect(result.isIpAddressesStale).toBe(true);
+            expect(result.isAddressesStale).toBe(true);
+        });
+    });
+    describe('Empty addresses edge cases', () => {
+        it('should return ADDRESS_UPDATE when cached empty and incoming has non-IP address', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: { addresses: [] },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    addresses: [{ city: 'Memphis', 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 VOLATILE_ONLY when cached empty and incoming has only IP address', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: { addresses: [] },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    addresses: [{ city: 'Detroit', 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 NONE when both cached and incoming have empty addresses', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: { addresses: [] },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: { addresses: [] },
+            };
+            const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
+            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.NONE);
+            expect(result.isAddressesStale).toBe(false);
+        });
+    });
+    describe('All addresses have s field explicitly set', () => {
+        it('should correctly identify source when all addresses have explicit s field', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    addresses: [
+                        { city: 'IP1', s: ADDRESS_INFO_SOURCE.IP_ADDRESS },
+                        { city: 'IN1', s: ADDRESS_INFO_SOURCE.INPUT },
+                    ],
+                },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    addresses: [
+                        { city: 'IP1', s: ADDRESS_INFO_SOURCE.IP_ADDRESS },
+                        { city: 'IN1', s: ADDRESS_INFO_SOURCE.INPUT },
+                        { city: 'IP2', s: ADDRESS_INFO_SOURCE.IP_ADDRESS },
+                        { city: 'IN2', 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);
+        });
+    });
+    describe('Mixed addresses: some IP, some input — only input changes', () => {
+        it('should return ADDRESS_UPDATE when only input address changes', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    addresses: [
+                        { city: 'IP City', s: ADDRESS_INFO_SOURCE.IP_ADDRESS },
+                        { city: 'Input City', s: ADDRESS_INFO_SOURCE.INPUT },
+                    ],
+                },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    addresses: [
+                        { city: 'IP City', s: ADDRESS_INFO_SOURCE.IP_ADDRESS },
+                        { city: 'Input City', s: ADDRESS_INFO_SOURCE.INPUT },
+                        { city: 'New Input City', 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);
+        });
+    });
+});
+describe('Volatile Traits Optimization - checkScalarTraitChanged behavior', () => {
+    afterEach(() => {
+        jest.resetModules();
+    });
+    it('should NOT mark stale when incoming is empty/undefined but cached has value', () => {
+        const cachedIdentity = {
+            identityId: 'test-id',
+            traits: {
+                ipAddress: '192.168.1.1',
+                userAgent: 'Mozilla/5.0',
+            },
+        };
+        const incomingIdentity = {
+            identityId: 'test-id',
+            traits: {},
+        };
+        const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
+        expect(result.isIpAddressStale).toBe(false);
+        expect(result.isUserAgentStale).toBe(false);
+        expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.NONE);
+    });
+    it('should mark stale when cached is undefined but incoming has value', () => {
+        const cachedIdentity = {
+            identityId: 'test-id',
+            traits: {},
+        };
+        const incomingIdentity = {
+            identityId: 'test-id',
+            traits: {
+                ipAddress: '192.168.1.1',
+                userAgent: 'Mozilla/5.0',
+            },
+        };
+        const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
+        expect(result.isIpAddressStale).toBe(true);
+        expect(result.isUserAgentStale).toBe(true);
+        expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.VOLATILE_ONLY);
+    });
+    it('should mark stale when both have values but they differ', () => {
+        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.isIpAddressStale).toBe(true);
+    });
+});
+describe('Volatile Traits Optimization - Error Handling', () => {
+    afterEach(() => {
+        jest.resetModules();
+    });
+    it('should return NONE when both identities have same identityId but malformed traits', () => {
+        const result = isIdentityCacheStale({ identityId: 'test', traits: 'not-an-object' }, { identityId: 'test', traits: 123 });
+        expect(result.isCacheStale).toBe(false);
+        expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.NONE);
+    });
+    it('should return IDENTITY_STALE when cached identity is null but incoming has identityId', () => {
+        const result = isIdentityCacheStale(null, { identityId: 'test', traits: {} });
+        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 when cached identity is undefined but incoming has identityId', () => {
+        const result = isIdentityCacheStale(undefined, { identityId: 'test', traits: {} });
+        expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.IDENTITY_STALE);
+        expect(result.isCacheStale).toBe(true);
+        expect(result.isIdentityIdStale).toBe(true);
+    });
+});
+describe('Volatile Traits Optimization - Backward Compatibility', () => {
+    afterEach(() => {
+        jest.resetModules();
+    });
+    it('should maintain isAddressesStale=true when either IP or non-IP addresses are stale', () => {
+        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.isIpAddressesStale).toBe(true);
+        expect(result.isNonIpAddressesStale).toBe(false);
+    });
+    it('should include all stale trait tracker fields', () => {
+        const cachedIdentity = {
+            identityId: 'test-id',
+            traits: {},
+        };
+        const incomingIdentity = {
+            identityId: 'test-id',
+            traits: {},
+        };
+        const result = isIdentityCacheStale(cachedIdentity, incomingIdentity);
+        expect(result).toHaveProperty('cachedTraits');
+        expect(result).toHaveProperty('incomingTraits');
+        expect(result).toHaveProperty('isIdentityIdStale');
+        expect(result).toHaveProperty('isUserIdsStale');
+        expect(result).toHaveProperty('isIdsStale');
+        expect(result).toHaveProperty('isEmailsStale');
+        expect(result).toHaveProperty('isPhonesStale');
+        expect(result).toHaveProperty('isShopifyYIdsStale');
+        expect(result).toHaveProperty('isGendersStale');
+        expect(result).toHaveProperty('isDobsStale');
+        expect(result).toHaveProperty('isAddressesStale');
+        expect(result).toHaveProperty('isIpAddressesStale');
+        expect(result).toHaveProperty('isNonIpAddressesStale');
+        expect(result).toHaveProperty('isClickInfosStale');
+        expect(result).toHaveProperty('isIpAddressStale');
+        expect(result).toHaveProperty('isUserAgentStale');
+        expect(result).toHaveProperty('isThirdPartyContactsStale');
+        expect(result).toHaveProperty('isCacheStale');
+        expect(result).toHaveProperty('staleTier');
+    });
+});
 //# sourceMappingURL=volatile-traits-optimization.spec.js.map