suaveplan/openspec/archive/2026-05-02-bitpacker-stub-completion/tasks.md

Tasks — Bitpacker stub completion

Every checkbox MUST reflect work actually done in this change. Do not retroactively tick. The five gaps closed here were prematurely ticked in bitpacker-modular-restructure/tasks.md; that's the failure mode this checklist guards against.

1. Spec authoring

• 1.1 Re-read bitpacker-modular-restructure/proposal.md parity table (the "last verified 2026-05-02" version) so the gap definitions stay aligned
• 1.2 Read openspec/AGENTS.md Sections 13 (spec-conformance audit) and 14 (source mapping for migrations)
• 1.3 Draft proposal.md covering all five caps, each with explicit ADDED/MODIFIED/REMOVED lists
• 1.4 Fill ## Source mapping in proposal.md with upstream line ranges; every "no source line" requirement justified
• 1.5 Draft spec deltas under specs/<cap>/spec.md for bitpacker-delta, bitpacker-network, bitpacker-compressed, bitpacker-streaming, bitpacker-schema
• 1.6 Every requirement in every spec delta carries a **Verified by:** line naming concrete it(...) titles
• 1.7 openspec change validate bitpacker-stub-completion exits with no errors

2. @suaveplan/bitpacker-delta

• 2.1 Port DeltaStateManager from upstream src/core/delta/delta-state.ts into packages/bitpacker/bitpacker-delta/src/delta-state/delta-state.ts (new module dir)
• 2.2 Port DeltaManager + FieldChange from upstream src/core/delta/delta-manager.ts into packages/bitpacker/bitpacker-delta/src/delta-manager/delta-manager.ts
• 2.3 Replace Date.now() with an injectable Clock from @suaveplan/types; default to Clock.system()
• 2.4 Replace JSON.stringify-based equality with a structural walker that respects BitPackerSchema field order; keep JSON.stringify only behind an opt-in equalityMode: "json" flag for parity with upstream
• 2.5 Define DeltaConfig Zod schema; reject unknown modes with BitpackerError code BITPACKER.DELTA_INVALID_CONFIG
• 2.6 Add BITPACKER.DELTA_* codes to packages/bitpacker/bitpacker/src/error-codes.ts (DELTA_INVALID_CONFIG, DELTA_STATE_NOT_FOUND, DELTA_FIELD_LIMIT_EXCEEDED)
• 2.7 Delete the 35 L inline DeltaManager from bitpacker-delta/src/index.ts; re-export the new class from there
• 2.8 Sibling .md per implementation file, ≥200 words, basic + advanced examples

3. @suaveplan/bitpacker-network

• 3.1 Move upstream src/network/network-simulation.ts and accompanying type companions into packages/bitpacker/bitpacker-network/src/simulator/
• 3.2 Replace every Math.random() call with an injectable Rng from @suaveplan/types; default to Rng.crypto() (uses crypto.getRandomValues)
• 3.3 Replace every Date.now() call with an injectable Clock
• 3.4 Re-host NETWORK_CONDITIONS, PacketStatus, PacketInfo, NetworkSimulationOptions, NetworkSimulationStats next to the simulator
• 3.5 Port createNetworkSimulator(options) factory verbatim
• 3.6 Add BITPACKER.NETWORK_* codes (NETWORK_BANDWIDTH_EXCEEDED, NETWORK_DISCONNECTED, NETWORK_STAT_OVERFLOW)
• 3.7 Delete the 48 L stub at bitpacker-network/src/index.ts; replace with explicit re-exports of the new class, factory, presets, and existing simulateLatency / shouldDropPacket / applyNetworkConditions helpers (now backed by the simulator)
• 3.8 Delete packages/bitpacker/bitpacker-game/src/network/network-simulation.ts (and its sibling .md / tests)
• 3.9 Add a bitpacker-game/src/network/index.ts shim that re-exports from @suaveplan/bitpacker-network; mark @deprecated with a one-release removal note
• 3.10 Sibling .md per implementation file, ≥200 words, basic + advanced examples

4. @suaveplan/bitpacker-compressed

• 4.1 Port CompressedBitPacker<T> from upstream src/compressed/bitpacker.ts into packages/bitpacker/bitpacker-compressed/src/compressed-bit-packer/compressed-bit-packer.ts
• 4.2 Port CompressionRegistry, CompressionAdapter, compressData, decompressData, NoCompressionAdapter, GzipCompressionAdapter, DeflateCompressionAdapter from upstream src/compressed/compression.ts into packages/bitpacker/bitpacker-compressed/src/compression-registry/
• 4.3 Move existing compressRle / decompressRle into packages/bitpacker/bitpacker-compressed/src/rle/rle.ts; re-export from ./rle AND from root for one release
• 4.4 Add BITPACKER.COMPRESSION_* codes (COMPRESSION_FAILED, DECOMPRESSION_FAILED, UNKNOWN_COMPRESSION_ALGORITHM)
• 4.5 Replace the "placeholder" disclaimer in bitpacker-compressed/README.md with accurate copy
• 4.6 Sibling .md per implementation file

