@adtrackify/at-service-common 5.1.0 → 5.1.2

package/dist/esm/__tests__/clients/sqs-unbundle.spec.js

@@ -1,1356 +1,1357 @@
-import { unbundleRecords, unbundleMessage, isBundledEnvelope } from '../../clients/generic/sqs-unbundle';
-import { CompressionAlgorithm } from '../../clients/generic/sqs-bundled-client.types';
-import { compress, CompressionTimeoutError, CompressionOperation, getGzipUncompressedSize, } from '../../utils/compression';
-import { gzip } from 'node:zlib';
-import { promisify } from 'node:util';
-const gzipAsync = promisify(gzip);
-jest.mock('../../helpers/logging-helper', () => ({
-    Logger: {
-        debug: jest.fn(),
-        info: jest.fn(),
-        warn: jest.fn(),
-        error: jest.fn(),
-    },
-}));
-function makeTestEvent(id, name = 'test_event', value) {
-    return { eventId: id, name, value };
-}
-function makeSqsRecord(body, messageId = 'msg-1') {
-    return {
-        messageId,
-        body: typeof body === 'string' ? body : JSON.stringify(body),
-    };
-}
-function makeBundledEnvelope(items) {
-    return {
-        v: 1,
-        c: CompressionAlgorithm.NONE,
-        n: items.length,
-        s: JSON.stringify(items).length,
-        p: items,
-    };
-}
-async function makeCompressedEnvelope(items, level = 3) {
-    const json = JSON.stringify(items);
-    const compressed = await compress(Buffer.from(json, 'utf8'), CompressionAlgorithm.ZSTD, level);
-    const base64 = compressed.toString('base64');
-    return {
-        v: 1,
-        c: CompressionAlgorithm.ZSTD,
-        n: items.length,
-        s: json.length,
-        p: base64,
-    };
-}
-async function makeGzipCompressedEnvelope(items) {
-    const json = JSON.stringify(items);
-    const compressed = await gzipAsync(Buffer.from(json, 'utf8'));
-    const base64 = compressed.toString('base64');
-    return {
-        v: 1,
-        c: CompressionAlgorithm.GZIP,
-        n: items.length,
-        s: json.length,
-        p: base64,
-    };
-}
-describe('isBundledEnvelope', () => {
-    it('returns true for valid bundled envelope with NONE compression', () => {
-        const envelope = makeBundledEnvelope([makeTestEvent('1')]);
-        expect(isBundledEnvelope(envelope)).toBe(true);
-    });
-    it('returns true for valid bundled envelope with ZSTD compression', async () => {
-        const envelope = await makeCompressedEnvelope([makeTestEvent('1')]);
-        expect(isBundledEnvelope(envelope)).toBe(true);
-    });
-    it('returns false for null', () => {
-        expect(isBundledEnvelope(null)).toBe(false);
-    });
-    it('returns false for undefined', () => {
-        expect(isBundledEnvelope(undefined)).toBe(false);
-    });
-    it('returns false for plain object (legacy message)', () => {
-        expect(isBundledEnvelope(makeTestEvent('1'))).toBe(false);
-    });
-    it('returns false for wrong version', () => {
-        const envelope = { v: 2, c: 'none', n: 1, p: [] };
-        expect(isBundledEnvelope(envelope)).toBe(false);
-    });
-    it('returns true for valid bundled envelope with GZIP compression', async () => {
-        const envelope = await makeGzipCompressedEnvelope([makeTestEvent('1')]);
-        expect(isBundledEnvelope(envelope)).toBe(true);
-    });
-    it('returns false for invalid compression algorithm', () => {
-        const envelope = { v: 1, c: 'lz4', n: 1, p: [] };
-        expect(isBundledEnvelope(envelope)).toBe(false);
-    });
-    it('returns false for missing count', () => {
-        const envelope = { v: 1, c: 'none', p: [] };
-        expect(isBundledEnvelope(envelope)).toBe(false);
-    });
-    it('returns false for missing payload', () => {
-        const envelope = { v: 1, c: 'none', n: 1 };
-        expect(isBundledEnvelope(envelope)).toBe(false);
-    });
-});
-describe('unbundleMessage', () => {
-    it('unbundles NONE compression envelope', async () => {
-        const items = [makeTestEvent('1'), makeTestEvent('2')];
-        const envelope = makeBundledEnvelope(items);
-        const result = await unbundleMessage(envelope);
-        expect(result).toHaveLength(2);
-        expect(result[0].eventId).toBe('1');
-        expect(result[1].eventId).toBe('2');
-    });
-    it('unbundles ZSTD compressed envelope', async () => {
-        const items = [makeTestEvent('1'), makeTestEvent('2'), makeTestEvent('3')];
-        const envelope = await makeCompressedEnvelope(items);
-        const result = await unbundleMessage(envelope);
-        expect(result).toHaveLength(3);
-        expect(result[0].eventId).toBe('1');
-        expect(result[1].eventId).toBe('2');
-        expect(result[2].eventId).toBe('3');
-    });
-    it('unbundles large batches with ZSTD compression', async () => {
-        const items = Array.from({ length: 500 }, (_, i) => makeTestEvent(`event-${i}`, `event_${i}`, i * 10));
-        const envelope = await makeCompressedEnvelope(items);
-        const result = await unbundleMessage(envelope);
-        expect(result).toHaveLength(500);
-        expect(result[0].eventId).toBe('event-0');
-        expect(result[499].eventId).toBe('event-499');
-    });
-    it('throws on unsupported bundle version', async () => {
-        const envelope = { v: 99, c: 'none', n: 1, p: [] };
-        await expect(unbundleMessage(envelope)).rejects.toThrow('Unsupported bundle version: 99');
-    });
-    it('throws on invalid payload type for NONE compression', async () => {
-        const envelope = { v: 1, c: 'none', n: 1, p: 'not-an-array' };
-        await expect(unbundleMessage(envelope)).rejects.toThrow('Invalid bundle: NONE compression but payload is not an array');
-    });
-    it('throws on invalid payload type for ZSTD compression', async () => {
-        const envelope = { v: 1, c: 'zstd', n: 1, p: [] };
-        await expect(unbundleMessage(envelope)).rejects.toThrow('Invalid bundle: zstd compression but payload is not a string');
-    });
-    it('unbundles GZIP compressed envelope', async () => {
-        const items = [makeTestEvent('1'), makeTestEvent('2'), makeTestEvent('3')];
-        const envelope = await makeGzipCompressedEnvelope(items);
-        const result = await unbundleMessage(envelope);
-        expect(result).toHaveLength(3);
-        expect(result[0].eventId).toBe('1');
-        expect(result[1].eventId).toBe('2');
-        expect(result[2].eventId).toBe('3');
-    });
-    it('unbundles large batches with GZIP compression', async () => {
-        const items = Array.from({ length: 500 }, (_, i) => makeTestEvent(`event-${i}`, `event_${i}`, i * 10));
-        const envelope = await makeGzipCompressedEnvelope(items);
-        const result = await unbundleMessage(envelope);
-        expect(result).toHaveLength(500);
-        expect(result[0].eventId).toBe('event-0');
-        expect(result[499].eventId).toBe('event-499');
-    });
-    it('throws on invalid payload type for GZIP compression', async () => {
-        const envelope = { v: 1, c: 'gzip', n: 1, p: [] };
-        await expect(unbundleMessage(envelope)).rejects.toThrow('Invalid bundle: gzip compression but payload is not a string');
-    });
-});
-describe('unbundleRecords', () => {
-    describe('legacy (non-bundled) messages', () => {
-        it('parses raw JSON message', async () => {
-            const event = makeTestEvent('raw-1', 'purchase');
-            const record = makeSqsRecord(event);
-            const { items, stats, failedMessageIds } = await unbundleRecords([record]);
-            expect(items).toHaveLength(1);
-            expect(items[0].eventId).toBe('raw-1');
-            expect(items[0].name).toBe('purchase');
-            expect(stats.legacySqsRecords).toBe(1);
-            expect(stats.bundledSqsRecords).toBe(0);
-            expect(failedMessageIds).toHaveLength(0);
-        });
-        it('parses wrapped messageBody format', async () => {
-            const event = makeTestEvent('wrapped-1');
-            const record = makeSqsRecord({ messageBody: event });
-            const { items, stats } = await unbundleRecords([record]);
-            expect(items).toHaveLength(1);
-            expect(items[0].eventId).toBe('wrapped-1');
-            expect(stats.legacySqsRecords).toBe(1);
-        });
-        it('handles multiple legacy records', async () => {
-            const records = [
-                makeSqsRecord(makeTestEvent('1'), 'msg-1'),
-                makeSqsRecord(makeTestEvent('2'), 'msg-2'),
-                makeSqsRecord(makeTestEvent('3'), 'msg-3'),
-            ];
-            const { items, stats, recordMap } = await unbundleRecords(records);
-            expect(items).toHaveLength(3);
-            expect(stats.legacySqsRecords).toBe(3);
-            expect(stats.totalItems).toBe(3);
-            expect(recordMap.get(items[0])).toBe('msg-1');
-            expect(recordMap.get(items[1])).toBe('msg-2');
-            expect(recordMap.get(items[2])).toBe('msg-3');
-        });
-    });
-    describe('bundled messages (NONE compression)', () => {
-        it('unbundles wrapped messageBody envelope', async () => {
-            const items = [makeTestEvent('b1'), makeTestEvent('b2')];
-            const envelope = makeBundledEnvelope(items);
-            const record = makeSqsRecord({ messageBody: envelope });
-            const { items: result, stats } = await unbundleRecords([record]);
-            expect(result).toHaveLength(2);
-            expect(result[0].eventId).toBe('b1');
-            expect(result[1].eventId).toBe('b2');
-            expect(stats.bundledSqsRecords).toBe(1);
-            expect(stats.legacySqsRecords).toBe(0);
-        });
-        it('unbundles raw envelope (not wrapped)', async () => {
-            const items = [makeTestEvent('r1'), makeTestEvent('r2')];
-            const envelope = makeBundledEnvelope(items);
-            const record = makeSqsRecord(envelope);
-            const { items: result, stats } = await unbundleRecords([record]);
-            expect(result).toHaveLength(2);
-            expect(stats.bundledSqsRecords).toBe(1);
-        });
-        it('maps all items from bundle to same messageId', async () => {
-            const items = [makeTestEvent('x1'), makeTestEvent('x2'), makeTestEvent('x3')];
-            const envelope = makeBundledEnvelope(items);
-            const record = makeSqsRecord({ messageBody: envelope }, 'bundle-msg-1');
-            const { items: result, recordMap } = await unbundleRecords([record]);
-            expect(result).toHaveLength(3);
-            expect(recordMap.get(result[0])).toBe('bundle-msg-1');
-            expect(recordMap.get(result[1])).toBe('bundle-msg-1');
-            expect(recordMap.get(result[2])).toBe('bundle-msg-1');
-        });
-    });
-    describe('bundled messages (ZSTD compression)', () => {
-        it('unbundles ZSTD compressed envelope', async () => {
-            const items = [makeTestEvent('z1'), makeTestEvent('z2')];
-            const envelope = await makeCompressedEnvelope(items);
-            const record = makeSqsRecord({ messageBody: envelope });
-            const { items: result, stats } = await unbundleRecords([record]);
-            expect(result).toHaveLength(2);
-            expect(result[0].eventId).toBe('z1');
-            expect(result[1].eventId).toBe('z2');
-            expect(stats.bundledSqsRecords).toBe(1);
-        });
-        it('handles large compressed bundles (500 items)', async () => {
-            const items = Array.from({ length: 500 }, (_, i) => makeTestEvent(`item-${i}`));
-            const envelope = await makeCompressedEnvelope(items);
-            const record = makeSqsRecord({ messageBody: envelope });
-            const { items: result, stats } = await unbundleRecords([record]);
-            expect(result).toHaveLength(500);
-            expect(stats.bundledSqsRecords).toBe(1);
-            expect(stats.totalItems).toBe(500);
-        });
-    });
-    describe('bundled messages (GZIP compression - CF Worker)', () => {
-        it('unbundles GZIP compressed envelope', async () => {
-            const items = [makeTestEvent('g1'), makeTestEvent('g2')];
-            const envelope = await makeGzipCompressedEnvelope(items);
-            const record = makeSqsRecord({ messageBody: envelope });
-            const { items: result, stats } = await unbundleRecords([record]);
-            expect(result).toHaveLength(2);
-            expect(result[0].eventId).toBe('g1');
-            expect(result[1].eventId).toBe('g2');
-            expect(stats.bundledSqsRecords).toBe(1);
-        });
-        it('handles large GZIP compressed bundles (500 items)', async () => {
-            const items = Array.from({ length: 500 }, (_, i) => makeTestEvent(`item-${i}`));
-            const envelope = await makeGzipCompressedEnvelope(items);
-            const record = makeSqsRecord({ messageBody: envelope });
-            const { items: result, stats } = await unbundleRecords([record]);
-            expect(result).toHaveLength(500);
-            expect(stats.bundledSqsRecords).toBe(1);
-            expect(stats.totalItems).toBe(500);
-        });
-        it('maps all items from GZIP bundle to same messageId', async () => {
-            const items = [makeTestEvent('x1'), makeTestEvent('x2'), makeTestEvent('x3')];
-            const envelope = await makeGzipCompressedEnvelope(items);
-            const record = makeSqsRecord({ messageBody: envelope }, 'gzip-bundle-msg-1');
-            const { items: result, recordMap } = await unbundleRecords([record]);
-            expect(result).toHaveLength(3);
-            expect(recordMap.get(result[0])).toBe('gzip-bundle-msg-1');
-            expect(recordMap.get(result[1])).toBe('gzip-bundle-msg-1');
-            expect(recordMap.get(result[2])).toBe('gzip-bundle-msg-1');
-        });
-        it('unbundles GZIP envelope wrapped in full InternalSQSMessage format (CF Worker format)', async () => {
-            const items = [makeTestEvent('cf1'), makeTestEvent('cf2'), makeTestEvent('cf3')];
-            const envelope = await makeGzipCompressedEnvelope(items);
-            const internalSqsMessage = {
-                messageId: 'cf-internal-msg-123',
-                messageType: 'TRACKING_EVENT_COLLECT',
-                messageTime: '2026-05-29T11:00:10.076Z',
-                messageBody: envelope,
-            };
-            const record = makeSqsRecord(internalSqsMessage, 'sqs-msg-id');
-            const { items: result, stats, recordMap } = await unbundleRecords([record]);
-            expect(result).toHaveLength(3);
-            expect(result[0].eventId).toBe('cf1');
-            expect(result[1].eventId).toBe('cf2');
-            expect(result[2].eventId).toBe('cf3');
-            expect(stats.bundledSqsRecords).toBe(1);
-            expect(stats.legacySqsRecords).toBe(0);
-            expect(stats.totalItems).toBe(3);
-            expect(recordMap.get(result[0])).toBe('sqs-msg-id');
-            expect(recordMap.get(result[1])).toBe('sqs-msg-id');
-            expect(recordMap.get(result[2])).toBe('sqs-msg-id');
-        });
-        it('unbundles GZIP envelope with extra wrapper fields (messageTime, messageType)', async () => {
-            const items = [makeTestEvent('w1')];
-            const envelope = await makeGzipCompressedEnvelope(items);
-            const wrappedMessage = {
-                messageTime: new Date().toISOString(),
-                messageType: 'SESSION_EVENT',
-                messageBody: envelope,
-                someOtherField: 'ignored',
-            };
-            const record = makeSqsRecord(wrappedMessage);
-            const { items: result, stats } = await unbundleRecords([record]);
-            expect(result).toHaveLength(1);
-            expect(result[0].eventId).toBe('w1');
-            expect(stats.bundledSqsRecords).toBe(1);
-        });
-        it('handles decompression failure gracefully (does not return wrapper)', async () => {
-            const corruptedEnvelope = {
-                v: 1,
-                c: 'gzip',
-                n: 1,
-                s: 100,
-                p: 'H4sIAAAAAAAAA+TRUNCATED',
-            };
-            const internalSqsMessage = {
-                messageTime: '2026-05-29T11:00:10.076Z',
-                messageType: 'TRACKING_EVENT_COLLECT',
-                messageBody: corruptedEnvelope,
-                messageId: 'corrupted-msg-id',
-            };
-            const record = makeSqsRecord(internalSqsMessage, 'sqs-record-id');
-            const { items, stats, failedMessageIds } = await unbundleRecords([record]);
-            expect(failedMessageIds).toHaveLength(1);
-            expect(stats.failedRecords).toBe(1);
-            expect(items).toHaveLength(0);
-            items.forEach((item) => {
-                expect(item).not.toHaveProperty('messageTime');
-                expect(item).not.toHaveProperty('messageType');
-                expect(item).not.toHaveProperty('messageBody');
-            });
-        });
-        it('verifies decompression failure does NOT leak wrapper into items', async () => {
-            const badEnvelope = {
-                v: 1,
-                c: 'gzip',
-                n: 5,
-                s: 1000,
-                p: 'dGhpcyBpcyBub3QgdmFsaWQgZ3ppcA==',
-            };
-            const wrapper = {
-                messageTime: new Date().toISOString(),
-                messageType: 'TRACKING_EVENT_COLLECT',
-                messageBody: badEnvelope,
-                messageId: 'test-internal-msg-id',
-            };
-            const record = makeSqsRecord(wrapper, 'sqs-msg-id');
-            const { items, stats, failedMessageIds } = await unbundleRecords([record]);
-            expect(failedMessageIds).toContain('sqs-msg-id');
-            expect(stats.failedRecords).toBe(1);
-            expect(items).toHaveLength(0);
-            expect(stats.totalItems).toBe(0);
-        });
-        it('simulates old version without GZIP - returns envelope as item (BUG)', async () => {
-            const items = [{ pixelId: 'px123', trackingEvent: { name: 'page_view' } }];
-            const envelope = await makeGzipCompressedEnvelope(items);
-            const wrapper = {
-                messageTime: new Date().toISOString(),
-                messageType: 'TRACKING_EVENT_COLLECT',
-                messageBody: envelope,
-                messageId: 'cf-msg-id',
-            };
-            expect(isBundledEnvelope(envelope)).toBe(true);
-            const record = makeSqsRecord(wrapper, 'sqs-msg-id');
-            const { items: result, stats } = await unbundleRecords([record]);
-            expect(stats.bundledSqsRecords).toBe(1);
-            expect(result).toHaveLength(1);
-            expect(result[0].pixelId).toBe('px123');
-            expect(result[0]).not.toHaveProperty('v');
-            expect(result[0]).not.toHaveProperty('c');
-            expect(result[0]).not.toHaveProperty('n');
-            expect(result[0]).not.toHaveProperty('p');
-            expect(result[0]).not.toHaveProperty('s');
-        });
-        it('unknown compression algorithm causes legacy fallback (returns messageBody)', async () => {
-            const unknownEnvelope = {
-                v: 1,
-                c: 'lz4',
-                n: 1,
-                s: 100,
-                p: 'some-base64-data',
-            };
-            const wrapper = {
-                messageTime: new Date().toISOString(),
-                messageType: 'TEST_MESSAGE',
-                messageBody: unknownEnvelope,
-                messageId: 'wrapper-msg-id',
-            };
-            expect(isBundledEnvelope(unknownEnvelope)).toBe(false);
-            const record = makeSqsRecord(wrapper, 'sqs-msg-id');
-            const { items, stats } = await unbundleRecords([record]);
-            expect(stats.legacySqsRecords).toBe(1);
-            expect(stats.bundledSqsRecords).toBe(0);
-            expect(items).toHaveLength(1);
-            expect(items[0]).toHaveProperty('v', 1);
-            expect(items[0]).toHaveProperty('c', 'lz4');
-            expect(items[0]).toHaveProperty('n', 1);
-            expect(items[0]).toHaveProperty('p');
-        });
-    });
-    describe('mixed message formats', () => {
-        it('handles mix of legacy and bundled messages', async () => {
-            const legacyEvent = makeTestEvent('legacy-1');
-            const bundledItems = [makeTestEvent('bundled-1'), makeTestEvent('bundled-2')];
-            const bundleEnvelope = makeBundledEnvelope(bundledItems);
-            const records = [
-                makeSqsRecord(legacyEvent, 'msg-legacy'),
-                makeSqsRecord({ messageBody: bundleEnvelope }, 'msg-bundle'),
-            ];
-            const { items, stats, recordMap } = await unbundleRecords(records);
-            expect(items).toHaveLength(3);
-            expect(stats.legacySqsRecords).toBe(1);
-            expect(stats.bundledSqsRecords).toBe(1);
-            expect(stats.totalItems).toBe(3);
-            expect(recordMap.get(items[0])).toBe('msg-legacy');
-            expect(recordMap.get(items[1])).toBe('msg-bundle');
-            expect(recordMap.get(items[2])).toBe('msg-bundle');
-        });
-        it('handles mix of NONE and ZSTD compressed bundles', async () => {
-            const noneItems = [makeTestEvent('none-1')];
-            const zstdItems = [makeTestEvent('zstd-1'), makeTestEvent('zstd-2')];
-            const noneEnvelope = makeBundledEnvelope(noneItems);
-            const zstdEnvelope = await makeCompressedEnvelope(zstdItems);
-            const records = [
-                makeSqsRecord({ messageBody: noneEnvelope }, 'msg-none'),
-                makeSqsRecord({ messageBody: zstdEnvelope }, 'msg-zstd'),
-            ];
-            const { items, stats } = await unbundleRecords(records);
-            expect(items).toHaveLength(3);
-            expect(stats.bundledSqsRecords).toBe(2);
-            expect(stats.totalItems).toBe(3);
-        });
-        it('handles mix of ZSTD, GZIP, and legacy messages', async () => {
-            const legacyEvent = makeTestEvent('legacy-1');
-            const zstdItems = [makeTestEvent('zstd-1'), makeTestEvent('zstd-2')];
-            const gzipItems = [makeTestEvent('gzip-1'), makeTestEvent('gzip-2'), makeTestEvent('gzip-3')];
-            const zstdEnvelope = await makeCompressedEnvelope(zstdItems);
-            const gzipEnvelope = await makeGzipCompressedEnvelope(gzipItems);
-            const records = [
-                makeSqsRecord(legacyEvent, 'msg-legacy'),
-                makeSqsRecord({ messageBody: zstdEnvelope }, 'msg-zstd'),
-                makeSqsRecord({ messageBody: gzipEnvelope }, 'msg-gzip'),
-            ];
-            const { items, stats, recordMap } = await unbundleRecords(records);
-            expect(items).toHaveLength(6);
-            expect(stats.legacySqsRecords).toBe(1);
-            expect(stats.bundledSqsRecords).toBe(2);
-            expect(stats.totalItems).toBe(6);
-            expect(recordMap.get(items[0])).toBe('msg-legacy');
-            expect(recordMap.get(items[1])).toBe('msg-zstd');
-            expect(recordMap.get(items[2])).toBe('msg-zstd');
-            expect(recordMap.get(items[3])).toBe('msg-gzip');
-            expect(recordMap.get(items[4])).toBe('msg-gzip');
-            expect(recordMap.get(items[5])).toBe('msg-gzip');
-        });
-    });
-    describe('error handling', () => {
-        it('returns failed messageId for invalid JSON', async () => {
-            const records = [makeSqsRecord('not-valid-json{{{', 'msg-bad'), makeSqsRecord(makeTestEvent('good'), 'msg-good')];
-            const { items, failedMessageIds, stats } = await unbundleRecords(records);
-            expect(items).toHaveLength(1);
-            expect(items[0].eventId).toBe('good');
-            expect(failedMessageIds).toEqual(['msg-bad']);
-            expect(stats.failedRecords).toBe(1);
-            expect(stats.legacySqsRecords).toBe(1);
-        });
-        it('returns failed messageId for corrupt ZSTD compressed data', async () => {
-            const corruptEnvelope = {
-                v: 1,
-                c: CompressionAlgorithm.ZSTD,
-                n: 10,
-                p: 'dGhpcyBpcyBub3QgdmFsaWQgenN0ZA==',
-            };
-            const records = [
-                makeSqsRecord({ messageBody: corruptEnvelope }, 'msg-corrupt'),
-                makeSqsRecord(makeTestEvent('valid'), 'msg-valid'),
-            ];
-            const { items, failedMessageIds, stats } = await unbundleRecords(records);
-            expect(items).toHaveLength(1);
-            expect(items[0].eventId).toBe('valid');
-            expect(failedMessageIds).toContain('msg-corrupt');
-            expect(stats.failedRecords).toBe(1);
-        });
-        it('returns failed messageId for corrupt GZIP compressed data', async () => {
-            const corruptEnvelope = {
-                v: 1,
-                c: CompressionAlgorithm.GZIP,
-                n: 10,
-                p: 'dGhpcyBpcyBub3QgdmFsaWQgZ3ppcA==',
-            };
-            const records = [
-                makeSqsRecord({ messageBody: corruptEnvelope }, 'msg-corrupt-gzip'),
-                makeSqsRecord(makeTestEvent('valid'), 'msg-valid'),
-            ];
-            const { items, failedMessageIds, stats } = await unbundleRecords(records);
-            expect(items).toHaveLength(1);
-            expect(items[0].eventId).toBe('valid');
-            expect(failedMessageIds).toContain('msg-corrupt-gzip');
-            expect(stats.failedRecords).toBe(1);
-        });
-        it('returns empty result for all failed records', async () => {
-            const records = [makeSqsRecord('invalid-1', 'msg-1'), makeSqsRecord('invalid-2', 'msg-2')];
-            const { items, failedMessageIds, stats } = await unbundleRecords(records);
-            expect(items).toHaveLength(0);
-            expect(failedMessageIds).toEqual(['msg-1', 'msg-2']);
-            expect(stats.failedRecords).toBe(2);
-            expect(stats.totalItems).toBe(0);
-        });
-        it('handles empty records array', async () => {
-            const { items, failedMessageIds, stats } = await unbundleRecords([]);
-            expect(items).toHaveLength(0);
-            expect(failedMessageIds).toHaveLength(0);
-            expect(stats.totalRecords).toBe(0);
-            expect(stats.totalItems).toBe(0);
-        });
-        it('rejects ZSTD payload exceeding max decompressed size', async () => {
-            const largeItems = Array.from({ length: 1000 }, (_, i) => ({
-                id: `item-${i}`,
-                data: 'x'.repeat(1000),
-            }));
-            const envelope = await makeCompressedEnvelope(largeItems);
-            const record = makeSqsRecord({ messageBody: envelope }, 'msg-too-large');
-            const { failedMessageIds, stats } = await unbundleRecords([record], {
-                maxDecompressedSizeBytes: 100 * 1024,
-            });
-            expect(failedMessageIds).toContain('msg-too-large');
-            expect(stats.failedRecords).toBe(1);
-        });
-        it('rejects GZIP payload exceeding max decompressed size (post-decompress check)', async () => {
-            const largeItems = Array.from({ length: 1000 }, (_, i) => ({
-                id: `item-${i}`,
-                data: 'x'.repeat(1000),
-            }));
-            const envelope = await makeGzipCompressedEnvelope(largeItems);
-            const record = makeSqsRecord({ messageBody: envelope }, 'msg-too-large-gzip');
-            const { failedMessageIds, stats } = await unbundleRecords([record], {
-                maxDecompressedSizeBytes: 100 * 1024,
-            });
-            expect(failedMessageIds).toContain('msg-too-large-gzip');
-            expect(stats.failedRecords).toBe(1);
-        });
-        it('fails on invalid base64 in compressed payload', async () => {
-            const badEnvelope = {
-                v: 1,
-                c: CompressionAlgorithm.ZSTD,
-                n: 1,
-                s: 100,
-                p: '!!!not-valid-base64!!!',
-            };
-            const record = makeSqsRecord({ messageBody: badEnvelope }, 'msg-bad-base64');
-            const { failedMessageIds } = await unbundleRecords([record]);
-            expect(failedMessageIds).toContain('msg-bad-base64');
-        });
-    });
-    describe('bundle format edge cases', () => {
-        it('successfully unbundles even when n does not match actual item count', async () => {
-            const envelope = {
-                v: 1,
-                c: CompressionAlgorithm.NONE,
-                n: 5,
-                s: 50,
-                p: [makeTestEvent('1'), makeTestEvent('2')],
-            };
-            const record = makeSqsRecord({ messageBody: envelope });
-            const { items } = await unbundleRecords([record]);
-            expect(items).toHaveLength(2);
-        });
-        it('treats envelope with unsupported version as legacy message', async () => {
-            const badEnvelope = { v: 99, c: 'none', n: 1, s: 10, p: [] };
-            const record = makeSqsRecord({ messageBody: badEnvelope }, 'msg-bad-version');
-            const { items, stats } = await unbundleRecords([record]);
-            expect(items).toHaveLength(1);
-            expect(items[0].v).toBe(99);
-            expect(stats.legacySqsRecords).toBe(1);
-            expect(stats.bundledSqsRecords).toBe(0);
-        });
-    });
-    describe('timeout protection', () => {
-        it('respects timeoutMs option for ZSTD', async () => {
-            const items = [makeTestEvent('1')];
-            const envelope = await makeCompressedEnvelope(items);
-            const record = makeSqsRecord({ messageBody: envelope });
-            const { items: result, failedMessageIds } = await unbundleRecords([record], {
-                timeoutMs: 5000,
-            });
-            expect(result).toHaveLength(1);
-            expect(failedMessageIds).toHaveLength(0);
-        });
-        it('respects timeoutMs option for GZIP', async () => {
-            const items = [makeTestEvent('1')];
-            const envelope = await makeGzipCompressedEnvelope(items);
-            const record = makeSqsRecord({ messageBody: envelope });
-            const { items: result, failedMessageIds } = await unbundleRecords([record], {
-                timeoutMs: 5000,
-            });
-            expect(result).toHaveLength(1);
-            expect(failedMessageIds).toHaveLength(0);
-        });
-        it('passes timeoutMs through to decompression', async () => {
-            const items = [makeTestEvent('1')];
-            const envelope = await makeCompressedEnvelope(items);
-            const record = makeSqsRecord({ messageBody: envelope });
-            await expect(unbundleRecords([record], { timeoutMs: 30000 })).resolves.toBeDefined();
-        });
-        it('CompressionTimeoutError is properly exported', () => {
-            const error = new CompressionTimeoutError(CompressionOperation.DECOMPRESS, 5000);
-            expect(error).toBeInstanceOf(Error);
-            expect(error.name).toBe('CompressionTimeoutError');
-            expect(error.operation).toBe('decompress');
-            expect(error.timeoutMs).toBe(5000);
-            expect(error.message).toContain('timed out after 5000ms');
-        });
-        it('includes timeout info in failure logging for ZSTD', async () => {
-            const corruptEnvelope = {
-                v: 1,
-                c: CompressionAlgorithm.ZSTD,
-                n: 1,
-                s: 100,
-                p: 'dGhpcyBpcyBub3QgdmFsaWQgenN0ZA==',
-            };
-            const record = makeSqsRecord({ messageBody: corruptEnvelope }, 'msg-timeout-test');
-            const { failedMessageIds } = await unbundleRecords([record], {
-                timeoutMs: 5000,
-            });
-            expect(failedMessageIds).toContain('msg-timeout-test');
-        });
-        it('includes timeout info in failure logging for GZIP', async () => {
-            const corruptEnvelope = {
-                v: 1,
-                c: CompressionAlgorithm.GZIP,
-                n: 1,
-                s: 100,
-                p: 'dGhpcyBpcyBub3QgdmFsaWQgZ3ppcA==',
-            };
-            const record = makeSqsRecord({ messageBody: corruptEnvelope }, 'msg-gzip-timeout-test');
-            const { failedMessageIds } = await unbundleRecords([record], {
-                timeoutMs: 5000,
-            });
-            expect(failedMessageIds).toContain('msg-gzip-timeout-test');
-        });
-    });
-    describe('end-to-end: producer bundle → consumer unbundle', () => {
-        it('simulates full bundle → unbundle flow with compression', async () => {
-            const producerItems = Array.from({ length: 100 }, (_, i) => makeTestEvent(`event-${i}`, 'page_view', i * 1.5));
-            const envelope = await makeCompressedEnvelope(producerItems, 3);
-            const sqsMessageBody = { messageBody: envelope };
-            const consumerRecord = makeSqsRecord(sqsMessageBody, 'sqs-message-id-123');
-            const { items, recordMap, stats } = await unbundleRecords([consumerRecord]);
-            expect(items).toHaveLength(100);
-            expect(items[0]).toEqual({ eventId: 'event-0', name: 'page_view', value: 0 });
-            expect(items[99]).toEqual({ eventId: 'event-99', name: 'page_view', value: 148.5 });
-            expect(stats.bundledSqsRecords).toBe(1);
-            expect(stats.legacySqsRecords).toBe(0);
-            expect(stats.totalItems).toBe(100);
-            for (const item of items) {
-                expect(recordMap.get(item)).toBe('sqs-message-id-123');
-            }
-        });
-        it('simulates mixed batch with legacy and bundled messages', async () => {
-            const legacyRecord1 = makeSqsRecord({ messageBody: makeTestEvent('legacy-1', 'purchase', 99.99) }, 'legacy-msg-1');
-            const legacyRecord2 = makeSqsRecord(makeTestEvent('legacy-2', 'add_to_cart', 29.99), 'legacy-msg-2');
-            const bundledItems = [
-                makeTestEvent('bundled-1', 'page_view'),
-                makeTestEvent('bundled-2', 'session_start'),
-                makeTestEvent('bundled-3', 'page_end'),
-            ];
-            const envelope = await makeCompressedEnvelope(bundledItems);
-            const bundledRecord = makeSqsRecord({ messageBody: envelope }, 'bundled-msg-1');
-            const records = [legacyRecord1, bundledRecord, legacyRecord2];
-            const { items, stats, recordMap } = await unbundleRecords(records);
-            expect(items).toHaveLength(5);
-            expect(stats.legacySqsRecords).toBe(2);
-            expect(stats.bundledSqsRecords).toBe(1);
-            expect(stats.totalItems).toBe(5);
-            expect(recordMap.get(items[0])).toBe('legacy-msg-1');
-            expect(recordMap.get(items[1])).toBe('bundled-msg-1');
-            expect(recordMap.get(items[2])).toBe('bundled-msg-1');
-            expect(recordMap.get(items[3])).toBe('bundled-msg-1');
-            expect(recordMap.get(items[4])).toBe('legacy-msg-2');
-        });
-    });
-    describe('consumer edge cases - real sequences', () => {
-        it('handles 500 items in single compressed bundle with exact verification', async () => {
-            const originalItems = Array.from({ length: 500 }, (_, i) => ({
-                id: `item-${i}`,
-                name: `Event ${i}`,
-                data: { nested: { value: i * 1.5 } },
-                timestamp: Date.now() + i,
-            }));
-            const envelope = await makeCompressedEnvelope(originalItems);
-            const record = makeSqsRecord({ messageBody: envelope }, 'msg-500-items');
-            const { items, recordMap, stats } = await unbundleRecords([record]);
-            expect(items).toHaveLength(500);
-            expect(items[0]).toEqual(originalItems[0]);
-            expect(items[249]).toEqual(originalItems[249]);
-            expect(items[499]).toEqual(originalItems[499]);
-            expect(stats.bundledSqsRecords).toBe(1);
-            expect(stats.totalItems).toBe(500);
-            for (let i = 0; i < 500; i++) {
-                expect(items[i].id).toBe(`item-${i}`);
-                expect(items[i].data.nested.value).toBe(i * 1.5);
-            }
-            for (const item of items) {
-                expect(recordMap.get(item)).toBe('msg-500-items');
-            }
-        });
-        it('handles multiple bundles in single batch with different item counts', async () => {
-            const counts = [10, 50, 100, 200, 300];
-            const records = [];
-            const expectedTotal = counts.reduce((sum, c) => sum + c, 0);
-            for (let bundleIdx = 0; bundleIdx < counts.length; bundleIdx++) {
-                const count = counts[bundleIdx];
-                const items = Array.from({ length: count }, (_, i) => ({
-                    bundleId: bundleIdx,
-                    itemIdx: i,
-                    payload: `bundle-${bundleIdx}-item-${i}`,
-                }));
-                const envelope = await makeCompressedEnvelope(items);
-                records.push(makeSqsRecord({ messageBody: envelope }, `msg-bundle-${bundleIdx}`));
-            }
-            const { items, recordMap, stats } = await unbundleRecords(records);
-            expect(items).toHaveLength(expectedTotal);
-            expect(stats.totalItems).toBe(expectedTotal);
-            expect(stats.bundledSqsRecords).toBe(5);
-            expect(stats.legacySqsRecords).toBe(0);
-            expect(stats.failedRecords).toBe(0);
-            const itemsByBundle = new Map();
-            for (const item of items) {
-                const expectedMsgId = `msg-bundle-${item.bundleId}`;
-                expect(recordMap.get(item)).toBe(expectedMsgId);
-                itemsByBundle.set(item.bundleId, (itemsByBundle.get(item.bundleId) ?? 0) + 1);
-            }
-            expect(itemsByBundle.get(0)).toBe(10);
-            expect(itemsByBundle.get(1)).toBe(50);
-            expect(itemsByBundle.get(2)).toBe(100);
-            expect(itemsByBundle.get(3)).toBe(200);
-            expect(itemsByBundle.get(4)).toBe(300);
-        });
-        it('handles realistic 80% bundled / 20% legacy migration ratio', async () => {
-            const records = [];
-            const totalMessages = 100;
-            const bundledCount = 80;
-            const legacyCount = 20;
-            const itemsPerBundle = 25;
-            for (let i = 0; i < bundledCount; i++) {
-                const items = Array.from({ length: itemsPerBundle }, (_, j) => ({
-                    type: 'bundled',
-                    bundleIdx: i,
-                    itemIdx: j,
-                }));
-                const envelope = await makeCompressedEnvelope(items);
-                records.push(makeSqsRecord({ messageBody: envelope }, `msg-bundled-${i}`));
-            }
-            for (let i = 0; i < legacyCount; i++) {
-                const legacyEvent = {
-                    type: 'legacy',
-                    legacyIdx: i,
-                    itemIdx: 0,
-                };
-                records.push(makeSqsRecord(legacyEvent, `msg-legacy-${i}`));
-            }
-            const shuffled = [...records].sort(() => Math.random() - 0.5);
-            const { items, stats, recordMap } = await unbundleRecords(shuffled);
-            expect(stats.totalRecords).toBe(totalMessages);
-            expect(stats.bundledSqsRecords).toBe(bundledCount);
-            expect(stats.legacySqsRecords).toBe(legacyCount);
-            expect(stats.failedRecords).toBe(0);
-            expect(items).toHaveLength(bundledCount * itemsPerBundle + legacyCount);
-            expect(stats.totalItems).toBe(2020);
-            const bundledItems = items.filter((i) => i.type === 'bundled');
-            const legacyItems = items.filter((i) => i.type === 'legacy');
-            expect(bundledItems).toHaveLength(bundledCount * itemsPerBundle);
-            expect(legacyItems).toHaveLength(legacyCount);
-            for (const item of bundledItems) {
-                expect(recordMap.get(item)).toBe(`msg-bundled-${item.bundleIdx}`);
-            }
-            for (const item of legacyItems) {
-                expect(recordMap.get(item)).toBe(`msg-legacy-${item.legacyIdx}`);
-            }
-        });
-        it('preserves Unicode characters through ZSTD compression', async () => {
-            const unicodeItems = [
-                {
-                    id: 'emoji',
-                    content: '🎉🚀💻🌍✨ Party time!',
-                    description: 'Emojis should survive compression',
-                },
-                {
-                    id: 'chinese',
-                    content: '中文测试：欢迎使用我们的服务',
-                    description: 'Chinese characters',
-                },
-                {
-                    id: 'arabic',
-                    content: 'العربية: مرحبا بكم في خدمتنا',
-                    description: 'Arabic text (RTL)',
-                },
-                {
-                    id: 'math',
-                    content: '∑∫∂∇ε → ∞ × ∈ ⊆ ∀∃',
-                    description: 'Mathematical symbols',
-                },
-                {
-                    id: 'mixed',
-                    content: 'Hello 世界 🌏 مرحبا ∑ Привет',
-                    description: 'Mixed scripts',
-                },
-                {
-                    id: 'special',
-                    content: '️️️️️️️️️️️️️️️️',
-                    description: 'Unicode edge cases',
-                },
-                {
-                    id: 'japanese',
-                    content: 'こんにちは世界 ひらがな カタカナ 漢字',
-                    description: 'Japanese hiragana, katakana, kanji',
-                },
-                {
-                    id: 'korean',
-                    content: '안녕하세요 세계',
-                    description: 'Korean hangul',
-                },
-                {
-                    id: 'cyrillic',
-                    content: 'Привет мир! Это тест.',
-                    description: 'Russian Cyrillic',
-                },
-                {
-                    id: 'combining',
-                    content: 'e\u0301 n\u0303 c\u0327',
-                    description: 'Combining diacritical marks',
-                },
-            ];
-            const envelope = await makeCompressedEnvelope(unicodeItems);
-            const record = makeSqsRecord({ messageBody: envelope }, 'msg-unicode');
-            const { items } = await unbundleRecords([record]);
-            expect(items).toHaveLength(unicodeItems.length);
-            for (let i = 0; i < unicodeItems.length; i++) {
-                expect(items[i].id).toBe(unicodeItems[i].id);
-                expect(items[i].content).toBe(unicodeItems[i].content);
-                expect(items[i].description).toBe(unicodeItems[i].description);
-                const originalBytes = Buffer.from(unicodeItems[i].content, 'utf8');
-                const recoveredBytes = Buffer.from(items[i].content, 'utf8');
-                expect(recoveredBytes.equals(originalBytes)).toBe(true);
-            }
-        });
-        it('preserves deeply nested structures (10 levels)', async () => {
-            function createDeepStructure(depth, maxDepth = 10) {
-                const node = {
-                    level: depth,
-                    data: `level-${depth}-data-${Math.random().toString(36).slice(2)}`,
-                };
-                if (depth < maxDepth) {
-                    node.child = createDeepStructure(depth + 1, maxDepth);
-                    node.siblings = [
-                        createDeepStructure(depth + 1, Math.min(depth + 3, maxDepth)),
-                        createDeepStructure(depth + 1, Math.min(depth + 2, maxDepth)),
-                    ];
-                }
-                return node;
-            }
-            const deepItems = Array.from({ length: 10 }, (_, i) => ({
-                id: `deep-${i}`,
-                nested: createDeepStructure(0, 10),
-                arrays: [[[[[['deeply', 'nested', 'array']]], [{ inner: { value: i } }]]]],
-            }));
-            const envelope = await makeCompressedEnvelope(deepItems);
-            const record = makeSqsRecord({ messageBody: envelope }, 'msg-deep');
-            const { items } = await unbundleRecords([record]);
-            expect(items).toHaveLength(10);
-            for (let i = 0; i < 10; i++) {
-                expect(JSON.stringify(items[i])).toBe(JSON.stringify(deepItems[i]));
-                expect(items[i].nested.level).toBe(0);
-                expect(items[i].nested.child?.level).toBe(1);
-                expect(items[i].nested.child?.child?.child?.level).toBe(3);
-                expect(items[i].arrays[0][0][0][0][0][0]).toBe('deeply');
-            }
-        });
-        it('handles binary-like string data (base64 encoded)', async () => {
-            const binaryItems = [
-                {
-                    id: 'small-binary',
-                    base64Data: Buffer.from('Small binary payload').toString('base64'),
-                    size: 'small',
-                },
-                {
-                    id: 'medium-binary',
-                    base64Data: Buffer.from('x'.repeat(1000)).toString('base64'),
-                    size: 'medium',
-                },
-                {
-                    id: 'image-simulation',
-                    base64Data: Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0xff, 0xd8, 0xff, 0xe0]).toString('base64'),
-                    size: 'binary-header',
-                },
-                {
-                    id: 'random-bytes',
-                    base64Data: Buffer.from(Array.from({ length: 256 }, () => Math.floor(Math.random() * 256))).toString('base64'),
-                    size: 'random',
-                },
-                {
-                    id: 'all-byte-values',
-                    base64Data: Buffer.from(Array.from({ length: 256 }, (_, i) => i)).toString('base64'),
-                    size: 'full-range',
-                },
-            ];
-            const envelope = await makeCompressedEnvelope(binaryItems);
-            const record = makeSqsRecord({ messageBody: envelope }, 'msg-binary');
-            const { items } = await unbundleRecords([record]);
-            expect(items).toHaveLength(binaryItems.length);
-            for (let i = 0; i < binaryItems.length; i++) {
-                expect(items[i].id).toBe(binaryItems[i].id);
-                expect(items[i].base64Data).toBe(binaryItems[i].base64Data);
-                const originalDecoded = Buffer.from(binaryItems[i].base64Data, 'base64');
-                const recoveredDecoded = Buffer.from(items[i].base64Data, 'base64');
-                expect(recoveredDecoded.equals(originalDecoded)).toBe(true);
-            }
-        });
-        it('handles concurrent unbundling stress test (100 records in parallel)', async () => {
-            const recordCount = 100;
-            const records = [];
-            for (let i = 0; i < recordCount; i++) {
-                const itemsInBundle = 10 + (i % 20);
-                const items = Array.from({ length: itemsInBundle }, (_, j) => ({
-                    recordIdx: i,
-                    itemIdx: j,
-                    uniqueId: `r${i}-i${j}`,
-                    timestamp: Date.now() + i * 1000 + j,
-                    data: `payload-${i}-${j}-${Math.random().toString(36).slice(2)}`,
-                }));
-                const envelope = await makeCompressedEnvelope(items);
-                records.push(makeSqsRecord({ messageBody: envelope }, `stress-msg-${i}`));
-            }
-            const startTime = Date.now();
-            const { items, recordMap, stats, failedMessageIds } = await unbundleRecords(records);
-            const duration = Date.now() - startTime;
-            expect(failedMessageIds).toHaveLength(0);
-            expect(stats.failedRecords).toBe(0);
-            expect(stats.bundledSqsRecords).toBe(recordCount);
-            const seenUniqueIds = new Set();
-            for (const item of items) {
-                expect(seenUniqueIds.has(item.uniqueId)).toBe(false);
-                seenUniqueIds.add(item.uniqueId);
-                const expectedMsgId = `stress-msg-${item.recordIdx}`;
-                expect(recordMap.get(item)).toBe(expectedMsgId);
-                expect(item.itemIdx).toBeGreaterThanOrEqual(0);
-                expect(item.itemIdx).toBeLessThan(30);
-            }
-            const expectedTotal = Array.from({ length: recordCount }, (_, i) => 10 + (i % 20)).reduce((a, b) => a + b, 0);
-            expect(items).toHaveLength(expectedTotal);
-            expect(stats.totalItems).toBe(expectedTotal);
-            console.log(`Unbundled ${recordCount} records (${stats.totalItems} items) in ${duration}ms`);
-        });
-        it('handles items with all JSON primitive types', async () => {
-            const primitiveItems = [
-                {
-                    id: 'primitives',
-                    stringVal: 'hello',
-                    numberVal: 42,
-                    floatVal: 3.14159265359,
-                    boolTrue: true,
-                    boolFalse: false,
-                    nullVal: null,
-                    emptyString: '',
-                    zero: 0,
-                    negativeNum: -999,
-                    largeNum: Number.MAX_SAFE_INTEGER,
-                    smallNum: Number.MIN_SAFE_INTEGER,
-                    scientificNotation: 1.23e10,
-                },
-                {
-                    id: 'arrays',
-                    emptyArray: [],
-                    numberArray: [1, 2, 3],
-                    mixedArray: [1, 'two', true, null],
-                    nestedArray: [[1, 2], [3, 4], [[5]]],
-                },
-                {
-                    id: 'objects',
-                    emptyObject: {},
-                    nestedObject: { a: { b: { c: 1 } } },
-                    arrayOfObjects: [{ x: 1 }, { y: 2 }],
-                },
-            ];
-            const envelope = await makeCompressedEnvelope(primitiveItems);
-            const record = makeSqsRecord({ messageBody: envelope }, 'msg-primitives');
-            const { items } = await unbundleRecords([record]);
-            expect(items).toHaveLength(3);
-            expect(JSON.stringify(items)).toBe(JSON.stringify(primitiveItems));
-        });
-        it('maintains item order across multiple bundles', async () => {
-            const records = [];
-            let globalIdx = 0;
-            for (let bundleIdx = 0; bundleIdx < 10; bundleIdx++) {
-                const itemCount = 10 + bundleIdx * 5;
-                const items = Array.from({ length: itemCount }, () => ({
-                    globalOrder: globalIdx++,
-                    bundle: bundleIdx,
-                }));
-                const envelope = await makeCompressedEnvelope(items);
-                records.push(makeSqsRecord({ messageBody: envelope }, `order-msg-${bundleIdx}`));
-            }
-            const { items } = await unbundleRecords(records);
-            const bundleGroups = new Map();
-            for (const item of items) {
-                if (!bundleGroups.has(item.bundle)) {
-                    bundleGroups.set(item.bundle, []);
-                }
-                bundleGroups.get(item.bundle)?.push(item.globalOrder);
-            }
-            for (const [, orders] of bundleGroups) {
-                for (let i = 1; i < orders.length; i++) {
-                    expect(orders[i]).toBeGreaterThan(orders[i - 1]);
-                }
-            }
-        });
-        it('handles edge case: single item bundles', async () => {
-            const records = await Promise.all(Array.from({ length: 50 }, async (_, i) => {
-                const items = [{ id: `single-${i}`, value: i }];
-                const envelope = await makeCompressedEnvelope(items);
-                return makeSqsRecord({ messageBody: envelope }, `single-msg-${i}`);
-            }));
-            const { items, stats, recordMap } = await unbundleRecords(records);
-            expect(items).toHaveLength(50);
-            expect(stats.bundledSqsRecords).toBe(50);
-            expect(stats.totalItems).toBe(50);
-            for (let i = 0; i < 50; i++) {
-                const item = items.find((x) => x.value === i);
-                expect(item).toBeDefined();
-                if (!item)
-                    throw new Error(`Expected item with value ${i} to be found`);
-                expect(recordMap.get(item)).toMatch(/single-msg-\d+/);
-            }
-        });
-        it('handles edge case: empty arrays in bundles', async () => {
-            const emptyEnvelope = {
-                v: 1,
-                c: CompressionAlgorithm.NONE,
-                n: 0,
-                p: [],
-            };
-            const record = makeSqsRecord({ messageBody: emptyEnvelope }, 'msg-empty');
-            const { items, stats } = await unbundleRecords([record]);
-            expect(items).toHaveLength(0);
-            expect(stats.bundledSqsRecords).toBe(1);
-            expect(stats.totalItems).toBe(0);
-        });
-    });
-    describe('GZIP comprehensive tests', () => {
-        describe('GZIP pre-decompression bomb protection', () => {
-            it('rejects GZIP with fake ISIZE claiming huge size BEFORE decompression starts', async () => {
-                const gzipHeader = Buffer.from([0x1f, 0x8b, 0x08, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x03]);
-                const emptyDeflate = Buffer.from([0x03, 0x00]);
-                const crc32 = Buffer.from([0x00, 0x00, 0x00, 0x00]);
-                const fakeIsize = Buffer.alloc(4);
-                fakeIsize.writeUInt32LE(100 * 1024 * 1024, 0);
-                const fakeGzip = Buffer.concat([gzipHeader, emptyDeflate, crc32, fakeIsize]);
-                const base64 = fakeGzip.toString('base64');
-                const bombEnvelope = {
-                    v: 1,
-                    c: CompressionAlgorithm.GZIP,
-                    n: 1,
-                    s: 100,
-                    p: base64,
-                };
-                const record = makeSqsRecord({ messageBody: bombEnvelope }, 'msg-gzip-bomb');
-                const { failedMessageIds, stats } = await unbundleRecords([record], {
-                    maxDecompressedSizeBytes: 10 * 1024 * 1024,
-                });
-                expect(failedMessageIds).toContain('msg-gzip-bomb');
-                expect(stats.failedRecords).toBe(1);
-            });
-            it('allows GZIP with ISIZE within limit', async () => {
-                const items = [makeTestEvent('valid-1')];
-                const envelope = await makeGzipCompressedEnvelope(items);
-                const record = makeSqsRecord({ messageBody: envelope }, 'msg-gzip-valid');
-                const { items: result, failedMessageIds } = await unbundleRecords([record], {
-                    maxDecompressedSizeBytes: 10 * 1024 * 1024,
-                });
-                expect(result).toHaveLength(1);
-                expect(failedMessageIds).toHaveLength(0);
-            });
-            it('pre-check catches bomb even when ISIZE is exactly at limit + 1', async () => {
-                const limit = 1000;
-                const gzipHeader = Buffer.from([0x1f, 0x8b, 0x08, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x03]);
-                const emptyDeflate = Buffer.from([0x03, 0x00]);
-                const crc32 = Buffer.from([0x00, 0x00, 0x00, 0x00]);
-                const fakeIsize = Buffer.alloc(4);
-                fakeIsize.writeUInt32LE(limit + 1, 0);
-                const fakeGzip = Buffer.concat([gzipHeader, emptyDeflate, crc32, fakeIsize]);
-                const base64 = fakeGzip.toString('base64');
-                const bombEnvelope = {
-                    v: 1,
-                    c: CompressionAlgorithm.GZIP,
-                    n: 1,
-                    s: 100,
-                    p: base64,
-                };
-                const record = makeSqsRecord({ messageBody: bombEnvelope }, 'msg-boundary-bomb');
-                const { failedMessageIds } = await unbundleRecords([record], {
-                    maxDecompressedSizeBytes: limit,
-                });
-                expect(failedMessageIds).toContain('msg-boundary-bomb');
-            });
-        });
-        describe('empty GZIP bundle', () => {
-            it('unbundles empty GZIP compressed array', async () => {
-                const envelope = await makeGzipCompressedEnvelope([]);
-                const record = makeSqsRecord({ messageBody: envelope }, 'msg-empty-gzip');
-                const { items, stats } = await unbundleRecords([record]);
-                expect(items).toHaveLength(0);
-                expect(stats.bundledSqsRecords).toBe(1);
-                expect(stats.totalItems).toBe(0);
-            });
-        });
-        describe('Unicode characters in GZIP payload', () => {
-            it('preserves emoji through GZIP compression', async () => {
-                const items = [
-                    { eventId: 'emoji-1', content: '🎉🚀💻🌍✨' },
-                    { eventId: 'emoji-2', content: '👋🏽👨‍👩‍👧‍👦🏳️‍🌈' },
-                ];
-                const envelope = await makeGzipCompressedEnvelope(items);
-                const record = makeSqsRecord({ messageBody: envelope });
-                const { items: result } = await unbundleRecords([record]);
-                expect(result).toHaveLength(2);
-                expect(result[0].content).toBe('🎉🚀💻🌍✨');
-                expect(result[1].content).toBe('👋🏽👨‍👩‍👧‍👦🏳️‍🌈');
-            });
-            it('preserves CJK characters through GZIP compression', async () => {
-                const items = [
-                    { eventId: 'cjk-1', content: '中文测试：欢迎使用' },
-                    { eventId: 'cjk-2', content: 'こんにちは世界 ひらがな カタカナ' },
-                    { eventId: 'cjk-3', content: '안녕하세요 세계' },
-                ];
-                const envelope = await makeGzipCompressedEnvelope(items);
-                const record = makeSqsRecord({ messageBody: envelope });
-                const { items: result } = await unbundleRecords([record]);
-                expect(result).toHaveLength(3);
-                expect(result[0].content).toBe('中文测试：欢迎使用');
-                expect(result[1].content).toBe('こんにちは世界 ひらがな カタカナ');
-                expect(result[2].content).toBe('안녕하세요 세계');
-            });
-            it('preserves special characters and mixed scripts through GZIP compression', async () => {
-                const items = [
-                    { eventId: 'special-1', content: '∑∫∂∇ε → ∞ × ∈ ⊆ ∀∃' },
-                    { eventId: 'special-2', content: 'العربية: مرحبا بكم' },
-                    { eventId: 'mixed', content: 'Hello 世界 🌏 مرحبا Привет' },
-                    { eventId: 'combining', content: 'e\u0301 n\u0303 c\u0327' },
-                ];
-                const envelope = await makeGzipCompressedEnvelope(items);
-                const record = makeSqsRecord({ messageBody: envelope });
-                const { items: result } = await unbundleRecords([record]);
-                expect(result).toHaveLength(4);
-                for (let i = 0; i < items.length; i++) {
-                    expect(result[i].content).toBe(items[i].content);
-                    const originalBytes = Buffer.from(items[i].content, 'utf8');
-                    const recoveredBytes = Buffer.from(result[i].content, 'utf8');
-                    expect(recoveredBytes.equals(originalBytes)).toBe(true);
-                }
-            });
-        });
-        describe('GZIP with invalid magic bytes', () => {
-            it('fails gracefully for buffer with wrong magic bytes', async () => {
-                const wrongMagic = Buffer.from([0x00, 0x00, 0x08, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x03]);
-                const filler = Buffer.alloc(10);
-                const invalidGzip = Buffer.concat([wrongMagic, filler]);
-                const base64 = invalidGzip.toString('base64');
-                const badEnvelope = {
-                    v: 1,
-                    c: CompressionAlgorithm.GZIP,
-                    n: 1,
-                    s: 100,
-                    p: base64,
-                };
-                const record = makeSqsRecord({ messageBody: badEnvelope }, 'msg-wrong-magic');
-                const { failedMessageIds } = await unbundleRecords([record]);
-                expect(failedMessageIds).toContain('msg-wrong-magic');
-            });
-            it('fails gracefully for buffer starting with valid magic but corrupted data', async () => {
-                const validMagic = Buffer.from([0x1f, 0x8b]);
-                const garbage = Buffer.from('this is not valid gzip data after magic');
-                const invalidGzip = Buffer.concat([validMagic, garbage]);
-                const base64 = invalidGzip.toString('base64');
-                const badEnvelope = {
-                    v: 1,
-                    c: CompressionAlgorithm.GZIP,
-                    n: 1,
-                    s: 100,
-                    p: base64,
-                };
-                const record = makeSqsRecord({ messageBody: badEnvelope }, 'msg-corrupt-gzip');
-                const { failedMessageIds } = await unbundleRecords([record]);
-                expect(failedMessageIds).toContain('msg-corrupt-gzip');
-            });
-        });
-        describe('GZIP minimum size edge cases', () => {
-            it('handles buffer exactly 18 bytes (minimum valid)', async () => {
-                const minBuffer = Buffer.alloc(18);
-                minBuffer[0] = 0x1f;
-                minBuffer[1] = 0x8b;
-                const size = getGzipUncompressedSize(minBuffer);
-                expect(size).toBe(0);
-            });
-            it('returns undefined for buffer exactly 17 bytes (too small)', async () => {
-                const tooSmall = Buffer.alloc(17);
-                tooSmall[0] = 0x1f;
-                tooSmall[1] = 0x8b;
-                const size = getGzipUncompressedSize(tooSmall);
-                expect(size).toBeUndefined();
-            });
-            it('fails gracefully for 17-byte GZIP envelope', async () => {
-                const tooSmall = Buffer.alloc(17);
-                tooSmall[0] = 0x1f;
-                tooSmall[1] = 0x8b;
-                const base64 = tooSmall.toString('base64');
-                const badEnvelope = {
-                    v: 1,
-                    c: CompressionAlgorithm.GZIP,
-                    n: 1,
-                    s: 100,
-                    p: base64,
-                };
-                const record = makeSqsRecord({ messageBody: badEnvelope }, 'msg-too-small');
-                const { failedMessageIds } = await unbundleRecords([record]);
-                expect(failedMessageIds).toContain('msg-too-small');
-            });
-        });
-        describe('GZIP timeout protection', () => {
-            it('CompressionTimeoutError has correct properties', () => {
-                const error = new CompressionTimeoutError(CompressionOperation.DECOMPRESS, 100);
-                expect(error).toBeInstanceOf(Error);
-                expect(error.name).toBe('CompressionTimeoutError');
-                expect(error.operation).toBe('decompress');
-                expect(error.timeoutMs).toBe(100);
-                expect(error.message).toContain('timed out after 100ms');
-            });
-            it('GZIP decompression respects timeout option', async () => {
-                const items = [makeTestEvent('timeout-test')];
-                const envelope = await makeGzipCompressedEnvelope(items);
-                const record = makeSqsRecord({ messageBody: envelope });
-                const { items: result, failedMessageIds } = await unbundleRecords([record], {
-                    timeoutMs: 10000,
-                });
-                expect(result).toHaveLength(1);
-                expect(failedMessageIds).toHaveLength(0);
-            });
-        });
-        describe('large GZIP near SQS limit', () => {
-            it('decompresses large GZIP bundle near 256KB compressed', async () => {
-                const items = Array.from({ length: 200 }, (_, i) => ({
-                    eventId: `large-${i}`,
-                    name: 'page_view',
-                    data: `repeated-content-for-compression-${i}-`.repeat(50),
-                    value: i * 1.5,
-                }));
-                const envelope = await makeGzipCompressedEnvelope(items);
-                const compressedSize = Buffer.byteLength(JSON.stringify(envelope.p), 'utf8');
-                console.log(`Large GZIP test: compressed payload ~${Math.round(compressedSize / 1024)}KB`);
-                const record = makeSqsRecord({ messageBody: envelope }, 'msg-large-gzip');
-                const { items: result, failedMessageIds } = await unbundleRecords([record]);
-                expect(failedMessageIds).toHaveLength(0);
-                expect(result).toHaveLength(200);
-                expect(result[0].eventId).toBe('large-0');
-                expect(result[199].eventId).toBe('large-199');
-            });
-            it('handles GZIP with maximum decompressed size exactly at limit', async () => {
-                const items = [{ eventId: 'boundary', data: 'x'.repeat(5000) }];
-                const envelope = await makeGzipCompressedEnvelope(items);
-                const record = makeSqsRecord({ messageBody: envelope });
-                const { items: result, failedMessageIds } = await unbundleRecords([record], {
-                    maxDecompressedSizeBytes: 10 * 1024,
-                });
-                expect(failedMessageIds).toHaveLength(0);
-                expect(result).toHaveLength(1);
-            });
-        });
-    });
-});
-describe('getGzipUncompressedSize', () => {
-    it('returns correct size for valid GZIP', async () => {
-        const originalData = 'Hello, World! This is a test.';
-        const compressed = await gzipAsync(Buffer.from(originalData, 'utf8'));
-        const size = getGzipUncompressedSize(compressed);
-        expect(size).toBe(Buffer.byteLength(originalData, 'utf8'));
-    });
-    it('returns correct size for larger payload', async () => {
-        const originalData = 'x'.repeat(10000);
-        const compressed = await gzipAsync(Buffer.from(originalData, 'utf8'));
-        const size = getGzipUncompressedSize(compressed);
-        expect(size).toBe(10000);
-    });
-    it('returns undefined for buffer too small', () => {
-        const tooSmall = Buffer.alloc(17);
-        tooSmall[0] = 0x1f;
-        tooSmall[1] = 0x8b;
-        expect(getGzipUncompressedSize(tooSmall)).toBeUndefined();
-    });
-    it('returns undefined for wrong magic bytes', () => {
-        const wrongMagic = Buffer.alloc(20);
-        wrongMagic[0] = 0x00;
-        wrongMagic[1] = 0x00;
-        expect(getGzipUncompressedSize(wrongMagic)).toBeUndefined();
-    });
-    it('returns undefined for empty buffer', () => {
-        expect(getGzipUncompressedSize(Buffer.alloc(0))).toBeUndefined();
-    });
-    it('returns undefined for single byte buffer', () => {
-        expect(getGzipUncompressedSize(Buffer.from([0x1f]))).toBeUndefined();
-    });
-    it('returns undefined for buffer with only magic bytes', () => {
-        expect(getGzipUncompressedSize(Buffer.from([0x1f, 0x8b]))).toBeUndefined();
-    });
-    it('returns 0 for GZIP with ISIZE = 0', () => {
-        const buffer = Buffer.alloc(18);
-        buffer[0] = 0x1f;
-        buffer[1] = 0x8b;
-        const size = getGzipUncompressedSize(buffer);
-        expect(size).toBe(0);
-    });
-    it('reads ISIZE correctly as little-endian', async () => {
-        const buffer = Buffer.alloc(18);
-        buffer[0] = 0x1f;
-        buffer[1] = 0x8b;
-        buffer.writeUInt32LE(0x12345678, 14);
-        const size = getGzipUncompressedSize(buffer);
-        expect(size).toBe(0x12345678);
-    });
-    it('handles maximum 32-bit ISIZE value', () => {
-        const buffer = Buffer.alloc(18);
-        buffer[0] = 0x1f;
-        buffer[1] = 0x8b;
-        buffer.writeUInt32LE(0xffffffff, 14);
-        const size = getGzipUncompressedSize(buffer);
-        expect(size).toBe(0xffffffff);
-    });
-    it('correctly extracts size from real GZIP data', async () => {
-        const testSizes = [1, 10, 100, 1000, 50000];
-        for (const testSize of testSizes) {
-            const originalData = 'a'.repeat(testSize);
-            const compressed = await gzipAsync(Buffer.from(originalData, 'utf8'));
-            const size = getGzipUncompressedSize(compressed);
-            expect(size).toBe(testSize);
-        }
-    });
-    it('handles JSON array compression correctly', async () => {
-        const items = [{ id: 1 }, { id: 2 }, { id: 3 }];
-        const json = JSON.stringify(items);
-        const compressed = await gzipAsync(Buffer.from(json, 'utf8'));
-        const size = getGzipUncompressedSize(compressed);
-        expect(size).toBe(Buffer.byteLength(json, 'utf8'));
-    });
-});
+import { describe, it, expect, vi } from 'vitest';
+import { unbundleRecords, unbundleMessage, isBundledEnvelope } from '../../clients/generic/sqs-unbundle';
+import { CompressionAlgorithm } from '../../clients/generic/sqs-bundled-client.types';
+import { compress, CompressionTimeoutError, CompressionOperation, getGzipUncompressedSize, } from '../../utils/compression';
+import { gzip } from 'node:zlib';
+import { promisify } from 'node:util';
+const gzipAsync = promisify(gzip);
+vi.mock('../../helpers/logging-helper', () => ({
+    Logger: {
+        debug: vi.fn(),
+        info: vi.fn(),
+        warn: vi.fn(),
+        error: vi.fn(),
+    },
+}));
+function makeTestEvent(id, name = 'test_event', value) {
+    return { eventId: id, name, value };
+}
+function makeSqsRecord(body, messageId = 'msg-1') {
+    return {
+        messageId,
+        body: typeof body === 'string' ? body : JSON.stringify(body),
+    };
+}
+function makeBundledEnvelope(items) {
+    return {
+        v: 1,
+        c: CompressionAlgorithm.NONE,
+        n: items.length,
+        s: JSON.stringify(items).length,
+        p: items,
+    };
+}
+async function makeCompressedEnvelope(items, level = 3) {
+    const json = JSON.stringify(items);
+    const compressed = await compress(Buffer.from(json, 'utf8'), CompressionAlgorithm.ZSTD, level);
+    const base64 = compressed.toString('base64');
+    return {
+        v: 1,
+        c: CompressionAlgorithm.ZSTD,
+        n: items.length,
+        s: json.length,
+        p: base64,
+    };
+}
+async function makeGzipCompressedEnvelope(items) {
+    const json = JSON.stringify(items);
+    const compressed = await gzipAsync(Buffer.from(json, 'utf8'));
+    const base64 = compressed.toString('base64');
+    return {
+        v: 1,
+        c: CompressionAlgorithm.GZIP,
+        n: items.length,
+        s: json.length,
+        p: base64,
+    };
+}
+describe('isBundledEnvelope', () => {
+    it('returns true for valid bundled envelope with NONE compression', () => {
+        const envelope = makeBundledEnvelope([makeTestEvent('1')]);
+        expect(isBundledEnvelope(envelope)).toBe(true);
+    });
+    it('returns true for valid bundled envelope with ZSTD compression', async () => {
+        const envelope = await makeCompressedEnvelope([makeTestEvent('1')]);
+        expect(isBundledEnvelope(envelope)).toBe(true);
+    });
+    it('returns false for null', () => {
+        expect(isBundledEnvelope(null)).toBe(false);
+    });
+    it('returns false for undefined', () => {
+        expect(isBundledEnvelope(undefined)).toBe(false);
+    });
+    it('returns false for plain object (legacy message)', () => {
+        expect(isBundledEnvelope(makeTestEvent('1'))).toBe(false);
+    });
+    it('returns false for wrong version', () => {
+        const envelope = { v: 2, c: 'none', n: 1, p: [] };
+        expect(isBundledEnvelope(envelope)).toBe(false);
+    });
+    it('returns true for valid bundled envelope with GZIP compression', async () => {
+        const envelope = await makeGzipCompressedEnvelope([makeTestEvent('1')]);
+        expect(isBundledEnvelope(envelope)).toBe(true);
+    });
+    it('returns false for invalid compression algorithm', () => {
+        const envelope = { v: 1, c: 'lz4', n: 1, p: [] };
+        expect(isBundledEnvelope(envelope)).toBe(false);
+    });
+    it('returns false for missing count', () => {
+        const envelope = { v: 1, c: 'none', p: [] };
+        expect(isBundledEnvelope(envelope)).toBe(false);
+    });
+    it('returns false for missing payload', () => {
+        const envelope = { v: 1, c: 'none', n: 1 };
+        expect(isBundledEnvelope(envelope)).toBe(false);
+    });
+});
+describe('unbundleMessage', () => {
+    it('unbundles NONE compression envelope', async () => {
+        const items = [makeTestEvent('1'), makeTestEvent('2')];
+        const envelope = makeBundledEnvelope(items);
+        const result = await unbundleMessage(envelope);
+        expect(result).toHaveLength(2);
+        expect(result[0].eventId).toBe('1');
+        expect(result[1].eventId).toBe('2');
+    });
+    it('unbundles ZSTD compressed envelope', async () => {
+        const items = [makeTestEvent('1'), makeTestEvent('2'), makeTestEvent('3')];
+        const envelope = await makeCompressedEnvelope(items);
+        const result = await unbundleMessage(envelope);
+        expect(result).toHaveLength(3);
+        expect(result[0].eventId).toBe('1');
+        expect(result[1].eventId).toBe('2');
+        expect(result[2].eventId).toBe('3');
+    });
+    it('unbundles large batches with ZSTD compression', async () => {
+        const items = Array.from({ length: 500 }, (_, i) => makeTestEvent(`event-${i}`, `event_${i}`, i * 10));
+        const envelope = await makeCompressedEnvelope(items);
+        const result = await unbundleMessage(envelope);
+        expect(result).toHaveLength(500);
+        expect(result[0].eventId).toBe('event-0');
+        expect(result[499].eventId).toBe('event-499');
+    });
+    it('throws on unsupported bundle version', async () => {
+        const envelope = { v: 99, c: 'none', n: 1, p: [] };
+        await expect(unbundleMessage(envelope)).rejects.toThrow('Unsupported bundle version: 99');
+    });
+    it('throws on invalid payload type for NONE compression', async () => {
+        const envelope = { v: 1, c: 'none', n: 1, p: 'not-an-array' };
+        await expect(unbundleMessage(envelope)).rejects.toThrow('Invalid bundle: NONE compression but payload is not an array');
+    });
+    it('throws on invalid payload type for ZSTD compression', async () => {
+        const envelope = { v: 1, c: 'zstd', n: 1, p: [] };
+        await expect(unbundleMessage(envelope)).rejects.toThrow('Invalid bundle: zstd compression but payload is not a string');
+    });
+    it('unbundles GZIP compressed envelope', async () => {
+        const items = [makeTestEvent('1'), makeTestEvent('2'), makeTestEvent('3')];
+        const envelope = await makeGzipCompressedEnvelope(items);
+        const result = await unbundleMessage(envelope);
+        expect(result).toHaveLength(3);
+        expect(result[0].eventId).toBe('1');
+        expect(result[1].eventId).toBe('2');
+        expect(result[2].eventId).toBe('3');
+    });
+    it('unbundles large batches with GZIP compression', async () => {
+        const items = Array.from({ length: 500 }, (_, i) => makeTestEvent(`event-${i}`, `event_${i}`, i * 10));
+        const envelope = await makeGzipCompressedEnvelope(items);
+        const result = await unbundleMessage(envelope);
+        expect(result).toHaveLength(500);
+        expect(result[0].eventId).toBe('event-0');
+        expect(result[499].eventId).toBe('event-499');
+    });
+    it('throws on invalid payload type for GZIP compression', async () => {
+        const envelope = { v: 1, c: 'gzip', n: 1, p: [] };
+        await expect(unbundleMessage(envelope)).rejects.toThrow('Invalid bundle: gzip compression but payload is not a string');
+    });
+});
+describe('unbundleRecords', () => {
+    describe('legacy (non-bundled) messages', () => {
+        it('parses raw JSON message', async () => {
+            const event = makeTestEvent('raw-1', 'purchase');
+            const record = makeSqsRecord(event);
+            const { items, stats, failedMessageIds } = await unbundleRecords([record]);
+            expect(items).toHaveLength(1);
+            expect(items[0].eventId).toBe('raw-1');
+            expect(items[0].name).toBe('purchase');
+            expect(stats.legacySqsRecords).toBe(1);
+            expect(stats.bundledSqsRecords).toBe(0);
+            expect(failedMessageIds).toHaveLength(0);
+        });
+        it('parses wrapped messageBody format', async () => {
+            const event = makeTestEvent('wrapped-1');
+            const record = makeSqsRecord({ messageBody: event });
+            const { items, stats } = await unbundleRecords([record]);
+            expect(items).toHaveLength(1);
+            expect(items[0].eventId).toBe('wrapped-1');
+            expect(stats.legacySqsRecords).toBe(1);
+        });
+        it('handles multiple legacy records', async () => {
+            const records = [
+                makeSqsRecord(makeTestEvent('1'), 'msg-1'),
+                makeSqsRecord(makeTestEvent('2'), 'msg-2'),
+                makeSqsRecord(makeTestEvent('3'), 'msg-3'),
+            ];
+            const { items, stats, recordMap } = await unbundleRecords(records);
+            expect(items).toHaveLength(3);
+            expect(stats.legacySqsRecords).toBe(3);
+            expect(stats.totalItems).toBe(3);
+            expect(recordMap.get(items[0])).toBe('msg-1');
+            expect(recordMap.get(items[1])).toBe('msg-2');
+            expect(recordMap.get(items[2])).toBe('msg-3');
+        });
+    });
+    describe('bundled messages (NONE compression)', () => {
+        it('unbundles wrapped messageBody envelope', async () => {
+            const items = [makeTestEvent('b1'), makeTestEvent('b2')];
+            const envelope = makeBundledEnvelope(items);
+            const record = makeSqsRecord({ messageBody: envelope });
+            const { items: result, stats } = await unbundleRecords([record]);
+            expect(result).toHaveLength(2);
+            expect(result[0].eventId).toBe('b1');
+            expect(result[1].eventId).toBe('b2');
+            expect(stats.bundledSqsRecords).toBe(1);
+            expect(stats.legacySqsRecords).toBe(0);
+        });
+        it('unbundles raw envelope (not wrapped)', async () => {
+            const items = [makeTestEvent('r1'), makeTestEvent('r2')];
+            const envelope = makeBundledEnvelope(items);
+            const record = makeSqsRecord(envelope);
+            const { items: result, stats } = await unbundleRecords([record]);
+            expect(result).toHaveLength(2);
+            expect(stats.bundledSqsRecords).toBe(1);
+        });
+        it('maps all items from bundle to same messageId', async () => {
+            const items = [makeTestEvent('x1'), makeTestEvent('x2'), makeTestEvent('x3')];
+            const envelope = makeBundledEnvelope(items);
+            const record = makeSqsRecord({ messageBody: envelope }, 'bundle-msg-1');
+            const { items: result, recordMap } = await unbundleRecords([record]);
+            expect(result).toHaveLength(3);
+            expect(recordMap.get(result[0])).toBe('bundle-msg-1');
+            expect(recordMap.get(result[1])).toBe('bundle-msg-1');
+            expect(recordMap.get(result[2])).toBe('bundle-msg-1');
+        });
+    });
+    describe('bundled messages (ZSTD compression)', () => {
+        it('unbundles ZSTD compressed envelope', async () => {
+            const items = [makeTestEvent('z1'), makeTestEvent('z2')];
+            const envelope = await makeCompressedEnvelope(items);
+            const record = makeSqsRecord({ messageBody: envelope });
+            const { items: result, stats } = await unbundleRecords([record]);
+            expect(result).toHaveLength(2);
+            expect(result[0].eventId).toBe('z1');
+            expect(result[1].eventId).toBe('z2');
+            expect(stats.bundledSqsRecords).toBe(1);
+        });
+        it('handles large compressed bundles (500 items)', async () => {
+            const items = Array.from({ length: 500 }, (_, i) => makeTestEvent(`item-${i}`));
+            const envelope = await makeCompressedEnvelope(items);
+            const record = makeSqsRecord({ messageBody: envelope });
+            const { items: result, stats } = await unbundleRecords([record]);
+            expect(result).toHaveLength(500);
+            expect(stats.bundledSqsRecords).toBe(1);
+            expect(stats.totalItems).toBe(500);
+        });
+    });
+    describe('bundled messages (GZIP compression - CF Worker)', () => {
+        it('unbundles GZIP compressed envelope', async () => {
+            const items = [makeTestEvent('g1'), makeTestEvent('g2')];
+            const envelope = await makeGzipCompressedEnvelope(items);
+            const record = makeSqsRecord({ messageBody: envelope });
+            const { items: result, stats } = await unbundleRecords([record]);
+            expect(result).toHaveLength(2);
+            expect(result[0].eventId).toBe('g1');
+            expect(result[1].eventId).toBe('g2');
+            expect(stats.bundledSqsRecords).toBe(1);
+        });
+        it('handles large GZIP compressed bundles (500 items)', async () => {
+            const items = Array.from({ length: 500 }, (_, i) => makeTestEvent(`item-${i}`));
+            const envelope = await makeGzipCompressedEnvelope(items);
+            const record = makeSqsRecord({ messageBody: envelope });
+            const { items: result, stats } = await unbundleRecords([record]);
+            expect(result).toHaveLength(500);
+            expect(stats.bundledSqsRecords).toBe(1);
+            expect(stats.totalItems).toBe(500);
+        });
+        it('maps all items from GZIP bundle to same messageId', async () => {
+            const items = [makeTestEvent('x1'), makeTestEvent('x2'), makeTestEvent('x3')];
+            const envelope = await makeGzipCompressedEnvelope(items);
+            const record = makeSqsRecord({ messageBody: envelope }, 'gzip-bundle-msg-1');
+            const { items: result, recordMap } = await unbundleRecords([record]);
+            expect(result).toHaveLength(3);
+            expect(recordMap.get(result[0])).toBe('gzip-bundle-msg-1');
+            expect(recordMap.get(result[1])).toBe('gzip-bundle-msg-1');
+            expect(recordMap.get(result[2])).toBe('gzip-bundle-msg-1');
+        });
+        it('unbundles GZIP envelope wrapped in full InternalSQSMessage format (CF Worker format)', async () => {
+            const items = [makeTestEvent('cf1'), makeTestEvent('cf2'), makeTestEvent('cf3')];
+            const envelope = await makeGzipCompressedEnvelope(items);
+            const internalSqsMessage = {
+                messageId: 'cf-internal-msg-123',
+                messageType: 'TRACKING_EVENT_COLLECT',
+                messageTime: '2026-05-29T11:00:10.076Z',
+                messageBody: envelope,
+            };
+            const record = makeSqsRecord(internalSqsMessage, 'sqs-msg-id');
+            const { items: result, stats, recordMap } = await unbundleRecords([record]);
+            expect(result).toHaveLength(3);
+            expect(result[0].eventId).toBe('cf1');
+            expect(result[1].eventId).toBe('cf2');
+            expect(result[2].eventId).toBe('cf3');
+            expect(stats.bundledSqsRecords).toBe(1);
+            expect(stats.legacySqsRecords).toBe(0);
+            expect(stats.totalItems).toBe(3);
+            expect(recordMap.get(result[0])).toBe('sqs-msg-id');
+            expect(recordMap.get(result[1])).toBe('sqs-msg-id');
+            expect(recordMap.get(result[2])).toBe('sqs-msg-id');
+        });
+        it('unbundles GZIP envelope with extra wrapper fields (messageTime, messageType)', async () => {
+            const items = [makeTestEvent('w1')];
+            const envelope = await makeGzipCompressedEnvelope(items);
+            const wrappedMessage = {
+                messageTime: new Date().toISOString(),
+                messageType: 'SESSION_EVENT',
+                messageBody: envelope,
+                someOtherField: 'ignored',
+            };
+            const record = makeSqsRecord(wrappedMessage);
+            const { items: result, stats } = await unbundleRecords([record]);
+            expect(result).toHaveLength(1);
+            expect(result[0].eventId).toBe('w1');
+            expect(stats.bundledSqsRecords).toBe(1);
+        });
+        it('handles decompression failure gracefully (does not return wrapper)', async () => {
+            const corruptedEnvelope = {
+                v: 1,
+                c: 'gzip',
+                n: 1,
+                s: 100,
+                p: 'H4sIAAAAAAAAA+TRUNCATED',
+            };
+            const internalSqsMessage = {
+                messageTime: '2026-05-29T11:00:10.076Z',
+                messageType: 'TRACKING_EVENT_COLLECT',
+                messageBody: corruptedEnvelope,
+                messageId: 'corrupted-msg-id',
+            };
+            const record = makeSqsRecord(internalSqsMessage, 'sqs-record-id');
+            const { items, stats, failedMessageIds } = await unbundleRecords([record]);
+            expect(failedMessageIds).toHaveLength(1);
+            expect(stats.failedRecords).toBe(1);
+            expect(items).toHaveLength(0);
+            items.forEach((item) => {
+                expect(item).not.toHaveProperty('messageTime');
+                expect(item).not.toHaveProperty('messageType');
+                expect(item).not.toHaveProperty('messageBody');
+            });
+        });
+        it('verifies decompression failure does NOT leak wrapper into items', async () => {
+            const badEnvelope = {
+                v: 1,
+                c: 'gzip',
+                n: 5,
+                s: 1000,
+                p: 'dGhpcyBpcyBub3QgdmFsaWQgZ3ppcA==',
+            };
+            const wrapper = {
+                messageTime: new Date().toISOString(),
+                messageType: 'TRACKING_EVENT_COLLECT',
+                messageBody: badEnvelope,
+                messageId: 'test-internal-msg-id',
+            };
+            const record = makeSqsRecord(wrapper, 'sqs-msg-id');
+            const { items, stats, failedMessageIds } = await unbundleRecords([record]);
+            expect(failedMessageIds).toContain('sqs-msg-id');
+            expect(stats.failedRecords).toBe(1);
+            expect(items).toHaveLength(0);
+            expect(stats.totalItems).toBe(0);
+        });
+        it('simulates old version without GZIP - returns envelope as item (BUG)', async () => {
+            const items = [{ pixelId: 'px123', trackingEvent: { name: 'page_view' } }];
+            const envelope = await makeGzipCompressedEnvelope(items);
+            const wrapper = {
+                messageTime: new Date().toISOString(),
+                messageType: 'TRACKING_EVENT_COLLECT',
+                messageBody: envelope,
+                messageId: 'cf-msg-id',
+            };
+            expect(isBundledEnvelope(envelope)).toBe(true);
+            const record = makeSqsRecord(wrapper, 'sqs-msg-id');
+            const { items: result, stats } = await unbundleRecords([record]);
+            expect(stats.bundledSqsRecords).toBe(1);
+            expect(result).toHaveLength(1);
+            expect(result[0].pixelId).toBe('px123');
+            expect(result[0]).not.toHaveProperty('v');
+            expect(result[0]).not.toHaveProperty('c');
+            expect(result[0]).not.toHaveProperty('n');
+            expect(result[0]).not.toHaveProperty('p');
+            expect(result[0]).not.toHaveProperty('s');
+        });
+        it('unknown compression algorithm causes legacy fallback (returns messageBody)', async () => {
+            const unknownEnvelope = {
+                v: 1,
+                c: 'lz4',
+                n: 1,
+                s: 100,
+                p: 'some-base64-data',
+            };
+            const wrapper = {
+                messageTime: new Date().toISOString(),
+                messageType: 'TEST_MESSAGE',
+                messageBody: unknownEnvelope,
+                messageId: 'wrapper-msg-id',
+            };
+            expect(isBundledEnvelope(unknownEnvelope)).toBe(false);
+            const record = makeSqsRecord(wrapper, 'sqs-msg-id');
+            const { items, stats } = await unbundleRecords([record]);
+            expect(stats.legacySqsRecords).toBe(1);
+            expect(stats.bundledSqsRecords).toBe(0);
+            expect(items).toHaveLength(1);
+            expect(items[0]).toHaveProperty('v', 1);
+            expect(items[0]).toHaveProperty('c', 'lz4');
+            expect(items[0]).toHaveProperty('n', 1);
+            expect(items[0]).toHaveProperty('p');
+        });
+    });
+    describe('mixed message formats', () => {
+        it('handles mix of legacy and bundled messages', async () => {
+            const legacyEvent = makeTestEvent('legacy-1');
+            const bundledItems = [makeTestEvent('bundled-1'), makeTestEvent('bundled-2')];
+            const bundleEnvelope = makeBundledEnvelope(bundledItems);
+            const records = [
+                makeSqsRecord(legacyEvent, 'msg-legacy'),
+                makeSqsRecord({ messageBody: bundleEnvelope }, 'msg-bundle'),
+            ];
+            const { items, stats, recordMap } = await unbundleRecords(records);
+            expect(items).toHaveLength(3);
+            expect(stats.legacySqsRecords).toBe(1);
+            expect(stats.bundledSqsRecords).toBe(1);
+            expect(stats.totalItems).toBe(3);
+            expect(recordMap.get(items[0])).toBe('msg-legacy');
+            expect(recordMap.get(items[1])).toBe('msg-bundle');
+            expect(recordMap.get(items[2])).toBe('msg-bundle');
+        });
+        it('handles mix of NONE and ZSTD compressed bundles', async () => {
+            const noneItems = [makeTestEvent('none-1')];
+            const zstdItems = [makeTestEvent('zstd-1'), makeTestEvent('zstd-2')];
+            const noneEnvelope = makeBundledEnvelope(noneItems);
+            const zstdEnvelope = await makeCompressedEnvelope(zstdItems);
+            const records = [
+                makeSqsRecord({ messageBody: noneEnvelope }, 'msg-none'),
+                makeSqsRecord({ messageBody: zstdEnvelope }, 'msg-zstd'),
+            ];
+            const { items, stats } = await unbundleRecords(records);
+            expect(items).toHaveLength(3);
+            expect(stats.bundledSqsRecords).toBe(2);
+            expect(stats.totalItems).toBe(3);
+        });
+        it('handles mix of ZSTD, GZIP, and legacy messages', async () => {
+            const legacyEvent = makeTestEvent('legacy-1');
+            const zstdItems = [makeTestEvent('zstd-1'), makeTestEvent('zstd-2')];
+            const gzipItems = [makeTestEvent('gzip-1'), makeTestEvent('gzip-2'), makeTestEvent('gzip-3')];
+            const zstdEnvelope = await makeCompressedEnvelope(zstdItems);
+            const gzipEnvelope = await makeGzipCompressedEnvelope(gzipItems);
+            const records = [
+                makeSqsRecord(legacyEvent, 'msg-legacy'),
+                makeSqsRecord({ messageBody: zstdEnvelope }, 'msg-zstd'),
+                makeSqsRecord({ messageBody: gzipEnvelope }, 'msg-gzip'),
+            ];
+            const { items, stats, recordMap } = await unbundleRecords(records);
+            expect(items).toHaveLength(6);
+            expect(stats.legacySqsRecords).toBe(1);
+            expect(stats.bundledSqsRecords).toBe(2);
+            expect(stats.totalItems).toBe(6);
+            expect(recordMap.get(items[0])).toBe('msg-legacy');
+            expect(recordMap.get(items[1])).toBe('msg-zstd');
+            expect(recordMap.get(items[2])).toBe('msg-zstd');
+            expect(recordMap.get(items[3])).toBe('msg-gzip');
+            expect(recordMap.get(items[4])).toBe('msg-gzip');
+            expect(recordMap.get(items[5])).toBe('msg-gzip');
+        });
+    });
+    describe('error handling', () => {
+        it('returns failed messageId for invalid JSON', async () => {
+            const records = [makeSqsRecord('not-valid-json{{{', 'msg-bad'), makeSqsRecord(makeTestEvent('good'), 'msg-good')];
+            const { items, failedMessageIds, stats } = await unbundleRecords(records);
+            expect(items).toHaveLength(1);
+            expect(items[0].eventId).toBe('good');
+            expect(failedMessageIds).toEqual(['msg-bad']);
+            expect(stats.failedRecords).toBe(1);
+            expect(stats.legacySqsRecords).toBe(1);
+        });
+        it('returns failed messageId for corrupt ZSTD compressed data', async () => {
+            const corruptEnvelope = {
+                v: 1,
+                c: CompressionAlgorithm.ZSTD,
+                n: 10,
+                p: 'dGhpcyBpcyBub3QgdmFsaWQgenN0ZA==',
+            };
+            const records = [
+                makeSqsRecord({ messageBody: corruptEnvelope }, 'msg-corrupt'),
+                makeSqsRecord(makeTestEvent('valid'), 'msg-valid'),
+            ];
+            const { items, failedMessageIds, stats } = await unbundleRecords(records);
+            expect(items).toHaveLength(1);
+            expect(items[0].eventId).toBe('valid');
+            expect(failedMessageIds).toContain('msg-corrupt');
+            expect(stats.failedRecords).toBe(1);
+        });
+        it('returns failed messageId for corrupt GZIP compressed data', async () => {
+            const corruptEnvelope = {
+                v: 1,
+                c: CompressionAlgorithm.GZIP,
+                n: 10,
+                p: 'dGhpcyBpcyBub3QgdmFsaWQgZ3ppcA==',
+            };
+            const records = [
+                makeSqsRecord({ messageBody: corruptEnvelope }, 'msg-corrupt-gzip'),
+                makeSqsRecord(makeTestEvent('valid'), 'msg-valid'),
+            ];
+            const { items, failedMessageIds, stats } = await unbundleRecords(records);
+            expect(items).toHaveLength(1);
+            expect(items[0].eventId).toBe('valid');
+            expect(failedMessageIds).toContain('msg-corrupt-gzip');
+            expect(stats.failedRecords).toBe(1);
+        });
+        it('returns empty result for all failed records', async () => {
+            const records = [makeSqsRecord('invalid-1', 'msg-1'), makeSqsRecord('invalid-2', 'msg-2')];
+            const { items, failedMessageIds, stats } = await unbundleRecords(records);
+            expect(items).toHaveLength(0);
+            expect(failedMessageIds).toEqual(['msg-1', 'msg-2']);
+            expect(stats.failedRecords).toBe(2);
+            expect(stats.totalItems).toBe(0);
+        });
+        it('handles empty records array', async () => {
+            const { items, failedMessageIds, stats } = await unbundleRecords([]);
+            expect(items).toHaveLength(0);
+            expect(failedMessageIds).toHaveLength(0);
+            expect(stats.totalRecords).toBe(0);
+            expect(stats.totalItems).toBe(0);
+        });
+        it('rejects ZSTD payload exceeding max decompressed size', async () => {
+            const largeItems = Array.from({ length: 1000 }, (_, i) => ({
+                id: `item-${i}`,
+                data: 'x'.repeat(1000),
+            }));
+            const envelope = await makeCompressedEnvelope(largeItems);
+            const record = makeSqsRecord({ messageBody: envelope }, 'msg-too-large');
+            const { failedMessageIds, stats } = await unbundleRecords([record], {
+                maxDecompressedSizeBytes: 100 * 1024,
+            });
+            expect(failedMessageIds).toContain('msg-too-large');
+            expect(stats.failedRecords).toBe(1);
+        });
+        it('rejects GZIP payload exceeding max decompressed size (post-decompress check)', async () => {
+            const largeItems = Array.from({ length: 1000 }, (_, i) => ({
+                id: `item-${i}`,
+                data: 'x'.repeat(1000),
+            }));
+            const envelope = await makeGzipCompressedEnvelope(largeItems);
+            const record = makeSqsRecord({ messageBody: envelope }, 'msg-too-large-gzip');
+            const { failedMessageIds, stats } = await unbundleRecords([record], {
+                maxDecompressedSizeBytes: 100 * 1024,
+            });
+            expect(failedMessageIds).toContain('msg-too-large-gzip');
+            expect(stats.failedRecords).toBe(1);
+        });
+        it('fails on invalid base64 in compressed payload', async () => {
+            const badEnvelope = {
+                v: 1,
+                c: CompressionAlgorithm.ZSTD,
+                n: 1,
+                s: 100,
+                p: '!!!not-valid-base64!!!',
+            };
+            const record = makeSqsRecord({ messageBody: badEnvelope }, 'msg-bad-base64');
+            const { failedMessageIds } = await unbundleRecords([record]);
+            expect(failedMessageIds).toContain('msg-bad-base64');
+        });
+    });
+    describe('bundle format edge cases', () => {
+        it('successfully unbundles even when n does not match actual item count', async () => {
+            const envelope = {
+                v: 1,
+                c: CompressionAlgorithm.NONE,
+                n: 5,
+                s: 50,
+                p: [makeTestEvent('1'), makeTestEvent('2')],
+            };
+            const record = makeSqsRecord({ messageBody: envelope });
+            const { items } = await unbundleRecords([record]);
+            expect(items).toHaveLength(2);
+        });
+        it('treats envelope with unsupported version as legacy message', async () => {
+            const badEnvelope = { v: 99, c: 'none', n: 1, s: 10, p: [] };
+            const record = makeSqsRecord({ messageBody: badEnvelope }, 'msg-bad-version');
+            const { items, stats } = await unbundleRecords([record]);
+            expect(items).toHaveLength(1);
+            expect(items[0].v).toBe(99);
+            expect(stats.legacySqsRecords).toBe(1);
+            expect(stats.bundledSqsRecords).toBe(0);
+        });
+    });
+    describe('timeout protection', () => {
+        it('respects timeoutMs option for ZSTD', async () => {
+            const items = [makeTestEvent('1')];
+            const envelope = await makeCompressedEnvelope(items);
+            const record = makeSqsRecord({ messageBody: envelope });
+            const { items: result, failedMessageIds } = await unbundleRecords([record], {
+                timeoutMs: 5000,
+            });
+            expect(result).toHaveLength(1);
+            expect(failedMessageIds).toHaveLength(0);
+        });
+        it('respects timeoutMs option for GZIP', async () => {
+            const items = [makeTestEvent('1')];
+            const envelope = await makeGzipCompressedEnvelope(items);
+            const record = makeSqsRecord({ messageBody: envelope });
+            const { items: result, failedMessageIds } = await unbundleRecords([record], {
+                timeoutMs: 5000,
+            });
+            expect(result).toHaveLength(1);
+            expect(failedMessageIds).toHaveLength(0);
+        });
+        it('passes timeoutMs through to decompression', async () => {
+            const items = [makeTestEvent('1')];
+            const envelope = await makeCompressedEnvelope(items);
+            const record = makeSqsRecord({ messageBody: envelope });
+            await expect(unbundleRecords([record], { timeoutMs: 30000 })).resolves.toBeDefined();
+        });
+        it('CompressionTimeoutError is properly exported', () => {
+            const error = new CompressionTimeoutError(CompressionOperation.DECOMPRESS, 5000);
+            expect(error).toBeInstanceOf(Error);
+            expect(error.name).toBe('CompressionTimeoutError');
+            expect(error.operation).toBe('decompress');
+            expect(error.timeoutMs).toBe(5000);
+            expect(error.message).toContain('timed out after 5000ms');
+        });
+        it('includes timeout info in failure logging for ZSTD', async () => {
+            const corruptEnvelope = {
+                v: 1,
+                c: CompressionAlgorithm.ZSTD,
+                n: 1,
+                s: 100,
+                p: 'dGhpcyBpcyBub3QgdmFsaWQgenN0ZA==',
+            };
+            const record = makeSqsRecord({ messageBody: corruptEnvelope }, 'msg-timeout-test');
+            const { failedMessageIds } = await unbundleRecords([record], {
+                timeoutMs: 5000,
+            });
+            expect(failedMessageIds).toContain('msg-timeout-test');
+        });
+        it('includes timeout info in failure logging for GZIP', async () => {
+            const corruptEnvelope = {
+                v: 1,
+                c: CompressionAlgorithm.GZIP,
+                n: 1,
+                s: 100,
+                p: 'dGhpcyBpcyBub3QgdmFsaWQgZ3ppcA==',
+            };
+            const record = makeSqsRecord({ messageBody: corruptEnvelope }, 'msg-gzip-timeout-test');
+            const { failedMessageIds } = await unbundleRecords([record], {
+                timeoutMs: 5000,
+            });
+            expect(failedMessageIds).toContain('msg-gzip-timeout-test');
+        });
+    });
+    describe('end-to-end: producer bundle → consumer unbundle', () => {
+        it('simulates full bundle → unbundle flow with compression', async () => {
+            const producerItems = Array.from({ length: 100 }, (_, i) => makeTestEvent(`event-${i}`, 'page_view', i * 1.5));
+            const envelope = await makeCompressedEnvelope(producerItems, 3);
+            const sqsMessageBody = { messageBody: envelope };
+            const consumerRecord = makeSqsRecord(sqsMessageBody, 'sqs-message-id-123');
+            const { items, recordMap, stats } = await unbundleRecords([consumerRecord]);
+            expect(items).toHaveLength(100);
+            expect(items[0]).toEqual({ eventId: 'event-0', name: 'page_view', value: 0 });
+            expect(items[99]).toEqual({ eventId: 'event-99', name: 'page_view', value: 148.5 });
+            expect(stats.bundledSqsRecords).toBe(1);
+            expect(stats.legacySqsRecords).toBe(0);
+            expect(stats.totalItems).toBe(100);
+            for (const item of items) {
+                expect(recordMap.get(item)).toBe('sqs-message-id-123');
+            }
+        });
+        it('simulates mixed batch with legacy and bundled messages', async () => {
+            const legacyRecord1 = makeSqsRecord({ messageBody: makeTestEvent('legacy-1', 'purchase', 99.99) }, 'legacy-msg-1');
+            const legacyRecord2 = makeSqsRecord(makeTestEvent('legacy-2', 'add_to_cart', 29.99), 'legacy-msg-2');
+            const bundledItems = [
+                makeTestEvent('bundled-1', 'page_view'),
+                makeTestEvent('bundled-2', 'session_start'),
+                makeTestEvent('bundled-3', 'page_end'),
+            ];
+            const envelope = await makeCompressedEnvelope(bundledItems);
+            const bundledRecord = makeSqsRecord({ messageBody: envelope }, 'bundled-msg-1');
+            const records = [legacyRecord1, bundledRecord, legacyRecord2];
+            const { items, stats, recordMap } = await unbundleRecords(records);
+            expect(items).toHaveLength(5);
+            expect(stats.legacySqsRecords).toBe(2);
+            expect(stats.bundledSqsRecords).toBe(1);
+            expect(stats.totalItems).toBe(5);
+            expect(recordMap.get(items[0])).toBe('legacy-msg-1');
+            expect(recordMap.get(items[1])).toBe('bundled-msg-1');
+            expect(recordMap.get(items[2])).toBe('bundled-msg-1');
+            expect(recordMap.get(items[3])).toBe('bundled-msg-1');
+            expect(recordMap.get(items[4])).toBe('legacy-msg-2');
+        });
+    });
+    describe('consumer edge cases - real sequences', () => {
+        it('handles 500 items in single compressed bundle with exact verification', async () => {
+            const originalItems = Array.from({ length: 500 }, (_, i) => ({
+                id: `item-${i}`,
+                name: `Event ${i}`,
+                data: { nested: { value: i * 1.5 } },
+                timestamp: Date.now() + i,
+            }));
+            const envelope = await makeCompressedEnvelope(originalItems);
+            const record = makeSqsRecord({ messageBody: envelope }, 'msg-500-items');
+            const { items, recordMap, stats } = await unbundleRecords([record]);
+            expect(items).toHaveLength(500);
+            expect(items[0]).toEqual(originalItems[0]);
+            expect(items[249]).toEqual(originalItems[249]);
+            expect(items[499]).toEqual(originalItems[499]);
+            expect(stats.bundledSqsRecords).toBe(1);
+            expect(stats.totalItems).toBe(500);
+            for (let i = 0; i < 500; i++) {
+                expect(items[i].id).toBe(`item-${i}`);
+                expect(items[i].data.nested.value).toBe(i * 1.5);
+            }
+            for (const item of items) {
+                expect(recordMap.get(item)).toBe('msg-500-items');
+            }
+        });
+        it('handles multiple bundles in single batch with different item counts', async () => {
+            const counts = [10, 50, 100, 200, 300];
+            const records = [];
+            const expectedTotal = counts.reduce((sum, c) => sum + c, 0);
+            for (let bundleIdx = 0; bundleIdx < counts.length; bundleIdx++) {
+                const count = counts[bundleIdx];
+                const items = Array.from({ length: count }, (_, i) => ({
+                    bundleId: bundleIdx,
+                    itemIdx: i,
+                    payload: `bundle-${bundleIdx}-item-${i}`,
+                }));
+                const envelope = await makeCompressedEnvelope(items);
+                records.push(makeSqsRecord({ messageBody: envelope }, `msg-bundle-${bundleIdx}`));
+            }
+            const { items, recordMap, stats } = await unbundleRecords(records);
+            expect(items).toHaveLength(expectedTotal);
+            expect(stats.totalItems).toBe(expectedTotal);
+            expect(stats.bundledSqsRecords).toBe(5);
+            expect(stats.legacySqsRecords).toBe(0);
+            expect(stats.failedRecords).toBe(0);
+            const itemsByBundle = new Map();
+            for (const item of items) {
+                const expectedMsgId = `msg-bundle-${item.bundleId}`;
+                expect(recordMap.get(item)).toBe(expectedMsgId);
+                itemsByBundle.set(item.bundleId, (itemsByBundle.get(item.bundleId) ?? 0) + 1);
+            }
+            expect(itemsByBundle.get(0)).toBe(10);
+            expect(itemsByBundle.get(1)).toBe(50);
+            expect(itemsByBundle.get(2)).toBe(100);
+            expect(itemsByBundle.get(3)).toBe(200);
+            expect(itemsByBundle.get(4)).toBe(300);
+        });
+        it('handles realistic 80% bundled / 20% legacy migration ratio', async () => {
+            const records = [];
+            const totalMessages = 100;
+            const bundledCount = 80;
+            const legacyCount = 20;
+            const itemsPerBundle = 25;
+            for (let i = 0; i < bundledCount; i++) {
+                const items = Array.from({ length: itemsPerBundle }, (_, j) => ({
+                    type: 'bundled',
+                    bundleIdx: i,
+                    itemIdx: j,
+                }));
+                const envelope = await makeCompressedEnvelope(items);
+                records.push(makeSqsRecord({ messageBody: envelope }, `msg-bundled-${i}`));
+            }
+            for (let i = 0; i < legacyCount; i++) {
+                const legacyEvent = {
+                    type: 'legacy',
+                    legacyIdx: i,
+                    itemIdx: 0,
+                };
+                records.push(makeSqsRecord(legacyEvent, `msg-legacy-${i}`));
+            }
+            const shuffled = [...records].sort(() => Math.random() - 0.5);
+            const { items, stats, recordMap } = await unbundleRecords(shuffled);
+            expect(stats.totalRecords).toBe(totalMessages);
+            expect(stats.bundledSqsRecords).toBe(bundledCount);
+            expect(stats.legacySqsRecords).toBe(legacyCount);
+            expect(stats.failedRecords).toBe(0);
+            expect(items).toHaveLength(bundledCount * itemsPerBundle + legacyCount);
+            expect(stats.totalItems).toBe(2020);
+            const bundledItems = items.filter((i) => i.type === 'bundled');
+            const legacyItems = items.filter((i) => i.type === 'legacy');
+            expect(bundledItems).toHaveLength(bundledCount * itemsPerBundle);
+            expect(legacyItems).toHaveLength(legacyCount);
+            for (const item of bundledItems) {
+                expect(recordMap.get(item)).toBe(`msg-bundled-${item.bundleIdx}`);
+            }
+            for (const item of legacyItems) {
+                expect(recordMap.get(item)).toBe(`msg-legacy-${item.legacyIdx}`);
+            }
+        });
+        it('preserves Unicode characters through ZSTD compression', async () => {
+            const unicodeItems = [
+                {
+                    id: 'emoji',
+                    content: '🎉🚀💻🌍✨ Party time!',
+                    description: 'Emojis should survive compression',
+                },
+                {
+                    id: 'chinese',
+                    content: '中文测试：欢迎使用我们的服务',
+                    description: 'Chinese characters',
+                },
+                {
+                    id: 'arabic',
+                    content: 'العربية: مرحبا بكم في خدمتنا',
+                    description: 'Arabic text (RTL)',
+                },
+                {
+                    id: 'math',
+                    content: '∑∫∂∇ε → ∞ × ∈ ⊆ ∀∃',
+                    description: 'Mathematical symbols',
+                },
+                {
+                    id: 'mixed',
+                    content: 'Hello 世界 🌏 مرحبا ∑ Привет',
+                    description: 'Mixed scripts',
+                },
+                {
+                    id: 'special',
+                    content: '️️️️️️️️️️️️️️️️',
+                    description: 'Unicode edge cases',
+                },
+                {
+                    id: 'japanese',
+                    content: 'こんにちは世界 ひらがな カタカナ 漢字',
+                    description: 'Japanese hiragana, katakana, kanji',
+                },
+                {
+                    id: 'korean',
+                    content: '안녕하세요 세계',
+                    description: 'Korean hangul',
+                },
+                {
+                    id: 'cyrillic',
+                    content: 'Привет мир! Это тест.',
+                    description: 'Russian Cyrillic',
+                },
+                {
+                    id: 'combining',
+                    content: 'e\u0301 n\u0303 c\u0327',
+                    description: 'Combining diacritical marks',
+                },
+            ];
+            const envelope = await makeCompressedEnvelope(unicodeItems);
+            const record = makeSqsRecord({ messageBody: envelope }, 'msg-unicode');
+            const { items } = await unbundleRecords([record]);
+            expect(items).toHaveLength(unicodeItems.length);
+            for (let i = 0; i < unicodeItems.length; i++) {
+                expect(items[i].id).toBe(unicodeItems[i].id);
+                expect(items[i].content).toBe(unicodeItems[i].content);
+                expect(items[i].description).toBe(unicodeItems[i].description);
+                const originalBytes = Buffer.from(unicodeItems[i].content, 'utf8');
+                const recoveredBytes = Buffer.from(items[i].content, 'utf8');
+                expect(recoveredBytes.equals(originalBytes)).toBe(true);
+            }
+        });
+        it('preserves deeply nested structures (10 levels)', async () => {
+            function createDeepStructure(depth, maxDepth = 10) {
+                const node = {
+                    level: depth,
+                    data: `level-${depth}-data-${Math.random().toString(36).slice(2)}`,
+                };
+                if (depth < maxDepth) {
+                    node.child = createDeepStructure(depth + 1, maxDepth);
+                    node.siblings = [
+                        createDeepStructure(depth + 1, Math.min(depth + 3, maxDepth)),
+                        createDeepStructure(depth + 1, Math.min(depth + 2, maxDepth)),
+                    ];
+                }
+                return node;
+            }
+            const deepItems = Array.from({ length: 10 }, (_, i) => ({
+                id: `deep-${i}`,
+                nested: createDeepStructure(0, 10),
+                arrays: [[[[[['deeply', 'nested', 'array']]], [{ inner: { value: i } }]]]],
+            }));
+            const envelope = await makeCompressedEnvelope(deepItems);
+            const record = makeSqsRecord({ messageBody: envelope }, 'msg-deep');
+            const { items } = await unbundleRecords([record]);
+            expect(items).toHaveLength(10);
+            for (let i = 0; i < 10; i++) {
+                expect(JSON.stringify(items[i])).toBe(JSON.stringify(deepItems[i]));
+                expect(items[i].nested.level).toBe(0);
+                expect(items[i].nested.child?.level).toBe(1);
+                expect(items[i].nested.child?.child?.child?.level).toBe(3);
+                expect(items[i].arrays[0][0][0][0][0][0]).toBe('deeply');
+            }
+        });
+        it('handles binary-like string data (base64 encoded)', async () => {
+            const binaryItems = [
+                {
+                    id: 'small-binary',
+                    base64Data: Buffer.from('Small binary payload').toString('base64'),
+                    size: 'small',
+                },
+                {
+                    id: 'medium-binary',
+                    base64Data: Buffer.from('x'.repeat(1000)).toString('base64'),
+                    size: 'medium',
+                },
+                {
+                    id: 'image-simulation',
+                    base64Data: Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0xff, 0xd8, 0xff, 0xe0]).toString('base64'),
+                    size: 'binary-header',
+                },
+                {
+                    id: 'random-bytes',
+                    base64Data: Buffer.from(Array.from({ length: 256 }, () => Math.floor(Math.random() * 256))).toString('base64'),
+                    size: 'random',
+                },
+                {
+                    id: 'all-byte-values',
+                    base64Data: Buffer.from(Array.from({ length: 256 }, (_, i) => i)).toString('base64'),
+                    size: 'full-range',
+                },
+            ];
+            const envelope = await makeCompressedEnvelope(binaryItems);
+            const record = makeSqsRecord({ messageBody: envelope }, 'msg-binary');
+            const { items } = await unbundleRecords([record]);
+            expect(items).toHaveLength(binaryItems.length);
+            for (let i = 0; i < binaryItems.length; i++) {
+                expect(items[i].id).toBe(binaryItems[i].id);
+                expect(items[i].base64Data).toBe(binaryItems[i].base64Data);
+                const originalDecoded = Buffer.from(binaryItems[i].base64Data, 'base64');
+                const recoveredDecoded = Buffer.from(items[i].base64Data, 'base64');
+                expect(recoveredDecoded.equals(originalDecoded)).toBe(true);
+            }
+        });
+        it('handles concurrent unbundling stress test (100 records in parallel)', async () => {
+            const recordCount = 100;
+            const records = [];
+            for (let i = 0; i < recordCount; i++) {
+                const itemsInBundle = 10 + (i % 20);
+                const items = Array.from({ length: itemsInBundle }, (_, j) => ({
+                    recordIdx: i,
+                    itemIdx: j,
+                    uniqueId: `r${i}-i${j}`,
+                    timestamp: Date.now() + i * 1000 + j,
+                    data: `payload-${i}-${j}-${Math.random().toString(36).slice(2)}`,
+                }));
+                const envelope = await makeCompressedEnvelope(items);
+                records.push(makeSqsRecord({ messageBody: envelope }, `stress-msg-${i}`));
+            }
+            const startTime = Date.now();
+            const { items, recordMap, stats, failedMessageIds } = await unbundleRecords(records);
+            const duration = Date.now() - startTime;
+            expect(failedMessageIds).toHaveLength(0);
+            expect(stats.failedRecords).toBe(0);
+            expect(stats.bundledSqsRecords).toBe(recordCount);
+            const seenUniqueIds = new Set();
+            for (const item of items) {
+                expect(seenUniqueIds.has(item.uniqueId)).toBe(false);
+                seenUniqueIds.add(item.uniqueId);
+                const expectedMsgId = `stress-msg-${item.recordIdx}`;
+                expect(recordMap.get(item)).toBe(expectedMsgId);
+                expect(item.itemIdx).toBeGreaterThanOrEqual(0);
+                expect(item.itemIdx).toBeLessThan(30);
+            }
+            const expectedTotal = Array.from({ length: recordCount }, (_, i) => 10 + (i % 20)).reduce((a, b) => a + b, 0);
+            expect(items).toHaveLength(expectedTotal);
+            expect(stats.totalItems).toBe(expectedTotal);
+            console.log(`Unbundled ${recordCount} records (${stats.totalItems} items) in ${duration}ms`);
+        });
+        it('handles items with all JSON primitive types', async () => {
+            const primitiveItems = [
+                {
+                    id: 'primitives',
+                    stringVal: 'hello',
+                    numberVal: 42,
+                    floatVal: 3.14159265359,
+                    boolTrue: true,
+                    boolFalse: false,
+                    nullVal: null,
+                    emptyString: '',
+                    zero: 0,
+                    negativeNum: -999,
+                    largeNum: Number.MAX_SAFE_INTEGER,
+                    smallNum: Number.MIN_SAFE_INTEGER,
+                    scientificNotation: 1.23e10,
+                },
+                {
+                    id: 'arrays',
+                    emptyArray: [],
+                    numberArray: [1, 2, 3],
+                    mixedArray: [1, 'two', true, null],
+                    nestedArray: [[1, 2], [3, 4], [[5]]],
+                },
+                {
+                    id: 'objects',
+                    emptyObject: {},
+                    nestedObject: { a: { b: { c: 1 } } },
+                    arrayOfObjects: [{ x: 1 }, { y: 2 }],
+                },
+            ];
+            const envelope = await makeCompressedEnvelope(primitiveItems);
+            const record = makeSqsRecord({ messageBody: envelope }, 'msg-primitives');
+            const { items } = await unbundleRecords([record]);
+            expect(items).toHaveLength(3);
+            expect(JSON.stringify(items)).toBe(JSON.stringify(primitiveItems));
+        });
+        it('maintains item order across multiple bundles', async () => {
+            const records = [];
+            let globalIdx = 0;
+            for (let bundleIdx = 0; bundleIdx < 10; bundleIdx++) {
+                const itemCount = 10 + bundleIdx * 5;
+                const items = Array.from({ length: itemCount }, () => ({
+                    globalOrder: globalIdx++,
+                    bundle: bundleIdx,
+                }));
+                const envelope = await makeCompressedEnvelope(items);
+                records.push(makeSqsRecord({ messageBody: envelope }, `order-msg-${bundleIdx}`));
+            }
+            const { items } = await unbundleRecords(records);
+            const bundleGroups = new Map();
+            for (const item of items) {
+                if (!bundleGroups.has(item.bundle)) {
+                    bundleGroups.set(item.bundle, []);
+                }
+                bundleGroups.get(item.bundle)?.push(item.globalOrder);
+            }
+            for (const [, orders] of bundleGroups) {
+                for (let i = 1; i < orders.length; i++) {
+                    expect(orders[i]).toBeGreaterThan(orders[i - 1]);
+                }
+            }
+        });
+        it('handles edge case: single item bundles', async () => {
+            const records = await Promise.all(Array.from({ length: 50 }, async (_, i) => {
+                const items = [{ id: `single-${i}`, value: i }];
+                const envelope = await makeCompressedEnvelope(items);
+                return makeSqsRecord({ messageBody: envelope }, `single-msg-${i}`);
+            }));
+            const { items, stats, recordMap } = await unbundleRecords(records);
+            expect(items).toHaveLength(50);
+            expect(stats.bundledSqsRecords).toBe(50);
+            expect(stats.totalItems).toBe(50);
+            for (let i = 0; i < 50; i++) {
+                const item = items.find((x) => x.value === i);
+                expect(item).toBeDefined();
+                if (!item)
+                    throw new Error(`Expected item with value ${i} to be found`);
+                expect(recordMap.get(item)).toMatch(/single-msg-\d+/);
+            }
+        });
+        it('handles edge case: empty arrays in bundles', async () => {
+            const emptyEnvelope = {
+                v: 1,
+                c: CompressionAlgorithm.NONE,
+                n: 0,
+                p: [],
+            };
+            const record = makeSqsRecord({ messageBody: emptyEnvelope }, 'msg-empty');
+            const { items, stats } = await unbundleRecords([record]);
+            expect(items).toHaveLength(0);
+            expect(stats.bundledSqsRecords).toBe(1);
+            expect(stats.totalItems).toBe(0);
+        });
+    });
+    describe('GZIP comprehensive tests', () => {
+        describe('GZIP pre-decompression bomb protection', () => {
+            it('rejects GZIP with fake ISIZE claiming huge size BEFORE decompression starts', async () => {
+                const gzipHeader = Buffer.from([0x1f, 0x8b, 0x08, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x03]);
+                const emptyDeflate = Buffer.from([0x03, 0x00]);
+                const crc32 = Buffer.from([0x00, 0x00, 0x00, 0x00]);
+                const fakeIsize = Buffer.alloc(4);
+                fakeIsize.writeUInt32LE(100 * 1024 * 1024, 0);
+                const fakeGzip = Buffer.concat([gzipHeader, emptyDeflate, crc32, fakeIsize]);
+                const base64 = fakeGzip.toString('base64');
+                const bombEnvelope = {
+                    v: 1,
+                    c: CompressionAlgorithm.GZIP,
+                    n: 1,
+                    s: 100,
+                    p: base64,
+                };
+                const record = makeSqsRecord({ messageBody: bombEnvelope }, 'msg-gzip-bomb');
+                const { failedMessageIds, stats } = await unbundleRecords([record], {
+                    maxDecompressedSizeBytes: 10 * 1024 * 1024,
+                });
+                expect(failedMessageIds).toContain('msg-gzip-bomb');
+                expect(stats.failedRecords).toBe(1);
+            });
+            it('allows GZIP with ISIZE within limit', async () => {
+                const items = [makeTestEvent('valid-1')];
+                const envelope = await makeGzipCompressedEnvelope(items);
+                const record = makeSqsRecord({ messageBody: envelope }, 'msg-gzip-valid');
+                const { items: result, failedMessageIds } = await unbundleRecords([record], {
+                    maxDecompressedSizeBytes: 10 * 1024 * 1024,
+                });
+                expect(result).toHaveLength(1);
+                expect(failedMessageIds).toHaveLength(0);
+            });
+            it('pre-check catches bomb even when ISIZE is exactly at limit + 1', async () => {
+                const limit = 1000;
+                const gzipHeader = Buffer.from([0x1f, 0x8b, 0x08, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x03]);
+                const emptyDeflate = Buffer.from([0x03, 0x00]);
+                const crc32 = Buffer.from([0x00, 0x00, 0x00, 0x00]);
+                const fakeIsize = Buffer.alloc(4);
+                fakeIsize.writeUInt32LE(limit + 1, 0);
+                const fakeGzip = Buffer.concat([gzipHeader, emptyDeflate, crc32, fakeIsize]);
+                const base64 = fakeGzip.toString('base64');
+                const bombEnvelope = {
+                    v: 1,
+                    c: CompressionAlgorithm.GZIP,
+                    n: 1,
+                    s: 100,
+                    p: base64,
+                };
+                const record = makeSqsRecord({ messageBody: bombEnvelope }, 'msg-boundary-bomb');
+                const { failedMessageIds } = await unbundleRecords([record], {
+                    maxDecompressedSizeBytes: limit,
+                });
+                expect(failedMessageIds).toContain('msg-boundary-bomb');
+            });
+        });
+        describe('empty GZIP bundle', () => {
+            it('unbundles empty GZIP compressed array', async () => {
+                const envelope = await makeGzipCompressedEnvelope([]);
+                const record = makeSqsRecord({ messageBody: envelope }, 'msg-empty-gzip');
+                const { items, stats } = await unbundleRecords([record]);
+                expect(items).toHaveLength(0);
+                expect(stats.bundledSqsRecords).toBe(1);
+                expect(stats.totalItems).toBe(0);
+            });
+        });
+        describe('Unicode characters in GZIP payload', () => {
+            it('preserves emoji through GZIP compression', async () => {
+                const items = [
+                    { eventId: 'emoji-1', content: '🎉🚀💻🌍✨' },
+                    { eventId: 'emoji-2', content: '👋🏽👨‍👩‍👧‍👦🏳️‍🌈' },
+                ];
+                const envelope = await makeGzipCompressedEnvelope(items);
+                const record = makeSqsRecord({ messageBody: envelope });
+                const { items: result } = await unbundleRecords([record]);
+                expect(result).toHaveLength(2);
+                expect(result[0].content).toBe('🎉🚀💻🌍✨');
+                expect(result[1].content).toBe('👋🏽👨‍👩‍👧‍👦🏳️‍🌈');
+            });
+            it('preserves CJK characters through GZIP compression', async () => {
+                const items = [
+                    { eventId: 'cjk-1', content: '中文测试：欢迎使用' },
+                    { eventId: 'cjk-2', content: 'こんにちは世界 ひらがな カタカナ' },
+                    { eventId: 'cjk-3', content: '안녕하세요 세계' },
+                ];
+                const envelope = await makeGzipCompressedEnvelope(items);
+                const record = makeSqsRecord({ messageBody: envelope });
+                const { items: result } = await unbundleRecords([record]);
+                expect(result).toHaveLength(3);
+                expect(result[0].content).toBe('中文测试：欢迎使用');
+                expect(result[1].content).toBe('こんにちは世界 ひらがな カタカナ');
+                expect(result[2].content).toBe('안녕하세요 세계');
+            });
+            it('preserves special characters and mixed scripts through GZIP compression', async () => {
+                const items = [
+                    { eventId: 'special-1', content: '∑∫∂∇ε → ∞ × ∈ ⊆ ∀∃' },
+                    { eventId: 'special-2', content: 'العربية: مرحبا بكم' },
+                    { eventId: 'mixed', content: 'Hello 世界 🌏 مرحبا Привет' },
+                    { eventId: 'combining', content: 'e\u0301 n\u0303 c\u0327' },
+                ];
+                const envelope = await makeGzipCompressedEnvelope(items);
+                const record = makeSqsRecord({ messageBody: envelope });
+                const { items: result } = await unbundleRecords([record]);
+                expect(result).toHaveLength(4);
+                for (let i = 0; i < items.length; i++) {
+                    expect(result[i].content).toBe(items[i].content);
+                    const originalBytes = Buffer.from(items[i].content, 'utf8');
+                    const recoveredBytes = Buffer.from(result[i].content, 'utf8');
+                    expect(recoveredBytes.equals(originalBytes)).toBe(true);
+                }
+            });
+        });
+        describe('GZIP with invalid magic bytes', () => {
+            it('fails gracefully for buffer with wrong magic bytes', async () => {
+                const wrongMagic = Buffer.from([0x00, 0x00, 0x08, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x03]);
+                const filler = Buffer.alloc(10);
+                const invalidGzip = Buffer.concat([wrongMagic, filler]);
+                const base64 = invalidGzip.toString('base64');
+                const badEnvelope = {
+                    v: 1,
+                    c: CompressionAlgorithm.GZIP,
+                    n: 1,
+                    s: 100,
+                    p: base64,
+                };
+                const record = makeSqsRecord({ messageBody: badEnvelope }, 'msg-wrong-magic');
+                const { failedMessageIds } = await unbundleRecords([record]);
+                expect(failedMessageIds).toContain('msg-wrong-magic');
+            });
+            it('fails gracefully for buffer starting with valid magic but corrupted data', async () => {
+                const validMagic = Buffer.from([0x1f, 0x8b]);
+                const garbage = Buffer.from('this is not valid gzip data after magic');
+                const invalidGzip = Buffer.concat([validMagic, garbage]);
+                const base64 = invalidGzip.toString('base64');
+                const badEnvelope = {
+                    v: 1,
+                    c: CompressionAlgorithm.GZIP,
+                    n: 1,
+                    s: 100,
+                    p: base64,
+                };
+                const record = makeSqsRecord({ messageBody: badEnvelope }, 'msg-corrupt-gzip');
+                const { failedMessageIds } = await unbundleRecords([record]);
+                expect(failedMessageIds).toContain('msg-corrupt-gzip');
+            });
+        });
+        describe('GZIP minimum size edge cases', () => {
+            it('handles buffer exactly 18 bytes (minimum valid)', () => {
+                const minBuffer = Buffer.alloc(18);
+                minBuffer[0] = 0x1f;
+                minBuffer[1] = 0x8b;
+                const size = getGzipUncompressedSize(minBuffer);
+                expect(size).toBe(0);
+            });
+            it('returns undefined for buffer exactly 17 bytes (too small)', () => {
+                const tooSmall = Buffer.alloc(17);
+                tooSmall[0] = 0x1f;
+                tooSmall[1] = 0x8b;
+                const size = getGzipUncompressedSize(tooSmall);
+                expect(size).toBeUndefined();
+            });
+            it('fails gracefully for 17-byte GZIP envelope', async () => {
+                const tooSmall = Buffer.alloc(17);
+                tooSmall[0] = 0x1f;
+                tooSmall[1] = 0x8b;
+                const base64 = tooSmall.toString('base64');
+                const badEnvelope = {
+                    v: 1,
+                    c: CompressionAlgorithm.GZIP,
+                    n: 1,
+                    s: 100,
+                    p: base64,
+                };
+                const record = makeSqsRecord({ messageBody: badEnvelope }, 'msg-too-small');
+                const { failedMessageIds } = await unbundleRecords([record]);
+                expect(failedMessageIds).toContain('msg-too-small');
+            });
+        });
+        describe('GZIP timeout protection', () => {
+            it('CompressionTimeoutError has correct properties', () => {
+                const error = new CompressionTimeoutError(CompressionOperation.DECOMPRESS, 100);
+                expect(error).toBeInstanceOf(Error);
+                expect(error.name).toBe('CompressionTimeoutError');
+                expect(error.operation).toBe('decompress');
+                expect(error.timeoutMs).toBe(100);
+                expect(error.message).toContain('timed out after 100ms');
+            });
+            it('GZIP decompression respects timeout option', async () => {
+                const items = [makeTestEvent('timeout-test')];
+                const envelope = await makeGzipCompressedEnvelope(items);
+                const record = makeSqsRecord({ messageBody: envelope });
+                const { items: result, failedMessageIds } = await unbundleRecords([record], {
+                    timeoutMs: 10000,
+                });
+                expect(result).toHaveLength(1);
+                expect(failedMessageIds).toHaveLength(0);
+            });
+        });
+        describe('large GZIP near SQS limit', () => {
+            it('decompresses large GZIP bundle near 256KB compressed', async () => {
+                const items = Array.from({ length: 200 }, (_, i) => ({
+                    eventId: `large-${i}`,
+                    name: 'page_view',
+                    data: `repeated-content-for-compression-${i}-`.repeat(50),
+                    value: i * 1.5,
+                }));
+                const envelope = await makeGzipCompressedEnvelope(items);
+                const compressedSize = Buffer.byteLength(JSON.stringify(envelope.p), 'utf8');
+                console.log(`Large GZIP test: compressed payload ~${Math.round(compressedSize / 1024)}KB`);
+                const record = makeSqsRecord({ messageBody: envelope }, 'msg-large-gzip');
+                const { items: result, failedMessageIds } = await unbundleRecords([record]);
+                expect(failedMessageIds).toHaveLength(0);
+                expect(result).toHaveLength(200);
+                expect(result[0].eventId).toBe('large-0');
+                expect(result[199].eventId).toBe('large-199');
+            });
+            it('handles GZIP with maximum decompressed size exactly at limit', async () => {
+                const items = [{ eventId: 'boundary', data: 'x'.repeat(5000) }];
+                const envelope = await makeGzipCompressedEnvelope(items);
+                const record = makeSqsRecord({ messageBody: envelope });
+                const { items: result, failedMessageIds } = await unbundleRecords([record], {
+                    maxDecompressedSizeBytes: 10 * 1024,
+                });
+                expect(failedMessageIds).toHaveLength(0);
+                expect(result).toHaveLength(1);
+            });
+        });
+    });
+});
+describe('getGzipUncompressedSize', () => {
+    it('returns correct size for valid GZIP', async () => {
+        const originalData = 'Hello, World! This is a test.';
+        const compressed = await gzipAsync(Buffer.from(originalData, 'utf8'));
+        const size = getGzipUncompressedSize(compressed);
+        expect(size).toBe(Buffer.byteLength(originalData, 'utf8'));
+    });
+    it('returns correct size for larger payload', async () => {
+        const originalData = 'x'.repeat(10000);
+        const compressed = await gzipAsync(Buffer.from(originalData, 'utf8'));
+        const size = getGzipUncompressedSize(compressed);
+        expect(size).toBe(10000);
+    });
+    it('returns undefined for buffer too small', () => {
+        const tooSmall = Buffer.alloc(17);
+        tooSmall[0] = 0x1f;
+        tooSmall[1] = 0x8b;
+        expect(getGzipUncompressedSize(tooSmall)).toBeUndefined();
+    });
+    it('returns undefined for wrong magic bytes', () => {
+        const wrongMagic = Buffer.alloc(20);
+        wrongMagic[0] = 0x00;
+        wrongMagic[1] = 0x00;
+        expect(getGzipUncompressedSize(wrongMagic)).toBeUndefined();
+    });
+    it('returns undefined for empty buffer', () => {
+        expect(getGzipUncompressedSize(Buffer.alloc(0))).toBeUndefined();
+    });
+    it('returns undefined for single byte buffer', () => {
+        expect(getGzipUncompressedSize(Buffer.from([0x1f]))).toBeUndefined();
+    });
+    it('returns undefined for buffer with only magic bytes', () => {
+        expect(getGzipUncompressedSize(Buffer.from([0x1f, 0x8b]))).toBeUndefined();
+    });
+    it('returns 0 for GZIP with ISIZE = 0', () => {
+        const buffer = Buffer.alloc(18);
+        buffer[0] = 0x1f;
+        buffer[1] = 0x8b;
+        const size = getGzipUncompressedSize(buffer);
+        expect(size).toBe(0);
+    });
+    it('reads ISIZE correctly as little-endian', () => {
+        const buffer = Buffer.alloc(18);
+        buffer[0] = 0x1f;
+        buffer[1] = 0x8b;
+        buffer.writeUInt32LE(0x12345678, 14);
+        const size = getGzipUncompressedSize(buffer);
+        expect(size).toBe(0x12345678);
+    });
+    it('handles maximum 32-bit ISIZE value', () => {
+        const buffer = Buffer.alloc(18);
+        buffer[0] = 0x1f;
+        buffer[1] = 0x8b;
+        buffer.writeUInt32LE(0xffffffff, 14);
+        const size = getGzipUncompressedSize(buffer);
+        expect(size).toBe(0xffffffff);
+    });
+    it('correctly extracts size from real GZIP data', async () => {
+        const testSizes = [1, 10, 100, 1000, 50000];
+        for (const testSize of testSizes) {
+            const originalData = 'a'.repeat(testSize);
+            const compressed = await gzipAsync(Buffer.from(originalData, 'utf8'));
+            const size = getGzipUncompressedSize(compressed);
+            expect(size).toBe(testSize);
+        }
+    });
+    it('handles JSON array compression correctly', async () => {
+        const items = [{ id: 1 }, { id: 2 }, { id: 3 }];
+        const json = JSON.stringify(items);
+        const compressed = await gzipAsync(Buffer.from(json, 'utf8'));
+        const size = getGzipUncompressedSize(compressed);
+        expect(size).toBe(Buffer.byteLength(json, 'utf8'));
+    });
+});
 //# sourceMappingURL=sqs-unbundle.spec.js.map