@adtrackify/at-service-common 4.0.5 → 4.0.7

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

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+const at_tracking_event_types_1 = require("@adtrackify/at-tracking-event-types");
 const mockInvokeFunction = jest.fn();
 jest.mock('../../clients/index.js', () => ({
     DynamoDbClient: {
@@ -23,10 +24,13 @@ jest.mock('../../helpers/index.js', () => ({
         error: jest.fn(),
     },
 }));
-const identity_cache_dynamodb_service_js_1 = require("../../services/db/identity-cache-dynamodb-service.js");
+const key_builders_js_1 = require("../../services/db/identity-cache-dynamodb-service/key-builders.js");
+const identity_gateway_service_js_1 = require("../../services/db/identity-cache-dynamodb-service/identity-gateway-service.js");
+const types_js_1 = require("../../services/db/identity-cache-dynamodb-service/types.js");
+const identity_cache_dynamodb_db_service_js_1 = require("../../services/db/identity-cache-dynamodb-service/identity-cache-dynamodb-db-service.js");
 const index_js_1 = require("../../clients/index.js");
 const mockedDynamoDbClient = index_js_1.DynamoDbClient;
-describe('IdentityCacheDynamoDbService', () => {
+describe('IdentityGatewayService', () => {
     beforeEach(() => {
         jest.clearAllMocks();
         mockedDynamoDbClient.safeGet.mockReset();
@@ -37,9 +41,33 @@ describe('IdentityCacheDynamoDbService', () => {
         mockedDynamoDbClient.safeQueryByGSI.mockReset();
         mockedDynamoDbClient.batchWrite.mockReset();
         mockInvokeFunction.mockReset();
-        identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.lambdaInvokeClient = undefined;
+        identity_gateway_service_js_1.IdentityGatewayService.lambdaInvokeClient = undefined;
     });
-    describe('getIdentityWithCaching', () => {
+    describe('identity cache key builders', () => {
+        it('should build primary identity cache keys', () => {
+            expect((0, key_builders_js_1.buildIdentityPk)('pixel123', 'identity456')).toBe('identity#pixel123#identity456');
+        });
+        it('should build lowercase email pointer keys', () => {
+            expect((0, key_builders_js_1.buildEmailPk)('pixel123', 'Test@Email.COM')).toBe('email#pixel123#test@email.com');
+        });
+        it('should build trimmed user id pointer keys', () => {
+            expect((0, key_builders_js_1.buildUserIdPk)('pixel123', ' user-1 ')).toBe('user_id#pixel123#user-1');
+        });
+        it('should build identity map keys', () => {
+            expect((0, key_builders_js_1.buildIdentityMapPk)('pixel123', 'identity456')).toBe('identity_map#pixel123#identity456');
+        });
+        it('should build force purge keys', () => {
+            expect((0, key_builders_js_1.buildForcePurgePk)('pixel123', 'identity456')).toBe('force_purge#pixel123#identity456');
+        });
+        it('should match the installed tracking-event-types key builder behavior during migration', () => {
+            expect((0, key_builders_js_1.buildIdentityPk)('pixel123', 'identity456')).toBe((0, at_tracking_event_types_1.buildIdentityPk)('pixel123', 'identity456'));
+            expect((0, key_builders_js_1.buildEmailPk)('pixel123', 'Test@Email.COM')).toBe((0, at_tracking_event_types_1.buildEmailPk)('pixel123', 'Test@Email.COM'));
+            expect((0, key_builders_js_1.buildUserIdPk)('pixel123', ' user-1 ')).toBe((0, at_tracking_event_types_1.buildUserIdPk)('pixel123', ' user-1 '));
+            expect((0, key_builders_js_1.buildIdentityMapPk)('pixel123', 'identity456')).toBe((0, at_tracking_event_types_1.buildIdentityMapPk)('pixel123', 'identity456'));
+            expect((0, key_builders_js_1.buildForcePurgePk)('pixel123', 'identity456')).toBe((0, at_tracking_event_types_1.buildForcePurgePk)('pixel123', 'identity456'));
+        });
+    });
+    describe('getIdentityWithCachingV2', () => {
         const pixelId = 'pixel123';
         const lambdaArn = 'arn:aws:lambda:us-east-1:123456789:function:identity-private';
         describe('cache hit (fresh cache)', () => {
@@ -59,9 +87,9 @@ describe('IdentityCacheDynamoDbService', () => {
                     updatedAt: new Date().toISOString(),
                 };
                 mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
-                const result = await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
-                expect(result).toBeDefined();
-                expect(result?.identityId).toBe('identity456');
+                const result = await identity_gateway_service_js_1.IdentityGatewayService.getIdentityWithCachingV2(pixelId, incomingIdentity, lambdaArn);
+                expect(result.identity).toBeDefined();
+                expect(result.identity?.identityId).toBe('identity456');
                 expect(mockInvokeFunction).not.toHaveBeenCalled();
             });
         });
@@ -81,12 +109,12 @@ describe('IdentityCacheDynamoDbService', () => {
                         },
                     }),
                 });
-                const result = await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
+                const result = await identity_gateway_service_js_1.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 () => {
@@ -99,8 +127,8 @@ describe('IdentityCacheDynamoDbService', () => {
                     statusCode: 200,
                     body: JSON.stringify({ identity: undefined }),
                 });
-                const result = await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
-                expect(result).toEqual(incomingIdentity);
+                const result = await identity_gateway_service_js_1.IdentityGatewayService.getIdentityWithCachingV2(pixelId, incomingIdentity, lambdaArn);
+                expect(result.identity).toEqual(incomingIdentity);
             });
         });
         describe('cache stale', () => {
@@ -129,10 +157,10 @@ describe('IdentityCacheDynamoDbService', () => {
                         },
                     }),
                 });
-                const result = await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
+                const result = await identity_gateway_service_js_1.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 = {
@@ -154,9 +182,9 @@ describe('IdentityCacheDynamoDbService', () => {
                     statusCode: 500,
                     body: 'Internal Server Error',
                 });
-                const result = await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
-                expect(result).toBeDefined();
-                expect(result?.identityId).toBe('identity456');
+                const result = await identity_gateway_service_js_1.IdentityGatewayService.getIdentityWithCachingV2(pixelId, incomingIdentity, lambdaArn);
+                expect(result.identity).toBeDefined();
+                expect(result.identity?.identityId).toBe('identity456');
             });
         });
         describe('Neptune Lambda invocation', () => {
@@ -174,7 +202,7 @@ describe('IdentityCacheDynamoDbService', () => {
                         },
                     }),
                 });
-                await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
+                await identity_gateway_service_js_1.IdentityGatewayService.getIdentityWithCachingV2(pixelId, incomingIdentity, lambdaArn);
                 expect(mockedDynamoDbClient.safeBatchWrite).toHaveBeenCalled();
                 const writtenItems = mockedDynamoDbClient.safeBatchWrite.mock.calls[0][1];
                 const identityPks = writtenItems.map((item) => item.pk);
@@ -189,30 +217,33 @@ describe('IdentityCacheDynamoDbService', () => {
                     statusCode: 200,
                     body: JSON.stringify({ identity: undefined }),
                 });
-                await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
+                await identity_gateway_service_js_1.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 identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.getIdentityWithCaching(null, { identityId: 'test-id' }, lambdaArn);
-                expect(result).toBeUndefined();
+            it('should return undefined identity when pixelId is missing', async () => {
+                const result = await identity_gateway_service_js_1.IdentityGatewayService.getIdentityWithCachingV2(null, { identityId: 'test-id' }, lambdaArn);
+                expect(result.identity).toBeUndefined();
+                expect(result.summary.outcome).toBe(types_js_1.IDENTITY_CACHE_WITH_CACHING_OUTCOME.INVALID_INPUT);
                 expect(mockInvokeFunction).not.toHaveBeenCalled();
             });
-            it('should return undefined when incomingIdentity is missing', async () => {
-                const result = await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, null, lambdaArn);
-                expect(result).toBeUndefined();
+            it('should return undefined identity when incomingIdentity is missing', async () => {
+                const result = await identity_gateway_service_js_1.IdentityGatewayService.getIdentityWithCachingV2(pixelId, null, lambdaArn);
+                expect(result.identity).toBeUndefined();
+                expect(result.summary.outcome).toBe(types_js_1.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 identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
-                expect(result).toEqual(incomingIdentity);
+                const result = await identity_gateway_service_js_1.IdentityGatewayService.getIdentityWithCachingV2(pixelId, incomingIdentity, lambdaArn);
+                expect(result.identity).toEqual(incomingIdentity);
+                expect(result.summary.outcome).toBe(types_js_1.IDENTITY_CACHE_WITH_CACHING_OUTCOME.FALLBACK_INCOMING);
             });
             it('should not throw when cache write fails after Neptune success', async () => {
                 const incomingIdentity = {
@@ -229,8 +260,8 @@ describe('IdentityCacheDynamoDbService', () => {
                     }),
                 });
                 mockedDynamoDbClient.safeBatchWrite.mockRejectedValueOnce(new Error('DynamoDB write failed'));
-                const result = await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
-                expect(result?.identityId).toBe('neptune-resolved-id');
+                const result = await identity_gateway_service_js_1.IdentityGatewayService.getIdentityWithCachingV2(pixelId, incomingIdentity, lambdaArn);
+                expect(result.identity?.identityId).toBe('neptune-resolved-id');
             });
         });
     });
