feat: allow links to declare whether they are required

[JoshuaHarris391]

Links were declared as a parent/multiplicity/child triple and the generator stamped
required: true on every one, so the input language could not describe an optional parent.

That is not a cosmetic gap. Across the four dictionaries built with this tool, 41 of 113 links are
required: false, and the same triple shape appears with both values — in one repository
subject → site is required while subject → demographic_measurements, an identical one_to_one
triple, is not. No rule derived from the triple could produce both, so those values had been
hand-edited into the generated files and were destroyed on every regeneration.

It is also a live blocker: omix3schemadev cannot move to input-driven generation until this
exists, because regenerating would silently make eight optional parent relationships mandatory.

The change

A link may now declare required:

links:
  - parent: sample
    multiplicity: one_to_many
    child: lipidomics_file          # required by default
  - parent: site
    multiplicity: one_to_many
    child: lipidomics_file
    required: false                 # optional parent

It is read per link, so where a node has two or three parents each is answered independently
rather than the node getting a single blanket setting. The subgroup wrapper is untouched and still
means "at least one of these", so a node whose links are all optional is not left orphaned.

Default is true — what the generator emitted before — so the change is purely additive.

Also fixed

A data_file node with no declared links received no core_metadata_collection link while still
receiving the matching property, producing a schema that failed this tool's own
data_file_link_core_metadata rule. The tool should not be able to generate something its validator
rejects. No dictionary in the fleet has such a node, so this is inert for existing consumers.

Verification

Proof that it is additive: bpsych, omix3 and acdc were regenerated from their real inputs under
3.0.1 and under this build. All three are byte-identical — 19, 31 and 32 files respectively.

tests/test_link_required.py adds nine tests: the default, an optional link, per-link values across
a three-link subgroup, the flat single-link path, the injected core-metadata link staying optional,
precedence between a declared value and the fallback parameter, rejection of a meaningless value,
and a regression test for the link-less data_file bug. 173 tests pass on Python 3.9–3.12.

Hands-on: declared a mixed subgroup by hand, confirmed it generates true/false/false in the
right places and that validate still exits 0.

Documentation

Detail goes in docs/gen3_data_modelling/links.md — a new
section on declaring links from the input_yaml, the multi-parent case, a table distinguishing the
two levels of required, and the honest caveat that subgroup exclusive/required are still not
settable and that links to program/project/core_metadata_collection are discarded.
first_dictionary.md gets a short §4.3 with one example. The quickstart is deliberately
untouched — it does not discuss links and stays that way.

🤖 Generated with Claude Code