docs(rfc): RFC 0033 §3.2 amendment — compressed artifact encoding (run #20 answer)

[jensholdgaard]

What

The RFC 0033 §3.2 amendment answering run #20 (§9.14): zstd-compressed artifact at a new key template_map.v2.json.zst, format_version: 2. Docs only — dated amendment blocks in the RFC 0031 §3.6 style; the v1 design stays readable underneath.

Key decisions, with the rejected fork recorded:

• Version-in-key over magic-sniffing. Same-key zstd sniffing is correct but lies twice: old readers would classify a healthy v2 artifact Torn (§3.7 pins torn as the corruption page-signal — a mixed fleet would page on healthy state), and §3.3's UnknownVersion disposition becomes unreachable. A new key makes the bump literal absence for old readers — §3.3's unknown-version-is-absent rule realized in its cleanest form. Both audit walks ignore non-*.parquet keys by construction (verified at audit_scan.rs local + S3 arms), so the second key never enters LIST freshness.
• Publish hygiene: best-effort delete of the stale v1 key after a successful v2 publish; crash between the two is harmless (§3.4 amendment; §7 gains the hygiene open question).
• Abstention unchanged in spirit: publish iff the compressed size beats the folded audit bytes. §3.7's artifact-size histogram records compressed (published-object) bytes — the GET cost it always meant.
• §5/§6 scenario text unchanged — RFC0033.6's "artifact object's byte size" is what a warm GET pays, encoding-agnostic. §6 amendment pins validation as comparative run docs(rfc-0001): amend §6.1 to align record schema with OTLP LogRecord #21 from the implementation branch before merge, with the harness printing each pair's publish outcome (published/abstained + would-be size vs fold/lost_race/error) so run docs(architecture): OTLP log-format gap analysis (Half 1 investigation) #20's abstention-vs-failure ambiguity cannot recur.
• Zero new dependencies: zstd 0.13 is already in every querier build (parquet's zstd feature; ourios-bench binds it directly as the A1 reference codec) and already on the deny.toml allow-list.

Checks run

mdbook build clean. Docs only.

🤖 Generated with Claude Code

https://claude.ai/code/session_01WQY9wfrfRggqSpMLH8Xj3Y

[coderabbitai]

Warning

Review limit reached

@jensholdgaard, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 14 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 3f810f7d-7099-4c28-803e-3f481514edc9

📥 Commits

Reviewing files that changed from the base of the PR and between 1fdbd27 and c4f2c10.

📒 Files selected for processing (1)

• docs/rfcs/0033-cached-template-map.md

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch rfc0033-amend-compressed-artifact

---

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

[Copilot]

Pull request overview

Updates RFC 0033’s cached template-map artifact specification to introduce a zstd-compressed v2 artifact at a new, versioned key, clarifying mixed-version behavior and publish hygiene based on benchmark run #20 findings.

Changes:

• Amend §3.2 to specify zstd-compressed artifact encoding with format_version: 2 and a new key template_map.v2.json.zst.
• Add corresponding amendment notes in §3.3 and §3.4 (read dispositions, publish behavior, best-effort v1 key deletion).
• Add cross-section amendment pointers/notes tying the change to acceptance/validation guidance (incl. comparative run #21 expectations).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.