Throw type_error.321 when serializing discarded values to binary formats

[nlohmann]

The CBOR, MessagePack, UBJSON, BJData and BSON writers skip the payload of a discarded value nested in an array or object, but they still count it in the container size. For BSON they also write its entry header. The result is corrupt binary output that cannot be parsed back (#4714).

All five writers now throw type_error.321 ("cannot serialize discarded value to ") for a discarded value anywhere in the tree. For CBOR, MessagePack, UBJSON and BJData this includes a discarded value at the top level. For BSON, a top-level discarded value keeps throwing the existing type_error.317 ("top-level type must be object").

• binary_writer.hpp: one JSON_HEDLEY_NO_RETURN helper, throw_on_discarded(), called from the discarded cases of write_cbor, write_msgpack, write_ubjson (UBJSON and BJData, including the optimized-array path) and the BSON value writer and size calculation. For BSON this case was wrongly treated as unreachable under LCOV_EXCL.
• Docs: new type_error.321 entry in exceptions.md. The to_cbor/to_msgpack/to_ubjson/to_bjdata/to_bson pages list the new exception.
• Tests in all five suites: a discarded value in an array, as an object value, nested deeper, and at the top level. Plus the optimized UBJSON/BJData arrays, and BSON. The old tests that expected the silent behavior now expect the exception.

This takes over #5382 by @ameliabarnabyhub, which went stale. The binary writers have changed a lot since then, so their change was redone on current develop, with them as the commit author. Review points from #5382:

• missing return/[[noreturn]] → the helper is JSON_HEDLEY_NO_RETURN
• amalgamation noise → regenerated with make amalgamate
• reuse of out_of_range.412 and the MessagePack size branches → dropped, since they are not related to Binary formats invalid encoding for <discarded> values in arrays and objects #4714
• no BSON tests → added

The exception id is 321 because 318 is used on develop, and 319 and 320 are used by open PRs (#5630, #5632).

This will conflict with #5518 (non-recursive binary writers). Whichever PR lands second needs a small rebase.

Closes #4714. Supersedes #5382. Thanks @ameliabarnabyhub!

Public API

This changes behavior but no signatures. Serializing a discarded value to a binary format used to silently produce corrupt output. It now throws type_error.321 (type_error.317 for a top-level value in BSON). Code that serializes only regular values is not affected.

🤖 Generated with Claude Code

[gregmarr]

The CBOR, MessagePack, UBJSON, BJData and BSON writers skip the payload of a discarded value nested in an array or object, but they still count it in the container size. For BSON they also write its entry header. The result is corrupt binary output that cannot be parsed back (#4714).

Would writing null instead of discarded fix the issue without blocking otherwise-valid documents from being written?

Original issue says better to throw an error than to write null and mask an error:
#4714 (comment)

[nlohmann]

As you found in #4714, writing null would silently produce a different document than the one the caller has. A discarded value only exists after a parse callback rejected it or after parse(..., false) failed, so serializing it is almost always a bug in the calling code. Throwing makes that visible instead of emitting something that round-trips to a value nobody asked for. Callers who really want null there can replace discarded values before serializing. The text serializer also treats discarded values as something that should not reach output (it writes <discarded>, which is not valid JSON either), so throwing is the consistent choice for the binary formats, where there is no such placeholder.

(Written by Claude Code.)

[gregmarr]

so serializing it is almost always a bug in the calling code

I'll accept that.