fix: drop unknown-magic items in cbor_decode instead of failing the document

[thedavidmeister]

Closes #186.

The adjudication

#186 asks, neutrally, whether cbor_decode is meant to be strict about unknown
magic numbers or to drop them. This PR takes drop, because the spec text is
one-sided on it:

• Design goal: "Tooling can efficiently O(1) drop/ignore meta that it does not
  need or support decoding and parsing for". The per-item magic is named as
  exactly the mechanism for that — "a signal of intent for the payload
  without needing to first parse ... the entire payload".
• "feel free to build systems and applications with your own numbers and
  interpretations", and the map structure exists "to facilitate future
  modifications to the conventions in this document in a way that tooling can
  adopt (or not) in a backwards compatible way".

Under the old behaviour neither is achievable: one third-party or newer-spec
item made the whole cbor-seq undecodable, so the supported items alongside it
were unreachable. The spec's magic number table already lists a number this
crate does not carry (Web data v1, the subject of #187), so a document a
conforming encoder can produce today is one this crate cannot read at all.

If a reviewer wants strict instead, then the spec text quoted above needs the
clarifying note #186 mentions, and this PR should be closed rather than
reworked.

What changed

RainMetaDocumentV1Item::cbor_decode peeks the magic under cbor map key 1 on
the already-parsed serde_cbor::Value and skips the item when it is not a
KnownMagic, then returns the rest.

• The Deserialize visitor is untouched and still errors on an unknown magic.
  magic is typed KnownMagic, so a single item with an unknown magic has no
  representation; the drop belongs at the sequence level, which is where the
  spec puts it.
• Only an unsigned integer under key 1 can be dropped. A missing, non-integer
  or negative key 1, and a sequence member that is not a map at all, still go
  through from_value and error exactly as before.
• An input left with no items after the drop is Error::UnsupportedMeta,
  not Ok(vec![]). cbor_decode never returning an empty vec is load-bearing:
  AuthoringMetaV2::fetch_for_contract indexes [0] on the result.
• The corrupt-meta guard drops track.len() != metas.len() (dropping items
  makes those lengths legitimately differ) and moves metas.is_empty() out to
  the new unsupported check. track.is_empty() and the end-offset equality
  stay, so empty input, a bare document prefix and trailing/truncated bytes are
  still CorruptMeta.

Overlap with sibling issues

All five open cbor_decode / KnownMagic issues were checked; this PR touches
one of them.

• cbor_decode corrupt-meta guard carries unreachable sub-conditions (eof offset equality, track/metas length) — equivalent-mutant evidence #190 — overlaps. It calls the corrupt-meta guard's
  track.len() != metas.len() and metas.is_empty() sub-conditions equivalent
  mutants. This PR removes the first (dropping items makes it reachable in the
  other direction, so it had to go) and repurposes the second as the
  unsupported check. The eof error.offset() == len condition cbor_decode corrupt-meta guard carries unreachable sub-conditions (eof offset equality, track/metas length) — equivalent-mutant evidence #190 also names
  is untouched.
• KnownMagic is missing Web data v1 (0xff5dcce9b571ba42) listed in the metadata-v1 spec magic number table #187 (Web data v1 missing from KnownMagic) — no overlap. Adding that
  variant only moves one number from dropped to decoded. The new tests
  deliberately use 0xdeadbeefdeadbeef, never a spec-table number, so they do
  not collide with that fix.
• Items missing mandatory cbor keys 0/1 abort the whole decode; spec says they MUST be treated as unexpected and dropped/ignored #188 (items missing mandatory keys 0/1 should be dropped) — no overlap
  and no behaviour change here: an item with no key 1 still reaches
  from_value and still errors. If Items missing mandatory cbor keys 0/1 abort the whole decode; spec says they MUST be treated as unexpected and dropped/ignored #188 lands, its drop belongs in this same
  loop.
• RainMetaDocumentV1Item decode accepts duplicate cbor map keys with last-wins instead of treating the map as invalid #191 (duplicate cbor map keys) — no overlap. The peek reads the same
  serde_cbor::Value map from_value already consumed, so whatever that does
  with duplicates is unchanged.
• cbor_decode accepts input without the rain meta document prefix; spec says tooling MUST discard data not beginning with the magic number #203 (input without the document prefix) — no overlap; the prefix
  handling is untouched.

QA

• Discriminating tests: test_cbor_decode_drops_unknown_magic_items,
  test_cbor_decode_unknown_magic_first_item,
  test_cbor_decode_all_unknown_magic_is_unsupported,
  test_cbor_decode_unknown_magic_then_truncated_is_corrupt — each fails on
  base, verified by mutating the skip back off (if true || !is_unknown_magic,
  which restores the base decode path): all four fail, and the mixed-document
  one fails with the issue's own repro,
  SerdeCborError(Message("unknown magic number")). The base-behaviour test
  they replace, test_cbor_decode_unknown_magic_errors, is deleted — it pinned
  the behaviour this PR changes.
  test_cbor_decode_non_integer_magic_errors and
  test_cbor_decode_non_map_item_errors do NOT fail on base (base also errors
  there); they are guard tests bounding the new drop path, mutation-killed
  below.

• Mutations applied:

  1. if !is_unknown_magic → if true || !is_unknown_magic (never drop) →
     killed by test_cbor_decode_drops_unknown_magic_items,
     test_cbor_decode_unknown_magic_first_item,
     test_cbor_decode_all_unknown_magic_is_unsupported,
     test_cbor_decode_unknown_magic_then_truncated_is_corrupt (4 failed).
  2. if metas.is_empty() { Err(UnsupportedMeta)? } → if false && ...
     (no unsupported guard, returns Ok(vec![])) → killed by
     test_cbor_decode_all_unknown_magic_is_unsupported (1 failed).
  3. peek_magic's two _ => None arms → _ => Some(0) (treat a missing,
     non-integer or non-map key 1 as an unknown magic and drop it) → killed by
     test_cbor_decode_non_integer_magic_errors,
     test_cbor_decode_non_map_item_errors and the pre-existing
     test_cbor_decode_missing_magic_errors (3 failed).

  Each mutant was reverted and the suite re-run green after measuring.

