@adtrackify/at-service-common 4.0.0 → 4.0.2

package/dist/esm/__tests__/identity-cache/identity-cache-tier-routing.spec.js

@@ -1,850 +1,850 @@
-import { ADDRESS_INFO_SOURCE } from '@adtrackify/at-tracking-event-types';
-import { IDENTITY_CACHE_STALENESS_TIER } from '../../helpers/identity-cache-helper';
-import { CACHE_WRITE_REASON } from '../../services/db/identity-cache-dynamodb-service';
-const mockInvokeFunction = jest.fn();
-jest.mock('../../clients/index.js', () => ({
-    DynamoDbClient: {
-        safeGet: jest.fn(),
-        safePut: jest.fn(),
-        safeDelete: jest.fn(),
-        safeBatchGet: jest.fn(),
-        safeBatchWrite: jest.fn(),
-        safeQueryByGSI: jest.fn(),
-        batchWrite: jest.fn(),
-    },
-    LambdaInvokeClient: jest.fn().mockImplementation(() => ({
-        invokeFunction: mockInvokeFunction,
-    })),
-}));
-jest.mock('../../helpers/index.js', () => ({
-    Logger: {
-        debug: jest.fn(),
-        info: jest.fn(),
-        warn: jest.fn(),
-        error: jest.fn(),
-    },
-}));
-import { IdentityCacheDynamoDbService, } from '../../services/db/identity-cache-dynamodb-service.js';
-import { DynamoDbClient } from '../../clients/index.js';
-import { Logger } from '../../helpers/index.js';
-const mockedDynamoDbClient = DynamoDbClient;
-const mockedLogger = Logger;
-describe('Identity Cache Three-Tier Routing', () => {
-    const pixelId = 'pixel123';
-    const lambdaArn = 'arn:aws:lambda:us-east-1:123456789:function:identity-private';
-    beforeEach(() => {
-        jest.clearAllMocks();
-        mockedDynamoDbClient.safeGet.mockReset();
-        mockedDynamoDbClient.safePut.mockReset();
-        mockedDynamoDbClient.safeDelete.mockReset();
-        mockedDynamoDbClient.safeBatchGet.mockReset();
-        mockedDynamoDbClient.safeBatchWrite.mockReset();
-        mockedDynamoDbClient.safeQueryByGSI.mockReset();
-        mockedDynamoDbClient.batchWrite.mockReset();
-        mockInvokeFunction.mockReset();
-        IdentityCacheDynamoDbService.lambdaInvokeClient = undefined;
-    });
-    describe('TIER: VOLATILE_ONLY — Returns merged identity, NO Neptune, NO cache write', () => {
-        it('should return merged identity without Neptune call when only ipAddress is stale', async () => {
-            const incomingIdentity = {
-                identityId: 'identity456',
-                traits: {
-                    emails: ['test@email.com'],
-                    ipAddress: '10.0.0.1',
-                },
-            };
-            const cachedResponse = {
-                pk: `identity#${pixelId}#identity456`,
-                pixelId,
-                identityId: 'identity456',
-                response: {
-                    identityId: 'identity456',
-                    traits: {
-                        emails: ['test@email.com'],
-                        ipAddress: '192.168.1.1',
-                    },
-                },
-                updatedAt: new Date().toISOString(),
-            };
-            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
-            const result = await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
-            expect(result).toBeDefined();
-            expect(result?.identityId).toBe('identity456');
-            expect(mockInvokeFunction).not.toHaveBeenCalled();
-            expect(mockedDynamoDbClient.safeBatchWrite).not.toHaveBeenCalled();
-        });
-        it('should return merged identity without Neptune call when only userAgent is stale', async () => {
-            const incomingIdentity = {
-                identityId: 'identity456',
-                traits: {
-                    emails: ['test@email.com'],
-                    userAgent: 'Chrome/120.0',
-                },
-            };
-            const cachedResponse = {
-                pk: `identity#${pixelId}#identity456`,
-                pixelId,
-                identityId: 'identity456',
-                response: {
-                    identityId: 'identity456',
-                    traits: {
-                        emails: ['test@email.com'],
-                        userAgent: 'Mozilla/5.0',
-                    },
-                },
-                updatedAt: new Date().toISOString(),
-            };
-            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
-            const result = await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
-            expect(result).toBeDefined();
-            expect(mockInvokeFunction).not.toHaveBeenCalled();
-            expect(mockedDynamoDbClient.safeBatchWrite).not.toHaveBeenCalled();
-        });
-        it('should return merged identity without Neptune call when only IP-sourced addresses are stale', async () => {
-            const incomingIdentity = {
-                identityId: 'identity456',
-                traits: {
-                    emails: ['test@email.com'],
-                    addresses: [{ city: 'New York', s: ADDRESS_INFO_SOURCE.IP_ADDRESS }],
-                },
-            };
-            const cachedResponse = {
-                pk: `identity#${pixelId}#identity456`,
-                pixelId,
-                identityId: 'identity456',
-                response: {
-                    identityId: 'identity456',
-                    traits: {
-                        emails: ['test@email.com'],
-                        addresses: [{ city: 'Chicago', s: ADDRESS_INFO_SOURCE.IP_ADDRESS }],
-                    },
-                },
-                updatedAt: new Date().toISOString(),
-            };
-            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
-            const result = await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
-            expect(result).toBeDefined();
-            expect(mockInvokeFunction).not.toHaveBeenCalled();
-            expect(mockedDynamoDbClient.safeBatchWrite).not.toHaveBeenCalled();
-        });
-    });
-    describe('TIER: ADDRESS_UPDATE — Writes to cache, NO Neptune call', () => {
-        it('should write to cache but skip Neptune when new non-IP address is added', async () => {
-            const incomingIdentity = {
-                identityId: 'identity456',
-                traits: {
-                    emails: ['test@email.com'],
-                    addresses: [{ city: 'Boston', firstName: 'John', s: ADDRESS_INFO_SOURCE.INPUT }],
-                },
-            };
-            const cachedResponse = {
-                pk: `identity#${pixelId}#identity456`,
-                pixelId,
-                identityId: 'identity456',
-                response: {
-                    identityId: 'identity456',
-                    traits: {
-                        emails: ['test@email.com'],
-                        addresses: [],
-                    },
-                },
-                updatedAt: new Date().toISOString(),
-            };
-            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
-            const result = await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
-            expect(result).toBeDefined();
-            expect(result?.traits?.addresses).toHaveLength(1);
-            expect(mockInvokeFunction).not.toHaveBeenCalled();
-            expect(mockedDynamoDbClient.safeBatchWrite).toHaveBeenCalled();
-        });
-        it('should write to cache and skip Neptune when address with PII but no source is added', async () => {
-            const incomingIdentity = {
-                identityId: 'identity456',
-                traits: {
-                    emails: ['test@email.com'],
-                    addresses: [{ city: 'Miami', lastName: 'Smith' }],
-                },
-            };
-            const cachedResponse = {
-                pk: `identity#${pixelId}#identity456`,
-                pixelId,
-                identityId: 'identity456',
-                response: {
-                    identityId: 'identity456',
-                    traits: {
-                        emails: ['test@email.com'],
-                        addresses: [],
-                    },
-                },
-                updatedAt: new Date().toISOString(),
-            };
-            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
-            const result = await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
-            expect(result).toBeDefined();
-            expect(mockInvokeFunction).not.toHaveBeenCalled();
-            expect(mockedDynamoDbClient.safeBatchWrite).toHaveBeenCalled();
-        });
-        it('should log with writeReason ADDRESS_UPDATE and staleTraits', async () => {
-            const incomingIdentity = {
-                identityId: 'identity456',
-                traits: {
-                    emails: ['test@email.com'],
-                    addresses: [{ city: 'Seattle', s: ADDRESS_INFO_SOURCE.INPUT }],
-                },
-            };
-            const cachedResponse = {
-                pk: `identity#${pixelId}#identity456`,
-                pixelId,
-                identityId: 'identity456',
-                response: {
-                    identityId: 'identity456',
-                    traits: {
-                        emails: ['test@email.com'],
-                        addresses: [],
-                    },
-                },
-                updatedAt: new Date().toISOString(),
-            };
-            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
-            await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
-            expect(mockedLogger.info).toHaveBeenCalledWith('identity cache write: address update only (skipping Neptune)', expect.objectContaining({
-                pixelId,
-                writeReason: CACHE_WRITE_REASON.ADDRESS_UPDATE,
-                staleTier: IDENTITY_CACHE_STALENESS_TIER.ADDRESS_UPDATE,
-            }));
-        });
-    });
-    describe('TIER: IDENTITY_STALE — Calls Neptune AND writes to cache', () => {
-        it('should call Neptune and write to cache when emails are stale', async () => {
-            const incomingIdentity = {
-                identityId: 'identity456',
-                traits: {
-                    emails: ['old@email.com', 'new@email.com'],
-                },
-            };
-            const cachedResponse = {
-                pk: `identity#${pixelId}#identity456`,
-                pixelId,
-                identityId: 'identity456',
-                response: {
-                    identityId: 'identity456',
-                    traits: {
-                        emails: ['old@email.com'],
-                    },
-                },
-                updatedAt: new Date().toISOString(),
-            };
-            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
-            mockInvokeFunction.mockResolvedValueOnce({
-                statusCode: 200,
-                body: JSON.stringify({
-                    identity: {
-                        identityId: 'identity456',
-                        traits: { emails: ['old@email.com', 'new@email.com', 'resolved@email.com'] },
-                    },
-                }),
-            });
-            const result = await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
-            expect(result).toBeDefined();
-            expect(mockInvokeFunction).toHaveBeenCalled();
-            expect(mockedDynamoDbClient.safeBatchWrite).toHaveBeenCalled();
-        });
-        it('should call Neptune and write to cache when phones are stale', async () => {
-            const incomingIdentity = {
-                identityId: 'identity456',
-                traits: {
-                    phones: ['+1234567890', '+9876543210'],
-                },
-            };
-            const cachedResponse = {
-                pk: `identity#${pixelId}#identity456`,
-                pixelId,
-                identityId: 'identity456',
-                response: {
-                    identityId: 'identity456',
-                    traits: {
-                        phones: ['+1234567890'],
-                    },
-                },
-                updatedAt: new Date().toISOString(),
-            };
-            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
-            mockInvokeFunction.mockResolvedValueOnce({
-                statusCode: 200,
-                body: JSON.stringify({
-                    identity: {
-                        identityId: 'identity456',
-                        traits: { phones: ['+1234567890', '+9876543210'] },
-                    },
-                }),
-            });
-            const result = await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
-            expect(result).toBeDefined();
-            expect(mockInvokeFunction).toHaveBeenCalled();
-            expect(mockedDynamoDbClient.safeBatchWrite).toHaveBeenCalled();
-        });
-        it('should log with writeReason STALE_TRAITS, staleTraits, and traitChanges', async () => {
-            const incomingIdentity = {
-                identityId: 'identity456',
-                traits: {
-                    emails: ['old@email.com', 'new@email.com'],
-                },
-            };
-            const cachedResponse = {
-                pk: `identity#${pixelId}#identity456`,
-                pixelId,
-                identityId: 'identity456',
-                response: {
-                    identityId: 'identity456',
-                    traits: { emails: ['old@email.com'] },
-                },
-                updatedAt: new Date().toISOString(),
-            };
-            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
-            mockInvokeFunction.mockResolvedValueOnce({
-                statusCode: 200,
-                body: JSON.stringify({
-                    identity: {
-                        identityId: 'identity456',
-                        traits: { emails: ['old@email.com', 'new@email.com'] },
-                    },
-                }),
-            });
-            await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
-            expect(mockedLogger.info).toHaveBeenCalledWith('identity cache write: stale identity traits update', expect.objectContaining({
-                pixelId,
-                writeReason: CACHE_WRITE_REASON.STALE_TRAITS,
-                staleTier: IDENTITY_CACHE_STALENESS_TIER.IDENTITY_STALE,
-                staleTraits: expect.arrayContaining(['emails']),
-            }));
-        });
-    });
-    describe('CACHE_MISS — Calls Neptune AND writes to cache', () => {
-        it('should call Neptune and write to cache on complete cache miss', async () => {
-            const incomingIdentity = {
-                identityId: 'identity456',
-                traits: { emails: ['test@email.com'] },
-            };
-            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
-            mockInvokeFunction.mockResolvedValueOnce({
-                statusCode: 200,
-                body: JSON.stringify({
-                    identity: {
-                        identityId: 'identity456',
-                        traits: { emails: ['test@email.com'] },
-                    },
-                }),
-            });
-            const result = await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
-            expect(result).toBeDefined();
-            expect(mockInvokeFunction).toHaveBeenCalled();
-            expect(mockedDynamoDbClient.safeBatchWrite).toHaveBeenCalled();
-        });
-        it('should log with writeReason CACHE_MISS', async () => {
-            const incomingIdentity = {
-                identityId: 'identity456',
-                traits: { emails: ['test@email.com'] },
-            };
-            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
-            mockInvokeFunction.mockResolvedValueOnce({
-                statusCode: 200,
-                body: JSON.stringify({
-                    identity: {
-                        identityId: 'identity456',
-                        traits: { emails: ['test@email.com'] },
-                    },
-                }),
-            });
-            await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
-            expect(mockedLogger.info).toHaveBeenCalledWith('identity cache write: new identity', expect.objectContaining({
-                pixelId,
-                writeReason: CACHE_WRITE_REASON.CACHE_MISS,
-            }));
-        });
-    });
-    describe('EMAIL_POINTER_DISCOVERY — Calls Neptune with discovered identityId', () => {
-        it('should call Neptune with discovered identityId from email pointer', async () => {
-            const incomingIdentity = {
-                traits: { emails: ['test@email.com'] },
-            };
-            const pointerRecord = {
-                pk: `email#${pixelId}#test@email.com`,
-                pixelId,
-                identityId: 'discovered-id',
-                gsi1pk: 'discovered-id',
-                updatedAt: new Date().toISOString(),
-            };
-            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(pointerRecord);
-            mockInvokeFunction.mockResolvedValueOnce({
-                statusCode: 200,
-                body: JSON.stringify({
-                    identity: {
-                        identityId: 'discovered-id',
-                        traits: { emails: ['test@email.com', 'other@email.com'] },
-                    },
-                }),
-            });
-            const result = await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
-            expect(result?.identityId).toBe('discovered-id');
-            expect(mockInvokeFunction).toHaveBeenCalledWith(lambdaArn, expect.objectContaining({
-                context: {
-                    identity: expect.objectContaining({
-                        identityId: 'discovered-id',
-                    }),
-                },
-            }));
-        });
-    });
-});
-describe('Identity Cache stripAddressTimestamps', () => {
-    const pixelId = 'pixel123';
-    const lambdaArn = 'arn:aws:lambda:us-east-1:123456789:function:identity-private';
-    beforeEach(() => {
-        jest.clearAllMocks();
-        mockedDynamoDbClient.safeGet.mockReset();
-        mockedDynamoDbClient.safeBatchWrite.mockReset();
-        mockInvokeFunction.mockReset();
-        IdentityCacheDynamoDbService.lambdaInvokeClient = undefined;
-    });
-    it('should strip cra and upa from addresses during comparison', async () => {
-        const incomingIdentity = {
-            identityId: 'identity456',
-            traits: {
-                emails: ['test@email.com'],
-                addresses: [
-                    {
-                        city: 'Test City',
-                        s: ADDRESS_INFO_SOURCE.INPUT,
-                        cra: Date.parse('2024-01-01T00:00:00Z'),
-                        upa: Date.parse('2024-01-15T00:00:00Z'),
-                    },
-                ],
-            },
-        };
-        const cachedResponse = {
-            pk: `identity#${pixelId}#identity456`,
-            pixelId,
-            identityId: 'identity456',
-            response: {
-                identityId: 'identity456',
-                traits: {
-                    emails: ['test@email.com'],
-                    addresses: [
-                        {
-                            city: 'Test City',
-                            s: ADDRESS_INFO_SOURCE.INPUT,
-                            cra: Date.parse('2023-06-01T00:00:00Z'),
-                            upa: Date.parse('2023-12-01T00:00:00Z'),
-                        },
-                    ],
-                },
-            },
-            updatedAt: new Date().toISOString(),
-        };
-        mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
-        const result = await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
-        expect(result).toBeDefined();
-        expect(mockInvokeFunction).not.toHaveBeenCalled();
-    });
-    it('should NOT mutate the original object when stripping timestamps', async () => {
-        const originalAddress = {
-            city: 'Original City',
-            s: ADDRESS_INFO_SOURCE.INPUT,
-            cra: Date.parse('2024-01-01T00:00:00Z'),
-            upa: Date.parse('2024-01-15T00:00:00Z'),
-        };
-        const incomingIdentity = {
-            identityId: 'identity456',
-            traits: {
-                emails: ['test@email.com'],
-                addresses: [{ ...originalAddress }],
-            },
-        };
-        const cachedResponse = {
-            pk: `identity#${pixelId}#identity456`,
-            pixelId,
-            identityId: 'identity456',
-            response: {
-                identityId: 'identity456',
-                traits: {
-                    emails: ['test@email.com'],
-                    addresses: [
-                        {
-                            city: 'Original City',
-                            s: ADDRESS_INFO_SOURCE.INPUT,
-                            cra: Date.parse('2023-06-01T00:00:00Z'),
-                            upa: Date.parse('2023-06-15T00:00:00Z'),
-                        },
-                    ],
-                },
-            },
-            updatedAt: new Date().toISOString(),
-        };
-        mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
-        await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
-        expect(incomingIdentity.traits?.addresses?.[0]).toHaveProperty('cra');
-        expect(incomingIdentity.traits?.addresses?.[0]).toHaveProperty('upa');
-        expect(cachedResponse.response.traits?.addresses?.[0]).toHaveProperty('cra');
-        expect(cachedResponse.response.traits?.addresses?.[0]).toHaveProperty('upa');
-    });
-    it('should handle identity with no addresses', async () => {
-        const incomingIdentity = {
-            identityId: 'identity456',
-            traits: {
-                emails: ['test@email.com'],
-            },
-        };
-        const cachedResponse = {
-            pk: `identity#${pixelId}#identity456`,
-            pixelId,
-            identityId: 'identity456',
-            response: {
-                identityId: 'identity456',
-                traits: {
-                    emails: ['test@email.com'],
-                },
-            },
-            updatedAt: new Date().toISOString(),
-        };
-        mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
-        const result = await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
-        expect(result).toBeDefined();
-        expect(mockInvokeFunction).not.toHaveBeenCalled();
-    });
-    it('should handle identity with empty addresses array', async () => {
-        const incomingIdentity = {
-            identityId: 'identity456',
-            traits: {
-                emails: ['test@email.com'],
-                addresses: [],
-            },
-        };
-        const cachedResponse = {
-            pk: `identity#${pixelId}#identity456`,
-            pixelId,
-            identityId: 'identity456',
-            response: {
-                identityId: 'identity456',
-                traits: {
-                    emails: ['test@email.com'],
-                    addresses: [],
-                },
-            },
-            updatedAt: new Date().toISOString(),
-        };
-        mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
-        const result = await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
-        expect(result).toBeDefined();
-        expect(mockInvokeFunction).not.toHaveBeenCalled();
-    });
-    it('should handle addresses without cra/upa (no-op)', async () => {
-        const incomingIdentity = {
-            identityId: 'identity456',
-            traits: {
-                emails: ['test@email.com'],
-                addresses: [{ city: 'Simple City', s: ADDRESS_INFO_SOURCE.INPUT }],
-            },
-        };
-        const cachedResponse = {
-            pk: `identity#${pixelId}#identity456`,
-            pixelId,
-            identityId: 'identity456',
-            response: {
-                identityId: 'identity456',
-                traits: {
-                    emails: ['test@email.com'],
-                    addresses: [{ city: 'Simple City', s: ADDRESS_INFO_SOURCE.INPUT }],
-                },
-            },
-            updatedAt: new Date().toISOString(),
-        };
-        mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
-        const result = await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
-        expect(result).toBeDefined();
-        expect(mockInvokeFunction).not.toHaveBeenCalled();
-    });
-});
-describe('Identity Cache fastDeepEqual with Timestamp Stripping', () => {
-    const pixelId = 'pixel123';
-    const lambdaArn = 'arn:aws:lambda:us-east-1:123456789:function:identity-private';
-    beforeEach(() => {
-        jest.clearAllMocks();
-        mockedDynamoDbClient.safeGet.mockReset();
-        mockedDynamoDbClient.safeBatchWrite.mockReset();
-        mockInvokeFunction.mockReset();
-        IdentityCacheDynamoDbService.lambdaInvokeClient = undefined;
-    });
-    it('should treat cached and merged as equal when they differ ONLY in cra/upa', async () => {
-        const incomingIdentity = {
-            identityId: 'identity456',
-            traits: {
-                emails: ['test@email.com'],
-                addresses: [
-                    {
-                        city: 'Same City',
-                        province: 'Same State',
-                        country: 'Same Country',
-                        s: ADDRESS_INFO_SOURCE.INPUT,
-                        cra: Date.parse('2024-06-01T00:00:00Z'),
-                        upa: Date.parse('2024-06-15T00:00:00Z'),
-                    },
-                ],
-            },
-        };
-        const cachedResponse = {
-            pk: `identity#${pixelId}#identity456`,
-            pixelId,
-            identityId: 'identity456',
-            response: {
-                identityId: 'identity456',
-                traits: {
-                    emails: ['test@email.com'],
-                    addresses: [
-                        {
-                            city: 'Same City',
-                            province: 'Same State',
-                            country: 'Same Country',
-                            s: ADDRESS_INFO_SOURCE.INPUT,
-                            cra: Date.parse('2024-01-01T00:00:00Z'),
-                            upa: Date.parse('2024-01-15T00:00:00Z'),
-                        },
-                    ],
-                },
-            },
-            updatedAt: new Date().toISOString(),
-        };
-        mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
-        const result = await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
-        expect(result).toBeDefined();
-        expect(mockInvokeFunction).not.toHaveBeenCalled();
-        expect(mockedDynamoDbClient.safeBatchWrite).not.toHaveBeenCalled();
-    });
-    it('should treat cached and merged as NOT equal when address content differs (plus cra/upa)', async () => {
-        const incomingIdentity = {
-            identityId: 'identity456',
-            traits: {
-                emails: ['test@email.com'],
-                addresses: [
-                    {
-                        city: 'Different City',
-                        province: 'Same State',
-                        s: ADDRESS_INFO_SOURCE.INPUT,
-                        cra: Date.parse('2024-06-01T00:00:00Z'),
-                        upa: Date.parse('2024-06-15T00:00:00Z'),
-                    },
-                ],
-            },
-        };
-        const cachedResponse = {
-            pk: `identity#${pixelId}#identity456`,
-            pixelId,
-            identityId: 'identity456',
-            response: {
-                identityId: 'identity456',
-                traits: {
-                    emails: ['test@email.com'],
-                    addresses: [
-                        {
-                            city: 'Original City',
-                            province: 'Same State',
-                            s: ADDRESS_INFO_SOURCE.INPUT,
-                            cra: Date.parse('2024-01-01T00:00:00Z'),
-                            upa: Date.parse('2024-01-15T00:00:00Z'),
-                        },
-                    ],
-                },
-            },
-            updatedAt: new Date().toISOString(),
-        };
-        mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
-        const result = await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
-        expect(result).toBeDefined();
-    });
-});
-describe('Identity Cache Logging Levels', () => {
-    const pixelId = 'pixel123';
-    const lambdaArn = 'arn:aws:lambda:us-east-1:123456789:function:identity-private';
-    beforeEach(() => {
-        jest.clearAllMocks();
-        mockedDynamoDbClient.safeGet.mockReset();
-        mockedDynamoDbClient.safeBatchWrite.mockReset();
-        mockInvokeFunction.mockReset();
-        IdentityCacheDynamoDbService.lambdaInvokeClient = undefined;
-    });
-    it('should log at debug level when cache is fresh (deep equal)', async () => {
-        const incomingIdentity = {
-            identityId: 'identity456',
-            traits: {
-                emails: ['test@email.com'],
-            },
-        };
-        const cachedResponse = {
-            pk: `identity#${pixelId}#identity456`,
-            pixelId,
-            identityId: 'identity456',
-            response: {
-                identityId: 'identity456',
-                traits: {
-                    emails: ['test@email.com'],
-                },
-            },
-            updatedAt: new Date().toISOString(),
-        };
-        mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
-        await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
-        expect(mockedLogger.debug).toHaveBeenCalledWith(expect.stringContaining('identity cache'), expect.any(Object));
-        expect(mockInvokeFunction).not.toHaveBeenCalled();
-        expect(mockedDynamoDbClient.safeBatchWrite).not.toHaveBeenCalled();
-    });
-    it('should log at info level for ADDRESS_UPDATE path', async () => {
-        const incomingIdentity = {
-            identityId: 'identity456',
-            traits: {
-                emails: ['test@email.com'],
-                addresses: [{ city: 'New City', s: ADDRESS_INFO_SOURCE.INPUT }],
-            },
-        };
-        const cachedResponse = {
-            pk: `identity#${pixelId}#identity456`,
-            pixelId,
-            identityId: 'identity456',
-            response: {
-                identityId: 'identity456',
-                traits: {
-                    emails: ['test@email.com'],
-                    addresses: [],
-                },
-            },
-            updatedAt: new Date().toISOString(),
-        };
-        mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
-        await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
-        expect(mockedLogger.info).toHaveBeenCalledWith('identity cache write: address update only (skipping Neptune)', expect.objectContaining({
-            writeReason: CACHE_WRITE_REASON.ADDRESS_UPDATE,
-            staleTraits: expect.any(Array),
-        }));
-    });
-    it('should log at info level for IDENTITY_STALE path with traitChanges', async () => {
-        const incomingIdentity = {
-            identityId: 'identity456',
-            traits: {
-                emails: ['old@email.com', 'new@email.com'],
-            },
-        };
-        const cachedResponse = {
-            pk: `identity#${pixelId}#identity456`,
-            pixelId,
-            identityId: 'identity456',
-            response: {
-                identityId: 'identity456',
-                traits: {
-                    emails: ['old@email.com'],
-                },
-            },
-            updatedAt: new Date().toISOString(),
-        };
-        mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
-        mockInvokeFunction.mockResolvedValueOnce({
-            statusCode: 200,
-            body: JSON.stringify({
-                identity: {
-                    identityId: 'identity456',
-                    traits: { emails: ['old@email.com', 'new@email.com'] },
-                },
-            }),
-        });
-        await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
-        expect(mockedLogger.info).toHaveBeenCalledWith('identity cache write: stale identity traits update', expect.objectContaining({
-            writeReason: CACHE_WRITE_REASON.STALE_TRAITS,
-            staleTraits: expect.arrayContaining(['emails']),
-            traitChanges: expect.any(Object),
-        }));
-    });
-});
-describe('getIdentityFromCache staleness tier results', () => {
-    const pixelId = 'pixel123';
-    beforeEach(() => {
-        jest.clearAllMocks();
-        mockedDynamoDbClient.safeGet.mockReset();
-    });
-    it('should return staleTier NONE when cached and incoming are deep equal', async () => {
-        const incomingIdentity = {
-            identityId: 'identity456',
-            traits: {
-                emails: ['test@email.com'],
-            },
-        };
-        const cachedResponse = {
-            pk: `identity#${pixelId}#identity456`,
-            pixelId,
-            identityId: 'identity456',
-            response: {
-                identityId: 'identity456',
-                traits: {
-                    emails: ['test@email.com'],
-                },
-            },
-            updatedAt: new Date().toISOString(),
-        };
-        mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
-        const result = await IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, incomingIdentity);
-        expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.NONE);
-        expect(result.isCacheStale).toBe(false);
-        expect(result.skipNeptune).toBeUndefined();
-    });
-    it('should return staleTier ADDRESS_UPDATE and skipNeptune=true for new non-IP address', async () => {
-        const incomingIdentity = {
-            identityId: 'identity456',
-            traits: {
-                emails: ['test@email.com'],
-                addresses: [{ city: 'New City', s: ADDRESS_INFO_SOURCE.INPUT }],
-            },
-        };
-        const cachedResponse = {
-            pk: `identity#${pixelId}#identity456`,
-            pixelId,
-            identityId: 'identity456',
-            response: {
-                identityId: 'identity456',
-                traits: {
-                    emails: ['test@email.com'],
-                    addresses: [],
-                },
-            },
-            updatedAt: new Date().toISOString(),
-        };
-        mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
-        const result = await IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, incomingIdentity);
-        expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.ADDRESS_UPDATE);
-        expect(result.isCacheStale).toBe(true);
-        expect(result.skipNeptune).toBe(true);
-        expect(result.writeReason).toBe(CACHE_WRITE_REASON.ADDRESS_UPDATE);
-    });
-    it('should return staleTier IDENTITY_STALE and skipNeptune=false for new email', async () => {
-        const incomingIdentity = {
-            identityId: 'identity456',
-            traits: {
-                emails: ['old@email.com', 'new@email.com'],
-            },
-        };
-        const cachedResponse = {
-            pk: `identity#${pixelId}#identity456`,
-            pixelId,
-            identityId: 'identity456',
-            response: {
-                identityId: 'identity456',
-                traits: {
-                    emails: ['old@email.com'],
-                },
-            },
-            updatedAt: new Date().toISOString(),
-        };
-        mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
-        const result = await IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, incomingIdentity);
-        expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.IDENTITY_STALE);
-        expect(result.isCacheStale).toBe(true);
-        expect(result.skipNeptune).toBe(false);
-        expect(result.writeReason).toBe(CACHE_WRITE_REASON.STALE_TRAITS);
-    });
-});
+import { ADDRESS_INFO_SOURCE } from '@adtrackify/at-tracking-event-types';
+import { IDENTITY_CACHE_STALENESS_TIER } from '../../helpers/identity-cache-helper';
+import { CACHE_WRITE_REASON } from '../../services/db/identity-cache-dynamodb-service';
+const mockInvokeFunction = jest.fn();
+jest.mock('../../clients/index.js', () => ({
+    DynamoDbClient: {
+        safeGet: jest.fn(),
+        safePut: jest.fn(),
+        safeDelete: jest.fn(),
+        safeBatchGet: jest.fn(),
+        safeBatchWrite: jest.fn(),
+        safeQueryByGSI: jest.fn(),
+        batchWrite: jest.fn(),
+    },
+    LambdaInvokeClient: jest.fn().mockImplementation(() => ({
+        invokeFunction: mockInvokeFunction,
+    })),
+}));
+jest.mock('../../helpers/index.js', () => ({
+    Logger: {
+        debug: jest.fn(),
+        info: jest.fn(),
+        warn: jest.fn(),
+        error: jest.fn(),
+    },
+}));
+import { IdentityCacheDynamoDbService, } from '../../services/db/identity-cache-dynamodb-service.js';
+import { DynamoDbClient } from '../../clients/index.js';
+import { Logger } from '../../helpers/index.js';
+const mockedDynamoDbClient = DynamoDbClient;
+const mockedLogger = Logger;
+describe('Identity Cache Three-Tier Routing', () => {
+    const pixelId = 'pixel123';
+    const lambdaArn = 'arn:aws:lambda:us-east-1:123456789:function:identity-private';
+    beforeEach(() => {
+        jest.clearAllMocks();
+        mockedDynamoDbClient.safeGet.mockReset();
+        mockedDynamoDbClient.safePut.mockReset();
+        mockedDynamoDbClient.safeDelete.mockReset();
+        mockedDynamoDbClient.safeBatchGet.mockReset();
+        mockedDynamoDbClient.safeBatchWrite.mockReset();
+        mockedDynamoDbClient.safeQueryByGSI.mockReset();
+        mockedDynamoDbClient.batchWrite.mockReset();
+        mockInvokeFunction.mockReset();
+        IdentityCacheDynamoDbService.lambdaInvokeClient = undefined;
+    });
+    describe('TIER: VOLATILE_ONLY — Returns merged identity, NO Neptune, NO cache write', () => {
+        it('should return merged identity without Neptune call when only ipAddress is stale', async () => {
+            const incomingIdentity = {
+                identityId: 'identity456',
+                traits: {
+                    emails: ['test@email.com'],
+                    ipAddress: '10.0.0.1',
+                },
+            };
+            const cachedResponse = {
+                pk: `identity#${pixelId}#identity456`,
+                pixelId,
+                identityId: 'identity456',
+                response: {
+                    identityId: 'identity456',
+                    traits: {
+                        emails: ['test@email.com'],
+                        ipAddress: '192.168.1.1',
+                    },
+                },
+                updatedAt: new Date().toISOString(),
+            };
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+            const result = await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
+            expect(result).toBeDefined();
+            expect(result?.identityId).toBe('identity456');
+            expect(mockInvokeFunction).not.toHaveBeenCalled();
+            expect(mockedDynamoDbClient.safeBatchWrite).not.toHaveBeenCalled();
+        });
+        it('should return merged identity without Neptune call when only userAgent is stale', async () => {
+            const incomingIdentity = {
+                identityId: 'identity456',
+                traits: {
+                    emails: ['test@email.com'],
+                    userAgent: 'Chrome/120.0',
+                },
+            };
+            const cachedResponse = {
+                pk: `identity#${pixelId}#identity456`,
+                pixelId,
+                identityId: 'identity456',
+                response: {
+                    identityId: 'identity456',
+                    traits: {
+                        emails: ['test@email.com'],
+                        userAgent: 'Mozilla/5.0',
+                    },
+                },
+                updatedAt: new Date().toISOString(),
+            };
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+            const result = await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
+            expect(result).toBeDefined();
+            expect(mockInvokeFunction).not.toHaveBeenCalled();
+            expect(mockedDynamoDbClient.safeBatchWrite).not.toHaveBeenCalled();
+        });
+        it('should return merged identity without Neptune call when only IP-sourced addresses are stale', async () => {
+            const incomingIdentity = {
+                identityId: 'identity456',
+                traits: {
+                    emails: ['test@email.com'],
+                    addresses: [{ city: 'New York', s: ADDRESS_INFO_SOURCE.IP_ADDRESS }],
+                },
+            };
+            const cachedResponse = {
+                pk: `identity#${pixelId}#identity456`,
+                pixelId,
+                identityId: 'identity456',
+                response: {
+                    identityId: 'identity456',
+                    traits: {
+                        emails: ['test@email.com'],
+                        addresses: [{ city: 'Chicago', s: ADDRESS_INFO_SOURCE.IP_ADDRESS }],
+                    },
+                },
+                updatedAt: new Date().toISOString(),
+            };
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+            const result = await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
+            expect(result).toBeDefined();
+            expect(mockInvokeFunction).not.toHaveBeenCalled();
+            expect(mockedDynamoDbClient.safeBatchWrite).not.toHaveBeenCalled();
+        });
+    });
+    describe('TIER: ADDRESS_UPDATE — Writes to cache, NO Neptune call', () => {
+        it('should write to cache but skip Neptune when new non-IP address is added', async () => {
+            const incomingIdentity = {
+                identityId: 'identity456',
+                traits: {
+                    emails: ['test@email.com'],
+                    addresses: [{ city: 'Boston', firstName: 'John', s: ADDRESS_INFO_SOURCE.INPUT }],
+                },
+            };
+            const cachedResponse = {
+                pk: `identity#${pixelId}#identity456`,
+                pixelId,
+                identityId: 'identity456',
+                response: {
+                    identityId: 'identity456',
+                    traits: {
+                        emails: ['test@email.com'],
+                        addresses: [],
+                    },
+                },
+                updatedAt: new Date().toISOString(),
+            };
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+            const result = await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
+            expect(result).toBeDefined();
+            expect(result?.traits?.addresses).toHaveLength(1);
+            expect(mockInvokeFunction).not.toHaveBeenCalled();
+            expect(mockedDynamoDbClient.safeBatchWrite).toHaveBeenCalled();
+        });
+        it('should write to cache and skip Neptune when address with PII but no source is added', async () => {
+            const incomingIdentity = {
+                identityId: 'identity456',
+                traits: {
+                    emails: ['test@email.com'],
+                    addresses: [{ city: 'Miami', lastName: 'Smith' }],
+                },
+            };
+            const cachedResponse = {
+                pk: `identity#${pixelId}#identity456`,
+                pixelId,
+                identityId: 'identity456',
+                response: {
+                    identityId: 'identity456',
+                    traits: {
+                        emails: ['test@email.com'],
+                        addresses: [],
+                    },
+                },
+                updatedAt: new Date().toISOString(),
+            };
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+            const result = await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
+            expect(result).toBeDefined();
+            expect(mockInvokeFunction).not.toHaveBeenCalled();
+            expect(mockedDynamoDbClient.safeBatchWrite).toHaveBeenCalled();
+        });
+        it('should log with writeReason ADDRESS_UPDATE and staleTraits', async () => {
+            const incomingIdentity = {
+                identityId: 'identity456',
+                traits: {
+                    emails: ['test@email.com'],
+                    addresses: [{ city: 'Seattle', s: ADDRESS_INFO_SOURCE.INPUT }],
+                },
+            };
+            const cachedResponse = {
+                pk: `identity#${pixelId}#identity456`,
+                pixelId,
+                identityId: 'identity456',
+                response: {
+                    identityId: 'identity456',
+                    traits: {
+                        emails: ['test@email.com'],
+                        addresses: [],
+                    },
+                },
+                updatedAt: new Date().toISOString(),
+            };
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+            await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
+            expect(mockedLogger.info).toHaveBeenCalledWith('IdentityCache - identity cache write: address update only (skipping Neptune)', expect.objectContaining({
+                pixelId,
+                writeReason: CACHE_WRITE_REASON.ADDRESS_UPDATE,
+                staleTier: IDENTITY_CACHE_STALENESS_TIER.ADDRESS_UPDATE,
+            }));
+        });
+    });
+    describe('TIER: IDENTITY_STALE — Calls Neptune AND writes to cache', () => {
+        it('should call Neptune and write to cache when emails are stale', async () => {
+            const incomingIdentity = {
+                identityId: 'identity456',
+                traits: {
+                    emails: ['old@email.com', 'new@email.com'],
+                },
+            };
+            const cachedResponse = {
+                pk: `identity#${pixelId}#identity456`,
+                pixelId,
+                identityId: 'identity456',
+                response: {
+                    identityId: 'identity456',
+                    traits: {
+                        emails: ['old@email.com'],
+                    },
+                },
+                updatedAt: new Date().toISOString(),
+            };
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+            mockInvokeFunction.mockResolvedValueOnce({
+                statusCode: 200,
+                body: JSON.stringify({
+                    identity: {
+                        identityId: 'identity456',
+                        traits: { emails: ['old@email.com', 'new@email.com', 'resolved@email.com'] },
+                    },
+                }),
+            });
+            const result = await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
+            expect(result).toBeDefined();
+            expect(mockInvokeFunction).toHaveBeenCalled();
+            expect(mockedDynamoDbClient.safeBatchWrite).toHaveBeenCalled();
+        });
+        it('should call Neptune and write to cache when phones are stale', async () => {
+            const incomingIdentity = {
+                identityId: 'identity456',
+                traits: {
+                    phones: ['+1234567890', '+9876543210'],
+                },
+            };
+            const cachedResponse = {
+                pk: `identity#${pixelId}#identity456`,
+                pixelId,
+                identityId: 'identity456',
+                response: {
+                    identityId: 'identity456',
+                    traits: {
+                        phones: ['+1234567890'],
+                    },
+                },
+                updatedAt: new Date().toISOString(),
+            };
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+            mockInvokeFunction.mockResolvedValueOnce({
+                statusCode: 200,
+                body: JSON.stringify({
+                    identity: {
+                        identityId: 'identity456',
+                        traits: { phones: ['+1234567890', '+9876543210'] },
+                    },
+                }),
+            });
+            const result = await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
+            expect(result).toBeDefined();
+            expect(mockInvokeFunction).toHaveBeenCalled();
+            expect(mockedDynamoDbClient.safeBatchWrite).toHaveBeenCalled();
+        });
+        it('should log with writeReason STALE_TRAITS, staleTraits, and traitChanges', async () => {
+            const incomingIdentity = {
+                identityId: 'identity456',
+                traits: {
+                    emails: ['old@email.com', 'new@email.com'],
+                },
+            };
+            const cachedResponse = {
+                pk: `identity#${pixelId}#identity456`,
+                pixelId,
+                identityId: 'identity456',
+                response: {
+                    identityId: 'identity456',
+                    traits: { emails: ['old@email.com'] },
+                },
+                updatedAt: new Date().toISOString(),
+            };
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+            mockInvokeFunction.mockResolvedValueOnce({
+                statusCode: 200,
+                body: JSON.stringify({
+                    identity: {
+                        identityId: 'identity456',
+                        traits: { emails: ['old@email.com', 'new@email.com'] },
+                    },
+                }),
+            });
+            await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
+            expect(mockedLogger.info).toHaveBeenCalledWith('IdentityCache - identity cache write: stale_traits_update', expect.objectContaining({
+                pixelId,
+                writeReason: CACHE_WRITE_REASON.STALE_TRAITS,
+                staleTier: IDENTITY_CACHE_STALENESS_TIER.IDENTITY_STALE,
+                staleTraits: expect.arrayContaining(['emails']),
+            }));
+        });
+    });
+    describe('CACHE_MISS — Calls Neptune AND writes to cache', () => {
+        it('should call Neptune and write to cache on complete cache miss', async () => {
+            const incomingIdentity = {
+                identityId: 'identity456',
+                traits: { emails: ['test@email.com'] },
+            };
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
+            mockInvokeFunction.mockResolvedValueOnce({
+                statusCode: 200,
+                body: JSON.stringify({
+                    identity: {
+                        identityId: 'identity456',
+                        traits: { emails: ['test@email.com'] },
+                    },
+                }),
+            });
+            const result = await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
+            expect(result).toBeDefined();
+            expect(mockInvokeFunction).toHaveBeenCalled();
+            expect(mockedDynamoDbClient.safeBatchWrite).toHaveBeenCalled();
+        });
+        it('should log with writeReason CACHE_MISS', async () => {
+            const incomingIdentity = {
+                identityId: 'identity456',
+                traits: { emails: ['test@email.com'] },
+            };
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
+            mockInvokeFunction.mockResolvedValueOnce({
+                statusCode: 200,
+                body: JSON.stringify({
+                    identity: {
+                        identityId: 'identity456',
+                        traits: { emails: ['test@email.com'] },
+                    },
+                }),
+            });
+            await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
+            expect(mockedLogger.info).toHaveBeenCalledWith('IdentityCache - identity cache write: new_identity', expect.objectContaining({
+                pixelId,
+                writeReason: CACHE_WRITE_REASON.CACHE_MISS,
+            }));
+        });
+    });
+    describe('EMAIL_POINTER_DISCOVERY — Calls Neptune with discovered identityId', () => {
+        it('should call Neptune with discovered identityId from email pointer', async () => {
+            const incomingIdentity = {
+                traits: { emails: ['test@email.com'] },
+            };
+            const pointerRecord = {
+                pk: `email#${pixelId}#test@email.com`,
+                pixelId,
+                identityId: 'discovered-id',
+                gsi1pk: 'discovered-id',
+                updatedAt: new Date().toISOString(),
+            };
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(pointerRecord);
+            mockInvokeFunction.mockResolvedValueOnce({
+                statusCode: 200,
+                body: JSON.stringify({
+                    identity: {
+                        identityId: 'discovered-id',
+                        traits: { emails: ['test@email.com', 'other@email.com'] },
+                    },
+                }),
+            });
+            const result = await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
+            expect(result?.identityId).toBe('discovered-id');
+            expect(mockInvokeFunction).toHaveBeenCalledWith(lambdaArn, expect.objectContaining({
+                context: {
+                    identity: expect.objectContaining({
+                        identityId: 'discovered-id',
+                    }),
+                },
+            }));
+        });
+    });
+});
+describe('Identity Cache stripAddressTimestamps', () => {
+    const pixelId = 'pixel123';
+    const lambdaArn = 'arn:aws:lambda:us-east-1:123456789:function:identity-private';
+    beforeEach(() => {
+        jest.clearAllMocks();
+        mockedDynamoDbClient.safeGet.mockReset();
+        mockedDynamoDbClient.safeBatchWrite.mockReset();
+        mockInvokeFunction.mockReset();
+        IdentityCacheDynamoDbService.lambdaInvokeClient = undefined;
+    });
+    it('should strip cra and upa from addresses during comparison', async () => {
+        const incomingIdentity = {
+            identityId: 'identity456',
+            traits: {
+                emails: ['test@email.com'],
+                addresses: [
+                    {
+                        city: 'Test City',
+                        s: ADDRESS_INFO_SOURCE.INPUT,
+                        cra: Date.parse('2024-01-01T00:00:00Z'),
+                        upa: Date.parse('2024-01-15T00:00:00Z'),
+                    },
+                ],
+            },
+        };
+        const cachedResponse = {
+            pk: `identity#${pixelId}#identity456`,
+            pixelId,
+            identityId: 'identity456',
+            response: {
+                identityId: 'identity456',
+                traits: {
+                    emails: ['test@email.com'],
+                    addresses: [
+                        {
+                            city: 'Test City',
+                            s: ADDRESS_INFO_SOURCE.INPUT,
+                            cra: Date.parse('2023-06-01T00:00:00Z'),
+                            upa: Date.parse('2023-12-01T00:00:00Z'),
+                        },
+                    ],
+                },
+            },
+            updatedAt: new Date().toISOString(),
+        };
+        mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+        const result = await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
+        expect(result).toBeDefined();
+        expect(mockInvokeFunction).not.toHaveBeenCalled();
+    });
+    it('should NOT mutate the original object when stripping timestamps', async () => {
+        const originalAddress = {
+            city: 'Original City',
+            s: ADDRESS_INFO_SOURCE.INPUT,
+            cra: Date.parse('2024-01-01T00:00:00Z'),
+            upa: Date.parse('2024-01-15T00:00:00Z'),
+        };
+        const incomingIdentity = {
+            identityId: 'identity456',
+            traits: {
+                emails: ['test@email.com'],
+                addresses: [{ ...originalAddress }],
+            },
+        };
+        const cachedResponse = {
+            pk: `identity#${pixelId}#identity456`,
+            pixelId,
+            identityId: 'identity456',
+            response: {
+                identityId: 'identity456',
+                traits: {
+                    emails: ['test@email.com'],
+                    addresses: [
+                        {
+                            city: 'Original City',
+                            s: ADDRESS_INFO_SOURCE.INPUT,
+                            cra: Date.parse('2023-06-01T00:00:00Z'),
+                            upa: Date.parse('2023-06-15T00:00:00Z'),
+                        },
+                    ],
+                },
+            },
+            updatedAt: new Date().toISOString(),
+        };
+        mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+        await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
+        expect(incomingIdentity.traits?.addresses?.[0]).toHaveProperty('cra');
+        expect(incomingIdentity.traits?.addresses?.[0]).toHaveProperty('upa');
+        expect(cachedResponse.response.traits?.addresses?.[0]).toHaveProperty('cra');
+        expect(cachedResponse.response.traits?.addresses?.[0]).toHaveProperty('upa');
+    });
+    it('should handle identity with no addresses', async () => {
+        const incomingIdentity = {
+            identityId: 'identity456',
+            traits: {
+                emails: ['test@email.com'],
+            },
+        };
+        const cachedResponse = {
+            pk: `identity#${pixelId}#identity456`,
+            pixelId,
+            identityId: 'identity456',
+            response: {
+                identityId: 'identity456',
+                traits: {
+                    emails: ['test@email.com'],
+                },
+            },
+            updatedAt: new Date().toISOString(),
+        };
+        mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+        const result = await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
+        expect(result).toBeDefined();
+        expect(mockInvokeFunction).not.toHaveBeenCalled();
+    });
+    it('should handle identity with empty addresses array', async () => {
+        const incomingIdentity = {
+            identityId: 'identity456',
+            traits: {
+                emails: ['test@email.com'],
+                addresses: [],
+            },
+        };
+        const cachedResponse = {
+            pk: `identity#${pixelId}#identity456`,
+            pixelId,
+            identityId: 'identity456',
+            response: {
+                identityId: 'identity456',
+                traits: {
+                    emails: ['test@email.com'],
+                    addresses: [],
+                },
+            },
+            updatedAt: new Date().toISOString(),
+        };
+        mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+        const result = await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
+        expect(result).toBeDefined();
+        expect(mockInvokeFunction).not.toHaveBeenCalled();
+    });
+    it('should handle addresses without cra/upa (no-op)', async () => {
+        const incomingIdentity = {
+            identityId: 'identity456',
+            traits: {
+                emails: ['test@email.com'],
+                addresses: [{ city: 'Simple City', s: ADDRESS_INFO_SOURCE.INPUT }],
+            },
+        };
+        const cachedResponse = {
+            pk: `identity#${pixelId}#identity456`,
+            pixelId,
+            identityId: 'identity456',
+            response: {
+                identityId: 'identity456',
+                traits: {
+                    emails: ['test@email.com'],
+                    addresses: [{ city: 'Simple City', s: ADDRESS_INFO_SOURCE.INPUT }],
+                },
+            },
+            updatedAt: new Date().toISOString(),
+        };
+        mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+        const result = await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
+        expect(result).toBeDefined();
+        expect(mockInvokeFunction).not.toHaveBeenCalled();
+    });
+});
+describe('Identity Cache fastDeepEqual with Timestamp Stripping', () => {
+    const pixelId = 'pixel123';
+    const lambdaArn = 'arn:aws:lambda:us-east-1:123456789:function:identity-private';
+    beforeEach(() => {
+        jest.clearAllMocks();
+        mockedDynamoDbClient.safeGet.mockReset();
+        mockedDynamoDbClient.safeBatchWrite.mockReset();
+        mockInvokeFunction.mockReset();
+        IdentityCacheDynamoDbService.lambdaInvokeClient = undefined;
+    });
+    it('should treat cached and merged as equal when they differ ONLY in cra/upa', async () => {
+        const incomingIdentity = {
+            identityId: 'identity456',
+            traits: {
+                emails: ['test@email.com'],
+                addresses: [
+                    {
+                        city: 'Same City',
+                        province: 'Same State',
+                        country: 'Same Country',
+                        s: ADDRESS_INFO_SOURCE.INPUT,
+                        cra: Date.parse('2024-06-01T00:00:00Z'),
+                        upa: Date.parse('2024-06-15T00:00:00Z'),
+                    },
+                ],
+            },
+        };
+        const cachedResponse = {
+            pk: `identity#${pixelId}#identity456`,
+            pixelId,
+            identityId: 'identity456',
+            response: {
+                identityId: 'identity456',
+                traits: {
+                    emails: ['test@email.com'],
+                    addresses: [
+                        {
+                            city: 'Same City',
+                            province: 'Same State',
+                            country: 'Same Country',
+                            s: ADDRESS_INFO_SOURCE.INPUT,
+                            cra: Date.parse('2024-01-01T00:00:00Z'),
+                            upa: Date.parse('2024-01-15T00:00:00Z'),
+                        },
+                    ],
+                },
+            },
+            updatedAt: new Date().toISOString(),
+        };
+        mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+        const result = await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
+        expect(result).toBeDefined();
+        expect(mockInvokeFunction).not.toHaveBeenCalled();
+        expect(mockedDynamoDbClient.safeBatchWrite).not.toHaveBeenCalled();
+    });
+    it('should treat cached and merged as NOT equal when address content differs (plus cra/upa)', async () => {
+        const incomingIdentity = {
+            identityId: 'identity456',
+            traits: {
+                emails: ['test@email.com'],
+                addresses: [
+                    {
+                        city: 'Different City',
+                        province: 'Same State',
+                        s: ADDRESS_INFO_SOURCE.INPUT,
+                        cra: Date.parse('2024-06-01T00:00:00Z'),
+                        upa: Date.parse('2024-06-15T00:00:00Z'),
+                    },
+                ],
+            },
+        };
+        const cachedResponse = {
+            pk: `identity#${pixelId}#identity456`,
+            pixelId,
+            identityId: 'identity456',
+            response: {
+                identityId: 'identity456',
+                traits: {
+                    emails: ['test@email.com'],
+                    addresses: [
+                        {
+                            city: 'Original City',
+                            province: 'Same State',
+                            s: ADDRESS_INFO_SOURCE.INPUT,
+                            cra: Date.parse('2024-01-01T00:00:00Z'),
+                            upa: Date.parse('2024-01-15T00:00:00Z'),
+                        },
+                    ],
+                },
+            },
+            updatedAt: new Date().toISOString(),
+        };
+        mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+        const result = await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
+        expect(result).toBeDefined();
+    });
+});
+describe('Identity Cache Logging Levels', () => {
+    const pixelId = 'pixel123';
+    const lambdaArn = 'arn:aws:lambda:us-east-1:123456789:function:identity-private';
+    beforeEach(() => {
+        jest.clearAllMocks();
+        mockedDynamoDbClient.safeGet.mockReset();
+        mockedDynamoDbClient.safeBatchWrite.mockReset();
+        mockInvokeFunction.mockReset();
+        IdentityCacheDynamoDbService.lambdaInvokeClient = undefined;
+    });
+    it('should log at debug level when cache is fresh (deep equal)', async () => {
+        const incomingIdentity = {
+            identityId: 'identity456',
+            traits: {
+                emails: ['test@email.com'],
+            },
+        };
+        const cachedResponse = {
+            pk: `identity#${pixelId}#identity456`,
+            pixelId,
+            identityId: 'identity456',
+            response: {
+                identityId: 'identity456',
+                traits: {
+                    emails: ['test@email.com'],
+                },
+            },
+            updatedAt: new Date().toISOString(),
+        };
+        mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+        await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
+        expect(mockedLogger.debug).toHaveBeenCalledWith(expect.stringContaining('IdentityCache - '), expect.any(Object));
+        expect(mockInvokeFunction).not.toHaveBeenCalled();
+        expect(mockedDynamoDbClient.safeBatchWrite).not.toHaveBeenCalled();
+    });
+    it('should log at info level for ADDRESS_UPDATE path', async () => {
+        const incomingIdentity = {
+            identityId: 'identity456',
+            traits: {
+                emails: ['test@email.com'],
+                addresses: [{ city: 'New City', s: ADDRESS_INFO_SOURCE.INPUT }],
+            },
+        };
+        const cachedResponse = {
+            pk: `identity#${pixelId}#identity456`,
+            pixelId,
+            identityId: 'identity456',
+            response: {
+                identityId: 'identity456',
+                traits: {
+                    emails: ['test@email.com'],
+                    addresses: [],
+                },
+            },
+            updatedAt: new Date().toISOString(),
+        };
+        mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+        await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
+        expect(mockedLogger.info).toHaveBeenCalledWith('IdentityCache - identity cache write: address update only (skipping Neptune)', expect.objectContaining({
+            writeReason: CACHE_WRITE_REASON.ADDRESS_UPDATE,
+            staleTraits: expect.any(Array),
+        }));
+    });
+    it('should log at info level for IDENTITY_STALE path with traitChanges', async () => {
+        const incomingIdentity = {
+            identityId: 'identity456',
+            traits: {
+                emails: ['old@email.com', 'new@email.com'],
+            },
+        };
+        const cachedResponse = {
+            pk: `identity#${pixelId}#identity456`,
+            pixelId,
+            identityId: 'identity456',
+            response: {
+                identityId: 'identity456',
+                traits: {
+                    emails: ['old@email.com'],
+                },
+            },
+            updatedAt: new Date().toISOString(),
+        };
+        mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+        mockInvokeFunction.mockResolvedValueOnce({
+            statusCode: 200,
+            body: JSON.stringify({
+                identity: {
+                    identityId: 'identity456',
+                    traits: { emails: ['old@email.com', 'new@email.com'] },
+                },
+            }),
+        });
+        await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
+        expect(mockedLogger.info).toHaveBeenCalledWith('IdentityCache - identity cache write: stale_traits_update', expect.objectContaining({
+            writeReason: CACHE_WRITE_REASON.STALE_TRAITS,
+            staleTraits: expect.arrayContaining(['emails']),
+            traitChanges: expect.any(Object),
+        }));
+    });
+});
+describe('getIdentityFromCache staleness tier results', () => {
+    const pixelId = 'pixel123';
+    beforeEach(() => {
+        jest.clearAllMocks();
+        mockedDynamoDbClient.safeGet.mockReset();
+    });
+    it('should return staleTier NONE when cached and incoming are deep equal', async () => {
+        const incomingIdentity = {
+            identityId: 'identity456',
+            traits: {
+                emails: ['test@email.com'],
+            },
+        };
+        const cachedResponse = {
+            pk: `identity#${pixelId}#identity456`,
+            pixelId,
+            identityId: 'identity456',
+            response: {
+                identityId: 'identity456',
+                traits: {
+                    emails: ['test@email.com'],
+                },
+            },
+            updatedAt: new Date().toISOString(),
+        };
+        mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+        const result = await IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, incomingIdentity);
+        expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.NONE);
+        expect(result.isCacheStale).toBe(false);
+        expect(result.skipNeptune).toBeUndefined();
+    });
+    it('should return staleTier ADDRESS_UPDATE and skipNeptune=true for new non-IP address', async () => {
+        const incomingIdentity = {
+            identityId: 'identity456',
+            traits: {
+                emails: ['test@email.com'],
+                addresses: [{ city: 'New City', s: ADDRESS_INFO_SOURCE.INPUT }],
+            },
+        };
+        const cachedResponse = {
+            pk: `identity#${pixelId}#identity456`,
+            pixelId,
+            identityId: 'identity456',
+            response: {
+                identityId: 'identity456',
+                traits: {
+                    emails: ['test@email.com'],
+                    addresses: [],
+                },
+            },
+            updatedAt: new Date().toISOString(),
+        };
+        mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+        const result = await IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, incomingIdentity);
+        expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.ADDRESS_UPDATE);
+        expect(result.isCacheStale).toBe(true);
+        expect(result.skipNeptune).toBe(true);
+        expect(result.writeReason).toBe(CACHE_WRITE_REASON.ADDRESS_UPDATE);
+    });
+    it('should return staleTier IDENTITY_STALE and skipNeptune=false for new email', async () => {
+        const incomingIdentity = {
+            identityId: 'identity456',
+            traits: {
+                emails: ['old@email.com', 'new@email.com'],
+            },
+        };
+        const cachedResponse = {
+            pk: `identity#${pixelId}#identity456`,
+            pixelId,
+            identityId: 'identity456',
+            response: {
+                identityId: 'identity456',
+                traits: {
+                    emails: ['old@email.com'],
+                },
+            },
+            updatedAt: new Date().toISOString(),
+        };
+        mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+        const result = await IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, incomingIdentity);
+        expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.IDENTITY_STALE);
+        expect(result.isCacheStale).toBe(true);
+        expect(result.skipNeptune).toBe(false);
+        expect(result.writeReason).toBe(CACHE_WRITE_REASON.STALE_TRAITS);
+    });
+});
 //# sourceMappingURL=identity-cache-tier-routing.spec.js.map