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

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

## 2. `@suaveplan/bitpacker-delta`

- [x] 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)
- [x] 2.2 Port `DeltaManager` + `FieldChange` from upstream `src/core/delta/delta-manager.ts` into `packages/bitpacker/bitpacker-delta/src/delta-manager/delta-manager.ts`
- [x] 2.3 Replace `Date.now()` with an injectable `Clock` from `@suaveplan/types`; default to `Clock.system()`
- [x] 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
- [x] 2.5 Define `DeltaConfig` Zod schema; reject unknown modes with `BitpackerError` code `BITPACKER.DELTA_INVALID_CONFIG`
- [x] 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`)
- [x] 2.7 Delete the 35 L inline `DeltaManager` from `bitpacker-delta/src/index.ts`; re-export the new class from there
- [x] 2.8 Sibling `.md` per implementation file, ≥200 words, basic + advanced examples

## 3. `@suaveplan/bitpacker-network`

- [x] 3.1 Move upstream `src/network/network-simulation.ts` and accompanying type companions into `packages/bitpacker/bitpacker-network/src/simulator/`
- [x] 3.2 Replace every `Math.random()` call with an injectable `Rng` from `@suaveplan/types`; default to `Rng.crypto()` (uses `crypto.getRandomValues`)
- [x] 3.3 Replace every `Date.now()` call with an injectable `Clock`
- [x] 3.4 Re-host `NETWORK_CONDITIONS`, `PacketStatus`, `PacketInfo`, `NetworkSimulationOptions`, `NetworkSimulationStats` next to the simulator
- [x] 3.5 Port `createNetworkSimulator(options)` factory verbatim
- [x] 3.6 Add `BITPACKER.NETWORK_*` codes (`NETWORK_BANDWIDTH_EXCEEDED`, `NETWORK_DISCONNECTED`, `NETWORK_STAT_OVERFLOW`)
- [x] 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)
- [x] 3.8 Delete `packages/bitpacker/bitpacker-game/src/network/network-simulation.ts` (and its sibling `.md` / tests)
- [x] 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
- [x] 3.10 Sibling `.md` per implementation file, ≥200 words, basic + advanced examples

## 4. `@suaveplan/bitpacker-compressed`

- [x] 4.1 Port `CompressedBitPacker<T>` from upstream `src/compressed/bitpacker.ts` into `packages/bitpacker/bitpacker-compressed/src/compressed-bit-packer/compressed-bit-packer.ts`
- [x] 4.2 Port `CompressionRegistry`, `CompressionAdapter`, `compressData`, `decompressData`, `NoCompressionAdapter`, `GzipCompressionAdapter`, `DeflateCompressionAdapter` from upstream `src/compressed/compression.ts` into `packages/bitpacker/bitpacker-compressed/src/compression-registry/`
- [x] 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
- [x] 4.4 Add `BITPACKER.COMPRESSION_*` codes (`COMPRESSION_FAILED`, `DECOMPRESSION_FAILED`, `UNKNOWN_COMPRESSION_ALGORITHM`)
- [x] 4.5 Replace the "placeholder" disclaimer in `bitpacker-compressed/README.md` with accurate copy
- [x] 4.6 Sibling `.md` per implementation file

## 5. `@suaveplan/bitpacker-streaming`

- [x] 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`
- [x] 5.2 Thread `AbortSignal` through `packStream` / `unpackStream`; abort-on-signal flushes in-flight chunks and rejects with `BitpackerError` code `BITPACKER.STREAM_ABORTED`
- [x] 5.3 Refactor existing `packToChunks` / `unpackFromChunks` / `unpackFromChunksAsync` to delegate into `StreamingBitPacker`; preserve their synchronous-friendly signatures
- [x] 5.4 Add `BITPACKER.STREAM_*` codes (`STREAM_ABORTED`, `STREAM_VALIDATION_FAILED`, `STREAM_CHUNK_PROCESSOR_FAILED`)
- [x] 5.5 Sibling `.md` per implementation file

## 6. `@suaveplan/bitpacker-schema`

- [x] 6.1 Port `SchemaRegistryStorage` interface, `InMemorySchemaRegistryStorage`, `LocalStorageSchemaRegistryStorage` from upstream `src/schema/registry/registry.ts` into `packages/bitpacker/bitpacker-schema/src/registry/`
- [x] 6.2 Port the storage-backed `SchemaRegistry` (versioned `registerSchema` / `loadSchema` / `listSchemas` / `deleteSchema` / `registerVersionedSchema`)
- [x] 6.3 Replace `new Date()` with an injectable `Clock`; stamp `createdAt` / `updatedAt` from it
- [x] 6.4 Port `createInMemorySchemaRegistry` / `createLocalStorageSchemaRegistry` factories
- [x] 6.5 Add `BITPACKER.SCHEMA_*` codes (`SCHEMA_NOT_FOUND`, `SCHEMA_CONFLICT`, `SCHEMA_INVALID_METADATA`)
- [x] 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
- [x] 6.7 Sibling `.md` per implementation file

