@adtrackify/at-service-common 5.0.7 → 5.1.2

package/dist/esm/__tests__/identity-cache/helpers.spec.js

@@ -1,591 +1,592 @@
-import { IDENTITY_CACHE_STALENESS_TIER, mergeAndComputeIdentityStaleness, stripAddressTimestamps, computeTraitChanges } from '@adtrackify/at-shared-utils';
-describe('processCacheHit helper', () => {
-    describe('deep equality check behavior', () => {
-        it('should return isDeepEqual=true when merged equals cached', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    phones: ['555-1234'],
-                },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    phones: ['555-1234'],
-                },
-            };
-            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
-            expect(result.isDeepEqual).toBe(true);
-            expect(result.isCacheStale).toBe(false);
-        });
-        it('should return isDeepEqual=false when merged differs from cached', () => {
-            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 = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
-            expect(result.isDeepEqual).toBe(false);
-            expect(result.isCacheStale).toBe(true);
-        });
-        it('should strip address timestamps before comparison', () => {
-            const now = Date.now();
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    addresses: [{ city: 'NYC', firstName: 'John', cra: now - 10000, upa: now - 5000 }],
-                },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                },
-            };
-            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
-            expect(result.isCacheStale).toBe(false);
-        });
-        it('should detect difference in address content even with timestamp stripping', () => {
-            const now = Date.now();
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    addresses: [{ city: 'NYC', cra: now }],
-                },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    addresses: [{ city: 'Boston', cra: now }],
-                },
-            };
-            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
-            expect(result.isDeepEqual).toBe(false);
-        });
-    });
-    describe('volatile-only tier handling', () => {
-        it('should return isVolatileOnly=true when only ipAddress changes', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    ipAddress: '10.0.0.1',
-                },
-            };
-            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
-            expect(result.isVolatileOnly).toBe(true);
-            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.VOLATILE_ONLY);
-        });
-        it('should return isVolatileOnly=true when only userAgent changes', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    userAgent: 'Mozilla/5.0',
-                },
-            };
-            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
-            expect(result.isVolatileOnly).toBe(true);
-        });
-        it('should set isCacheStale=false for volatile-only tier (override)', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    ipAddress: '192.168.1.1',
-                    userAgent: 'Chrome/100',
-                },
-            };
-            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
-            expect(result.isVolatileOnly).toBe(true);
-            expect(result.isCacheStale).toBe(false);
-        });
-        it('should set skipNeptune=true for volatile-only tier', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    ipAddress: '10.0.0.1',
-                },
-            };
-            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
-            expect(result.skipNeptune).toBe(true);
-        });
-        it('should return merged identity with volatile traits', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    phones: ['555-cached'],
-                },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    ipAddress: '10.0.0.1',
-                },
-            };
-            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
-            expect(result.mergedIdentity.traits?.phones).toContain('555-cached');
-            expect(result.mergedIdentity.traits?.ipAddress).toBe('10.0.0.1');
-        });
-    });
-    describe('address update tier handling', () => {
-        it('should return isAddressUpdate=true when non-IP address is added', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    addresses: [],
-                },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    addresses: [{ firstName: 'John', lastName: 'Doe', city: 'NYC' }],
-                },
-            };
-            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
-            expect(result.isAddressUpdate).toBe(true);
-            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.ADDRESS_UPDATE);
-        });
-        it('should set writeReason=ADDRESS_UPDATE for address update tier', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    addresses: [],
-                },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    addresses: [{ firstName: 'Jane', city: 'Boston' }],
-                },
-            };
-            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
-            expect(result.isAddressUpdate).toBe(true);
-        });
-        it('should set skipNeptune=true for address update tier', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    addresses: [],
-                },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    addresses: [{ firstName: 'Test', city: 'TestCity', zip: '12345' }],
-                },
-            };
-            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
-            expect(result.skipNeptune).toBe(true);
-        });
-        it('should set isCacheStale=true for address update tier', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    addresses: [],
-                },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    addresses: [{ firstName: 'Test', city: 'TestCity' }],
-                },
-            };
-            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
-            expect(result.isCacheStale).toBe(true);
-        });
-        it('should NOT be address update for IP-sourced addresses', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    addresses: [],
-                },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    addresses: [{ city: 'IPCity', country: 'US' }],
-                },
-            };
-            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
-            expect(result.isAddressUpdate).toBe(false);
-            expect(result.isVolatileOnly).toBe(true);
-        });
-    });
-    describe('identity stale tier handling', () => {
-        it('should return IDENTITY_STALE when identity-defining trait changes', () => {
-            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 = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
-            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.IDENTITY_STALE);
-            expect(result.isCacheStale).toBe(true);
-        });
-        it('should set writeReason=STALE_TRAITS for identity stale tier', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    phones: ['555-old'],
-                },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    phones: ['555-old', '555-new'],
-                },
-            };
-            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
-            expect(result.isAddressUpdate).toBe(false);
-            expect(result.isCacheStale).toBe(true);
-        });
-        it('should set skipNeptune=false for identity stale tier', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                    userIds: ['user-123'],
-                },
-            };
-            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
-            expect(result.skipNeptune).toBe(false);
-        });
-        it('should populate staleTraits with changed trait names', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['old@email.com'],
-                },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['old@email.com', 'new@email.com'],
-                    phones: ['555-new'],
-                },
-            };
-            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
-            expect(result.staleTraits).toContain('emails');
-            expect(result.staleTraits).toContain('phones');
-        });
-    });
-    describe('deep equality override for isCacheStale', () => {
-        it('should set isCacheStale=false when deep equal regardless of staleness computation', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['test@email.com'],
-                },
-            };
-            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
-            expect(result.isDeepEqual).toBe(true);
-            expect(result.isCacheStale).toBe(false);
-        });
-    });
-    describe('staleTracker population', () => {
-        it('should return populated staleTracker from mergeAndComputeIdentityStaleness', () => {
-            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 = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
-            expect(result.staleTracker).toBeDefined();
-            expect(result.staleTracker.isEmailsStale).toBe(true);
-        });
-    });
-    describe('merged identity correctness', () => {
-        it('should merge traits from both incoming and cached', () => {
-            const cachedIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['cached@email.com'],
-                    phones: ['555-cached'],
-                },
-            };
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: {
-                    emails: ['cached@email.com', 'new@email.com'],
-                },
-            };
-            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
-            expect(result.mergedIdentity.traits?.emails).toContain('cached@email.com');
-            expect(result.mergedIdentity.traits?.emails).toContain('new@email.com');
-            expect(result.mergedIdentity.traits?.phones).toContain('555-cached');
-        });
-        it('should preserve identityId from incoming (incoming spreads first)', () => {
-            const cachedIdentity = {
-                identityId: 'cached-identity-id',
-                traits: { emails: ['test@email.com'] },
-            };
-            const incomingIdentity = {
-                identityId: 'incoming-identity-id',
-                traits: { emails: ['test@email.com'] },
-            };
-            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
-            expect(result.mergedIdentity.identityId).toBe('incoming-identity-id');
-        });
-    });
-});
-describe('stripAddressTimestamps helper', () => {
-    it('should remove cra and upa from addresses', () => {
-        const identity = {
-            identityId: 'test',
-            traits: {
-                addresses: [
-                    { city: 'NYC', cra: 1234567890, upa: 1234567899 },
-                    { city: 'LA', cra: 9876543210, upa: 9876543219 },
-                ],
-            },
-        };
-        const result = stripAddressTimestamps(identity);
-        expect(result.traits?.addresses?.[0]).not.toHaveProperty('cra');
-        expect(result.traits?.addresses?.[0]).not.toHaveProperty('upa');
-        expect(result.traits?.addresses?.[0]?.city).toBe('NYC');
-        expect(result.traits?.addresses?.[1]).not.toHaveProperty('cra');
-        expect(result.traits?.addresses?.[1]).not.toHaveProperty('upa');
-        expect(result.traits?.addresses?.[1]?.city).toBe('LA');
-    });
-    it('should return original identity if no addresses', () => {
-        const identity = {
-            identityId: 'test',
-            traits: {
-                emails: ['test@email.com'],
-            },
-        };
-        const result = stripAddressTimestamps(identity);
-        expect(result).toEqual(identity);
-    });
-    it('should return original identity if addresses array is empty', () => {
-        const identity = {
-            identityId: 'test',
-            traits: {
-                addresses: [],
-            },
-        };
-        const result = stripAddressTimestamps(identity);
-        expect(result).toEqual(identity);
-    });
-    it('should preserve other address fields', () => {
-        const identity = {
-            identityId: 'test',
-            traits: {
-                addresses: [
-                    {
-                        firstName: 'John',
-                        lastName: 'Doe',
-                        city: 'NYC',
-                        zip: '10001',
-                        country: 'US',
-                        cra: 123456,
-                        upa: 789012,
-                    },
-                ],
-            },
-        };
-        const result = stripAddressTimestamps(identity);
-        const addr = result.traits?.addresses?.[0];
-        expect(addr?.firstName).toBe('John');
-        expect(addr?.lastName).toBe('Doe');
-        expect(addr?.city).toBe('NYC');
-        expect(addr?.zip).toBe('10001');
-        expect(addr?.country).toBe('US');
-        expect(addr).not.toHaveProperty('cra');
-        expect(addr).not.toHaveProperty('upa');
-    });
-});
-describe('computeTraitChanges helper', () => {
-    it('should detect email changes', () => {
-        const cached = {
-            identityId: 'test',
-            traits: { emails: ['old@email.com'] },
-        };
-        const resolved = {
-            identityId: 'test',
-            traits: { emails: ['old@email.com', 'new@email.com'] },
-        };
-        const changes = computeTraitChanges(cached, resolved);
-        expect(changes.emails).toBeDefined();
-        expect(changes.emails?.cached).toEqual(['old@email.com']);
-        expect(changes.emails?.resolved).toEqual(['old@email.com', 'new@email.com']);
-    });
-    it('should detect phone changes', () => {
-        const cached = {
-            identityId: 'test',
-            traits: { phones: ['555-old'] },
-        };
-        const resolved = {
-            identityId: 'test',
-            traits: { phones: ['555-old', '555-new'] },
-        };
-        const changes = computeTraitChanges(cached, resolved);
-        expect(changes.phones).toBeDefined();
-        expect(changes.phones?.cached).toEqual(['555-old']);
-        expect(changes.phones?.resolved).toContain('555-new');
-    });
-    it('should detect address changes', () => {
-        const cached = {
-            identityId: 'test',
-            traits: { addresses: [{ city: 'NYC' }] },
-        };
-        const resolved = {
-            identityId: 'test',
-            traits: { addresses: [{ city: 'NYC' }, { city: 'LA' }] },
-        };
-        const changes = computeTraitChanges(cached, resolved);
-        expect(changes.addresses).toBeDefined();
-    });
-    it('should detect identityId changes', () => {
-        const cached = {
-            identityId: 'old-id',
-            traits: {},
-        };
-        const resolved = {
-            identityId: 'new-id',
-            traits: {},
-        };
-        const changes = computeTraitChanges(cached, resolved);
-        expect(changes.identityId).toBeDefined();
-        expect(changes.identityId?.cached).toBe('old-id');
-        expect(changes.identityId?.resolved).toBe('new-id');
-    });
-    it('should detect ipAddress changes', () => {
-        const cached = {
-            identityId: 'test',
-            traits: { ipAddress: '10.0.0.1' },
-        };
-        const resolved = {
-            identityId: 'test',
-            traits: { ipAddress: '10.0.0.2' },
-        };
-        const changes = computeTraitChanges(cached, resolved);
-        expect(changes.ipAddress).toBeDefined();
-        expect(changes.ipAddress?.cached).toBe('10.0.0.1');
-        expect(changes.ipAddress?.resolved).toBe('10.0.0.2');
-    });
-    it('should detect userAgent changes', () => {
-        const cached = {
-            identityId: 'test',
-            traits: { userAgent: 'Mozilla/5.0 Old' },
-        };
-        const resolved = {
-            identityId: 'test',
-            traits: { userAgent: 'Mozilla/5.0 New' },
-        };
-        const changes = computeTraitChanges(cached, resolved);
-        expect(changes.userAgent).toBeDefined();
-    });
-    it('should not include unchanged traits', () => {
-        const cached = {
-            identityId: 'test',
-            traits: {
-                emails: ['same@email.com'],
-                phones: ['555-same'],
-            },
-        };
-        const resolved = {
-            identityId: 'test',
-            traits: {
-                emails: ['same@email.com'],
-                phones: ['555-same'],
-            },
-        };
-        const changes = computeTraitChanges(cached, resolved);
-        expect(changes.emails).toBeUndefined();
-        expect(changes.phones).toBeUndefined();
-    });
-    it('should handle undefined traits gracefully', () => {
-        const cached = {
-            identityId: 'test',
-            traits: undefined,
-        };
-        const resolved = {
-            identityId: 'test',
-            traits: { emails: ['new@email.com'] },
-        };
-        const changes = computeTraitChanges(cached, resolved);
-        expect(changes.emails).toBeDefined();
-        expect(changes.emails?.cached).toEqual([]);
-        expect(changes.emails?.resolved).toEqual(['new@email.com']);
-    });
-});
+import { describe, it, expect } from 'vitest';
+import { IDENTITY_CACHE_STALENESS_TIER, mergeAndComputeIdentityStaleness, stripAddressTimestamps, computeTraitChanges, } from '@adtrackify/at-shared-utils';
+describe('processCacheHit helper', () => {
+    describe('deep equality check behavior', () => {
+        it('should return isDeepEqual=true when merged equals cached', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    phones: ['555-1234'],
+                },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    phones: ['555-1234'],
+                },
+            };
+            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
+            expect(result.isDeepEqual).toBe(true);
+            expect(result.isCacheStale).toBe(false);
+        });
+        it('should return isDeepEqual=false when merged differs from cached', () => {
+            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 = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
+            expect(result.isDeepEqual).toBe(false);
+            expect(result.isCacheStale).toBe(true);
+        });
+        it('should strip address timestamps before comparison', () => {
+            const now = Date.now();
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    addresses: [{ city: 'NYC', firstName: 'John', cra: now - 10000, upa: now - 5000 }],
+                },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                },
+            };
+            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
+            expect(result.isCacheStale).toBe(false);
+        });
+        it('should detect difference in address content even with timestamp stripping', () => {
+            const now = Date.now();
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    addresses: [{ city: 'NYC', cra: now }],
+                },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    addresses: [{ city: 'Boston', cra: now }],
+                },
+            };
+            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
+            expect(result.isDeepEqual).toBe(false);
+        });
+    });
+    describe('volatile-only tier handling', () => {
+        it('should return isVolatileOnly=true when only ipAddress changes', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    ipAddress: '10.0.0.1',
+                },
+            };
+            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
+            expect(result.isVolatileOnly).toBe(true);
+            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.VOLATILE_ONLY);
+        });
+        it('should return isVolatileOnly=true when only userAgent changes', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    userAgent: 'Mozilla/5.0',
+                },
+            };
+            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
+            expect(result.isVolatileOnly).toBe(true);
+        });
+        it('should set isCacheStale=false for volatile-only tier (override)', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    ipAddress: '192.168.1.1',
+                    userAgent: 'Chrome/100',
+                },
+            };
+            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
+            expect(result.isVolatileOnly).toBe(true);
+            expect(result.isCacheStale).toBe(false);
+        });
+        it('should set skipNeptune=true for volatile-only tier', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    ipAddress: '10.0.0.1',
+                },
+            };
+            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
+            expect(result.skipNeptune).toBe(true);
+        });
+        it('should return merged identity with volatile traits', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    phones: ['555-cached'],
+                },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    ipAddress: '10.0.0.1',
+                },
+            };
+            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
+            expect(result.mergedIdentity.traits?.phones).toContain('555-cached');
+            expect(result.mergedIdentity.traits?.ipAddress).toBe('10.0.0.1');
+        });
+    });
+    describe('address update tier handling', () => {
+        it('should return isAddressUpdate=true when non-IP address is added', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    addresses: [],
+                },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    addresses: [{ firstName: 'John', lastName: 'Doe', city: 'NYC' }],
+                },
+            };
+            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
+            expect(result.isAddressUpdate).toBe(true);
+            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.ADDRESS_UPDATE);
+        });
+        it('should set writeReason=ADDRESS_UPDATE for address update tier', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    addresses: [],
+                },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    addresses: [{ firstName: 'Jane', city: 'Boston' }],
+                },
+            };
+            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
+            expect(result.isAddressUpdate).toBe(true);
+        });
+        it('should set skipNeptune=true for address update tier', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    addresses: [],
+                },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    addresses: [{ firstName: 'Test', city: 'TestCity', zip: '12345' }],
+                },
+            };
+            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
+            expect(result.skipNeptune).toBe(true);
+        });
+        it('should set isCacheStale=true for address update tier', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    addresses: [],
+                },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    addresses: [{ firstName: 'Test', city: 'TestCity' }],
+                },
+            };
+            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
+            expect(result.isCacheStale).toBe(true);
+        });
+        it('should NOT be address update for IP-sourced addresses', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    addresses: [],
+                },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    addresses: [{ city: 'IPCity', country: 'US' }],
+                },
+            };
+            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
+            expect(result.isAddressUpdate).toBe(false);
+            expect(result.isVolatileOnly).toBe(true);
+        });
+    });
+    describe('identity stale tier handling', () => {
+        it('should return IDENTITY_STALE when identity-defining trait changes', () => {
+            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 = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
+            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.IDENTITY_STALE);
+            expect(result.isCacheStale).toBe(true);
+        });
+        it('should set writeReason=STALE_TRAITS for identity stale tier', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    phones: ['555-old'],
+                },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    phones: ['555-old', '555-new'],
+                },
+            };
+            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
+            expect(result.isAddressUpdate).toBe(false);
+            expect(result.isCacheStale).toBe(true);
+        });
+        it('should set skipNeptune=false for identity stale tier', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                    userIds: ['user-123'],
+                },
+            };
+            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
+            expect(result.skipNeptune).toBe(false);
+        });
+        it('should populate staleTraits with changed trait names', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['old@email.com'],
+                },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['old@email.com', 'new@email.com'],
+                    phones: ['555-new'],
+                },
+            };
+            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
+            expect(result.staleTraits).toContain('emails');
+            expect(result.staleTraits).toContain('phones');
+        });
+    });
+    describe('deep equality override for isCacheStale', () => {
+        it('should set isCacheStale=false when deep equal regardless of staleness computation', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['test@email.com'],
+                },
+            };
+            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
+            expect(result.isDeepEqual).toBe(true);
+            expect(result.isCacheStale).toBe(false);
+        });
+    });
+    describe('staleTracker population', () => {
+        it('should return populated staleTracker from mergeAndComputeIdentityStaleness', () => {
+            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 = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
+            expect(result.staleTracker).toBeDefined();
+            expect(result.staleTracker.isEmailsStale).toBe(true);
+        });
+    });
+    describe('merged identity correctness', () => {
+        it('should merge traits from both incoming and cached', () => {
+            const cachedIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['cached@email.com'],
+                    phones: ['555-cached'],
+                },
+            };
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: {
+                    emails: ['cached@email.com', 'new@email.com'],
+                },
+            };
+            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
+            expect(result.mergedIdentity.traits?.emails).toContain('cached@email.com');
+            expect(result.mergedIdentity.traits?.emails).toContain('new@email.com');
+            expect(result.mergedIdentity.traits?.phones).toContain('555-cached');
+        });
+        it('should preserve identityId from incoming (incoming spreads first)', () => {
+            const cachedIdentity = {
+                identityId: 'cached-identity-id',
+                traits: { emails: ['test@email.com'] },
+            };
+            const incomingIdentity = {
+                identityId: 'incoming-identity-id',
+                traits: { emails: ['test@email.com'] },
+            };
+            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
+            expect(result.mergedIdentity.identityId).toBe('incoming-identity-id');
+        });
+    });
+});
+describe('stripAddressTimestamps helper', () => {
+    it('should remove cra and upa from addresses', () => {
+        const identity = {
+            identityId: 'test',
+            traits: {
+                addresses: [
+                    { city: 'NYC', cra: 1234567890, upa: 1234567899 },
+                    { city: 'LA', cra: 9876543210, upa: 9876543219 },
+                ],
+            },
+        };
+        const result = stripAddressTimestamps(identity);
+        expect(result.traits?.addresses?.[0]).not.toHaveProperty('cra');
+        expect(result.traits?.addresses?.[0]).not.toHaveProperty('upa');
+        expect(result.traits?.addresses?.[0]?.city).toBe('NYC');
+        expect(result.traits?.addresses?.[1]).not.toHaveProperty('cra');
+        expect(result.traits?.addresses?.[1]).not.toHaveProperty('upa');
+        expect(result.traits?.addresses?.[1]?.city).toBe('LA');
+    });
+    it('should return original identity if no addresses', () => {
+        const identity = {
+            identityId: 'test',
+            traits: {
+                emails: ['test@email.com'],
+            },
+        };
+        const result = stripAddressTimestamps(identity);
+        expect(result).toEqual(identity);
+    });
+    it('should return original identity if addresses array is empty', () => {
+        const identity = {
+            identityId: 'test',
+            traits: {
+                addresses: [],
+            },
+        };
+        const result = stripAddressTimestamps(identity);
+        expect(result).toEqual(identity);
+    });
+    it('should preserve other address fields', () => {
+        const identity = {
+            identityId: 'test',
+            traits: {
+                addresses: [
+                    {
+                        firstName: 'John',
+                        lastName: 'Doe',
+                        city: 'NYC',
+                        zip: '10001',
+                        country: 'US',
+                        cra: 123456,
+                        upa: 789012,
+                    },
+                ],
+            },
+        };
+        const result = stripAddressTimestamps(identity);
+        const addr = result.traits?.addresses?.[0];
+        expect(addr?.firstName).toBe('John');
+        expect(addr?.lastName).toBe('Doe');
+        expect(addr?.city).toBe('NYC');
+        expect(addr?.zip).toBe('10001');
+        expect(addr?.country).toBe('US');
+        expect(addr).not.toHaveProperty('cra');
+        expect(addr).not.toHaveProperty('upa');
+    });
+});
+describe('computeTraitChanges helper', () => {
+    it('should detect email changes', () => {
+        const cached = {
+            identityId: 'test',
+            traits: { emails: ['old@email.com'] },
+        };
+        const resolved = {
+            identityId: 'test',
+            traits: { emails: ['old@email.com', 'new@email.com'] },
+        };
+        const changes = computeTraitChanges(cached, resolved);
+        expect(changes.emails).toBeDefined();
+        expect(changes.emails?.cached).toEqual(['old@email.com']);
+        expect(changes.emails?.resolved).toEqual(['old@email.com', 'new@email.com']);
+    });
+    it('should detect phone changes', () => {
+        const cached = {
+            identityId: 'test',
+            traits: { phones: ['555-old'] },
+        };
+        const resolved = {
+            identityId: 'test',
+            traits: { phones: ['555-old', '555-new'] },
+        };
+        const changes = computeTraitChanges(cached, resolved);
+        expect(changes.phones).toBeDefined();
+        expect(changes.phones?.cached).toEqual(['555-old']);
+        expect(changes.phones?.resolved).toContain('555-new');
+    });
+    it('should detect address changes', () => {
+        const cached = {
+            identityId: 'test',
+            traits: { addresses: [{ city: 'NYC' }] },
+        };
+        const resolved = {
+            identityId: 'test',
+            traits: { addresses: [{ city: 'NYC' }, { city: 'LA' }] },
+        };
+        const changes = computeTraitChanges(cached, resolved);
+        expect(changes.addresses).toBeDefined();
+    });
+    it('should detect identityId changes', () => {
+        const cached = {
+            identityId: 'old-id',
+            traits: {},
+        };
+        const resolved = {
+            identityId: 'new-id',
+            traits: {},
+        };
+        const changes = computeTraitChanges(cached, resolved);
+        expect(changes.identityId).toBeDefined();
+        expect(changes.identityId?.cached).toBe('old-id');
+        expect(changes.identityId?.resolved).toBe('new-id');
+    });
+    it('should detect ipAddress changes', () => {
+        const cached = {
+            identityId: 'test',
+            traits: { ipAddress: '10.0.0.1' },
+        };
+        const resolved = {
+            identityId: 'test',
+            traits: { ipAddress: '10.0.0.2' },
+        };
+        const changes = computeTraitChanges(cached, resolved);
+        expect(changes.ipAddress).toBeDefined();
+        expect(changes.ipAddress?.cached).toBe('10.0.0.1');
+        expect(changes.ipAddress?.resolved).toBe('10.0.0.2');
+    });
+    it('should detect userAgent changes', () => {
+        const cached = {
+            identityId: 'test',
+            traits: { userAgent: 'Mozilla/5.0 Old' },
+        };
+        const resolved = {
+            identityId: 'test',
+            traits: { userAgent: 'Mozilla/5.0 New' },
+        };
+        const changes = computeTraitChanges(cached, resolved);
+        expect(changes.userAgent).toBeDefined();
+    });
+    it('should not include unchanged traits', () => {
+        const cached = {
+            identityId: 'test',
+            traits: {
+                emails: ['same@email.com'],
+                phones: ['555-same'],
+            },
+        };
+        const resolved = {
+            identityId: 'test',
+            traits: {
+                emails: ['same@email.com'],
+                phones: ['555-same'],
+            },
+        };
+        const changes = computeTraitChanges(cached, resolved);
+        expect(changes.emails).toBeUndefined();
+        expect(changes.phones).toBeUndefined();
+    });
+    it('should handle undefined traits gracefully', () => {
+        const cached = {
+            identityId: 'test',
+            traits: undefined,
+        };
+        const resolved = {
+            identityId: 'test',
+            traits: { emails: ['new@email.com'] },
+        };
+        const changes = computeTraitChanges(cached, resolved);
+        expect(changes.emails).toBeDefined();
+        expect(changes.emails?.cached).toEqual([]);
+        expect(changes.emails?.resolved).toEqual(['new@email.com']);
+    });
+});
 //# sourceMappingURL=helpers.spec.js.map