feat(labs): keep the reference range a report prints beside a value

A lab runs its own method on its own device, so the window a physician
evaluates a value against is the one printed next to it on that report,
not a catalog band averaged over every lab. Reading a report pulled the
value and dropped that range: the extraction asked for it, the commit
handed it to the biomarker resolver, and the resolver only uses it when
it mints a NEW marker. For every analyte the user already had — the
normal case after a first panel — the printed range was read and then
thrown away.

Add `sourceReferenceLow` / `sourceReferenceHigh` / `sourceReferenceText`
to `LabResult` and carry the range from the report to the reading. The
text is stored whether or not numbers can be read out of it, because
"bis 5,0" and "negativ" state a window too; a range that could not be
parsed is kept verbatim, never replaced with invented bounds.

`resolveEffectiveReferenceRange` is the one place the precedence lives:
the source window wins for that single reading, and the catalog stays
the net for readings without one. A printed string with no derivable
bound does not displace the catalog. Every surface that judges a
reading routes through it — the API verdict, the doctor report, the
insights blocks and per-marker assessment, the coach snapshot, the MCP
read and the FHIR `referenceRange` — so a value cannot read in range on
one surface and out on another.

The API keeps `referenceLow` / `referenceHigh` as the window in force,
so a client that reads only those two renders the right range and the
right verdict with no change of its own; the catalog band, the source
window, its origin and a divergence flag ride alongside for clients
that want to show both.

Read side: the chart draws the source window as a second, visually
distinct band with the reading it came from named beneath it, the
reading rows name the printed range and the catalog band where the two
disagree, and the doctor-report PDF prints the report's own string with
a footnote naming the saved range. Entry side: one optional field on
the lab form, folded away until asked for, and the printed range is
editable on the scan review screen.

The range parser covers the notations German and English reports
actually print — two-sided, one-sided, comma or dot decimals, thousands
separators, trailing units — reads units without ever converting them,
and refuses to guess on anything ambiguous.

src/app/api/admin/backups/[id]/restore/route.ts

@@ -894,6 +894,9 @@ const handler = apiHandler(
                 unit: lab.unit,
                 referenceLow: lab.referenceLow ?? null,
                 referenceHigh: lab.referenceHigh ?? null,
+                sourceReferenceLow: lab.sourceReferenceLow ?? null,
+                sourceReferenceHigh: lab.sourceReferenceHigh ?? null,
+                sourceReferenceText: lab.sourceReferenceText ?? null,
                 takenAt: new Date(lab.takenAt),
                 source: lab.source,
                 noteEncrypted:

src/app/api/documents/inbound/[id]/facts/[factId]/route.ts

@@ -57,6 +57,7 @@ function editToFactData(edit: InboundFactEdit): FactData {
       unit: edit.unit ?? null,
       referenceLow: edit.referenceLow ?? null,
       referenceHigh: edit.referenceHigh ?? null,
+      referenceText: edit.referenceText ?? null,
       effectiveDate: edit.effectiveDate ?? null,
     };
     return data;

src/app/api/insights/labs-changes/route.ts

@@ -46,6 +46,9 @@ export const GET = apiHandler(async () => {
       value: true,
       referenceLow: true,
       referenceHigh: true,
+      sourceReferenceLow: true,
+      sourceReferenceHigh: true,
+      sourceReferenceText: true,
       takenAt: true,
     },
     orderBy: { takenAt: "desc" },
@@ -58,6 +61,9 @@ export const GET = apiHandler(async () => {
       value: r.value as number,
       referenceLow: r.referenceLow,
       referenceHigh: r.referenceHigh,
+      sourceReferenceLow: r.sourceReferenceLow,
+      sourceReferenceHigh: r.sourceReferenceHigh,
+      sourceReferenceText: r.sourceReferenceText,
       takenAt: r.takenAt,
     })),
   );

src/app/api/labs/[id]/route.ts

