@adtrackify/at-service-common 4.0.13 → 4.0.15

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

@@ -1,2168 +0,0 @@
-const mockInvokeFunction = jest.fn();
-const mockBuildAndSendMessage = jest.fn();
-const mockSQSClientConstructor = jest.fn();
-jest.mock('../../clients/index.js', () => ({
-    DynamoDbClient: {
-        safeGet: jest.fn(),
-        safePut: jest.fn(),
-        safeDelete: jest.fn(),
-        safeBatchGet: jest.fn(),
-        safeBatchWrite: jest.fn(),
-        safeQueryByGSI: jest.fn(),
-        batchWrite: jest.fn(),
-    },
-    LambdaInvokeClient: jest.fn().mockImplementation(() => ({
-        invokeFunction: mockInvokeFunction,
-    })),
-    SQSClient: jest.fn().mockImplementation((_region, _accountId, _queueName) => {
-        mockSQSClientConstructor(_region, _accountId, _queueName);
-        return {
-            buildAndSendMessage: mockBuildAndSendMessage,
-            queueUrl: `https://sqs.${_region}.amazonaws.com/${_accountId}/${_queueName}`,
-        };
-    }),
-}));
-jest.mock('../../helpers/index.js', () => ({
-    Logger: {
-        debug: jest.fn(),
-        info: jest.fn(),
-        warn: jest.fn(),
-        error: jest.fn(),
-    },
-}));
-import { IdentityGatewayService, } from '../../services/db/identity-cache-dynamodb-service/identity-gateway-service.js';
-import { IDENTITY_CACHE_WITH_CACHING_OUTCOME, } from '../../services/db/identity-cache-dynamodb-service/types.js';
-import { DynamoDbClient, SQSClient } from '../../clients/index.js';
-import { Logger } from '../../helpers/index.js';
-const mockedDynamoDbClient = DynamoDbClient;
-const mockedLogger = Logger;
-const mockedSQSClient = SQSClient;
-describe('IdentityGatewayService new features', () => {
-    const pixelId = 'pixel123';
-    const lambdaArn = 'arn:aws:lambda:us-east-1:123456789:function:identity-private';
-    beforeEach(() => {
-        jest.clearAllMocks();
-        mockedDynamoDbClient.safeGet.mockReset();
-        mockedDynamoDbClient.safePut.mockReset();
-        mockedDynamoDbClient.safeDelete.mockReset();
-        mockedDynamoDbClient.safeBatchGet.mockReset();
-        mockedDynamoDbClient.safeBatchWrite.mockReset();
-        mockedDynamoDbClient.safeQueryByGSI.mockReset();
-        mockedDynamoDbClient.batchWrite.mockReset();
-        mockInvokeFunction.mockReset();
-        mockBuildAndSendMessage.mockReset();
-        mockSQSClientConstructor.mockReset();
-        mockedSQSClient.mockClear();
-        IdentityGatewayService.lambdaInvokeClient = undefined;
-        IdentityGatewayService.sqsClient = undefined;
-        IdentityGatewayService.sqsQueueUrl = undefined;
-    });
-    describe('configure()', () => {
-        it('should configure with direct queue URL', () => {
-            const options = {
-                asyncUpdateQueueUrl: 'https://sqs.us-east-1.amazonaws.com/123456789/test-queue',
-            };
-            IdentityGatewayService.configure(options);
-            expect(IdentityGatewayService.sqsQueueUrl).toBe(options.asyncUpdateQueueUrl);
-        });
-        it('should configure with region/accountId/queueName', () => {
-            const options = {
-                awsRegion: 'us-east-1',
-                awsAccountId: '123456789',
-                asyncUpdateQueueName: 'identity-async-queue',
-            };
-            IdentityGatewayService.configure(options);
-            expect(mockSQSClientConstructor).toHaveBeenCalledWith('us-east-1', '123456789', 'identity-async-queue');
-            expect(IdentityGatewayService.sqsClient).toBeDefined();
-            expect(IdentityGatewayService.sqsQueueUrl).toBeDefined();
-        });
-        it('should fallback to environment variable for queue name', () => {
-            const originalEnv = process.env.IDENTIFY_ASYNC_UPDATE_QUEUE_NAME;
-            process.env.IDENTIFY_ASYNC_UPDATE_QUEUE_NAME = 'env-queue-name';
-            try {
-                const options = {
-                    awsRegion: 'us-west-2',
-                    awsAccountId: '987654321',
-                };
-                IdentityGatewayService.configure(options);
-                expect(mockSQSClientConstructor).toHaveBeenCalledWith('us-west-2', '987654321', 'env-queue-name');
-            }
-            finally {
-                if (originalEnv !== undefined) {
-                    process.env.IDENTIFY_ASYNC_UPDATE_QUEUE_NAME = originalEnv;
-                }
-                else {
-                    delete process.env.IDENTIFY_ASYNC_UPDATE_QUEUE_NAME;
-                }
-            }
-        });
-        it('should not configure SQS when region/accountId provided but no queue name', () => {
-            const originalEnv = process.env.IDENTIFY_ASYNC_UPDATE_QUEUE_NAME;
-            delete process.env.IDENTIFY_ASYNC_UPDATE_QUEUE_NAME;
-            try {
-                const options = {
-                    awsRegion: 'us-east-1',
-                    awsAccountId: '123456789',
-                };
-                IdentityGatewayService.configure(options);
-                expect(mockSQSClientConstructor).not.toHaveBeenCalled();
-                expect(IdentityGatewayService.sqsClient).toBeUndefined();
-            }
-            finally {
-                if (originalEnv !== undefined) {
-                    process.env.IDENTIFY_ASYNC_UPDATE_QUEUE_NAME = originalEnv;
-                }
-            }
-        });
-        it('should not configure SQS when only region provided', () => {
-            const options = {
-                awsRegion: 'us-east-1',
-            };
-            IdentityGatewayService.configure(options);
-            expect(mockSQSClientConstructor).not.toHaveBeenCalled();
-            expect(IdentityGatewayService.sqsClient).toBeUndefined();
-        });
-    });
-    describe('enqueueAsyncIdentityUpdate()', () => {
-        const testIdentity = {
-            identityId: 'identity456',
-            traits: { emails: ['test@email.com'] },
-        };
-        const testContext = {
-            identity: testIdentity,
-        };
-        it('should return error result when SQS client is not configured', async () => {
-            const result = await IdentityGatewayService.enqueueAsyncIdentityUpdate({
-                pixelId,
-                identity: testIdentity,
-                context: testContext,
-                reason: 'test reason',
-                eventId: 'event123',
-            });
-            expect(result.success).toBe(false);
-            expect(result.error).toBe('SQS client not configured');
-            expect(result.messageId).toBeUndefined();
-            expect(mockedLogger.warn).toHaveBeenCalledWith('IdentityGateway - enqueueAsyncIdentityUpdate: SQS client not configured', expect.objectContaining({
-                pixelId,
-                identityId: testIdentity.identityId,
-                reason: 'test reason',
-                eventId: 'event123',
-            }));
-        });
-        it('should successfully enqueue message when SQS client is configured', async () => {
-            IdentityGatewayService.configure({
-                awsRegion: 'us-east-1',
-                awsAccountId: '123456789',
-                asyncUpdateQueueName: 'test-queue',
-            });
-            mockBuildAndSendMessage.mockResolvedValueOnce({
-                MessageId: 'sqs-message-id-123',
-            });
-            const result = await IdentityGatewayService.enqueueAsyncIdentityUpdate({
-                pixelId,
-                identity: testIdentity,
-                context: testContext,
-                reason: 'stale cache traits',
-                eventId: 'event456',
-            });
-            expect(result.success).toBe(true);
-            expect(result.messageId).toBe('sqs-message-id-123');
-            expect(result.error).toBeUndefined();
-            expect(mockBuildAndSendMessage).toHaveBeenCalledWith('identify.updateAsync', expect.objectContaining({
-                pixelId,
-                incomingIdentityId: testIdentity.identityId,
-                context: testContext,
-            }));
-            expect(mockedLogger.debug).toHaveBeenCalledWith('IdentityGateway - enqueueAsyncIdentityUpdate: message sent', expect.objectContaining({
-                pixelId,
-                identityId: testIdentity.identityId,
-                reason: 'stale cache traits',
-                eventId: 'event456',
-                sqsMessageId: 'sqs-message-id-123',
-            }));
-        });
-        it('should fail open with logging when SQS send fails', async () => {
-            IdentityGatewayService.configure({
-                awsRegion: 'us-east-1',
-                awsAccountId: '123456789',
-                asyncUpdateQueueName: 'test-queue',
-            });
-            mockBuildAndSendMessage.mockRejectedValueOnce(new Error('SQS send failed'));
-            const result = await IdentityGatewayService.enqueueAsyncIdentityUpdate({
-                pixelId,
-                identity: testIdentity,
-                context: testContext,
-                reason: 'test reason',
-                eventId: 'event789',
-            });
-            expect(result.success).toBe(false);
-            expect(result.error).toBe('SQS send failed');
-            expect(result.messageId).toBeUndefined();
-            expect(mockedLogger.warn).toHaveBeenCalledWith('IdentityGateway - enqueueAsyncIdentityUpdate: failed to enqueue (failing open)', expect.objectContaining({
-                error: expect.any(Error),
-                errorMessage: 'SQS send failed',
-                pixelId,
-                identityId: testIdentity.identityId,
-                reason: 'test reason',
-                eventId: 'event789',
-            }));
-        });
-        it('should build message shape matching IdentifyAsyncUpdateMessage interface', async () => {
-            IdentityGatewayService.configure({
-                awsRegion: 'us-east-1',
-                awsAccountId: '123456789',
-                asyncUpdateQueueName: 'test-queue',
-            });
-            mockBuildAndSendMessage.mockResolvedValueOnce({ MessageId: 'test-id' });
-            const identity = {
-                identityId: 'id-xyz',
-                traits: { emails: ['user@example.com'], userIds: ['user-1'] },
-            };
-            const context = { identity };
-            await IdentityGatewayService.enqueueAsyncIdentityUpdate({
-                pixelId: 'pixel-abc',
-                identity,
-                context,
-                reason: 'test',
-            });
-            const messageArg = mockBuildAndSendMessage.mock.calls[0][1];
-            expect(messageArg).toEqual({
-                pixelId: 'pixel-abc',
-                incomingIdentityId: 'id-xyz',
-                context,
-            });
-        });
-        it('should return error when identity has no identityId', async () => {
-            IdentityGatewayService.configure({
-                awsRegion: 'us-east-1',
-                awsAccountId: '123456789',
-                asyncUpdateQueueName: 'test-queue',
-            });
-            const identityWithoutId = {
-                traits: { emails: ['anon@example.com'] },
-            };
-            const context = { identity: identityWithoutId };
-            const result = await IdentityGatewayService.enqueueAsyncIdentityUpdate({
-                pixelId,
-                identity: identityWithoutId,
-                context,
-                reason: 'anonymous identity',
-            });
-            expect(result.success).toBe(false);
-            expect(result.error).toBe('Missing required pixelId or identityId');
-            expect(mockBuildAndSendMessage).not.toHaveBeenCalled();
-        });
-        it('should handle optional eventId parameter', async () => {
-            IdentityGatewayService.configure({
-                awsRegion: 'us-east-1',
-                awsAccountId: '123456789',
-                asyncUpdateQueueName: 'test-queue',
-            });
-            mockBuildAndSendMessage.mockResolvedValueOnce({ MessageId: 'test-id' });
-            await IdentityGatewayService.enqueueAsyncIdentityUpdate({
-                pixelId,
-                identity: testIdentity,
-                context: testContext,
-                reason: 'test',
-            });
-            expect(mockedLogger.debug).toHaveBeenCalledWith('IdentityGateway - enqueueAsyncIdentityUpdate: message sent', expect.objectContaining({
-                eventId: undefined,
-            }));
-        });
-    });
-    describe('getIdentityWithCachingV2() with skipCacheWrite option', () => {
-        const incomingIdentity = {
-            identityId: 'identity456',
-            traits: { emails: ['test@email.com'] },
-        };
-        describe('default behavior (no options)', () => {
-            it('should write to cache when Neptune returns new identity', async () => {
-                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
-                mockInvokeFunction.mockResolvedValueOnce({
-                    statusCode: 200,
-                    body: JSON.stringify({
-                        identity: {
-                            identityId: 'resolved-identity',
-                            traits: { emails: ['test@email.com', 'resolved@email.com'] },
-                        },
-                    }),
-                });
-                const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, incomingIdentity, lambdaArn);
-                expect(result.summary.didWriteCache).toBe(false);
-                expect(mockedDynamoDbClient.safeBatchWrite).not.toHaveBeenCalled();
-            });
-        });
-        describe('skipCacheWrite: false', () => {
-            it('should write to cache (same as default)', async () => {
-                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
-                mockInvokeFunction.mockResolvedValueOnce({
-                    statusCode: 200,
-                    body: JSON.stringify({
-                        identity: {
-                            identityId: 'resolved-identity',
-                            traits: { emails: ['test@email.com'] },
-                        },
-                    }),
-                });
-                const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, incomingIdentity, lambdaArn, { skipCacheWrite: false });
-                expect(result.summary.didWriteCache).toBe(false);
-                expect(mockedDynamoDbClient.safeBatchWrite).not.toHaveBeenCalled();
-            });
-        });
-        describe('skipCacheWrite: true', () => {
-            it('should NOT write to cache on Neptune write-back path', async () => {
-                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
-                mockInvokeFunction.mockResolvedValueOnce({
-                    statusCode: 200,
-                    body: JSON.stringify({
-                        identity: {
-                            identityId: 'resolved-identity',
-                            traits: { emails: ['test@email.com', 'resolved@email.com'] },
-                        },
-                    }),
-                });
-                const result = await IdentityGatewayService.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_RESOLVED);
-                expect(mockedDynamoDbClient.safeBatchWrite).not.toHaveBeenCalled();
-            });
-            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,
-                    identityId: 'identity456',
-                    response: {
-                        identityId: 'identity456',
-                        traits: {
-                            emails: ['test@email.com'],
-                            addresses: [{ city: 'Old City', upa: 1704067200000 }],
-                        },
-                    },
-                    updatedAt: new Date().toISOString(),
-                };
-                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
-                const identityWithNewAddress = {
-                    identityId: 'identity456',
-                    traits: {
-                        emails: ['test@email.com'],
-                        addresses: [{ city: 'New City', upa: 1717200000000 }],
-                    },
-                };
-                const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, identityWithNewAddress, lambdaArn, { skipCacheWrite: true });
-                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 () => {
-                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
-                mockInvokeFunction.mockResolvedValueOnce({
-                    statusCode: 200,
-                    body: JSON.stringify({
-                        identity: {
-                            identityId: 'neptune-resolved-id',
-                            traits: { emails: ['test@email.com', 'new@email.com'] },
-                        },
-                    }),
-                });
-                const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, incomingIdentity, lambdaArn, { skipCacheWrite: true });
-                expect(result.identity).toBeDefined();
-                expect(result.identity?.identityId).toBe('neptune-resolved-id');
-                expect(result.identity?.traits?.emails).toContain('new@email.com');
-            });
-            it('should return fresh cache hit without writing (skipCacheWrite irrelevant for hits)', async () => {
-                const cachedResponse = {
-                    pk: `identity#${pixelId}#identity456`,
-                    pixelId,
-                    identityId: 'identity456',
-                    response: {
-                        identityId: 'identity456',
-                        traits: { emails: ['test@email.com'] },
-                    },
-                    updatedAt: new Date().toISOString(),
-                };
-                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
-                const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, incomingIdentity, lambdaArn, { skipCacheWrite: true });
-                expect(result.summary.outcome).toBe(IDENTITY_CACHE_WITH_CACHING_OUTCOME.FRESH_CACHE_HIT);
-                expect(result.summary.didWriteCache).toBe(false);
-                expect(mockInvokeFunction).not.toHaveBeenCalled();
-                expect(mockedDynamoDbClient.safeBatchWrite).not.toHaveBeenCalled();
-            });
-        });
-        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,
-                    identityId: 'identity456',
-                    response: {
-                        identityId: 'identity456',
-                        traits: {
-                            emails: ['test@email.com'],
-                            addresses: [{ city: 'Old City', upa: 1704067200000 }],
-                        },
-                    },
-                    updatedAt: new Date().toISOString(),
-                };
-                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedResponse);
-                const identityWithNewAddress = {
-                    identityId: 'identity456',
-                    traits: {
-                        emails: ['test@email.com'],
-                        addresses: [{ city: 'New City', upa: 1717200000000 }],
-                    },
-                };
-                const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, identityWithNewAddress, lambdaArn, { skipCacheWrite: false });
-                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', () => {
-        it('should return invalid input when pixelId is undefined', async () => {
-            const result = await IdentityGatewayService.getIdentityWithCachingV2(undefined, { identityId: 'test' }, lambdaArn);
-            expect(result.identity).toBeUndefined();
-            expect(result.summary.outcome).toBe(IDENTITY_CACHE_WITH_CACHING_OUTCOME.INVALID_INPUT);
-            expect(result.summary.didReadCache).toBe(false);
-            expect(result.summary.didWriteCache).toBe(false);
-        });
-        it('should return invalid input when incomingIdentity is null', async () => {
-            const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, null, lambdaArn);
-            expect(result.identity).toBeUndefined();
-            expect(result.summary.outcome).toBe(IDENTITY_CACHE_WITH_CACHING_OUTCOME.INVALID_INPUT);
-        });
-        it('should return invalid input when both pixelId and identity are missing', async () => {
-            const result = await IdentityGatewayService.getIdentityWithCachingV2('', undefined, lambdaArn);
-            expect(result.identity).toBeUndefined();
-            expect(result.summary.outcome).toBe(IDENTITY_CACHE_WITH_CACHING_OUTCOME.INVALID_INPUT);
-        });
-        it('should gracefully fallback when cache read fails (fail-open pattern)', async () => {
-            mockedDynamoDbClient.safeGet.mockRejectedValueOnce(new Error('Unexpected DynamoDB error'));
-            mockInvokeFunction.mockResolvedValueOnce({
-                statusCode: 200,
-                body: JSON.stringify({
-                    identity: {
-                        identityId: 'neptune-resolved',
-                        traits: { emails: ['test@email.com'] },
-                    },
-                }),
-            });
-            const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, { identityId: 'test-id', traits: { emails: ['test@email.com'] } }, lambdaArn);
-            expect(result.identity).toBeDefined();
-            expect(result.identity?.identityId).toBe('neptune-resolved');
-            expect(result.summary.didReadCache).toBe(true);
-            expect(result.summary.didCallNeptune).toBe(true);
-        });
-        it('should reject identity with undefined identityId in enqueue', async () => {
-            IdentityGatewayService.configure({
-                awsRegion: 'us-east-1',
-                awsAccountId: '123456789',
-                asyncUpdateQueueName: 'test-queue',
-            });
-            const identity = { traits: { emails: ['test@email.com'] } };
-            const context = { identity };
-            const result = await IdentityGatewayService.enqueueAsyncIdentityUpdate({
-                pixelId,
-                identity,
-                context,
-                reason: 'anonymous user',
-            });
-            expect(result.success).toBe(false);
-            expect(result.error).toBe('Missing required pixelId or identityId');
-            expect(mockBuildAndSendMessage).not.toHaveBeenCalled();
-            expect(mockedLogger.warn).toHaveBeenCalledWith('IdentityGateway - enqueueAsyncIdentityUpdate: missing required params', expect.objectContaining({
-                pixelId,
-                identityId: undefined,
-            }));
-        });
-    });
-    describe('safeWriteBackToCache behavior with skipCacheWrite', () => {
-        it('should not call safeWriteBackToCache when skipCacheWrite is true and Neptune returns new identity', async () => {
-            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
-            mockInvokeFunction.mockResolvedValueOnce({
-                statusCode: 200,
-                body: JSON.stringify({
-                    identity: {
-                        identityId: 'new-resolved-identity',
-                        traits: { emails: ['test@email.com'] },
-                    },
-                }),
-            });
-            await IdentityGatewayService.getIdentityWithCachingV2(pixelId, { identityId: 'original-id', traits: { emails: ['test@email.com'] } }, lambdaArn, { skipCacheWrite: true });
-            expect(mockedDynamoDbClient.safeBatchWrite).not.toHaveBeenCalled();
-        });
-        it('should call safeWriteBackToCache when skipCacheWrite is false and Neptune returns new identity', async () => {
-            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
-            mockInvokeFunction.mockResolvedValueOnce({
-                statusCode: 200,
-                body: JSON.stringify({
-                    identity: {
-                        identityId: 'new-resolved-identity',
-                        traits: { emails: ['test@email.com'] },
-                    },
-                }),
-            });
-            await IdentityGatewayService.getIdentityWithCachingV2(pixelId, { identityId: 'original-id', traits: { emails: ['test@email.com'] } }, lambdaArn, { skipCacheWrite: false });
-            expect(mockedDynamoDbClient.safeBatchWrite).not.toHaveBeenCalled();
-        });
-    });
-    describe('summary fields consistency', () => {
-        it('should include all required summary fields in getIdentityWithCachingV2 result', async () => {
-            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
-            mockInvokeFunction.mockResolvedValueOnce({
-                statusCode: 200,
-                body: JSON.stringify({
-                    identity: {
-                        identityId: 'resolved-id',
-                        traits: { emails: ['test@email.com'] },
-                    },
-                }),
-            });
-            const result = await IdentityGatewayService.getIdentityWithCachingV2(pixelId, { identityId: 'incoming-id', traits: { emails: ['test@email.com'] } }, lambdaArn, { skipCacheWrite: true });
-            expect(result.summary).toEqual(expect.objectContaining({
-                outcome: expect.any(String),
-                pixelId,
-                identityId: 'resolved-id',
-                didReadCache: true,
-                didCallNeptune: true,
-                didWriteCache: false,
-                didSkipNeptune: false,
-                didFallbackToIncoming: false,
-                didEnqueueAsync: false,
-                staleTraits: expect.any(Array),
-            }));
-        });
-        it('should include traitChanges in summary when identity changes', 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 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_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).toBe('discovered-id');
-                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