Initial Commit

openspec/archive/2026-05-02-bitpacker-modular-restructure/specs/bitpacker/spec.md

@@ -0,0 +1,53 @@
+## ADDED Requirements
+
+### Requirement: Core package exposes low-level bit I/O
+The `@suaveplan/bitpacker` package SHALL expose `BitWriter` and `BitReader` classes for bit-level read/write operations.
+
+#### Scenario: BitWriter packs bits sequentially
+- **WHEN** a caller invokes `writeUint(42, 8)` followed by `writeBool(true)` on a `BitWriter`
+- **THEN** the resulting byte array contains 42 in the first 8 bits and 1 in the 9th bit
+
+#### Scenario: BitReader unpacks bits sequentially
+- **WHEN** a caller constructs a `BitReader` from a packed byte array and invokes `readUint(8)` then `readBool()`
+- **THEN** the values match the original written values
+
+### Requirement: Core package exposes strategy manager
+The `@suaveplan/bitpacker` package SHALL expose `PackingStrategyManager` that maintains an ordered chain of `PackingStrategy` instances.
+
+#### Scenario: Strategy manager resolves schema to strategy
+- **WHEN** `findStrategy(schema)` is called with a schema token
+- **THEN** the first strategy whose `canHandle(schema)` returns `true` is returned
+
+#### Scenario: Custom strategy registration
+- **WHEN** `registerStrategy(strategy)` is called
+- **THEN** the strategy is inserted before the catch-all `InvalidSchemaStrategy`
+
+### Requirement: Core package exposes BitPacker orchestrator
+The `@suaveplan/bitpacker` package SHALL expose a `BitPacker` class that uses a `PackingStrategyManager` to pack/unpack values against schemas.
+
+#### Scenario: Round-trip pack and unpack
+- **WHEN** `pack(data, schema)` is invoked followed by `unpack(bytes, schema)`
+- **THEN** the unpacked value equals the original data
+
+#### Scenario: Schema registry resolves references
+- **WHEN** a schema contains `{ _ref: "namedSchema" }` and the name is registered via `registerSchema`
+- **THEN** the referenced schema is used for pack/unpack
+
+### Requirement: Genesis additions are preserved in core
+The core package SHALL preserve `zigzagEncode`/`zigzagDecode`, `packBits`/`unpackBits`, `peek(bits)`, `seek(position)`, and `align()`.
+
+#### Scenario: Peek does not advance bit position
+- **WHEN** `peek(8)` is called on a `BitReader`
+- **THEN** the returned value matches the next 8 bits and `bitPosition` is unchanged
+
+#### Scenario: Zigzag encoding round-trips
+- **WHEN** `zigzagEncode(n)` is called followed by `zigzagDecode` on the result
+- **THEN** the original value is restored for both positive and negative integers
+
+## MODIFIED Requirements
+
+None.
+
+## REMOVED Requirements
+
+None.