@adtrackify/at-service-common 4.0.4 → 4.0.6

package/dist/esm/__tests__/identity-cache/identity-cache-dynamodb-service.spec.js

@@ -1,1139 +1,1281 @@
-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';
-const mockedDynamoDbClient = DynamoDbClient;
-describe('IdentityCacheDynamoDbService', () => {
-    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('getIdentityWithCaching', () => {
-        const pixelId = 'pixel123';
-        const lambdaArn = 'arn:aws:lambda:us-east-1:123456789:function:identity-private';
-        describe('cache hit (fresh cache)', () => {
-            it('should return cached identity without invoking Neptune Lambda', 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(result?.identityId).toBe('identity456');
-                expect(mockInvokeFunction).not.toHaveBeenCalled();
-            });
-        });
-        describe('cache miss', () => {
-            it('should invoke Neptune Lambda and return resolved identity', async () => {
-                const incomingIdentity = {
-                    identityId: 'identity456',
-                    traits: { emails: ['test@email.com'] },
-                };
-                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
-                mockInvokeFunction.mockResolvedValueOnce({
-                    statusCode: 200,
-                    body: JSON.stringify({
-                        identity: {
-                            identityId: 'resolved-identity',
-                            traits: { emails: ['test@email.com', 'resolved@email.com'] },
-                        },
-                    }),
-                });
-                const result = await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
-                expect(mockInvokeFunction).toHaveBeenCalledWith(lambdaArn, {
-                    pixelId,
-                    context: { identity: incomingIdentity },
-                });
-                expect(result?.identityId).toBe('resolved-identity');
-                expect(mockedDynamoDbClient.safeBatchWrite).toHaveBeenCalled();
-            });
-            it('should return incomingIdentity when Neptune Lambda fails to resolve', async () => {
-                const incomingIdentity = {
-                    identityId: 'identity456',
-                    traits: { emails: ['test@email.com'] },
-                };
-                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
-                mockInvokeFunction.mockResolvedValueOnce({
-                    statusCode: 200,
-                    body: JSON.stringify({ identity: undefined }),
-                });
-                const result = await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
-                expect(result).toEqual(incomingIdentity);
-            });
-        });
-        describe('cache stale', () => {
-            it('should invoke Neptune Lambda when cache is 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'] },
-                        },
-                    }),
-                });
-                const result = await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
-                expect(mockInvokeFunction).toHaveBeenCalled();
-                expect(result?.identityId).toBe('identity456');
-                expect(result?.traits?.emails).toContain('new@email.com');
-            });
-            it('should use merged cache identity when Neptune fails', 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: 500,
-                    body: 'Internal Server Error',
-                });
-                const result = await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
-                expect(result).toBeDefined();
-                expect(result?.identityId).toBe('identity456');
-            });
-        });
-        describe('Neptune Lambda invocation', () => {
-            it('should write-back Neptune response to cache on success', async () => {
-                const incomingIdentity = {
-                    traits: { emails: ['test@email.com'] },
-                };
-                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
-                mockInvokeFunction.mockResolvedValueOnce({
-                    statusCode: 200,
-                    body: JSON.stringify({
-                        identity: {
-                            identityId: 'neptune-resolved-id',
-                            traits: { emails: ['test@email.com'] },
-                        },
-                    }),
-                });
-                await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
-                expect(mockedDynamoDbClient.safeBatchWrite).toHaveBeenCalled();
-                const writtenItems = mockedDynamoDbClient.safeBatchWrite.mock.calls[0][1];
-                const identityPks = writtenItems.map((item) => item.pk);
-                expect(identityPks).toContain(`identity#${pixelId}#neptune-resolved-id`);
-            });
-            it('should not write to cache when Neptune returns undefined', async () => {
-                const incomingIdentity = {
-                    traits: { emails: ['test@email.com'] },
-                };
-                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
-                mockInvokeFunction.mockResolvedValueOnce({
-                    statusCode: 200,
-                    body: JSON.stringify({ identity: undefined }),
-                });
-                await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
-                expect(mockedDynamoDbClient.safeBatchWrite).not.toHaveBeenCalled();
-            });
-        });
-        describe('error handling (fail-open)', () => {
-            it('should return undefined when pixelId is missing', async () => {
-                const result = await IdentityCacheDynamoDbService.getIdentityWithCaching(null, { identityId: 'test-id' }, lambdaArn);
-                expect(result).toBeUndefined();
-                expect(mockInvokeFunction).not.toHaveBeenCalled();
-            });
-            it('should return undefined when incomingIdentity is missing', async () => {
-                const result = await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, null, lambdaArn);
-                expect(result).toBeUndefined();
-                expect(mockInvokeFunction).not.toHaveBeenCalled();
-            });
-            it('should return undefined when Neptune Lambda throws', async () => {
-                const incomingIdentity = {
-                    identityId: 'identity456',
-                    traits: { emails: ['test@email.com'] },
-                };
-                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
-                mockInvokeFunction.mockRejectedValueOnce(new Error('Lambda invocation failed'));
-                const result = await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
-                expect(result).toEqual(incomingIdentity);
-            });
-            it('should not throw when cache write fails after Neptune success', async () => {
-                const incomingIdentity = {
-                    traits: { emails: ['test@email.com'] },
-                };
-                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
-                mockInvokeFunction.mockResolvedValueOnce({
-                    statusCode: 200,
-                    body: JSON.stringify({
-                        identity: {
-                            identityId: 'neptune-resolved-id',
-                            traits: { emails: ['test@email.com'] },
-                        },
-                    }),
-                });
-                mockedDynamoDbClient.safeBatchWrite.mockRejectedValueOnce(new Error('DynamoDB write failed'));
-                const result = await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
-                expect(result?.identityId).toBe('neptune-resolved-id');
-            });
-        });
-    });
-    describe('Key Builders', () => {
-        describe('buildIdentityPk', () => {
-            it('should build correct pk for identity lookup', async () => {
-                const pixelId = 'pixel123';
-                const identityId = 'identity456';
-                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
-                await IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, { identityId });
-                expect(mockedDynamoDbClient.safeGet).toHaveBeenCalledWith(expect.any(String), 'pk', `identity#${pixelId}#${identityId}`);
-            });
-        });
-        describe('buildEmailPk', () => {
-            it('should build correct pk for email lookup (lowercase)', async () => {
-                const pixelId = 'pixel123';
-                const email = 'Test@Email.COM';
-                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
-                await IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, {
-                    traits: { emails: [email] },
-                });
-                expect(mockedDynamoDbClient.safeGet).toHaveBeenCalledWith(expect.any(String), 'pk', `email#${pixelId}#test@email.com`);
-            });
-        });
-        describe('buildUserIdPk (no longer used for lookup)', () => {
-            it('should NOT lookup by userId (optimization: email-only secondary lookup)', async () => {
-                const pixelId = 'pixel123';
-                const userId = '  user789  ';
-                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
-                await IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, {
-                    traits: { userIds: [userId] },
-                });
-                expect(mockedDynamoDbClient.safeBatchGet).not.toHaveBeenCalled();
-            });
-        });
-    });
-    describe('getIdentityFromCache', () => {
-        const pixelId = 'pixel123';
-        describe('with identityId (primary lookup)', () => {
-            it('should return cache hit when identity found', async () => {
-                const identityId = 'identity456';
-                const cachedResponse = {
-                    pk: `identity#${pixelId}#${identityId}`,
-                    pixelId,
-                    identityId,
-                    response: {
-                        identityId,
-                        traits: { emails: ['test@email.com'] },
-                    },
-                    updatedAt: new Date().toISOString(),
-                };
-                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
-                const result = await IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, {
-                    identityId,
-                    traits: { emails: ['test@email.com'] },
-                });
-                expect(result.resolvedIdentity).toBeDefined();
-                expect(result.resolvedIdentity?.identityId).toBe(identityId);
-                expect(result.isCacheStale).toBe(false);
-            });
-            it('should return cache miss when identity not found', async () => {
-                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
-                const result = await IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, {
-                    identityId: 'unknown-id',
-                });
-                expect(result.resolvedIdentity).toBeUndefined();
-                expect(result.isCacheStale).toBe(true);
-            });
-            it('should NOT fallback to secondary keys when identityId lookup misses', async () => {
-                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
-                await IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, {
-                    identityId: 'unknown-id',
-                    traits: { emails: ['test@email.com'] },
-                });
-                expect(mockedDynamoDbClient.safeBatchGet).not.toHaveBeenCalled();
-            });
-            it('should detect stale cache when new traits present', async () => {
-                const identityId = 'identity456';
-                const cachedResponse = {
-                    pk: `identity#${pixelId}#${identityId}`,
-                    pixelId,
-                    identityId,
-                    response: {
-                        identityId,
-                        traits: { emails: ['old@email.com'] },
-                    },
-                    updatedAt: new Date().toISOString(),
-                };
-                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
-                const result = await IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, {
-                    identityId,
-                    traits: { emails: ['old@email.com', 'new@email.com'] },
-                });
-                expect(result.resolvedIdentity).toBeDefined();
-                expect(result.isCacheStale).toBe(true);
-            });
-        });
-        describe('without identityId (secondary lookup)', () => {
-            it('should use single get for email lookup (pointer-based)', async () => {
-                const pointerRecord = {
-                    pk: `email#${pixelId}#test@email.com`,
-                    pixelId,
-                    identityId: 'resolved-id',
-                    gsi1pk: 'resolved-id',
-                    updatedAt: new Date().toISOString(),
-                };
-                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(pointerRecord);
-                const result = await IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, {
-                    traits: { emails: ['test@email.com'], userIds: ['user123'] },
-                });
-                expect(mockedDynamoDbClient.safeGet).toHaveBeenCalledWith(expect.any(String), 'pk', `email#${pixelId}#test@email.com`);
-                expect(mockedDynamoDbClient.safeBatchGet).not.toHaveBeenCalled();
-                expect(result.resolvedIdentity).toBeDefined();
-                expect(result.resolvedIdentity?.traits?.emails).toContain('test@email.com');
-                expect(result.isCacheStale).toBe(true);
-            });
-            it('should return discovered identityId with stale flag for Neptune resolution', async () => {
-                const pointerRecord = {
-                    pk: `email#${pixelId}#test@email.com`,
-                    pixelId,
-                    identityId: 'discovered-id',
-                    gsi1pk: 'discovered-id',
-                    updatedAt: new Date().toISOString(),
-                };
-                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(pointerRecord);
-                const result = await IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, {
-                    traits: { emails: ['test@email.com'], userIds: ['user123'] },
-                });
-                expect(result.resolvedIdentity).toBeDefined();
-                expect(result.resolvedIdentity?.identityId).toBe('discovered-id');
-                expect(result.isCacheStale).toBe(true);
-            });
-            it('should return cache miss when no secondary keys match', async () => {
-                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
-                const result = await IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, {
-                    traits: { emails: ['unknown@email.com'] },
-                });
-                expect(result.resolvedIdentity).toBeUndefined();
-                expect(result.isCacheStale).toBe(true);
-            });
-            it('should return cache miss when no emails to lookup', async () => {
-                const result = await IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, {
-                    traits: { userIds: ['user123'] },
-                });
-                expect(result.resolvedIdentity).toBeUndefined();
-                expect(result.isCacheStale).toBe(true);
-                expect(mockedDynamoDbClient.safeGet).not.toHaveBeenCalled();
-            });
-            it('should return cache miss when empty traits', async () => {
-                const result = await IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, {
-                    traits: {},
-                });
-                expect(result.resolvedIdentity).toBeUndefined();
-                expect(result.isCacheStale).toBe(true);
-            });
-        });
-        describe('error handling (fail-open)', () => {
-            it('should return cache miss on safeGet error', async () => {
-                mockedDynamoDbClient.safeGet.mockRejectedValueOnce(new Error('DynamoDB error'));
-                const result = await IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, {
-                    identityId: 'test-id',
-                });
-                expect(result.resolvedIdentity).toBeUndefined();
-                expect(result.isCacheStale).toBe(true);
-            });
-            it('should return cache miss on safeGet error for email lookup', async () => {
-                mockedDynamoDbClient.safeGet.mockRejectedValueOnce(new Error('DynamoDB error'));
-                const result = await IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, {
-                    traits: { emails: ['test@email.com'] },
-                });
-                expect(result.resolvedIdentity).toBeUndefined();
-                expect(result.isCacheStale).toBe(true);
-            });
-            it('should return cache miss for null pixelId', async () => {
-                const result = await IdentityCacheDynamoDbService.getIdentityFromCache(null, {
-                    identityId: 'test-id',
-                });
-                expect(result.resolvedIdentity).toBeUndefined();
-                expect(result.isCacheStale).toBe(true);
-            });
-            it('should return cache miss for null incomingIdentity', async () => {
-                const result = await IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, null);
-                expect(result.resolvedIdentity).toBeUndefined();
-                expect(result.isCacheStale).toBe(true);
-            });
-        });
-    });
-    describe('updateIdentityCache', () => {
-        const pixelId = 'pixel123';
-        it('should write identity with email pointer (no full blob on secondary keys)', async () => {
-            const identity = {
-                identityId: 'identity456',
-                traits: {
-                    emails: ['test@email.com', 'other@email.com'],
-                    userIds: ['user1', 'user2'],
-                },
-            };
-            await IdentityCacheDynamoDbService.updateIdentityCache(pixelId, identity);
-            expect(mockedDynamoDbClient.safeBatchWrite).toHaveBeenCalledTimes(1);
-            const writtenItems = mockedDynamoDbClient.safeBatchWrite.mock.calls[0][1];
-            expect(writtenItems).toHaveLength(3);
-            const pks = writtenItems.map((item) => item.pk);
-            expect(pks).toContain(`identity#${pixelId}#identity456`);
-            expect(pks).toContain(`email#${pixelId}#test@email.com`);
-            expect(pks).toContain(`email#${pixelId}#other@email.com`);
-            expect(pks).not.toContain(`user_id#${pixelId}#user1`);
-            expect(pks).not.toContain(`user_id#${pixelId}#user2`);
-            const identityItem = writtenItems.find((item) => item.pk.startsWith('identity#'));
-            expect(identityItem).toBeDefined();
-            expect(identityItem.response).toBeDefined();
-            expect(identityItem.response.identityId).toBe('identity456');
-            const emailItem = writtenItems.find((item) => item.pk.startsWith('email#'));
-            expect(emailItem).toBeDefined();
-            expect(emailItem.response).toBeUndefined();
-            expect(emailItem.identityId).toBe('identity456');
-        });
-        it('should not throw on safeBatchWrite error (fail-open)', async () => {
-            mockedDynamoDbClient.safeBatchWrite.mockRejectedValueOnce(new Error('DynamoDB error'));
-            const identity = {
-                identityId: 'identity456',
-                traits: { emails: ['test@email.com'] },
-            };
-            await expect(IdentityCacheDynamoDbService.updateIdentityCache(pixelId, identity)).resolves.toBeUndefined();
-        });
-        it('should return early for missing identityId', async () => {
-            await IdentityCacheDynamoDbService.updateIdentityCache(pixelId, {});
-            expect(mockedDynamoDbClient.safeBatchWrite).not.toHaveBeenCalled();
-        });
-        it('should return early for missing pixelId', async () => {
-            await IdentityCacheDynamoDbService.updateIdentityCache(null, {
-                identityId: 'test-id',
-            });
-            expect(mockedDynamoDbClient.safeBatchWrite).not.toHaveBeenCalled();
-        });
-        it('should handle identity with no traits', async () => {
-            const identity = {
-                identityId: 'identity456',
-            };
-            await IdentityCacheDynamoDbService.updateIdentityCache(pixelId, identity);
-            const writtenItems = mockedDynamoDbClient.safeBatchWrite.mock.calls[0][1];
-            expect(writtenItems).toHaveLength(1);
-        });
-        it('should include gsi1pk for reverse lookups', async () => {
-            const identity = {
-                identityId: 'identity456',
-                traits: { emails: ['test@email.com'] },
-            };
-            await IdentityCacheDynamoDbService.updateIdentityCache(pixelId, identity);
-            const writtenItems = mockedDynamoDbClient.safeBatchWrite.mock.calls[0][1];
-            for (const item of writtenItems) {
-                expect(item.gsi1pk).toBe('identity456');
-            }
-        });
-    });
-    describe('getIdentityMap', () => {
-        it('should return identity map when found', async () => {
-            const mockMap = {
-                pk: 'identity_map#pixel123#identity456',
-                pixelId: 'pixel123',
-                identityId: 'identity456',
-                linkedIdentities: ['identity789'],
-                updatedAt: new Date().toISOString(),
-            };
-            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(mockMap);
-            const result = await IdentityCacheDynamoDbService.getIdentityMap('pixel123', 'identity456');
-            expect(result).toEqual(mockMap);
-            expect(mockedDynamoDbClient.safeGet).toHaveBeenCalledWith(expect.any(String), 'pk', 'identity_map#pixel123#identity456');
-        });
-        it('should return undefined when not found', async () => {
-            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
-            const result = await IdentityCacheDynamoDbService.getIdentityMap('pixel123', 'identity456');
-            expect(result).toBeUndefined();
-        });
-        it('should return undefined for missing params (fail-open)', async () => {
-            const result = await IdentityCacheDynamoDbService.getIdentityMap('', '');
-            expect(result).toBeUndefined();
-            expect(mockedDynamoDbClient.safeGet).not.toHaveBeenCalled();
-        });
-        it('should return undefined when only pixelId is missing', async () => {
-            const result = await IdentityCacheDynamoDbService.getIdentityMap('', 'identity456');
-            expect(result).toBeUndefined();
-            expect(mockedDynamoDbClient.safeGet).not.toHaveBeenCalled();
-        });
-        it('should return undefined when only identityId is missing', async () => {
-            const result = await IdentityCacheDynamoDbService.getIdentityMap('pixel123', '');
-            expect(result).toBeUndefined();
-            expect(mockedDynamoDbClient.safeGet).not.toHaveBeenCalled();
-        });
-        it('should return undefined on safeGet error (fail-open)', async () => {
-            mockedDynamoDbClient.safeGet.mockRejectedValueOnce(new Error('DynamoDB error'));
-            const result = await IdentityCacheDynamoDbService.getIdentityMap('pixel123', 'identity456');
-            expect(result).toBeUndefined();
-        });
-    });
-    describe('getForcePurgeFlag', () => {
-        it('should return true when flag exists', async () => {
-            mockedDynamoDbClient.safeGet.mockResolvedValueOnce({
-                pk: 'force_purge#pixel123#identity456',
-            });
-            const result = await IdentityCacheDynamoDbService.getForcePurgeFlag('pixel123', 'identity456');
-            expect(result).toBe(true);
-        });
-        it('should return false when flag not found', async () => {
-            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
-            const result = await IdentityCacheDynamoDbService.getForcePurgeFlag('pixel123', 'identity456');
-            expect(result).toBe(false);
-        });
-        it('should return false on error (fail-open)', async () => {
-            mockedDynamoDbClient.safeGet.mockRejectedValueOnce(new Error('DynamoDB error'));
-            const result = await IdentityCacheDynamoDbService.getForcePurgeFlag('pixel123', 'identity456');
-            expect(result).toBe(false);
-        });
-        it('should return false for missing params', async () => {
-            const result = await IdentityCacheDynamoDbService.getForcePurgeFlag('', '');
-            expect(result).toBe(false);
-            expect(mockedDynamoDbClient.safeGet).not.toHaveBeenCalled();
-        });
-    });
-    describe('setForcePurgeFlag', () => {
-        it('should set flag with TTL', async () => {
-            await IdentityCacheDynamoDbService.setForcePurgeFlag('pixel123', 'identity456');
-            expect(mockedDynamoDbClient.safePut).toHaveBeenCalledTimes(1);
-            const putItem = mockedDynamoDbClient.safePut.mock.calls[0][1];
-            expect(putItem.pk).toBe('force_purge#pixel123#identity456');
-            expect(putItem.pixelId).toBe('pixel123');
-            expect(putItem.identityId).toBe('identity456');
-            expect(putItem.ttl).toBeGreaterThan(0);
-        });
-        it('should accept custom TTL', async () => {
-            await IdentityCacheDynamoDbService.setForcePurgeFlag('pixel123', 'identity456', 3600);
-            const putItem = mockedDynamoDbClient.safePut.mock.calls[0][1];
-            expect(putItem.ttl).toBeGreaterThan(0);
-        });
-        it('should include createdAt timestamp', async () => {
-            const before = new Date().toISOString();
-            await IdentityCacheDynamoDbService.setForcePurgeFlag('pixel123', 'identity456');
-            const after = new Date().toISOString();
-            const putItem = mockedDynamoDbClient.safePut.mock.calls[0][1];
-            expect(putItem.createdAt).toBeDefined();
-            expect(putItem.createdAt >= before).toBe(true);
-            expect(putItem.createdAt <= after).toBe(true);
-        });
-        it('should return early when pixelId is missing', async () => {
-            await IdentityCacheDynamoDbService.setForcePurgeFlag('', 'identity456');
-            expect(mockedDynamoDbClient.safePut).not.toHaveBeenCalled();
-        });
-        it('should return early when identityId is missing', async () => {
-            await IdentityCacheDynamoDbService.setForcePurgeFlag('pixel123', '');
-            expect(mockedDynamoDbClient.safePut).not.toHaveBeenCalled();
-        });
-        it('should not throw on error (fail-open)', async () => {
-            mockedDynamoDbClient.safePut.mockRejectedValueOnce(new Error('DynamoDB error'));
-            await expect(IdentityCacheDynamoDbService.setForcePurgeFlag('pixel123', 'identity456')).resolves.toBeUndefined();
-        });
-    });
-    describe('putIdentityMap', () => {
-        it('should write identity map', async () => {
-            await IdentityCacheDynamoDbService.putIdentityMap('pixel123', 'identity456', ['linked1', 'linked2']);
-            expect(mockedDynamoDbClient.safePut).toHaveBeenCalledTimes(1);
-            const putItem = mockedDynamoDbClient.safePut.mock.calls[0][1];
-            expect(putItem.pk).toBe('identity_map#pixel123#identity456');
-            expect(putItem.linkedIdentities).toEqual(['linked1', 'linked2']);
-        });
-        it('should return early for missing params', async () => {
-            await IdentityCacheDynamoDbService.putIdentityMap('', '', []);
-            expect(mockedDynamoDbClient.safePut).not.toHaveBeenCalled();
-        });
-        it('should return early when only pixelId is missing', async () => {
-            await IdentityCacheDynamoDbService.putIdentityMap('', 'identity456', ['linked1']);
-            expect(mockedDynamoDbClient.safePut).not.toHaveBeenCalled();
-        });
-        it('should return early when only identityId is missing', async () => {
-            await IdentityCacheDynamoDbService.putIdentityMap('pixel123', '', ['linked1']);
-            expect(mockedDynamoDbClient.safePut).not.toHaveBeenCalled();
-        });
-        it('should include updatedAt timestamp', async () => {
-            const before = new Date().toISOString();
-            await IdentityCacheDynamoDbService.putIdentityMap('pixel123', 'identity456', ['linked1']);
-            const after = new Date().toISOString();
-            const putItem = mockedDynamoDbClient.safePut.mock.calls[0][1];
-            expect(putItem.updatedAt).toBeDefined();
-            expect(putItem.updatedAt >= before).toBe(true);
-            expect(putItem.updatedAt <= after).toBe(true);
-        });
-        it('should not throw on safePut error (fail-open)', async () => {
-            mockedDynamoDbClient.safePut.mockRejectedValueOnce(new Error('DynamoDB error'));
-            await expect(IdentityCacheDynamoDbService.putIdentityMap('pixel123', 'identity456', ['linked1'])).resolves.toBeUndefined();
-        });
-    });
-    describe('deleteIdentityMap', () => {
-        it('should delete identity map', async () => {
-            await IdentityCacheDynamoDbService.deleteIdentityMap('pixel123', 'identity456');
-            expect(mockedDynamoDbClient.safeDelete).toHaveBeenCalledWith(expect.any(String), 'pk', 'identity_map#pixel123#identity456');
-        });
-        it('should return early for missing params', async () => {
-            await IdentityCacheDynamoDbService.deleteIdentityMap('', '');
-            expect(mockedDynamoDbClient.safeDelete).not.toHaveBeenCalled();
-        });
-        it('should return early when only pixelId is missing', async () => {
-            await IdentityCacheDynamoDbService.deleteIdentityMap('', 'identity456');
-            expect(mockedDynamoDbClient.safeDelete).not.toHaveBeenCalled();
-        });
-        it('should return early when only identityId is missing', async () => {
-            await IdentityCacheDynamoDbService.deleteIdentityMap('pixel123', '');
-            expect(mockedDynamoDbClient.safeDelete).not.toHaveBeenCalled();
-        });
-        it('should not throw on safeDelete error (fail-open)', async () => {
-            mockedDynamoDbClient.safeDelete.mockRejectedValueOnce(new Error('DynamoDB error'));
-            await expect(IdentityCacheDynamoDbService.deleteIdentityMap('pixel123', 'identity456')).resolves.toBeUndefined();
-        });
-    });
-    describe('deleteForcePurgeFlag', () => {
-        it('should delete force purge flag', async () => {
-            await IdentityCacheDynamoDbService.deleteForcePurgeFlag('pixel123', 'identity456');
-            expect(mockedDynamoDbClient.safeDelete).toHaveBeenCalledWith(expect.any(String), 'pk', 'force_purge#pixel123#identity456');
-        });
-        it('should return early for missing params', async () => {
-            await IdentityCacheDynamoDbService.deleteForcePurgeFlag('', '');
-            expect(mockedDynamoDbClient.safeDelete).not.toHaveBeenCalled();
-        });
-        it('should return early when only pixelId is missing', async () => {
-            await IdentityCacheDynamoDbService.deleteForcePurgeFlag('', 'identity456');
-            expect(mockedDynamoDbClient.safeDelete).not.toHaveBeenCalled();
-        });
-        it('should return early when only identityId is missing', async () => {
-            await IdentityCacheDynamoDbService.deleteForcePurgeFlag('pixel123', '');
-            expect(mockedDynamoDbClient.safeDelete).not.toHaveBeenCalled();
-        });
-        it('should not throw on safeDelete error (fail-open)', async () => {
-            mockedDynamoDbClient.safeDelete.mockRejectedValueOnce(new Error('DynamoDB error'));
-            await expect(IdentityCacheDynamoDbService.deleteForcePurgeFlag('pixel123', 'identity456')).resolves.toBeUndefined();
-        });
-    });
-    describe('deleteIdentityCache', () => {
-        const pixelId = 'pixel123';
-        it('should delete all related cache items', async () => {
-            mockedDynamoDbClient.safeQueryByGSI.mockResolvedValue([
-                { pk: `identity#${pixelId}#identity456`, pixelId },
-                { pk: `email#${pixelId}#test@email.com`, pixelId },
-            ]);
-            mockedDynamoDbClient.batchWrite.mockResolvedValue({ $metadata: {} });
-            const incomingIdentity = {
-                identityId: 'identity456',
-                traits: { emails: ['test@email.com'] },
-            };
-            const resolvedIdentity = {
-                identityId: 'identity456',
-                traits: { emails: ['test@email.com', 'other@email.com'] },
-            };
-            await IdentityCacheDynamoDbService.deleteIdentityCache(pixelId, incomingIdentity, resolvedIdentity);
-            expect(mockedDynamoDbClient.safeQueryByGSI).toHaveBeenCalled();
-            expect(mockedDynamoDbClient.batchWrite).toHaveBeenCalled();
-        });
-        it('should return early for missing pixelId', async () => {
-            await IdentityCacheDynamoDbService.deleteIdentityCache(null, {}, {});
-            expect(mockedDynamoDbClient.safeQueryByGSI).not.toHaveBeenCalled();
-        });
-        it('should handle different identityIds in incoming vs resolved', async () => {
-            mockedDynamoDbClient.safeQueryByGSI.mockResolvedValue([{ pk: `identity#${pixelId}#incoming-id`, pixelId }]);
-            mockedDynamoDbClient.batchWrite.mockResolvedValue({ $metadata: {} });
-            const incomingIdentity = {
-                identityId: 'incoming-id',
-                traits: { emails: ['test@email.com'] },
-            };
-            const resolvedIdentity = {
-                identityId: 'resolved-id',
-                traits: { emails: ['test@email.com'] },
-            };
-            await IdentityCacheDynamoDbService.deleteIdentityCache(pixelId, incomingIdentity, resolvedIdentity);
-            expect(mockedDynamoDbClient.safeQueryByGSI).toHaveBeenCalledTimes(2);
-        });
-        it('should not throw on batchWrite error (fail-open)', async () => {
-            mockedDynamoDbClient.safeQueryByGSI.mockResolvedValue([{ pk: `identity#${pixelId}#identity456`, pixelId }]);
-            mockedDynamoDbClient.batchWrite.mockRejectedValueOnce(new Error('DynamoDB error'));
-            await expect(IdentityCacheDynamoDbService.deleteIdentityCache(pixelId, { identityId: 'identity456' }, { identityId: 'identity456' })).resolves.toBeUndefined();
-        });
-        it('should deduplicate keys when same items returned from GSI query', async () => {
-            const duplicateItem = { pk: `identity#${pixelId}#identity456`, pixelId };
-            mockedDynamoDbClient.safeQueryByGSI.mockResolvedValue([duplicateItem, duplicateItem]);
-            mockedDynamoDbClient.batchWrite.mockResolvedValue({ $metadata: {} });
-            await IdentityCacheDynamoDbService.deleteIdentityCache(pixelId, { identityId: 'identity456' }, { identityId: 'identity456' });
-            expect(mockedDynamoDbClient.batchWrite).toHaveBeenCalled();
-            const batchWriteCall = mockedDynamoDbClient.batchWrite.mock.calls[0];
-            expect(batchWriteCall).toBeDefined();
-        });
-    });
-    describe('merge and staleness logic', () => {
-        const pixelId = 'pixel123';
-        it('should merge incoming traits with cached traits', async () => {
-            const cachedResponse = {
-                pk: `identity#${pixelId}#identity456`,
-                pixelId,
-                identityId: 'identity456',
-                response: {
-                    identityId: 'identity456',
-                    traits: {
-                        emails: ['cached@email.com'],
-                        userIds: ['cached-user'],
-                    },
-                },
-                updatedAt: new Date().toISOString(),
-            };
-            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
-            const result = await IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, {
-                identityId: 'identity456',
-                traits: {
-                    emails: ['incoming@email.com'],
-                    phones: ['+1234567890'],
-                },
-            });
-            expect(result.resolvedIdentity?.traits?.emails).toContain('incoming@email.com');
-            expect(result.resolvedIdentity?.traits?.emails).toContain('cached@email.com');
-            expect(result.resolvedIdentity?.traits?.userIds).toContain('cached-user');
-            expect(result.resolvedIdentity?.traits?.phones).toContain('+1234567890');
-        });
-        it('should mark cache stale when new data present', async () => {
-            const cachedResponse = {
-                pk: `identity#${pixelId}#identity456`,
-                pixelId,
-                identityId: 'identity456',
-                response: {
-                    identityId: 'identity456',
-                    traits: { emails: ['cached@email.com'] },
-                },
-                updatedAt: new Date().toISOString(),
-            };
-            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
-            const result = await IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, {
-                identityId: 'identity456',
-                traits: {
-                    emails: ['cached@email.com', 'new@email.com'],
-                },
-            });
-            expect(result.isCacheStale).toBe(true);
-        });
-        it('should not mark cache stale when incoming is subset of cached', async () => {
-            const cachedResponse = {
-                pk: `identity#${pixelId}#identity456`,
-                pixelId,
-                identityId: 'identity456',
-                response: {
-                    identityId: 'identity456',
-                    traits: {
-                        emails: ['a@email.com', 'b@email.com'],
-                        userIds: ['user1', 'user2'],
-                    },
-                },
-                updatedAt: new Date().toISOString(),
-            };
-            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
-            const result = await IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, {
-                identityId: 'identity456',
-                traits: {
-                    emails: ['a@email.com'],
-                },
-            });
-            expect(result.isCacheStale).toBe(false);
-        });
-    });
-    describe('multiple emails pointer writes', () => {
-        const pixelId = 'pixel123';
-        it('should write ALL emails as pointer records (not just first)', async () => {
-            const identity = {
-                identityId: 'identity456',
-                traits: {
-                    emails: ['first@email.com', 'second@email.com', 'third@email.com', 'fourth@email.com'],
-                },
-            };
-            await IdentityCacheDynamoDbService.updateIdentityCache(pixelId, identity);
-            const writtenItems = mockedDynamoDbClient.safeBatchWrite.mock.calls[0][1];
-            expect(writtenItems).toHaveLength(5);
-            const emailPks = writtenItems
-                .filter((item) => item.pk.startsWith('email#'))
-                .map((item) => item.pk);
-            expect(emailPks).toContain(`email#${pixelId}#first@email.com`);
-            expect(emailPks).toContain(`email#${pixelId}#second@email.com`);
-            expect(emailPks).toContain(`email#${pixelId}#third@email.com`);
-            expect(emailPks).toContain(`email#${pixelId}#fourth@email.com`);
-        });
-        it('should skip null/undefined emails in array', async () => {
-            const identity = {
-                identityId: 'identity456',
-                traits: {
-                    emails: ['valid@email.com', null, undefined, '', 'another@email.com'],
-                },
-            };
-            await IdentityCacheDynamoDbService.updateIdentityCache(pixelId, identity);
-            const writtenItems = mockedDynamoDbClient.safeBatchWrite.mock.calls[0][1];
-            const emailItems = writtenItems.filter((item) => item.pk.startsWith('email#'));
-            expect(emailItems).toHaveLength(2);
-            expect(emailItems.map((e) => e.pk)).toContain(`email#${pixelId}#valid@email.com`);
-            expect(emailItems.map((e) => e.pk)).toContain(`email#${pixelId}#another@email.com`);
-        });
-        it('should handle empty emails array', async () => {
-            const identity = {
-                identityId: 'identity456',
-                traits: { emails: [] },
-            };
-            await IdentityCacheDynamoDbService.updateIdentityCache(pixelId, identity);
-            const writtenItems = mockedDynamoDbClient.safeBatchWrite.mock.calls[0][1];
-            expect(writtenItems).toHaveLength(1);
-            expect(writtenItems[0].pk).toBe(`identity#${pixelId}#identity456`);
-        });
-        it('should handle email normalization (lowercase)', async () => {
-            const identity = {
-                identityId: 'identity456',
-                traits: {
-                    emails: ['UPPERCASE@EMAIL.COM', 'MixedCase@Email.Com'],
-                },
-            };
-            await IdentityCacheDynamoDbService.updateIdentityCache(pixelId, identity);
-            const writtenItems = mockedDynamoDbClient.safeBatchWrite.mock.calls[0][1];
-            const emailPks = writtenItems
-                .filter((item) => item.pk.startsWith('email#'))
-                .map((item) => item.pk);
-            expect(emailPks).toContain(`email#${pixelId}#uppercase@email.com`);
-            expect(emailPks).toContain(`email#${pixelId}#mixedcase@email.com`);
-        });
-    });
-    describe('null/undefined traits edge cases', () => {
-        const pixelId = 'pixel123';
-        it('should handle null traits object', async () => {
-            const identity = {
-                identityId: 'identity456',
-                traits: null,
-            };
-            await IdentityCacheDynamoDbService.updateIdentityCache(pixelId, identity);
-            const writtenItems = mockedDynamoDbClient.safeBatchWrite.mock.calls[0][1];
-            expect(writtenItems).toHaveLength(1);
-        });
-        it('should handle undefined traits object', async () => {
-            const identity = {
-                identityId: 'identity456',
-                traits: undefined,
-            };
-            await IdentityCacheDynamoDbService.updateIdentityCache(pixelId, identity);
-            const writtenItems = mockedDynamoDbClient.safeBatchWrite.mock.calls[0][1];
-            expect(writtenItems).toHaveLength(1);
-        });
-        it('should return cache miss for identity with null traits in lookup', async () => {
-            const result = await IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, {
-                traits: null,
-            });
-            expect(result.resolvedIdentity).toBeUndefined();
-            expect(result.isCacheStale).toBe(true);
-            expect(mockedDynamoDbClient.safeGet).not.toHaveBeenCalled();
-        });
-        it('should handle identity with undefined emails in traits', async () => {
-            const result = await IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, {
-                traits: { userIds: ['user123'] },
-            });
-            expect(result.resolvedIdentity).toBeUndefined();
-            expect(result.isCacheStale).toBe(true);
-        });
-    });
-    describe('backward compatibility (old full-blob format)', () => {
-        const pixelId = 'pixel123';
-        it('should read old format email record with full response blob', async () => {
-            const oldFormatEmailRecord = {
-                pk: `email#${pixelId}#test@email.com`,
-                pixelId,
-                identityId: 'discovered-id',
-                gsi1pk: 'discovered-id',
-                response: {
-                    identityId: 'discovered-id',
-                    traits: { emails: ['test@email.com', 'other@email.com'] },
-                },
-                updatedAt: new Date().toISOString(),
-            };
-            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(oldFormatEmailRecord);
-            const result = await IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, {
-                traits: { emails: ['test@email.com'] },
-            });
-            expect(result.resolvedIdentity).toBeDefined();
-            expect(result.resolvedIdentity?.identityId).toBe('discovered-id');
-            expect(result.isCacheStale).toBe(true);
-        });
-        it('should read new format pointer record (no response blob)', async () => {
-            const newFormatPointerRecord = {
-                pk: `email#${pixelId}#test@email.com`,
-                pixelId,
-                identityId: 'discovered-id',
-                gsi1pk: 'discovered-id',
-                updatedAt: new Date().toISOString(),
-            };
-            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(newFormatPointerRecord);
-            const result = await IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, {
-                traits: { emails: ['test@email.com'] },
-            });
-            expect(result.resolvedIdentity).toBeDefined();
-            expect(result.resolvedIdentity?.identityId).toBe('discovered-id');
-            expect(result.isCacheStale).toBe(true);
-        });
-        it('should trigger Neptune resolution after finding pointer record', async () => {
-            const lambdaArn = 'arn:aws:lambda:us-east-1:123456789:function:identity-private';
-            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', 'resolved@email.com'] },
-                    },
-                }),
-            });
-            const result = await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, { traits: { emails: ['test@email.com'] } }, lambdaArn);
-            expect(mockInvokeFunction).toHaveBeenCalledWith(lambdaArn, expect.objectContaining({
-                pixelId,
-                context: {
-                    identity: expect.objectContaining({
-                        identityId: 'discovered-id',
-                    }),
-                },
-            }));
-            expect(result?.identityId).toBe('discovered-id');
-        });
-    });
-    describe('deleteIdentityCache with multiple email pointers', () => {
-        const pixelId = 'pixel123';
-        it('should delete all email pointers from both incoming and resolved identities', async () => {
-            mockedDynamoDbClient.safeQueryByGSI.mockResolvedValue([
-                { pk: `identity#${pixelId}#identity456`, pixelId },
-            ]);
-            mockedDynamoDbClient.batchWrite.mockResolvedValue({ $metadata: {} });
-            const incomingIdentity = {
-                identityId: 'identity456',
-                traits: { emails: ['incoming1@email.com', 'incoming2@email.com'] },
-            };
-            const resolvedIdentity = {
-                identityId: 'identity456',
-                traits: { emails: ['resolved1@email.com', 'resolved2@email.com', 'resolved3@email.com'] },
-            };
-            await IdentityCacheDynamoDbService.deleteIdentityCache(pixelId, incomingIdentity, resolvedIdentity);
-            expect(mockedDynamoDbClient.batchWrite).toHaveBeenCalled();
-            const batchWriteCall = mockedDynamoDbClient.batchWrite.mock.calls[0][0];
-            const deleteRequests = batchWriteCall.RequestItems[Object.keys(batchWriteCall.RequestItems)[0]];
-            const deletedPks = deleteRequests.map((req) => req.DeleteRequest.Key.pk);
-            expect(deletedPks).toContain(`identity#${pixelId}#identity456`);
-            expect(deletedPks).toContain(`email#${pixelId}#incoming1@email.com`);
-            expect(deletedPks).toContain(`email#${pixelId}#incoming2@email.com`);
-            expect(deletedPks).toContain(`email#${pixelId}#resolved1@email.com`);
-            expect(deletedPks).toContain(`email#${pixelId}#resolved2@email.com`);
-            expect(deletedPks).toContain(`email#${pixelId}#resolved3@email.com`);
-        });
-        it('should handle empty emails in delete', async () => {
-            mockedDynamoDbClient.safeQueryByGSI.mockResolvedValue([
-                { pk: `identity#${pixelId}#identity456`, pixelId },
-            ]);
-            mockedDynamoDbClient.batchWrite.mockResolvedValue({ $metadata: {} });
-            await IdentityCacheDynamoDbService.deleteIdentityCache(pixelId, { identityId: 'identity456', traits: { emails: [] } }, { identityId: 'identity456' });
-            expect(mockedDynamoDbClient.batchWrite).toHaveBeenCalled();
-        });
-        it('should handle missing traits in delete', async () => {
-            mockedDynamoDbClient.safeQueryByGSI.mockResolvedValue([
-                { pk: `identity#${pixelId}#identity456`, pixelId },
-            ]);
-            mockedDynamoDbClient.batchWrite.mockResolvedValue({ $metadata: {} });
-            await IdentityCacheDynamoDbService.deleteIdentityCache(pixelId, { identityId: 'identity456' }, { identityId: 'identity456' });
-            expect(mockedDynamoDbClient.batchWrite).toHaveBeenCalled();
-        });
-        it('should not delete items from other pixelIds', async () => {
-            const otherPixelId = 'other-pixel';
-            mockedDynamoDbClient.safeQueryByGSI.mockResolvedValue([
-                { pk: `identity#${pixelId}#identity456`, pixelId },
-                { pk: `identity#${otherPixelId}#identity456`, pixelId: otherPixelId },
-            ]);
-            mockedDynamoDbClient.batchWrite.mockResolvedValue({ $metadata: {} });
-            await IdentityCacheDynamoDbService.deleteIdentityCache(pixelId, { identityId: 'identity456' }, { identityId: 'identity456' });
-            const batchWriteCall = mockedDynamoDbClient.batchWrite.mock.calls[0][0];
-            const deleteRequests = batchWriteCall.RequestItems[Object.keys(batchWriteCall.RequestItems)[0]];
-            const deletedPks = deleteRequests.map((req) => req.DeleteRequest.Key.pk);
-            expect(deletedPks).toContain(`identity#${pixelId}#identity456`);
-            expect(deletedPks).not.toContain(`identity#${otherPixelId}#identity456`);
-        });
-    });
-    describe('GSI1 query for reverse lookups', () => {
-        const pixelId = 'pixel123';
-        it('should find all records by identityId via GSI1', async () => {
-            const identityId = 'identity456';
-            const mockResults = [
-                { pk: `identity#${pixelId}#${identityId}`, pixelId, identityId },
-                { pk: `email#${pixelId}#email1@test.com`, pixelId, identityId },
-                { pk: `email#${pixelId}#email2@test.com`, pixelId, identityId },
-            ];
-            mockedDynamoDbClient.safeQueryByGSI.mockResolvedValue(mockResults);
-            mockedDynamoDbClient.batchWrite.mockResolvedValue({ $metadata: {} });
-            await IdentityCacheDynamoDbService.deleteIdentityCache(pixelId, { identityId }, { identityId });
-            expect(mockedDynamoDbClient.safeQueryByGSI).toHaveBeenCalledWith(expect.any(String), expect.any(String), 'gsi1pk', identityId);
-        });
-        it('should handle GSI1 query returning empty results', async () => {
-            mockedDynamoDbClient.safeQueryByGSI.mockResolvedValue([]);
-            await IdentityCacheDynamoDbService.deleteIdentityCache(pixelId, { identityId: 'unknown-id' }, { identityId: 'unknown-id' });
-            expect(mockedDynamoDbClient.batchWrite).not.toHaveBeenCalled();
-        });
-        it('should handle GSI1 query error gracefully (fail-open)', async () => {
-            mockedDynamoDbClient.safeQueryByGSI.mockRejectedValueOnce(new Error('GSI query failed'));
-            await expect(IdentityCacheDynamoDbService.deleteIdentityCache(pixelId, { identityId: 'identity456' }, { identityId: 'identity456' })).resolves.toBeUndefined();
-        });
-    });
-    describe('email pointer lookups', () => {
-        const pixelId = 'pixel123';
-        it('should only lookup first email (optimization)', async () => {
-            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
-            await IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, {
-                traits: { emails: ['first@email.com', 'second@email.com', 'third@email.com'] },
-            });
-            expect(mockedDynamoDbClient.safeGet).toHaveBeenCalledTimes(1);
-            expect(mockedDynamoDbClient.safeGet).toHaveBeenCalledWith(expect.any(String), 'pk', `email#${pixelId}#first@email.com`);
-        });
-        it('should handle whitespace in email during lookup', async () => {
-            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
-            await IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, {
-                traits: { emails: ['  test@email.com  '] },
-            });
-            expect(mockedDynamoDbClient.safeGet).toHaveBeenCalled();
-        });
-    });
-    describe('fail-open behavior comprehensive', () => {
-        const pixelId = 'pixel123';
-        const lambdaArn = 'arn:aws:lambda:us-east-1:123456789:function:identity-private';
-        it('should return incoming identity when Neptune throws (fail-open fallback)', async () => {
-            const incomingIdentity = {
-                identityId: 'identity456',
-                traits: { emails: ['test@email.com'] },
-            };
-            mockedDynamoDbClient.safeGet.mockRejectedValueOnce(new Error('DynamoDB down'));
-            mockInvokeFunction.mockRejectedValueOnce(new Error('Lambda down'));
-            const result = await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
-            expect(result).toEqual(incomingIdentity);
-        });
-        it('should continue when cache write fails after Neptune success', async () => {
-            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
-            mockInvokeFunction.mockResolvedValueOnce({
-                statusCode: 200,
-                body: JSON.stringify({
-                    identity: { identityId: 'resolved-id', traits: { emails: ['test@email.com'] } },
-                }),
-            });
-            mockedDynamoDbClient.safeBatchWrite.mockRejectedValueOnce(new Error('Write failed'));
-            const result = await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, { traits: { emails: ['test@email.com'] } }, lambdaArn);
-            expect(result?.identityId).toBe('resolved-id');
-        });
-        it('should return incoming identity when Neptune returns non-200', async () => {
-            const incomingIdentity = {
-                identityId: 'incoming-id',
-                traits: { emails: ['test@email.com'] },
-            };
-            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
-            mockInvokeFunction.mockResolvedValueOnce({
-                statusCode: 500,
-                body: 'Internal Server Error',
-            });
-            const result = await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
-            expect(result).toEqual(incomingIdentity);
-        });
-        it('should return incoming identity when Neptune returns malformed JSON (fail-open)', async () => {
-            const incomingIdentity = {
-                identityId: 'test-id',
-                traits: { emails: ['test@email.com'] },
-            };
-            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
-            mockInvokeFunction.mockResolvedValueOnce({
-                statusCode: 200,
-                body: 'not valid json',
-            });
-            const result = await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
-            expect(result).toEqual(incomingIdentity);
-        });
-        it('should return undefined only when both inputs are invalid', async () => {
-            const result = await IdentityCacheDynamoDbService.getIdentityWithCaching(null, null, lambdaArn);
-            expect(result).toBeUndefined();
-        });
-    });
-    describe('gsi1pk attribute on all records', () => {
-        const pixelId = 'pixel123';
-        it('should include gsi1pk on identity record', async () => {
-            const identity = {
-                identityId: 'identity456',
-                traits: { emails: ['test@email.com'] },
-            };
-            await IdentityCacheDynamoDbService.updateIdentityCache(pixelId, identity);
-            const writtenItems = mockedDynamoDbClient.safeBatchWrite.mock.calls[0][1];
-            const identityItem = writtenItems.find((item) => item.pk.startsWith('identity#'));
-            expect(identityItem).toBeDefined();
-            expect(identityItem.gsi1pk).toBe('identity456');
-        });
-        it('should include gsi1pk on all email pointer records', async () => {
-            const identity = {
-                identityId: 'identity456',
-                traits: { emails: ['email1@test.com', 'email2@test.com'] },
-            };
-            await IdentityCacheDynamoDbService.updateIdentityCache(pixelId, identity);
-            const writtenItems = mockedDynamoDbClient.safeBatchWrite.mock.calls[0][1];
-            const emailItems = writtenItems.filter((item) => item.pk.startsWith('email#'));
-            for (const emailItem of emailItems) {
-                expect(emailItem.gsi1pk).toBe('identity456');
-            }
-        });
-    });
-});
+import { buildEmailPk as buildTrackingTypesEmailPk, buildForcePurgePk as buildTrackingTypesForcePurgePk, buildIdentityMapPk as buildTrackingTypesIdentityMapPk, buildIdentityPk as buildTrackingTypesIdentityPk, buildUserIdPk as buildTrackingTypesUserIdPk, } from '@adtrackify/at-tracking-event-types';
+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 { buildEmailPk, buildForcePurgePk, buildIdentityMapPk, buildIdentityPk, buildUserIdPk, } from '../../services/db/identity-cache-dynamodb-service/key-builders.js';
+import { IdentityGatewayService, } from '../../services/db/identity-cache-dynamodb-service/identity-gateway-service.js';
+import { IDENTITY_CACHE_WITH_CACHING_OUTCOME, } from '../../services/db/identity-cache-dynamodb-service/types.js';
+import { IdentityCacheDynamoDbDbService } from '../../services/db/identity-cache-dynamodb-service/identity-cache-dynamodb-db-service.js';
+import { DynamoDbClient } from '../../clients/index.js';
+const mockedDynamoDbClient = DynamoDbClient;
+describe('IdentityGatewayService', () => {
+    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();
+        IdentityGatewayService.lambdaInvokeClient = undefined;
+    });
+    describe('identity cache key builders', () => {
+        it('should build primary identity cache keys', () => {
+            expect(buildIdentityPk('pixel123', 'identity456')).toBe('identity#pixel123#identity456');
+        });
+        it('should build lowercase email pointer keys', () => {
+            expect(buildEmailPk('pixel123', 'Test@Email.COM')).toBe('email#pixel123#test@email.com');
+        });
+        it('should build trimmed user id pointer keys', () => {
+            expect(buildUserIdPk('pixel123', ' user-1 ')).toBe('user_id#pixel123#user-1');
+        });
+        it('should build identity map keys', () => {
+            expect(buildIdentityMapPk('pixel123', 'identity456')).toBe('identity_map#pixel123#identity456');
+        });
+        it('should build force purge keys', () => {
+            expect(buildForcePurgePk('pixel123', 'identity456')).toBe('force_purge#pixel123#identity456');
+        });
+        it('should match the installed tracking-event-types key builder behavior during migration', () => {
+            expect(buildIdentityPk('pixel123', 'identity456')).toBe(buildTrackingTypesIdentityPk('pixel123', 'identity456'));
+            expect(buildEmailPk('pixel123', 'Test@Email.COM')).toBe(buildTrackingTypesEmailPk('pixel123', 'Test@Email.COM'));
+            expect(buildUserIdPk('pixel123', ' user-1 ')).toBe(buildTrackingTypesUserIdPk('pixel123', ' user-1 '));
+            expect(buildIdentityMapPk('pixel123', 'identity456')).toBe(buildTrackingTypesIdentityMapPk('pixel123', 'identity456'));
+            expect(buildForcePurgePk('pixel123', 'identity456')).toBe(buildTrackingTypesForcePurgePk('pixel123', 'identity456'));
+        });
+    });
+    describe('getIdentityWithCaching', () => {
+        const pixelId = 'pixel123';
+        const lambdaArn = 'arn:aws:lambda:us-east-1:123456789:function:identity-private';
+        describe('cache hit (fresh cache)', () => {
+            it('should return cached identity without invoking Neptune Lambda', 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 IdentityGatewayService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
+                expect(result).toBeDefined();
+                expect(result?.identityId).toBe('identity456');
+                expect(mockInvokeFunction).not.toHaveBeenCalled();
+            });
+        });
+        describe('cache miss', () => {
+            it('should invoke Neptune Lambda and return resolved identity', async () => {
+                const incomingIdentity = {
+                    identityId: 'identity456',
+                    traits: { emails: ['test@email.com'] },
+                };
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
+                mockInvokeFunction.mockResolvedValueOnce({
+                    statusCode: 200,
+                    body: JSON.stringify({
+                        identity: {
+                            identityId: 'resolved-identity',
+                            traits: { emails: ['test@email.com', 'resolved@email.com'] },
+                        },
+                    }),
+                });
+                const result = await IdentityGatewayService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
+                expect(mockInvokeFunction).toHaveBeenCalledWith(lambdaArn, {
+                    pixelId,
+                    context: { identity: incomingIdentity },
+                });
+                expect(result?.identityId).toBe('resolved-identity');
+                expect(mockedDynamoDbClient.safeBatchWrite).toHaveBeenCalled();
+            });
+            it('should return incomingIdentity when Neptune Lambda fails to resolve', async () => {
+                const incomingIdentity = {
+                    identityId: 'identity456',
+                    traits: { emails: ['test@email.com'] },
+                };
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
+                mockInvokeFunction.mockResolvedValueOnce({
+                    statusCode: 200,
+                    body: JSON.stringify({ identity: undefined }),
+                });
+                const result = await IdentityGatewayService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
+                expect(result).toEqual(incomingIdentity);
+            });
+        });
+        describe('cache stale', () => {
+            it('should invoke Neptune Lambda when cache is 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'] },
+                        },
+                    }),
+                });
+                const result = await IdentityGatewayService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
+                expect(mockInvokeFunction).toHaveBeenCalled();
+                expect(result?.identityId).toBe('identity456');
+                expect(result?.traits?.emails).toContain('new@email.com');
+            });
+            it('should use merged cache identity when Neptune fails', 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: 500,
+                    body: 'Internal Server Error',
+                });
+                const result = await IdentityGatewayService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
+                expect(result).toBeDefined();
+                expect(result?.identityId).toBe('identity456');
+            });
+        });
+        describe('Neptune Lambda invocation', () => {
+            it('should write-back Neptune response to cache on success', async () => {
+                const incomingIdentity = {
+                    traits: { emails: ['test@email.com'] },
+                };
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
+                mockInvokeFunction.mockResolvedValueOnce({
+                    statusCode: 200,
+                    body: JSON.stringify({
+                        identity: {
+                            identityId: 'neptune-resolved-id',
+                            traits: { emails: ['test@email.com'] },
+                        },
+                    }),
+                });
+                await IdentityGatewayService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
+                expect(mockedDynamoDbClient.safeBatchWrite).toHaveBeenCalled();
+                const writtenItems = mockedDynamoDbClient.safeBatchWrite.mock.calls[0][1];
+                const identityPks = writtenItems.map((item) => item.pk);
+                expect(identityPks).toContain(`identity#${pixelId}#neptune-resolved-id`);
+            });
+            it('should not write to cache when Neptune returns undefined', async () => {
+                const incomingIdentity = {
+                    traits: { emails: ['test@email.com'] },
+                };
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
+                mockInvokeFunction.mockResolvedValueOnce({
+                    statusCode: 200,
+                    body: JSON.stringify({ identity: undefined }),
+                });
+                await IdentityGatewayService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
+                expect(mockedDynamoDbClient.safeBatchWrite).not.toHaveBeenCalled();
+            });
+        });
+        describe('error handling (fail-open)', () => {
+            it('should return undefined when pixelId is missing', async () => {
+                const result = await IdentityGatewayService.getIdentityWithCaching(null, { identityId: 'test-id' }, lambdaArn);
+                expect(result).toBeUndefined();
+                expect(mockInvokeFunction).not.toHaveBeenCalled();
+            });
+            it('should return undefined when incomingIdentity is missing', async () => {
+                const result = await IdentityGatewayService.getIdentityWithCaching(pixelId, null, lambdaArn);
+                expect(result).toBeUndefined();
+                expect(mockInvokeFunction).not.toHaveBeenCalled();
+            });
+            it('should return undefined when Neptune Lambda throws', async () => {
+                const incomingIdentity = {
+                    identityId: 'identity456',
+                    traits: { emails: ['test@email.com'] },
+                };
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
+                mockInvokeFunction.mockRejectedValueOnce(new Error('Lambda invocation failed'));
+                const result = await IdentityGatewayService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
+                expect(result).toEqual(incomingIdentity);
+            });
+            it('should not throw when cache write fails after Neptune success', async () => {
+                const incomingIdentity = {
+                    traits: { emails: ['test@email.com'] },
+                };
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
+                mockInvokeFunction.mockResolvedValueOnce({
+                    statusCode: 200,
+                    body: JSON.stringify({
+                        identity: {
+                            identityId: 'neptune-resolved-id',
+                            traits: { emails: ['test@email.com'] },
+                        },
+                    }),
+                });
+                mockedDynamoDbClient.safeBatchWrite.mockRejectedValueOnce(new Error('DynamoDB write failed'));
+                const result = await IdentityGatewayService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
+                expect(result?.identityId).toBe('neptune-resolved-id');
+            });
+        });
+    });
+    describe('Key Builders', () => {
+        describe('buildIdentityPk', () => {
+            it('should build correct pk for identity lookup', async () => {
+                const pixelId = 'pixel123';
+                const identityId = 'identity456';
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
+                await IdentityCacheDynamoDbDbService.getIdentityFromCache(pixelId, { identityId });
+                expect(mockedDynamoDbClient.safeGet).toHaveBeenCalledWith(expect.any(String), 'pk', `identity#${pixelId}#${identityId}`);
+            });
+        });
+        describe('buildEmailPk', () => {
+            it('should build correct pk for email lookup (lowercase)', async () => {
+                const pixelId = 'pixel123';
+                const email = 'Test@Email.COM';
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
+                await IdentityCacheDynamoDbDbService.getIdentityFromCache(pixelId, {
+                    traits: { emails: [email] },
+                });
+                expect(mockedDynamoDbClient.safeGet).toHaveBeenCalledWith(expect.any(String), 'pk', `email#${pixelId}#test@email.com`);
+            });
+        });
+        describe('buildUserIdPk (no longer used for lookup)', () => {
+            it('should NOT lookup by userId (optimization: email-only secondary lookup)', async () => {
+                const pixelId = 'pixel123';
+                const userId = '  user789  ';
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
+                await IdentityCacheDynamoDbDbService.getIdentityFromCache(pixelId, {
+                    traits: { userIds: [userId] },
+                });
+                expect(mockedDynamoDbClient.safeBatchGet).not.toHaveBeenCalled();
+            });
+        });
+    });
+    describe('getIdentityFromCache', () => {
+        const pixelId = 'pixel123';
+        describe('with identityId (primary lookup)', () => {
+            it('should return cache hit when identity found', async () => {
+                const identityId = 'identity456';
+                const cachedResponse = {
+                    pk: `identity#${pixelId}#${identityId}`,
+                    pixelId,
+                    identityId,
+                    response: {
+                        identityId,
+                        traits: { emails: ['test@email.com'] },
+                    },
+                    updatedAt: new Date().toISOString(),
+                };
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+                const result = await IdentityCacheDynamoDbDbService.getIdentityFromCache(pixelId, {
+                    identityId,
+                    traits: { emails: ['test@email.com'] },
+                });
+                expect(result.resolvedIdentity).toBeDefined();
+                expect(result.resolvedIdentity?.identityId).toBe(identityId);
+                expect(result.isCacheStale).toBe(false);
+            });
+            it('should return cache miss when identity not found', async () => {
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
+                const result = await IdentityCacheDynamoDbDbService.getIdentityFromCache(pixelId, {
+                    identityId: 'unknown-id',
+                });
+                expect(result.resolvedIdentity).toBeUndefined();
+                expect(result.isCacheStale).toBe(true);
+            });
+            it('should NOT fallback to secondary keys when identityId lookup misses', async () => {
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
+                await IdentityCacheDynamoDbDbService.getIdentityFromCache(pixelId, {
+                    identityId: 'unknown-id',
+                    traits: { emails: ['test@email.com'] },
+                });
+                expect(mockedDynamoDbClient.safeBatchGet).not.toHaveBeenCalled();
+            });
+            it('should detect stale cache when new traits present', async () => {
+                const identityId = 'identity456';
+                const cachedResponse = {
+                    pk: `identity#${pixelId}#${identityId}`,
+                    pixelId,
+                    identityId,
+                    response: {
+                        identityId,
+                        traits: { emails: ['old@email.com'] },
+                    },
+                    updatedAt: new Date().toISOString(),
+                };
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+                const result = await IdentityCacheDynamoDbDbService.getIdentityFromCache(pixelId, {
+                    identityId,
+                    traits: { emails: ['old@email.com', 'new@email.com'] },
+                });
+                expect(result.resolvedIdentity).toBeDefined();
+                expect(result.isCacheStale).toBe(true);
+            });
+        });
+        describe('without identityId (secondary lookup)', () => {
+            it('should use single get for email lookup (pointer-based)', async () => {
+                const pointerRecord = {
+                    pk: `email#${pixelId}#test@email.com`,
+                    pixelId,
+                    identityId: 'resolved-id',
+                    gsi1pk: 'resolved-id',
+                    updatedAt: new Date().toISOString(),
+                };
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(pointerRecord);
+                const result = await IdentityCacheDynamoDbDbService.getIdentityFromCache(pixelId, {
+                    traits: { emails: ['test@email.com'], userIds: ['user123'] },
+                });
+                expect(mockedDynamoDbClient.safeGet).toHaveBeenCalledWith(expect.any(String), 'pk', `email#${pixelId}#test@email.com`);
+                expect(mockedDynamoDbClient.safeBatchGet).not.toHaveBeenCalled();
+                expect(result.resolvedIdentity).toBeDefined();
+                expect(result.resolvedIdentity?.traits?.emails).toContain('test@email.com');
+                expect(result.isCacheStale).toBe(true);
+            });
+            it('should return discovered identityId with stale flag for Neptune resolution', async () => {
+                const pointerRecord = {
+                    pk: `email#${pixelId}#test@email.com`,
+                    pixelId,
+                    identityId: 'discovered-id',
+                    gsi1pk: 'discovered-id',
+                    updatedAt: new Date().toISOString(),
+                };
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(pointerRecord);
+                const result = await IdentityCacheDynamoDbDbService.getIdentityFromCache(pixelId, {
+                    traits: { emails: ['test@email.com'], userIds: ['user123'] },
+                });
+                expect(result.resolvedIdentity).toBeDefined();
+                expect(result.resolvedIdentity?.identityId).toBe('discovered-id');
+                expect(result.isCacheStale).toBe(true);
+            });
+            it('should return cache miss when no secondary keys match', async () => {
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
+                const result = await IdentityCacheDynamoDbDbService.getIdentityFromCache(pixelId, {
+                    traits: { emails: ['unknown@email.com'] },
+                });
+                expect(result.resolvedIdentity).toBeUndefined();
+                expect(result.isCacheStale).toBe(true);
+            });
+            it('should return cache miss when no emails to lookup', async () => {
+                const result = await IdentityCacheDynamoDbDbService.getIdentityFromCache(pixelId, {
+                    traits: { userIds: ['user123'] },
+                });
+                expect(result.resolvedIdentity).toBeUndefined();
+                expect(result.isCacheStale).toBe(true);
+                expect(mockedDynamoDbClient.safeGet).not.toHaveBeenCalled();
+            });
+            it('should return cache miss when empty traits', async () => {
+                const result = await IdentityCacheDynamoDbDbService.getIdentityFromCache(pixelId, {
+                    traits: {},
+                });
+                expect(result.resolvedIdentity).toBeUndefined();
+                expect(result.isCacheStale).toBe(true);
+            });
+        });
+        describe('error handling (fail-open)', () => {
+            it('should return cache miss on safeGet error', async () => {
+                mockedDynamoDbClient.safeGet.mockRejectedValueOnce(new Error('DynamoDB error'));
+                const result = await IdentityCacheDynamoDbDbService.getIdentityFromCache(pixelId, {
+                    identityId: 'test-id',
+                });
+                expect(result.resolvedIdentity).toBeUndefined();
+                expect(result.isCacheStale).toBe(true);
+            });
+            it('should return cache miss on safeGet error for email lookup', async () => {
+                mockedDynamoDbClient.safeGet.mockRejectedValueOnce(new Error('DynamoDB error'));
+                const result = await IdentityCacheDynamoDbDbService.getIdentityFromCache(pixelId, {
+                    traits: { emails: ['test@email.com'] },
+                });
+                expect(result.resolvedIdentity).toBeUndefined();
+                expect(result.isCacheStale).toBe(true);
+            });
+            it('should return cache miss for null pixelId', async () => {
+                const result = await IdentityCacheDynamoDbDbService.getIdentityFromCache(null, {
+                    identityId: 'test-id',
+                });
+                expect(result.resolvedIdentity).toBeUndefined();
+                expect(result.isCacheStale).toBe(true);
+            });
+            it('should return cache miss for null incomingIdentity', async () => {
+                const result = await IdentityCacheDynamoDbDbService.getIdentityFromCache(pixelId, null);
+                expect(result.resolvedIdentity).toBeUndefined();
+                expect(result.isCacheStale).toBe(true);
+            });
+        });
+    });
+    describe('updateIdentityCache', () => {
+        const pixelId = 'pixel123';
+        it('should write identity with email pointer (no full blob on secondary keys)', async () => {
+            const identity = {
+                identityId: 'identity456',
+                traits: {
+                    emails: ['test@email.com', 'other@email.com'],
+                    userIds: ['user1', 'user2'],
+                },
+            };
+            await IdentityCacheDynamoDbDbService.updateIdentityCache(pixelId, identity);
+            expect(mockedDynamoDbClient.safeBatchWrite).toHaveBeenCalledTimes(1);
+            const writtenItems = mockedDynamoDbClient.safeBatchWrite.mock.calls[0][1];
+            expect(writtenItems).toHaveLength(3);
+            const pks = writtenItems.map((item) => item.pk);
+            expect(pks).toContain(`identity#${pixelId}#identity456`);
+            expect(pks).toContain(`email#${pixelId}#test@email.com`);
+            expect(pks).toContain(`email#${pixelId}#other@email.com`);
+            expect(pks).not.toContain(`user_id#${pixelId}#user1`);
+            expect(pks).not.toContain(`user_id#${pixelId}#user2`);
+            const identityItem = writtenItems.find((item) => item.pk.startsWith('identity#'));
+            expect(identityItem).toBeDefined();
+            expect(identityItem?.response).toBeDefined();
+            expect(identityItem?.response.identityId).toBe('identity456');
+            const emailItem = writtenItems.find((item) => item.pk.startsWith('email#'));
+            expect(emailItem).toBeDefined();
+            expect(emailItem?.response).toBeUndefined();
+            expect(emailItem?.identityId).toBe('identity456');
+        });
+        it('should not throw on safeBatchWrite error (fail-open)', async () => {
+            mockedDynamoDbClient.safeBatchWrite.mockRejectedValueOnce(new Error('DynamoDB error'));
+            const identity = {
+                identityId: 'identity456',
+                traits: { emails: ['test@email.com'] },
+            };
+            await expect(IdentityCacheDynamoDbDbService.updateIdentityCache(pixelId, identity)).resolves.toBeUndefined();
+        });
+        it('should return early for missing identityId', async () => {
+            await IdentityCacheDynamoDbDbService.updateIdentityCache(pixelId, {});
+            expect(mockedDynamoDbClient.safeBatchWrite).not.toHaveBeenCalled();
+        });
+        it('should return early for missing pixelId', async () => {
+            await IdentityCacheDynamoDbDbService.updateIdentityCache(null, {
+                identityId: 'test-id',
+            });
+            expect(mockedDynamoDbClient.safeBatchWrite).not.toHaveBeenCalled();
+        });
+        it('should handle identity with no traits', async () => {
+            const identity = {
+                identityId: 'identity456',
+            };
+            await IdentityCacheDynamoDbDbService.updateIdentityCache(pixelId, identity);
+            const writtenItems = mockedDynamoDbClient.safeBatchWrite.mock.calls[0][1];
+            expect(writtenItems).toHaveLength(1);
+        });
+        it('should include gsi1pk for reverse lookups', async () => {
+            const identity = {
+                identityId: 'identity456',
+                traits: { emails: ['test@email.com'] },
+            };
+            await IdentityCacheDynamoDbDbService.updateIdentityCache(pixelId, identity);
+            const writtenItems = mockedDynamoDbClient.safeBatchWrite.mock.calls[0][1];
+            for (const item of writtenItems) {
+                expect(item.gsi1pk).toBe('identity456');
+            }
+        });
+    });
+    describe('getIdentityMap', () => {
+        it('should return identity map when found', async () => {
+            const mockMap = {
+                pk: 'identity_map#pixel123#identity456',
+                pixelId: 'pixel123',
+                identityId: 'identity456',
+                linkedIdentities: ['identity789'],
+                updatedAt: new Date().toISOString(),
+            };
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(mockMap);
+            const result = await IdentityCacheDynamoDbDbService.getIdentityMap('pixel123', 'identity456');
+            expect(result).toEqual(mockMap);
+            expect(mockedDynamoDbClient.safeGet).toHaveBeenCalledWith(expect.any(String), 'pk', 'identity_map#pixel123#identity456');
+        });
+        it('should return undefined when not found', async () => {
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
+            const result = await IdentityCacheDynamoDbDbService.getIdentityMap('pixel123', 'identity456');
+            expect(result).toBeUndefined();
+        });
+        it('should return undefined for missing params (fail-open)', async () => {
+            const result = await IdentityCacheDynamoDbDbService.getIdentityMap('', '');
+            expect(result).toBeUndefined();
+            expect(mockedDynamoDbClient.safeGet).not.toHaveBeenCalled();
+        });
+        it('should return undefined when only pixelId is missing', async () => {
+            const result = await IdentityCacheDynamoDbDbService.getIdentityMap('', 'identity456');
+            expect(result).toBeUndefined();
+            expect(mockedDynamoDbClient.safeGet).not.toHaveBeenCalled();
+        });
+        it('should return undefined when only identityId is missing', async () => {
+            const result = await IdentityCacheDynamoDbDbService.getIdentityMap('pixel123', '');
+            expect(result).toBeUndefined();
+            expect(mockedDynamoDbClient.safeGet).not.toHaveBeenCalled();
+        });
+        it('should return undefined on safeGet error (fail-open)', async () => {
+            mockedDynamoDbClient.safeGet.mockRejectedValueOnce(new Error('DynamoDB error'));
+            const result = await IdentityCacheDynamoDbDbService.getIdentityMap('pixel123', 'identity456');
+            expect(result).toBeUndefined();
+        });
+    });
+    describe('getForcePurgeFlag', () => {
+        it('should return true when flag exists', async () => {
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce({
+                pk: 'force_purge#pixel123#identity456',
+            });
+            const result = await IdentityCacheDynamoDbDbService.getForcePurgeFlag('pixel123', 'identity456');
+            expect(result).toBe(true);
+        });
+        it('should return false when flag not found', async () => {
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
+            const result = await IdentityCacheDynamoDbDbService.getForcePurgeFlag('pixel123', 'identity456');
+            expect(result).toBe(false);
+        });
+        it('should return false on error (fail-open)', async () => {
+            mockedDynamoDbClient.safeGet.mockRejectedValueOnce(new Error('DynamoDB error'));
+            const result = await IdentityCacheDynamoDbDbService.getForcePurgeFlag('pixel123', 'identity456');
+            expect(result).toBe(false);
+        });
+        it('should return false for missing params', async () => {
+            const result = await IdentityCacheDynamoDbDbService.getForcePurgeFlag('', '');
+            expect(result).toBe(false);
+            expect(mockedDynamoDbClient.safeGet).not.toHaveBeenCalled();
+        });
+    });
+    describe('setForcePurgeFlag', () => {
+        it('should set flag with TTL', async () => {
+            await IdentityCacheDynamoDbDbService.setForcePurgeFlag('pixel123', 'identity456');
+            expect(mockedDynamoDbClient.safePut).toHaveBeenCalledTimes(1);
+            const putItem = mockedDynamoDbClient.safePut.mock.calls[0][1];
+            expect(putItem.pk).toBe('force_purge#pixel123#identity456');
+            expect(putItem.pixelId).toBe('pixel123');
+            expect(putItem.identityId).toBe('identity456');
+            expect(putItem.ttl).toBeGreaterThan(0);
+        });
+        it('should accept custom TTL', async () => {
+            await IdentityCacheDynamoDbDbService.setForcePurgeFlag('pixel123', 'identity456', 3600);
+            const putItem = mockedDynamoDbClient.safePut.mock.calls[0][1];
+            expect(putItem.ttl).toBeGreaterThan(0);
+        });
+        it('should include createdAt timestamp', async () => {
+            const before = new Date().toISOString();
+            await IdentityCacheDynamoDbDbService.setForcePurgeFlag('pixel123', 'identity456');
+            const after = new Date().toISOString();
+            const putItem = mockedDynamoDbClient.safePut.mock.calls[0][1];
+            expect(putItem.createdAt).toBeDefined();
+            expect(putItem.createdAt >= before).toBe(true);
+            expect(putItem.createdAt <= after).toBe(true);
+        });
+        it('should return early when pixelId is missing', async () => {
+            await IdentityCacheDynamoDbDbService.setForcePurgeFlag('', 'identity456');
+            expect(mockedDynamoDbClient.safePut).not.toHaveBeenCalled();
+        });
+        it('should return early when identityId is missing', async () => {
+            await IdentityCacheDynamoDbDbService.setForcePurgeFlag('pixel123', '');
+            expect(mockedDynamoDbClient.safePut).not.toHaveBeenCalled();
+        });
+        it('should not throw on error (fail-open)', async () => {
+            mockedDynamoDbClient.safePut.mockRejectedValueOnce(new Error('DynamoDB error'));
+            await expect(IdentityCacheDynamoDbDbService.setForcePurgeFlag('pixel123', 'identity456')).resolves.toBeUndefined();
+        });
+    });
+    describe('putIdentityMap', () => {
+        it('should write identity map', async () => {
+            await IdentityCacheDynamoDbDbService.putIdentityMap('pixel123', 'identity456', ['linked1', 'linked2']);
+            expect(mockedDynamoDbClient.safePut).toHaveBeenCalledTimes(1);
+            const putItem = mockedDynamoDbClient.safePut.mock.calls[0][1];
+            expect(putItem.pk).toBe('identity_map#pixel123#identity456');
+            expect(putItem.linkedIdentities).toEqual(['linked1', 'linked2']);
+        });
+        it('should return early for missing params', async () => {
+            await IdentityCacheDynamoDbDbService.putIdentityMap('', '', []);
+            expect(mockedDynamoDbClient.safePut).not.toHaveBeenCalled();
+        });
+        it('should return early when only pixelId is missing', async () => {
+            await IdentityCacheDynamoDbDbService.putIdentityMap('', 'identity456', ['linked1']);
+            expect(mockedDynamoDbClient.safePut).not.toHaveBeenCalled();
+        });
+        it('should return early when only identityId is missing', async () => {
+            await IdentityCacheDynamoDbDbService.putIdentityMap('pixel123', '', ['linked1']);
+            expect(mockedDynamoDbClient.safePut).not.toHaveBeenCalled();
+        });
+        it('should include updatedAt timestamp', async () => {
+            const before = new Date().toISOString();
+            await IdentityCacheDynamoDbDbService.putIdentityMap('pixel123', 'identity456', ['linked1']);
+            const after = new Date().toISOString();
+            const putItem = mockedDynamoDbClient.safePut.mock.calls[0][1];
+            expect(putItem.updatedAt).toBeDefined();
+            expect(putItem.updatedAt >= before).toBe(true);
+            expect(putItem.updatedAt <= after).toBe(true);
+        });
+        it('should not throw on safePut error (fail-open)', async () => {
+            mockedDynamoDbClient.safePut.mockRejectedValueOnce(new Error('DynamoDB error'));
+            await expect(IdentityCacheDynamoDbDbService.putIdentityMap('pixel123', 'identity456', ['linked1'])).resolves.toBeUndefined();
+        });
+    });
+    describe('deleteIdentityMap', () => {
+        it('should delete identity map', async () => {
+            await IdentityCacheDynamoDbDbService.deleteIdentityMap('pixel123', 'identity456');
+            expect(mockedDynamoDbClient.safeDelete).toHaveBeenCalledWith(expect.any(String), 'pk', 'identity_map#pixel123#identity456');
+        });
+        it('should return early for missing params', async () => {
+            await IdentityCacheDynamoDbDbService.deleteIdentityMap('', '');
+            expect(mockedDynamoDbClient.safeDelete).not.toHaveBeenCalled();
+        });
+        it('should return early when only pixelId is missing', async () => {
+            await IdentityCacheDynamoDbDbService.deleteIdentityMap('', 'identity456');
+            expect(mockedDynamoDbClient.safeDelete).not.toHaveBeenCalled();
+        });
+        it('should return early when only identityId is missing', async () => {
+            await IdentityCacheDynamoDbDbService.deleteIdentityMap('pixel123', '');
+            expect(mockedDynamoDbClient.safeDelete).not.toHaveBeenCalled();
+        });
+        it('should not throw on safeDelete error (fail-open)', async () => {
+            mockedDynamoDbClient.safeDelete.mockRejectedValueOnce(new Error('DynamoDB error'));
+            await expect(IdentityCacheDynamoDbDbService.deleteIdentityMap('pixel123', 'identity456')).resolves.toBeUndefined();
+        });
+    });
+    describe('deleteForcePurgeFlag', () => {
+        it('should delete force purge flag', async () => {
+            await IdentityCacheDynamoDbDbService.deleteForcePurgeFlag('pixel123', 'identity456');
+            expect(mockedDynamoDbClient.safeDelete).toHaveBeenCalledWith(expect.any(String), 'pk', 'force_purge#pixel123#identity456');
+        });
+        it('should return early for missing params', async () => {
+            await IdentityCacheDynamoDbDbService.deleteForcePurgeFlag('', '');
+            expect(mockedDynamoDbClient.safeDelete).not.toHaveBeenCalled();
+        });
+        it('should return early when only pixelId is missing', async () => {
+            await IdentityCacheDynamoDbDbService.deleteForcePurgeFlag('', 'identity456');
+            expect(mockedDynamoDbClient.safeDelete).not.toHaveBeenCalled();
+        });
+        it('should return early when only identityId is missing', async () => {
+            await IdentityCacheDynamoDbDbService.deleteForcePurgeFlag('pixel123', '');
+            expect(mockedDynamoDbClient.safeDelete).not.toHaveBeenCalled();
+        });
+        it('should not throw on safeDelete error (fail-open)', async () => {
+            mockedDynamoDbClient.safeDelete.mockRejectedValueOnce(new Error('DynamoDB error'));
+            await expect(IdentityCacheDynamoDbDbService.deleteForcePurgeFlag('pixel123', 'identity456')).resolves.toBeUndefined();
+        });
+    });
+    describe('deleteIdentityCache', () => {
+        const pixelId = 'pixel123';
+        it('should delete all related cache items', async () => {
+            mockedDynamoDbClient.safeQueryByGSI.mockResolvedValue([
+                { pk: `identity#${pixelId}#identity456`, pixelId },
+                { pk: `email#${pixelId}#test@email.com`, pixelId },
+            ]);
+            mockedDynamoDbClient.batchWrite.mockResolvedValue({ $metadata: {} });
+            const incomingIdentity = {
+                identityId: 'identity456',
+                traits: { emails: ['test@email.com'] },
+            };
+            const resolvedIdentity = {
+                identityId: 'identity456',
+                traits: { emails: ['test@email.com', 'other@email.com'] },
+            };
+            await IdentityCacheDynamoDbDbService.deleteIdentityCache(pixelId, incomingIdentity, resolvedIdentity);
+            expect(mockedDynamoDbClient.safeQueryByGSI).toHaveBeenCalled();
+            expect(mockedDynamoDbClient.batchWrite).toHaveBeenCalled();
+        });
+        it('should return early for missing pixelId', async () => {
+            await IdentityCacheDynamoDbDbService.deleteIdentityCache(null, {}, {});
+            expect(mockedDynamoDbClient.safeQueryByGSI).not.toHaveBeenCalled();
+        });
+        it('should handle different identityIds in incoming vs resolved', async () => {
+            mockedDynamoDbClient.safeQueryByGSI.mockResolvedValue([{ pk: `identity#${pixelId}#incoming-id`, pixelId }]);
+            mockedDynamoDbClient.batchWrite.mockResolvedValue({ $metadata: {} });
+            const incomingIdentity = {
+                identityId: 'incoming-id',
+                traits: { emails: ['test@email.com'] },
+            };
+            const resolvedIdentity = {
+                identityId: 'resolved-id',
+                traits: { emails: ['test@email.com'] },
+            };
+            await IdentityCacheDynamoDbDbService.deleteIdentityCache(pixelId, incomingIdentity, resolvedIdentity);
+            expect(mockedDynamoDbClient.safeQueryByGSI).toHaveBeenCalledTimes(2);
+        });
+        it('should not throw on batchWrite error (fail-open)', async () => {
+            mockedDynamoDbClient.safeQueryByGSI.mockResolvedValue([{ pk: `identity#${pixelId}#identity456`, pixelId }]);
+            mockedDynamoDbClient.batchWrite.mockRejectedValueOnce(new Error('DynamoDB error'));
+            await expect(IdentityCacheDynamoDbDbService.deleteIdentityCache(pixelId, { identityId: 'identity456' }, { identityId: 'identity456' })).resolves.toBeUndefined();
+        });
+        it('should deduplicate keys when same items returned from GSI query', async () => {
+            const duplicateItem = { pk: `identity#${pixelId}#identity456`, pixelId };
+            mockedDynamoDbClient.safeQueryByGSI.mockResolvedValue([duplicateItem, duplicateItem]);
+            mockedDynamoDbClient.batchWrite.mockResolvedValue({ $metadata: {} });
+            await IdentityCacheDynamoDbDbService.deleteIdentityCache(pixelId, { identityId: 'identity456' }, { identityId: 'identity456' });
+            expect(mockedDynamoDbClient.batchWrite).toHaveBeenCalled();
+            const batchWriteCall = mockedDynamoDbClient.batchWrite.mock.calls[0];
+            expect(batchWriteCall).toBeDefined();
+        });
+    });
+    describe('merge and staleness logic', () => {
+        const pixelId = 'pixel123';
+        it('should merge incoming traits with cached traits', async () => {
+            const cachedResponse = {
+                pk: `identity#${pixelId}#identity456`,
+                pixelId,
+                identityId: 'identity456',
+                response: {
+                    identityId: 'identity456',
+                    traits: {
+                        emails: ['cached@email.com'],
+                        userIds: ['cached-user'],
+                    },
+                },
+                updatedAt: new Date().toISOString(),
+            };
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCache(pixelId, {
+                identityId: 'identity456',
+                traits: {
+                    emails: ['incoming@email.com'],
+                    phones: ['+1234567890'],
+                },
+            });
+            expect(result.resolvedIdentity?.traits?.emails).toContain('incoming@email.com');
+            expect(result.resolvedIdentity?.traits?.emails).toContain('cached@email.com');
+            expect(result.resolvedIdentity?.traits?.userIds).toContain('cached-user');
+            expect(result.resolvedIdentity?.traits?.phones).toContain('+1234567890');
+        });
+        it('should mark cache stale when new data present', async () => {
+            const cachedResponse = {
+                pk: `identity#${pixelId}#identity456`,
+                pixelId,
+                identityId: 'identity456',
+                response: {
+                    identityId: 'identity456',
+                    traits: { emails: ['cached@email.com'] },
+                },
+                updatedAt: new Date().toISOString(),
+            };
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCache(pixelId, {
+                identityId: 'identity456',
+                traits: {
+                    emails: ['cached@email.com', 'new@email.com'],
+                },
+            });
+            expect(result.isCacheStale).toBe(true);
+        });
+        it('should not mark cache stale when incoming is subset of cached', async () => {
+            const cachedResponse = {
+                pk: `identity#${pixelId}#identity456`,
+                pixelId,
+                identityId: 'identity456',
+                response: {
+                    identityId: 'identity456',
+                    traits: {
+                        emails: ['a@email.com', 'b@email.com'],
+                        userIds: ['user1', 'user2'],
+                    },
+                },
+                updatedAt: new Date().toISOString(),
+            };
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCache(pixelId, {
+                identityId: 'identity456',
+                traits: {
+                    emails: ['a@email.com'],
+                },
+            });
+            expect(result.isCacheStale).toBe(false);
+        });
+    });
+    describe('multiple emails pointer writes', () => {
+        const pixelId = 'pixel123';
+        it('should write ALL emails as pointer records (not just first)', async () => {
+            const identity = {
+                identityId: 'identity456',
+                traits: {
+                    emails: ['first@email.com', 'second@email.com', 'third@email.com', 'fourth@email.com'],
+                },
+            };
+            await IdentityCacheDynamoDbDbService.updateIdentityCache(pixelId, identity);
+            const writtenItems = mockedDynamoDbClient.safeBatchWrite.mock.calls[0][1];
+            expect(writtenItems).toHaveLength(5);
+            const emailPks = writtenItems
+                .filter((item) => item.pk.startsWith('email#'))
+                .map((item) => item.pk);
+            expect(emailPks).toContain(`email#${pixelId}#first@email.com`);
+            expect(emailPks).toContain(`email#${pixelId}#second@email.com`);
+            expect(emailPks).toContain(`email#${pixelId}#third@email.com`);
+            expect(emailPks).toContain(`email#${pixelId}#fourth@email.com`);
+        });
+        it('should skip null/undefined emails in array', async () => {
+            const identity = {
+                identityId: 'identity456',
+                traits: {
+                    emails: ['valid@email.com', null, undefined, '', 'another@email.com'],
+                },
+            };
+            await IdentityCacheDynamoDbDbService.updateIdentityCache(pixelId, identity);
+            const writtenItems = mockedDynamoDbClient.safeBatchWrite.mock.calls[0][1];
+            const emailItems = writtenItems.filter((item) => item.pk.startsWith('email#'));
+            expect(emailItems).toHaveLength(2);
+            expect(emailItems.map((e) => e.pk)).toContain(`email#${pixelId}#valid@email.com`);
+            expect(emailItems.map((e) => e.pk)).toContain(`email#${pixelId}#another@email.com`);
+        });
+        it('should handle empty emails array', async () => {
+            const identity = {
+                identityId: 'identity456',
+                traits: { emails: [] },
+            };
+            await IdentityCacheDynamoDbDbService.updateIdentityCache(pixelId, identity);
+            const writtenItems = mockedDynamoDbClient.safeBatchWrite.mock.calls[0][1];
+            expect(writtenItems).toHaveLength(1);
+            expect(writtenItems[0].pk).toBe(`identity#${pixelId}#identity456`);
+        });
+        it('should handle email normalization (lowercase)', async () => {
+            const identity = {
+                identityId: 'identity456',
+                traits: {
+                    emails: ['UPPERCASE@EMAIL.COM', 'MixedCase@Email.Com'],
+                },
+            };
+            await IdentityCacheDynamoDbDbService.updateIdentityCache(pixelId, identity);
+            const writtenItems = mockedDynamoDbClient.safeBatchWrite.mock.calls[0][1];
+            const emailPks = writtenItems
+                .filter((item) => item.pk.startsWith('email#'))
+                .map((item) => item.pk);
+            expect(emailPks).toContain(`email#${pixelId}#uppercase@email.com`);
+            expect(emailPks).toContain(`email#${pixelId}#mixedcase@email.com`);
+        });
+    });
+    describe('null/undefined traits edge cases', () => {
+        const pixelId = 'pixel123';
+        it('should handle null traits object', async () => {
+            const identity = {
+                identityId: 'identity456',
+                traits: null,
+            };
+            await IdentityCacheDynamoDbDbService.updateIdentityCache(pixelId, identity);
+            const writtenItems = mockedDynamoDbClient.safeBatchWrite.mock.calls[0][1];
+            expect(writtenItems).toHaveLength(1);
+        });
+        it('should handle undefined traits object', async () => {
+            const identity = {
+                identityId: 'identity456',
+                traits: undefined,
+            };
+            await IdentityCacheDynamoDbDbService.updateIdentityCache(pixelId, identity);
+            const writtenItems = mockedDynamoDbClient.safeBatchWrite.mock.calls[0][1];
+            expect(writtenItems).toHaveLength(1);
+        });
+        it('should return cache miss for identity with null traits in lookup', async () => {
+            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCache(pixelId, {
+                traits: null,
+            });
+            expect(result.resolvedIdentity).toBeUndefined();
+            expect(result.isCacheStale).toBe(true);
+            expect(mockedDynamoDbClient.safeGet).not.toHaveBeenCalled();
+        });
+        it('should handle identity with undefined emails in traits', async () => {
+            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCache(pixelId, {
+                traits: { userIds: ['user123'] },
+            });
+            expect(result.resolvedIdentity).toBeUndefined();
+            expect(result.isCacheStale).toBe(true);
+        });
+    });
+    describe('backward compatibility (old full-blob format)', () => {
+        const pixelId = 'pixel123';
+        it('should read old format email record with full response blob', async () => {
+            const oldFormatEmailRecord = {
+                pk: `email#${pixelId}#test@email.com`,
+                pixelId,
+                identityId: 'discovered-id',
+                gsi1pk: 'discovered-id',
+                response: {
+                    identityId: 'discovered-id',
+                    traits: { emails: ['test@email.com', 'other@email.com'] },
+                },
+                updatedAt: new Date().toISOString(),
+            };
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(oldFormatEmailRecord);
+            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCache(pixelId, {
+                traits: { emails: ['test@email.com'] },
+            });
+            expect(result.resolvedIdentity).toBeDefined();
+            expect(result.resolvedIdentity?.identityId).toBe('discovered-id');
+            expect(result.isCacheStale).toBe(true);
+        });
+        it('should read new format pointer record (no response blob)', async () => {
+            const newFormatPointerRecord = {
+                pk: `email#${pixelId}#test@email.com`,
+                pixelId,
+                identityId: 'discovered-id',
+                gsi1pk: 'discovered-id',
+                updatedAt: new Date().toISOString(),
+            };
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(newFormatPointerRecord);
+            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCache(pixelId, {
+                traits: { emails: ['test@email.com'] },
+            });
+            expect(result.resolvedIdentity).toBeDefined();
+            expect(result.resolvedIdentity?.identityId).toBe('discovered-id');
+            expect(result.isCacheStale).toBe(true);
+        });
+        it('should trigger Neptune resolution after finding pointer record', async () => {
+            const lambdaArn = 'arn:aws:lambda:us-east-1:123456789:function:identity-private';
+            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', 'resolved@email.com'] },
+                    },
+                }),
+            });
+            const result = await IdentityGatewayService.getIdentityWithCaching(pixelId, { traits: { emails: ['test@email.com'] } }, lambdaArn);
+            expect(mockInvokeFunction).toHaveBeenCalledWith(lambdaArn, expect.objectContaining({
+                pixelId,
+                context: {
+                    identity: expect.objectContaining({
+                        identityId: 'discovered-id',
+                    }),
+                },
+            }));
+            expect(result?.identityId).toBe('discovered-id');
+        });
+    });
+    describe('deleteIdentityCache with multiple email pointers', () => {
+        const pixelId = 'pixel123';
+        it('should delete all email pointers from both incoming and resolved identities', async () => {
+            mockedDynamoDbClient.safeQueryByGSI.mockResolvedValue([
+                { pk: `identity#${pixelId}#identity456`, pixelId },
+            ]);
+            mockedDynamoDbClient.batchWrite.mockResolvedValue({ $metadata: {} });
+            const incomingIdentity = {
+                identityId: 'identity456',
+                traits: { emails: ['incoming1@email.com', 'incoming2@email.com'] },
+            };
+            const resolvedIdentity = {
+                identityId: 'identity456',
+                traits: { emails: ['resolved1@email.com', 'resolved2@email.com', 'resolved3@email.com'] },
+            };
+            await IdentityCacheDynamoDbDbService.deleteIdentityCache(pixelId, incomingIdentity, resolvedIdentity);
+            expect(mockedDynamoDbClient.batchWrite).toHaveBeenCalled();
+            const batchWriteCall = mockedDynamoDbClient.batchWrite.mock.calls[0][0];
+            const deleteRequests = batchWriteCall.RequestItems[Object.keys(batchWriteCall.RequestItems)[0]];
+            const deletedPks = deleteRequests.map((req) => req.DeleteRequest.Key.pk);
+            expect(deletedPks).toContain(`identity#${pixelId}#identity456`);
+            expect(deletedPks).toContain(`email#${pixelId}#incoming1@email.com`);
+            expect(deletedPks).toContain(`email#${pixelId}#incoming2@email.com`);
+            expect(deletedPks).toContain(`email#${pixelId}#resolved1@email.com`);
+            expect(deletedPks).toContain(`email#${pixelId}#resolved2@email.com`);
+            expect(deletedPks).toContain(`email#${pixelId}#resolved3@email.com`);
+        });
+        it('should handle empty emails in delete', async () => {
+            mockedDynamoDbClient.safeQueryByGSI.mockResolvedValue([
+                { pk: `identity#${pixelId}#identity456`, pixelId },
+            ]);
+            mockedDynamoDbClient.batchWrite.mockResolvedValue({ $metadata: {} });
+            await IdentityCacheDynamoDbDbService.deleteIdentityCache(pixelId, { identityId: 'identity456', traits: { emails: [] } }, { identityId: 'identity456' });
+            expect(mockedDynamoDbClient.batchWrite).toHaveBeenCalled();
+        });
+        it('should handle missing traits in delete', async () => {
+            mockedDynamoDbClient.safeQueryByGSI.mockResolvedValue([
+                { pk: `identity#${pixelId}#identity456`, pixelId },
+            ]);
+            mockedDynamoDbClient.batchWrite.mockResolvedValue({ $metadata: {} });
+            await IdentityCacheDynamoDbDbService.deleteIdentityCache(pixelId, { identityId: 'identity456' }, { identityId: 'identity456' });
+            expect(mockedDynamoDbClient.batchWrite).toHaveBeenCalled();
+        });
+        it('should not delete items from other pixelIds', async () => {
+            const otherPixelId = 'other-pixel';
+            mockedDynamoDbClient.safeQueryByGSI.mockResolvedValue([
+                { pk: `identity#${pixelId}#identity456`, pixelId },
+                { pk: `identity#${otherPixelId}#identity456`, pixelId: otherPixelId },
+            ]);
+            mockedDynamoDbClient.batchWrite.mockResolvedValue({ $metadata: {} });
+            await IdentityCacheDynamoDbDbService.deleteIdentityCache(pixelId, { identityId: 'identity456' }, { identityId: 'identity456' });
+            const batchWriteCall = mockedDynamoDbClient.batchWrite.mock.calls[0][0];
+            const deleteRequests = batchWriteCall.RequestItems[Object.keys(batchWriteCall.RequestItems)[0]];
+            const deletedPks = deleteRequests.map((req) => req.DeleteRequest.Key.pk);
+            expect(deletedPks).toContain(`identity#${pixelId}#identity456`);
+            expect(deletedPks).not.toContain(`identity#${otherPixelId}#identity456`);
+        });
+    });
+    describe('GSI1 query for reverse lookups', () => {
+        const pixelId = 'pixel123';
+        it('should find all records by identityId via GSI1', async () => {
+            const identityId = 'identity456';
+            const mockResults = [
+                { pk: `identity#${pixelId}#${identityId}`, pixelId, identityId },
+                { pk: `email#${pixelId}#email1@test.com`, pixelId, identityId },
+                { pk: `email#${pixelId}#email2@test.com`, pixelId, identityId },
+            ];
+            mockedDynamoDbClient.safeQueryByGSI.mockResolvedValue(mockResults);
+            mockedDynamoDbClient.batchWrite.mockResolvedValue({ $metadata: {} });
+            await IdentityCacheDynamoDbDbService.deleteIdentityCache(pixelId, { identityId }, { identityId });
+            expect(mockedDynamoDbClient.safeQueryByGSI).toHaveBeenCalledWith(expect.any(String), expect.any(String), 'gsi1pk', identityId);
+        });
+        it('should handle GSI1 query returning empty results', async () => {
+            mockedDynamoDbClient.safeQueryByGSI.mockResolvedValue([]);
+            await IdentityCacheDynamoDbDbService.deleteIdentityCache(pixelId, { identityId: 'unknown-id' }, { identityId: 'unknown-id' });
+            expect(mockedDynamoDbClient.batchWrite).not.toHaveBeenCalled();
+        });
+        it('should handle GSI1 query error gracefully (fail-open)', async () => {
+            mockedDynamoDbClient.safeQueryByGSI.mockRejectedValueOnce(new Error('GSI query failed'));
+            await expect(IdentityCacheDynamoDbDbService.deleteIdentityCache(pixelId, { identityId: 'identity456' }, { identityId: 'identity456' })).resolves.toBeUndefined();
+        });
+    });
+    describe('email pointer lookups', () => {
+        const pixelId = 'pixel123';
+        it('should only lookup first email (optimization)', async () => {
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
+            await IdentityCacheDynamoDbDbService.getIdentityFromCache(pixelId, {
+                traits: { emails: ['first@email.com', 'second@email.com', 'third@email.com'] },
+            });
+            expect(mockedDynamoDbClient.safeGet).toHaveBeenCalledTimes(1);
+            expect(mockedDynamoDbClient.safeGet).toHaveBeenCalledWith(expect.any(String), 'pk', `email#${pixelId}#first@email.com`);
+        });
+        it('should handle whitespace in email during lookup', async () => {
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
+            await IdentityCacheDynamoDbDbService.getIdentityFromCache(pixelId, {
+                traits: { emails: ['  test@email.com  '] },
+            });
+            expect(mockedDynamoDbClient.safeGet).toHaveBeenCalled();
+        });
+    });
+    describe('fail-open behavior comprehensive', () => {
+        const pixelId = 'pixel123';
+        const lambdaArn = 'arn:aws:lambda:us-east-1:123456789:function:identity-private';
+        it('should return incoming identity when Neptune throws (fail-open fallback)', async () => {
+            const incomingIdentity = {
+                identityId: 'identity456',
+                traits: { emails: ['test@email.com'] },
+            };
+            mockedDynamoDbClient.safeGet.mockRejectedValueOnce(new Error('DynamoDB down'));
+            mockInvokeFunction.mockRejectedValueOnce(new Error('Lambda down'));
+            const result = await IdentityGatewayService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
+            expect(result).toEqual(incomingIdentity);
+        });
+        it('should continue when cache write fails after Neptune success', async () => {
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
+            mockInvokeFunction.mockResolvedValueOnce({
+                statusCode: 200,
+                body: JSON.stringify({
+                    identity: { identityId: 'resolved-id', traits: { emails: ['test@email.com'] } },
+                }),
+            });
+            mockedDynamoDbClient.safeBatchWrite.mockRejectedValueOnce(new Error('Write failed'));
+            const result = await IdentityGatewayService.getIdentityWithCaching(pixelId, { traits: { emails: ['test@email.com'] } }, lambdaArn);
+            expect(result?.identityId).toBe('resolved-id');
+        });
+        it('should return incoming identity when Neptune returns non-200', async () => {
+            const incomingIdentity = {
+                identityId: 'incoming-id',
+                traits: { emails: ['test@email.com'] },
+            };
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
+            mockInvokeFunction.mockResolvedValueOnce({
+                statusCode: 500,
+                body: 'Internal Server Error',
+            });
+            const result = await IdentityGatewayService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
+            expect(result).toEqual(incomingIdentity);
+        });
+        it('should return incoming identity when Neptune returns malformed JSON (fail-open)', async () => {
+            const incomingIdentity = {
+                identityId: 'test-id',
+                traits: { emails: ['test@email.com'] },
+            };
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
+            mockInvokeFunction.mockResolvedValueOnce({
+                statusCode: 200,
+                body: 'not valid json',
+            });
+            const result = await IdentityGatewayService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
+            expect(result).toEqual(incomingIdentity);
+        });
+        it('should return undefined only when both inputs are invalid', async () => {
+            const result = await IdentityGatewayService.getIdentityWithCaching(null, null, lambdaArn);
+            expect(result).toBeUndefined();
+        });
+    });
+    describe('getIdentityWithCachingV2', () => {
+        const pixelId = 'pixel123';
+        const lambdaArn = 'arn:aws:lambda:us-east-1:123456789:function:identity-private';
+        it('should return invalid input summary without resolving', async () => {
+            const result = await IdentityGatewayService.getIdentityWithCachingV2('', { identityId: 'identity456' }, lambdaArn);
+            expect(result.identity).toBeUndefined();
+            expect(result.summary).toEqual(expect.objectContaining({
+                outcome: IDENTITY_CACHE_WITH_CACHING_OUTCOME.INVALID_INPUT,
+                didReadCache: false,
+                didCallNeptune: false,
+                didWriteCache: false,
+            }));
+            expect(mockInvokeFunction).not.toHaveBeenCalled();
+            expect(mockedDynamoDbClient.safeBatchWrite).not.toHaveBeenCalled();
+        });
+        it('should return fresh cache hit summary without invoking Neptune', 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 IdentityGatewayService.getIdentityWithCachingV2(pixelId, incomingIdentity, lambdaArn);
+            expect(result.identity?.identityId).toBe('identity456');
+            expect(result.summary).toEqual(expect.objectContaining({
+                outcome: IDENTITY_CACHE_WITH_CACHING_OUTCOME.FRESH_CACHE_HIT,
+                pixelId,
+                identityId: 'identity456',
+                didReadCache: true,
+                didCallNeptune: false,
+                didWriteCache: false,
+                cachedIdentity: cachedResponse.response,
+                incomingIdentity,
+                resolvedIdentity: expect.objectContaining({ identityId: 'identity456' }),
+            }));
+            expect(mockInvokeFunction).not.toHaveBeenCalled();
+        });
+        it('should return Neptune write-back summary on cache miss', async () => {
+            const incomingIdentity = {
+                identityId: 'identity456',
+                traits: { emails: ['test@email.com'] },
+            };
+            const neptuneIdentity = {
+                identityId: 'resolved-identity',
+                traits: { emails: ['test@email.com', 'resolved@email.com'] },
+            };
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
+            mockInvokeFunction.mockResolvedValueOnce({
+                statusCode: 200,
+                body: JSON.stringify({ identity: neptuneIdentity }),
+            });
+            const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, incomingIdentity, lambdaArn);
+            expect(result.identity).toEqual(neptuneIdentity);
+            expect(result.summary).toEqual(expect.objectContaining({
+                outcome: IDENTITY_CACHE_WITH_CACHING_OUTCOME.NEPTUNE_WRITE_BACK,
+                pixelId,
+                identityId: 'resolved-identity',
+                didReadCache: true,
+                didCallNeptune: true,
+                didWriteCache: true,
+                incomingIdentity,
+                identityForNeptune: incomingIdentity,
+                neptuneIdentity,
+                traitChanges: { reason: { resolved: 'no cached identity' } },
+            }));
+            expect(mockedDynamoDbClient.safeBatchWrite).toHaveBeenCalled();
+        });
+        it('should return Neptune skip-write summary when Neptune matches cached identity', async () => {
+            const incomingIdentity = {
+                identityId: 'identity456',
+                traits: { emails: ['old@email.com', 'new@email.com'] },
+            };
+            const cachedIdentity = {
+                identityId: 'identity456',
+                traits: { emails: ['old@email.com'] },
+            };
+            const cachedResponse = {
+                pk: `identity#${pixelId}#identity456`,
+                pixelId,
+                identityId: 'identity456',
+                response: cachedIdentity,
+                updatedAt: new Date().toISOString(),
+            };
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+            mockInvokeFunction.mockResolvedValueOnce({
+                statusCode: 200,
+                body: JSON.stringify({ identity: cachedIdentity }),
+            });
+            const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, incomingIdentity, lambdaArn);
+            expect(result.identity).toEqual(cachedIdentity);
+            expect(result.summary).toEqual(expect.objectContaining({
+                outcome: IDENTITY_CACHE_WITH_CACHING_OUTCOME.NEPTUNE_SKIP_WRITE,
+                pixelId,
+                identityId: 'identity456',
+                didReadCache: true,
+                didCallNeptune: true,
+                didWriteCache: false,
+                cachedIdentity,
+                incomingIdentity,
+                identityForNeptune: expect.objectContaining({ identityId: 'identity456' }),
+                neptuneIdentity: cachedIdentity,
+            }));
+            expect(mockedDynamoDbClient.safeBatchWrite).not.toHaveBeenCalled();
+        });
+    });
+    describe('gsi1pk attribute on all records', () => {
+        const pixelId = 'pixel123';
+        it('should include gsi1pk on identity record', async () => {
+            const identity = {
+                identityId: 'identity456',
+                traits: { emails: ['test@email.com'] },
+            };
+            await IdentityCacheDynamoDbDbService.updateIdentityCache(pixelId, identity);
+            const writtenItems = mockedDynamoDbClient.safeBatchWrite.mock.calls[0][1];
+            const identityItem = writtenItems.find((item) => item.pk.startsWith('identity#'));
+            expect(identityItem).toBeDefined();
+            expect(identityItem?.gsi1pk).toBe('identity456');
+        });
+        it('should include gsi1pk on all email pointer records', async () => {
+            const identity = {
+                identityId: 'identity456',
+                traits: { emails: ['email1@test.com', 'email2@test.com'] },
+            };
+            await IdentityCacheDynamoDbDbService.updateIdentityCache(pixelId, identity);
+            const writtenItems = mockedDynamoDbClient.safeBatchWrite.mock.calls[0][1];
+            const emailItems = writtenItems.filter((item) => item.pk.startsWith('email#'));
+            for (const emailItem of emailItems) {
+                expect(emailItem.gsi1pk).toBe('identity456');
+            }
+        });
+    });
+});
 //# sourceMappingURL=identity-cache-dynamodb-service.spec.js.map