[1/4] Add selected growth reference to every Measurement result

[eatyourpeas]

Safety driver

Hazard rcpch/digital-growth-charts-documentation#174 records a case where Trisomy 21 chart curves were displayed with a measurement tooltip whose SDS and centile had been calculated against UK-WHO. A downstream chart cannot guard against this mismatch unless each calculated Measurement carries explicit reference provenance.

This issue previously combined timestamps, API-version information and reference provenance. The safety chain below scopes this implementation to calculation-reference provenance. Timestamps and API-version metadata can be handled independently and must not delay the reference guard.

Sequential delivery chain

1. This issue: add the selected calculation reference to every rcpchgrowth Measurement result.
2. rcpch/digital-growth-charts-server#207 passes the package-produced value through the API and OpenAPI schema.
3. rcpch/digital-growth-charts-react-component-library#217 rejects missing, unknown, mixed or mismatched measurement references before rendering.
4. rcpch/digital-growth-charts-documentation#175 documents the contract and records QMS and hazard mitigation evidence.

This is step 1 and blocks step 2.

Current behaviour

Measurement already stores the caller-selected public reference as self.reference and uses it for calculation, but the public Measurement.measurement dictionary omits it. Consumers commonly retain only .measurement, so provenance is lost at the package boundary.

The public serialized vocabulary already exists in rcpchgrowth/constants/reference_constants.py:

• uk-who
• trisomy-21
• trisomy-21-aap
• turners-syndrome
• cdc
• who

These are public calculation selectors. Internal table identifiers such as uk90_preterm, uk_who_child or trisomy_21_aap_infant are different concepts and must not be returned in this field.

Required change

• Add an always-present top-level reference field to Measurement.measurement.
• Serialize the exact canonical public selector supplied to the calculation, for example "reference": "trisomy-21".
• Define or reuse one canonical public reference type/vocabulary for annotations and validation without changing existing serialized string values.
• Keep existing string constants and callers compatible; do not replace them with enum objects whose equality or JSON behaviour could break consumers.
• Propagate the field naturally through generate_fictional_child_data because those results are also Measurement dictionaries.
• Do not infer the value from calculated centiles or the physical table selected at a particular age.

Compatibility

This is an additive top-level property and should be released as a semver-minor package change. Every existing section and numerical value must remain unchanged. A downstream strict schema may filter or reject the new field, which is why step 2 is a separate coordinated server change.

Acceptance criteria

• Every successful Measurement dictionary contains top-level reference as a plain string.
• The value exactly matches the selected member of the six-value public reference vocabulary.
• trisomy-21 and trisomy-21-aap remain distinguishable.
• turners-syndrome retains its existing canonical spelling.
• Reference provenance remains present when numerical results are unavailable but a Measurement result is still returned.
• Every fictional-child Measurement contains the selected reference.
• Existing top-level sections and all calculated values remain unchanged.
• Tests parameterize all six public references and include direct Trisomy 21 and fictional-child assertions.
• The full test suite passes.
• The released package version and implementation PR are linked in steps 2-4 and hazard #174.

[mbarton]

I would be ideal to put in the body of the response with all the results but this would represent a breaking change for users

Could we add new top level fields with this so it's not a breaking change?

[eatyourpeas]

We have a typescript interface that matches the API specification of the Measurement class. If we add a new top level object might that not break it for people using older versions of the chart component?

[mbarton]

Ah I see. Given it's a debugging option we could add it as a new always present field in the Open API spec and then as an optional field in the Typescript interface?