# 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

- [x] Create directory `universal/compression/bitpacker/` with `src/`, `tests/`, `src/__benchmarks__/`, and all feature subdirectories per the layout in `proposal.md`.
- [x] 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`.
- [x] Write `tsconfig.json` extending `@suaveplan/typescript-config/library.json`.
- [x] Write `vitest.config.ts` using `createTestConfig()` from `@suaveplan/testing/config`.
- [x] Add `lint`, `typecheck`, `test`, `test:coverage`, `build`, `docs:check` scripts.

---

## 2. Types + errors

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

---

## 3. BitWriter

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

---

## 4. BitReader

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

---

## 5. BitSchema

- [x] 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`.
- [x] Write `bit-schema.test.ts` and `bit-schema.md`.

---

## 6. Pack utilities

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

---

## 7. Benchmarks

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

---

## 8. Tests

- [x] Write `tests/integration.test.ts` — BitWriter → BitReader full round-trip including schema.
- [x] 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

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