@adtrackify/at-service-common 5.0.7 → 5.1.2

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

@@ -1,726 +1,749 @@
-jest.mock('../../clients/index.js', () => ({
-    DynamoDbClient: {
-        safeGet: jest.fn(),
-        safePut: jest.fn(),
-        safeDelete: jest.fn(),
-        safeBatchGet: jest.fn(),
-        safeBatchWrite: jest.fn(),
-        safeQueryByGSI: jest.fn(),
-        batchGet: jest.fn(),
-        batchWrite: jest.fn(),
-    },
-}));
-jest.mock('../../helpers/index.js', () => ({
-    Logger: {
-        debug: jest.fn(),
-        info: jest.fn(),
-        warn: jest.fn(),
-        error: jest.fn(),
-    },
-}));
-import { IdentityCacheDynamoDbDbService } from '../../services/db/identity-cache-dynamodb-service/identity-cache-dynamodb-db-service.js';
-import { DynamoDbClient } from '../../clients/index.js';
-import { Logger } from '../../helpers/index.js';
-import { IDENTITY_CACHE_TABLE_NAME } from '../../services/db/identity-cache-dynamodb-service/constants.js';
-const mockedDynamoDbClient = DynamoDbClient;
-const mockedLogger = Logger;
-describe('IdentityCacheDynamoDbDbService.getIdentityFromCachePure()', () => {
-    const pixelId = 'pixel-test-123';
-    beforeEach(() => {
-        jest.clearAllMocks();
-        mockedDynamoDbClient.safeGet.mockReset();
-        mockedDynamoDbClient.safePut.mockReset();
-        mockedDynamoDbClient.safeBatchWrite.mockReset();
-        mockedDynamoDbClient.batchGet.mockReset();
-        mockedDynamoDbClient.batchWrite.mockReset();
-    });
-    describe('cache hit by identity ID', () => {
-        it('should return cachedIdentity with lookupPath=identity_id and cacheHit=true', async () => {
-            const incomingIdentity = {
-                identityId: 'identity-123',
-                traits: { emails: ['test@email.com'] },
-            };
-            const cachedRecord = {
-                pk: `identity#${pixelId}#identity-123`,
-                pixelId,
-                identityId: 'identity-123',
-                response: {
-                    identityId: 'identity-123',
-                    traits: {
-                        emails: ['test@email.com', 'cached@email.com'],
-                        phones: ['555-1234'],
-                    },
-                },
-                updatedAt: new Date().toISOString(),
-            };
-            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedRecord);
-            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
-            expect(result.cacheHit).toBe(true);
-            expect(result.lookupPath).toBe('identity_id');
-            expect(result.cachedIdentity).toEqual(cachedRecord.response);
-            expect(result.discoveredIdentityId).toBeUndefined();
-            expect(mockedDynamoDbClient.safeGet).toHaveBeenCalledTimes(1);
-            expect(mockedDynamoDbClient.safeGet).toHaveBeenCalledWith(expect.any(String), 'pk', `identity#${pixelId}#identity-123`);
-        });
-        it('should return cachedIdentity with all traits preserved', async () => {
-            const incomingIdentity = {
-                identityId: 'full-traits-id',
-                traits: { emails: ['new@email.com'] },
-            };
-            const fullCachedIdentity = {
-                identityId: 'full-traits-id',
-                traits: {
-                    emails: ['existing@email.com', 'another@email.com'],
-                    phones: ['555-1111', '555-2222'],
-                    addresses: [{ city: 'New York', zip: '10001' }],
-                    userIds: ['user-1', 'user-2'],
-                    shopifyYIds: ['shopify-y-1'],
-                    click: { fbp: 'fb.1.123.456' },
-                    ipAddress: '192.168.1.1',
-                    userAgent: 'Mozilla/5.0...',
-                },
-            };
-            const cachedRecord = {
-                pk: `identity#${pixelId}#full-traits-id`,
-                pixelId,
-                identityId: 'full-traits-id',
-                response: fullCachedIdentity,
-                updatedAt: new Date().toISOString(),
-            };
-            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedRecord);
-            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
-            expect(result.cacheHit).toBe(true);
-            expect(result.cachedIdentity).toEqual(fullCachedIdentity);
-            expect(result.cachedIdentity?.traits?.emails).toHaveLength(2);
-            expect(result.cachedIdentity?.traits?.phones).toHaveLength(2);
-            expect(result.cachedIdentity?.traits?.addresses).toHaveLength(1);
-        });
-        it('should NOT perform any merge logic', async () => {
-            const incomingIdentity = {
-                identityId: 'merge-test-id',
-                traits: {
-                    emails: ['new-email@test.com'],
-                    phones: ['999-0000'],
-                },
-            };
-            const cachedRecord = {
-                pk: `identity#${pixelId}#merge-test-id`,
-                pixelId,
-                identityId: 'merge-test-id',
-                response: {
-                    identityId: 'merge-test-id',
-                    traits: {
-                        emails: ['old-email@test.com'],
-                        phones: ['111-2222'],
-                    },
-                },
-                updatedAt: new Date().toISOString(),
-            };
-            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedRecord);
-            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
-            expect(result.cachedIdentity?.traits?.emails).toEqual(['old-email@test.com']);
-            expect(result.cachedIdentity?.traits?.phones).toEqual(['111-2222']);
-            expect(result.cachedIdentity?.traits?.emails).not.toContain('new-email@test.com');
-        });
-        it('should NOT perform staleness computation', async () => {
-            const incomingIdentity = {
-                identityId: 'stale-test-id',
-                traits: {
-                    emails: ['new-email@test.com'],
-                },
-            };
-            const cachedRecord = {
-                pk: `identity#${pixelId}#stale-test-id`,
-                pixelId,
-                identityId: 'stale-test-id',
-                response: {
-                    identityId: 'stale-test-id',
-                    traits: {
-                        emails: ['old-email@test.com'],
-                    },
-                },
-                updatedAt: new Date().toISOString(),
-            };
-            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedRecord);
-            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
-            expect(result).not.toHaveProperty('isCacheStale');
-            expect(result).not.toHaveProperty('staleTier');
-            expect(result).not.toHaveProperty('staleTracker');
-            expect(result).not.toHaveProperty('writeReason');
-            expect(result).not.toHaveProperty('skipNeptune');
-        });
-    });
-    describe('cache hit by email pointer', () => {
-        it('should return discoveredIdentityId with lookupPath=email_pointer and cacheHit=true', async () => {
-            const incomingIdentity = {
-                traits: { emails: ['lookup@email.com'] },
-            };
-            const emailPointerRecord = {
-                pk: `email#${pixelId}#lookup@email.com`,
-                pixelId,
-                identityId: 'discovered-identity-456',
-                updatedAt: new Date().toISOString(),
-            };
-            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(emailPointerRecord);
-            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
-            expect(result.cacheHit).toBe(true);
-            expect(result.lookupPath).toBe('email_pointer');
-            expect(result.discoveredIdentityId).toBe('discovered-identity-456');
-            expect(result.cachedIdentity).toBeUndefined();
-        });
-        it('should use first email in emails array for lookup', async () => {
-            const incomingIdentity = {
-                traits: { emails: ['first@email.com', 'second@email.com'] },
-            };
-            const emailPointerRecord = {
-                pk: `email#${pixelId}#first@email.com`,
-                pixelId,
-                identityId: 'pointer-identity-789',
-                updatedAt: new Date().toISOString(),
-            };
-            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(emailPointerRecord);
-            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
-            expect(result.discoveredIdentityId).toBe('pointer-identity-789');
-            expect(mockedDynamoDbClient.safeGet).toHaveBeenCalledWith(expect.any(String), 'pk', `email#${pixelId}#first@email.com`);
-        });
-        it('should NOT merge traits when returning email pointer discovery', async () => {
-            const incomingIdentity = {
-                traits: {
-                    emails: ['discovery@email.com'],
-                    phones: ['incoming-phone'],
-                },
-            };
-            const emailPointerRecord = {
-                pk: `email#${pixelId}#discovery@email.com`,
-                pixelId,
-                identityId: 'discovered-id',
-                updatedAt: new Date().toISOString(),
-            };
-            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(emailPointerRecord);
-            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
-            expect(result.cachedIdentity).toBeUndefined();
-            expect(result.discoveredIdentityId).toBe('discovered-id');
-        });
-    });
-    describe('cache miss', () => {
-        it('should return lookupPath=miss and cacheHit=false when identity not found', async () => {
-            const incomingIdentity = {
-                identityId: 'nonexistent-identity',
-                traits: { emails: ['test@email.com'] },
-            };
-            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
-            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
-            expect(result.cacheHit).toBe(false);
-            expect(result.lookupPath).toBe('identity_id');
-            expect(result.cachedIdentity).toBeUndefined();
-            expect(result.discoveredIdentityId).toBeUndefined();
-        });
-        it('should return lookupPath=miss and cacheHit=false when email pointer not found', async () => {
-            const incomingIdentity = {
-                traits: { emails: ['unknown@email.com'] },
-            };
-            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
-            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
-            expect(result.cacheHit).toBe(false);
-            expect(result.lookupPath).toBe('miss');
-            expect(result.cachedIdentity).toBeUndefined();
-            expect(result.discoveredIdentityId).toBeUndefined();
-        });
-        it('should return lookupPath=miss when cached record has no response field', async () => {
-            const incomingIdentity = {
-                identityId: 'no-response-identity',
-                traits: { emails: ['test@email.com'] },
-            };
-            const incompleteRecord = {
-                pk: `identity#${pixelId}#no-response-identity`,
-                pixelId,
-                identityId: 'no-response-identity',
-                updatedAt: new Date().toISOString(),
-            };
-            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(incompleteRecord);
-            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
-            expect(result.cacheHit).toBe(false);
-            expect(result.lookupPath).toBe('identity_id');
-            expect(result.cachedIdentity).toBeUndefined();
-        });
-        it('should return lookupPath=miss when no email provided for pointer lookup', async () => {
-            const incomingIdentity = {
-                traits: { phones: ['555-1234'] },
-            };
-            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
-            expect(result.cacheHit).toBe(false);
-            expect(result.lookupPath).toBe('miss');
-            expect(mockedDynamoDbClient.safeGet).not.toHaveBeenCalled();
-        });
-    });
-    describe('invalid input handling', () => {
-        it('should return cache miss for undefined pixelId', async () => {
-            const incomingIdentity = {
-                identityId: 'test-identity',
-                traits: { emails: ['test@email.com'] },
-            };
-            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(undefined, incomingIdentity);
-            expect(result.cacheHit).toBe(false);
-            expect(result.lookupPath).toBe('miss');
-            expect(mockedDynamoDbClient.safeGet).not.toHaveBeenCalled();
-        });
-        it('should return cache miss for empty pixelId', async () => {
-            const incomingIdentity = {
-                identityId: 'test-identity',
-                traits: { emails: ['test@email.com'] },
-            };
-            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure('', incomingIdentity);
-            expect(result.cacheHit).toBe(false);
-            expect(result.lookupPath).toBe('miss');
-        });
-        it('should return cache miss for undefined incomingIdentity', async () => {
-            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, undefined);
-            expect(result.cacheHit).toBe(false);
-            expect(result.lookupPath).toBe('miss');
-        });
-        it('should return cache miss for null incomingIdentity', async () => {
-            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, null);
-            expect(result.cacheHit).toBe(false);
-            expect(result.lookupPath).toBe('miss');
-        });
-    });
-    describe('error handling', () => {
-        it('should return cache miss when DynamoDB throws an error', async () => {
-            const incomingIdentity = {
-                identityId: 'error-test-identity',
-                traits: { emails: ['test@email.com'] },
-            };
-            mockedDynamoDbClient.safeGet.mockRejectedValueOnce(new Error('DynamoDB connection failed'));
-            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
-            expect(result.cacheHit).toBe(false);
-            expect(result.lookupPath).toBe('identity_id');
-            expect(result.cachedIdentity).toBeUndefined();
-            expect(mockedLogger.error).toHaveBeenCalledWith('IdentityCache - getItemByPk failed', expect.objectContaining({
-                error: expect.any(Error),
-                errorMessage: 'DynamoDB connection failed',
-            }));
-        });
-        it('should handle non-Error thrown values', async () => {
-            const incomingIdentity = {
-                identityId: 'string-error-identity',
-                traits: { emails: ['test@email.com'] },
-            };
-            mockedDynamoDbClient.safeGet.mockRejectedValueOnce('String error message');
-            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
-            expect(result.cacheHit).toBe(false);
-            expect(result.lookupPath).toBe('identity_id');
-            expect(mockedLogger.error).toHaveBeenCalledWith('IdentityCache - getItemByPk failed', expect.objectContaining({
-                errorMessage: 'String error message',
-            }));
-        });
-    });
-    describe('verification: no merge or staleness logic', () => {
-        it('should not call mergeIdentityTraits', async () => {
-            const incomingIdentity = {
-                identityId: 'verify-no-merge',
-                traits: { emails: ['incoming@email.com'] },
-            };
-            const cachedRecord = {
-                pk: `identity#${pixelId}#verify-no-merge`,
-                pixelId,
-                identityId: 'verify-no-merge',
-                response: {
-                    identityId: 'verify-no-merge',
-                    traits: { emails: ['cached@email.com'] },
-                },
-                updatedAt: new Date().toISOString(),
-            };
-            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedRecord);
-            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
-            expect(result.cachedIdentity).toBe(cachedRecord.response);
-            expect(result.cachedIdentity?.traits?.emails).toEqual(['cached@email.com']);
-        });
-        it('should not call isIdentityCacheStale', async () => {
-            const incomingIdentity = {
-                identityId: 'verify-no-staleness',
-                traits: {
-                    emails: ['new-email@test.com'],
-                },
-            };
-            const cachedRecord = {
-                pk: `identity#${pixelId}#verify-no-staleness`,
-                pixelId,
-                identityId: 'verify-no-staleness',
-                response: {
-                    identityId: 'verify-no-staleness',
-                    traits: { emails: ['old-email@test.com'] },
-                },
-                updatedAt: new Date().toISOString(),
-            };
-            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedRecord);
-            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
-            expect(Object.keys(result)).toEqual(['cachedIdentity', 'lookupPath', 'cacheHit']);
-        });
-        it('result should only contain pure lookup properties', async () => {
-            const incomingIdentity = {
-                identityId: 'result-shape-test',
-                traits: { emails: ['test@email.com'] },
-            };
-            const cachedRecord = {
-                pk: `identity#${pixelId}#result-shape-test`,
-                pixelId,
-                identityId: 'result-shape-test',
-                response: {
-                    identityId: 'result-shape-test',
-                    traits: { emails: ['test@email.com'] },
-                },
-                updatedAt: new Date().toISOString(),
-            };
-            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedRecord);
-            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
-            expect(result).toEqual({
-                cachedIdentity: cachedRecord.response,
-                lookupPath: 'identity_id',
-                cacheHit: true,
-            });
-            expect(result).not.toHaveProperty('resolvedIdentity');
-            expect(result).not.toHaveProperty('isCacheStale');
-            expect(result).not.toHaveProperty('staleTracker');
-            expect(result).not.toHaveProperty('staleTier');
-            expect(result).not.toHaveProperty('writeReason');
-            expect(result).not.toHaveProperty('skipNeptune');
-            expect(result).not.toHaveProperty('mergedIdentity');
-        });
-    });
-    describe('logging', () => {
-        it('should log debug on cache hit by identity ID', async () => {
-            const incomingIdentity = {
-                identityId: 'log-test-id',
-                traits: { emails: ['test@email.com'] },
-            };
-            const cachedRecord = {
-                pk: `identity#${pixelId}#log-test-id`,
-                pixelId,
-                identityId: 'log-test-id',
-                response: {
-                    identityId: 'log-test-id',
-                    traits: { emails: ['test@email.com'] },
-                },
-                updatedAt: new Date().toISOString(),
-            };
-            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedRecord);
-            await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
-            expect(mockedLogger.debug).toHaveBeenCalledWith('IdentityCache - pure lookup hit', expect.objectContaining({
-                pixelId,
-                identityId: 'log-test-id',
-            }));
-        });
-        it('should log debug on cache miss', async () => {
-            const incomingIdentity = {
-                identityId: 'miss-log-test',
-                traits: { emails: ['test@email.com'] },
-            };
-            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
-            await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
-            expect(mockedLogger.debug).toHaveBeenCalledWith('IdentityCache - pure lookup miss', expect.objectContaining({
-                pixelId,
-                identityId: 'miss-log-test',
-            }));
-        });
-        it('should log debug on email pointer discovery', async () => {
-            const incomingIdentity = {
-                traits: { emails: ['email-pointer@test.com'] },
-            };
-            const emailPointerRecord = {
-                pk: `email#${pixelId}#email-pointer@test.com`,
-                pixelId,
-                identityId: 'discovered-from-pointer',
-                updatedAt: new Date().toISOString(),
-            };
-            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(emailPointerRecord);
-            await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
-            expect(mockedLogger.debug).toHaveBeenCalledWith('IdentityCache - pure email pointer discovery', expect.objectContaining({
-                pixelId,
-                discoveredIdentityId: 'discovered-from-pointer',
-            }));
-        });
-    });
-});
-describe('IdentityCacheDynamoDbDbService cluster traits operations', () => {
-    const pixelId = 'pixel-cluster';
-    const primaryIdentityId = 'identity-primary';
-    const secondaryIdentityId = 'identity-secondary';
-    beforeEach(() => {
-        jest.clearAllMocks();
-    });
-    it('returns records by requested identity ID when every key is processed', async () => {
-        const primaryRecord = {
-            pk: `identity#${pixelId}#${primaryIdentityId}`,
-            pixelId,
-            identityId: primaryIdentityId,
-            response: { identityId: primaryIdentityId, traits: { emails: ['primary@test.com'] } },
-            updatedAt: '2026-09-04T12:00:00.000Z',
-        };
-        mockedDynamoDbClient.batchGet.mockResolvedValue({
-            Responses: { [IDENTITY_CACHE_TABLE_NAME]: [primaryRecord] },
-            UnprocessedKeys: {},
-            $metadata: {},
-        });
-        const result = await IdentityCacheDynamoDbDbService.getClusterIdentityRecords(pixelId, [primaryIdentityId, secondaryIdentityId]);
-        expect(result.complete).toBe(true);
-        expect(result.failedIdentityIds).toEqual([]);
-        expect(result.recordsByIdentityId.get(primaryIdentityId)).toEqual(primaryRecord);
-        expect(result.recordsByIdentityId.has(secondaryIdentityId)).toBe(false);
-    });
-    it('treats an unprocessed key as a failed read', async () => {
-        mockedDynamoDbClient.batchGet.mockResolvedValue({
-            Responses: { [IDENTITY_CACHE_TABLE_NAME]: [] },
-            UnprocessedKeys: {
-                [IDENTITY_CACHE_TABLE_NAME]: {
-                    Keys: [{ pk: `identity#${pixelId}#${secondaryIdentityId}` }],
-                },
-            },
-            $metadata: {},
-        });
-        const result = await IdentityCacheDynamoDbDbService.getClusterIdentityRecords(pixelId, [primaryIdentityId, secondaryIdentityId]);
-        expect(result.complete).toBe(false);
-        expect(result.failedIdentityIds).toEqual([secondaryIdentityId]);
-    });
-    it('marks every key in a failed chunk as a failed read', async () => {
-        mockedDynamoDbClient.batchGet.mockRejectedValue(new Error('read failed'));
-        const result = await IdentityCacheDynamoDbDbService.getClusterIdentityRecords(pixelId, [primaryIdentityId, secondaryIdentityId]);
-        expect(result.complete).toBe(false);
-        expect(result.failedIdentityIds).toEqual([primaryIdentityId, secondaryIdentityId]);
-    });
-    it('writes final primary traits and the migration marker in one item', async () => {
-        mockedDynamoDbClient.safePut.mockResolvedValue({ $metadata: { httpStatusCode: 200 } });
-        const success = await IdentityCacheDynamoDbDbService.putPrimaryIdentityTraits({
-            pixelId,
-            primaryIdentityId,
-            traits: { emails: ['merged@test.com'] },
-            traitsInDynamo: true,
-        });
-        expect(success).toBe(true);
-        expect(mockedDynamoDbClient.safePut).toHaveBeenCalledWith(expect.any(String), expect.objectContaining({
-            pk: `identity#${pixelId}#${primaryIdentityId}`,
-            identityId: primaryIdentityId,
-            traitsInDynamo: true,
-            response: {
-                identityId: primaryIdentityId,
-                traits: { emails: ['merged@test.com'] },
-            },
-        }));
-    });
-    it('reports a failed primary traits write', async () => {
-        mockedDynamoDbClient.safePut.mockResolvedValue(null);
-        const success = await IdentityCacheDynamoDbDbService.putPrimaryIdentityTraits({
-            pixelId,
-            primaryIdentityId,
-            traits: {},
-            traitsInDynamo: true,
-        });
-        expect(success).toBe(false);
-    });
-    it('deletes exact identity keys and returns unprocessed identity IDs', async () => {
-        mockedDynamoDbClient.batchWrite.mockResolvedValue({
-            UnprocessedItems: {
-                [IDENTITY_CACHE_TABLE_NAME]: [{
-                        DeleteRequest: { Key: { pk: `identity#${pixelId}#${secondaryIdentityId}` } },
-                    }],
-            },
-            $metadata: {},
-        });
-        const failedIdentityIds = await IdentityCacheDynamoDbDbService.deleteIdentityRecords(pixelId, [primaryIdentityId, secondaryIdentityId]);
-        expect(failedIdentityIds).toEqual([secondaryIdentityId]);
-        expect(mockedDynamoDbClient.batchWrite).toHaveBeenCalledWith({
-            RequestItems: {
-                [IDENTITY_CACHE_TABLE_NAME]: [
-                    { DeleteRequest: { Key: { pk: `identity#${pixelId}#${primaryIdentityId}` } } },
-                    { DeleteRequest: { Key: { pk: `identity#${pixelId}#${secondaryIdentityId}` } } },
-                ],
-            },
-        });
-    });
-    it('returns every identity ID when an exact delete chunk fails', async () => {
-        mockedDynamoDbClient.batchWrite.mockRejectedValue(new Error('delete failed'));
-        const failedIdentityIds = await IdentityCacheDynamoDbDbService.deleteIdentityRecords(pixelId, [primaryIdentityId, secondaryIdentityId]);
-        expect(failedIdentityIds).toEqual([primaryIdentityId, secondaryIdentityId]);
-    });
-    it('deduplicates requested identity IDs before issuing batchGet', async () => {
-        mockedDynamoDbClient.batchGet.mockResolvedValue({
-            Responses: { [IDENTITY_CACHE_TABLE_NAME]: [] },
-            UnprocessedKeys: {},
-            $metadata: {},
-        });
-        await IdentityCacheDynamoDbDbService.getClusterIdentityRecords(pixelId, [primaryIdentityId, primaryIdentityId, secondaryIdentityId]);
-        expect(mockedDynamoDbClient.batchGet).toHaveBeenCalledWith({
-            RequestItems: {
-                [IDENTITY_CACHE_TABLE_NAME]: {
-                    Keys: [
-                        { pk: `identity#${pixelId}#${primaryIdentityId}` },
-                        { pk: `identity#${pixelId}#${secondaryIdentityId}` },
-                    ],
-                },
-            },
-        });
-    });
-    it('treats a processed key with no returned item as a successful miss', async () => {
-        mockedDynamoDbClient.batchGet.mockResolvedValue({
-            Responses: { [IDENTITY_CACHE_TABLE_NAME]: [] },
-            UnprocessedKeys: {},
-            $metadata: {},
-        });
-        const result = await IdentityCacheDynamoDbDbService.getClusterIdentityRecords(pixelId, [primaryIdentityId, secondaryIdentityId]);
-        expect(result.complete).toBe(true);
-        expect(result.failedIdentityIds).toEqual([]);
-        expect(result.recordsByIdentityId.size).toBe(0);
-    });
-    it('reports a failed primary traits write when safePut throws', async () => {
-        mockedDynamoDbClient.safePut.mockRejectedValue(new Error('put failed'));
-        const success = await IdentityCacheDynamoDbDbService.putPrimaryIdentityTraits({
-            pixelId,
-            primaryIdentityId,
-            traits: { emails: ['merged@test.com'] },
-            traitsInDynamo: true,
-        });
-        expect(success).toBe(false);
-        expect(mockedLogger.error).toHaveBeenCalledWith('IdentityCache [primary traits write]: failed', expect.objectContaining({ pixelId, primaryIdentityId }));
-    });
-    it('deletes exact identity PKs without querying GSI1', async () => {
-        mockedDynamoDbClient.batchWrite.mockResolvedValue({
-            UnprocessedItems: {},
-            $metadata: {},
-        });
-        await IdentityCacheDynamoDbDbService.deleteIdentityRecords(pixelId, [secondaryIdentityId]);
-        expect(mockedDynamoDbClient.safeQueryByGSI).not.toHaveBeenCalled();
-        expect(mockedDynamoDbClient.batchWrite).toHaveBeenCalledWith({
-            RequestItems: {
-                [IDENTITY_CACHE_TABLE_NAME]: [
-                    { DeleteRequest: { Key: { pk: `identity#${pixelId}#${secondaryIdentityId}` } } },
-                ],
-            },
-        });
-    });
-    it('logs cluster read completion with requested identity IDs', async () => {
-        mockedDynamoDbClient.batchGet.mockResolvedValue({
-            Responses: { [IDENTITY_CACHE_TABLE_NAME]: [] },
-            UnprocessedKeys: {},
-            $metadata: {},
-        });
-        await IdentityCacheDynamoDbDbService.getClusterIdentityRecords(pixelId, [primaryIdentityId]);
-        expect(mockedLogger.debug).toHaveBeenCalledWith('IdentityCache [cluster traits read]: completed', expect.objectContaining({
-            pixelId,
-            identityIds: [primaryIdentityId],
-        }));
-    });
-});
-describe('mergeAndComputeIdentityStaleness (pure function)', () => {
-    const { mergeAndComputeIdentityStaleness, IDENTITY_CACHE_STALENESS_TIER } = jest.requireActual('@adtrackify/at-shared-utils');
-    describe('merge behavior', () => {
-        it('should merge incoming traits with cached traits', () => {
-            const incomingIdentity = {
-                identityId: 'merge-test',
-                traits: {
-                    emails: ['new@email.com'],
-                },
-            };
-            const cachedIdentity = {
-                identityId: 'merge-test',
-                traits: {
-                    emails: ['cached@email.com'],
-                    phones: ['555-1234'],
-                },
-            };
-            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
-            expect(result.mergedIdentity.traits?.emails).toContain('new@email.com');
-            expect(result.mergedIdentity.traits?.emails).toContain('cached@email.com');
-            expect(result.mergedIdentity.traits?.phones).toContain('555-1234');
-        });
-    });
-    describe('staleness tier computation', () => {
-        it('should return NONE tier when no traits are stale', () => {
-            const incomingIdentity = {
-                identityId: 'same-test',
-                traits: { emails: ['same@email.com'] },
-            };
-            const cachedIdentity = {
-                identityId: 'same-test',
-                traits: { emails: ['same@email.com'] },
-            };
-            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
-            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.NONE);
-            expect(result.isCacheStale).toBe(false);
-        });
-        it('should return VOLATILE_ONLY tier when incoming has new IP address (cached has none)', () => {
-            const incomingIdentity = {
-                identityId: 'volatile-test',
-                traits: {
-                    emails: ['same@email.com'],
-                    ipAddress: '192.168.1.100',
-                },
-            };
-            const cachedIdentity = {
-                identityId: 'volatile-test',
-                traits: {
-                    emails: ['same@email.com'],
-                },
-            };
-            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
-            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.VOLATILE_ONLY);
-            expect(result.isCacheStale).toBe(false);
-        });
-        it('should return ADDRESS_UPDATE tier when non-IP address is new', () => {
-            const incomingIdentity = {
-                identityId: 'address-test',
-                traits: {
-                    emails: ['same@email.com'],
-                    addresses: [{ firstName: 'John', city: 'New York' }],
-                },
-            };
-            const cachedIdentity = {
-                identityId: 'address-test',
-                traits: {
-                    emails: ['same@email.com'],
-                    addresses: [],
-                },
-            };
-            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
-            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.ADDRESS_UPDATE);
-            expect(result.isCacheStale).toBe(true);
-        });
-        it('should return IDENTITY_STALE tier when email changes', () => {
-            const incomingIdentity = {
-                identityId: 'stale-test',
-                traits: {
-                    emails: ['new@email.com'],
-                },
-            };
-            const cachedIdentity = {
-                identityId: 'stale-test',
-                traits: {
-                    emails: ['old@email.com'],
-                },
-            };
-            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
-            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.IDENTITY_STALE);
-            expect(result.isCacheStale).toBe(true);
-        });
-    });
-    describe('staleTraits extraction', () => {
-        it('should include changed trait names in staleTraits array', () => {
-            const incomingIdentity = {
-                identityId: 'traits-test',
-                traits: {
-                    emails: ['new@email.com'],
-                    phones: ['999-0000'],
-                },
-            };
-            const cachedIdentity = {
-                identityId: 'traits-test',
-                traits: {
-                    emails: ['old@email.com'],
-                    phones: ['111-2222'],
-                },
-            };
-            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
-            expect(result.staleTraits).toContain('emails');
-            expect(result.staleTraits).toContain('phones');
-        });
-    });
-});
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { IDENTITY_CACHE_STALENESS_TIER, mergeAndComputeIdentityStaleness } from '@adtrackify/at-shared-utils';
+vi.mock('../../clients/index.js', () => ({
+    DynamoDbClient: {
+        safeGet: vi.fn(),
+        safePut: vi.fn(),
+        safeDelete: vi.fn(),
+        safeBatchGet: vi.fn(),
+        safeBatchWrite: vi.fn(),
+        safeQueryByGSI: vi.fn(),
+        batchGet: vi.fn(),
+        batchWrite: vi.fn(),
+    },
+}));
+vi.mock('../../helpers/index.js', () => ({
+    Logger: {
+        debug: vi.fn(),
+        info: vi.fn(),
+        warn: vi.fn(),
+        error: vi.fn(),
+    },
+}));
+import { IdentityCacheDynamoDbDbService } from '../../services/db/identity-cache-dynamodb-service/identity-cache-dynamodb-db-service.js';
+import { DynamoDbClient } from '../../clients/index.js';
+import { Logger } from '../../helpers/index.js';
+import { IDENTITY_CACHE_TABLE_NAME } from '../../services/db/identity-cache-dynamodb-service/constants.js';
+const mockedDynamoDbClient = DynamoDbClient;
+const mockedLogger = Logger;
+describe('IdentityCacheDynamoDbDbService.getIdentityFromCachePure()', () => {
+    const pixelId = 'pixel-test-123';
+    beforeEach(() => {
+        vi.clearAllMocks();
+        mockedDynamoDbClient.safeGet.mockReset();
+        mockedDynamoDbClient.safePut.mockReset();
+        mockedDynamoDbClient.safeBatchWrite.mockReset();
+        mockedDynamoDbClient.batchGet.mockReset();
+        mockedDynamoDbClient.batchWrite.mockReset();
+    });
+    describe('cache hit by identity ID', () => {
+        it('should return cachedIdentity with lookupPath=identity_id and cacheHit=true', async () => {
+            const incomingIdentity = {
+                identityId: 'identity-123',
+                traits: { emails: ['test@email.com'] },
+            };
+            const cachedRecord = {
+                pk: `identity#${pixelId}#identity-123`,
+                pixelId,
+                identityId: 'identity-123',
+                response: {
+                    identityId: 'identity-123',
+                    traits: {
+                        emails: ['test@email.com', 'cached@email.com'],
+                        phones: ['555-1234'],
+                    },
+                },
+                updatedAt: new Date().toISOString(),
+            };
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedRecord);
+            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
+            expect(result.cacheHit).toBe(true);
+            expect(result.lookupPath).toBe('identity_id');
+            expect(result.cachedIdentity).toEqual(cachedRecord.response);
+            expect(result.discoveredIdentityId).toBeUndefined();
+            expect(mockedDynamoDbClient.safeGet).toHaveBeenCalledTimes(1);
+            expect(mockedDynamoDbClient.safeGet).toHaveBeenCalledWith(expect.any(String), 'pk', `identity#${pixelId}#identity-123`);
+        });
+        it('should return cachedIdentity with all traits preserved', async () => {
+            const incomingIdentity = {
+                identityId: 'full-traits-id',
+                traits: { emails: ['new@email.com'] },
+            };
+            const fullCachedIdentity = {
+                identityId: 'full-traits-id',
+                traits: {
+                    emails: ['existing@email.com', 'another@email.com'],
+                    phones: ['555-1111', '555-2222'],
+                    addresses: [{ city: 'New York', zip: '10001' }],
+                    userIds: ['user-1', 'user-2'],
+                    shopifyYIds: ['shopify-y-1'],
+                    click: { fbp: 'fb.1.123.456' },
+                    ipAddress: '192.168.1.1',
+                    userAgent: 'Mozilla/5.0...',
+                },
+            };
+            const cachedRecord = {
+                pk: `identity#${pixelId}#full-traits-id`,
+                pixelId,
+                identityId: 'full-traits-id',
+                response: fullCachedIdentity,
+                updatedAt: new Date().toISOString(),
+            };
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedRecord);
+            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
+            expect(result.cacheHit).toBe(true);
+            expect(result.cachedIdentity).toEqual(fullCachedIdentity);
+            expect(result.cachedIdentity?.traits?.emails).toHaveLength(2);
+            expect(result.cachedIdentity?.traits?.phones).toHaveLength(2);
+            expect(result.cachedIdentity?.traits?.addresses).toHaveLength(1);
+        });
+        it('should NOT perform any merge logic', async () => {
+            const incomingIdentity = {
+                identityId: 'merge-test-id',
+                traits: {
+                    emails: ['new-email@test.com'],
+                    phones: ['999-0000'],
+                },
+            };
+            const cachedRecord = {
+                pk: `identity#${pixelId}#merge-test-id`,
+                pixelId,
+                identityId: 'merge-test-id',
+                response: {
+                    identityId: 'merge-test-id',
+                    traits: {
+                        emails: ['old-email@test.com'],
+                        phones: ['111-2222'],
+                    },
+                },
+                updatedAt: new Date().toISOString(),
+            };
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedRecord);
+            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
+            expect(result.cachedIdentity?.traits?.emails).toEqual(['old-email@test.com']);
+            expect(result.cachedIdentity?.traits?.phones).toEqual(['111-2222']);
+            expect(result.cachedIdentity?.traits?.emails).not.toContain('new-email@test.com');
+        });
+        it('should NOT perform staleness computation', async () => {
+            const incomingIdentity = {
+                identityId: 'stale-test-id',
+                traits: {
+                    emails: ['new-email@test.com'],
+                },
+            };
+            const cachedRecord = {
+                pk: `identity#${pixelId}#stale-test-id`,
+                pixelId,
+                identityId: 'stale-test-id',
+                response: {
+                    identityId: 'stale-test-id',
+                    traits: {
+                        emails: ['old-email@test.com'],
+                    },
+                },
+                updatedAt: new Date().toISOString(),
+            };
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedRecord);
+            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
+            expect(result).not.toHaveProperty('isCacheStale');
+            expect(result).not.toHaveProperty('staleTier');
+            expect(result).not.toHaveProperty('staleTracker');
+            expect(result).not.toHaveProperty('writeReason');
+            expect(result).not.toHaveProperty('skipNeptune');
+        });
+    });
+    describe('cache hit by email pointer', () => {
+        it('should return discoveredIdentityId with lookupPath=email_pointer and cacheHit=true', async () => {
+            const incomingIdentity = {
+                traits: { emails: ['lookup@email.com'] },
+            };
+            const emailPointerRecord = {
+                pk: `email#${pixelId}#lookup@email.com`,
+                pixelId,
+                identityId: 'discovered-identity-456',
+                updatedAt: new Date().toISOString(),
+            };
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(emailPointerRecord);
+            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
+            expect(result.cacheHit).toBe(true);
+            expect(result.lookupPath).toBe('email_pointer');
+            expect(result.discoveredIdentityId).toBe('discovered-identity-456');
+            expect(result.cachedIdentity).toBeUndefined();
+        });
+        it('should use first email in emails array for lookup', async () => {
+            const incomingIdentity = {
+                traits: { emails: ['first@email.com', 'second@email.com'] },
+            };
+            const emailPointerRecord = {
+                pk: `email#${pixelId}#first@email.com`,
+                pixelId,
+                identityId: 'pointer-identity-789',
+                updatedAt: new Date().toISOString(),
+            };
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(emailPointerRecord);
+            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
+            expect(result.discoveredIdentityId).toBe('pointer-identity-789');
+            expect(mockedDynamoDbClient.safeGet).toHaveBeenCalledWith(expect.any(String), 'pk', `email#${pixelId}#first@email.com`);
+        });
+        it('should NOT merge traits when returning email pointer discovery', async () => {
+            const incomingIdentity = {
+                traits: {
+                    emails: ['discovery@email.com'],
+                    phones: ['incoming-phone'],
+                },
+            };
+            const emailPointerRecord = {
+                pk: `email#${pixelId}#discovery@email.com`,
+                pixelId,
+                identityId: 'discovered-id',
+                updatedAt: new Date().toISOString(),
+            };
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(emailPointerRecord);
+            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
+            expect(result.cachedIdentity).toBeUndefined();
+            expect(result.discoveredIdentityId).toBe('discovered-id');
+        });
+    });
+    describe('cache miss', () => {
+        it('should return lookupPath=miss and cacheHit=false when identity not found', async () => {
+            const incomingIdentity = {
+                identityId: 'nonexistent-identity',
+                traits: { emails: ['test@email.com'] },
+            };
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
+            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
+            expect(result.cacheHit).toBe(false);
+            expect(result.lookupPath).toBe('identity_id');
+            expect(result.cachedIdentity).toBeUndefined();
+            expect(result.discoveredIdentityId).toBeUndefined();
+        });
+        it('should return lookupPath=miss and cacheHit=false when email pointer not found', async () => {
+            const incomingIdentity = {
+                traits: { emails: ['unknown@email.com'] },
+            };
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
+            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
+            expect(result.cacheHit).toBe(false);
+            expect(result.lookupPath).toBe('miss');
+            expect(result.cachedIdentity).toBeUndefined();
+            expect(result.discoveredIdentityId).toBeUndefined();
+        });
+        it('should return lookupPath=miss when cached record has no response field', async () => {
+            const incomingIdentity = {
+                identityId: 'no-response-identity',
+                traits: { emails: ['test@email.com'] },
+            };
+            const incompleteRecord = {
+                pk: `identity#${pixelId}#no-response-identity`,
+                pixelId,
+                identityId: 'no-response-identity',
+                updatedAt: new Date().toISOString(),
+            };
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(incompleteRecord);
+            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
+            expect(result.cacheHit).toBe(false);
+            expect(result.lookupPath).toBe('identity_id');
+            expect(result.cachedIdentity).toBeUndefined();
+        });
+        it('should return lookupPath=miss when no email provided for pointer lookup', async () => {
+            const incomingIdentity = {
+                traits: { phones: ['555-1234'] },
+            };
+            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
+            expect(result.cacheHit).toBe(false);
+            expect(result.lookupPath).toBe('miss');
+            expect(mockedDynamoDbClient.safeGet).not.toHaveBeenCalled();
+        });
+    });
+    describe('invalid input handling', () => {
+        it('should return cache miss for undefined pixelId', async () => {
+            const incomingIdentity = {
+                identityId: 'test-identity',
+                traits: { emails: ['test@email.com'] },
+            };
+            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(undefined, incomingIdentity);
+            expect(result.cacheHit).toBe(false);
+            expect(result.lookupPath).toBe('miss');
+            expect(mockedDynamoDbClient.safeGet).not.toHaveBeenCalled();
+        });
+        it('should return cache miss for empty pixelId', async () => {
+            const incomingIdentity = {
+                identityId: 'test-identity',
+                traits: { emails: ['test@email.com'] },
+            };
+            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure('', incomingIdentity);
+            expect(result.cacheHit).toBe(false);
+            expect(result.lookupPath).toBe('miss');
+        });
+        it('should return cache miss for undefined incomingIdentity', async () => {
+            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, undefined);
+            expect(result.cacheHit).toBe(false);
+            expect(result.lookupPath).toBe('miss');
+        });
+        it('should return cache miss for null incomingIdentity', async () => {
+            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, null);
+            expect(result.cacheHit).toBe(false);
+            expect(result.lookupPath).toBe('miss');
+        });
+    });
+    describe('error handling', () => {
+        it('should return cache miss when DynamoDB throws an error', async () => {
+            const incomingIdentity = {
+                identityId: 'error-test-identity',
+                traits: { emails: ['test@email.com'] },
+            };
+            mockedDynamoDbClient.safeGet.mockRejectedValueOnce(new Error('DynamoDB connection failed'));
+            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
+            expect(result.cacheHit).toBe(false);
+            expect(result.lookupPath).toBe('identity_id');
+            expect(result.cachedIdentity).toBeUndefined();
+            expect(mockedLogger.error).toHaveBeenCalledWith('IdentityCache - getItemByPk failed', expect.objectContaining({
+                error: expect.any(Error),
+                errorMessage: 'DynamoDB connection failed',
+            }));
+        });
+        it('should handle non-Error thrown values', async () => {
+            const incomingIdentity = {
+                identityId: 'string-error-identity',
+                traits: { emails: ['test@email.com'] },
+            };
+            mockedDynamoDbClient.safeGet.mockRejectedValueOnce('String error message');
+            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
+            expect(result.cacheHit).toBe(false);
+            expect(result.lookupPath).toBe('identity_id');
+            expect(mockedLogger.error).toHaveBeenCalledWith('IdentityCache - getItemByPk failed', expect.objectContaining({
+                errorMessage: 'String error message',
+            }));
+        });
+    });
+    describe('verification: no merge or staleness logic', () => {
+        it('should not call mergeIdentityTraits', async () => {
+            const incomingIdentity = {
+                identityId: 'verify-no-merge',
+                traits: { emails: ['incoming@email.com'] },
+            };
+            const cachedRecord = {
+                pk: `identity#${pixelId}#verify-no-merge`,
+                pixelId,
+                identityId: 'verify-no-merge',
+                response: {
+                    identityId: 'verify-no-merge',
+                    traits: { emails: ['cached@email.com'] },
+                },
+                updatedAt: new Date().toISOString(),
+            };
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedRecord);
+            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
+            expect(result.cachedIdentity).toBe(cachedRecord.response);
+            expect(result.cachedIdentity?.traits?.emails).toEqual(['cached@email.com']);
+        });
+        it('should not call isIdentityCacheStale', async () => {
+            const incomingIdentity = {
+                identityId: 'verify-no-staleness',
+                traits: {
+                    emails: ['new-email@test.com'],
+                },
+            };
+            const cachedRecord = {
+                pk: `identity#${pixelId}#verify-no-staleness`,
+                pixelId,
+                identityId: 'verify-no-staleness',
+                response: {
+                    identityId: 'verify-no-staleness',
+                    traits: { emails: ['old-email@test.com'] },
+                },
+                updatedAt: new Date().toISOString(),
+            };
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedRecord);
+            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
+            expect(Object.keys(result)).toEqual(['cachedIdentity', 'lookupPath', 'cacheHit']);
+        });
+        it('result should only contain pure lookup properties', async () => {
+            const incomingIdentity = {
+                identityId: 'result-shape-test',
+                traits: { emails: ['test@email.com'] },
+            };
+            const cachedRecord = {
+                pk: `identity#${pixelId}#result-shape-test`,
+                pixelId,
+                identityId: 'result-shape-test',
+                response: {
+                    identityId: 'result-shape-test',
+                    traits: { emails: ['test@email.com'] },
+                },
+                updatedAt: new Date().toISOString(),
+            };
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedRecord);
+            const result = await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
+            expect(result).toEqual({
+                cachedIdentity: cachedRecord.response,
+                lookupPath: 'identity_id',
+                cacheHit: true,
+            });
+            expect(result).not.toHaveProperty('resolvedIdentity');
+            expect(result).not.toHaveProperty('isCacheStale');
+            expect(result).not.toHaveProperty('staleTracker');
+            expect(result).not.toHaveProperty('staleTier');
+            expect(result).not.toHaveProperty('writeReason');
+            expect(result).not.toHaveProperty('skipNeptune');
+            expect(result).not.toHaveProperty('mergedIdentity');
+        });
+    });
+    describe('logging', () => {
+        it('should log debug on cache hit by identity ID', async () => {
+            const incomingIdentity = {
+                identityId: 'log-test-id',
+                traits: { emails: ['test@email.com'] },
+            };
+            const cachedRecord = {
+                pk: `identity#${pixelId}#log-test-id`,
+                pixelId,
+                identityId: 'log-test-id',
+                response: {
+                    identityId: 'log-test-id',
+                    traits: { emails: ['test@email.com'] },
+                },
+                updatedAt: new Date().toISOString(),
+            };
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(cachedRecord);
+            await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
+            expect(mockedLogger.debug).toHaveBeenCalledWith('IdentityCache - pure lookup hit', expect.objectContaining({
+                pixelId,
+                identityId: 'log-test-id',
+            }));
+        });
+        it('should log debug on cache miss', async () => {
+            const incomingIdentity = {
+                identityId: 'miss-log-test',
+                traits: { emails: ['test@email.com'] },
+            };
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
+            await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
+            expect(mockedLogger.debug).toHaveBeenCalledWith('IdentityCache - pure lookup miss', expect.objectContaining({
+                pixelId,
+                identityId: 'miss-log-test',
+            }));
+        });
+        it('should log debug on email pointer discovery', async () => {
+            const incomingIdentity = {
+                traits: { emails: ['email-pointer@test.com'] },
+            };
+            const emailPointerRecord = {
+                pk: `email#${pixelId}#email-pointer@test.com`,
+                pixelId,
+                identityId: 'discovered-from-pointer',
+                updatedAt: new Date().toISOString(),
+            };
+            mockedDynamoDbClient.safeGet.mockResolvedValueOnce(emailPointerRecord);
+            await IdentityCacheDynamoDbDbService.getIdentityFromCachePure(pixelId, incomingIdentity);
+            expect(mockedLogger.debug).toHaveBeenCalledWith('IdentityCache - pure email pointer discovery', expect.objectContaining({
+                pixelId,
+                discoveredIdentityId: 'discovered-from-pointer',
+            }));
+        });
+    });
+});
+describe('IdentityCacheDynamoDbDbService cluster traits operations', () => {
+    const pixelId = 'pixel-cluster';
+    const primaryIdentityId = 'identity-primary';
+    const secondaryIdentityId = 'identity-secondary';
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
+    it('returns records by requested identity ID when every key is processed', async () => {
+        const primaryRecord = {
+            pk: `identity#${pixelId}#${primaryIdentityId}`,
+            pixelId,
+            identityId: primaryIdentityId,
+            response: { identityId: primaryIdentityId, traits: { emails: ['primary@test.com'] } },
+            updatedAt: '2026-09-04T12:00:00.000Z',
+        };
+        mockedDynamoDbClient.batchGet.mockResolvedValue({
+            Responses: { [IDENTITY_CACHE_TABLE_NAME]: [primaryRecord] },
+            UnprocessedKeys: {},
+            $metadata: {},
+        });
+        const result = await IdentityCacheDynamoDbDbService.getClusterIdentityRecords(pixelId, [
+            primaryIdentityId,
+            secondaryIdentityId,
+        ]);
+        expect(result.complete).toBe(true);
+        expect(result.failedIdentityIds).toEqual([]);
+        expect(result.recordsByIdentityId.get(primaryIdentityId)).toEqual(primaryRecord);
+        expect(result.recordsByIdentityId.has(secondaryIdentityId)).toBe(false);
+    });
+    it('treats an unprocessed key as a failed read', async () => {
+        mockedDynamoDbClient.batchGet.mockResolvedValue({
+            Responses: { [IDENTITY_CACHE_TABLE_NAME]: [] },
+            UnprocessedKeys: {
+                [IDENTITY_CACHE_TABLE_NAME]: {
+                    Keys: [{ pk: `identity#${pixelId}#${secondaryIdentityId}` }],
+                },
+            },
+            $metadata: {},
+        });
+        const result = await IdentityCacheDynamoDbDbService.getClusterIdentityRecords(pixelId, [
+            primaryIdentityId,
+            secondaryIdentityId,
+        ]);
+        expect(result.complete).toBe(false);
+        expect(result.failedIdentityIds).toEqual([secondaryIdentityId]);
+    });
+    it('marks every key in a failed chunk as a failed read', async () => {
+        mockedDynamoDbClient.batchGet.mockRejectedValue(new Error('read failed'));
+        const result = await IdentityCacheDynamoDbDbService.getClusterIdentityRecords(pixelId, [
+            primaryIdentityId,
+            secondaryIdentityId,
+        ]);
+        expect(result.complete).toBe(false);
+        expect(result.failedIdentityIds).toEqual([primaryIdentityId, secondaryIdentityId]);
+    });
+    it('writes final primary traits and the migration marker in one item', async () => {
+        mockedDynamoDbClient.safePut.mockResolvedValue({ $metadata: { httpStatusCode: 200 } });
+        const success = await IdentityCacheDynamoDbDbService.putPrimaryIdentityTraits({
+            pixelId,
+            primaryIdentityId,
+            traits: { emails: ['merged@test.com'] },
+            traitsInDynamo: true,
+        });
+        expect(success).toBe(true);
+        expect(mockedDynamoDbClient.safePut).toHaveBeenCalledWith(expect.any(String), expect.objectContaining({
+            pk: `identity#${pixelId}#${primaryIdentityId}`,
+            identityId: primaryIdentityId,
+            traitsInDynamo: true,
+            response: {
+                identityId: primaryIdentityId,
+                traits: { emails: ['merged@test.com'] },
+            },
+        }));
+    });
+    it('reports a failed primary traits write', async () => {
+        mockedDynamoDbClient.safePut.mockResolvedValue(null);
+        const success = await IdentityCacheDynamoDbDbService.putPrimaryIdentityTraits({
+            pixelId,
+            primaryIdentityId,
+            traits: {},
+            traitsInDynamo: true,
+        });
+        expect(success).toBe(false);
+    });
+    it('deletes exact identity keys and returns unprocessed identity IDs', async () => {
+        mockedDynamoDbClient.batchWrite.mockResolvedValue({
+            UnprocessedItems: {
+                [IDENTITY_CACHE_TABLE_NAME]: [
+                    {
+                        DeleteRequest: { Key: { pk: `identity#${pixelId}#${secondaryIdentityId}` } },
+                    },
+                ],
+            },
+            $metadata: {},
+        });
+        const failedIdentityIds = await IdentityCacheDynamoDbDbService.deleteIdentityRecords(pixelId, [
+            primaryIdentityId,
+            secondaryIdentityId,
+        ]);
+        expect(failedIdentityIds).toEqual([secondaryIdentityId]);
+        expect(mockedDynamoDbClient.batchWrite).toHaveBeenCalledWith({
+            RequestItems: {
+                [IDENTITY_CACHE_TABLE_NAME]: [
+                    { DeleteRequest: { Key: { pk: `identity#${pixelId}#${primaryIdentityId}` } } },
+                    { DeleteRequest: { Key: { pk: `identity#${pixelId}#${secondaryIdentityId}` } } },
+                ],
+            },
+        });
+    });
+    it('returns every identity ID when an exact delete chunk fails', async () => {
+        mockedDynamoDbClient.batchWrite.mockRejectedValue(new Error('delete failed'));
+        const failedIdentityIds = await IdentityCacheDynamoDbDbService.deleteIdentityRecords(pixelId, [
+            primaryIdentityId,
+            secondaryIdentityId,
+        ]);
+        expect(failedIdentityIds).toEqual([primaryIdentityId, secondaryIdentityId]);
+    });
+    it('deduplicates requested identity IDs before issuing batchGet', async () => {
+        mockedDynamoDbClient.batchGet.mockResolvedValue({
+            Responses: { [IDENTITY_CACHE_TABLE_NAME]: [] },
+            UnprocessedKeys: {},
+            $metadata: {},
+        });
+        await IdentityCacheDynamoDbDbService.getClusterIdentityRecords(pixelId, [
+            primaryIdentityId,
+            primaryIdentityId,
+            secondaryIdentityId,
+        ]);
+        expect(mockedDynamoDbClient.batchGet).toHaveBeenCalledWith({
+            RequestItems: {
+                [IDENTITY_CACHE_TABLE_NAME]: {
+                    Keys: [
+                        { pk: `identity#${pixelId}#${primaryIdentityId}` },
+                        { pk: `identity#${pixelId}#${secondaryIdentityId}` },
+                    ],
+                },
+            },
+        });
+    });
+    it('treats a processed key with no returned item as a successful miss', async () => {
+        mockedDynamoDbClient.batchGet.mockResolvedValue({
+            Responses: { [IDENTITY_CACHE_TABLE_NAME]: [] },
+            UnprocessedKeys: {},
+            $metadata: {},
+        });
+        const result = await IdentityCacheDynamoDbDbService.getClusterIdentityRecords(pixelId, [
+            primaryIdentityId,
+            secondaryIdentityId,
+        ]);
+        expect(result.complete).toBe(true);
+        expect(result.failedIdentityIds).toEqual([]);
+        expect(result.recordsByIdentityId.size).toBe(0);
+    });
+    it('reports a failed primary traits write when safePut throws', async () => {
+        mockedDynamoDbClient.safePut.mockRejectedValue(new Error('put failed'));
+        const success = await IdentityCacheDynamoDbDbService.putPrimaryIdentityTraits({
+            pixelId,
+            primaryIdentityId,
+            traits: { emails: ['merged@test.com'] },
+            traitsInDynamo: true,
+        });
+        expect(success).toBe(false);
+        expect(mockedLogger.error).toHaveBeenCalledWith('IdentityCache [primary traits write]: failed', expect.objectContaining({ pixelId, primaryIdentityId }));
+    });
+    it('deletes exact identity PKs without querying GSI1', async () => {
+        mockedDynamoDbClient.batchWrite.mockResolvedValue({
+            UnprocessedItems: {},
+            $metadata: {},
+        });
+        await IdentityCacheDynamoDbDbService.deleteIdentityRecords(pixelId, [secondaryIdentityId]);
+        expect(mockedDynamoDbClient.safeQueryByGSI).not.toHaveBeenCalled();
+        expect(mockedDynamoDbClient.batchWrite).toHaveBeenCalledWith({
+            RequestItems: {
+                [IDENTITY_CACHE_TABLE_NAME]: [{ DeleteRequest: { Key: { pk: `identity#${pixelId}#${secondaryIdentityId}` } } }],
+            },
+        });
+    });
+    it('logs cluster read completion with requested identity IDs', async () => {
+        mockedDynamoDbClient.batchGet.mockResolvedValue({
+            Responses: { [IDENTITY_CACHE_TABLE_NAME]: [] },
+            UnprocessedKeys: {},
+            $metadata: {},
+        });
+        await IdentityCacheDynamoDbDbService.getClusterIdentityRecords(pixelId, [primaryIdentityId]);
+        expect(mockedLogger.debug).toHaveBeenCalledWith('IdentityCache [cluster traits read]: completed', expect.objectContaining({
+            pixelId,
+            identityIds: [primaryIdentityId],
+        }));
+    });
+});
+describe('mergeAndComputeIdentityStaleness (pure function)', () => {
+    describe('merge behavior', () => {
+        it('should merge incoming traits with cached traits', () => {
+            const incomingIdentity = {
+                identityId: 'merge-test',
+                traits: {
+                    emails: ['new@email.com'],
+                },
+            };
+            const cachedIdentity = {
+                identityId: 'merge-test',
+                traits: {
+                    emails: ['cached@email.com'],
+                    phones: ['555-1234'],
+                },
+            };
+            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
+            expect(result.mergedIdentity.traits?.emails).toContain('new@email.com');
+            expect(result.mergedIdentity.traits?.emails).toContain('cached@email.com');
+            expect(result.mergedIdentity.traits?.phones).toContain('555-1234');
+        });
+    });
+    describe('staleness tier computation', () => {
+        it('should return NONE tier when no traits are stale', () => {
+            const incomingIdentity = {
+                identityId: 'same-test',
+                traits: { emails: ['same@email.com'] },
+            };
+            const cachedIdentity = {
+                identityId: 'same-test',
+                traits: { emails: ['same@email.com'] },
+            };
+            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
+            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.NONE);
+            expect(result.isCacheStale).toBe(false);
+        });
+        it('should return VOLATILE_ONLY tier when incoming has new IP address (cached has none)', () => {
+            const incomingIdentity = {
+                identityId: 'volatile-test',
+                traits: {
+                    emails: ['same@email.com'],
+                    ipAddress: '192.168.1.100',
+                },
+            };
+            const cachedIdentity = {
+                identityId: 'volatile-test',
+                traits: {
+                    emails: ['same@email.com'],
+                },
+            };
+            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
+            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.VOLATILE_ONLY);
+            expect(result.isCacheStale).toBe(false);
+        });
+        it('should return ADDRESS_UPDATE tier when non-IP address is new', () => {
+            const incomingIdentity = {
+                identityId: 'address-test',
+                traits: {
+                    emails: ['same@email.com'],
+                    addresses: [{ firstName: 'John', city: 'New York' }],
+                },
+            };
+            const cachedIdentity = {
+                identityId: 'address-test',
+                traits: {
+                    emails: ['same@email.com'],
+                    addresses: [],
+                },
+            };
+            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
+            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.ADDRESS_UPDATE);
+            expect(result.isCacheStale).toBe(true);
+        });
+        it('should return IDENTITY_STALE tier when email changes', () => {
+            const incomingIdentity = {
+                identityId: 'stale-test',
+                traits: {
+                    emails: ['new@email.com'],
+                },
+            };
+            const cachedIdentity = {
+                identityId: 'stale-test',
+                traits: {
+                    emails: ['old@email.com'],
+                },
+            };
+            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
+            expect(result.staleTier).toBe(IDENTITY_CACHE_STALENESS_TIER.IDENTITY_STALE);
+            expect(result.isCacheStale).toBe(true);
+        });
+    });
+    describe('staleTraits extraction', () => {
+        it('should include changed trait names in staleTraits array', () => {
+            const incomingIdentity = {
+                identityId: 'traits-test',
+                traits: {
+                    emails: ['new@email.com'],
+                    phones: ['999-0000'],
+                },
+            };
+            const cachedIdentity = {
+                identityId: 'traits-test',
+                traits: {
+                    emails: ['old@email.com'],
+                    phones: ['111-2222'],
+                },
+            };
+            const result = mergeAndComputeIdentityStaleness(incomingIdentity, cachedIdentity);
+            expect(result.staleTraits).toContain('emails');
+            expect(result.staleTraits).toContain('phones');
+        });
+    });
+});
 //# sourceMappingURL=identity-cache-dynamodb-db-service.spec.js.map