spec: Clarify metadata override semantics

[amacneil]

Update MCAP spec to clarify how readers should interpret multiple metadata records with the same name:

• recommend merge behavior in file order so later records overwrite earlier values for the same key
• clarify that readers may additionally expose an interface returning all metadata records without merging

[claude]

Resolved the prior MUST-level concern — SHOULD/MAY is the right call given none of the readers implement this today.

Two open questions on the current version: (1) merge vs. replace semantics — the switch from the original commit's replace behavior to merge has real implications for stale keys, and (2) no writer-side guidance, which leaves the motivation for duplicate names implicit. The use case context from the prior review thread is still unanswered.

[claude]

Merge vs. replace — is merge intentional here? The original commit used replace semantics (last record wins entirely), and this revision switched to merge (combine key-value pairs, last-write-wins per key). These are meaningfully different.

Consider: record 1 has {part_id: "A", serial: "123"}, record 2 has {part_id: "B"} (serial was removed). Merge produces {part_id: "B", serial: "123"} — silently carrying forward a stale key. Replace produces {part_id: "B"}.

Merge makes it impossible to "unset" a key, which could lead to subtle bugs when the intent is to publish a corrected/updated version of the metadata. Replace is simpler and avoids stale-data leakage. If merge is the desired behavior, it would help to document why — and maybe call out that keys cannot be removed, only overwritten.

Also: none of the six reader implementations do merge today (they all return all matching records individually), so either way this is new behavior that nobody implements yet. Worth noting in the PR description so it's clear this is aspirational guidance for future implementations.

[amacneil]

Merge is intentional. The Go cli uses merge when using mcap get metadata --name right?

The closest you can get to unsetting a key is to set it to an empty string.

[claude]

Any guidance for writers? The spec now tells readers what to do with duplicate names, but is silent on when/why a writer would produce them. Something like "Writers MAY write multiple metadata records with the same name to override or extend previously written metadata" would clarify intent and make the reader recommendation less surprising.

Also — what's the motivating use case? File concatenation? Writers appending corrected metadata? That context would help reviewers (and future spec readers) evaluate whether merge or replace is the right call.