docs(wire-format): a CK v3 frame header may end in spaces that align the payload (LAB-9999)

[27Bslash6]

A CK v3 frame's HEADER may now be followed by ASCII spaces, counted in HDR_LEN, that align the payload. cachekit-py uses this for uncompressed, unencrypted Arrow payloads, so the Arrow IPC file starts on a 64-byte boundary of a File backend cache file (polars copies misaligned numeric columns): cachekit-io/cachekit-py#581.

• spec/wire-format.md, "Python: CK v3 frame", HEADER bullet: one MAY clause, no new MUST, so no requirement id.
• changelog.d/20261018_lab-9999.md: the entry.
• test-vectors/python-frame.json: a new padded_header_frame vector (raw_payload_frame with its header padded so the payload starts at frame offset 128), generated by tools/python-frame-reference.py. Both reference readers parse it to the same header and payload, so a reader that rejected padding would now fail conformance. It is parse-level only: an SDK test that re-wraps vectors byte for byte must skip it. conformance/coverage.md is regenerated; it now marks the SDKs' vendored python-frame.json copies as behind the current revision.

Not breaking. JSON allows trailing whitespace, so a reader parses a padded header unchanged; both reference readers use their language's standard JSON parser. Unpadded frames stay valid, and every existing vector is unchanged. tools/conformance.py check, tools/python-frame-reference.py verify, tools/test_python_frame_reference.py, tools/frame-crosscheck.mjs and tools/test_changelog_collect.py pass.

Closes LAB-9999

[coderabbitai]

Warning

Review limit reached

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

Next included review available in 42 minutes.

Check out review usage here.

View limit details

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

Learn how review limits work.

Review configuration:

⚙️ Run configuration

• Configuration used: Repository: cachekit-io/protocol/.coderabbit.yaml
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: 787c1ca2-2749-4a1c-a42c-497a19fac221

📥 Commits

Reviewing files that changed from the base of the PR and between 3d64631 and b79285d.

📒 Files selected for processing: 1

• tools/python-frame-reference.py

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: 4154c08e-f1c9-4388-be95-f838924ad059

📥 Commits

Reviewing files that changed from the base of the PR and between 97b12c6 and 3d64631.

📒 Files selected for processing: 5

• changelog.d/20261018_lab-9999.md
• conformance/coverage.md
• spec/wire-format.md
• test-vectors/python-frame.json
• tools/python-frame-reference.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.

Summary by CodeRabbit

• Documentation
  • Clarified that CK v3 headers may include trailing ASCII spaces for alignment, and that readers accept both padded and unpadded frames.
  • Documented 64-byte alignment for uncompressed, unencrypted Arrow payloads in File backend cache files.
  • Added a padded-header example showing that readers parse it to the same header and payload as an unpadded frame.

Walkthrough

The wire-format specification and changelog describe optional ASCII-space padding in CK v3 headers. The reference generator and test vector add a frame with padding included in HDR_LEN and the payload at offset 128. The documentation states that cachekit-py uses padding to align certain Arrow payloads to a 64-byte boundary.

Changes

CK v3 header padding

Layer / File(s)	Summary
Document padded-header behaviour spec/wire-format.md, changelog.d/20261018_lab-9999.md, conformance/coverage.md	The specification permits ASCII spaces in the JSON header, counted in HDR_LEN, and requires readers to parse the padded header unchanged. It documents Arrow payload alignment. The changelog records that unpadded frames remain valid and existing vectors are unchanged. The coverage table notes that SDK fixtures are unversioned and not at the current revision.
Generate and record padded-header vector tools/python-frame-reference.py, test-vectors/python-frame.json	The reference generator creates a padded frame with its payload at offset 128 and checks that parsing yields the same header and payload as the unpadded frame. The vector records the frame and its expected values.

Priority: ➖ Normal

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Other

Merge Risk: ⚪ Minimal · up to 3d646

The change documents optional header padding and adds a parse-level vector. The inspected checks do not introduce a byte-round-trip failure, so no actionable merge blocker remains.

Pre-merge checks: 4 · 1

Failed checks: 1 warning

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 1 files. (4 skipped: 4 …	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks: 4 passed

Check name	Status	Explanation
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.
Title check		The title clearly identifies the main change: allowing spaces at the end of CK v3 frame headers to align the payload.
Description check		The description accurately explains the specification change, implementation context, test vector, compatibility impact, and validation results.

Full details: Docstring Coverage

Explanation

Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 1 files. (4 skipped: 4 unsupported.)

Resolution

Write docstrings for the functions missing them to satisfy the coverage threshold.

✨ Finishing Touches: 💡 1

📝 Generate docstrings: 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• 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.}

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

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

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