Merge branch 'v1423/labs' into release/v1.42.3

docs/api/openapi.yaml

@@ -14905,11 +14905,14 @@ paths:
         "403": *a11
         "409": *a7
         "422":
-          description: Nothing was written. `meta.errorCode` = `labs.create.invalid` when the body failed validation (every issue
+          description: "Nothing was written. `meta.errorCode` = `labs.create.invalid` when the body failed validation (every issue
             under `details.issues`), or `labs.unit.mismatch` when a numeric reading states a `unit` other than the one
-            its marker is tracked in (`meta.markerUnit`, `meta.readingUnit`). A unit is compared only when one is sent;
-            with a `biomarkerId` it may be omitted and the marker's unit is then the stated one. Spelling is forgiven
-            (`mmol/l`, `ug/L` for `µg/L`); a different unit is refused, never relabelled.
+            its marker is tracked in AND the pair cannot be converted (`meta.markerUnit`, `meta.readingUnit`,
+            `meta.reason` = `unknown_analyte` | `unknown_unit` | `not_finite`). A unit is compared only when one is
+            sent; with a `biomarkerId` it may be omitted and the marker's unit is then the stated one. Spelling is
+            forgiven (`mmol/l`, `ug/L` for `µg/L`); a different unit is converted when the marker's analyte is known and
+            the pair is in the unit-conversion registry (the 201 response then carries `converted: true`), and refused
+            otherwise, never relabelled."
           content:
             application/json:
               schema:
@@ -67394,6 +67397,16 @@ components:
             - type: "null"
         unit:
           type: string
+        converted:
+          type: boolean
+        sourceValue:
+          anyOf:
+            - type: number
+            - type: "null"
+        sourceUnit:
+          anyOf:
+            - type: string
+            - type: "null"
         referenceLow:
           anyOf:
             - type: number
@@ -67422,6 +67435,10 @@ components:
           anyOf:
             - type: string
             - type: "null"
+        printedReferenceText:
+          anyOf:
+            - type: string
+            - type: "null"
         referenceOrigin:
           $ref: "#/components/schemas/LabReferenceRangeOrigin"
         referenceDivergesFromCatalog:
@@ -67446,6 +67463,9 @@ components:
         - value
         - valueText
         - unit
+        - converted
+        - sourceValue
+        - sourceUnit
         - referenceLow
         - referenceHigh
         - catalogReferenceLow
@@ -67453,6 +67473,7 @@ components:
         - sourceReferenceLow
         - sourceReferenceHigh
         - sourceReferenceText
+        - printedReferenceText
         - referenceOrigin
         - referenceDivergesFromCatalog
         - takenAt
@@ -67476,8 +67497,14 @@ components:
         numbers could be read out of it). `catalogReferenceLow` / `catalogReferenceHigh` are the Biomarker band.
         `referenceOrigin` names the winner and `referenceDivergesFromCatalog` is true when the report's window and the
         catalog band state different limits — a surface showing only one of the two is showing a partial answer. The
-        client renders these values and never recomputes the range. The encrypted note is never echoed in list rows;
-        `hasNote` flags its presence and the single-resource GET returns the decrypted `note`.
+        client renders these values and never recomputes the range. `converted` is true when the stored `value` was
+        converted into the marker's `unit` from another unit; `sourceValue` and `sourceUnit` are then what the report
+        printed (full precision, round for display), and the report's own window was converted with it:
+        `sourceReferenceLow` / `sourceReferenceHigh` are then in the marker's `unit`. The printed range text is not
+        converted and stays in `sourceUnit`, so for a converted reading `sourceReferenceText` is null and the verbatim
+        text is in `printedReferenceText` instead, never mixed with the converted numbers. A reading stored as stated
+        has `converted: false`, two nulls and a null `printedReferenceText`. The encrypted note is never echoed in list
+        rows; `hasNote` flags its presence and the single-resource GET returns the decrypted `note`.
     LabReferenceRangeOrigin:
       type: string
       enum:
@@ -67556,6 +67583,16 @@ components:
             - type: "null"
         unit:
           type: string
+        converted:
+          type: boolean
+        sourceValue:
+          anyOf:
+            - type: number
+            - type: "null"
+        sourceUnit:
+          anyOf:
+            - type: string
+            - type: "null"
         referenceLow:
           anyOf:
             - type: number
@@ -67584,6 +67621,10 @@ components:
           anyOf:
             - type: string
             - type: "null"
+        printedReferenceText:
+          anyOf:
+            - type: string
+            - type: "null"
         referenceOrigin:
           $ref: "#/components/schemas/LabReferenceRangeOrigin"
         referenceDivergesFromCatalog:
@@ -67610,6 +67651,9 @@ components:
         - value
         - valueText
         - unit
+        - converted
+        - sourceValue
+        - sourceUnit
         - referenceLow
         - referenceHigh
         - catalogReferenceLow
@@ -67617,6 +67661,7 @@ components:
         - sourceReferenceLow
         - sourceReferenceHigh
         - sourceReferenceText
