feat(medications): shared helpers — readError + route-guards + dose-string + research-mode-types

Hoist five duplicated helpers into single source modules so each
contract evolves in exactly one place:

- src/lib/api/read-error.ts — replaces the four hand-rolled copies
  in the onboarding flow (Welcome / Goals / Source / Baseline).
- src/lib/medications/research-mode-types.ts — shared ResearchModeStatus
  DTO + tri-state gate helper consumed by both the DrugLevelChart
  and the Settings advanced section.
- src/lib/medications/route-guards.ts — assertMedicationOwnership
  for the eleven medication sub-routes, preserving the 404 leak
  shape across the privacy boundary.
- src/lib/medications/dose-string.ts — unified parseDoseMg + null
  variant replacing the DrugLevelChart and titration-route parsers.
- src/lib/medications/glp1-knowledge.ts — adds findDrugIdByBrand
  reverse lookup so the brand-to-id pattern stops being open-coded
  at every chart render.

28 new unit tests across the five helpers.

src/lib/api/__tests__/read-error.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it } from "vitest";
+
+import { readError } from "../read-error";
+
+function makeResponse(body: unknown, status: number, opts?: { invalidJson?: boolean }): Response {
+  if (opts?.invalidJson) {
+    return new Response("<<not json>>", {
+      status,
+      headers: { "content-type": "application/json" },
+    });
+  }
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+describe("readError", () => {
+  it("returns the server-supplied error string when present", async () => {
+    const res = makeResponse({ data: null, error: "Goal limit reached" }, 422);
+    expect(await readError(res)).toBe("Goal limit reached");
+  });
+
+  it("falls back to status-coded fallback when the envelope omits error", async () => {
+    const res = makeResponse({ data: null }, 500);
+    expect(await readError(res)).toBe("Request failed (500)");
+  });
+
+  it("falls back when the error field is empty", async () => {
+    const res = makeResponse({ data: null, error: "" }, 400);
+    expect(await readError(res)).toBe("Request failed (400)");
+  });
+
+  it("falls back when the JSON body fails to parse", async () => {
+    const res = makeResponse(null, 503, { invalidJson: true });
+    expect(await readError(res)).toBe("Request failed (503)");
+  });
+
+  it("falls back when the error field is the wrong type", async () => {
+    const res = makeResponse({ data: null, error: 42 }, 400);
+    expect(await readError(res)).toBe("Request failed (400)");
+  });
+
+  it("never throws even when the response body is empty", async () => {
+    const res = new Response(null, { status: 502 });
+    expect(await readError(res)).toBe("Request failed (502)");
+  });
+});

src/lib/api/read-error.ts

@@ -0,0 +1,27 @@
+/**
+ * v1.4.25 W21 Fix-N — shared client-side error reader.
+ *
+ * The four onboarding components (WelcomeCarousel, GoalsChipPicker,
+ * SourceCardGrid, BaselineForm) all hand-rolled the same helper to
+ * extract the `error` string from a non-OK `apiError` envelope, with an
+ * identical fall-through to `Request failed (<status>)`. Hoisting the
+ * helper keeps the four call sites honest — the envelope shape only
+ * needs to evolve once.
+ *
+ * Contract:
+ *   - The server-side `apiError` helper writes `{ data: null, error: "<msg>" }`.
+ *   - On parse failure (network error, non-JSON body, malformed shape)
+ *     fall back to a stable string the toast can surface.
+ *   - Never throw — the caller is already in a catch / setError path.
+ */
+export async function readError(res: Response): Promise<string> {
+  try {
+    const json = (await res.json()) as { error?: string };
+    if (typeof json.error === "string" && json.error.length > 0) {
+      return json.error;
+    }
+  } catch {
+    /* fall through */
+  }
+  return `Request failed (${res.status})`;
+}