@adtrackify/at-service-common 4.0.5 → 4.0.7

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

@@ -1,3 +1,4 @@
+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: {
@@ -21,10 +22,13 @@ jest.mock('../../helpers/index.js', () => ({
         error: jest.fn(),
     },
 }));
-import { IdentityCacheDynamoDbService, } from '../../services/db/identity-cache-dynamodb-service.js';
+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('IdentityCacheDynamoDbService', () => {
+describe('IdentityGatewayService', () => {
     beforeEach(() => {
         jest.clearAllMocks();
         mockedDynamoDbClient.safeGet.mockReset();
@@ -35,9 +39,33 @@ describe('IdentityCacheDynamoDbService', () => {
         mockedDynamoDbClient.safeQueryByGSI.mockReset();
         mockedDynamoDbClient.batchWrite.mockReset();
         mockInvokeFunction.mockReset();
-        IdentityCacheDynamoDbService.lambdaInvokeClient = undefined;
+        IdentityGatewayService.lambdaInvokeClient = undefined;
     });
-    describe('getIdentityWithCaching', () => {
+    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('getIdentityWithCachingV2', () => {
         const pixelId = 'pixel123';
         const lambdaArn = 'arn:aws:lambda:us-east-1:123456789:function:identity-private';
         describe('cache hit (fresh cache)', () => {
@@ -57,9 +85,9 @@ describe('IdentityCacheDynamoDbService', () => {
                     updatedAt: new Date().toISOString(),
                 };
                 mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
-                const result = await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
-                expect(result).toBeDefined();
-                expect(result?.identityId).toBe('identity456');
+                const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, incomingIdentity, lambdaArn);
+                expect(result.identity).toBeDefined();
+                expect(result.identity?.identityId).toBe('identity456');
                 expect(mockInvokeFunction).not.toHaveBeenCalled();
             });
         });
@@ -79,12 +107,12 @@ describe('IdentityCacheDynamoDbService', () => {
                         },
                     }),
                 });
-                const result = await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
+                const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, incomingIdentity, lambdaArn);
                 expect(mockInvokeFunction).toHaveBeenCalledWith(lambdaArn, {
                     pixelId,
                     context: { identity: incomingIdentity },
                 });
-                expect(result?.identityId).toBe('resolved-identity');
+                expect(result.identity?.identityId).toBe('resolved-identity');
                 expect(mockedDynamoDbClient.safeBatchWrite).toHaveBeenCalled();
             });
             it('should return incomingIdentity when Neptune Lambda fails to resolve', async () => {
@@ -97,8 +125,8 @@ describe('IdentityCacheDynamoDbService', () => {
                     statusCode: 200,
                     body: JSON.stringify({ identity: undefined }),
                 });
-                const result = await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
-                expect(result).toEqual(incomingIdentity);
+                const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, incomingIdentity, lambdaArn);
+                expect(result.identity).toEqual(incomingIdentity);
             });
         });
         describe('cache stale', () => {
@@ -127,10 +155,10 @@ describe('IdentityCacheDynamoDbService', () => {
                         },
                     }),
                 });
-                const result = await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
+                const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, incomingIdentity, lambdaArn);
                 expect(mockInvokeFunction).toHaveBeenCalled();
-                expect(result?.identityId).toBe('identity456');
-                expect(result?.traits?.emails).toContain('new@email.com');
+                expect(result.identity?.identityId).toBe('identity456');
+                expect(result.identity?.traits?.emails).toContain('new@email.com');
             });
             it('should use merged cache identity when Neptune fails', async () => {
                 const incomingIdentity = {
@@ -152,9 +180,9 @@ describe('IdentityCacheDynamoDbService', () => {
                     statusCode: 500,
                     body: 'Internal Server Error',
                 });
-                const result = await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
-                expect(result).toBeDefined();
-                expect(result?.identityId).toBe('identity456');
+                const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, incomingIdentity, lambdaArn);
+                expect(result.identity).toBeDefined();
+                expect(result.identity?.identityId).toBe('identity456');
             });
         });
         describe('Neptune Lambda invocation', () => {
@@ -172,7 +200,7 @@ describe('IdentityCacheDynamoDbService', () => {
                         },
                     }),
                 });
-                await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
+                await IdentityGatewayService.getIdentityWithCachingV2(pixelId, incomingIdentity, lambdaArn);
                 expect(mockedDynamoDbClient.safeBatchWrite).toHaveBeenCalled();
                 const writtenItems = mockedDynamoDbClient.safeBatchWrite.mock.calls[0][1];
                 const identityPks = writtenItems.map((item) => item.pk);
@@ -187,30 +215,33 @@ describe('IdentityCacheDynamoDbService', () => {
                     statusCode: 200,
                     body: JSON.stringify({ identity: undefined }),
                 });
