feat(labs): refuse a biomarker unit change while readings are linked

Readers label every linked reading with the marker's unit, so changing
it relabelled stored numbers without converting them. PUT
/api/biomarkers/{id} now answers 422 biomarkers.unit.locked with
meta.readingCount when the unit differs and any reading (tombstoned
ones included) is linked. The marker editor says so under the unit
field.

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

@@ -143,6 +143,28 @@ export const PUT = apiHandler(
       }
     }
 
+    // A marker's unit labels every reading linked to it: readers resolve the
+    // unit from the marker, and the stored numbers are in the old unit. A
+    // change while readings exist would relabel history without converting a
+    // single value, so it is refused. Tombstoned readings count too, since an
+    // undo brings them back under the new label.
+    if (d.unit !== undefined && d.unit !== existing.unit) {
+      const readingCount = await prisma.labResult.count({
+        where: { userId: user.id, biomarkerId: id },
+      });
+      if (readingCount > 0) {
+        annotate({
+          action: { name: "labs.biomarker.update.unit-locked" },
+          meta: { biomarkerId: id, readingCount },
+        });
+        return apiError(
+          "The unit of a biomarker with readings cannot be changed",
+          422,
+          { errorCode: "biomarkers.unit.locked", readingCount },
+        );
+      }
+    }
+
     // Build `data` field-by-field. `undefined` → leave the column untouched;
     // an explicit `null` on `context` / `panel` / a bound clears it.
     const data: Record<string, unknown> = {};

src/components/labs/biomarker-form.tsx

@@ -70,6 +70,7 @@ export function BiomarkerForm({
 }: BiomarkerFormProps) {
   const { t } = useTranslations();
   const formId = useId();
+  const unitHintId = `${formId}-unit-hint`;
 
   const [name, setName] = useState(existing?.name ?? "");
   const [unit, setUnit] = useState(existing?.unit ?? "");
@@ -225,7 +226,16 @@ export function BiomarkerForm({
             placeholder={t("labs.biomarker.form.unitPlaceholder")}
             maxLength={40}
             required
+            aria-describedby={existing ? unitHintId : undefined}
           />
+          {existing ? (
+            // The server refuses a unit change while readings are linked:
+            // every reading is shown in the marker's unit, so a new unit
+            // would relabel stored numbers without converting them.
+            <p id={unitHintId} className="text-muted-foreground text-xs">
+              {t("labs.biomarker.form.unitLockedHint")}
+            </p>
+          ) : null}
         </div>
         <div className="space-y-1.5">
           <Label htmlFor="biomarker-panel">

src/lib/openapi/error-codes.ts

@@ -76,6 +76,7 @@ export const ERROR_CODE_CATALOGUE: Readonly<Record<string, readonly string[]>> =
       "backup.section.missing",
       "backup.upload.too_large",
     ],
+    biomarkers: ["biomarkers.unit.locked"],
     "body-site": ["body-site.invalid"],
     coach: [
       "coach.budget.exceeded",

src/lib/openapi/routes/biomarkers.ts

@@ -155,7 +155,7 @@ export const biomarkerPaths: NonNullable<ZodOpenApiObject["paths"]> = {
       tags: ["Labs"],
       summary: "Edit a biomarker",
       description:
-        "Partial edit; omitted fields are untouched, an explicit null clears `context` / `panel` / a bound. Audits as `biomarker.update`.",
+        "Partial edit; omitted fields are untouched, an explicit null clears `context` / `panel` / a bound. Audits as `biomarker.update`. Since v1.40.0 a `unit` different from the stored one is refused with 422 `biomarkers.unit.locked` while any reading is linked to the marker (`meta.readingCount` carries how many): readers label every linked reading with the marker's unit, so a change would relabel stored numbers without converting them. Sending the current unit, or changing it on a marker with no readings, is accepted.",
       requestParams: { path: z.object({ id: z.string() }) },
       requestBody: {
         required: true,