## 7. Tests

- [x] 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
- [x] 7.2 `packages/bitpacker/bitpacker-delta/src/delta-state/delta-state.test.ts` — LRU eviction, deep-clone isolation, state-key sharding
- [x] 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`
- [x] 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
- [x] 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`
- [x] 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
- [x] 7.7 `packages/bitpacker/bitpacker-compressed/src/compression-registry/compression-registry.spec-conformance.test.ts` — adapter registration / replacement; unknown algorithm emits `UNKNOWN_COMPRESSION_ALGORITHM`
- [x] 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`
- [x] 7.9 `packages/bitpacker/bitpacker-streaming/src/streaming-bit-packer/streaming-bit-packer.spec-conformance.test.ts` — `chunkProcessor` invoked; `validateChunks` gates emit
- [x] 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
- [x] 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`
- [x] 7.12 `tests/bitpacker-game-network-shim.test.ts` — game's `network/index.ts` re-export resolves to the simulator from `@suaveplan/bitpacker-network`
- [x] 7.13 Every `it(...)` in 7.1–7.12 carries `{ timeout: 5000 }` (or 30000 for genuinely-async network simulation runs)

## 8. Documentation

- [x] 8.1 Sibling `.md` for every new implementation `.ts` (≥200 words, basic + advanced examples, full API reference)
- [x] 8.2 Update each affected package's `README.md` to link the new co-located `.md`s under `## Modules`
- [x] 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)

- [x] 9.1 `bun run check` — Biome 0/0/0 across the monorepo
- [x] 9.2 `bunx turbo lint typecheck test --filter=@suaveplan/bitpacker-delta` — green
- [x] 9.3 `bunx turbo lint typecheck test --filter=@suaveplan/bitpacker-network` — green
- [x] 9.4 `bunx turbo lint typecheck test --filter=@suaveplan/bitpacker-compressed` — green
- [x] 9.5 `bunx turbo lint typecheck test --filter=@suaveplan/bitpacker-streaming` — green
- [x] 9.6 `bunx turbo lint typecheck test --filter=@suaveplan/bitpacker-schema` — green
- [x] 9.7 `bunx turbo test:coverage --filter=@suaveplan/bitpacker-delta` — 100/100/100/100
- [x] 9.8 `bunx turbo test:coverage --filter=@suaveplan/bitpacker-network` — 100/100/100/100
- [x] 9.9 `bunx turbo test:coverage --filter=@suaveplan/bitpacker-compressed` — 100/100/100/100
- [x] 9.10 `bunx turbo test:coverage --filter=@suaveplan/bitpacker-streaming` — 100/100/100/100
- [x] 9.11 `bunx turbo test:coverage --filter=@suaveplan/bitpacker-schema` — 100/100/100/100
- [x] 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
- [x] 9.13 `bunx turbo build --filter=...@suaveplan/bitpacker-*` — green for every dependent in the monorepo
- [x] 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)

- [x] 10.1 Generics threaded; `expectTypeOf` assertions on every literal-type claim (especially `CompressedBitPacker<T>` and `StreamingBitPacker<T>`)
- [x] 10.2 Zod schemas wired at every declared boundary (`DeltaConfig`, `NetworkSimulationOptions`, `BitPackerCompressionOptions`, `StreamingOptions`, `SchemaMetadata`)
- [x] 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
- [x] 10.4 Strict-mode behaviors tested both on and off (e.g. `validateChunks: true` vs `false`; `equalityMode: "json"` vs structural)
- [x] 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`
- [x] 10.6 Lifecycle dedup tested where claimed: `DeltaStateManager` LRU eviction stable under concurrent `storePreviousState`; `SchemaRegistry.registerSchema` idempotent on identical metadata + schema
- [x] 10.7 No retroactive tick — every box above reflects work done in this change

## 11. Archive

- [x] 11.1 Fold each spec delta into `openspec/specs/<cap>/spec.md` (creating any cap files that don't yet exist)
- [x] 11.2 Move `openspec/changes/bitpacker-stub-completion/` → `openspec/archive/<yyyy-mm-dd>-bitpacker-stub-completion/`
- [x] 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
- [x] 11.4 Refresh `MANIFEST.md` (no package set or dep changes expected, but rerun for safety)
- [x] 11.5 Update STATUS.md with the rolled-up gap closure