suaveplan/openspec/archive/2026-04-24-enterprise-bitpacker/tasks.md

Tasks: enterprise-bitpacker

Change ID: enterprise-bitpacker Package: @suaveplan/bitpacker Target path: universal/compression/bitpacker Prerequisite packages on Verdaccio: @suaveplan/error, @suaveplan/types

---

1. Scaffold

• Create directory universal/compression/bitpacker/ with src/, tests/, src/__benchmarks__/, and all feature subdirectories per the layout in proposal.md.
• Write package.json at version 0.1.0 with "type": "module", "sideEffects": false, full exports map, deps: @suaveplan/error workspace:^, @suaveplan/types workspace:^, zod catalog:forms, @opentelemetry/api catalog:observability.
• Write tsconfig.json extending @suaveplan/typescript-config/library.json.
• Write vitest.config.ts using createTestConfig() from @suaveplan/testing/config.
• Add lint, typecheck, test, test:coverage, build, docs:check scripts.

---

2. Types + errors

• Write src/types/common.ts — FieldType, FieldDef, BitSchema interface.
• Write src/types/common.md.
• Write src/error-codes.ts — BitpackerErrorCode, BITPACKER_ERROR_METADATA, registerBitpackerErrorCodes().
• Write Zod schema: FieldDefSchema.

---

3. BitWriter

• Implement BitWriter — dynamic Uint8Array buffer (double-capacity growth), bit-cursor tracking, writeUint, writeInt (two's complement), writeBool, writeFixed, writeBytes, align, toUint8Array, bitLength, byteLength.
• Throws BitpackerError(BITPACKER_INVALID_BIT_WIDTH) for bits ≤ 0 or bits > 53.
• Throws BitpackerError(BITPACKER_VALUE_OUT_OF_RANGE) for out-of-range values.
• Write bit-writer.test.ts (≤500 lines): each method, boundary values, growth, align padding.
• Write bit-writer.md.

---

4. BitReader

• Implement BitReader — reads from frozen Uint8Array, readUint, readInt, readBool, readFixed, readBytes, align, bitPosition, bitsRemaining, peek, seek.
• Throws BitpackerError(BITPACKER_UNDERFLOW) when reading past end.
• Throws BitpackerError(BITPACKER_INVALID_BIT_WIDTH) for bits ≤ 0 or bits > 53.
• Write bit-reader.test.ts (≤500 lines): each method, underflow, seek/peek.
• Write bit-reader.md.

---

5. BitSchema

• Implement defineBitSchema<T>(fields): BitSchema<T> — validates field definitions via Zod, computes byteSize for fixed-width schemas, exposes typed pack(values): Uint8Array and unpack(data): T.
• Write bit-schema.test.ts and bit-schema.md.

---

6. Pack utilities

• Implement packBits, unpackBits, countBits, zigzagEncode, zigzagDecode in utils/pack-bits.ts and utils/zigzag.ts.
• Wire OTel counters on packBits / unpackBits.
• Write pack-bits.test.ts, pack-bits.md, zigzag.test.ts, zigzag.md.

---

7. Benchmarks

• Write src/__benchmarks__/bitpacker.bench.ts — pack 1000 × 7-bit uints, schema pack/unpack 100-field struct, packBits 10000 values.

---

8. Tests

• Write tests/integration.test.ts — BitWriter → BitReader full round-trip including schema.
• Write tests/property.test.ts (fast-check) — pack/unpack round-trip for arbitrary bit widths and values in range, zigzagEncode(zigzagDecode(n)) === n.

---

9. Docs + verify + publish

• All co-located .md files (≥200 words each).
• Write README.md at package root.
• bunx turbo lint typecheck test --filter=@suaveplan/bitpacker — green.
• bunx turbo test:coverage --filter=@suaveplan/bitpacker — 100%.
• bun scripts/publish.ts --package @suaveplan/bitpacker.
• Archive to openspec/archive/2026-04-24-enterprise-bitpacker/.