@adtrackify/at-service-common 4.0.7 → 4.0.8

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

@@ -288,8 +288,8 @@ describe('IdentityGatewayService new features', () => {
                     }),
                 });
                 const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, incomingIdentity, lambdaArn);
-                expect(result.summary.didWriteCache).toBe(true);
-                expect(mockedDynamoDbClient.safeBatchWrite).toHaveBeenCalled();
+                expect(result.summary.didWriteCache).toBe(false);
+                expect(mockedDynamoDbClient.safeBatchWrite).not.toHaveBeenCalled();
             });
         });
         describe('skipCacheWrite: false', () => {
@@ -305,8 +305,8 @@ describe('IdentityGatewayService new features', () => {
                     }),
                 });
                 const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, incomingIdentity, lambdaArn, { skipCacheWrite: false });
-                expect(result.summary.didWriteCache).toBe(true);
-                expect(mockedDynamoDbClient.safeBatchWrite).toHaveBeenCalled();
+                expect(result.summary.didWriteCache).toBe(false);
+                expect(mockedDynamoDbClient.safeBatchWrite).not.toHaveBeenCalled();
             });
         });
         describe('skipCacheWrite: true', () => {
@@ -324,10 +324,16 @@ describe('IdentityGatewayService new features', () => {
                 const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, incomingIdentity, lambdaArn, { skipCacheWrite: true });
                 expect(result.identity?.identityId).toBe('resolved-identity');
                 expect(result.summary.didWriteCache).toBe(false);
-                expect(result.summary.outcome).toBe(IDENTITY_CACHE_WITH_CACHING_OUTCOME.NEPTUNE_WRITE_BACK);
+                expect(result.summary.outcome).toBe(IDENTITY_CACHE_WITH_CACHING_OUTCOME.NEPTUNE_RESOLVED);
                 expect(mockedDynamoDbClient.safeBatchWrite).not.toHaveBeenCalled();
             });
-            it('should NOT write to cache on address update path', async () => {
+            it('should enqueue async update on address update path (never writes sync)', async () => {
+                IdentityGatewayService.configure({
+                    awsRegion: 'us-east-1',
+                    awsAccountId: '123456789',
+                    asyncUpdateQueueName: 'test-queue',
+                });
+                mockBuildAndSendMessage.mockResolvedValueOnce({ MessageId: 'test-msg-id' });
                 const cachedResponse = {
                     pk: `identity#${pixelId}#identity456`,
                     pixelId,
@@ -350,9 +356,11 @@ describe('IdentityGatewayService new features', () => {
                     },
                 };
                 const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, identityWithNewAddress, lambdaArn, { skipCacheWrite: true });
-                if (result.summary.outcome === IDENTITY_CACHE_WITH_CACHING_OUTCOME.ADDRESS_UPDATE_WRITE) {
+                if (result.summary.outcome === IDENTITY_CACHE_WITH_CACHING_OUTCOME.ADDRESS_UPDATE_ASYNC) {
                     expect(result.summary.didWriteCache).toBe(false);
+                    expect(result.summary.didEnqueueAsync).toBe(true);
                     expect(mockedDynamoDbClient.safeBatchWrite).not.toHaveBeenCalled();
+                    expect(mockBuildAndSendMessage).toHaveBeenCalled();
                 }
             });
             it('should still return resolved identity when skipCacheWrite is true', async () => {
@@ -390,8 +398,14 @@ describe('IdentityGatewayService new features', () => {
                 expect(mockedDynamoDbClient.safeBatchWrite).not.toHaveBeenCalled();
             });
         });
-        describe('address update path with skipCacheWrite', () => {
-            it('should write cache when skipCacheWrite is false and address update triggers write', async () => {
+        describe('address update path - always enqueues async (never writes sync)', () => {
+            it('should enqueue async (not write cache) when address update is detected', async () => {
+                IdentityGatewayService.configure({
+                    awsRegion: 'us-east-1',
+                    awsAccountId: '123456789',
+                    asyncUpdateQueueName: 'test-queue',
+                });
+                mockBuildAndSendMessage.mockResolvedValueOnce({ MessageId: 'test-msg-id' });
                 const cachedResponse = {
                     pk: `identity#${pixelId}#identity456`,
                     pixelId,
@@ -414,11 +428,84 @@ describe('IdentityGatewayService new features', () => {
                     },
                 };
                 const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, identityWithNewAddress, lambdaArn, { skipCacheWrite: false });
-                if (result.summary.outcome === IDENTITY_CACHE_WITH_CACHING_OUTCOME.ADDRESS_UPDATE_WRITE) {
-                    expect(result.summary.didWriteCache).toBe(true);
-                    expect(mockedDynamoDbClient.safeBatchWrite).toHaveBeenCalled();
+                if (result.summary.outcome === IDENTITY_CACHE_WITH_CACHING_OUTCOME.ADDRESS_UPDATE_ASYNC) {
+                    expect(result.summary.didWriteCache).toBe(false);
+                    expect(result.summary.didEnqueueAsync).toBe(true);
+                    expect(mockedDynamoDbClient.safeBatchWrite).not.toHaveBeenCalled();
+                    expect(mockBuildAndSendMessage).toHaveBeenCalledWith('identify.updateAsync', expect.objectContaining({
+                        pixelId,
+                        incomingIdentityId: 'identity456',
+                    }));
                 }
             });
+            it('should return merged identity without waiting for cache write', async () => {
+                IdentityGatewayService.configure({
+                    awsRegion: 'us-east-1',
+                    awsAccountId: '123456789',
+                    asyncUpdateQueueName: 'test-queue',
+                });
+                mockBuildAndSendMessage.mockResolvedValueOnce({ MessageId: 'test-msg-id' });
+                const cachedResponse = {
+                    pk: `identity#${pixelId}#identity456`,
+                    pixelId,
+                    identityId: 'identity456',
+                    response: {
+                        identityId: 'identity456',
+                        traits: {
+                            emails: ['test@email.com'],
+                            addresses: [],
+                        },
+                    },
+                    updatedAt: new Date().toISOString(),
+                };
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+                const identityWithNewAddress = {
+                    identityId: 'identity456',
+                    traits: {
+                        emails: ['test@email.com'],
+                        addresses: [{ city: 'New City', firstName: 'John' }],
+                    },
+                };
+                const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, identityWithNewAddress, lambdaArn);
+                expect(result.identity).toBeDefined();
+                expect(result.identity?.identityId).toBe('identity456');
+                expect(result.summary.didSkipNeptune).toBe(true);
+                expect(result.summary.didCallNeptune).toBe(false);
+                expect(result.summary.outcome).toBe(IDENTITY_CACHE_WITH_CACHING_OUTCOME.ADDRESS_UPDATE_ASYNC);
+            });
+            it('should set didEnqueueAsync to false when SQS enqueue fails', async () => {
+                IdentityGatewayService.configure({
+                    awsRegion: 'us-east-1',
+                    awsAccountId: '123456789',
+                    asyncUpdateQueueName: 'test-queue',
+                });
+                mockBuildAndSendMessage.mockRejectedValueOnce(new Error('SQS error'));
+                const cachedResponse = {
+                    pk: `identity#${pixelId}#identity456`,
+                    pixelId,
+                    identityId: 'identity456',
+                    response: {
+                        identityId: 'identity456',
+                        traits: {
+                            emails: ['test@email.com'],
+                            addresses: [],
+                        },
+                    },
+                    updatedAt: new Date().toISOString(),
+                };
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+                const identityWithNewAddress = {
+                    identityId: 'identity456',
+                    traits: {
+                        emails: ['test@email.com'],
+                        addresses: [{ city: 'New City', firstName: 'John' }],
+                    },
+                };
+                const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, identityWithNewAddress, lambdaArn);
+                expect(result.summary.outcome).toBe(IDENTITY_CACHE_WITH_CACHING_OUTCOME.ADDRESS_UPDATE_ASYNC);
+                expect(result.identity).toBeDefined();
+                expect(result.summary.didEnqueueAsync).toBe(false);
+            });
         });
     });
     describe('edge cases', () => {
@@ -506,7 +593,7 @@ describe('IdentityGatewayService new features', () => {
                 }),
             });
             await IdentityGatewayService.getIdentityWithCachingV2(pixelId, { identityId: 'original-id', traits: { emails: ['test@email.com'] } }, lambdaArn, { skipCacheWrite: false });
-            expect(mockedDynamoDbClient.safeBatchWrite).toHaveBeenCalled();
+            expect(mockedDynamoDbClient.safeBatchWrite).not.toHaveBeenCalled();
         });
     });
     describe('summary fields consistency', () => {
@@ -531,6 +618,7 @@ describe('IdentityGatewayService new features', () => {
                 didWriteCache: false,
                 didSkipNeptune: false,
                 didFallbackToIncoming: false,
+                didEnqueueAsync: false,
                 staleTraits: expect.any(Array),
             }));
         });
