# `@suaveplan/bitpacker` — Full Port from Suaveplan (v2.0.0)

**Status:** **SUPERSEDED (2026-05-03)** — fold complete via the modular family; remaining hardening carved to `bitpacker-hardening`.
**Target:** `@suaveplan/bitpacker` 0.0.0 → 2.0.0 (full port, replacing the cut-down genesis version)
**Source:** `/home/ubuntu/web/suaveplan/packages/universal/bitpacker/` (400 source files, v1.2.0)

## Triage outcome (2026-05-03)

This proposal was authored when `@suaveplan/bitpacker` was a 20-file stub. The reality on 2026-05-03 is a 10-package family of ~232 `.ts` files at 100/100/100/100 coverage, delivered through six smaller, archived changes:

| Archived change | What it delivered |
|---|---|
| `2026-04-24-enterprise-bitpacker` | Initial enterprise-grade reshape |
| `2026-05-02-bitpacker-modular-restructure` | Split the monolith into the 10-package family |
| `2026-05-02-bitpacker-stub-completion` | Filled the DeltaManager / NetworkSimulator / CompressedBitPacker / StreamingBitPacker stubs |
| `2026-05-02-bitpacker-canonical-spec` | Canonical `openspec/specs/bitpacker/spec.md` (adaptive `"~"` blob, strategy ordering, safety enforcement) |
| `2026-05-02-bitpacker-crypto-port` | First-pass `bitpacker-crypto` |
| `2026-05-02-bitpacker-crypto-rewrite` | Slimmed to non-overlapping primitives (`SchemaFingerprint`, `HashAlgorithmRegistry`) |

**Of the original 51 tasks:** 28 were already checked when this triage began, and a further 17 were verified done by the modular work. **6 are genuinely outstanding** and carved into `bitpacker-hardening`:

1. Zod schemas for every public type (partial today — only `bitpacker-crypto`, `-delta`, `-schema`)
2. Register Zod with `@suaveplan/schema-registry` (zero usage today)
3. OTel instrumentation across the core (only `bitpacker-crypto` has spans today)
4. `fast-check` property tests (zero, dependency not installed)
5. `mitata` benchmark suite + CI regression gate (zero, dependency not installed)
6. `@suaveplan/feature-flags` integration — decision pending (may be unnecessary)

**Plus one tracked-separately:** 47 source files in the bitpacker family lack a sibling `.md` (mostly `bitpacker` core 30, `bitpacker-validation` 9, `bitpacker-game` 7, `bitpacker-crypto` 1). Tracked as a documentation pass, not blocking.

This change folder is retained for archival traceability. **Do not start work here.** Do new work in `bitpacker-hardening`.

---

> Original proposal text below — preserved for traceability. The "What changes" sections are accurate as historical intent; for current state, see per-package CLAUDE.md entries and the canonical spec at `openspec/specs/bitpacker/spec.md`.

## Why

The genesis `bitpacker` at `packages/primitives/bitpacker` is a cut-down greenfield build (~20 source files) providing only low-level `BitWriter`/`BitReader` and a minimal `defineBitSchema`. It is missing the entire schema-driven packing system that makes suaveplan's bitpacker useful:

- **Six schema-reachable packers** (`enum`, `datetime`, `varint`, `map`, `set`, `bitarray`) — missing entirely.
- **Custom type registry** — `_customType` marker has no wiring.
- **Advanced schema primitives** — no optional fields (`?`), unions (`_union`), tuples (`_tuple`), shared sub-schemas (`$ref`), versioning (`_version`), or conditional presence (`_if`/`_when`).
- **Game state schemas** — no delta encoding, no compression pipeline.
- **Network simulation** — no jitter/latency helpers.
- **Streaming packers** — no chunked/iterative encode/decode.
- **Enterprise quality gaps** — no Zod schemas, no structured errors, no OTel, no benchmarks, no property tests.

This violates the directive: "ensure we don't write basic / cut down versions of the original libraries ever again."

---

## What changes

### Phase 1 — Core schema system port
Replace the genesis bitpacker source with the full suaveplan bitpacker source, preserving genesis additions (zigzag encoding, `peek`/`seek`, alignment helpers) where they don't conflict.

### Phase 2 — Schema flexibility (Tier 1–3)
Port the `bitpacker-schema-flexibility` change on top of the core:
- Tier 1: Register `EnumPacker`, `DateTimePacker`, `VarIntPacker`, `MapPacker`, `SetPacker`, `BitArrayPacker` in `createPackingStrategyManager`.
- Tier 2: Wire `CustomTypeRegistry` + `_customType` into the pack/unpack path.
- Tier 3: Add `?`, `_union`, `_tuple`, `_def`/`$ref`, `_version`, `_if`/`_when`.

### Phase 3 — Enterprise hardening
Port the `enterprise-bitpacker` requirements:
- Zod schemas registered with `@suaveplan/schema-registry`.
- Structured error hierarchy (`BITPACKER.*` codes) via `@suaveplan/error`.
- OTel instrumentation via `@suaveplan/opentelemetry`.
- Injectable `Clock` and `Rng` — no module-scope `Math.random()` / `Date.now()`.
- `AbortSignal` on iterative APIs.
- `fast-check` property tests + `mitata` benchmark suite.
- Explicit named re-exports, expanded `package.json` `exports` map.
- Coverage ≥ 95%, docs ≥ 90%.

### Non-goals

- No runtime code generation, `eval`, or schema → JS compilation.
- No replacement of `BitOperations` / standalone-packer APIs (escape hatch stays).
- No general expression language for conditional predicates.

---

## Impact

### Affected dependents

Run `bunx turbo ls --filter=...@suaveplan/bitpacker` to enumerate.

- `@suaveplan/packer` — imports bitpacker for envelope encoding; must be verified after port
- `@suaveplan/network-*` — imports bitpacker for protocol encoding; must be verified after port
- `@suaveplan/storage-*` — imports bitpacker for payload encoding; must be verified after port

### Breaking changes

The genesis `BitWriter`/`BitReader`/`defineBitSchema` API surface is preserved where possible, but:
- `defineBitSchema` return type will change to match suaveplan's richer `BitSchema` interface.
- Error types change from plain `Error` to `BitpackerError extends SuaveplanError`.
- New runtime deps: `@suaveplan/schema-registry`, `@suaveplan/opentelemetry`, `@suaveplan/feature-flags`.

---

## Migration

For consumers of the genesis cut-down API:
- `BitWriter` / `BitReader` — unchanged signatures, but now live under subpath imports.
- `defineBitSchema` — return type gains `pack`/`unpack` methods and metadata; existing call sites compile without change.
- Error handling — catch `BitpackerError` instead of `Error` for programmatic handling.