@@ -240,7 +271,7 @@ describe('IdentityCacheDynamoDbService', () => {
                 const pixelId = 'pixel123';
                 const identityId = 'identity456';
                 mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
-                await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, { identityId });
+                await identity_cache_dynamodb_db_service_js_1.IdentityCacheDynamoDbDbService.getIdentityFromCache(pixelId, { identityId });
                 expect(mockedDynamoDbClient.safeGet).toHaveBeenCalledWith(expect.any(String), 'pk', `identity#${pixelId}#${identityId}`);
             });
         });
@@ -249,7 +280,7 @@ describe('IdentityCacheDynamoDbService', () => {
                 const pixelId = 'pixel123';
                 const email = 'Test@Email.COM';
                 mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
-                await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, {
+                await identity_cache_dynamodb_db_service_js_1.IdentityCacheDynamoDbDbService.getIdentityFromCache(pixelId, {
                     traits: { emails: [email] },
                 });
                 expect(mockedDynamoDbClient.safeGet).toHaveBeenCalledWith(expect.any(String), 'pk', `email#${pixelId}#test@email.com`);
@@ -260,7 +291,7 @@ describe('IdentityCacheDynamoDbService', () => {
                 const pixelId = 'pixel123';
                 const userId = '  user789  ';
                 mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
-                await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, {
+                await identity_cache_dynamodb_db_service_js_1.IdentityCacheDynamoDbDbService.getIdentityFromCache(pixelId, {
                     traits: { userIds: [userId] },
                 });
                 expect(mockedDynamoDbClient.safeBatchGet).not.toHaveBeenCalled();
@@ -283,7 +314,7 @@ describe('IdentityCacheDynamoDbService', () => {
                     updatedAt: new Date().toISOString(),
                 };
                 mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
-                const result = await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, {
+                const result = await identity_cache_dynamodb_db_service_js_1.IdentityCacheDynamoDbDbService.getIdentityFromCache(pixelId, {
                     identityId,
                     traits: { emails: ['test@email.com'] },
                 });
@@ -293,7 +324,7 @@ describe('IdentityCacheDynamoDbService', () => {
             });
             it('should return cache miss when identity not found', async () => {
                 mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
-                const result = await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, {
+                const result = await identity_cache_dynamodb_db_service_js_1.IdentityCacheDynamoDbDbService.getIdentityFromCache(pixelId, {
                     identityId: 'unknown-id',
                 });
                 expect(result.resolvedIdentity).toBeUndefined();
@@ -301,7 +332,7 @@ describe('IdentityCacheDynamoDbService', () => {
             });
             it('should NOT fallback to secondary keys when identityId lookup misses', async () => {
                 mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
-                await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, {
+                await identity_cache_dynamodb_db_service_js_1.IdentityCacheDynamoDbDbService.getIdentityFromCache(pixelId, {
                     identityId: 'unknown-id',
                     traits: { emails: ['test@email.com'] },
                 });
@@ -320,7 +351,7 @@ describe('IdentityCacheDynamoDbService', () => {
                     updatedAt: new Date().toISOString(),
                 };
                 mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
-                const result = await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, {
+                const result = await identity_cache_dynamodb_db_service_js_1.IdentityCacheDynamoDbDbService.getIdentityFromCache(pixelId, {
                     identityId,
                     traits: { emails: ['old@email.com', 'new@email.com'] },
                 });
@@ -338,7 +369,7 @@ describe('IdentityCacheDynamoDbService', () => {
                     updatedAt: new Date().toISOString(),
                 };
                 mockedDynamoDbClient.safeGet.mockResolvedValueOnce(pointerRecord);
-                const result = await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, {
+                const result = await identity_cache_dynamodb_db_service_js_1.IdentityCacheDynamoDbDbService.getIdentityFromCache(pixelId, {
                     traits: { emails: ['test@email.com'], userIds: ['user123'] },
                 });
                 expect(mockedDynamoDbClient.safeGet).toHaveBeenCalledWith(expect.any(String), 'pk', `email#${pixelId}#test@email.com`);
@@ -356,7 +387,7 @@ describe('IdentityCacheDynamoDbService', () => {
                     updatedAt: new Date().toISOString(),
                 };
                 mockedDynamoDbClient.safeGet.mockResolvedValueOnce(pointerRecord);
-                const result = await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, {
+                const result = await identity_cache_dynamodb_db_service_js_1.IdentityCacheDynamoDbDbService.getIdentityFromCache(pixelId, {
                     traits: { emails: ['test@email.com'], userIds: ['user123'] },
                 });
                 expect(result.resolvedIdentity).toBeDefined();
@@ -365,14 +396,14 @@ describe('IdentityCacheDynamoDbService', () => {
             });
             it('should return cache miss when no secondary keys match', async () => {
                 mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
-                const result = await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, {
+                const result = await identity_cache_dynamodb_db_service_js_1.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 identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, {
+                const result = await identity_cache_dynamodb_db_service_js_1.IdentityCacheDynamoDbDbService.getIdentityFromCache(pixelId, {
                     traits: { userIds: ['user123'] },
                 });
                 expect(result.resolvedIdentity).toBeUndefined();
@@ -380,7 +411,7 @@ describe('IdentityCacheDynamoDbService', () => {
                 expect(mockedDynamoDbClient.safeGet).not.toHaveBeenCalled();
             });
             it('should return cache miss when empty traits', async () => {
-                const result = await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, {
+                const result = await identity_cache_dynamodb_db_service_js_1.IdentityCacheDynamoDbDbService.getIdentityFromCache(pixelId, {
                     traits: {},
                 });
                 expect(result.resolvedIdentity).toBeUndefined();
@@ -390,7 +421,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 identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, {
+                const result = await identity_cache_dynamodb_db_service_js_1.IdentityCacheDynamoDbDbService.getIdentityFromCache(pixelId, {
                     identityId: 'test-id',
                 });
                 expect(result.resolvedIdentity).toBeUndefined();
@@ -398,21 +429,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 identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, {
+                const result = await identity_cache_dynamodb_db_service_js_1.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 identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.getIdentityFromCache(null, {
+                const result = await identity_cache_dynamodb_db_service_js_1.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 identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, null);
+                const result = await identity_cache_dynamodb_db_service_js_1.IdentityCacheDynamoDbDbService.getIdentityFromCache(pixelId, null);
                 expect(result.resolvedIdentity).toBeUndefined();
                 expect(result.isCacheStale).toBe(true);
             });
@@ -428,7 +459,7 @@ describe('IdentityCacheDynamoDbService', () => {
                     userIds: ['user1', 'user2'],
                 },
             };
-            await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.updateIdentityCache(pixelId, identity);
+            await identity_cache_dynamodb_db_service_js_1.IdentityCacheDynamoDbDbService.updateIdentityCache(pixelId, identity);
             expect(mockedDynamoDbClient.safeBatchWrite).toHaveBeenCalledTimes(1);
             const writtenItems = mockedDynamoDbClient.safeBatchWrite.mock.calls[0][1];
             expect(writtenItems).toHaveLength(3);
@@ -440,12 +471,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'));
@@ -453,14 +484,14 @@ describe('IdentityCacheDynamoDbService', () => {
                 identityId: 'identity456',
                 traits: { emails: ['test@email.com'] },
             };
-            await expect(identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.updateIdentityCache(pixelId, identity)).resolves.toBeUndefined();
+            await expect(identity_cache_dynamodb_db_service_js_1.IdentityCacheDynamoDbDbService.updateIdentityCache(pixelId, identity)).resolves.toBeUndefined();
         });
         it('should return early for missing identityId', async () => {
-            await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.updateIdentityCache(pixelId, {});
+            await identity_cache_dynamodb_db_service_js_1.IdentityCacheDynamoDbDbService.updateIdentityCache(pixelId, {});
             expect(mockedDynamoDbClient.safeBatchWrite).not.toHaveBeenCalled();
         });
         it('should return early for missing pixelId', async () => {
-            await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.updateIdentityCache(null, {
+            await identity_cache_dynamodb_db_service_js_1.IdentityCacheDynamoDbDbService.updateIdentityCache(null, {
                 identityId: 'test-id',
             });
             expect(mockedDynamoDbClient.safeBatchWrite).not.toHaveBeenCalled();
@@ -469,7 +500,7 @@ describe('IdentityCacheDynamoDbService', () => {
             const identity = {
                 identityId: 'identity456',
             };
-            await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.updateIdentityCache(pixelId, identity);
+            await identity_cache_dynamodb_db_service_js_1.IdentityCacheDynamoDbDbService.updateIdentityCache(pixelId, identity);
             const writtenItems = mockedDynamoDbClient.safeBatchWrite.mock.calls[0][1];
             expect(writtenItems).toHaveLength(1);
         });
@@ -478,7 +509,7 @@ describe('IdentityCacheDynamoDbService', () => {
                 identityId: 'identity456',
                 traits: { emails: ['test@email.com'] },
             };
-            await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.updateIdentityCache(pixelId, identity);
+            await identity_cache_dynamodb_db_service_js_1.IdentityCacheDynamoDbDbService.updateIdentityCache(pixelId, identity);
             const writtenItems = mockedDynamoDbClient.safeBatchWrite.mock.calls[0][1];
             for (const item of writtenItems) {
                 expect(item.gsi1pk).toBe('identity456');
@@ -495,33 +526,33 @@ describe('IdentityCacheDynamoDbService', () => {
                 updatedAt: new Date().toISOString(),
             };
             mockedDynamoDbClient.safeGet.mockResolvedValueOnce(mockMap);
-            const result = await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.getIdentityMap('pixel123', 'identity456');
+            const result = await identity_cache_dynamodb_db_service_js_1.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 identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.getIdentityMap('pixel123', 'identity456');
+            const result = await identity_cache_dynamodb_db_service_js_1.IdentityCacheDynamoDbDbService.getIdentityMap('pixel123', 'identity456');
             expect(result).toBeUndefined();
         });
         it('should return undefined for missing params (fail-open)', async () => {
-            const result = await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.getIdentityMap('', '');
+            const result = await identity_cache_dynamodb_db_service_js_1.IdentityCacheDynamoDbDbService.getIdentityMap('', '');
             expect(result).toBeUndefined();
             expect(mockedDynamoDbClient.safeGet).not.toHaveBeenCalled();
         });
         it('should return undefined when only pixelId is missing', async () => {
-            const result = await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.getIdentityMap('', 'identity456');
+            const result = await identity_cache_dynamodb_db_service_js_1.IdentityCacheDynamoDbDbService.getIdentityMap('', 'identity456');
             expect(result).toBeUndefined();
             expect(mockedDynamoDbClient.safeGet).not.toHaveBeenCalled();
         });
         it('should return undefined when only identityId is missing', async () => {
-            const result = await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.getIdentityMap('pixel123', '');
+            const result = await identity_cache_dynamodb_db_service_js_1.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 identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.getIdentityMap('pixel123', 'identity456');
+            const result = await identity_cache_dynamodb_db_service_js_1.IdentityCacheDynamoDbDbService.getIdentityMap('pixel123', 'identity456');
             expect(result).toBeUndefined();
         });
     });
@@ -530,28 +561,28 @@ describe('IdentityCacheDynamoDbService', () => {
             mockedDynamoDbClient.safeGet.mockResolvedValueOnce({
                 pk: 'force_purge#pixel123#identity456',
             });
-            const result = await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.getForcePurgeFlag('pixel123', 'identity456');
+            const result = await identity_cache_dynamodb_db_service_js_1.IdentityCacheDynamoDbDbService.getForcePurgeFlag('pixel123', 'identity456');
             expect(result).toBe(true);
         });
         it('should return false when flag not found', async () => {
             mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
-            const result = await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.getForcePurgeFlag('pixel123', 'identity456');
+            const result = await identity_cache_dynamodb_db_service_js_1.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 identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.getForcePurgeFlag('pixel123', 'identity456');
+            const result = await identity_cache_dynamodb_db_service_js_1.IdentityCacheDynamoDbDbService.getForcePurgeFlag('pixel123', 'identity456');
             expect(result).toBe(false);
         });
         it('should return false for missing params', async () => {
-            const result = await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.getForcePurgeFlag('', '');
+            const result = await identity_cache_dynamodb_db_service_js_1.IdentityCacheDynamoDbDbService.getForcePurgeFlag('', '');
             expect(result).toBe(false);
             expect(mockedDynamoDbClient.safeGet).not.toHaveBeenCalled();
         });
     });
     describe('setForcePurgeFlag', () => {
         it('should set flag with TTL', async () => {
-            await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.setForcePurgeFlag('pixel123', 'identity456');
+            await identity_cache_dynamodb_db_service_js_1.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');
@@ -560,13 +591,13 @@ describe('IdentityCacheDynamoDbService', () => {
             expect(putItem.ttl).toBeGreaterThan(0);
         });
         it('should accept custom TTL', async () => {
-            await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.setForcePurgeFlag('pixel123', 'identity456', 3600);
+            await identity_cache_dynamodb_db_service_js_1.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 identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.setForcePurgeFlag('pixel123', 'identity456');
+            await identity_cache_dynamodb_db_service_js_1.IdentityCacheDynamoDbDbService.setForcePurgeFlag('pixel123', 'identity456');
             const after = new Date().toISOString();
             const putItem = mockedDynamoDbClient.safePut.mock.calls[0][1];
             expect(putItem.createdAt).toBeDefined();
@@ -574,41 +605,41 @@ describe('IdentityCacheDynamoDbService', () => {
             expect(putItem.createdAt <= after).toBe(true);
         });
         it('should return early when pixelId is missing', async () => {
-            await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.setForcePurgeFlag('', 'identity456');
+            await identity_cache_dynamodb_db_service_js_1.IdentityCacheDynamoDbDbService.setForcePurgeFlag('', 'identity456');
             expect(mockedDynamoDbClient.safePut).not.toHaveBeenCalled();
         });
         it('should return early when identityId is missing', async () => {
-            await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.setForcePurgeFlag('pixel123', '');
+            await identity_cache_dynamodb_db_service_js_1.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(identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.setForcePurgeFlag('pixel123', 'identity456')).resolves.toBeUndefined();
+            await expect(identity_cache_dynamodb_db_service_js_1.IdentityCacheDynamoDbDbService.setForcePurgeFlag('pixel123', 'identity456')).resolves.toBeUndefined();
         });
     });
     describe('putIdentityMap', () => {
         it('should write identity map', async () => {
-            await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.putIdentityMap('pixel123', 'identity456', ['linked1', 'linked2']);
+            await identity_cache_dynamodb_db_service_js_1.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 identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.putIdentityMap('', '', []);
+            await identity_cache_dynamodb_db_service_js_1.IdentityCacheDynamoDbDbService.putIdentityMap('', '', []);
             expect(mockedDynamoDbClient.safePut).not.toHaveBeenCalled();
         });
         it('should return early when only pixelId is missing', async () => {
-            await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.putIdentityMap('', 'identity456', ['linked1']);
+            await identity_cache_dynamodb_db_service_js_1.IdentityCacheDynamoDbDbService.putIdentityMap('', 'identity456', ['linked1']);
             expect(mockedDynamoDbClient.safePut).not.toHaveBeenCalled();
         });
         it('should return early when only identityId is missing', async () => {
-            await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.putIdentityMap('pixel123', '', ['linked1']);
+            await identity_cache_dynamodb_db_service_js_1.IdentityCacheDynamoDbDbService.putIdentityMap('pixel123', '', ['linked1']);
             expect(mockedDynamoDbClient.safePut).not.toHaveBeenCalled();
         });
         it('should include updatedAt timestamp', async () => {
             const before = new Date().toISOString();
-            await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.putIdentityMap('pixel123', 'identity456', ['linked1']);
+            await identity_cache_dynamodb_db_service_js_1.IdentityCacheDynamoDbDbService.putIdentityMap('pixel123', 'identity456', ['linked1']);
             const after = new Date().toISOString();
             const putItem = mockedDynamoDbClient.safePut.mock.calls[0][1];
             expect(putItem.updatedAt).toBeDefined();
@@ -617,51 +648,51 @@ describe('IdentityCacheDynamoDbService', () => {
         });
         it('should not throw on safePut error (fail-open)', async () => {
             mockedDynamoDbClient.safePut.mockRejectedValueOnce(new Error('DynamoDB error'));
-            await expect(identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.putIdentityMap('pixel123', 'identity456', ['linked1'])).resolves.toBeUndefined();
+            await expect(identity_cache_dynamodb_db_service_js_1.IdentityCacheDynamoDbDbService.putIdentityMap('pixel123', 'identity456', ['linked1'])).resolves.toBeUndefined();
         });
     });
     describe('deleteIdentityMap', () => {
         it('should delete identity map', async () => {
-            await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.deleteIdentityMap('pixel123', 'identity456');
+            await identity_cache_dynamodb_db_service_js_1.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 identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.deleteIdentityMap('', '');
+            await identity_cache_dynamodb_db_service_js_1.IdentityCacheDynamoDbDbService.deleteIdentityMap('', '');
             expect(mockedDynamoDbClient.safeDelete).not.toHaveBeenCalled();
         });
         it('should return early when only pixelId is missing', async () => {
-            await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.deleteIdentityMap('', 'identity456');
+            await identity_cache_dynamodb_db_service_js_1.IdentityCacheDynamoDbDbService.deleteIdentityMap('', 'identity456');
             expect(mockedDynamoDbClient.safeDelete).not.toHaveBeenCalled();
         });
         it('should return early when only identityId is missing', async () => {
-            await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.deleteIdentityMap('pixel123', '');
+            await identity_cache_dynamodb_db_service_js_1.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(identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.deleteIdentityMap('pixel123', 'identity456')).resolves.toBeUndefined();
+            await expect(identity_cache_dynamodb_db_service_js_1.IdentityCacheDynamoDbDbService.deleteIdentityMap('pixel123', 'identity456')).resolves.toBeUndefined();
         });
     });
     describe('deleteForcePurgeFlag', () => {
         it('should delete force purge flag', async () => {
-            await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.deleteForcePurgeFlag('pixel123', 'identity456');
+            await identity_cache_dynamodb_db_service_js_1.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 identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.deleteForcePurgeFlag('', '');
+            await identity_cache_dynamodb_db_service_js_1.IdentityCacheDynamoDbDbService.deleteForcePurgeFlag('', '');
             expect(mockedDynamoDbClient.safeDelete).not.toHaveBeenCalled();
         });
         it('should return early when only pixelId is missing', async () => {
-            await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.deleteForcePurgeFlag('', 'identity456');
+            await identity_cache_dynamodb_db_service_js_1.IdentityCacheDynamoDbDbService.deleteForcePurgeFlag('', 'identity456');
             expect(mockedDynamoDbClient.safeDelete).not.toHaveBeenCalled();
         });
         it('should return early when only identityId is missing', async () => {
-            await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.deleteForcePurgeFlag('pixel123', '');
+            await identity_cache_dynamodb_db_service_js_1.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(identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.deleteForcePurgeFlag('pixel123', 'identity456')).resolves.toBeUndefined();
+            await expect(identity_cache_dynamodb_db_service_js_1.IdentityCacheDynamoDbDbService.deleteForcePurgeFlag('pixel123', 'identity456')).resolves.toBeUndefined();
         });
     });
     describe('deleteIdentityCache', () => {
@@ -680,12 +711,12 @@ describe('IdentityCacheDynamoDbService', () => {
                 identityId: 'identity456',
                 traits: { emails: ['test@email.com', 'other@email.com'] },
             };
-            await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.deleteIdentityCache(pixelId, incomingIdentity, resolvedIdentity);
+            await identity_cache_dynamodb_db_service_js_1.IdentityCacheDynamoDbDbService.deleteIdentityCache(pixelId, incomingIdentity, resolvedIdentity);
             expect(mockedDynamoDbClient.safeQueryByGSI).toHaveBeenCalled();
             expect(mockedDynamoDbClient.batchWrite).toHaveBeenCalled();
         });
         it('should return early for missing pixelId', async () => {
-            await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.deleteIdentityCache(null, {}, {});
+            await identity_cache_dynamodb_db_service_js_1.IdentityCacheDynamoDbDbService.deleteIdentityCache(null, {}, {});
             expect(mockedDynamoDbClient.safeQueryByGSI).not.toHaveBeenCalled();
         });
         it('should handle different identityIds in incoming vs resolved', async () => {
@@ -699,19 +730,19 @@ describe('IdentityCacheDynamoDbService', () => {
                 identityId: 'resolved-id',
                 traits: { emails: ['test@email.com'] },
             };
-            await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.deleteIdentityCache(pixelId, incomingIdentity, resolvedIdentity);
+            await identity_cache_dynamodb_db_service_js_1.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(identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.deleteIdentityCache(pixelId, { identityId: 'identity456' }, { identityId: 'identity456' })).resolves.toBeUndefined();
+            await expect(identity_cache_dynamodb_db_service_js_1.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 identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.deleteIdentityCache(pixelId, { identityId: 'identity456' }, { identityId: 'identity456' });
+            await identity_cache_dynamodb_db_service_js_1.IdentityCacheDynamoDbDbService.deleteIdentityCache(pixelId, { identityId: 'identity456' }, { identityId: 'identity456' });
             expect(mockedDynamoDbClient.batchWrite).toHaveBeenCalled();
             const batchWriteCall = mockedDynamoDbClient.batchWrite.mock.calls[0];
             expect(batchWriteCall).toBeDefined();
@@ -734,7 +765,7 @@ describe('IdentityCacheDynamoDbService', () => {
                 updatedAt: new Date().toISOString(),
             };
             mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
-            const result = await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, {
+            const result = await identity_cache_dynamodb_db_service_js_1.IdentityCacheDynamoDbDbService.getIdentityFromCache(pixelId, {
                 identityId: 'identity456',
                 traits: {
                     emails: ['incoming@email.com'],
@@ -758,7 +789,7 @@ describe('IdentityCacheDynamoDbService', () => {
                 updatedAt: new Date().toISOString(),
             };
             mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
-            const result = await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, {
+            const result = await identity_cache_dynamodb_db_service_js_1.IdentityCacheDynamoDbDbService.getIdentityFromCache(pixelId, {
                 identityId: 'identity456',
                 traits: {
                     emails: ['cached@email.com', 'new@email.com'],
@@ -781,7 +812,7 @@ describe('IdentityCacheDynamoDbService', () => {
                 updatedAt: new Date().toISOString(),
             };
             mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
-            const result = await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, {
+            const result = await identity_cache_dynamodb_db_service_js_1.IdentityCacheDynamoDbDbService.getIdentityFromCache(pixelId, {
                 identityId: 'identity456',
                 traits: {
                     emails: ['a@email.com'],
@@ -799,7 +830,7 @@ describe('IdentityCacheDynamoDbService', () => {
                     emails: ['first@email.com', 'second@email.com', 'third@email.com', 'fourth@email.com'],
                 },
             };
-            await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.updateIdentityCache(pixelId, identity);
+            await identity_cache_dynamodb_db_service_js_1.IdentityCacheDynamoDbDbService.updateIdentityCache(pixelId, identity);
             const writtenItems = mockedDynamoDbClient.safeBatchWrite.mock.calls[0][1];
             expect(writtenItems).toHaveLength(5);
             const emailPks = writtenItems
@@ -817,7 +848,7 @@ describe('IdentityCacheDynamoDbService', () => {
                     emails: ['valid@email.com', null, undefined, '', 'another@email.com'],
                 },
             };
-            await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.updateIdentityCache(pixelId, identity);
+            await identity_cache_dynamodb_db_service_js_1.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);
@@ -829,7 +860,7 @@ describe('IdentityCacheDynamoDbService', () => {
                 identityId: 'identity456',
                 traits: { emails: [] },
             };
-            await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.updateIdentityCache(pixelId, identity);
+            await identity_cache_dynamodb_db_service_js_1.IdentityCacheDynamoDbDbService.updateIdentityCache(pixelId, identity);
             const writtenItems = mockedDynamoDbClient.safeBatchWrite.mock.calls[0][1];
             expect(writtenItems).toHaveLength(1);
             expect(writtenItems[0].pk).toBe(`identity#${pixelId}#identity456`);
@@ -841,7 +872,7 @@ describe('IdentityCacheDynamoDbService', () => {
                     emails: ['UPPERCASE@EMAIL.COM', 'MixedCase@Email.Com'],
                 },
             };
-            await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.updateIdentityCache(pixelId, identity);
+            await identity_cache_dynamodb_db_service_js_1.IdentityCacheDynamoDbDbService.updateIdentityCache(pixelId, identity);
             const writtenItems = mockedDynamoDbClient.safeBatchWrite.mock.calls[0][1];
             const emailPks = writtenItems
                 .filter((item) => item.pk.startsWith('email#'))
@@ -857,7 +888,7 @@ describe('IdentityCacheDynamoDbService', () => {
                 identityId: 'identity456',
                 traits: null,
             };
-            await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.updateIdentityCache(pixelId, identity);
+            await identity_cache_dynamodb_db_service_js_1.IdentityCacheDynamoDbDbService.updateIdentityCache(pixelId, identity);
             const writtenItems = mockedDynamoDbClient.safeBatchWrite.mock.calls[0][1];
             expect(writtenItems).toHaveLength(1);
         });
@@ -866,12 +897,12 @@ describe('IdentityCacheDynamoDbService', () => {
                 identityId: 'identity456',
                 traits: undefined,
             };
-            await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.updateIdentityCache(pixelId, identity);
+            await identity_cache_dynamodb_db_service_js_1.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 identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, {
+            const result = await identity_cache_dynamodb_db_service_js_1.IdentityCacheDynamoDbDbService.getIdentityFromCache(pixelId, {
                 traits: null,
             });
             expect(result.resolvedIdentity).toBeUndefined();
@@ -879,7 +910,7 @@ describe('IdentityCacheDynamoDbService', () => {
             expect(mockedDynamoDbClient.safeGet).not.toHaveBeenCalled();
         });
         it('should handle identity with undefined emails in traits', async () => {
-            const result = await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, {
+            const result = await identity_cache_dynamodb_db_service_js_1.IdentityCacheDynamoDbDbService.getIdentityFromCache(pixelId, {
                 traits: { userIds: ['user123'] },
             });
             expect(result.resolvedIdentity).toBeUndefined();
@@ -901,7 +932,7 @@ describe('IdentityCacheDynamoDbService', () => {
                 updatedAt: new Date().toISOString(),
             };
             mockedDynamoDbClient.safeGet.mockResolvedValueOnce(oldFormatEmailRecord);
-            const result = await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, {
+            const result = await identity_cache_dynamodb_db_service_js_1.IdentityCacheDynamoDbDbService.getIdentityFromCache(pixelId, {
                 traits: { emails: ['test@email.com'] },
             });
             expect(result.resolvedIdentity).toBeDefined();
@@ -917,7 +948,7 @@ describe('IdentityCacheDynamoDbService', () => {
                 updatedAt: new Date().toISOString(),
             };
             mockedDynamoDbClient.safeGet.mockResolvedValueOnce(newFormatPointerRecord);
-            const result = await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, {
+            const result = await identity_cache_dynamodb_db_service_js_1.IdentityCacheDynamoDbDbService.getIdentityFromCache(pixelId, {
                 traits: { emails: ['test@email.com'] },
             });
             expect(result.resolvedIdentity).toBeDefined();
@@ -943,7 +974,7 @@ describe('IdentityCacheDynamoDbService', () => {
                     },
                 }),
             });
-            const result = await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, { traits: { emails: ['test@email.com'] } }, lambdaArn);
+            const result = await identity_gateway_service_js_1.IdentityGatewayService.getIdentityWithCachingV2(pixelId, { traits: { emails: ['test@email.com'] } }, lambdaArn);
             expect(mockInvokeFunction).toHaveBeenCalledWith(lambdaArn, expect.objectContaining({
                 pixelId,
                 context: {
@@ -952,7 +983,7 @@ describe('IdentityCacheDynamoDbService', () => {
                     }),
                 },
             }));
-            expect(result?.identityId).toBe('discovered-id');
+            expect(result.identity?.identityId).toBe('discovered-id');
         });
     });
     describe('deleteIdentityCache with multiple email pointers', () => {
@@ -970,7 +1001,7 @@ describe('IdentityCacheDynamoDbService', () => {
                 identityId: 'identity456',
                 traits: { emails: ['resolved1@email.com', 'resolved2@email.com', 'resolved3@email.com'] },
             };
-            await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.deleteIdentityCache(pixelId, incomingIdentity, resolvedIdentity);
+            await identity_cache_dynamodb_db_service_js_1.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]];
@@ -987,7 +1018,7 @@ describe('IdentityCacheDynamoDbService', () => {
                 { pk: `identity#${pixelId}#identity456`, pixelId },
             ]);
             mockedDynamoDbClient.batchWrite.mockResolvedValue({ $metadata: {} });
-            await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.deleteIdentityCache(pixelId, { identityId: 'identity456', traits: { emails: [] } }, { identityId: 'identity456' });
+            await identity_cache_dynamodb_db_service_js_1.IdentityCacheDynamoDbDbService.deleteIdentityCache(pixelId, { identityId: 'identity456', traits: { emails: [] } }, { identityId: 'identity456' });
             expect(mockedDynamoDbClient.batchWrite).toHaveBeenCalled();
         });
         it('should handle missing traits in delete', async () => {
@@ -995,7 +1026,7 @@ describe('IdentityCacheDynamoDbService', () => {
                 { pk: `identity#${pixelId}#identity456`, pixelId },
             ]);
             mockedDynamoDbClient.batchWrite.mockResolvedValue({ $metadata: {} });
-            await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.deleteIdentityCache(pixelId, { identityId: 'identity456' }, { identityId: 'identity456' });
+            await identity_cache_dynamodb_db_service_js_1.IdentityCacheDynamoDbDbService.deleteIdentityCache(pixelId, { identityId: 'identity456' }, { identityId: 'identity456' });
             expect(mockedDynamoDbClient.batchWrite).toHaveBeenCalled();
         });
         it('should not delete items from other pixelIds', async () => {
@@ -1005,7 +1036,7 @@ describe('IdentityCacheDynamoDbService', () => {
                 { pk: `identity#${otherPixelId}#identity456`, pixelId: otherPixelId },
             ]);
             mockedDynamoDbClient.batchWrite.mockResolvedValue({ $metadata: {} });
-            await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.deleteIdentityCache(pixelId, { identityId: 'identity456' }, { identityId: 'identity456' });
+            await identity_cache_dynamodb_db_service_js_1.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);
@@ -1024,24 +1055,24 @@ describe('IdentityCacheDynamoDbService', () => {
             ];
             mockedDynamoDbClient.safeQueryByGSI.mockResolvedValue(mockResults);
             mockedDynamoDbClient.batchWrite.mockResolvedValue({ $metadata: {} });
-            await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.deleteIdentityCache(pixelId, { identityId }, { identityId });
+            await identity_cache_dynamodb_db_service_js_1.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 identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.deleteIdentityCache(pixelId, { identityId: 'unknown-id' }, { identityId: 'unknown-id' });
+            await identity_cache_dynamodb_db_service_js_1.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(identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.deleteIdentityCache(pixelId, { identityId: 'identity456' }, { identityId: 'identity456' })).resolves.toBeUndefined();
+            await expect(identity_cache_dynamodb_db_service_js_1.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 identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, {
+            await identity_cache_dynamodb_db_service_js_1.IdentityCacheDynamoDbDbService.getIdentityFromCache(pixelId, {
                 traits: { emails: ['first@email.com', 'second@email.com', 'third@email.com'] },
             });
             expect(mockedDynamoDbClient.safeGet).toHaveBeenCalledTimes(1);
@@ -1049,7 +1080,7 @@ describe('IdentityCacheDynamoDbService', () => {
         });
         it('should handle whitespace in email during lookup', async () => {
             mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
-            await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.getIdentityFromCache(pixelId, {
+            await identity_cache_dynamodb_db_service_js_1.IdentityCacheDynamoDbDbService.getIdentityFromCache(pixelId, {
                 traits: { emails: ['  test@email.com  '] },
             });
             expect(mockedDynamoDbClient.safeGet).toHaveBeenCalled();
@@ -1065,8 +1096,8 @@ describe('IdentityCacheDynamoDbService', () => {
             };
             mockedDynamoDbClient.safeGet.mockRejectedValueOnce(new Error('DynamoDB down'));
             mockInvokeFunction.mockRejectedValueOnce(new Error('Lambda down'));
-            const result = await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
-            expect(result).toEqual(incomingIdentity);
+            const result = await identity_gateway_service_js_1.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);
@@ -1077,8 +1108,8 @@ describe('IdentityCacheDynamoDbService', () => {
                 }),
             });
             mockedDynamoDbClient.safeBatchWrite.mockRejectedValueOnce(new Error('Write failed'));
-            const result = await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, { traits: { emails: ['test@email.com'] } }, lambdaArn);
-            expect(result?.identityId).toBe('resolved-id');
+            const result = await identity_gateway_service_js_1.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 = {
@@ -1090,8 +1121,8 @@ describe('IdentityCacheDynamoDbService', () => {
                 statusCode: 500,
                 body: 'Internal Server Error',
             });
-            const result = await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
-            expect(result).toEqual(incomingIdentity);
+            const result = await identity_gateway_service_js_1.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 = {
@@ -1103,12 +1134,127 @@ describe('IdentityCacheDynamoDbService', () => {
                 statusCode: 200,
                 body: 'not valid json',
             });
-            const result = await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.getIdentityWithCaching(pixelId, incomingIdentity, lambdaArn);
-            expect(result).toEqual(incomingIdentity);
+            const result = await identity_gateway_service_js_1.IdentityGatewayService.getIdentityWithCachingV2(pixelId, incomingIdentity, lambdaArn);
+            expect(result.identity).toEqual(incomingIdentity);
         });
-        it('should return undefined only when both inputs are invalid', async () => {
-            const result = await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.getIdentityWithCaching(null, null, lambdaArn);
-            expect(result).toBeUndefined();
+        it('should return undefined identity only when both inputs are invalid', async () => {
+            const result = await identity_gateway_service_js_1.IdentityGatewayService.getIdentityWithCachingV2(null, null, lambdaArn);
+            expect(result.identity).toBeUndefined();
+            expect(result.summary.outcome).toBe(types_js_1.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 identity_gateway_service_js_1.IdentityGatewayService.getIdentityWithCachingV2('', { identityId: 'identity456' }, lambdaArn);
+            expect(result.identity).toBeUndefined();
+            expect(result.summary).toEqual(expect.objectContaining({
+                outcome: types_js_1.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 identity_gateway_service_js_1.IdentityGatewayService.getIdentityWithCachingV2(pixelId, incomingIdentity, lambdaArn);
+            expect(result.identity?.identityId).toBe('identity456');
+            expect(result.summary).toEqual(expect.objectContaining({
+                outcome: types_js_1.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 identity_gateway_service_js_1.IdentityGatewayService.getIdentityWithCachingV2(pixelId, incomingIdentity, lambdaArn);
+            expect(result.identity).toEqual(neptuneIdentity);
+            expect(result.summary).toEqual(expect.objectContaining({
+                outcome: types_js_1.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 identity_gateway_service_js_1.IdentityGatewayService.getIdentityWithCachingV2(pixelId, incomingIdentity, lambdaArn);
+            expect(result.identity).toEqual(cachedIdentity);
+            expect(result.summary).toEqual(expect.objectContaining({
+                outcome: types_js_1.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', () => {
@@ -1118,18 +1264,18 @@ describe('IdentityCacheDynamoDbService', () => {
                 identityId: 'identity456',
                 traits: { emails: ['test@email.com'] },
             };
-            await identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.updateIdentityCache(pixelId, identity);
+            await identity_cache_dynamodb_db_service_js_1.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 identity_cache_dynamodb_service_js_1.IdentityCacheDynamoDbService.updateIdentityCache(pixelId, identity);
+            await identity_cache_dynamodb_db_service_js_1.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) {