108 lines
6.2 KiB
Markdown
108 lines
6.2 KiB
Markdown
# `@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.
|