docs(unixfs): document PBNode field order

[lidel]

In both Go and JS and legacy code, dag-pb serializes Links before Data on the wire, but the UnixFS spec did not document this or its impact on implementations.

This PR adds explicit mention of this, along with backward and forward related interop guidance. This is not spec change, just clarifying something that was already in the spec (protobuf order and test vectors already had Links first), just stating it explicitly for humans and LLMs to ensure both orders are parsed correctly, future-proofing the interop of our stack.

Thanks to @achingbrain for flagging this gap and ping @rvagg who did extensive cleanups of IPLD specs before

Changes

• note after PBNode schema: field order is stricter than intuitive protobuf convention, decoders MUST accept both, encoders SHOULD use Links-before-Data per IPIP-499 profiles
• warning in dag-pb Types section: streaming parsers cannot determine node type until after all links are read
• test vectors: wire order annotations for directory and HAMT fixtures
• appendix: historical context and Robustness Principle guidance
• dag-pb spec reference updated to Wayback Machine snapshot

Related / CC

• Loosen PBNode decode rules ipld/js-dag-pb#8
  • fix: loosen decode rules to account for ancient data  ipld/js-dag-pb#9
• block-layer/codecs: dag-pb can't enforce PBNode ordering ipld/specs#360
• allow decoding PBNode fields in any order ipld/go-codec-dagpb#26
• dag-pb: more accurate schema and up-to-date impl description ipld/specs#297

[github-actions]

🚀 Build Preview on IPFS ready

• 🔎 Commit: 4a2539b
• 🔏 CID bafybeifp455twxdq5qv6dreqp7kvhloeifvj6fuqjfmfw2nz346dbhexwa
• 📦 Preview:

  • dweb.link

  • inbrowser.link

[achingbrain]

Protobuf also allows the Data field to be in between Link messages, not sure if that's worth mentioning too.

[lidel]

good flag. i checked Go parser will return error "duplicate Links section", so better to lock this down at spec level as "not allowed", i think?

@achingbrain clarified in 4a2539b, lmk if this sounds sensible (i marked it as SHOULD because its niche + unsure if we can enforce this behavior across implementations)

[achingbrain]

It's valid protobuf so if it needs locking down SHOULD is probably as far as it needs to go - otherwise it prevents use of off the shelf parsers.

[rvagg]

https://github.com/ipld/codec-fixtures/blob/master/negative-fixtures/dag-pb/decode/edges.json#L43-L45

we validate all our codec implementations against the links,data,links case, they all strictly disallow this

[rvagg]

prevents use of off the shelf parsers

It's the encoding that matters here, off-the-shelf parsers should be mostly fine in any case, it's that we don't want to see encoded forms like this show up anywhere or we're in for a world of pain. The general rule should be: the fewer variations for the same data the better. More determinism = more better for many use cases. More slop = more pain. So where we can avoid slop we should.