suaveplan/openspec/archive/2026-05-02-bitpacker-modular-restructure/tasks.md

1. Workspace Setup

• 1.1 Create packages/bitpacker/ parent directory
• 1.2 Verify workspace glob packages/*/* picks up nested packages under packages/bitpacker/
• 1.3 Create base tsconfig.json template for bitpacker plugins

2. Core Package — @suaveplan/bitpacker

• 2.1 Create packages/bitpacker/bitpacker/ directory with package.json, tsconfig.lib.json, README.md
• 2.2 Port BitWriter from genesis packages/primitives/bitpacker/src/bit-writer/
• 2.3 Port BitReader from genesis packages/primitives/bitpacker/src/bit-reader/
• 2.4 Port PackingStrategyManager from suaveplan src/core/strategies/manager/
• 2.5 Port PackingContext and PackingStrategy types from suaveplan src/core/strategies/types.ts
• 2.6 Port BitPacker class from suaveplan src/core/bitpacker.ts
• 2.7 Port base types from suaveplan src/types.ts and src/types/base-types.ts
• 2.8 Preserve genesis additions: zigzag.ts, pack-bits.ts, peek/seek, align()
• 2.9 Port InvalidSchemaStrategy as catch-all in core
• 2.10 Write src/index.ts with explicit named re-exports
• 2.11 Write core tests (round-trip for primitive schemas, strategy manager, custom strategy registration)
• 2.12 Verify bunx turbo typecheck test --filter=@suaveplan/bitpacker passes

3. Strategies Plugin — @suaveplan/bitpacker-strategies

• 3.1 Create packages/bitpacker/strategies/ directory with package metadata
• 3.2 Port NumberPackingStrategy (integer + fixed-point) from suaveplan
• 3.3 Port StringPackingStrategy (fixed/variable strings, UUID, float formats) from suaveplan
• 3.4 Port BooleanPackingStrategy from suaveplan
• 3.5 Port NullPackingStrategy from suaveplan
• 3.6 Port BigIntPackingStrategy from suaveplan
• 3.7 Port ObjectPackingStrategy from suaveplan
• 3.8 Port ArrayPackingStrategy (tuple + dynamic arrays) from suaveplan
• 3.9 Port EnumPackingStrategy from suaveplan
• 3.10 Port OptionalPackingStrategy from suaveplan
• 3.11 Port OneOfPackingStrategy from suaveplan
• 3.12 Port ConditionalPackingStrategy from suaveplan
• 3.13 Port VersionPackingStrategy from suaveplan
• 3.14 Port DateTimePackingStrategy from suaveplan
• 3.15 Port VarIntPackingStrategy from suaveplan
• 3.16 Port MapPackingStrategy from suaveplan
• 3.17 Port SetPackingStrategy from suaveplan
• 3.18 Port BitArrayPackingStrategy from suaveplan
• 3.19 Port BlobPackingStrategy from suaveplan
• 3.20 Port BitsetPackingStrategy from suaveplan
• 3.21 Port DefsPackingStrategy (shared sub-schemas) from suaveplan
• 3.22 Port CustomTypePackingStrategy from suaveplan
• 3.23 Export registerDefaultStrategies(manager) function
• 3.24 Write strategy tests covering all schema tokens
• 3.25 Verify typecheck and tests pass

4. Schema Plugin — @suaveplan/bitpacker-schema

• 4.1 Create packages/bitpacker/bitpacker-schema/ directory with package metadata
• 4.2 Port SchemaRegistry from suaveplan src/schema/registry/ — resolved by archived change bitpacker-stub-completion (full storage-backed SchemaRegistry, in-memory + localStorage storage adapters, and factory helpers all ported).
• 4.3 Port schema matching from suaveplan src/schema/matching/ — verified ported as bitpacker-schema/matching/matching.ts (165L → 173L). Earlier "deferred" note was stale.
• 4.4 Port schema versioning from suaveplan src/schema/versioning/ — verified ported as bitpacker-schema/versioning/versioning.ts (435L → 365L). Earlier "deferred" note was stale.
• 4.5 Port schema visualization from suaveplan src/schema/visualization/ — verified ported as bitpacker-schema/visualization/visualization.ts (893L → 847L). Earlier "deferred" note was stale.
• 4.6 Port validateData and validation report from suaveplan src/validation/
• 4.7 Write schema tests
• 4.8 Verify typecheck and tests pass

Also ported (not originally listed): bitpacker-schema/migration/migration.ts (521L → 479L). Track in parity table only.

5. Streaming Plugin — @suaveplan/bitpacker-streaming

• 5.1 Create packages/bitpacker/bitpacker-streaming/ directory with package metadata
• 5.2 Port StreamingPacker from suaveplan src/streaming/ — resolved by archived change bitpacker-stub-completion (full StreamingBitPacker class with packStream/unpackStream, AbortSignal support, progress events, chunk processors).
• 5.3 Port transform streams from suaveplan src/streaming/transform/ — partial: 544L → 365L (~67%); core BitPackerTransformer and framing utilities present
• 5.4 Add AbortSignal support to all iterative APIs — verified in unpackFromChunksAsync
• 5.5 Write streaming tests
• 5.6 Verify typecheck and tests pass

6. Delta Plugin — @suaveplan/bitpacker-delta

• 6.1 Create packages/bitpacker/bitpacker-delta/ directory with package metadata
• 6.2 Port DeltaManager from suaveplan src/core/delta/ — resolved by archived change bitpacker-stub-completion (full DeltaManager + DeltaStateManager ported, injectable Clock, structural equality replacing JSON.stringify).
• 6.3 Port XOR encoder from suaveplan src/core/delta/xor-encoder.ts — partial: 177L → 60L (~34%)
• 6.4 Port string diff from suaveplan src/core/delta/string-diff.ts — partial: 226L → 113L (~50%)
• 6.5 Port number XOR from suaveplan src/core/delta/number-xor.ts — partial: 232L upstream number-xor.ts collapsed into a numberXor export inside xor-encoder.ts; richer surface lost
• 6.6 Write delta tests
• 6.7 Verify typecheck and tests pass

7. Game Plugin — @suaveplan/bitpacker-game

• 7.1 Create packages/bitpacker/bitpacker-game/ directory with package metadata
• 7.2 Port game bitpacker enhancements from suaveplan src/game/bitpacker/ — verified ported as bitpacker-game/bitpacker/bitpacker.ts (388L → 384L). Earlier "deferred" note was stale.
• 7.3 Port quantization from suaveplan src/game/quantization/
• 7.4 Port prediction from suaveplan src/game/prediction/ — all 5 files ported (kalman-filter, motion-math, position-predictor, prediction-algorithms, rotation-predictor + entry); 827L → 700L (~85%)
• 7.5 Port interpolation from suaveplan src/game/interpolation/ — partial: 745L → 447L (~60%); significant surface trim — flag for follow-up parity check
• 7.6 Port reconciliation from suaveplan src/game/reconciliation/ — partial: 615L → 478L (~78%)
• 7.7 Port state manager from suaveplan src/game/state-manager/
• 7.8 Port schema factory from suaveplan src/game/schema-factory/ — verified ported as bitpacker-game/schema-factory/schema-factory.ts (50L → 50L). Earlier "deferred" note was stale.
• 7.9 Write game tests
• 7.10 Verify typecheck and tests pass

8. Network Plugin — @suaveplan/bitpacker-network

• 8.1 Create packages/bitpacker/bitpacker-network/ directory with package metadata
• 8.2 Port network simulation from suaveplan src/network/ — resolved by archived change bitpacker-stub-completion (full NetworkSimulator ported into bitpacker-network/, injectable Rng+Clock, all module-scope randomness eliminated, deprecated shim left in bitpacker-game).
• 8.3 Write network tests
• 8.4 Verify typecheck and tests pass

9. Crypto Plugin — @suaveplan/bitpacker-crypto

• 9.1 Create packages/bitpacker/bitpacker-crypto/ directory with package metadata
• 9.2 Port checksum helpers (CRC32, Adler32) from suaveplan src/core/checksum/ — functional: crc32/adler32/appendCrc32/verifyAndStripCrc32 landed inlined into 80L bitpacker-crypto/index.ts. Old separated crc32.ts (176L) + adler32.ts (121L) — Adler32 lacks appendAdler32/verifyAdler32 wrappers; logged as polish gap in parity table
• 9.3 Port xxHash32 from suaveplan src/core/checksum/xxhash32.ts — verified ported as bitpacker-crypto/xxhash32.ts. Earlier "deferred" note was stale.
• 9.4 Port crypto adapters from suaveplan src/crypto/adapters/ — resolved 2026-05-02 by archived change bitpacker-crypto-port (and superseded surface preserved in restore-crypto-keychain-packer). Decision recorded in packages/bitpacker/bitpacker-crypto/SUPERSEDED.md.
• 9.5 Port crypto provider and registry from suaveplan src/crypto/provider/ and src/crypto/registry/ — resolved 2026-05-02 by archived change bitpacker-crypto-port (and superseded surface preserved in restore-crypto-keychain-packer). Decision recorded in packages/bitpacker/bitpacker-crypto/SUPERSEDED.md.
• 9.6 Write crypto tests
• 9.7 Verify typecheck and tests pass

10. Compressed Plugin — @suaveplan/bitpacker-compressed

• 10.1 Create packages/bitpacker/bitpacker-compressed/ directory with package metadata
• 10.2 Port compression pipeline from suaveplan src/compressed/ — resolved by archived change bitpacker-stub-completion (full CompressedBitPacker + CompressionRegistry + Gzip/Deflate/None adapters ported).
• 10.3 Write compressed tests — cover the placeholder RLE only
• 10.4 Verify typecheck and tests pass

11. Validation Plugin — @suaveplan/bitpacker-validation

• 11.1 Create packages/bitpacker/bitpacker-validation/ directory with package metadata
• 11.2 Port safety checks from suaveplan src/core/safety/
• 11.3 Port validation utilities from suaveplan src/validation/
• 11.4 Write validation tests
• 11.5 Verify typecheck and tests pass

12. Legacy Shim & Migration

• 12.1 Move old packages/primitives/bitpacker/ out of repo to /home/ubuntu/web/genesis-bitpacker-old
• 12.2 New core @suaveplan/bitpacker replaces old package; downstream consumers compile green
• 12.3 Downstream crypto package compiles and tests green
• 12.4 Downstream network-plugin-protocol compiles green
• 12.5 Downstream network-plugin-registry compiles green

13. Final Verification

• 13.1 Typecheck passes for all 10 bitpacker packages
• 13.2 All tests pass: 105 tests across 10 test files (coverage of placeholder/stub modules — see §14)
• 13.3 All source .ts files have sibling .md documentation
• 13.4 All 10 packages have README.md
• 13.5 Downstream consumers (crypto, network-plugin-protocol, network-plugin-registry) compile green

14. Outstanding work surfaced by 2026-05-02 audit

These items were originally ticked but the audit found the underlying work was a stub or had been ported into the wrong package. They are re-opened here so a follow-up change can close them; the parity checklist in proposal.md is the canonical source of truth.

• 14.1 Replace 35L inline DeltaManager in bitpacker-delta/index.ts with the full 269L delta-manager.ts + 149L delta-state.ts (drop Date.now() / JSON.stringify; use injectable Clock per CLAUDE.md determinism rule) — resolved by archived change bitpacker-stub-completion
• 14.2 Move 622L network-simulation.ts from bitpacker-game/src/network/ into bitpacker-network/, delete the 48L stub, drop module-scope Math.random() in favour of injectable Rng — resolved by archived change bitpacker-stub-completion
• 14.3 Port full CompressedBitPacker class (663L) into bitpacker-compressed; replace placeholder RLE — resolved by archived change bitpacker-stub-completion
• 14.4 Port full StreamingPacker class (406L) into bitpacker-streaming — resolved by archived change bitpacker-stub-completion
• 14.5 Port SchemaRegistry storage adapters (InMemorySchemaRegistryStorage, LocalStorageSchemaRegistryStorage) and factory helpers (createInMemorySchemaRegistry, createLocalStorageSchemaRegistry) into bitpacker-schema — resolved by archived change bitpacker-stub-completion
• 14.6 Port crypto subsystem Resolved 2026-05-02 in two parallel changes: (a) restore-crypto-keychain-packer — new opinionated @suaveplan/crypto layer with Packer / Unpacker / Authority / AuditLog / RevocationList / Keychain / Vault consolidating the 8+ inline sign-then-pack / encrypt-pack / Merkle-log patterns. (b) bitpacker-crypto-rewrite (slim) — auxiliary bit-packer-side SchemaFingerprint + HashAlgorithmRegistry primitives that don't overlap (a). Upstream's 1906L provider abstraction stays unported (no consumers). Decision recorded in packages/bitpacker/bitpacker-crypto/SUPERSEDED.md. Predecessor proposals (bitpacker-crypto-port deprecate-and-route; bitpacker-crypto-rewrite first-draft seven-primitive design) are preserved as decision-history.
• 14.7 Restore appendAdler32/verifyAdler32 wrappers in bitpacker-crypto to mirror the CRC32 helper API — added appendAdler32 + verifyAndStripAdler32 in packages/bitpacker/bitpacker-crypto/src/crc32.ts, re-exported from package root, covered by tests; mirrors the CRC32 wrapper API
• 14.8 Audit ⚠️-marked partials in parity checklist (xor-encoder 34%, string-diff 50%, interpolation 60%, transform 67%) — confirm each lost surface is intentional or restore — audit confirmed all four trims are intentional (see proposal.md parity table); the trimmed surface is duplicated by @suaveplan/diff (string diff), @suaveplan/bitpacker core (xor primitives folded into xor-encoder.ts), and existing transform helpers; no functional regression to consumers (drive, network, packer all green).