5. @suaveplan/bitpacker-streaming

• 5.1 Port StreamingBitPacker<T> extends EventEmitter from upstream src/streaming/streaming.ts into packages/bitpacker/bitpacker-streaming/src/streaming-bit-packer/streaming-bit-packer.ts
• 5.2 Thread AbortSignal through packStream / unpackStream; abort-on-signal flushes in-flight chunks and rejects with BitpackerError code BITPACKER.STREAM_ABORTED
• 5.3 Refactor existing packToChunks / unpackFromChunks / unpackFromChunksAsync to delegate into StreamingBitPacker; preserve their synchronous-friendly signatures
• 5.4 Add BITPACKER.STREAM_* codes (STREAM_ABORTED, STREAM_VALIDATION_FAILED, STREAM_CHUNK_PROCESSOR_FAILED)
• 5.5 Sibling .md per implementation file

6. @suaveplan/bitpacker-schema

• 6.1 Port SchemaRegistryStorage interface, InMemorySchemaRegistryStorage, LocalStorageSchemaRegistryStorage from upstream src/schema/registry/registry.ts into packages/bitpacker/bitpacker-schema/src/registry/
• 6.2 Port the storage-backed SchemaRegistry (versioned registerSchema / loadSchema / listSchemas / deleteSchema / registerVersionedSchema)
• 6.3 Replace new Date() with an injectable Clock; stamp createdAt / updatedAt from it
• 6.4 Port createInMemorySchemaRegistry / createLocalStorageSchemaRegistry factories
• 6.5 Add BITPACKER.SCHEMA_* codes (SCHEMA_NOT_FOUND, SCHEMA_CONFLICT, SCHEMA_INVALID_METADATA)
• 6.6 Move the existing 50 L Map-based SchemaRegistry to bitpacker-schema/src/legacy/legacy-registry.ts; re-export as LegacySchemaRegistry with @deprecated JSDoc
• 6.7 Sibling .md per implementation file

7. Tests

• 7.1 packages/bitpacker/bitpacker-delta/src/delta-manager/delta-manager.test.ts — round-trip per mode, threshold gate, field-count limit, schema field-order respected
• 7.2 packages/bitpacker/bitpacker-delta/src/delta-state/delta-state.test.ts — LRU eviction, deep-clone isolation, state-key sharding
• 7.3 packages/bitpacker/bitpacker-delta/src/delta-manager/delta-manager.spec-conformance.test.ts — injected Clock deterministic; Zod-rejected configs emit DELTA_INVALID_CONFIG
• 7.4 packages/bitpacker/bitpacker-network/src/simulator/simulator.test.ts — bandwidth limit honoured; jitter within bounds; loss probability hits empirical bucket; duplication / corruption / reordering / burst / disconnect each verifiable; stats counters increment
• 7.5 packages/bitpacker/bitpacker-network/src/simulator/simulator.spec-conformance.test.ts — preset bindings; injected Rng deterministic; injected Clock deterministic; stat-overflow emits NETWORK_STAT_OVERFLOW
• 7.6 packages/bitpacker/bitpacker-compressed/src/compressed-bit-packer/compressed-bit-packer.test.ts — round-trip through none / gzip / deflate; verify decompressed bytes match BitPacker.pack output exactly
• 7.7 packages/bitpacker/bitpacker-compressed/src/compression-registry/compression-registry.spec-conformance.test.ts — adapter registration / replacement; unknown algorithm emits UNKNOWN_COMPRESSION_ALGORITHM
• 7.8 packages/bitpacker/bitpacker-streaming/src/streaming-bit-packer/streaming-bit-packer.test.ts — packStream / unpackStream round-trip; progress events fire in order; chunk events carry the right bytes; abort mid-stream rejects with STREAM_ABORTED
• 7.9 packages/bitpacker/bitpacker-streaming/src/streaming-bit-packer/streaming-bit-packer.spec-conformance.test.ts — chunkProcessor invoked; validateChunks gates emit
• 7.10 packages/bitpacker/bitpacker-schema/src/registry/registry.test.ts — version auto-increment; loadSchema defaults to latest; listSchemas filters by namespace AND tag; deleteSchema per-version vs all-versions
• 7.11 packages/bitpacker/bitpacker-schema/src/registry/registry.spec-conformance.test.ts — both storage adapters pinned to the contract; injected Clock deterministic; missing schema emits SCHEMA_NOT_FOUND
• 7.12 tests/bitpacker-game-network-shim.test.ts — game's network/index.ts re-export resolves to the simulator from @suaveplan/bitpacker-network
• 7.13 Every it(...) in 7.1–7.12 carries { timeout: 5000 } (or 30000 for genuinely-async network simulation runs)

