component §4: metadata.version semantics — monotonicity, reuse, relationship to the item

[justinmerrell]

Left open by #13. Issue #9 supplied no answer.

specifications/component/v1/spec.md §4 is only this TODO — the section has no normative content at all:

TODO — Define metadata.version semantics: monotonicity requirements, the relationship to the containing item's version, and whether reuse of a version number with different content is an error.

Why it matters

metadata.version is load-bearing in three places already:

• blueprint §4.1 — a repo-local reference deploys "the referenced document's own metadata.version", and componentVersion MUST NOT be present, so this field is the only thing naming what gets deployed;
• blueprint §3 and listing §3 — ERR_VERSION_MISMATCH pins a blueprint and its listing to each other, but says nothing about the component documents beneath them;
• a published component reference does carry componentVersion, so the two forms disagree about who owns the number.

Three rules depend on a field whose semantics are undefined.

The concrete questions

1. Must it increase? Against what — the previous release of the same slug, or nothing?
2. May two different documents carry the same version? If yes, ERR_VERSION_MISMATCH compares a number that does not identify content.
3. What does it relate to for an item holding several component documents, each with its own version? (This is the same knot as listing §3: what metadata.version agrees with in a COMPONENT item #21.)

What deciding it costs

Monotonicity is a capability-phase rule — it needs the catalog to know what the previous version was — so it does not tighten offline validation. Stating it is a minor release.

Refs #9