docs+feat(rvf): ADR-009 — RVF v1 wire contract, exact magic bytes, golden vectors, CI gate - #769
Merged
Merged
Conversation
…t CI gate Derive Default where clippy requires it (quality.rs, security.rs, sha256.rs) and const-block a constant assertion — mechanical, behavior-preserving; the new rvf-wire-contract workflow runs clippy -D warnings over rvf-types and would fail its first run without these. Co-Authored-By: claude-flow <ruv@ruv.net>
…c bytes and golden vectors
Two incompatible layouts were both described as RVF: ADR-004/005's fixed
64-byte header at offset zero, and the shipped append-only segment stream
with a tail-discovered 4096-byte Level-0 root manifest. The magic
mnemonics (RVFS/RVM0) also read as ASCII byte sequences when the v1 wire
bytes are actually their little-endian serializations (53 46 56 52 /
30 4D 56 52).
- ADR-009 makes the shipped tail-manifest layout normative for v1 and
pins the exact wire bytes; ADR-004/005 wire sections marked superseded
- rvf-types exports SEGMENT_MAGIC_BYTES / ROOT_MANIFEST_MAGIC_BYTES;
docs state the mnemonic-vs-wire distinction explicitly
- Golden byte-vector tests derived from shipped writer output: full
64-byte canonical empty segment header (SHAKE-256 empty-input value
matches the NIST vector), root manifest prefix 30 4D 56 52 01 00 00 00
+ trailing CRC32C FF DD 18 14 + zero-fill, and a tail-discovery
round-trip proving no offset-zero header is required
- Fixed tail_scan.rs comment documenting the wrong anchor byte ('R'/0x52
where the code correctly scans 0x53) and doc pseudocode comparing wire
bytes to literal ASCII (a reader built from it would reject every real
RVF file)
- New rvf-wire-contract CI workflow (pinned actions, fmt+clippy+tests
over rvf-types/rvf-wire on wire-related paths)
Co-Authored-By: claude-flow <ruv@ruv.net>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Codifies the shipped RVF v1 wire format as the single normative contract (ADR-009), resolving the spec inconsistency where ADR-004/005 described a fixed offset-zero header while the shipped crates implement a tail-discovered manifest — flagged as the top blocker for optical/delta RVF delivery work.
Contents
docs/architecture/decisions/): tail-manifest layout normative for v1; exact little-endian wire bytes pinned (segment53 46 56 52, root30 4D 56 52); version-stability rules for any future byte change; ADR-004/005 wire sections marked superseded.SEGMENT_MAGIC_BYTES/ROOT_MANIFEST_MAGIC_BYTES; docs distinguish mnemonic (RVFS/RVM0) from wire bytes.rvf-wire/tests/wire_contract_golden.rs), derived from shipped writer output, all claims verified empirically:46b9dd2b...30 4D 56 52 01 00 00 00, trailing CRC32CFF DD 18 14, zero-fill in betweentail_scan.rscomment documented the wrong anchor byte (code was right); doc pseudocode compared wire bytes to literal ASCII — a reader built from it would reject every real RVF file.rvf-wire-contract.yml— fmt + clippy-D warnings+ tests over rvf-types/rvf-wire on wire-related paths, pinned action SHAs,contents: read.Verification
cargo fmt --check,clippy -D warnings: clean. Tests: rvf-types 230, rvf-wire 57 + 3 golden — all passing. Workflow YAML parses.No wire bytes changed — existing artifacts, hashes, and signatures remain valid.
🤖 Generated with claude-flow