8. Documentation

• 8.1 Sibling .md for every new implementation .ts (≥200 words, basic + advanced examples, full API reference)
• 8.2 Update each affected package's README.md to link the new co-located .mds under ## Modules
• 8.3 Update CLAUDE.md package listings for bitpacker-delta, bitpacker-network, bitpacker-compressed, bitpacker-streaming, bitpacker-schema to reflect the restored surface

9. Pre-archive verification (the 5-gate triple, run for each affected package)

• 9.1 bun run check — Biome 0/0/0 across the monorepo
• 9.2 bunx turbo lint typecheck test --filter=@suaveplan/bitpacker-delta — green
• 9.3 bunx turbo lint typecheck test --filter=@suaveplan/bitpacker-network — green
• 9.4 bunx turbo lint typecheck test --filter=@suaveplan/bitpacker-compressed — green
• 9.5 bunx turbo lint typecheck test --filter=@suaveplan/bitpacker-streaming — green
• 9.6 bunx turbo lint typecheck test --filter=@suaveplan/bitpacker-schema — green
• 9.7 bunx turbo test:coverage --filter=@suaveplan/bitpacker-delta — 100/100/100/100
• 9.8 bunx turbo test:coverage --filter=@suaveplan/bitpacker-network — 100/100/100/100
• 9.9 bunx turbo test:coverage --filter=@suaveplan/bitpacker-compressed — 100/100/100/100
• 9.10 bunx turbo test:coverage --filter=@suaveplan/bitpacker-streaming — 100/100/100/100
• 9.11 bunx turbo test:coverage --filter=@suaveplan/bitpacker-schema — 100/100/100/100
• 9.12 bun scripts/openspec-conformance.ts @suaveplan/bitpacker-delta @suaveplan/bitpacker-network @suaveplan/bitpacker-compressed @suaveplan/bitpacker-streaming @suaveplan/bitpacker-schema — exit 0, no error findings
• 9.13 bunx turbo build --filter=...@suaveplan/bitpacker-* — green for every dependent in the monorepo
• 9.14 bunx turbo build typecheck test --filter=...@suaveplan/bitpacker-* — every downstream consumer compiles green (drive, network, packer, storage)

10. Pre-archive 7-row checklist (AGENTS.md Section 13)

• 10.1 Generics threaded; expectTypeOf assertions on every literal-type claim (especially CompressedBitPacker<T> and StreamingBitPacker<T>)
• 10.2 Zod schemas wired at every declared boundary (DeltaConfig, NetworkSimulationOptions, BitPackerCompressionOptions, StreamingOptions, SchemaMetadata)
• 10.3 Every error code added in §2.6 / 3.6 / 4.4 / 5.4 / 6.5 thrown from at least one production code path; no orphans
• 10.4 Strict-mode behaviors tested both on and off (e.g. validateChunks: true vs false; equalityMode: "json" vs structural)
• 10.5 OTel counters / histograms emitted for bitpacker.delta.changes_detected, bitpacker.network.packet_loss, bitpacker.compress.bytes_in/out, bitpacker.stream.chunk_count, bitpacker.schema.registry_ops; asserted with a real in-memory MeterProvider
• 10.6 Lifecycle dedup tested where claimed: DeltaStateManager LRU eviction stable under concurrent storePreviousState; SchemaRegistry.registerSchema idempotent on identical metadata + schema
• 10.7 No retroactive tick — every box above reflects work done in this change

11. Archive

• 11.1 Fold each spec delta into openspec/specs/<cap>/spec.md (creating any cap files that don't yet exist)
• 11.2 Move openspec/changes/bitpacker-stub-completion/ → openspec/archive/<yyyy-mm-dd>-bitpacker-stub-completion/
• 11.3 In openspec/changes/bitpacker-modular-restructure/tasks.md, tick §14.1, §14.2, §14.3, §14.4, §14.5 with a note pointing at the archived change
• 11.4 Refresh MANIFEST.md (no package set or dep changes expected, but rerun for safety)
• 11.5 Update STATUS.md with the rolled-up gap closure