-                await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
+                await IdentityGatewayService.getIdentityWithCachingV2(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();
+            it('should return undefined identity when pixelId is missing', async () => {
+                const result = await IdentityGatewayService.getIdentityWithCachingV2(null, { identityId: 'test-id' }, lambdaArn);
+                expect(result.identity).toBeUndefined();
+                expect(result.summary.outcome).toBe(IDENTITY_CACHE_WITH_CACHING_OUTCOME.INVALID_INPUT);
                 expect(mockInvokeFunction).not.toHaveBeenCalled();
             });
-            it('should return undefined when incomingIdentity is missing', async () => {
-                const result = await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, null, lambdaArn);
-                expect(result).toBeUndefined();
+            it('should return undefined identity when incomingIdentity is missing', async () => {
+                const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, null, lambdaArn);
+                expect(result.identity).toBeUndefined();
+                expect(result.summary.outcome).toBe(IDENTITY_CACHE_WITH_CACHING_OUTCOME.INVALID_INPUT);
                 expect(mockInvokeFunction).not.toHaveBeenCalled();
             });
-            it('should return undefined when Neptune Lambda throws', async () => {
+            it('should return incomingIdentity 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);
+                const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, incomingIdentity, lambdaArn);
+                expect(result.identity).toEqual(incomingIdentity);
+                expect(result.summary.outcome).toBe(IDENTITY_CACHE_WITH_CACHING_OUTCOME.FALLBACK_INCOMING);
             });
             it('should not throw when cache write fails after Neptune success', async () => {
                 const incomingIdentity = {
@@ -227,8 +258,8 @@ describe('IdentityCacheDynamoDbService', () => {
                     }),
                 });
                 mockedDynamoDbClient.safeBatchWrite.mockRejectedValueOnce(new Error('DynamoDB write failed'));
-                const result = await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
-                expect(result?.identityId).toBe('neptune-resolved-id');
+                const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, incomingIdentity, lambdaArn);
+                expect(result.identity?.identityId).toBe('neptune-resolved-id');
             });
         });
     });
@@ -238,7 +269,7 @@ describe('IdentityCacheDynamoDbService', () => {
                 const pixelId = 'pixel123';
                 const identityId = 'identity456';
                 mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
-                await IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, { identityId });
+                await IdentityCacheDynamoDbDbService.getIdentityFromCache(pixelId, { identityId });
                 expect(mockedDynamoDbClient.safeGet).toHaveBeenCalledWith(expect.any(String), 'pk', `identity#${pixelId}#${identityId}`);
             });
         });
