suaveplan/openspec/archive/2026-05-03-bitpacker-full-port-superseded/tasks.md

Tasks — bitpacker full port

STATUS (2026-05-03 triage): This change has been superseded by the modular bitpacker family delivered across multiple smaller changes: enterprise-bitpacker, bitpacker-modular-restructure, bitpacker-stub-completion, bitpacker-canonical-spec, bitpacker-crypto-port, bitpacker-crypto-rewrite (all archived 2026-04-24 → 2026-05-02).

The remaining genuine hardening items (Zod-everywhere, schema-registry integration, OTel across core, fast-check property tests, mitata benchmarks, feature-flags integration) are carved into the focused bitpacker-hardening change folder. This folder is retained for archival traceability and is not active work.

See proposal.md "Triage outcome" section for the full mapping.

Phase 0 — Audit & Planning

• Inventory all 400 suaveplan bitpacker source files by directory — done as part of Phases 3a-3e modular ports; genesis family is 10 packages, ~232 .ts files
• Identify which genesis additions (zigzag, peek/seek, align) must be preserved — preserved through every port
• Map suaveplan package.json exports to genesis target structure — every package has explicit exports map
• Verify all required workspace deps exist in genesis (@suaveplan/schema-registry, @suaveplan/opentelemetry, @suaveplan/feature-flags, fast-check, mitata) — schema-registry / opentelemetry / feature-flags exist but are unused by bitpacker; fast-check and mitata not installed (deferred to bitpacker-hardening)

Phase 1 — Core Schema System Port

• Port src/core/ — BitPacker, BitOperations, PackingStrategyManager, packing context
• Port src/packers/ — all built-in packing strategies (blob, string, array, object, enum, datetime, varint, map, set, bitarray, etc.)
• Port src/schema/ — schema parsing, validation, token registry
• Port src/types/ — type definitions, schema shapes
• Port src/handlers/ — strategy dispatch and handler registry
• Port src/utils/ — utility functions (keep genesis zigzag, pack-bits where they don't conflict)
• Port src/validation/ — safety limits, schema validation
• Port src/iterators/ — streaming/iterative pack/unpack
• Port src/streaming/ — chunked streaming APIs (delivered as @suaveplan/bitpacker-streaming, Phase 3d)
• Port src/compressed/ — compression pipeline (delivered as @suaveplan/bitpacker-compressed, Phase 3c)
• Port src/crypto/ — checksum helpers (delivered as @suaveplan/bitpacker-crypto)
• Port src/network/ — network simulation helpers (delivered as @suaveplan/bitpacker-network, Phase 3b)
• Port src/game/ — game state schemas, delta encoding (delivered as @suaveplan/bitpacker-game + @suaveplan/bitpacker-delta, Phase 3a)
• Port src/serialization/ — serialize/deserialize helpers
• Rewrite src/index.ts with explicit named re-exports grouped by subpath
• Expand package.json exports map to match every public subpath

Phase 2 — Schema Flexibility (Tier 1–3)

• Register 6 missing packer tokens in registerDefaultStrategies (genesis equivalent of createPackingStrategyManager)
• Wire CustomTypeRegistry + _customType into new BitPacker(schema)
• Add _optional / ? suffix support
• Add _union for discriminated unions
• Add _tuple for heterogeneous fixed arrays (via ArraySchemaPackingStrategy on plain arrays)
• Add _def / $ref for shared sub-schemas (_ref + _defs strategies exist)
• Add _version + forward-compat rules — VersionPackingStrategy exists and enforces version match; "forward-compat" semantics (tolerating newer/older versions) is a feature decision deferred to bitpacker-hardening
• Add _if / _when for conditional presence (JSON-only predicates)
• Add regression test asserting schemas stay pure JSON (round-trip through JSON.stringify/JSON.parse)

Phase 3 — Enterprise Hardening

• Replace all catch (error: any) with unknown + typed narrowing — banned-pattern scan over src/ returns 0
• Introduce Zod schemas for every public type — partial (bitpacker-crypto, bitpacker-delta, bitpacker-schema have them; core does not). Carved to bitpacker-hardening.
• Register Zod schemas with @suaveplan/schema-registry — zero usage today. Carved to bitpacker-hardening.
• Define structured error hierarchy (BITPACKER.* codes) via @suaveplan/error — BitpackerError extends SuaveplanError<BitpackerErrorCode> with defineCodes("BITPACKER", [...]) registry covering 30+ codes
• Wire OTel instrumentation (counters, histograms, spans) — only bitpacker-crypto has spans today. Carved to bitpacker-hardening.
• Add injectable Clock and Rng — done in bitpacker-network, bitpacker-streaming, bitpacker-schema; each has defaults/default-clock.ts allow-listed module-scope Date.now()
• Add AbortSignal support to iterative APIs — done in bitpacker-streaming (every *Stream method) and bitpacker-crypto async paths
• Add fast-check property tests (round-trip, delta idempotency, checksum distribution) — zero. fast-check not installed. Carved to bitpacker-hardening.
• Add mitata benchmark suite with baselines — zero. mitata not installed. Carved to bitpacker-hardening.
• Add CI benchmark regression gate — N/A until benchmarks exist. Carved to bitpacker-hardening.
• Integrate @suaveplan/feature-flags for risky primitives — zero usage. Carved to bitpacker-hardening (decision pending — may be unnecessary).
• Raise coverage to ≥ 95% — exceeded: 100/100/100/100 across bitpacker, bitpacker-strategies, bitpacker-validation, bitpacker-game, and every Phase-3 module
• Ensure every exported symbol has a co-located .md — 47 sources without sibling .md (bulk: bitpacker 30, bitpacker-validation 9, bitpacker-game 7, bitpacker-crypto 1). Tracked separately as a documentation pass; not blocking.

Phase 4 — Verification

• bunx turbo lint typecheck test --filter=@suaveplan/bitpacker
• bunx turbo test:coverage --filter=@suaveplan/bitpacker — 100/100/100/100
• bunx turbo test --filter=...@suaveplan/bitpacker (dependent sweep) — 69/69 tasks succeed
• Banned-pattern scan (zero output) — clean over src/
• Missing .md scan (zero output) — 47 missing; documentation pass tracked separately
• Tree-shake test on rewritten index.ts — "sideEffects": false set on all 10 packages; explicit assertion test deferred (low value given the Vite build already verifies tree-shaking via dts-only outputs)

Acceptance

• All suaveplan bitpacker tests pass on genesis (or equivalent coverage) — equivalent: 100/100/100/100 across the family
• Downstream consumers (packer, network-*, storage-*) compile and test green — ...@suaveplan/bitpacker sweep: 69/69 successful
• No any, TODO, FIXME, ts-ignore, ts-expect-error in src/ — banned-pattern scan returns 0 over the bitpacker family