+        - printedReferenceText
         - referenceOrigin
         - referenceDivergesFromCatalog
         - takenAt
@@ -67820,7 +67865,8 @@ components:
                   - duplicate
                   - unit_mismatch
                 description: "`duplicate`: the row matched a live reading at commit time. `unit_mismatch`: the row states a unit other
-                  than the one its marker is tracked in, so it was not written."
+                  than the one its marker is tracked in and the pair cannot be converted, so it was not written. A pair
+                  that can be converted is written in the marker's unit and reported with `converted: true`."
             required:
               - analyte
               - reason
@@ -67867,6 +67913,16 @@ components:
             - type: "null"
         unit:
           type: string
+        converted:
+          type: boolean
+        sourceValue:
+          anyOf:
+            - type: number
+            - type: "null"
+        sourceUnit:
+          anyOf:
+            - type: string
+            - type: "null"
         referenceLow:
           anyOf:
             - type: number
@@ -67895,6 +67951,10 @@ components:
           anyOf:
             - type: string
             - type: "null"
+        printedReferenceText:
+          anyOf:
+            - type: string
+            - type: "null"
         referenceOrigin:
           type: string
           enum:
@@ -67928,6 +67988,9 @@ components:
         - value
         - valueText
         - unit
+        - converted
+        - sourceValue
+        - sourceUnit
         - referenceLow
         - referenceHigh
         - catalogReferenceLow
@@ -67935,6 +67998,7 @@ components:
         - sourceReferenceLow
         - sourceReferenceHigh
         - sourceReferenceText
+        - printedReferenceText
         - referenceOrigin
         - referenceDivergesFromCatalog
         - takenAt
@@ -67945,6 +68009,9 @@ components:
         - updatedAt
       additionalProperties: false
       description: A written reading. Its reference window resolves exactly as it does on `/api/labs` — see `LabResult`.
+        `converted`, `sourceValue` and `sourceUnit` say when the row's unit was converted into its marker's and what the
+        report printed; for a converted row the printed range text is in `printedReferenceText` (in `sourceUnit`) and
+        `sourceReferenceText` is null.
     AiRunEnvelope:
       type: object
       properties:
@@ -68184,8 +68251,16 @@ components:
             - type: string
             - type: "null"
           description: "The unit the matched marker is tracked in, or null when the marker does not exist yet (it will adopt this
-            row's unit). A row whose `unit` differs from it cannot be committed: the commit skips it with `reason:
-            unit_mismatch`, and the review screen marks it before Save."
+            row's unit). A row whose `unit` differs from it is converted on commit when the marker's analyte is known
+            and the pair is in the unit-conversion registry; otherwise the commit skips it with `reason: unit_mismatch`,
+            and the review screen marks it before Save."
+        markerAnalyteKey:
+          anyOf:
+            - type: string
+            - type: "null"
+          description: The analyte the matched marker is (the catalog slug, e.g. `fasting-glucose` or `ldl`, or a registry-only
+            key such as `urea`), or null when the marker does not exist yet or its name matches none. With `markerUnit`
+            it tells a client whether a row in another unit can be converted on commit.
         duplicateOf:
           anyOf:
             - type: string
@@ -68202,6 +68277,7 @@ components:
         - confidence
         - biomarkerMatch
         - markerUnit
+        - markerAnalyteKey
         - duplicateOf
       additionalProperties: false
       description: "One proposed reading transcribed from the upload. UNTRUSTED model output annotated server-side:
@@ -68333,6 +68409,10 @@ components:
           anyOf:
             - type: string
             - type: "null"
+        analyteKey:
+          anyOf:
+            - type: string
+            - type: "null"
         hasContext:
           type: boolean
         context:
@@ -68352,16 +68432,21 @@ components:
         - lowerBound
         - upperBound
         - panel
+        - analyteKey
         - hasContext
         - context
         - hidden
         - createdAt
         - updatedAt
       additionalProperties: false
-      description: A user-scoped catalog marker. `context` is the decrypted per-marker note (or null); `hasContext` flags its
-        presence. `hidden` drops the marker from the active catalog list and the lab-entry pickers without deleting it
-        (its readings and unit/range survive). A `LabResult` linking this marker resolves its unit + reference bounds
-        from here.
+      description: "A user-scoped catalog marker. `context` is the decrypted per-marker note (or null); `hasContext` flags its
+        presence. `analyteKey` is the analyte the marker was recognised as: the catalog slug its name belongs to (e.g.
+        `fasting-glucose`, `ldl`, `hdl`), or a key of the unit-conversion registry for an analyte with no catalog seed
+        (e.g. `urea`, `uric-acid`), or null when its name matches none. It is derived from `name` and `unit`, never
+        chosen: it is set on create and re-derived (or cleared) when an update changes either. A reading in another unit
+        is converted only for a marker that has one. `hidden` drops the marker from the active catalog list and the
+        lab-entry pickers without deleting it (its readings and unit/range survive). A `LabResult` linking this marker
+        resolves its unit + reference bounds from here."
     CreateBiomarkerResponse:
       type: object
       properties: