docs(wire-format): cachekit-core vendors fixture 1.1.1, so the bin16 coverage gap is closed (LAB-1750)

[27Bslash6]

Corrects spec/wire-format.md, which still said cachekit-core vendors fixture 1.1.0 and that width_boundary_bin16_bin has no canonical-writer (lz4_flex) compressed-byte or checksum check. Both claims have been false since cachekit-io/cachekit-core#70 merged. cachekit-core now pins 1.1.1 (fixture_is_current_version_with_vectors), re-encodes every bin twin, and derives each twin's expected marker from the decoded compressed_data length.

The gap paragraph is replaced with the current state, plus one rule for anyone vendoring the fixture: derive the marker from the length. An assertion that every twin is bin8 fails on 1.1.1, and one that accepts all three widths cannot detect a non-shortest header. It also drops the now-dangling "subject to the vendored-version gap" cross-reference, and adds a CHANGELOG entry.

Docs only. tools/wire-format-reference.py verify still passes: all 7 vector pairs, with msgpack-python conformance.

Summary by CodeRabbit

• Documentation
  • Updated the wire-format documentation to identify the vendored fixture version as 1.1.1.
  • Clarified that canonical compressed-byte and checksum checks cover the width_boundary_bin16_bin fixture.
  • Documented shortest-width marker validation for each *_bin fixture, including the bin16 pair, and updated the reference-verifier coverage description.

Summary

Documentation-only change to spec/wire-format.md that condenses the description of how the pinned wire-format fixture is verified. Version-specific statements about which fixture release cachekit-core vendors are replaced with version-independent guidance. No public APIs, code, or fixture data are modified.

Changes

Scope note (layer overview section)

• Removes the parenthetical saying cachekit-core vendors 1.1.1 and so covers every *_bin twin, including the bin16 pair.
• The sentence now says only that the re-encode assertion covers the vectors the pinned file contains.

Compressed-bytes canonicity section

• Removes the narrative that cachekit-core pins version == "1.1.1" and so applies the lz4_flex compressed-byte and xxh3-64 checks to width_boundary_bin16_bin.
• States generally that cachekit-core's tests recompute each twin's lz4_flex bytes and xxh3-64 checksum for the vectors present in its vendored fixture.
• Keeps the guidance for anyone vendoring the fixture, now phrased as a direct recommendation. Each *_bin twin's expected marker should be derived from its decoded compressed_data length:
  • ≤255 → 0xc4
  • ≤65535 → 0xc5
  • otherwise → 0xc6
• Keeps both warnings:
  • An assertion that every twin is bin8 fails on width_boundary_bin16_bin (0xc5, 303-byte compressed_data).
  • An assertion that accepts all three widths cannot detect a non-shortest header.
• Removes the sentence about this repo's tools/wire-format-reference.py verify asserting legacy and bin re-encode byte-identity for the bin16 pair, and liblz4 reproducing its compressed bytes on the optional lz4 leg. The existing statement that the liblz4 reference mapping is decode-verified against every vector is retained.

Impact

The spec no longer ties its verification description to a specific fixture version. The normative guidance on marker derivation and the canonical-writer scope is unchanged.

[kodus-27b]

Code Review Completed! 🔥

The code review was successfully completed based on your current configurations.

Kody Guide: Usage and Configuration

Interacting with Kody

• Request a Review: Ask Kody to review your PR manually by adding a comment with the `@kody start-review` command at the root of your PR.

• Provide Feedback: Help Kody learn and improve by reacting to its comments with a 👍 for helpful suggestions or a 👎 if improvements are needed.

Providing Context (Files & MCPs)

Add these hints in your PR description (or a comment) to unlock deeper checks:

• Ticket / Acceptance Criteria: `Refs: ABC-123` (Linear/Jira/Asana/ClickUp/Trello) or a direct ticket link.
• Bugfix Validation: a Sentry/Datadog/Bugsnag event link (or paste the stack trace/error message).
• Endpoint Risk: mention the route (e.g., `POST /api/payments`) or controller/action name.
• Attach a repo file as context: use an explicit marker like `@file:docs/guide.mdx#L10-L50` (replace with your real path).
• API Contract Docs: include `@file:openapi.yaml` or `@file:swagger.json` when changing routes/schemas.
• Definition of Done / Standards: include `@file:DOD.md` or `@file:CONTRIBUTING.md` if your repo has them.
• Design System Source of Truth: include `@file:ui/index.ts` (replace with your DS entrypoint path).
• Feature Flags: include the flag key/name and `@file:flags.ts` / `@file:config.json` (and optionally the PostHog flag name).
• Edge/CDN Rules: link the Cloudflare rule/zone or describe the intended redirect/header behavior.
• Attach an MCP tool output: use `@mcp<provider|tool>` (replace with an installed MCP provider + tool, e.g., `@mcp<sentry|events.search>`).

Current Kody Configuration

Review Options

The following review options are enabled or disabled:

Options	Enabled
Bug	✅
Performance	✅
Security	✅
Business Logic	✅

Access your configuration settings here.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

Warning

Review limit reached

Next included review available in 52 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Repository: cachekit-io/protocol/.coderabbit.yaml

Review profile: ASSERTIVE

Plan: Advanced

Run ID: 2e8048c5-fc3f-4226-adeb-4b73f39631bd

📥 Commits

Reviewing files that changed from the base of the PR and between 8b00fd3 and 9d4b4ba.

📒 Files selected for processing (1)

• spec/wire-format.md

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository: cachekit-io/protocol/.coderabbit.yaml

Review profile: ASSERTIVE

Plan: Advanced

Run ID: 2e35803c-bf1f-463a-9381-dbbe99383078

📥 Commits

Reviewing files that changed from the base of the PR and between 281a064 and 8b00fd3.

📒 Files selected for processing (2)

• CHANGELOG.md
• spec/wire-format.md

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

The specification and changelog now document cachekit-core fixture version 1.1.1 and describe verification coverage for the *_bin fixtures, including compressed bytes, checksums, and shortest-width markers.

Changes

Wire-format coverage documentation

Layer / File(s)	Summary
Document fixture verification coverage spec/wire-format.md, CHANGELOG.md	The specification describes canonical-writer byte and checksum checks, shortest-width marker checks, and verifier coverage for the 1.1.1 *_bin fixtures. The changelog records the width_boundary_bin16_bin details and marker-width expectations.

Priority: ⬇️ Low

Estimated code review effort: 1 (Trivial) | ~4 minutes

Change: Other

Merge Risk: ⚪ Minimal · up to 8b00f

The specification and changelog update fixture-coverage documentation, with no established runtime impact or actionable merge blocker. The upstream checksum assertions remain unverified.

Architecture Summary

Architecture risk: 🔵 Low · up to 8b00f

The change affects 2 systems.

Changed systems: CHANGELOG.md, spec

Architecture concerns
No architecture-level concerns identified.

Review details

Systems and components

• observed — CHANGELOG.md (service) was modified; 1 changed file maps to changed impact.
• observed — spec (service) was modified; 1 changed file maps to changed impact.

Before / after behavior

• observed — Modified behavior in CHANGELOG.md: Adds the LAB-1750 changelog note correcting the pinned fixture version to 1.1.1 and documenting the missing canonical-writer byte and checksum checks for width_boundary_bin16_bin. It states that vendored *_bin twins’ expected markers must be derived from decoded compressed_data length, not assumed to be bin8 or accepted at any bin width.
• observed — Modified behavior in spec/wire-format.md: The scope text changes the cachekit-core fixture version from 1.1.0 to 1.1.1 and states that re-encode checks cover all *_bin twins, including the bin16 pair.
• observed — Modified behavior in spec/wire-format.md: The paragraph now continues below with updated details rather than the previous reference to a vendored-version gap.
• observed — Modified behavior in spec/wire-format.md: The former account of width_boundary_bin16 lacking canonical-writer and checksum coverage, and the steps needed to add it, is replaced by coverage details for width_boundary_bin16_bin under fixture version 1.1.1. The text specifies lz4_flex byte checks and checksum recomputation, shortest-width marker checks derived from decoded data length, the repo verifier’s legacy and bin re-encode checks, and liblz4’s optional encode coverage.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarises the main documentation change: cachekit-core vendors fixture 1.1.1 and the bin16 coverage gap is closed. It is specific and related to the changeset.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

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.}

[kodus-27b]

Code Review Completed! 🔥

The code review was successfully completed based on your current configurations.

Kody Guide: Usage and Configuration

Interacting with Kody

• Request a Review: Ask Kody to review your PR manually by adding a comment with the `@kody start-review` command at the root of your PR.

• Provide Feedback: Help Kody learn and improve by reacting to its comments with a 👍 for helpful suggestions or a 👎 if improvements are needed.

Providing Context (Files & MCPs)

Add these hints in your PR description (or a comment) to unlock deeper checks:

• Ticket / Acceptance Criteria: `Refs: ABC-123` (Linear/Jira/Asana/ClickUp/Trello) or a direct ticket link.
• Bugfix Validation: a Sentry/Datadog/Bugsnag event link (or paste the stack trace/error message).
• Endpoint Risk: mention the route (e.g., `POST /api/payments`) or controller/action name.
• Attach a repo file as context: use an explicit marker like `@file:docs/guide.mdx#L10-L50` (replace with your real path).
• API Contract Docs: include `@file:openapi.yaml` or `@file:swagger.json` when changing routes/schemas.
• Definition of Done / Standards: include `@file:DOD.md` or `@file:CONTRIBUTING.md` if your repo has them.
• Design System Source of Truth: include `@file:ui/index.ts` (replace with your DS entrypoint path).
• Feature Flags: include the flag key/name and `@file:flags.ts` / `@file:config.json` (and optionally the PostHog flag name).
• Edge/CDN Rules: link the Cloudflare rule/zone or describe the intended redirect/header behavior.
• Attach an MCP tool output: use `@mcp<provider|tool>` (replace with an installed MCP provider + tool, e.g., `@mcp<sentry|events.search>`).

Current Kody Configuration

Review Options

The following review options are enabled or disabled:

Options	Enabled
Bug	✅
Performance	✅
Security	✅
Business Logic	✅

Access your configuration settings here.