@@ -143,6 +143,12 @@ export const PUT = apiHandler(
     // historical columns the serialiser ignores. Reject the attempt with a
     // 422 rather than silently no-op, so the client never believes an edit
     // landed. Edit such fields on the Biomarker itself instead.
+    //
+    // `sourceReference*` is deliberately NOT on that list. The catalog band is
+    // a property of the marker; the source window is a property of THIS
+    // reading — it is what one report printed beside one value — so it is
+    // editable on a linked row and there is nothing on the biomarker to edit
+    // it on instead.
     const isLinked = existing.biomarkerId !== null;
     if (
       isLinked &&
@@ -194,6 +200,15 @@ export const PUT = apiHandler(
     if (d.unit !== undefined) data.unit = d.unit;
     if (d.referenceLow !== undefined) data.referenceLow = d.referenceLow;
     if (d.referenceHigh !== undefined) data.referenceHigh = d.referenceHigh;
+    if (d.sourceReferenceLow !== undefined) {
+      data.sourceReferenceLow = d.sourceReferenceLow;
+    }
+    if (d.sourceReferenceHigh !== undefined) {
+      data.sourceReferenceHigh = d.sourceReferenceHigh;
+    }
+    if (d.sourceReferenceText !== undefined) {
+      data.sourceReferenceText = d.sourceReferenceText;
+    }
     if (d.takenAt !== undefined) data.takenAt = d.takenAt;
 
     // Inverted-range guard for a PARTIAL bound update. The schema-level
@@ -212,6 +227,20 @@ export const PUT = apiHandler(
         errorCode: "labs.update.referenceRangeInvalid",
       });
     }
+    // The same partial-update hole exists on the source window, and closes the
+    // same way.
+    if (
+      isInvertedRange(
+        effectiveBound(d.sourceReferenceLow, existing.sourceReferenceLow),
+        effectiveBound(d.sourceReferenceHigh, existing.sourceReferenceHigh),
+      )
+    ) {
+      return apiError(
+        "sourceReferenceLow must not exceed sourceReferenceHigh",
+        422,
+        { errorCode: "labs.update.sourceReferenceRangeInvalid" },
+      );
+    }
     if (d.note !== undefined) {
       data.noteEncrypted = d.note ? encryptNoteToBytes(d.note) : null;
     }
@@ -239,6 +268,9 @@ export const PUT = apiHandler(
             panel: existing.panel,
             referenceLow: existing.referenceLow,
             referenceHigh: existing.referenceHigh,
+            sourceReferenceLow: existing.sourceReferenceLow,
+            sourceReferenceHigh: existing.sourceReferenceHigh,
+            sourceReferenceText: existing.sourceReferenceText,
             takenAt: existing.takenAt,
           },
           after: {
@@ -249,6 +281,9 @@ export const PUT = apiHandler(
             panel: updated.panel,
             referenceLow: updated.referenceLow,
             referenceHigh: updated.referenceHigh,
+            sourceReferenceLow: updated.sourceReferenceLow,
+            sourceReferenceHigh: updated.sourceReferenceHigh,
+            sourceReferenceText: updated.sourceReferenceText,
             takenAt: updated.takenAt,
           },
           redacted: d.note !== undefined ? ["note"] : [],

src/app/api/labs/ocr/commit/route.ts

@@ -33,6 +33,7 @@ import { withIdempotency } from "@/lib/idempotency";
 import { enqueueReminderSatisfy } from "@/lib/jobs/reminder-satisfy";
 import { emitDataArrival } from "@/lib/arrivals/emit-shared";
 import { resolveOrMintBiomarker } from "@/lib/labs/biomarker-store";
+import { parseReferenceRange } from "@/lib/labs/parse-reference-range";
 import { serialiseLabResult } from "@/lib/labs/serialise";
 import {
   linkOcrLabsToVaultDocument,
@@ -151,12 +152,19 @@ async function commitOcrRows(request: NextRequest) {
     }
 
     const isQualitative = row.valueText !== undefined;
+    // The window the scan read off the report. The confirmed numeric bounds
+    // win over a re-parse of the string (the human may have corrected them on
+    // the review screen); the string rides along either way.
+    const printed = parseReferenceRange(row.referenceText, row.unit);
+    const sourceLow = row.referenceLow ?? printed?.low ?? null;
+    const sourceHigh = row.referenceHigh ?? printed?.high ?? null;
+    const sourceText = printed?.text ?? null;
     const biomarker = await resolveOrMintBiomarker(user.id, {
       analyte: row.analyte,
       // A qualitative reading has no numeric unit / range.
       unit: isQualitative ? (row.unit ?? "") : (row.unit as string),
-      referenceLow: isQualitative ? null : (row.referenceLow ?? null),
-      referenceHigh: isQualitative ? null : (row.referenceHigh ?? null),
+      referenceLow: isQualitative ? null : sourceLow,
+      referenceHigh: isQualitative ? null : sourceHigh,
       panel: row.panel ?? null,
     });
 
@@ -173,6 +181,9 @@ async function commitOcrRows(request: NextRequest) {
         unit: biomarker.unit,
         referenceLow: biomarker.lowerBound,
         referenceHigh: biomarker.upperBound,
+        sourceReferenceLow: isQualitative ? null : sourceLow,
+        sourceReferenceHigh: isQualitative ? null : sourceHigh,
+        sourceReferenceText: isQualitative ? null : sourceText,
         takenAt: row.takenAt,
         source: "OCR",
         noteEncrypted: null,

src/app/api/labs/route.ts

@@ -184,6 +184,9 @@ async function postLabResult(request: NextRequest) {
     unit,
     referenceLow,
     referenceHigh,
+    sourceReferenceLow,
+    sourceReferenceHigh,
+    sourceReferenceText,
     takenAt,
     note,
     source,
@@ -248,6 +251,13 @@ async function postLabResult(request: NextRequest) {
       unit: biomarker.unit,
       referenceLow: biomarker.lowerBound,
       referenceHigh: biomarker.upperBound,
+      // The window this reading's own report printed, kept beside the catalog
+      // stamp rather than folded into it: it governs THIS reading's verdict,
+      // and the catalog band stays the net for every reading without one. A
+      // qualitative reading has no window to record.
+      sourceReferenceLow: isQualitative ? null : (sourceReferenceLow ?? null),
+      sourceReferenceHigh: isQualitative ? null : (sourceReferenceHigh ?? null),
+      sourceReferenceText: isQualitative ? null : (sourceReferenceText ?? null),
       takenAt,
       // v1.25 (iOS #36) — provenance: the on-device-OCR path posts
       // `source: "OCR"`; an omitted field stays "MANUAL" so the legacy
@@ -258,6 +268,7 @@ async function postLabResult(request: NextRequest) {
     },
   });
   invalidateUserHealthScore(user.id);
+  const dto = serialiseLabResult(created, biomarker);
 
   await auditLog("labResult.create", {
     userId: user.id,
@@ -275,6 +286,9 @@ async function postLabResult(request: NextRequest) {
       structured: biomarkerId !== undefined,
       // v1.25 (iOS #36) — provenance of the reading ("MANUAL" | "OCR").
       source: source ?? "MANUAL",
+      // Which window governs this reading's verdict, so a dashboard can see
+      // how often a report's own range displaces the catalog band.
+      referenceOrigin: dto.referenceOrigin,
     },
   });
 
@@ -298,5 +312,5 @@ async function postLabResult(request: NextRequest) {
     source: "manual",
   }).catch(() => {});
 
-  return apiSuccess(serialiseLabResult(created, biomarker), 201);
+  return apiSuccess(dto, 201);
 }