@@ -247,7 +278,7 @@ describe('IdentityCacheDynamoDbService', () => {
                 const pixelId = 'pixel123';
                 const email = 'Test@Email.COM';
                 mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
-                await IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, {
+                await IdentityCacheDynamoDbDbService.getIdentityFromCache(pixelId, {
                     traits: { emails: [email] },
                 });
                 expect(mockedDynamoDbClient.safeGet).toHaveBeenCalledWith(expect.any(String), 'pk', `email#${pixelId}#test@email.com`);
@@ -258,7 +289,7 @@ describe('IdentityCacheDynamoDbService', () => {
                 const pixelId = 'pixel123';
                 const userId = '  user789  ';
                 mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
-                await IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, {
+                await IdentityCacheDynamoDbDbService.getIdentityFromCache(pixelId, {
                     traits: { userIds: [userId] },
                 });
                 expect(mockedDynamoDbClient.safeBatchGet).not.toHaveBeenCalled();
@@ -281,7 +312,7 @@ describe('IdentityCacheDynamoDbService', () => {
                     updatedAt: new Date().toISOString(),
                 };
                 mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
-                const result = await IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, {
+                const result = await IdentityCacheDynamoDbDbService.getIdentityFromCache(pixelId, {
                     identityId,
                     traits: { emails: ['test@email.com'] },
                 });
@@ -291,7 +322,7 @@ describe('IdentityCacheDynamoDbService', () => {
             });
             it('should return cache miss when identity not found', async () => {
                 mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
-                const result = await IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, {
+                const result = await IdentityCacheDynamoDbDbService.getIdentityFromCache(pixelId, {
                     identityId: 'unknown-id',
                 });
                 expect(result.resolvedIdentity).toBeUndefined();
@@ -299,7 +330,7 @@ describe('IdentityCacheDynamoDbService', () => {
             });
             it('should NOT fallback to secondary keys when identityId lookup misses', async () => {
                 mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
-                await IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, {
+                await IdentityCacheDynamoDbDbService.getIdentityFromCache(pixelId, {
                     identityId: 'unknown-id',
                     traits: { emails: ['test@email.com'] },
                 });
@@ -318,7 +349,7 @@ describe('IdentityCacheDynamoDbService', () => {
                     updatedAt: new Date().toISOString(),
                 };
                 mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
-                const result = await IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, {
+                const result = await IdentityCacheDynamoDbDbService.getIdentityFromCache(pixelId, {
                     identityId,
                     traits: { emails: ['old@email.com', 'new@email.com'] },
                 });
@@ -336,7 +367,7 @@ describe('IdentityCacheDynamoDbService', () => {
                     updatedAt: new Date().toISOString(),
                 };
                 mockedDynamoDbClient.safeGet.mockResolvedValueOnce(pointerRecord);
-                const result = await IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, {
+                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`);
@@ -354,7 +385,7 @@ describe('IdentityCacheDynamoDbService', () => {
                     updatedAt: new Date().toISOString(),
                 };
                 mockedDynamoDbClient.safeGet.mockResolvedValueOnce(pointerRecord);
-                const result = await IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, {
+                const result = await IdentityCacheDynamoDbDbService.getIdentityFromCache(pixelId, {
                     traits: { emails: ['test@email.com'], userIds: ['user123'] },
                 });
                 expect(result.resolvedIdentity).toBeDefined();
@@ -363,14 +394,14 @@ describe('IdentityCacheDynamoDbService', () => {
             });
             it('should return cache miss when no secondary keys match', async () => {
                 mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
-                const result = await IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, {
+                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 IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, {
+                const result = await IdentityCacheDynamoDbDbService.getIdentityFromCache(pixelId, {
                     traits: { userIds: ['user123'] },
                 });
                 expect(result.resolvedIdentity).toBeUndefined();
@@ -378,7 +409,7 @@ describe('IdentityCacheDynamoDbService', () => {
                 expect(mockedDynamoDbClient.safeGet).not.toHaveBeenCalled();
             });
             it('should return cache miss when empty traits', async () => {
-                const result = await IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, {
+                const result = await IdentityCacheDynamoDbDbService.getIdentityFromCache(pixelId, {
                     traits: {},
                 });
                 expect(result.resolvedIdentity).toBeUndefined();
@@ -388,7 +419,7 @@ describe('IdentityCacheDynamoDbService', () => {
         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, {
+                const result = await IdentityCacheDynamoDbDbService.getIdentityFromCache(pixelId, {
                     identityId: 'test-id',
                 });
                 expect(result.resolvedIdentity).toBeUndefined();
@@ -396,21 +427,21 @@ describe('IdentityCacheDynamoDbService', () => {
             });
             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, {
+                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 IdentityCacheDynamoDbService.getIdentityFromCache(null, {
+                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 IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, null);
+                const result = await IdentityCacheDynamoDbDbService.getIdentityFromCache(pixelId, null);
                 expect(result.resolvedIdentity).toBeUndefined();
                 expect(result.isCacheStale).toBe(true);
             });
@@ -426,7 +457,7 @@ describe('IdentityCacheDynamoDbService', () => {
                     userIds: ['user1', 'user2'],
                 },
             };
-            await IdentityCacheDynamoDbService.updateIdentityCache(pixelId, identity);
+            await IdentityCacheDynamoDbDbService.updateIdentityCache(pixelId, identity);
             expect(mockedDynamoDbClient.safeBatchWrite).toHaveBeenCalledTimes(1);
             const writtenItems = mockedDynamoDbClient.safeBatchWrite.mock.calls[0][1];
             expect(writtenItems).toHaveLength(3);
@@ -438,12 +469,12 @@ describe('IdentityCacheDynamoDbService', () => {
             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');
+            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');
+            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'));
@@ -451,14 +482,14 @@ describe('IdentityCacheDynamoDbService', () => {
                 identityId: 'identity456',
                 traits: { emails: ['test@email.com'] },
             };
-            await expect(IdentityCacheDynamoDbService.updateIdentityCache(pixelId, identity)).resolves.toBeUndefined();
+            await expect(IdentityCacheDynamoDbDbService.updateIdentityCache(pixelId, identity)).resolves.toBeUndefined();
         });
         it('should return early for missing identityId', async () => {
-            await IdentityCacheDynamoDbService.updateIdentityCache(pixelId, {});
+            await IdentityCacheDynamoDbDbService.updateIdentityCache(pixelId, {});
             expect(mockedDynamoDbClient.safeBatchWrite).not.toHaveBeenCalled();
         });
         it('should return early for missing pixelId', async () => {
-            await IdentityCacheDynamoDbService.updateIdentityCache(null, {
+            await IdentityCacheDynamoDbDbService.updateIdentityCache(null, {
                 identityId: 'test-id',
             });
             expect(mockedDynamoDbClient.safeBatchWrite).not.toHaveBeenCalled();
@@ -467,7 +498,7 @@ describe('IdentityCacheDynamoDbService', () => {
             const identity = {
                 identityId: 'identity456',
             };
-            await IdentityCacheDynamoDbService.updateIdentityCache(pixelId, identity);
+            await IdentityCacheDynamoDbDbService.updateIdentityCache(pixelId, identity);
             const writtenItems = mockedDynamoDbClient.safeBatchWrite.mock.calls[0][1];
             expect(writtenItems).toHaveLength(1);
         });
@@ -476,7 +507,7 @@ describe('IdentityCacheDynamoDbService', () => {
                 identityId: 'identity456',
                 traits: { emails: ['test@email.com'] },
             };
-            await IdentityCacheDynamoDbService.updateIdentityCache(pixelId, identity);
+            await IdentityCacheDynamoDbDbService.updateIdentityCache(pixelId, identity);
             const writtenItems = mockedDynamoDbClient.safeBatchWrite.mock.calls[0][1];
             for (const item of writtenItems) {
                 expect(item.gsi1pk).toBe('identity456');
@@ -493,33 +524,33 @@ describe('IdentityCacheDynamoDbService', () => {
                 updatedAt: new Date().toISOString(),
             };
             mockedDynamoDbClient.safeGet.mockResolvedValueOnce(mockMap);
-            const result = await IdentityCacheDynamoDbService.getIdentityMap('pixel123', 'identity456');
+            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 IdentityCacheDynamoDbService.getIdentityMap('pixel123', 'identity456');
+            const result = await IdentityCacheDynamoDbDbService.getIdentityMap('pixel123', 'identity456');
             expect(result).toBeUndefined();
         });
         it('should return undefined for missing params (fail-open)', async () => {
-            const result = await IdentityCacheDynamoDbService.getIdentityMap('', '');
+            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 IdentityCacheDynamoDbService.getIdentityMap('', 'identity456');
+            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 IdentityCacheDynamoDbService.getIdentityMap('pixel123', '');
+            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 IdentityCacheDynamoDbService.getIdentityMap('pixel123', 'identity456');
+            const result = await IdentityCacheDynamoDbDbService.getIdentityMap('pixel123', 'identity456');
             expect(result).toBeUndefined();
         });
     });
@@ -528,28 +559,28 @@ describe('IdentityCacheDynamoDbService', () => {
             mockedDynamoDbClient.safeGet.mockResolvedValueOnce({
                 pk: 'force_purge#pixel123#identity456',
             });
-            const result = await IdentityCacheDynamoDbService.getForcePurgeFlag('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 IdentityCacheDynamoDbService.getForcePurgeFlag('pixel123', 'identity456');
+            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 IdentityCacheDynamoDbService.getForcePurgeFlag('pixel123', 'identity456');
+            const result = await IdentityCacheDynamoDbDbService.getForcePurgeFlag('pixel123', 'identity456');
             expect(result).toBe(false);
         });
         it('should return false for missing params', async () => {
-            const result = await IdentityCacheDynamoDbService.getForcePurgeFlag('', '');
+            const result = await IdentityCacheDynamoDbDbService.getForcePurgeFlag('', '');
             expect(result).toBe(false);
             expect(mockedDynamoDbClient.safeGet).not.toHaveBeenCalled();
         });
     });
     describe('setForcePurgeFlag', () => {
         it('should set flag with TTL', async () => {
-            await IdentityCacheDynamoDbService.setForcePurgeFlag('pixel123', 'identity456');
+            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');
@@ -558,13 +589,13 @@ describe('IdentityCacheDynamoDbService', () => {
             expect(putItem.ttl).toBeGreaterThan(0);
         });
         it('should accept custom TTL', async () => {
-            await IdentityCacheDynamoDbService.setForcePurgeFlag('pixel123', 'identity456', 3600);
+            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 IdentityCacheDynamoDbService.setForcePurgeFlag('pixel123', 'identity456');
+            await IdentityCacheDynamoDbDbService.setForcePurgeFlag('pixel123', 'identity456');
             const after = new Date().toISOString();
             const putItem = mockedDynamoDbClient.safePut.mock.calls[0][1];
             expect(putItem.createdAt).toBeDefined();
@@ -572,41 +603,41 @@ describe('IdentityCacheDynamoDbService', () => {
             expect(putItem.createdAt <= after).toBe(true);
         });
         it('should return early when pixelId is missing', async () => {
-            await IdentityCacheDynamoDbService.setForcePurgeFlag('', 'identity456');
+            await IdentityCacheDynamoDbDbService.setForcePurgeFlag('', 'identity456');
             expect(mockedDynamoDbClient.safePut).not.toHaveBeenCalled();
         });
         it('should return early when identityId is missing', async () => {
-            await IdentityCacheDynamoDbService.setForcePurgeFlag('pixel123', '');
+            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(IdentityCacheDynamoDbService.setForcePurgeFlag('pixel123', 'identity456')).resolves.toBeUndefined();
+            await expect(IdentityCacheDynamoDbDbService.setForcePurgeFlag('pixel123', 'identity456')).resolves.toBeUndefined();
         });
     });
     describe('putIdentityMap', () => {
         it('should write identity map', async () => {
-            await IdentityCacheDynamoDbService.putIdentityMap('pixel123', 'identity456', ['linked1', 'linked2']);
+            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 IdentityCacheDynamoDbService.putIdentityMap('', '', []);
+            await IdentityCacheDynamoDbDbService.putIdentityMap('', '', []);
             expect(mockedDynamoDbClient.safePut).not.toHaveBeenCalled();
         });
         it('should return early when only pixelId is missing', async () => {
-            await IdentityCacheDynamoDbService.putIdentityMap('', 'identity456', ['linked1']);
+            await IdentityCacheDynamoDbDbService.putIdentityMap('', 'identity456', ['linked1']);
             expect(mockedDynamoDbClient.safePut).not.toHaveBeenCalled();
         });
         it('should return early when only identityId is missing', async () => {
-            await IdentityCacheDynamoDbService.putIdentityMap('pixel123', '', ['linked1']);
+            await IdentityCacheDynamoDbDbService.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']);
+            await IdentityCacheDynamoDbDbService.putIdentityMap('pixel123', 'identity456', ['linked1']);
             const after = new Date().toISOString();
             const putItem = mockedDynamoDbClient.safePut.mock.calls[0][1];
             expect(putItem.updatedAt).toBeDefined();
@@ -615,51 +646,51 @@ describe('IdentityCacheDynamoDbService', () => {
         });
         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();
+            await expect(IdentityCacheDynamoDbDbService.putIdentityMap('pixel123', 'identity456', ['linked1'])).resolves.toBeUndefined();
         });
     });
     describe('deleteIdentityMap', () => {
         it('should delete identity map', async () => {
-            await IdentityCacheDynamoDbService.deleteIdentityMap('pixel123', 'identity456');
+            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 IdentityCacheDynamoDbService.deleteIdentityMap('', '');
+            await IdentityCacheDynamoDbDbService.deleteIdentityMap('', '');
             expect(mockedDynamoDbClient.safeDelete).not.toHaveBeenCalled();
         });
         it('should return early when only pixelId is missing', async () => {
-            await IdentityCacheDynamoDbService.deleteIdentityMap('', 'identity456');
+            await IdentityCacheDynamoDbDbService.deleteIdentityMap('', 'identity456');
             expect(mockedDynamoDbClient.safeDelete).not.toHaveBeenCalled();
         });
         it('should return early when only identityId is missing', async () => {
-            await IdentityCacheDynamoDbService.deleteIdentityMap('pixel123', '');
+            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(IdentityCacheDynamoDbService.deleteIdentityMap('pixel123', 'identity456')).resolves.toBeUndefined();
+            await expect(IdentityCacheDynamoDbDbService.deleteIdentityMap('pixel123', 'identity456')).resolves.toBeUndefined();
         });
     });
     describe('deleteForcePurgeFlag', () => {
         it('should delete force purge flag', async () => {
-            await IdentityCacheDynamoDbService.deleteForcePurgeFlag('pixel123', 'identity456');
+            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 IdentityCacheDynamoDbService.deleteForcePurgeFlag('', '');
+            await IdentityCacheDynamoDbDbService.deleteForcePurgeFlag('', '');
             expect(mockedDynamoDbClient.safeDelete).not.toHaveBeenCalled();
         });
         it('should return early when only pixelId is missing', async () => {
-            await IdentityCacheDynamoDbService.deleteForcePurgeFlag('', 'identity456');
+            await IdentityCacheDynamoDbDbService.deleteForcePurgeFlag('', 'identity456');
             expect(mockedDynamoDbClient.safeDelete).not.toHaveBeenCalled();
         });
         it('should return early when only identityId is missing', async () => {
-            await IdentityCacheDynamoDbService.deleteForcePurgeFlag('pixel123', '');
+            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(IdentityCacheDynamoDbService.deleteForcePurgeFlag('pixel123', 'identity456')).resolves.toBeUndefined();
+            await expect(IdentityCacheDynamoDbDbService.deleteForcePurgeFlag('pixel123', 'identity456')).resolves.toBeUndefined();
         });
     });
     describe('deleteIdentityCache', () => {
@@ -678,12 +709,12 @@ describe('IdentityCacheDynamoDbService', () => {
                 identityId: 'identity456',
                 traits: { emails: ['test@email.com', 'other@email.com'] },
             };
-            await IdentityCacheDynamoDbService.deleteIdentityCache(pixelId, incomingIdentity, resolvedIdentity);
+            await IdentityCacheDynamoDbDbService.deleteIdentityCache(pixelId, incomingIdentity, resolvedIdentity);
             expect(mockedDynamoDbClient.safeQueryByGSI).toHaveBeenCalled();
             expect(mockedDynamoDbClient.batchWrite).toHaveBeenCalled();
         });
         it('should return early for missing pixelId', async () => {
-            await IdentityCacheDynamoDbService.deleteIdentityCache(null, {}, {});
+            await IdentityCacheDynamoDbDbService.deleteIdentityCache(null, {}, {});
             expect(mockedDynamoDbClient.safeQueryByGSI).not.toHaveBeenCalled();
         });
         it('should handle different identityIds in incoming vs resolved', async () => {
@@ -697,19 +728,19 @@ describe('IdentityCacheDynamoDbService', () => {
                 identityId: 'resolved-id',
                 traits: { emails: ['test@email.com'] },
             };
-            await IdentityCacheDynamoDbService.deleteIdentityCache(pixelId, incomingIdentity, resolvedIdentity);
+            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(IdentityCacheDynamoDbService.deleteIdentityCache(pixelId, { identityId: 'identity456' }, { identityId: 'identity456' })).resolves.toBeUndefined();
+            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 IdentityCacheDynamoDbService.deleteIdentityCache(pixelId, { identityId: 'identity456' }, { identityId: 'identity456' });
+            await IdentityCacheDynamoDbDbService.deleteIdentityCache(pixelId, { identityId: 'identity456' }, { identityId: 'identity456' });
             expect(mockedDynamoDbClient.batchWrite).toHaveBeenCalled();
             const batchWriteCall = mockedDynamoDbClient.batchWrite.mock.calls[0];
             expect(batchWriteCall).toBeDefined();
@@ -732,7 +763,7 @@ describe('IdentityCacheDynamoDbService', () => {
                 updatedAt: new Date().toISOString(),
             };
             mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
-            const result = await IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, {
+            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCache(pixelId, {
                 identityId: 'identity456',
                 traits: {
                     emails: ['incoming@email.com'],
@@ -756,7 +787,7 @@ describe('IdentityCacheDynamoDbService', () => {
                 updatedAt: new Date().toISOString(),
             };
             mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
-            const result = await IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, {
+            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCache(pixelId, {
                 identityId: 'identity456',
                 traits: {
                     emails: ['cached@email.com', 'new@email.com'],
@@ -779,7 +810,7 @@ describe('IdentityCacheDynamoDbService', () => {
                 updatedAt: new Date().toISOString(),
             };
             mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
-            const result = await IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, {
+            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCache(pixelId, {
                 identityId: 'identity456',
                 traits: {
                     emails: ['a@email.com'],
@@ -797,7 +828,7 @@ describe('IdentityCacheDynamoDbService', () => {
                     emails: ['first@email.com', 'second@email.com', 'third@email.com', 'fourth@email.com'],
                 },
             };
-            await IdentityCacheDynamoDbService.updateIdentityCache(pixelId, identity);
+            await IdentityCacheDynamoDbDbService.updateIdentityCache(pixelId, identity);
             const writtenItems = mockedDynamoDbClient.safeBatchWrite.mock.calls[0][1];
             expect(writtenItems).toHaveLength(5);
             const emailPks = writtenItems
@@ -815,7 +846,7 @@ describe('IdentityCacheDynamoDbService', () => {
                     emails: ['valid@email.com', null, undefined, '', 'another@email.com'],
                 },
             };
-            await IdentityCacheDynamoDbService.updateIdentityCache(pixelId, identity);
+            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);
@@ -827,7 +858,7 @@ describe('IdentityCacheDynamoDbService', () => {
                 identityId: 'identity456',
                 traits: { emails: [] },
             };
-            await IdentityCacheDynamoDbService.updateIdentityCache(pixelId, identity);
+            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`);
@@ -839,7 +870,7 @@ describe('IdentityCacheDynamoDbService', () => {
                     emails: ['UPPERCASE@EMAIL.COM', 'MixedCase@Email.Com'],
                 },
             };
-            await IdentityCacheDynamoDbService.updateIdentityCache(pixelId, identity);
+            await IdentityCacheDynamoDbDbService.updateIdentityCache(pixelId, identity);
             const writtenItems = mockedDynamoDbClient.safeBatchWrite.mock.calls[0][1];
             const emailPks = writtenItems
                 .filter((item) => item.pk.startsWith('email#'))
@@ -855,7 +886,7 @@ describe('IdentityCacheDynamoDbService', () => {
                 identityId: 'identity456',
                 traits: null,
             };
-            await IdentityCacheDynamoDbService.updateIdentityCache(pixelId, identity);
+            await IdentityCacheDynamoDbDbService.updateIdentityCache(pixelId, identity);
             const writtenItems = mockedDynamoDbClient.safeBatchWrite.mock.calls[0][1];
             expect(writtenItems).toHaveLength(1);
         });
@@ -864,12 +895,12 @@ describe('IdentityCacheDynamoDbService', () => {
                 identityId: 'identity456',
                 traits: undefined,
             };
-            await IdentityCacheDynamoDbService.updateIdentityCache(pixelId, identity);
+            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 IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, {
+            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCache(pixelId, {
                 traits: null,
             });
             expect(result.resolvedIdentity).toBeUndefined();
@@ -877,7 +908,7 @@ describe('IdentityCacheDynamoDbService', () => {
             expect(mockedDynamoDbClient.safeGet).not.toHaveBeenCalled();
         });
         it('should handle identity with undefined emails in traits', async () => {
-            const result = await IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, {
+            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCache(pixelId, {
                 traits: { userIds: ['user123'] },
             });
             expect(result.resolvedIdentity).toBeUndefined();
@@ -899,7 +930,7 @@ describe('IdentityCacheDynamoDbService', () => {
                 updatedAt: new Date().toISOString(),
             };
             mockedDynamoDbClient.safeGet.mockResolvedValueOnce(oldFormatEmailRecord);
-            const result = await IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, {
+            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCache(pixelId, {
                 traits: { emails: ['test@email.com'] },
             });
             expect(result.resolvedIdentity).toBeDefined();
@@ -915,7 +946,7 @@ describe('IdentityCacheDynamoDbService', () => {
                 updatedAt: new Date().toISOString(),
             };
             mockedDynamoDbClient.safeGet.mockResolvedValueOnce(newFormatPointerRecord);
-            const result = await IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, {
+            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCache(pixelId, {
                 traits: { emails: ['test@email.com'] },
             });
             expect(result.resolvedIdentity).toBeDefined();
@@ -941,7 +972,7 @@ describe('IdentityCacheDynamoDbService', () => {
                     },
                 }),
             });
-            const result = await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, { traits: { emails: ['test@email.com'] } }, lambdaArn);
+            const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, { traits: { emails: ['test@email.com'] } }, lambdaArn);
             expect(mockInvokeFunction).toHaveBeenCalledWith(lambdaArn, expect.objectContaining({
                 pixelId,
                 context: {
@@ -950,7 +981,7 @@ describe('IdentityCacheDynamoDbService', () => {
                     }),
                 },
             }));
-            expect(result?.identityId).toBe('discovered-id');
+            expect(result.identity?.identityId).toBe('discovered-id');
         });
     });
     describe('deleteIdentityCache with multiple email pointers', () => {
@@ -968,7 +999,7 @@ describe('IdentityCacheDynamoDbService', () => {
                 identityId: 'identity456',
                 traits: { emails: ['resolved1@email.com', 'resolved2@email.com', 'resolved3@email.com'] },
             };
-            await IdentityCacheDynamoDbService.deleteIdentityCache(pixelId, incomingIdentity, resolvedIdentity);
+            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]];
@@ -985,7 +1016,7 @@ describe('IdentityCacheDynamoDbService', () => {
                 { pk: `identity#${pixelId}#identity456`, pixelId },
             ]);
             mockedDynamoDbClient.batchWrite.mockResolvedValue({ $metadata: {} });
-            await IdentityCacheDynamoDbService.deleteIdentityCache(pixelId, { identityId: 'identity456', traits: { emails: [] } }, { identityId: 'identity456' });
+            await IdentityCacheDynamoDbDbService.deleteIdentityCache(pixelId, { identityId: 'identity456', traits: { emails: [] } }, { identityId: 'identity456' });
             expect(mockedDynamoDbClient.batchWrite).toHaveBeenCalled();
         });
         it('should handle missing traits in delete', async () => {
@@ -993,7 +1024,7 @@ describe('IdentityCacheDynamoDbService', () => {
                 { pk: `identity#${pixelId}#identity456`, pixelId },
             ]);
             mockedDynamoDbClient.batchWrite.mockResolvedValue({ $metadata: {} });
-            await IdentityCacheDynamoDbService.deleteIdentityCache(pixelId, { identityId: 'identity456' }, { identityId: 'identity456' });
+            await IdentityCacheDynamoDbDbService.deleteIdentityCache(pixelId, { identityId: 'identity456' }, { identityId: 'identity456' });
             expect(mockedDynamoDbClient.batchWrite).toHaveBeenCalled();
         });
         it('should not delete items from other pixelIds', async () => {
@@ -1003,7 +1034,7 @@ describe('IdentityCacheDynamoDbService', () => {
                 { pk: `identity#${otherPixelId}#identity456`, pixelId: otherPixelId },
             ]);
             mockedDynamoDbClient.batchWrite.mockResolvedValue({ $metadata: {} });
-            await IdentityCacheDynamoDbService.deleteIdentityCache(pixelId, { identityId: 'identity456' }, { identityId: 'identity456' });
+            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);
@@ -1022,24 +1053,24 @@ describe('IdentityCacheDynamoDbService', () => {
             ];
             mockedDynamoDbClient.safeQueryByGSI.mockResolvedValue(mockResults);
             mockedDynamoDbClient.batchWrite.mockResolvedValue({ $metadata: {} });
-            await IdentityCacheDynamoDbService.deleteIdentityCache(pixelId, { identityId }, { identityId });
+            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 IdentityCacheDynamoDbService.deleteIdentityCache(pixelId, { identityId: 'unknown-id' }, { identityId: 'unknown-id' });
+            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(IdentityCacheDynamoDbService.deleteIdentityCache(pixelId, { identityId: 'identity456' }, { identityId: 'identity456' })).resolves.toBeUndefined();
+            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 IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, {
+            await IdentityCacheDynamoDbDbService.getIdentityFromCache(pixelId, {
                 traits: { emails: ['first@email.com', 'second@email.com', 'third@email.com'] },
             });
             expect(mockedDynamoDbClient.safeGet).toHaveBeenCalledTimes(1);
@@ -1047,7 +1078,7 @@ describe('IdentityCacheDynamoDbService', () => {
         });
         it('should handle whitespace in email during lookup', async () => {
             mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
-            await IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, {
+            await IdentityCacheDynamoDbDbService.getIdentityFromCache(pixelId, {
                 traits: { emails: ['  test@email.com  '] },
             });
             expect(mockedDynamoDbClient.safeGet).toHaveBeenCalled();
@@ -1063,8 +1094,8 @@ describe('IdentityCacheDynamoDbService', () => {
             };
             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);
+            const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, incomingIdentity, lambdaArn);
+            expect(result.identity).toEqual(incomingIdentity);
         });
         it('should continue when cache write fails after Neptune success', async () => {
             mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
@@ -1075,8 +1106,8 @@ describe('IdentityCacheDynamoDbService', () => {
                 }),
             });
             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');
+            const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, { traits: { emails: ['test@email.com'] } }, lambdaArn);
+            expect(result.identity?.identityId).toBe('resolved-id');
         });
         it('should return incoming identity when Neptune returns non-200', async () => {
             const incomingIdentity = {
@@ -1088,8 +1119,8 @@ describe('IdentityCacheDynamoDbService', () => {
                 statusCode: 500,
                 body: 'Internal Server Error',
             });
-            const result = await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
-            expect(result).toEqual(incomingIdentity);
+            const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, incomingIdentity, lambdaArn);
+            expect(result.identity).toEqual(incomingIdentity);
         });
         it('should return incoming identity when Neptune returns malformed JSON (fail-open)', async () => {
             const incomingIdentity = {
@@ -1101,12 +1132,127 @@ describe('IdentityCacheDynamoDbService', () => {
                 statusCode: 200,
                 body: 'not valid json',
             });
-            const result = await IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
-            expect(result).toEqual(incomingIdentity);
+            const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, incomingIdentity, lambdaArn);
+            expect(result.identity).toEqual(incomingIdentity);
         });
-        it('should return undefined only when both inputs are invalid', async () => {
-            const result = await IdentityCacheDynamoDbService.getIdentityWithCaching(null, null, lambdaArn);
-            expect(result).toBeUndefined();
+        it('should return undefined identity only when both inputs are invalid', async () => {
+            const result = await IdentityGatewayService.getIdentityWithCachingV2(null, null, lambdaArn);
+            expect(result.identity).toBeUndefined();
+            expect(result.summary.outcome).toBe(IDENTITY_CACHE_WITH_CACHING_OUTCOME.INVALID_INPUT);
+        });
+    });
+    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', () => {
@@ -1116,18 +1262,18 @@ describe('IdentityCacheDynamoDbService', () => {
                 identityId: 'identity456',
                 traits: { emails: ['test@email.com'] },
             };
-            await IdentityCacheDynamoDbService.updateIdentityCache(pixelId, identity);
+            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');
+            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);
+            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) {