@adtrackify/at-service-common 4.0.7 → 4.0.9

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

@@ -1,6 +1,6 @@
 import { ADDRESS_INFO_SOURCE } from '@adtrackify/at-tracking-event-types';
 import { mergeIdentityTraits } from '@adtrackify/at-shared-utils';
-import { isIdentityCacheStale, isClickInfosStale, IDENTITY_CACHE_STALENESS_TIER, } from '../../helpers/identity-cache-helper';
+import { isIdentityCacheStale, isClickInfosStale, IDENTITY_CACHE_STALENESS_TIER, extractStaleTraitNames, mergeAndComputeIdentityStaleness, } from '../../helpers/identity-cache-helper';
 describe('Identity Trait Merging Tests', () => {
     afterEach(() => {
         jest.resetModules();
@@ -1056,4 +1056,715 @@ describe('Three-Tier Staleness Model Tests', () => {
         });
     });
 });
+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