`@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:

Zod schemas for every public type (partial today — only bitpacker-crypto, -delta, -schema)
Register Zod with @suaveplan/schema-registry (zero usage today)
OTel instrumentation across the core (only bitpacker-crypto has spans today)
fast-check property tests (zero, dependency not installed)
mitata benchmark suite + CI regression gate (zero, dependency not installed)
@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.

6.2 KiB Raw Blame History Unescape Escape

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