@adtrackify/at-service-common 4.0.5 → 4.0.6

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

@@ -0,0 +1,644 @@
+import { ADDRESS_INFO_SOURCE } from '@adtrackify/at-tracking-event-types';
+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(),
+    },
+}));
+jest.mock('../../helpers/index.js', () => ({
+    Logger: {
+        debug: jest.fn(),
+        info: jest.fn(),
+        warn: jest.fn(),
+        error: jest.fn(),
+    },
+}));
+import { DynamoDbClient } from '../../clients/index.js';
+import { Logger } from '../../helpers/index.js';
+import { IdentityCacheDynamoDbDbService } from '../../services/db/identity-cache-dynamodb-service/identity-cache-dynamodb-db-service.js';
+import { CACHE_WRITE_REASON, IDENTITY_CACHE_LOOKUP_OUTCOME, } from '../../services/db/identity-cache-dynamodb-service/types.js';
+const mockedDynamoDbClient = DynamoDbClient;
+const mockedLogger = Logger;
+const pixelId = 'pixel-cache-lookup-v2';
+let dateNowSpy;
+const deepClone = (value) => {
+    if (value === undefined) {
+        return value;
+    }
+    return JSON.parse(JSON.stringify(value));
+};
+const normalizeDynamicValues = (value) => {
+    if (Array.isArray(value)) {
+        return value.map(normalizeDynamicValues);
+    }
+    if (value && typeof value === 'object') {
+        const normalized = {};
+        for (const [key, objectValue] of Object.entries(value)) {
+            if (key === 'updatedAt' || key === 'createdAt') {
+                normalized[key] = '<timestamp>';
+            }
+            else {
+                normalized[key] = normalizeDynamicValues(objectValue);
+            }
+        }
+        return normalized;
+    }
+    return value;
+};
+const cloneCalls = (mockFunction) => normalizeDynamicValues(deepClone(mockFunction.mock.calls));
+const captureDynamoDbCalls = () => ({
+    safeGet: cloneCalls(mockedDynamoDbClient.safeGet),
+    safePut: cloneCalls(mockedDynamoDbClient.safePut),
+    safeDelete: cloneCalls(mockedDynamoDbClient.safeDelete),
+    safeBatchGet: cloneCalls(mockedDynamoDbClient.safeBatchGet),
+    safeBatchWrite: cloneCalls(mockedDynamoDbClient.safeBatchWrite),
+    safeQueryByGSI: cloneCalls(mockedDynamoDbClient.safeQueryByGSI),
+    batchWrite: cloneCalls(mockedDynamoDbClient.batchWrite),
+});
+const captureLoggerCalls = () => ({
+    debug: cloneCalls(mockedLogger.debug),
+    info: cloneCalls(mockedLogger.info),
+    warn: cloneCalls(mockedLogger.warn),
+    error: cloneCalls(mockedLogger.error),
+});
+const resetMocksForRun = () => {
+    dateNowSpy?.mockRestore();
+    dateNowSpy = jest.spyOn(Date, 'now').mockReturnValue(1782532911813);
+    jest.clearAllMocks();
+    mockedDynamoDbClient.safeGet.mockReset();
+    mockedDynamoDbClient.safePut.mockReset();
+    mockedDynamoDbClient.safeDelete.mockReset();
+    mockedDynamoDbClient.safeBatchGet.mockReset();
+    mockedDynamoDbClient.safeBatchWrite.mockReset();
+    mockedDynamoDbClient.safeQueryByGSI.mockReset();
+    mockedDynamoDbClient.batchWrite.mockReset();
+};
+const buildCachedRecord = (identity) => ({
+    pk: `identity#${pixelId}#${identity.identityId}`,
+    pixelId,
+    identityId: identity.identityId ?? 'missing-id',
+    response: deepClone(identity),
+    updatedAt: '2026-01-01T00:00:00.000Z',
+});
+const runOriginal = async (scenario) => {
+    resetMocksForRun();
+    scenario.setupMocks();
+    const cacheResult = await IdentityCacheDynamoDbDbService.getIdentityFromCache(pixelId, deepClone(scenario.incomingIdentity));
+    return {
+        cacheResult: normalizeDynamicValues(deepClone(cacheResult)),
+        dynamoDbCalls: captureDynamoDbCalls(),
+        loggerCalls: captureLoggerCalls(),
+    };
+};
+const runV2 = async (scenario) => {
+    resetMocksForRun();
+    scenario.setupMocks();
+    const result = await IdentityCacheDynamoDbDbService.getIdentityFromCacheV2(pixelId, deepClone(scenario.incomingIdentity));
+    return {
+        cacheResult: normalizeDynamicValues(deepClone(result.cacheResult)),
+        summary: normalizeDynamicValues(deepClone(result.summary)),
+        dynamoDbCalls: captureDynamoDbCalls(),
+        loggerCalls: captureLoggerCalls(),
+    };
+};
+const expectV2ToMatchOriginal = async (scenario) => {
+    const originalRun = await runOriginal(scenario);
+    const v2Run = await runV2(scenario);
+    expect(v2Run.cacheResult).toEqual(originalRun.cacheResult);
+    expect(v2Run.dynamoDbCalls).toEqual(originalRun.dynamoDbCalls);
+    expect(v2Run.loggerCalls).toEqual(originalRun.loggerCalls);
+    expect(v2Run.summary.outcome).toBe(scenario.expectedOutcome);
+    scenario.assertSummary?.(v2Run.summary);
+    return { originalRun, v2Run };
+};
+describe('IdentityCacheDynamoDbDbService getIdentityFromCache() vs getIdentityFromCacheV2()', () => {
+    it('matches invalid input behavior', async () => {
+        await expectV2ToMatchOriginal({
+            incomingIdentity: null,
+            expectedOutcome: IDENTITY_CACHE_LOOKUP_OUTCOME.INVALID_INPUT,
+            setupMocks: () => undefined,
+            assertSummary: (summary) => {
+                expect(summary.isCacheStale).toBe(true);
+                expect(summary.writeReason).toBe(CACHE_WRITE_REASON.CACHE_MISS);
+            },
+        });
+    });
+    it('matches primary identity cache miss behavior', async () => {
+        await expectV2ToMatchOriginal({
+            incomingIdentity: {
+                identityId: 'missing-primary',
+                traits: { emails: ['missing@example.com'] },
+            },
+            expectedOutcome: IDENTITY_CACHE_LOOKUP_OUTCOME.PRIMARY_CACHE_MISS,
+            setupMocks: () => {
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
+            },
+            assertSummary: (summary) => {
+                expect(summary.didLookupByIdentityId).toBe(true);
+                expect(summary.didLookupByEmail).toBe(false);
+                expect(summary.writeReason).toBe(CACHE_WRITE_REASON.CACHE_MISS);
+            },
+        });
+    });
+    it('matches cached identity without response behavior', async () => {
+        await expectV2ToMatchOriginal({
+            incomingIdentity: {
+                identityId: 'missing-response',
+                traits: { emails: ['missing-response@example.com'] },
+            },
+            expectedOutcome: IDENTITY_CACHE_LOOKUP_OUTCOME.PRIMARY_CACHE_MISS_NO_RESPONSE,
+            setupMocks: () => {
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce({
+                    pk: `identity#${pixelId}#missing-response`,
+                    pixelId,
+                    identityId: 'missing-response',
+                    updatedAt: '2026-01-01T00:00:00.000Z',
+                });
+            },
+            assertSummary: (summary) => {
+                expect(summary.didLookupByIdentityId).toBe(true);
+                expect(summary.isCacheStale).toBe(true);
+            },
+        });
+    });
+    it('matches primary cache hit behavior when traits are equal', async () => {
+        const cachedIdentity = {
+            identityId: 'fresh-primary',
+            traits: { emails: ['fresh@example.com'] },
+        };
+        await expectV2ToMatchOriginal({
+            incomingIdentity: deepClone(cachedIdentity),
+            expectedOutcome: IDENTITY_CACHE_LOOKUP_OUTCOME.PRIMARY_CACHE_HIT,
+            setupMocks: () => {
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(buildCachedRecord(cachedIdentity));
+            },
+            assertSummary: (summary) => {
+                expect(summary.didLookupByIdentityId).toBe(true);
+                expect(summary.isDeepEqual).toBe(true);
+                expect(summary.isCacheStale).toBe(false);
+            },
+        });
+    });
+    it('matches primary stale behavior for identity traits', async () => {
+        const cachedIdentity = {
+            identityId: 'stale-primary',
+            traits: { emails: ['old@example.com'] },
+        };
+        await expectV2ToMatchOriginal({
+            incomingIdentity: {
+                identityId: 'stale-primary',
+                traits: { emails: ['old@example.com', 'new@example.com'] },
+            },
+            expectedOutcome: IDENTITY_CACHE_LOOKUP_OUTCOME.PRIMARY_CACHE_STALE,
+            setupMocks: () => {
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(buildCachedRecord(cachedIdentity));
+            },
+            assertSummary: (summary) => {
+                expect(summary.isCacheStale).toBe(true);
+                expect(summary.writeReason).toBe(CACHE_WRITE_REASON.STALE_TRAITS);
+                expect(summary.skipNeptune).toBe(false);
+                expect(summary.staleTraits).toContain('emails');
+            },
+        });
+    });
+    it('matches primary address update behavior', async () => {
+        const cachedIdentity = {
+            identityId: 'address-primary',
+            traits: {
+                emails: ['address@example.com'],
+                addresses: [],
+            },
+        };
+        await expectV2ToMatchOriginal({
+            incomingIdentity: {
+                identityId: 'address-primary',
+                traits: {
+                    emails: ['address@example.com'],
+                    addresses: [{ city: 'Boston', s: ADDRESS_INFO_SOURCE.INPUT }],
+                },
+            },
+            expectedOutcome: IDENTITY_CACHE_LOOKUP_OUTCOME.PRIMARY_CACHE_STALE,
+            setupMocks: () => {
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(buildCachedRecord(cachedIdentity));
+            },
+            assertSummary: (summary) => {
+                expect(summary.writeReason).toBe(CACHE_WRITE_REASON.ADDRESS_UPDATE);
+                expect(summary.skipNeptune).toBe(true);
+                expect(summary.staleTraits).toContain('addresses');
+            },
+        });
+    });
+    it('matches volatile-only behavior', async () => {
+        const cachedIdentity = {
+            identityId: 'volatile-primary',
+            traits: {
+                emails: ['volatile@example.com'],
+                ipAddress: '192.168.1.1',
+            },
+        };
+        await expectV2ToMatchOriginal({
+            incomingIdentity: {
+                identityId: 'volatile-primary',
+                traits: {
+                    emails: ['volatile@example.com'],
+                    ipAddress: '10.0.0.1',
+                },
+            },
+            expectedOutcome: IDENTITY_CACHE_LOOKUP_OUTCOME.PRIMARY_CACHE_HIT,
+            setupMocks: () => {
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(buildCachedRecord(cachedIdentity));
+            },
+            assertSummary: (summary) => {
+                expect(summary.isCacheStale).toBe(false);
+                expect(summary.writeReason).toBeUndefined();
+            },
+        });
+    });
+    it('matches email pointer discovery behavior', async () => {
+        await expectV2ToMatchOriginal({
+            incomingIdentity: {
+                traits: { emails: ['pointer@example.com'] },
+            },
+            expectedOutcome: IDENTITY_CACHE_LOOKUP_OUTCOME.EMAIL_POINTER_DISCOVERY,
+            setupMocks: () => {
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce({
+                    pk: `email#${pixelId}#pointer@example.com`,
+                    pixelId,
+                    identityId: 'discovered-id',
+                    gsi1pk: 'discovered-id',
+                    updatedAt: '2026-01-01T00:00:00.000Z',
+                });
+            },
+            assertSummary: (summary) => {
+                expect(summary.didLookupByEmail).toBe(true);
+                expect(summary.discoveredIdentityId).toBe('discovered-id');
+                expect(summary.writeReason).toBe(CACHE_WRITE_REASON.EMAIL_POINTER_DISCOVERY);
+            },
+        });
+    });
+    it('matches email pointer miss behavior', async () => {
+        await expectV2ToMatchOriginal({
+            incomingIdentity: {
+                traits: { emails: ['missing-pointer@example.com'] },
+            },
+            expectedOutcome: IDENTITY_CACHE_LOOKUP_OUTCOME.EMAIL_POINTER_MISS,
+            setupMocks: () => {
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(null);
+            },
+            assertSummary: (summary) => {
+                expect(summary.didLookupByEmail).toBe(true);
+                expect(summary.writeReason).toBe(CACHE_WRITE_REASON.CACHE_MISS);
+            },
+        });
+    });
+    it('matches no-email miss behavior without reading DynamoDB', async () => {
+        await expectV2ToMatchOriginal({
+            incomingIdentity: {
+                traits: { userIds: ['user-only'] },
+            },
+            expectedOutcome: IDENTITY_CACHE_LOOKUP_OUTCOME.EMAIL_POINTER_MISS,
+            setupMocks: () => undefined,
+            assertSummary: (summary) => {
+                expect(summary.didLookupByEmail).toBe(false);
+                expect(summary.writeReason).toBe(CACHE_WRITE_REASON.CACHE_MISS);
+            },
+        });
+    });
+    it('matches fail-open behavior when primary lookup throws', async () => {
+        await expectV2ToMatchOriginal({
+            incomingIdentity: {
+                identityId: 'throws-primary',
+                traits: { emails: ['throws@example.com'] },
+            },
+            expectedOutcome: IDENTITY_CACHE_LOOKUP_OUTCOME.PRIMARY_CACHE_MISS,
+            setupMocks: () => {
+                mockedDynamoDbClient.safeGet.mockRejectedValueOnce(new Error('dynamo failed'));
+            },
+            assertSummary: (summary) => {
+                expect(summary.errorMessage).toBeUndefined();
+                expect(summary.writeReason).toBe(CACHE_WRITE_REASON.CACHE_MISS);
+            },
+        });
+    });
+    it('matches fail-open behavior when email lookup throws', async () => {
+        await expectV2ToMatchOriginal({
+            incomingIdentity: {
+                traits: { emails: ['throws-email@example.com'] },
+            },
+            expectedOutcome: IDENTITY_CACHE_LOOKUP_OUTCOME.EMAIL_POINTER_MISS,
+            setupMocks: () => {
+                mockedDynamoDbClient.safeGet.mockRejectedValueOnce(new Error('email lookup dynamo failed'));
+            },
+            assertSummary: (summary) => {
+                expect(summary.didLookupByEmail).toBe(true);
+                expect(summary.errorMessage).toBeUndefined();
+                expect(summary.writeReason).toBe(CACHE_WRITE_REASON.CACHE_MISS);
+                expect(summary.discoveredIdentityId).toBeUndefined();
+            },
+        });
+    });
+    it('matches primary cache hit with null traits on cached identity', async () => {
+        const cachedIdentity = {
+            identityId: 'null-traits-primary',
+            traits: null,
+        };
+        await expectV2ToMatchOriginal({
+            incomingIdentity: {
+                identityId: 'null-traits-primary',
+                traits: { emails: ['incoming@example.com'] },
+            },
+            expectedOutcome: IDENTITY_CACHE_LOOKUP_OUTCOME.PRIMARY_CACHE_STALE,
+            setupMocks: () => {
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(buildCachedRecord(cachedIdentity));
+            },
+            assertSummary: (summary) => {
+                expect(summary.didLookupByIdentityId).toBe(true);
+                expect(summary.isCacheStale).toBe(true);
+                expect(summary.cachedIdentity).toEqual(cachedIdentity);
+                expect(summary.mergedIdentity?.traits?.emails).toContain('incoming@example.com');
+            },
+        });
+    });
+    it('matches primary cache hit with empty traits object on cached identity', async () => {
+        const cachedIdentity = {
+            identityId: 'empty-traits-primary',
+            traits: {},
+        };
+        await expectV2ToMatchOriginal({
+            incomingIdentity: {
+                identityId: 'empty-traits-primary',
+                traits: { emails: ['new@example.com'] },
+            },
+            expectedOutcome: IDENTITY_CACHE_LOOKUP_OUTCOME.PRIMARY_CACHE_STALE,
+            setupMocks: () => {
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(buildCachedRecord(cachedIdentity));
+            },
+            assertSummary: (summary) => {
+                expect(summary.didLookupByIdentityId).toBe(true);
+                expect(summary.isCacheStale).toBe(true);
+                expect(summary.mergedIdentity?.traits?.emails).toContain('new@example.com');
+            },
+        });
+    });
+    it('matches primary cache hit when incoming has empty traits (subset of cached)', async () => {
+        const cachedIdentity = {
+            identityId: 'incoming-empty-traits',
+            traits: { emails: ['cached@example.com'], phones: ['+1234567890'] },
+        };
+        await expectV2ToMatchOriginal({
+            incomingIdentity: {
+                identityId: 'incoming-empty-traits',
+                traits: {},
+            },
+            expectedOutcome: IDENTITY_CACHE_LOOKUP_OUTCOME.PRIMARY_CACHE_HIT,
+            setupMocks: () => {
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(buildCachedRecord(cachedIdentity));
+            },
+            assertSummary: (summary) => {
+                expect(summary.didLookupByIdentityId).toBe(true);
+                expect(summary.isCacheStale).toBe(false);
+                expect(summary.isDeepEqual).toBe(true);
+                expect(summary.mergedIdentity?.traits?.emails).toContain('cached@example.com');
+                expect(summary.mergedIdentity?.traits?.phones).toContain('+1234567890');
+            },
+        });
+    });
+    it('matches timestamp stripping behavior - addresses differ only by timestamp', async () => {
+        const cachedIdentity = {
+            identityId: 'timestamp-diff-primary',
+            traits: {
+                emails: ['timestamp@example.com'],
+                addresses: [
+                    { city: 'Boston', s: ADDRESS_INFO_SOURCE.INPUT, cra: 1704067200000, upa: 1704067200000 },
+                ],
+            },
+        };
+        const incomingIdentity = {
+            identityId: 'timestamp-diff-primary',
+            traits: {
+                emails: ['timestamp@example.com'],
+                addresses: [
+                    { city: 'Boston', s: ADDRESS_INFO_SOURCE.INPUT, cra: 1717200000000, upa: 1718409600000 },
+                ],
+            },
+        };
+        await expectV2ToMatchOriginal({
+            incomingIdentity,
+            expectedOutcome: IDENTITY_CACHE_LOOKUP_OUTCOME.PRIMARY_CACHE_HIT,
+            setupMocks: () => {
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(buildCachedRecord(cachedIdentity));
+            },
+            assertSummary: (summary) => {
+                expect(summary.didLookupByIdentityId).toBe(true);
+                expect(summary.isDeepEqual).toBe(true);
+                expect(summary.isCacheStale).toBe(false);
+                expect(summary.writeReason).toBeUndefined();
+            },
+        });
+    });
+    it('verifies summary fields populated on primary cache hit', async () => {
+        const cachedIdentity = {
+            identityId: 'summary-hit-primary',
+            traits: { emails: ['summary-hit@example.com'], phones: ['+1111111111'] },
+        };
+        const incomingIdentity = {
+            identityId: 'summary-hit-primary',
+            traits: { emails: ['summary-hit@example.com'] },
+        };
+        const { v2Run } = await expectV2ToMatchOriginal({
+            incomingIdentity,
+            expectedOutcome: IDENTITY_CACHE_LOOKUP_OUTCOME.PRIMARY_CACHE_HIT,
+            setupMocks: () => {
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(buildCachedRecord(cachedIdentity));
+            },
+            assertSummary: (summary) => {
+                expect(summary.cachedIdentity).toEqual(cachedIdentity);
+                expect(summary.incomingIdentity).toEqual(incomingIdentity);
+                expect(summary.mergedIdentity).toBeDefined();
+                expect(summary.mergedIdentity?.traits?.emails).toContain('summary-hit@example.com');
+                expect(summary.mergedIdentity?.traits?.phones).toContain('+1111111111');
+                expect(summary.resolvedIdentity).toEqual(summary.mergedIdentity);
+                expect(summary.incomingClick).toBeNull();
+                expect(summary.cachedClick).toBeNull();
+                expect(summary.mergedClick).toBeNull();
+            },
+        });
+        const cacheResult = v2Run.cacheResult;
+        expect(cacheResult.resolvedIdentity).toEqual(v2Run.summary.mergedIdentity);
+        expect(cacheResult.isCacheStale).toBe(false);
+        expect(cacheResult.cachedIdentity).toEqual(cachedIdentity);
+        expect(cacheResult.staleTracker).toBeUndefined();
+        expect(cacheResult.writeReason).toBeUndefined();
+    });
+    it('verifies staleTracker present only when stale', async () => {
+        const cachedIdentity = {
+            identityId: 'stale-tracker-primary',
+            traits: { emails: ['old@example.com'] },
+        };
+        const staleIncoming = {
+            identityId: 'stale-tracker-primary',
+            traits: { emails: ['old@example.com', 'new@example.com'] },
+        };
+        const { v2Run: staleRun } = await expectV2ToMatchOriginal({
+            incomingIdentity: staleIncoming,
+            expectedOutcome: IDENTITY_CACHE_LOOKUP_OUTCOME.PRIMARY_CACHE_STALE,
+            setupMocks: () => {
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(buildCachedRecord(cachedIdentity));
+            },
+            assertSummary: (summary) => {
+                expect(summary.isCacheStale).toBe(true);
+            },
+        });
+        const staleCacheResult = staleRun.cacheResult;
+        expect(staleCacheResult.staleTracker).toEqual(expect.objectContaining({
+            isCacheStale: true,
+            isEmailsStale: true,
+        }));
+        const freshIncoming = {
+            identityId: 'stale-tracker-primary',
+            traits: { emails: ['old@example.com'] },
+        };
+        const { v2Run: freshRun } = await expectV2ToMatchOriginal({
+            incomingIdentity: freshIncoming,
+            expectedOutcome: IDENTITY_CACHE_LOOKUP_OUTCOME.PRIMARY_CACHE_HIT,
+            setupMocks: () => {
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(buildCachedRecord(cachedIdentity));
+            },
+            assertSummary: (summary) => {
+                expect(summary.isCacheStale).toBe(false);
+            },
+        });
+        const freshCacheResult = freshRun.cacheResult;
+        expect(freshCacheResult.staleTracker).toBeUndefined();
+    });
+    it('verifies summary fields populated on primary cache stale', async () => {
+        const cachedIdentity = {
+            identityId: 'summary-stale-primary',
+            traits: { emails: ['old@example.com'] },
+        };
+        const incomingIdentity = {
+            identityId: 'summary-stale-primary',
+            traits: { emails: ['old@example.com', 'new@example.com'], phones: ['+1234567890'] },
+        };
+        await expectV2ToMatchOriginal({
+            incomingIdentity,
+            expectedOutcome: IDENTITY_CACHE_LOOKUP_OUTCOME.PRIMARY_CACHE_STALE,
+            setupMocks: () => {
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(buildCachedRecord(cachedIdentity));
+            },
+            assertSummary: (summary) => {
+                expect(summary.cachedIdentity).toEqual(cachedIdentity);
+                expect(summary.incomingIdentity).toEqual(incomingIdentity);
+                expect(summary.mergedIdentity).toBeDefined();
+                expect(summary.mergedIdentity?.traits?.emails).toContain('old@example.com');
+                expect(summary.mergedIdentity?.traits?.emails).toContain('new@example.com');
+                expect(summary.mergedIdentity?.traits?.phones).toContain('+1234567890');
+                expect(summary.resolvedIdentity).toEqual(summary.mergedIdentity);
+                expect(summary.staleTier).toBeDefined();
+                expect(summary.staleTraits.length).toBeGreaterThan(0);
+            },
+        });
+    });
+    it('matches cache miss summary with correct flags', async () => {
+        await expectV2ToMatchOriginal({
+            incomingIdentity: {
+                traits: { userIds: ['user-only-no-email'] },
+            },
+            expectedOutcome: IDENTITY_CACHE_LOOKUP_OUTCOME.EMAIL_POINTER_MISS,
+            setupMocks: () => undefined,
+            assertSummary: (summary) => {
+                expect(summary.didLookupByIdentityId).toBe(false);
+                expect(summary.didLookupByEmail).toBe(false);
+                expect(summary.isCacheStale).toBe(true);
+                expect(summary.writeReason).toBe(CACHE_WRITE_REASON.CACHE_MISS);
+                expect(summary.cachedIdentity).toBeUndefined();
+                expect(summary.mergedIdentity).toBeUndefined();
+                expect(summary.resolvedIdentity).toBeUndefined();
+                expect(summary.discoveredIdentityId).toBeUndefined();
+                expect(summary.staleTraits).toEqual([]);
+            },
+        });
+    });
+    it('matches email pointer discovery summary fields', async () => {
+        const incomingIdentity = {
+            traits: { emails: ['discovery-summary@example.com'], phones: ['+9999999999'] },
+        };
+        await expectV2ToMatchOriginal({
+            incomingIdentity,
+            expectedOutcome: IDENTITY_CACHE_LOOKUP_OUTCOME.EMAIL_POINTER_DISCOVERY,
+            setupMocks: () => {
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce({
+                    pk: `email#${pixelId}#discovery-summary@example.com`,
+                    pixelId,
+                    identityId: 'discovered-summary-id',
+                    gsi1pk: 'discovered-summary-id',
+                    updatedAt: '2026-01-01T00:00:00.000Z',
+                });
+            },
+            assertSummary: (summary) => {
+                expect(summary.didLookupByEmail).toBe(true);
+                expect(summary.discoveredIdentityId).toBe('discovered-summary-id');
+                expect(summary.resolvedIdentity?.identityId).toBe('discovered-summary-id');
+                expect(summary.resolvedIdentity?.traits?.emails).toContain('discovery-summary@example.com');
+                expect(summary.resolvedIdentity?.traits?.phones).toContain('+9999999999');
+                expect(summary.cachedIdentity).toBeUndefined();
+                expect(summary.mergedIdentity).toBeUndefined();
+            },
+        });
+    });
+    it('matches volatile-only with source field changes treated as cache hit', async () => {
+        const cachedIdentity = {
+            identityId: 'volatile-source-primary',
+            traits: {
+                emails: ['volatile-source@example.com'],
+                addresses: [{ city: 'Boston', s: ADDRESS_INFO_SOURCE.INPUT }],
+                ipAddress: '192.168.1.1',
+                userAgent: 'Mozilla/5.0 Old',
+            },
+        };
+        const incomingIdentity = {
+            identityId: 'volatile-source-primary',
+            traits: {
+                emails: ['volatile-source@example.com'],
+                addresses: [{ city: 'Boston', s: ADDRESS_INFO_SOURCE.INPUT }],
+                ipAddress: '10.0.0.1',
+                userAgent: 'Mozilla/5.0 New',
+            },
+        };
+        await expectV2ToMatchOriginal({
+            incomingIdentity,
+            expectedOutcome: IDENTITY_CACHE_LOOKUP_OUTCOME.PRIMARY_CACHE_HIT,
+            setupMocks: () => {
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(buildCachedRecord(cachedIdentity));
+            },
+            assertSummary: (summary) => {
+                expect(summary.isCacheStale).toBe(false);
+                expect(summary.writeReason).toBeUndefined();
+                expect(summary.skipNeptune).toBeUndefined();
+            },
+        });
+    });
+    it('matches skipNeptune undefined when cache is fresh', async () => {
+        const cachedIdentity = {
+            identityId: 'skip-neptune-fresh',
+            traits: { emails: ['fresh@example.com'] },
+        };
+        await expectV2ToMatchOriginal({
+            incomingIdentity: deepClone(cachedIdentity),
+            expectedOutcome: IDENTITY_CACHE_LOOKUP_OUTCOME.PRIMARY_CACHE_HIT,
+            setupMocks: () => {
+                mockedDynamoDbClient.safeGet.mockResolvedValueOnce(buildCachedRecord(cachedIdentity));
+            },
+            assertSummary: (summary) => {
+                expect(summary.isCacheStale).toBe(false);
+                expect(summary.skipNeptune).toBeUndefined();
+            },
+        });
+    });
+});
+//# sourceMappingURL=identity-cache-dynamodb-db-service-v2-comparison.spec.js.map