[goldyfruit]

🤖 Auto-generated by Claude Opus 5.5 via Claude Code — NOT human-reviewed. Verify before acting.

bitstring 5 removed BitStream and ConstBitStream and reversed the argument order of BitArray.insert(). serialization.py imports BitStream at module load, and the declared dependency is bitstring>=4.1.1. So a fresh install on Python 3.11 or later resolves bitstring 5, and importing hivemind_bus_client.client fails with ImportError: cannot import name 'BitStream'. That covers hivemind-core and every satellite. Python 3.10 still resolves bitstring 4, because bitstring 5 requires 3.11.

The decoder used BitStream only as a read cursor: read N bits, check the position, take the rest. It now reads through a small _FrameReader over Bits slices. Slicing behaves the same in bitstring 4 and 5, and the reader raises bitstring's ReadError on an over-read as BitStream.read did, so the existing error mapping to MalformedBinaryFrame is untouched. bitstring 5's own replacement, Reader, does not exist in bitstring 4, so it cannot serve both. The encoder's left padding uses prepend(), which takes the same argument in both versions, instead of insert() in a loop. The BINARY payload type check accepts Bits, which covers BitArray and bitstring 4's BitStream.

The wire format does not change. The cross-platform vectors and the rest of the suite pass unchanged on bitstring 4.4.0 and on 5.0.0 (1088 passed, 4 skipped on each, Python 3.12). The CI matrix covers both, because 3.10 resolves bitstring 4 and 3.11 to 3.14 resolve 5.

tests/test_bitstring_major_versions.py runs the codec in a child interpreter where BitStream and ConstBitStream are removed and the old insert() order is refused, whatever bitstring is installed. It round-trips BUS frames (compressed or not, versioned or not) and a BINARY frame, and checks that a truncated frame is malformed. With the source change reverted, it fails on bitstring 4.4.0 with the BitStream ImportError, not only on 5. It also covers the reader's bounds and the padding layout. Existing tests that built frames with BitStream, bytes= or the old insert() order now use the API both versions share.

Downstream, packages that depend on this one have been capping bitstring<5 until a release carries this change.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Bug Fixes
  • Improved compatibility across bitstring versions so text and binary messages can be encoded and decoded consistently, including frames with padding, compression, or versioning.
  • Invalid payload shapes and truncated binary frames are rejected with clear errors.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: 5ab339a7-5ce8-4d8c-a051-bbf115e4bf28

---

📥 Commits

Reviewing files that changed from the base of the PR and between 945661b and 58474bd.

---

📒 Files selected for processing (5)

• hivemind_bus_client/serialization.py
• tests/test_binary_send_payload_shape.py
• tests/test_bitstring_major_versions.py
• tests/test_serialization.py
• tests/test_wire_payload_is_an_object.py

---

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

---

---

📝 Walkthrough

Walkthrough

The serialization codec now uses Bits and a cursor-based reader for frame decoding. It prepends frame padding in one operation and updates binary payload validation. Tests cover compatibility across bitstring versions and frame behavior.

Changes

Serialization compatibility

Layer / File(s)	Summary
Codec input and frame handling hivemind_bus_client/serialization.py	The codec accepts Bits for binary payloads, prepends padding in one operation, and uses a cursor over Bits to read frames.
Compatibility and frame tests tests/test_bitstring_major_versions.py, tests/test_binary_send_payload_shape.py, tests/test_serialization.py, tests/test_wire_payload_is_an_object.py	Tests cover bitstring-version behavior, frame-reader bounds and positions, encoded padding, payload validation, and serialization fixtures.

Priority: ⬆️ High

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Bug fix

---

Merge Risk: ⚪ Minimal · up to 58474

This change restores import compatibility with bitstring 5 while keeping the wire format unchanged. No actionable merge-blocking risk was identified.

Pre-merge checks | 4 | 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 35.71% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 28 functions across 5 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly identifies the main change: compatibility for encoding and decoding binary frames with bitstring versions 4 and 5.
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

---

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

---

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

---

_{Comment @coderabbitai help to get the list of available commands.}

[goldyfruit]

Ready for review. bitstring 5.0.0 (released 2026-10-11) removed BitStream and reversed the argument order of BitArray.insert(). Any fresh install of hivemind-bus-client 0.4.4 now fails to import (cannot import name 'BitStream'), because the requirement is only bitstring>=4.1.1.

This replaces the BitStream read cursor with a small reader over Bits slices and uses prepend() for the padding. The wire format is unchanged, and the full suite passes on both bitstring 4.4.0 and 5.0.0. Until a release ships, downstream projects can pin bitstring<5.