@@ -556,10 +644,1525 @@ describe('IdentityGatewayService new features', () => {
                 }),
             });
             const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, { identityId: 'identity456', traits: { emails: ['old@email.com', 'new@email.com'] } }, lambdaArn);
-            if (result.summary.outcome === IDENTITY_CACHE_WITH_CACHING_OUTCOME.NEPTUNE_WRITE_BACK) {
+            if (result.summary.outcome === IDENTITY_CACHE_WITH_CACHING_OUTCOME.NEPTUNE_RESOLVED) {
                 expect(result.summary.traitChanges).toBeDefined();
             }
         });
     });
+    describe('ADDRESS_UPDATE async behavior (comprehensive)', () => {
+        describe('ADDRESS_UPDATE enqueues async (not sync write)', () => {
+            it('should enqueue async when staleness tier is ADDRESS_UPDATE with non-IP address', async () => {
+                IdentityGatewayService.configure({
+                    awsRegion: 'us-east-1',
+                    awsAccountId: '123456789',
+                    asyncUpdateQueueName: 'identity-async-queue',
+                });
+                mockBuildAndSendMessage.mockResolvedValueOnce({ MessageId: 'async-msg-123' });
+                const cachedResponse = {
+                    pk: `identity#${pixelId}#identity456`,
+                    pixelId,
+                    identityId: 'identity456',
+                    response: {
+                        identityId: 'identity456',
+                        traits: {
+                            emails: ['test@email.com'],
+                            addresses: [],
+                        },
+                    },
+                    updatedAt: new Date().toISOString(),
+                };
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+                const incomingWithAddress = {
+                    identityId: 'identity456',
+                    traits: {
+                        emails: ['test@email.com'],
+                        addresses: [{ firstName: 'John', lastName: 'Doe', city: 'New York' }],
+                    },
+                };
+                const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, incomingWithAddress, lambdaArn);
+                expect(result.summary.outcome).toBe(IDENTITY_CACHE_WITH_CACHING_OUTCOME.ADDRESS_UPDATE_ASYNC);
+                expect(mockBuildAndSendMessage).toHaveBeenCalledWith('identify.updateAsync', expect.objectContaining({
+                    pixelId,
+                    incomingIdentityId: 'identity456',
+                }));
+                expect(result.summary.didEnqueueAsync).toBe(true);
+                expect(result.summary.didWriteCache).toBe(false);
+                expect(result.summary.didCallNeptune).toBe(false);
+                expect(result.summary.didSkipNeptune).toBe(true);
+                expect(mockedDynamoDbClient.safeBatchWrite).not.toHaveBeenCalled();
+                expect(mockInvokeFunction).not.toHaveBeenCalled();
+            });
+            it('should return merged identity with updated addresses', async () => {
+                IdentityGatewayService.configure({
+                    awsRegion: 'us-east-1',
+                    awsAccountId: '123456789',
+                    asyncUpdateQueueName: 'identity-async-queue',
+                });
+                mockBuildAndSendMessage.mockResolvedValueOnce({ MessageId: 'msg-456' });
+                const cachedResponse = {
+                    pk: `identity#${pixelId}#identity456`,
+                    pixelId,
+                    identityId: 'identity456',
+                    response: {
+                        identityId: 'identity456',
+                        traits: {
+                            emails: ['test@email.com'],
+                            phones: ['555-1234'],
+                            addresses: [],
+                        },
+                    },
+                    updatedAt: new Date().toISOString(),
+                };
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+                const incomingWithAddress = {
+                    identityId: 'identity456',
+                    traits: {
+                        emails: ['test@email.com'],
+                        addresses: [{ firstName: 'Jane', city: 'Boston', zip: '02101' }],
+                    },
+                };
+                const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, incomingWithAddress, lambdaArn);
+                expect(result.identity).toBeDefined();
+                expect(result.identity?.identityId).toBe('identity456');
+                expect(result.identity?.traits?.emails).toContain('test@email.com');
+                expect(result.identity?.traits?.addresses).toHaveLength(1);
+                expect(result.identity?.traits?.addresses?.[0]?.firstName).toBe('Jane');
+            });
+            it('should include writeReason ADDRESS_UPDATE in summary', async () => {
+                IdentityGatewayService.configure({
+                    awsRegion: 'us-east-1',
+                    awsAccountId: '123456789',
+                    asyncUpdateQueueName: 'identity-async-queue',
+                });
+                mockBuildAndSendMessage.mockResolvedValueOnce({ MessageId: 'msg-789' });
+                const cachedResponse = {
+                    pk: `identity#${pixelId}#identity456`,
+                    pixelId,
+                    identityId: 'identity456',
+                    response: {
+                        identityId: 'identity456',
+                        traits: {
+                            emails: ['test@email.com'],
+                            addresses: [],
+                        },
+                    },
+                    updatedAt: new Date().toISOString(),
+                };
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+                const incomingWithAddress = {
+                    identityId: 'identity456',
+                    traits: {
+                        emails: ['test@email.com'],
+                        addresses: [{ firstName: 'Bob', city: 'Seattle' }],
+                    },
+                };
+                const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, incomingWithAddress, lambdaArn);
+                expect(result.summary.writeReason).toBe('address_update');
+            });
+            it('should include traitChanges for address update', async () => {
+                IdentityGatewayService.configure({
+                    awsRegion: 'us-east-1',
+                    awsAccountId: '123456789',
+                    asyncUpdateQueueName: 'identity-async-queue',
+                });
+                mockBuildAndSendMessage.mockResolvedValueOnce({ MessageId: 'msg-trait' });
+                const cachedResponse = {
+                    pk: `identity#${pixelId}#identity456`,
+                    pixelId,
+                    identityId: 'identity456',
+                    response: {
+                        identityId: 'identity456',
+                        traits: {
+                            emails: ['test@email.com'],
+                            addresses: [],
+                        },
+                    },
+                    updatedAt: new Date().toISOString(),
+                };
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+                const incomingWithAddress = {
+                    identityId: 'identity456',
+                    traits: {
+                        emails: ['test@email.com'],
+                        addresses: [{ firstName: 'Alice', city: 'Chicago' }],
+                    },
+                };
+                const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, incomingWithAddress, lambdaArn);
+                expect(result.summary.traitChanges).toBeDefined();
+            });
+        });
+        describe('ADDRESS_UPDATE async failure handling', () => {
+            it('should set didEnqueueAsync to false when enqueue fails', async () => {
+                IdentityGatewayService.configure({
+                    awsRegion: 'us-east-1',
+                    awsAccountId: '123456789',
+                    asyncUpdateQueueName: 'identity-async-queue',
+                });
+                mockBuildAndSendMessage.mockRejectedValueOnce(new Error('SQS unavailable'));
+                const cachedResponse = {
+                    pk: `identity#${pixelId}#identity456`,
+                    pixelId,
+                    identityId: 'identity456',
+                    response: {
+                        identityId: 'identity456',
+                        traits: {
+                            emails: ['test@email.com'],
+                            addresses: [],
+                        },
+                    },
+                    updatedAt: new Date().toISOString(),
+                };
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+                const incomingWithAddress = {
+                    identityId: 'identity456',
+                    traits: {
+                        emails: ['test@email.com'],
+                        addresses: [{ firstName: 'Test', city: 'TestCity' }],
+                    },
+                };
+                const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, incomingWithAddress, lambdaArn);
+                expect(result.summary.outcome).toBe(IDENTITY_CACHE_WITH_CACHING_OUTCOME.ADDRESS_UPDATE_ASYNC);
+                expect(result.summary.didEnqueueAsync).toBe(false);
+                expect(result.identity).toBeDefined();
+                expect(result.identity?.identityId).toBe('identity456');
+            });
+            it('should log warning when enqueue fails', async () => {
+                IdentityGatewayService.configure({
+                    awsRegion: 'us-east-1',
+                    awsAccountId: '123456789',
+                    asyncUpdateQueueName: 'identity-async-queue',
+                });
+                mockBuildAndSendMessage.mockRejectedValueOnce(new Error('Network timeout'));
+                const cachedResponse = {
+                    pk: `identity#${pixelId}#identity456`,
+                    pixelId,
+                    identityId: 'identity456',
+                    response: {
+                        identityId: 'identity456',
+                        traits: {
+                            emails: ['test@email.com'],
+                            addresses: [],
+                        },
+                    },
+                    updatedAt: new Date().toISOString(),
+                };
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+                const incomingWithAddress = {
+                    identityId: 'identity456',
+                    traits: {
+                        emails: ['test@email.com'],
+                        addresses: [{ firstName: 'Test', city: 'TestCity' }],
+                    },
+                };
+                await IdentityGatewayService.getIdentityWithCachingV2(pixelId, incomingWithAddress, lambdaArn);
+                expect(mockedLogger.warn).toHaveBeenCalledWith('IdentityGateway - enqueueAsyncIdentityUpdate: failed to enqueue (failing open)', expect.objectContaining({
+                    error: expect.any(Error),
+                    errorMessage: 'Network timeout',
+                    pixelId,
+                }));
+            });
+            it('should set didEnqueueAsync to false when SQS client is not configured', async () => {
+                const cachedResponse = {
+                    pk: `identity#${pixelId}#identity456`,
+                    pixelId,
+                    identityId: 'identity456',
+                    response: {
+                        identityId: 'identity456',
+                        traits: {
+                            emails: ['test@email.com'],
+                            addresses: [],
+                        },
+                    },
+                    updatedAt: new Date().toISOString(),
+                };
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+                const incomingWithAddress = {
+                    identityId: 'identity456',
+                    traits: {
+                        emails: ['test@email.com'],
+                        addresses: [{ firstName: 'Test', city: 'TestCity' }],
+                    },
+                };
+                const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, incomingWithAddress, lambdaArn);
+                expect(result.summary.outcome).toBe(IDENTITY_CACHE_WITH_CACHING_OUTCOME.ADDRESS_UPDATE_ASYNC);
+                expect(result.summary.didEnqueueAsync).toBe(false);
+                expect(result.identity).toBeDefined();
+            });
+        });
+        describe('IDENTITY_STALE path (comparison with ADDRESS_UPDATE)', () => {
+            it('should call Neptune when staleness tier is IDENTITY_STALE (not ADDRESS_UPDATE)', async () => {
+                IdentityGatewayService.configure({
+                    awsRegion: 'us-east-1',
+                    awsAccountId: '123456789',
+                    asyncUpdateQueueName: 'identity-async-queue',
+                });
+                const cachedResponse = {
+                    pk: `identity#${pixelId}#identity456`,
+                    pixelId,
+                    identityId: 'identity456',
+                    response: {
+                        identityId: 'identity456',
+                        traits: {
+                            emails: ['old@email.com'],
+                        },
+                    },
+                    updatedAt: new Date().toISOString(),
+                };
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+                mockInvokeFunction.mockResolvedValueOnce({
+                    statusCode: 200,
+                    body: JSON.stringify({
+                        identity: {
+                            identityId: 'identity456',
+                            traits: {
+                                emails: ['old@email.com', 'new@email.com'],
+                            },
+                        },
+                    }),
+                });
+                const incomingWithNewEmail = {
+                    identityId: 'identity456',
+                    traits: {
+                        emails: ['old@email.com', 'new@email.com'],
+                    },
+                };
+                const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, incomingWithNewEmail, lambdaArn);
+                expect(mockInvokeFunction).toHaveBeenCalled();
+                expect(result.summary.didCallNeptune).toBe(true);
+                expect(result.summary.didSkipNeptune).toBe(false);
+                expect(mockBuildAndSendMessage).not.toHaveBeenCalled();
+                expect(result.summary.didEnqueueAsync).toBe(false);
+                expect(result.summary.outcome).not.toBe(IDENTITY_CACHE_WITH_CACHING_OUTCOME.ADDRESS_UPDATE_ASYNC);
+            });
+            it('should NOT call Neptune when staleness tier is ADDRESS_UPDATE', async () => {
+                IdentityGatewayService.configure({
+                    awsRegion: 'us-east-1',
+                    awsAccountId: '123456789',
+                    asyncUpdateQueueName: 'identity-async-queue',
+                });
+                mockBuildAndSendMessage.mockResolvedValueOnce({ MessageId: 'msg-no-neptune' });
+                const cachedResponse = {
+                    pk: `identity#${pixelId}#identity456`,
+                    pixelId,
+                    identityId: 'identity456',
+                    response: {
+                        identityId: 'identity456',
+                        traits: {
+                            emails: ['test@email.com'],
+                            addresses: [],
+                        },
+                    },
+                    updatedAt: new Date().toISOString(),
+                };
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+                const incomingWithAddress = {
+                    identityId: 'identity456',
+                    traits: {
+                        emails: ['test@email.com'],
+                        addresses: [{ firstName: 'Test', city: 'TestCity' }],
+                    },
+                };
+                const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, incomingWithAddress, lambdaArn);
+                expect(mockInvokeFunction).not.toHaveBeenCalled();
+                expect(result.summary.didCallNeptune).toBe(false);
+                expect(result.summary.didSkipNeptune).toBe(true);
+                expect(result.summary.outcome).toBe(IDENTITY_CACHE_WITH_CACHING_OUTCOME.ADDRESS_UPDATE_ASYNC);
+            });
+            it('should write cache from Neptune in IDENTITY_STALE path (identity-service handles it)', async () => {
+                const cachedResponse = {
+                    pk: `identity#${pixelId}#identity456`,
+                    pixelId,
+                    identityId: 'identity456',
+                    response: {
+                        identityId: 'identity456',
+                        traits: {
+                            emails: ['old@email.com'],
+                        },
+                    },
+                    updatedAt: new Date().toISOString(),
+                };
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+                mockInvokeFunction.mockResolvedValueOnce({
+                    statusCode: 200,
+                    body: JSON.stringify({
+                        identity: {
+                            identityId: 'identity456',
+                            traits: {
+                                emails: ['old@email.com', 'new@email.com'],
+                            },
+                        },
+                    }),
+                });
+                const incomingWithNewEmail = {
+                    identityId: 'identity456',
+                    traits: {
+                        emails: ['old@email.com', 'new@email.com'],
+                    },
+                };
+                const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, incomingWithNewEmail, lambdaArn);
+                expect(result.summary.didCallNeptune).toBe(true);
+                expect(result.summary.didWriteCache).toBe(false);
+                expect(mockedDynamoDbClient.safeBatchWrite).not.toHaveBeenCalled();
+            });
+        });
+        describe('summary correctness for ADDRESS_UPDATE path', () => {
+            it('should have correct summary fields for successful ADDRESS_UPDATE async enqueue', async () => {
+                IdentityGatewayService.configure({
+                    awsRegion: 'us-east-1',
+                    awsAccountId: '123456789',
+                    asyncUpdateQueueName: 'identity-async-queue',
+                });
+                mockBuildAndSendMessage.mockResolvedValueOnce({ MessageId: 'summary-test-msg' });
+                const cachedResponse = {
+                    pk: `identity#${pixelId}#identity456`,
+                    pixelId,
+                    identityId: 'identity456',
+                    response: {
+                        identityId: 'identity456',
+                        traits: {
+                            emails: ['test@email.com'],
+                            addresses: [],
+                        },
+                    },
+                    updatedAt: new Date().toISOString(),
+                };
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+                const incomingWithAddress = {
+                    identityId: 'identity456',
+                    traits: {
+                        emails: ['test@email.com'],
+                        addresses: [{ firstName: 'Summary', city: 'SummaryCity' }],
+                    },
+                };
+                const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, incomingWithAddress, lambdaArn);
+                expect(result.summary).toEqual(expect.objectContaining({
+                    outcome: IDENTITY_CACHE_WITH_CACHING_OUTCOME.ADDRESS_UPDATE_ASYNC,
+                    pixelId,
+                    identityId: 'identity456',
+                    didReadCache: true,
+                    didCallNeptune: false,
+                    didWriteCache: false,
+                    didSkipNeptune: true,
+                    didFallbackToIncoming: false,
+                    didEnqueueAsync: true,
+                    writeReason: 'address_update',
+                }));
+            });
+            it('should have correct summary fields for failed ADDRESS_UPDATE async enqueue', async () => {
+                IdentityGatewayService.configure({
+                    awsRegion: 'us-east-1',
+                    awsAccountId: '123456789',
+                    asyncUpdateQueueName: 'identity-async-queue',
+                });
+                mockBuildAndSendMessage.mockRejectedValueOnce(new Error('Enqueue failed'));
+                const cachedResponse = {
+                    pk: `identity#${pixelId}#identity456`,
+                    pixelId,
+                    identityId: 'identity456',
+                    response: {
+                        identityId: 'identity456',
+                        traits: {
+                            emails: ['test@email.com'],
+                            addresses: [],
+                        },
+                    },
+                    updatedAt: new Date().toISOString(),
+                };
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+                const incomingWithAddress = {
+                    identityId: 'identity456',
+                    traits: {
+                        emails: ['test@email.com'],
+                        addresses: [{ firstName: 'Fail', city: 'FailCity' }],
+                    },
+                };
+                const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, incomingWithAddress, lambdaArn);
+                expect(result.summary).toEqual(expect.objectContaining({
+                    outcome: IDENTITY_CACHE_WITH_CACHING_OUTCOME.ADDRESS_UPDATE_ASYNC,
+                    pixelId,
+                    identityId: 'identity456',
+                    didReadCache: true,
+                    didCallNeptune: false,
+                    didWriteCache: false,
+                    didSkipNeptune: true,
+                    didFallbackToIncoming: false,
+                    didEnqueueAsync: false,
+                    writeReason: 'address_update',
+                }));
+            });
+        });
+        describe('IP-sourced vs non-IP address behavior', () => {
+            it('should NOT trigger ADDRESS_UPDATE for IP-sourced addresses (VOLATILE_ONLY tier)', async () => {
+                IdentityGatewayService.configure({
+                    awsRegion: 'us-east-1',
+                    awsAccountId: '123456789',
+                    asyncUpdateQueueName: 'identity-async-queue',
+                });
+                const cachedResponse = {
+                    pk: `identity#${pixelId}#identity456`,
+                    pixelId,
+                    identityId: 'identity456',
+                    response: {
+                        identityId: 'identity456',
+                        traits: {
+                            emails: ['test@email.com'],
+                            addresses: [],
+                        },
+                    },
+                    updatedAt: new Date().toISOString(),
+                };
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+                const incomingWithIpAddress = {
+                    identityId: 'identity456',
+                    traits: {
+                        emails: ['test@email.com'],
+                        addresses: [{ city: 'IPCity', country: 'US' }],
+                    },
+                };
+                const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, incomingWithIpAddress, lambdaArn);
+                expect(result.summary.outcome).toBe(IDENTITY_CACHE_WITH_CACHING_OUTCOME.VOLATILE_ONLY_CACHE_HIT);
+                expect(result.summary.didEnqueueAsync).toBe(false);
+                expect(mockBuildAndSendMessage).not.toHaveBeenCalled();
+            });
+            it('should trigger ADDRESS_UPDATE for non-IP address (has PII fields)', async () => {
+                IdentityGatewayService.configure({
+                    awsRegion: 'us-east-1',
+                    awsAccountId: '123456789',
+                    asyncUpdateQueueName: 'identity-async-queue',
+                });
+                mockBuildAndSendMessage.mockResolvedValueOnce({ MessageId: 'non-ip-msg' });
+                const cachedResponse = {
+                    pk: `identity#${pixelId}#identity456`,
+                    pixelId,
+                    identityId: 'identity456',
+                    response: {
+                        identityId: 'identity456',
+                        traits: {
+                            emails: ['test@email.com'],
+                            addresses: [],
+                        },
+                    },
+                    updatedAt: new Date().toISOString(),
+                };
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+                const incomingWithNonIpAddress = {
+                    identityId: 'identity456',
+                    traits: {
+                        emails: ['test@email.com'],
+                        addresses: [{ firstName: 'John', city: 'NonIPCity' }],
+                    },
+                };
+                const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, incomingWithNonIpAddress, lambdaArn);
+                expect(result.summary.outcome).toBe(IDENTITY_CACHE_WITH_CACHING_OUTCOME.ADDRESS_UPDATE_ASYNC);
+                expect(result.summary.didEnqueueAsync).toBe(true);
+                expect(mockBuildAndSendMessage).toHaveBeenCalled();
+            });
+        });
+    });
+    describe('refactored flow: merge and staleness computation', () => {
+        describe('mergeAndComputeIdentityStaleness behavior', () => {
+            it('should merge incoming traits with cached traits on cache hit', async () => {
+                const cachedResponse = {
+                    pk: `identity#${pixelId}#merge-test`,
+                    pixelId,
+                    identityId: 'merge-test',
+                    response: {
+                        identityId: 'merge-test',
+                        traits: {
+                            emails: ['cached@email.com'],
+                            phones: ['555-cached'],
+                        },
+                    },
+                    updatedAt: new Date().toISOString(),
+                };
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+                const incomingIdentity = {
+                    identityId: 'merge-test',
+                    traits: {
+                        emails: ['cached@email.com'],
+                    },
+                };
+                const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, incomingIdentity, lambdaArn);
+                expect(result.identity?.traits?.emails).toContain('cached@email.com');
+                expect(result.identity?.traits?.phones).toContain('555-cached');
+            });
+            it('should compute staleness after cache hit', async () => {
+                const cachedResponse = {
+                    pk: `identity#${pixelId}#staleness-compute`,
+                    pixelId,
+                    identityId: 'staleness-compute',
+                    response: {
+                        identityId: 'staleness-compute',
+                        traits: {
+                            emails: ['old@email.com'],
+                        },
+                    },
+                    updatedAt: new Date().toISOString(),
+                };
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+                mockInvokeFunction.mockResolvedValueOnce({
+                    statusCode: 200,
+                    body: JSON.stringify({
+                        identity: {
+                            identityId: 'staleness-compute',
+                            traits: { emails: ['old@email.com', 'new@email.com'] },
+                        },
+                    }),
+                });
+                const incomingIdentity = {
+                    identityId: 'staleness-compute',
+                    traits: {
+                        emails: ['old@email.com', 'new@email.com'],
+                    },
+                };
+                const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, incomingIdentity, lambdaArn);
+                expect(result.summary.didCallNeptune).toBe(true);
+                expect(result.summary.staleTraits).toContain('emails');
+            });
+        });
+        describe('deep equality check', () => {
+            it('should treat as cache hit when merged identity is deep equal to cached', async () => {
+                const cachedResponse = {
+                    pk: `identity#${pixelId}#deep-equal`,
+                    pixelId,
+                    identityId: 'deep-equal',
+                    response: {
+                        identityId: 'deep-equal',
+                        traits: {
+                            emails: ['same@email.com'],
+                            phones: ['555-1234'],
+                        },
+                    },
+                    updatedAt: new Date().toISOString(),
+                };
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+                const incomingIdentity = {
+                    identityId: 'deep-equal',
+                    traits: {
+                        emails: ['same@email.com'],
+                        phones: ['555-1234'],
+                    },
+                };
+                const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, incomingIdentity, lambdaArn);
+                expect(result.summary.outcome).toBe(IDENTITY_CACHE_WITH_CACHING_OUTCOME.FRESH_CACHE_HIT);
+                expect(result.summary.didCallNeptune).toBe(false);
+                expect(mockInvokeFunction).not.toHaveBeenCalled();
+            });
+            it('should strip address timestamps before deep equality comparison', async () => {
+                const now = Date.now();
+                const cachedResponse = {
+                    pk: `identity#${pixelId}#timestamp-strip`,
+                    pixelId,
+                    identityId: 'timestamp-strip',
+                    response: {
+                        identityId: 'timestamp-strip',
+                        traits: {
+                            emails: ['test@email.com'],
+                            addresses: [{ city: 'NYC', cra: now - 10000, upa: now - 5000 }],
+                        },
+                    },
+                    updatedAt: new Date().toISOString(),
+                };
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+                const incomingIdentity = {
+                    identityId: 'timestamp-strip',
+                    traits: {
+                        emails: ['test@email.com'],
+                        addresses: [{ city: 'NYC', cra: now, upa: now }],
+                    },
+                };
+                const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, incomingIdentity, lambdaArn);
+                expect(result.summary.outcome).toBe(IDENTITY_CACHE_WITH_CACHING_OUTCOME.FRESH_CACHE_HIT);
+                expect(result.summary.didCallNeptune).toBe(false);
+            });
+        });
+        describe('volatile-only override', () => {
+            it('should treat VOLATILE_ONLY + not deep equal as cache hit', async () => {
+                const cachedResponse = {
+                    pk: `identity#${pixelId}#volatile-override`,
+                    pixelId,
+                    identityId: 'volatile-override',
+                    response: {
+                        identityId: 'volatile-override',
+                        traits: {
+                            emails: ['same@email.com'],
+                        },
+                    },
+                    updatedAt: new Date().toISOString(),
+                };
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+                const incomingIdentity = {
+                    identityId: 'volatile-override',
+                    traits: {
+                        emails: ['same@email.com'],
+                        ipAddress: '10.0.0.1',
+                        userAgent: 'Mozilla/5.0 (New)',
+                    },
+                };
+                const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, incomingIdentity, lambdaArn);
+                expect(result.summary.outcome).toBe(IDENTITY_CACHE_WITH_CACHING_OUTCOME.VOLATILE_ONLY_CACHE_HIT);
+                expect(result.summary.didCallNeptune).toBe(false);
+                expect(result.summary.didWriteCache).toBe(false);
+            });
+            it('should return merged identity for VOLATILE_ONLY tier', async () => {
+                const cachedResponse = {
+                    pk: `identity#${pixelId}#volatile-merged`,
+                    pixelId,
+                    identityId: 'volatile-merged',
+                    response: {
+                        identityId: 'volatile-merged',
+                        traits: {
+                            emails: ['test@email.com'],
+                            phones: ['555-cached'],
+                        },
+                    },
+                    updatedAt: new Date().toISOString(),
+                };
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+                const incomingIdentity = {
+                    identityId: 'volatile-merged',
+                    traits: {
+                        emails: ['test@email.com'],
+                        ipAddress: '10.0.0.1',
+                    },
+                };
+                const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, incomingIdentity, lambdaArn);
+                expect(result.summary.outcome).toBe(IDENTITY_CACHE_WITH_CACHING_OUTCOME.VOLATILE_ONLY_CACHE_HIT);
+                expect(result.identity?.traits?.emails).toContain('test@email.com');
+                expect(result.identity?.traits?.phones).toContain('555-cached');
+                expect(result.identity?.traits?.ipAddress).toBe('10.0.0.1');
+            });
+        });
+        describe('skipNeptune derivation from staleTier', () => {
+            it('should set skipNeptune=true for ADDRESS_UPDATE tier', async () => {
+                IdentityGatewayService.configure({
+                    awsRegion: 'us-east-1',
+                    awsAccountId: '123456789',
+                    asyncUpdateQueueName: 'identity-async-queue',
+                });
+                mockBuildAndSendMessage.mockResolvedValueOnce({ MessageId: 'skip-neptune-test' });
+                const cachedResponse = {
+                    pk: `identity#${pixelId}#skip-neptune-addr`,
+                    pixelId,
+                    identityId: 'skip-neptune-addr',
+                    response: {
+                        identityId: 'skip-neptune-addr',
+                        traits: {
+                            emails: ['test@email.com'],
+                            addresses: [],
+                        },
+                    },
+                    updatedAt: new Date().toISOString(),
+                };
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+                const incomingIdentity = {
+                    identityId: 'skip-neptune-addr',
+                    traits: {
+                        emails: ['test@email.com'],
+                        addresses: [{ firstName: 'John', city: 'NYC' }],
+                    },
+                };
+                const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, incomingIdentity, lambdaArn);
+                expect(result.summary.didSkipNeptune).toBe(true);
+                expect(result.summary.didCallNeptune).toBe(false);
+                expect(mockInvokeFunction).not.toHaveBeenCalled();
+            });
+            it('should set skipNeptune=false for IDENTITY_STALE tier', async () => {
+                const cachedResponse = {
+                    pk: `identity#${pixelId}#call-neptune`,
+                    pixelId,
+                    identityId: 'call-neptune',
+                    response: {
+                        identityId: 'call-neptune',
+                        traits: {
+                            emails: ['old@email.com'],
+                        },
+                    },
+                    updatedAt: new Date().toISOString(),
+                };
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+                mockInvokeFunction.mockResolvedValueOnce({
+                    statusCode: 200,
+                    body: JSON.stringify({
+                        identity: {
+                            identityId: 'call-neptune',
+                            traits: { emails: ['old@email.com', 'new@email.com'] },
+                        },
+                    }),
+                });
+                const incomingIdentity = {
+                    identityId: 'call-neptune',
+                    traits: {
+                        emails: ['old@email.com', 'new@email.com'],
+                    },
+                };
+                const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, incomingIdentity, lambdaArn);
+                expect(result.summary.didSkipNeptune).toBe(false);
+                expect(result.summary.didCallNeptune).toBe(true);
+                expect(mockInvokeFunction).toHaveBeenCalled();
+            });
+        });
+        describe('writeReason derivation from staleTier', () => {
+            it('should set writeReason=address_update for ADDRESS_UPDATE tier', async () => {
+                IdentityGatewayService.configure({
+                    awsRegion: 'us-east-1',
+                    awsAccountId: '123456789',
+                    asyncUpdateQueueName: 'identity-async-queue',
+                });
+                mockBuildAndSendMessage.mockResolvedValueOnce({ MessageId: 'addr-reason-test' });
+                const cachedResponse = {
+                    pk: `identity#${pixelId}#addr-reason`,
+                    pixelId,
+                    identityId: 'addr-reason',
+                    response: {
+                        identityId: 'addr-reason',
+                        traits: {
+                            emails: ['test@email.com'],
+                            addresses: [],
+                        },
+                    },
+                    updatedAt: new Date().toISOString(),
+                };
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+                const incomingIdentity = {
+                    identityId: 'addr-reason',
+                    traits: {
+                        emails: ['test@email.com'],
+                        addresses: [{ firstName: 'Test', city: 'TestCity' }],
+                    },
+                };
+                const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, incomingIdentity, lambdaArn);
+                expect(result.summary.writeReason).toBe('address_update');
+            });
+            it('should set writeReason=stale_traits for IDENTITY_STALE tier', async () => {
+                const cachedResponse = {
+                    pk: `identity#${pixelId}#stale-reason`,
+                    pixelId,
+                    identityId: 'stale-reason',
+                    response: {
+                        identityId: 'stale-reason',
+                        traits: {
+                            emails: ['old@email.com'],
+                        },
+                    },
+                    updatedAt: new Date().toISOString(),
+                };
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+                mockInvokeFunction.mockResolvedValueOnce({
+                    statusCode: 200,
+                    body: JSON.stringify({
+                        identity: {
+                            identityId: 'stale-reason',
+                            traits: { emails: ['old@email.com', 'new@email.com'] },
+                        },
+                    }),
+                });
+                const incomingIdentity = {
+                    identityId: 'stale-reason',
+                    traits: {
+                        emails: ['old@email.com', 'new@email.com'],
+                    },
+                };
+                const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, incomingIdentity, lambdaArn);
+                expect(result.summary.writeReason).toBeUndefined();
+                expect(result.summary.outcome).toBe(IDENTITY_CACHE_WITH_CACHING_OUTCOME.NEPTUNE_RESOLVED);
+            });
+        });
+        describe('ADDRESS_UPDATE → enqueueAsyncIdentityUpdate path', () => {
+            it('should enqueue async update instead of calling Neptune', async () => {
+                IdentityGatewayService.configure({
+                    awsRegion: 'us-east-1',
+                    awsAccountId: '123456789',
+                    asyncUpdateQueueName: 'identity-async-queue',
+                });
+                mockBuildAndSendMessage.mockResolvedValueOnce({ MessageId: 'async-path-test' });
+                const cachedResponse = {
+                    pk: `identity#${pixelId}#async-enqueue`,
+                    pixelId,
+                    identityId: 'async-enqueue',
+                    response: {
+                        identityId: 'async-enqueue',
+                        traits: {
+                            emails: ['test@email.com'],
+                            addresses: [],
+                        },
+                    },
+                    updatedAt: new Date().toISOString(),
+                };
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+                const incomingIdentity = {
+                    identityId: 'async-enqueue',
+                    traits: {
+                        emails: ['test@email.com'],
+                        addresses: [{ firstName: 'Async', city: 'AsyncCity' }],
+                    },
+                };
+                const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, incomingIdentity, lambdaArn);
+                expect(result.summary.outcome).toBe(IDENTITY_CACHE_WITH_CACHING_OUTCOME.ADDRESS_UPDATE_ASYNC);
+                expect(result.summary.didEnqueueAsync).toBe(true);
+                expect(result.summary.didCallNeptune).toBe(false);
+                expect(mockBuildAndSendMessage).toHaveBeenCalledWith('identify.updateAsync', expect.objectContaining({
+                    pixelId,
+                    incomingIdentityId: 'async-enqueue',
+                }));
+                expect(mockInvokeFunction).not.toHaveBeenCalled();
+            });
+            it('should return merged identity immediately (no Neptune wait)', async () => {
+                IdentityGatewayService.configure({
+                    awsRegion: 'us-east-1',
+                    awsAccountId: '123456789',
+                    asyncUpdateQueueName: 'identity-async-queue',
+                });
+                mockBuildAndSendMessage.mockResolvedValueOnce({ MessageId: 'immediate-return' });
+                const cachedResponse = {
+                    pk: `identity#${pixelId}#immediate`,
+                    pixelId,
+                    identityId: 'immediate',
+                    response: {
+                        identityId: 'immediate',
+                        traits: {
+                            emails: ['test@email.com'],
+                            phones: ['555-cached'],
+                            addresses: [],
+                        },
+                    },
+                    updatedAt: new Date().toISOString(),
+                };
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+                const incomingIdentity = {
+                    identityId: 'immediate',
+                    traits: {
+                        emails: ['test@email.com'],
+                        addresses: [{ firstName: 'Immediate', city: 'ImmediateCity' }],
+                    },
+                };
+                const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, incomingIdentity, lambdaArn);
+                expect(result.identity).toBeDefined();
+                expect(result.identity?.identityId).toBe('immediate');
+                expect(result.identity?.traits?.phones).toContain('555-cached');
+                expect(result.identity?.traits?.addresses).toHaveLength(1);
+            });
+        });
+        describe('IDENTITY_STALE → Neptune path', () => {
+            it('should call Neptune for identity-defining trait changes', async () => {
+                const cachedResponse = {
+                    pk: `identity#${pixelId}#neptune-path`,
+                    pixelId,
+                    identityId: 'neptune-path',
+                    response: {
+                        identityId: 'neptune-path',
+                        traits: {
+                            emails: ['old@email.com'],
+                        },
+                    },
+                    updatedAt: new Date().toISOString(),
+                };
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+                mockInvokeFunction.mockResolvedValueOnce({
+                    statusCode: 200,
+                    body: JSON.stringify({
+                        identity: {
+                            identityId: 'neptune-path',
+                            traits: { emails: ['old@email.com', 'new@email.com'] },
+                        },
+                    }),
+                });
+                const incomingIdentity = {
+                    identityId: 'neptune-path',
+                    traits: {
+                        emails: ['old@email.com', 'new@email.com'],
+                    },
+                };
+                const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, incomingIdentity, lambdaArn);
+                expect(result.summary.didCallNeptune).toBe(true);
+                expect(mockInvokeFunction).toHaveBeenCalledWith(lambdaArn, expect.objectContaining({
+                    pixelId,
+                }));
+            });
+            it('should write Neptune result to cache when different from cached', async () => {
+                const cachedResponse = {
+                    pk: `identity#${pixelId}#neptune-write`,
+                    pixelId,
+                    identityId: 'neptune-write',
+                    response: {
+                        identityId: 'neptune-write',
+                        traits: {
+                            emails: ['old@email.com'],
+                        },
+                    },
+                    updatedAt: new Date().toISOString(),
+                };
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+                mockInvokeFunction.mockResolvedValueOnce({
+                    statusCode: 200,
+                    body: JSON.stringify({
+                        identity: {
+                            identityId: 'neptune-write',
+                            traits: {
+                                emails: ['old@email.com', 'new@email.com'],
+                                phones: ['555-neptune'],
+                            },
+                        },
+                    }),
+                });
+                const incomingIdentity = {
+                    identityId: 'neptune-write',
+                    traits: {
+                        emails: ['old@email.com', 'new@email.com'],
+                    },
+                };
+                const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, incomingIdentity, lambdaArn);
+                expect(result.summary.didWriteCache).toBe(false);
+                expect(result.summary.outcome).toBe(IDENTITY_CACHE_WITH_CACHING_OUTCOME.NEPTUNE_RESOLVED);
+                expect(mockedDynamoDbClient.safeBatchWrite).not.toHaveBeenCalled();
+            });
+            it('should skip cache write when Neptune result matches cached', async () => {
+                const cachedResponse = {
+                    pk: `identity#${pixelId}#neptune-skip-write`,
+                    pixelId,
+                    identityId: 'neptune-skip-write',
+                    response: {
+                        identityId: 'neptune-skip-write',
+                        traits: {
+                            emails: ['existing@email.com'],
+                        },
+                    },
+                    updatedAt: new Date().toISOString(),
+                };
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+                mockInvokeFunction.mockResolvedValueOnce({
+                    statusCode: 200,
+                    body: JSON.stringify({
+                        identity: {
+                            identityId: 'neptune-skip-write',
+                            traits: {
+                                emails: ['existing@email.com'],
+                            },
+                        },
+                    }),
+                });
+                const incomingIdentity = {
+                    identityId: 'neptune-skip-write',
+                    traits: {
+                        emails: ['existing@email.com', 'thought-new@email.com'],
+                    },
+                };
+                const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, incomingIdentity, lambdaArn);
+                expect(result.summary.didCallNeptune).toBe(true);
+                expect(result.summary.didWriteCache).toBe(false);
+                expect(result.summary.outcome).toBe(IDENTITY_CACHE_WITH_CACHING_OUTCOME.NEPTUNE_RESOLVED);
+            });
+            it('should return NEPTUNE_RESOLUTION_FAILED when Neptune throws', async () => {
+                const cachedResponse = {
+                    pk: `identity#${pixelId}#neptune-throws`,
+                    pixelId,
+                    identityId: 'neptune-throws',
+                    response: {
+                        identityId: 'neptune-throws',
+                        traits: {
+                            emails: ['old@email.com'],
+                        },
+                    },
+                    updatedAt: new Date().toISOString(),
+                };
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+                mockInvokeFunction.mockRejectedValueOnce(new Error('Neptune invocation failed'));
+                const incomingIdentity = {
+                    identityId: 'neptune-throws',
+                    traits: {
+                        emails: ['old@email.com', 'new@email.com'],
+                    },
+                };
+                const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, incomingIdentity, lambdaArn);
+                expect(result.summary.didCallNeptune).toBe(true);
+                expect(result.summary.didWriteCache).toBe(false);
+                expect(result.summary.outcome).toBe(IDENTITY_CACHE_WITH_CACHING_OUTCOME.NEPTUNE_RESOLUTION_FAILED);
+                expect(result.identity).toBeDefined();
+                expect(result.identity?.identityId).toBe('neptune-throws');
+                expect(result.identity?.traits?.emails).toEqual(['old@email.com', 'new@email.com']);
+            });
+        });
+    });
+    describe('resolveCacheMissViaNeptune helper', () => {
+        describe('cache miss without discovered identity ID', () => {
+            it('should call Neptune with incoming identity when no discovered ID', async () => {
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
+                mockInvokeFunction.mockResolvedValueOnce({
+                    statusCode: 200,
+                    body: JSON.stringify({
+                        identity: {
+                            identityId: 'neptune-resolved-id',
+                            traits: { emails: ['test@email.com'] },
+                        },
+                    }),
+                });
+                const incomingIdentity = {
+                    identityId: 'incoming-id',
+                    traits: { emails: ['test@email.com'] },
+                };
+                const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, incomingIdentity, lambdaArn);
+                expect(mockInvokeFunction).toHaveBeenCalledWith(lambdaArn, expect.objectContaining({
+                    pixelId,
+                    context: expect.objectContaining({
+                        identity: expect.objectContaining({
+                            identityId: 'incoming-id',
+                        }),
+                    }),
+                }));
+                expect(result.summary.outcome).toBe(IDENTITY_CACHE_WITH_CACHING_OUTCOME.NEPTUNE_RESOLVED);
+                expect(result.summary.hasDiscoveredIdentityId).toBeUndefined();
+                expect(result.summary.writeReason).toBeUndefined();
+            });
+            it('should set state.didReadCache=true and state.didCallNeptune=true', async () => {
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
+                mockInvokeFunction.mockResolvedValueOnce({
+                    statusCode: 200,
+                    body: JSON.stringify({
+                        identity: { identityId: 'resolved', traits: {} },
+                    }),
+                });
+                const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, { identityId: 'test', traits: {} }, lambdaArn);
+                expect(result.summary.didReadCache).toBe(true);
+                expect(result.summary.didCallNeptune).toBe(true);
+            });
+        });
+        describe('email pointer discovery with discovered identity ID', () => {
+            it('should call Neptune with discovered identity ID when email lookup succeeds', async () => {
+                const incomingNoId = {
+                    traits: { emails: ['discovered@email.com'] },
+                };
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce({
+                    pk: `email#${pixelId}#discovered@email.com`,
+                    identityId: 'discovered-identity-id',
+                });
+                mockInvokeFunction.mockResolvedValueOnce({
+                    statusCode: 200,
+                    body: JSON.stringify({
+                        identity: {
+                            identityId: 'discovered-identity-id',
+                            traits: { emails: ['discovered@email.com', 'other@email.com'] },
+                        },
+                    }),
+                });
+                const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, incomingNoId, lambdaArn);
+                expect(result.identity?.identityId).toBe('discovered-identity-id');
+            });
+            it('should use incoming identity in Neptune call (not discovered ID)', async () => {
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce({
+                    pk: `email#${pixelId}#test@email.com`,
+                    identityId: 'discovered-from-email',
+                });
+                mockInvokeFunction.mockResolvedValueOnce({
+                    statusCode: 200,
+                    body: JSON.stringify({
+                        identity: {
+                            identityId: 'neptune-resolved',
+                            traits: { emails: ['test@email.com'] },
+                        },
+                    }),
+                });
+                await IdentityGatewayService.getIdentityWithCachingV2(pixelId, { traits: { emails: ['test@email.com'] } }, lambdaArn);
+                expect(mockInvokeFunction).toHaveBeenCalledWith(lambdaArn, expect.objectContaining({
+                    pixelId,
+                    context: expect.objectContaining({
+                        identity: expect.objectContaining({
+                            traits: { emails: ['test@email.com'] },
+                        }),
+                    }),
+                }));
+            });
+        });
+        describe('Neptune resolution success → write-back', () => {
+            it('should write to cache when Neptune returns identity', async () => {
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
+                mockInvokeFunction.mockResolvedValueOnce({
+                    statusCode: 200,
+                    body: JSON.stringify({
+                        identity: {
+                            identityId: 'neptune-success',
+                            traits: { emails: ['test@email.com'], phones: ['555-1234'] },
+                        },
+                    }),
+                });
+                const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, { identityId: 'incoming', traits: { emails: ['test@email.com'] } }, lambdaArn);
+                expect(result.summary.didWriteCache).toBe(false);
+                expect(result.summary.outcome).toBe(IDENTITY_CACHE_WITH_CACHING_OUTCOME.NEPTUNE_RESOLVED);
+                expect(mockedDynamoDbClient.safeBatchWrite).not.toHaveBeenCalled();
+            });
+            it('should set resolvedIdentity to Neptune response', async () => {
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
+                mockInvokeFunction.mockResolvedValueOnce({
+                    statusCode: 200,
+                    body: JSON.stringify({
+                        identity: {
+                            identityId: 'from-neptune',
+                            traits: { emails: ['neptune@email.com'] },
+                        },
+                    }),
+                });
+                const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, { identityId: 'original', traits: { emails: ['original@email.com'] } }, lambdaArn);
+                expect(result.identity?.identityId).toBe('from-neptune');
+                expect(result.identity?.traits?.emails).toContain('neptune@email.com');
+            });
+            it('should include traitChanges with "no cached identity" reason', async () => {
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
+                mockInvokeFunction.mockResolvedValueOnce({
+                    statusCode: 200,
+                    body: JSON.stringify({
+                        identity: {
+                            identityId: 'new-identity',
+                            traits: { emails: ['new@email.com'] },
+                        },
+                    }),
+                });
+                const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, { identityId: 'incoming', traits: { emails: ['incoming@email.com'] } }, lambdaArn);
+                expect(result.summary.traitChanges).toEqual({
+                    reason: { resolved: 'no cached identity' },
+                });
+            });
+        });
+        describe('Neptune resolution failure → fallback to incoming', () => {
+            it('should fallback to incoming identity when Neptune fails', async () => {
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
+                mockInvokeFunction.mockRejectedValueOnce(new Error('Neptune unavailable'));
+                const incomingIdentity = {
+                    identityId: 'fallback-incoming',
+                    traits: { emails: ['fallback@email.com'] },
+                };
+                const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, incomingIdentity, lambdaArn);
+                expect(result.summary.outcome).toBe(IDENTITY_CACHE_WITH_CACHING_OUTCOME.NEPTUNE_RESOLUTION_FAILED);
+                expect(result.summary.didFallbackToIncoming).toBe(true);
+                expect(result.identity?.identityId).toBe('fallback-incoming');
+            });
+            it('should set didWriteCache=false when Neptune fails', async () => {
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
+                mockInvokeFunction.mockRejectedValueOnce(new Error('Lambda timeout'));
+                const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, { identityId: 'test', traits: {} }, lambdaArn);
+                expect(result.summary.didWriteCache).toBe(false);
+                expect(mockedDynamoDbClient.safeBatchWrite).not.toHaveBeenCalled();
+            });
+            it('should use identityForNeptune (with discovered ID) as fallback when available', async () => {
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce({
+                    pk: `email#${pixelId}#test@email.com`,
+                    identityId: 'discovered-id',
+                });
+                mockInvokeFunction.mockRejectedValueOnce(new Error('Neptune error'));
+                const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, { traits: { emails: ['test@email.com'] } }, lambdaArn);
+                expect(result.summary.didFallbackToIncoming).toBe(true);
+                expect(result.identity?.identityId).toBeUndefined();
+                expect(result.identity?.traits?.emails).toContain('test@email.com');
+            });
+        });
+        describe('skipCacheWrite=true behavior', () => {
+            it('should NOT write to cache when skipCacheWrite=true', async () => {
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
+                mockInvokeFunction.mockResolvedValueOnce({
+                    statusCode: 200,
+                    body: JSON.stringify({
+                        identity: {
+                            identityId: 'skip-write-identity',
+                            traits: { emails: ['test@email.com'] },
+                        },
+                    }),
+                });
+                const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, { identityId: 'incoming', traits: { emails: ['test@email.com'] } }, lambdaArn, { skipCacheWrite: true });
+                expect(result.summary.didWriteCache).toBe(false);
+                expect(mockedDynamoDbClient.safeBatchWrite).not.toHaveBeenCalled();
+                expect(result.identity?.identityId).toBe('skip-write-identity');
+                expect(result.summary.outcome).toBe(IDENTITY_CACHE_WITH_CACHING_OUTCOME.NEPTUNE_RESOLVED);
+            });
+            it('should still call Neptune when skipCacheWrite=true', async () => {
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
+                mockInvokeFunction.mockResolvedValueOnce({
+                    statusCode: 200,
+                    body: JSON.stringify({
+                        identity: { identityId: 'resolved', traits: {} },
+                    }),
+                });
+                await IdentityGatewayService.getIdentityWithCachingV2(pixelId, { identityId: 'test', traits: {} }, lambdaArn, { skipCacheWrite: true });
+                expect(mockInvokeFunction).toHaveBeenCalled();
+            });
+        });
+    });
+    describe('resolveStaleViaNeptune helper', () => {
+        describe('Neptune resolution success with changes → write-back', () => {
+            it('should write to cache when Neptune returns different identity', async () => {
+                const cachedResponse = {
+                    pk: `identity#${pixelId}#stale-changes`,
+                    pixelId,
+                    identityId: 'stale-changes',
+                    response: {
+                        identityId: 'stale-changes',
+                        traits: { emails: ['old@email.com'] },
+                    },
+                    updatedAt: new Date().toISOString(),
+                };
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+                mockInvokeFunction.mockResolvedValueOnce({
+                    statusCode: 200,
+                    body: JSON.stringify({
+                        identity: {
+                            identityId: 'stale-changes',
+                            traits: { emails: ['old@email.com', 'new@email.com'], phones: ['555-new'] },
+                        },
+                    }),
+                });
+                const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, { identityId: 'stale-changes', traits: { emails: ['old@email.com', 'new@email.com'] } }, lambdaArn);
+                expect(result.summary.didWriteCache).toBe(false);
+                expect(result.summary.outcome).toBe(IDENTITY_CACHE_WITH_CACHING_OUTCOME.NEPTUNE_RESOLVED);
+                expect(mockedDynamoDbClient.safeBatchWrite).not.toHaveBeenCalled();
+            });
+            it('should compute traitChanges between cached and Neptune identity', async () => {
+                const cachedResponse = {
+                    pk: `identity#${pixelId}#trait-changes`,
+                    pixelId,
+                    identityId: 'trait-changes',
+                    response: {
+                        identityId: 'trait-changes',
+                        traits: {
+                            emails: ['old@email.com'],
+                            phones: ['555-old'],
+                        },
+                    },
+                    updatedAt: new Date().toISOString(),
+                };
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+                mockInvokeFunction.mockResolvedValueOnce({
+                    statusCode: 200,
+                    body: JSON.stringify({
+                        identity: {
+                            identityId: 'trait-changes',
+                            traits: {
+                                emails: ['old@email.com', 'new@email.com'],
+                                phones: ['555-old', '555-new'],
+                            },
+                        },
+                    }),
+                });
+                const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, { identityId: 'trait-changes', traits: { emails: ['old@email.com', 'new@email.com'] } }, lambdaArn);
+                expect(result.summary.traitChanges).toBeDefined();
+                expect(result.summary.traitChanges?.emails).toBeDefined();
+            });
+        });
+        describe('Neptune resolution success without changes → skip write', () => {
+            it('should skip cache write when Neptune matches cached', async () => {
+                const cachedResponse = {
+                    pk: `identity#${pixelId}#no-changes`,
+                    pixelId,
+                    identityId: 'no-changes',
+                    response: {
+                        identityId: 'no-changes',
+                        traits: { emails: ['same@email.com'] },
+                    },
+                    updatedAt: new Date().toISOString(),
+                };
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+                mockInvokeFunction.mockResolvedValueOnce({
+                    statusCode: 200,
+                    body: JSON.stringify({
+                        identity: {
+                            identityId: 'no-changes',
+                            traits: { emails: ['same@email.com'] },
+                        },
+                    }),
+                });
+                const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, { identityId: 'no-changes', traits: { emails: ['same@email.com', 'thought-new@email.com'] } }, lambdaArn);
+                expect(result.summary.didCallNeptune).toBe(true);
+                expect(result.summary.didWriteCache).toBe(false);
+                expect(result.summary.outcome).toBe(IDENTITY_CACHE_WITH_CACHING_OUTCOME.NEPTUNE_RESOLVED);
+                expect(mockedDynamoDbClient.safeBatchWrite).not.toHaveBeenCalled();
+            });
+            it('should still return Neptune identity even when skipping write', async () => {
+                const cachedResponse = {
+                    pk: `identity#${pixelId}#return-identity`,
+                    pixelId,
+                    identityId: 'return-identity',
+                    response: {
+                        identityId: 'return-identity',
+                        traits: { emails: ['cached@email.com'] },
+                    },
+                    updatedAt: new Date().toISOString(),
+                };
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+                mockInvokeFunction.mockResolvedValueOnce({
+                    statusCode: 200,
+                    body: JSON.stringify({
+                        identity: {
+                            identityId: 'return-identity',
+                            traits: { emails: ['cached@email.com'] },
+                        },
+                    }),
+                });
+                const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, { identityId: 'return-identity', traits: { emails: ['cached@email.com', 'extra@email.com'] } }, lambdaArn);
+                expect(result.identity?.identityId).toBe('return-identity');
+            });
+            it('should strip address timestamps for comparison', async () => {
+                const now = Date.now();
+                const cachedResponse = {
+                    pk: `identity#${pixelId}#addr-timestamp`,
+                    pixelId,
+                    identityId: 'addr-timestamp',
+                    response: {
+                        identityId: 'addr-timestamp',
+                        traits: {
+                            emails: ['test@email.com'],
+                            addresses: [{ city: 'NYC', cra: now - 1000, upa: now - 500 }],
+                        },
+                    },
+                    updatedAt: new Date().toISOString(),
+                };
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+                mockInvokeFunction.mockResolvedValueOnce({
+                    statusCode: 200,
+                    body: JSON.stringify({
+                        identity: {
+                            identityId: 'addr-timestamp',
+                            traits: {
+                                emails: ['test@email.com'],
+                                addresses: [{ city: 'NYC', cra: now, upa: now }],
+                            },
+                        },
+                    }),
+                });
+                const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, { identityId: 'addr-timestamp', traits: { emails: ['test@email.com', 'new@email.com'] } }, lambdaArn);
+                expect(result.summary.didWriteCache).toBe(false);
+                expect(result.summary.outcome).toBe(IDENTITY_CACHE_WITH_CACHING_OUTCOME.NEPTUNE_RESOLVED);
+            });
+        });
+        describe('Neptune resolution failure', () => {
+            it('should return NEPTUNE_RESOLUTION_FAILED when Neptune fails', async () => {
+                const cachedResponse = {
+                    pk: `identity#${pixelId}#neptune-fail`,
+                    pixelId,
+                    identityId: 'neptune-fail',
+                    response: {
+                        identityId: 'neptune-fail',
+                        traits: { emails: ['cached@email.com'] },
+                    },
+                    updatedAt: new Date().toISOString(),
+                };
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+                mockInvokeFunction.mockRejectedValueOnce(new Error('Lambda invocation failed'));
+                const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, { identityId: 'neptune-fail', traits: { emails: ['cached@email.com', 'new@email.com'] } }, lambdaArn);
+                expect(result.summary.didCallNeptune).toBe(true);
+                expect(result.summary.outcome).toBe(IDENTITY_CACHE_WITH_CACHING_OUTCOME.NEPTUNE_RESOLUTION_FAILED);
+            });
+            it('should not write to cache when Neptune fails', async () => {
+                const cachedResponse = {
+                    pk: `identity#${pixelId}#no-write-fail`,
+                    pixelId,
+                    identityId: 'no-write-fail',
+                    response: {
+                        identityId: 'no-write-fail',
+                        traits: { emails: ['test@email.com'] },
+                    },
+                    updatedAt: new Date().toISOString(),
+                };
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+                mockInvokeFunction.mockRejectedValueOnce(new Error('Network error'));
+                const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, { identityId: 'no-write-fail', traits: { emails: ['test@email.com', 'extra@email.com'] } }, lambdaArn);
+                expect(result.summary.didWriteCache).toBe(false);
+                expect(mockedDynamoDbClient.safeBatchWrite).not.toHaveBeenCalled();
+            });
+            it('should still return merged identity when Neptune fails', async () => {
+                const cachedResponse = {
+                    pk: `identity#${pixelId}#merged-on-fail`,
+                    pixelId,
+                    identityId: 'merged-on-fail',
+                    response: {
+                        identityId: 'merged-on-fail',
+                        traits: {
+                            emails: ['cached@email.com'],
+                            phones: ['555-cached'],
+                        },
+                    },
+                    updatedAt: new Date().toISOString(),
+                };
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+                mockInvokeFunction.mockRejectedValueOnce(new Error('Timeout'));
+                const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, { identityId: 'merged-on-fail', traits: { emails: ['cached@email.com', 'new@email.com'] } }, lambdaArn);
+                expect(result.identity).toBeDefined();
+            });
+        });
+        describe('skipCacheWrite=true behavior', () => {
+            it('should NOT write to cache when skipCacheWrite=true even with changes', async () => {
+                const cachedResponse = {
+                    pk: `identity#${pixelId}#skip-stale`,
+                    pixelId,
+                    identityId: 'skip-stale',
+                    response: {
+                        identityId: 'skip-stale',
+                        traits: { emails: ['old@email.com'] },
+                    },
+                    updatedAt: new Date().toISOString(),
+                };
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+                mockInvokeFunction.mockResolvedValueOnce({
+                    statusCode: 200,
+                    body: JSON.stringify({
+                        identity: {
+                            identityId: 'skip-stale',
+                            traits: { emails: ['old@email.com', 'new@email.com'], phones: ['555-new'] },
+                        },
+                    }),
+                });
+                const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, { identityId: 'skip-stale', traits: { emails: ['old@email.com', 'new@email.com'] } }, lambdaArn, { skipCacheWrite: true });
+                expect(result.summary.didWriteCache).toBe(false);
+                expect(mockedDynamoDbClient.safeBatchWrite).not.toHaveBeenCalled();
+                expect(result.summary.outcome).toBe(IDENTITY_CACHE_WITH_CACHING_OUTCOME.NEPTUNE_RESOLVED);
+            });
+            it('should still call Neptune when skipCacheWrite=true', async () => {
+                const cachedResponse = {
+                    pk: `identity#${pixelId}#call-neptune-skip`,
+                    pixelId,
+                    identityId: 'call-neptune-skip',
+                    response: {
+                        identityId: 'call-neptune-skip',
+                        traits: { emails: ['test@email.com'] },
+                    },
+                    updatedAt: new Date().toISOString(),
+                };
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+                mockInvokeFunction.mockResolvedValueOnce({
+                    statusCode: 200,
+                    body: JSON.stringify({
+                        identity: {
+                            identityId: 'call-neptune-skip',
+                            traits: { emails: ['test@email.com', 'added@email.com'] },
+                        },
+                    }),
+                });
+                await IdentityGatewayService.getIdentityWithCachingV2(pixelId, { identityId: 'call-neptune-skip', traits: { emails: ['test@email.com', 'added@email.com'] } }, lambdaArn, { skipCacheWrite: true });
+                expect(mockInvokeFunction).toHaveBeenCalled();
+            });
+            it('should return Neptune identity when skipCacheWrite=true', async () => {
+                const cachedResponse = {
+                    pk: `identity#${pixelId}#return-skip`,
+                    pixelId,
+                    identityId: 'return-skip',
+                    response: {
+                        identityId: 'return-skip',
+                        traits: { emails: ['cached@email.com'] },
+                    },
+                    updatedAt: new Date().toISOString(),
+                };
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
+                mockInvokeFunction.mockResolvedValueOnce({
+                    statusCode: 200,
+                    body: JSON.stringify({
+                        identity: {
+                            identityId: 'return-skip',
+                            traits: {
+                                emails: ['cached@email.com', 'neptune@email.com'],
+                                phones: ['555-neptune'],
+                            },
+                        },
+                    }),
+                });
+                const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, { identityId: 'return-skip', traits: { emails: ['cached@email.com', 'neptune@email.com'] } }, lambdaArn, { skipCacheWrite: true });
+                expect(result.identity?.traits?.phones).toContain('555-neptune');
+            });
+        });
+    });
 });
 //# sourceMappingURL=identity-gateway-service.spec.js.map