• Oracle: the metadata-v1 spec
  (https://github.com/rainlanguage/specs/blob/main/metadata-v1.md), quoted
  above, for the drop/ignore behaviour; the cbor spec for the expected bytes.
  Every fixture is handwritten byte by byte (handwritten_map_for emits
  a2 00 41 <payload> 01 1b <magic big-endian> from the cbor major types, not
  from cbor_encode), and the expected decoded values are built with
  plain_item, so no assertion is computed by the code under test.

• Category check: the issue asks one question — strict vs drop — and reports one
  behaviour (a document mixing supported and unknown-magic items decodes to
  nothing). Covered: the mixed document now decodes to its supported items in
  order (unknown in the middle, and unknown first), and the all-unknown boundary
  the question implies is settled explicitly as UnsupportedMeta. The issue's
  fallback ask — "if the strict behaviour is intended, the spec text may deserve
  a clarifying note" — is not taken, because this PR adjudicates the other way;
  the spec repo is not this repo and no spec change is made here.

Verification: cargo test -p rain-metadata --lib meta:: — 237 passed, 0 failed.
cargo clippy --all-targets -- -D warnings and cargo fmt --check clean. The
full suite was not run locally by request; CI covers it.

🤖 Generated with Claude Code

[coderabbitai]

Warning

Review limit reached

Next included review available in 17 minutes.

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: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 9a1f7625-e435-4c41-a1e4-a332f91497c7

📥 Commits

Reviewing files that changed from the base of the PR and between 45ca96c and a0fab88.

📒 Files selected for processing (1)

• crates/cli/src/meta/mod.rs

---

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