BSON docs: missing interoperability warning for marker 0x11, and binary round-trip asymmetry not mentioned #5311

Description

Two gaps on the BSON feature page (docs/mkdocs/docs/features/binary_formats/bson.md).

1. Marker 0x11 interoperability is only covered in one direction.

The serialization table maps number_unsigned in 9223372036854775808..18446744073709551615 to marker 0x11, with no caveat. In the BSON spec, 0x11 is Timestamp (a MongoDB-internal uint64 type), not a general unsigned integer — so documents this library writes will be read as timestamps by mongod and other drivers.

The existing note covers only the reading direction:

BSON type 0x11 is used to represent uint64 numbers. This library treats these values purely as uint64 numbers and does not parse them into date-related formats.

It appears under "Deserialization" and says nothing about what happens when other implementations read what this library writes. Since #4286 (v3.12.0) made to_bson() emit 0x11 rather than throwing out_of_range.407, the serialization side needs the same warning.

2. Binary round-trip is not identity.

A binary value with no subtype is written with subtype 0x00 and read back with subtype 0, so from_bson(to_bson(j)) != j:

json j;
j["b"] = json::binary({1, 2, 3});          // has_subtype() == false
const auto k = json::from_bson(json::to_bson(j));
// k["b"].get_binary().has_subtype() == true
// j == k  -->  false

This is stated in docs/mkdocs/docs/features/binary_values.md ("If no subtype is given, the generic binary subtype 0x00 is used"), but not on the BSON page, and the consequence for round-tripping is not spelled out anywhere. It is also untested: tests/src/unit-bson.cpp only round-trips binary values that already carry an explicit subtype (json::binary(s, 0) and json::binary(md5hash, 5)), so nothing would catch a regression here.

Suggested fix

• Add an interoperability warning next to the 0x11 row in the serialization table, or move/extend the existing note so it covers both directions.
• Note the subtype-less binary asymmetry on the BSON page and add a round-trip test for json::binary({...}) without a subtype.

Notes

This issue covers only the documentation gaps from a wider BSON review. The unbounded-recursion concern found in the same pass is already tracked in #5104 and addressed by #5293, so it is deliberately not repeated here.

Library version

develop @ 06ac77f