@pablotech/akesi 0.1.22

package/marker-groups-prompt.ts

@@ -0,0 +1,198 @@
+// Isomorphic marker->body-system prompt/schema + multi-pass convergence loop, so a Node caller
+// and a zero-knowledge web path can share one implementation. The actual model call stays with
+// each caller (an SDK singleton vs a runtime-bound key) — this module only builds requests and
+// reconciles responses, injected via `callModel`.
+import type { Client } from "./types";
+import { UNCATEGORIZED } from "./system-groups";
+
+export const GROUPS_SCHEMA = {
+  type: "object",
+  properties: {
+    groups: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          group: { type: "string" },
+          markers: { type: "array", items: { type: "string" } },
+        },
+        required: ["group", "markers"],
+        additionalProperties: false,
+      },
+    },
+  },
+  required: ["groups"],
+  additionalProperties: false,
+} as const;
+
+export interface GroupsAIResponse {
+  groups: { group: string; markers: string[] }[];
+}
+
+// The full marker universe to place: every distinct marker with data, plus any
+// watchlisted marker that has no reading yet (so it still gets a home).
+export function distinctMarkerNames(client: Client): string[] {
+  const names = new Set<string>();
+  for (const r of client.results) names.add(r.marker);
+  for (const m of client.watchlist) names.add(m);
+  return [...names].sort((a, b) => a.localeCompare(b));
+}
+
+// cyrb53 — a small, non-cryptographic, deterministic string hash (this is a cache/staleness
+// key, not a security boundary, so no need for node:crypto: that import isn't available in
+// the browser, and this module is isomorphic — shared by the client, the Workers Function, and
+// the Node ingest script). https://github.com/bryc/code/blob/master/jshash/experimental/cyrb53.js
+function cyrb53(str: string, seed = 0): number {
+  let h1 = 0xdeadbeef ^ seed;
+  let h2 = 0x41c6ce57 ^ seed;
+  for (let i = 0; i < str.length; i++) {
+    const ch = str.charCodeAt(i);
+    h1 = Math.imul(h1 ^ ch, 2654435761);
+    h2 = Math.imul(h2 ^ ch, 1597334677);
+  }
+  h1 = Math.imul(h1 ^ (h1 >>> 16), 2246822507) ^ Math.imul(h2 ^ (h2 >>> 13), 3266489909);
+  h2 = Math.imul(h2 ^ (h2 >>> 16), 2246822507) ^ Math.imul(h1 ^ (h1 >>> 13), 3266489909);
+  return 4294967296 * (2097151 & h2) + (h1 >>> 0);
+}
+
+// Hash over BOTH the marker set and the disease-group set: a new marker or a changed System
+// Analysis both invalidate the grouping.
+export function markerGroupsHashOf(markerNames: string[], systemGroups: string[]): string {
+  const a = [...markerNames].sort().join("\n");
+  const b = [...systemGroups].sort().join("\n");
+  return cyrb53(`${a}␞${b}`).toString(16).padStart(12, "0").slice(0, 12);
+}
+
+export const SYSTEM_PROMPT = [
+  "You assign a patient's lab/biometric markers to the patient's own body systems",
+  "(the AI Finding's disease areas), so each marker is read alongside the others",
+  "that speak to the same underlying system. This is cross-source: a marker may come",
+  "from bloodwork, a scan, or a body-composition scale — assign by what it MEANS",
+  "clinically, not by the panel or device it came from (e.g. an aortic-root diameter",
+  "and ApoB both belong to Cardiovascular Risk; Android % Fat belongs to Body",
+  "Composition).",
+  "",
+  "You are given the patient's BODY SYSTEMS. Assign EVERY marker to EXACTLY ONE of",
+  "them, using the system name VERBATIM — never rename, merge, abbreviate, or invent",
+  "a system. If a marker genuinely fits none of the listed systems, place it in a",
+  `group named exactly "${UNCATEGORIZED}". Reply with strict JSON matching the schema.`,
+  "",
+  "Rules:",
+  "- Output EVERY provided marker exactly once — none omitted, none invented, names",
+  "  verbatim. The total marker count across your groups MUST equal the number given.",
+  "- EVERY listed name is a DISTINCT marker you must place, even when it closely",
+  "  resembles another one. A free vs total, a percentage vs mass vs area, a ratio vs",
+  "  its components, a high-sensitivity vs standard assay, a per-segment vs whole-body",
+  "  measure are DIFFERENT markers — place ALL of them (e.g. Apolipoprotein B, Apo B :",
+  "  Apo A-1, and Apolipoprotein A-1 are three separate Cardiovascular markers; hsCRP",
+  "  and CRP are both Inflammation; Free testosterone and Testosterone are both",
+  "  Hormonal). NEVER drop a marker as redundant.",
+  "- Every group name MUST be one of the listed body systems verbatim, or the literal",
+  `  "${UNCATEGORIZED}". Do not create any other group name.`,
+  "- Put each marker in the SINGLE system where observing it next to its group-mates",
+  "  is most informative for this patient.",
+  "- Within a group, order markers from most to least central to the system.",
+].join("\n");
+
+export function contextBlock(client: Client, markers: string[], leftover: boolean): string {
+  const lines: string[] = [];
+  const valueByMarker = new Map<string, string>();
+  for (const r of [...client.results].sort((a, b) => a.date.localeCompare(b.date))) {
+    valueByMarker.set(r.marker, r.valueText ?? `${r.value} ${r.unit}`.trim());
+  }
+  const watch = new Set(client.watchlist);
+
+  lines.push("BODY SYSTEMS (assign every marker to one of these, verbatim):");
+  for (const d of client.finding?.disease ?? []) {
+    const gist = (d.finding ?? "").trim().split(/(?<=[.!?])\s+/)[0] ?? "";
+    lines.push(`  - ${d.group}${gist ? ` — ${gist}` : ""}`);
+  }
+
+  lines.push(
+    leftover
+      ? "\nThese markers were NOT assigned on the first pass. EVERY marker below belongs to" +
+        " one of the systems above — assign each to its SINGLE CLOSEST system. Every listed" +
+        " marker MUST appear under exactly one body system. Do NOT output a" +
+        ` "${UNCATEGORIZED}" group — it is not permitted in this response; if a marker seems` +
+        " to fit no system, choose the one it relates to most (every marker relates to some" +
+        " system — e.g. a red-cell index relates to the system its anemia/pathology bears on):"
+      : "\nMARKERS TO ASSIGN (place every one of these exactly once):",
+  );
+  for (const m of markers) {
+    const v = valueByMarker.get(m);
+    const w = watch.has(m) ? " [watchlist]" : "";
+    lines.push(`  - ${m}${w}${v ? ` (latest ${v})` : " (no data on file)"}`);
+  }
+
+  const studies = leftover ? [] : client.study?.entries ?? [];
+  if (studies.length > 0) {
+    lines.push("\nPURSUED STUDIES (assignment hints):");
+    for (const s of studies) lines.push(`  - ${s.focus}: ${s.detail}`);
+  }
+  return lines.join("\n");
+}
+
+// Reconcile the model's grouping against the real marker set and the allowed body
+// systems: keep only real markers, keep only verbatim-system group names (an
+// invented/renamed group has its markers swept), dedupe (first placement wins),
+// and sweep any unplaced marker into a trailing "Not yet categorized" group so
+// coverage is exactly-once and complete.
+export function reconcileGroups(
+  markerNames: string[],
+  systemGroups: string[],
+  raw: { group: string; markers: string[] }[],
+): { group: string; markers: string[] }[] {
+  const want = new Set(markerNames);
+  const allowed = new Set(systemGroups);
+  const placed = new Set<string>();
+  const out: { group: string; markers: string[] }[] = [];
+  for (const g of raw) {
+    const name = (g.group ?? "").trim();
+    if (name !== UNCATEGORIZED && !allowed.has(name)) continue; // reject non-verbatim systems
+    const markers = (g.markers ?? []).filter((m) => want.has(m) && !placed.has(m));
+    markers.forEach((m) => placed.add(m));
+    if (markers.length > 0) out.push({ group: name, markers });
+  }
+  const leftover = markerNames.filter((m) => !placed.has(m));
+  if (leftover.length > 0) {
+    const existing = out.find((g) => g.group === UNCATEGORIZED);
+    if (existing) existing.markers.push(...leftover);
+    else out.push({ group: UNCATEGORIZED, markers: leftover });
+  }
+  return out;
+}
+
+export type CallModel = (markers: string[], leftover: boolean) => Promise<{ group: string; markers: string[] }[]>;
+
+// The absorb/completeness-round loop: accumulate marker->system placements across passes
+// (first placement wins), then drive the residue to ZERO with up to 3 forced re-passes over
+// only the still-missing markers. Each caller supplies `callModel` — its own Anthropic-calling
+// glue (Node SDK vs Workers-bound key) — built from the shared SYSTEM_PROMPT/GROUPS_SCHEMA/
+// contextBlock above. Returns the final reconciled groups (including the trailing
+// UNCATEGORIZED bucket for any residue the reconcile safety-net still catches).
+export async function runMarkerGroupingPasses(
+  client: Client,
+  systems: string[],
+  callModel: CallModel,
+): Promise<{ group: string; markers: string[] }[]> {
+  const markerNames = distinctMarkerNames(client);
+  const place = new Map<string, string>();
+  const absorb = (subset: string[], groups: { group: string; markers: string[] }[]): void => {
+    for (const g of reconcileGroups(subset, systems, groups)) {
+      if (g.group === UNCATEGORIZED) continue;
+      for (const n of g.markers) if (!place.has(n)) place.set(n, g.group);
+    }
+  };
+
+  absorb(markerNames, await callModel(markerNames, false));
+  for (let round = 0; round < 3; round++) {
+    const missing = markerNames.filter((n) => !place.has(n));
+    if (missing.length === 0) break;
+    const before = place.size;
+    absorb(missing, await callModel(missing, true));
+    if (place.size === before) break;
+  }
+
+  const raw = systems.map((s) => ({ group: s, markers: markerNames.filter((n) => place.get(n) === s) }));
+  return reconcileGroups(markerNames, systems, raw);
+}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@pablotech/akesi",
+  "version": "0.1.22",
+  "description": "Schema-constrained clinical reasoning over lab and marker data, where every constraint stated to the model in prose is re-enforced in code on the response.",
+  "type": "module",
+  "main": "index.ts",
+  "types": "index.ts",
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "*.ts",
+    "benchmarks/**/*.ts",
+    "!tests"
+  ],
+  "exports": {
+    ".": "./index.ts",
+    "./types": "./types.ts",
+    "./treatment-normalize": "./treatment-normalize.ts",
+    "./treatment-bucket": "./treatment-bucket.ts",
+    "./treatment-product": "./treatment-product.ts",
+    "./treatment-timing-rules": "./treatment-timing-rules.ts",
+    "./marker-deltas": "./marker-deltas.ts",
+    "./unit-systems": "./unit-systems.ts",
+    "./dates": "./dates.ts",
+    "./ranges": "./ranges.ts",
+    "./ranges-prompt": "./ranges-prompt.ts",
+    "./item-registry": "./item-registry.ts",
+    "./report-title": "./report-title.ts",
+    "./imaging-catalog": "./imaging-catalog.ts",
+    "./system-groups": "./system-groups.ts",
+    "./factors-edit": "./factors-edit.ts",
+    "./report-extract": "./report-extract.ts",
+    "./report-merge": "./report-merge.ts",
+    "./document-model": "./document-model.ts",
+    "./document-read": "./document-read.ts",
+    "./ingest-core": "./ingest-core.ts",
+    "./pdf-node": "./parsers-report.ts",
+    "./marker-groups-prompt": "./marker-groups-prompt.ts",
+    "./treatment-infer": "./treatment-infer.ts",
+    "./finding-generate": "./finding-generate.ts",
+    "./finding-assemble": "./finding-assemble.ts",
+    "./finding-regroup": "./finding-regroup.ts",
+    "./pinned-queries": "./pinned-queries.ts",
+    "./section-labels": "./section-labels.ts",
+    "./benchmarks/retry-corrections": "./benchmarks/retry-corrections.ts"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "prompt:golden": "tsx tests/gen-prompt-golden.ts",
+    "bench:retry": "tsx benchmarks/retry-corrections.ts --preview"
+  },
+  "peerDependencies": {
+    "@anthropic-ai/sdk": "^0.88.0",
+    "pdfjs-dist": "^6.2.108"
+  },
+  "peerDependenciesMeta": {
+    "@anthropic-ai/sdk": {
+      "optional": true
+    },
+    "pdfjs-dist": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "tsx": "^4.22.3",
+    "vitest": "^4.1.8"
+  }
+}

package/parsers-report.ts

@@ -0,0 +1,21 @@
+import { getDocument } from "pdfjs-dist/legacy/build/pdf.mjs";
+
+// Flatten a narrative report PDF (e.g. an Epic MyChart "Test Details" radiology
+// report) to plain text. Unlike parseDexa, which keeps positional {str,x,y}
+// items to read a fixed table, here we just want the prose for an LLM to read.
+export async function extractReportText(bytes: Uint8Array): Promise<string> {
+  // isEvalSupported:false is a real pdfjs runtime option (disables eval), just missing from the
+  // legacy build's DocumentInitParameters typing — cast to the param type to keep it.
+  const pdf = await getDocument({ data: bytes, isEvalSupported: false } as Parameters<typeof getDocument>[0]).promise;
+  const pages: string[] = [];
+  for (let p = 1; p <= pdf.numPages; p++) {
+    const content = await (await pdf.getPage(p)).getTextContent();
+    const parts: string[] = [];
+    for (const it of content.items) {
+      if (!("str" in it)) continue;
+      parts.push(it.str as string);
+    }
+    pages.push(parts.join(" "));
+  }
+  return pages.join("\n\n").replace(/[ \t]+/g, " ").trim();
+}

package/pinned-queries.ts

@@ -0,0 +1,113 @@
+// Every pinned item in one client, as AREAS OF QUERY.
+//
+// This is the single place that answers "what has the user starred?", and it exists because that
+// answer is needed in three places that must not be allowed to disagree: the clinical prompt
+// (finding-generate.ts), the staleness hash (factors-hash.ts), and the UI notice that tells the
+// user their pins will steer the next Finding.
+//
+// WHAT A PIN MEANS — this is the load-bearing distinction in this file:
+//
+//   A pin says WHAT TO LOOK INTO. It never says what is true.
+//
+// A pinned question is not an answered question. A pinned glossary term is not a diagnosis. A
+// pinned report is not a summary of that report — the report's own extracted data reaches the model
+// through the ordinary evidence sections, and pinning it adds nothing to that evidence, only
+// emphasis on the topic. Nothing in this file is a clinical record, a finding, or a source of fact,
+// and the prompt block built from it says so in as many words.
+//
+// The stakes are concrete: a patient pinning "Could this be early kidney disease?" must never
+// cause the model to write as though early kidney disease were established. They asked a question.
+import type { Client } from "./types";
+import { reportTitleOf } from "./report-title";
+import { pinnedItems } from "./item-registry";
+import { SECTION_LABEL } from "./section-labels";
+
+export interface PinnedQuery {
+  /** The section it was pinned in, shown to the model as the area's context. */
+  section: string;
+  label: string;
+}
+
+const MAX_LABEL = 160;
+
+function clip(s: string): string {
+  const t = s.trim().replace(/\s+/g, " ");
+  return t.length > MAX_LABEL ? t.slice(0, MAX_LABEL) + "…" : t;
+}
+
+// A generated item's kind, as the section KEY it belongs to — the label itself comes from
+// section-labels' SECTION_LABEL, so this file cannot spell a section differently from the app.
+const GENERATED_SECTION_KEY: Record<string, string> = {
+  question: "docInference",
+  glossary: "definitions",
+  exploration: "exploration",
+  analysis: "analysis",
+  recommendedMarkers: "healthMarkers",
+};
+
+/**
+ * Every pinned item, in a stable section order.
+ *
+ * `client.watchlist` is deliberately NOT here. Watchlisted markers already reach the prompt as
+ * their own section and are already in the staleness hash; folding them in too would double them
+ * in the prompt and, worse, change the hash of every client who has ever watchlisted a marker —
+ * a mass regeneration bought for nothing.
+ */
+export function pinnedQueries(client: Client): PinnedQuery[] {
+  const f = client.factors ?? {};
+  const out: PinnedQuery[] = [];
+  const push = (section: string, label: string | undefined | null) => {
+    const t = label?.trim();
+    if (t) out.push({ section, label: clip(t) });
+  };
+
+  // M74 reversed, on the owner's instruction (2026-08-20): a ratio name used to be barred from the
+  // prompt outright. As an area of query it is safe and useful — "look at the TG/HDL ratio" is a
+  // topic, not a reading — and the block below is explicit that it is not data.
+  for (const name of client.pinnedRatios ?? []) push("Marker ratios", name);
+  const label = (key: string) => SECTION_LABEL[key] ?? key;
+  for (const s of client.sources ?? []) if (s.pinned) push(label("clinicalReports"), reportTitleOf(s));
+  for (const r of pinnedItems(client)) push(label(GENERATED_SECTION_KEY[r.kind] ?? r.kind), r.label);
+  for (const n of f.noteEntries ?? []) if (n.pinned) push(label("notes"), n.text);
+  for (const e of client.study?.entries ?? []) if (e.pinned) push(label("study"), e.focus);
+  for (const t of f.treatments ?? []) if (t.pinned) push(label("treatment"), t.name);
+  for (const d of f.decisions ?? []) if (d.pinned) push(label("futureTreatment"), d.intervention);
+  for (const a of f.allergies ?? []) if (a.pinned) push(label("allergies"), a.allergen);
+  for (const h of f.familyHistory ?? []) if (h.pinned) push(label("familyHistory"), h.relation);
+  return out;
+}
+
+/** Canonical, sorted, de-duplicated — the form the staleness hash uses. */
+export function pinnedQueryLines(client: Client): string[] {
+  return [...new Set(pinnedQueries(client).map((q) => `${q.section}|${q.label}`))].sort();
+}
+
+/**
+ * The prompt section, or null when nothing is pinned — the caller omits the section entirely rather
+ * than sending "Areas of query: (none)", which would be a sentence about nothing.
+ */
+export function pinnedQueryBlock(client: Client): string | null {
+  const items = pinnedQueries(client);
+  if (items.length === 0) return null;
+  const bySection = new Map<string, string[]>();
+  for (const q of items) bySection.set(q.section, [...(bySection.get(q.section) ?? []), q.label]);
+  const body = [...bySection]
+    .map(([section, labels]) => `  ${section}:\n` + labels.map((l) => `    - ${l}`).join("\n"))
+    .join("\n");
+  return (
+    `Areas of query (${items.length} item${items.length === 1 ? "" : "s"} the patient or their ` +
+    `provider has STARRED, asking you to look into them).\n\n` +
+    `READ THIS BEFORE USING THE LIST. These are questions, not answers:\n` +
+    `  • They tell you WHAT TO LOOK INTO. They never tell you what is true.\n` +
+    `  • They are NOT evidence, NOT clinical record, NOT data, and NOT a source you may cite. ` +
+    `Every fact you state must still come from the evidence sections above — the markers, ` +
+    `reports, treatments, study notes and profile.\n` +
+    `  • A starred question is an OPEN question. Never write as though it were settled. A starred ` +
+    `glossary term, report or topic means "this is on their mind", nothing more.\n` +
+    `  • If the evidence does not support saying anything about a starred area, say that plainly ` +
+    `rather than inventing a finding to fill it.\n` +
+    `  • Where the evidence DOES speak to a starred area, give it more of your attention and more ` +
+    `of your words than you otherwise would. That is the entire effect of a star.\n\n` +
+    body
+  );
+}

package/ranges-prompt.ts

@@ -0,0 +1,228 @@
+// The Node/process-free edge of Ranges generation, mirroring report-extract.ts's split: the
+// schema, prompt and validation live here, so a Node caller (which brings its own env-keyed
+// client) and an edge-runtime caller (which injects one) run the exact same logic.
+//
+// This module must never import the Finding inference graph. That is the whole point: a host
+// serving only Ranges can then keep that graph out of its bundle entirely.
+import { ageYears } from "./ranges";
+import type { Client, ClientFactors, MarkerResult } from "./types";
+import { treatmentsOf } from "./treatment-normalize";
+import { bucketOf, todayISODate } from "./treatment-bucket";
+
+export const RANGE_SCHEMA = {
+  type: "object",
+  properties: {
+    low: { type: ["number", "null"] },
+    high: { type: ["number", "null"] },
+    unit: { type: "string" },
+    meaning: { type: "string" },
+    explanation: { type: "string" },
+    explanationImperial: { type: ["string", "null"] },
+    generalLow: { type: ["number", "null"] },
+    generalHigh: { type: ["number", "null"] },
+    generalExplanation: { type: "string" },
+  },
+  required: ["low", "high", "unit", "meaning", "explanation", "explanationImperial", "generalLow", "generalHigh", "generalExplanation"],
+  additionalProperties: false,
+} as const;
+
+export interface RangeAIResponse {
+  low: number | null;
+  high: number | null;
+  unit: string;
+  meaning: string;
+  explanation: string;
+  explanationImperial: string | null;
+  generalLow: number | null;
+  generalHigh: number | null;
+  generalExplanation: string;
+}
+
+export const IMPERIAL_CONVERTS: Record<string, string> = {
+  kg: "lb",
+  g: "lb",
+  cm: "in",
+  "cm²": "in²",
+  "cm³": "in³",
+  "g/L": "mg/dL",
+};
+
+function describeFactors(client: Client): string {
+  const age = ageYears(client.dob);
+  const parts: string[] = [];
+  parts.push(`${age ?? "unknown age"}-year-old ${client.gender}`);
+  const f: ClientFactors = client.factors ?? {};
+  if (f.diseases && f.diseases.length > 0) {
+    const fmt = f.diseases.map((d) => `${d.diagnostic} (${d.date})`).join(", ");
+    parts.push(`prior diagnoses: ${fmt}`);
+  }
+  const today = todayISODate();
+  const ongoing = treatmentsOf(client).filter((t) => bucketOf(t, today) === "ongoing");
+  if (ongoing.length > 0) {
+    const fmt = ongoing
+      .map((t) => `${[t.name, t.dose].filter(Boolean).join(" ")}${t.start ? ` [${t.start}]` : ""}`.trim())
+      .join(", ");
+    parts.push(`current treatments: ${fmt}`);
+  }
+  if (f.pregnancy && f.pregnancy !== "none") parts.push(f.pregnancy);
+  if (f.athletic) parts.push(`${f.athletic} activity level`);
+  if (f.height) parts.push(`height ${f.height}`);
+  if (typeof f.bmi === "number") parts.push(`BMI ${f.bmi}`);
+  if (f.smoking) parts.push(`${f.smoking} smoker`);
+  if (f.ethnicity) parts.push(`ethnicity: ${f.ethnicity}`);
+  if (f.goal) parts.push(`personal health goal: ${f.goal}`);
+  if (f.focus) parts.push(`current clinical focus: ${f.focus}`);
+  return parts.join("; ");
+}
+
+export function systemPromptFor(client: Client): string {
+  return [
+    "You are advising on optimal/functional reference ranges for blood and body markers,",
+    "personalized to one specific patient. You will be given a marker name and the unit",
+    "in which results are reported. Reply with strict JSON matching the requested schema.",
+    "",
+    "Guidance:",
+    "- Use peer-reviewed medical literature. Prefer functional/optimal ranges over the broad",
+    "  lab 'normal' range when they meaningfully differ.",
+    "- The 'unit' field in your response MUST match the unit provided in the user message,",
+    "  with values scaled accordingly. Do not change units.",
+    "- When the same unit string appears across multiple assays with very different",
+    "  reference ranges (notably Free testosterone in pg/mL, Insulin, IGF-1 across",
+    "  ages, some hormones), use the patient's recent measured values shown in the",
+    "  user message to decide which assay produced them, and target a reference range",
+    "  from that same assay. The chosen low/high MUST be on the same scale as those",
+    "  measured values. If the patient's measurements lie entirely above or entirely",
+    "  below the range you're considering, you have picked the wrong assay scale.",
+    "- low and high are numbers in that unit, or null if the marker has only an upper or",
+    "  lower bound (e.g. 'less than 5 mg/L'). At least one of low/high must be a number.",
+    "- meaning is a short, patient-INDEPENDENT definition of what the marker is and what it",
+    "  reflects physiologically — one plain phrase, ~8-18 words, no numbers or ranges. It",
+    "  answers 'what is this marker?' for a layperson (e.g. \"ApoB counts the atherogenic",
+    "  particles that drive plaque; the core lipid causal to heart disease\"). Do NOT discuss",
+    "  this patient, their factors, or their target here — that is the explanation's job.",
+    "- explanation is the DISCUSSION of why the PERSONALIZED range is more relevant for",
+    "  THIS patient than the general range — 2-4 plain sentences (target 400-700",
+    "  characters, hard cap 900). Name the specific factors below that shift the",
+    "  personalized range and why they matter for this person. You MAY refer to \"the",
+    "  general range\" by name when you contrast, but do NOT re-quote its numbers — they",
+    "  are already shown on the separate 'General range' line, so e.g. \"tighter than the",
+    "  general range\" suffices. If no factor meaningfully shifts the range from the",
+    "  general one, say so plainly.",
+    "- generalLow / generalHigh: the GENERAL reference range for this marker based ONLY on",
+    "  the patient's age, gender, and height. EXPLICITLY IGNORE this patient's conditions,",
+    "  prior diagnoses, medications, supplements, stated goal, and clinical focus for these",
+    "  two fields — those shape ONLY the personalized low/high above. Same unit and scale as",
+    "  low/high (null where a side is unbounded; at least one must be a number). Use a",
+    "  standard population/clinical-guideline range, or a simple guideline formula where one",
+    "  is conventional (e.g. waist circumference target < half of height). This is the",
+    "  baseline a typical same-age, same-sex, same-height person would be measured against.",
+    "- generalExplanation: 1-2 plain sentences stating the general range and its age/gender/",
+    "  height basis (the guideline or population reference). Do NOT mention this patient's",
+    "  conditions, medications, supplements, or goals here.",
+    "- explanationImperial: if the lab unit is one of kg, g, cm, cm², cm³, g/L (i.e. has",
+    "  an American/imperial equivalent: lb, in, in², in³, mg/dL), provide the same 2-4",
+    "  sentence explanation but with every numeric mention converted to the imperial",
+    "  unit (and any reference-range parenthetical also in imperial). Otherwise (e.g.",
+    "  units like mg/dL, ng/mL, mmol/L, %, IU/L that don't convert), return null —",
+    "  the metric explanation will be reused for both unit systems.",
+    "- If the patient states a personal health goal (e.g. Health span, Longevity,",
+    "  Performance, Fertility, Weight loss), weight the range toward that goal: prefer",
+    "  tighter optimal ranges that maximize the stated outcome, and call out in the",
+    "  explanation how the goal influenced the bounds.",
+    "- If the patient states a current clinical focus (e.g. lower visceral fat,",
+    "  lower LDL/ApoB, raise HDL, improve insulin sensitivity), treat it as a more",
+    "  specific aim on top of the broader goal: tighten the range for markers",
+    "  directly relevant to that focus, and name the focus in the explanation when",
+    "  it shifts the bound. For markers unrelated to the focus, defer to the goal.",
+    "- Medications and supplements do NOT shift the personalized range. The range",
+    "  is the patient's goal-aligned target (e.g. healthspan-optimized ApoB), and",
+    "  is the same whether or not they take any medication or supplement. Do not",
+    "  'predict' the patient's level after treatment by tightening or loosening",
+    "  the range. The range is set by age, gender, conditions, goal, and the other",
+    "  factors below — never by what the patient is currently taking.",
+    "- However, the explanation should describe what level may be anticipated as",
+    "  a result of any relevant current medication or supplement, so the patient",
+    "  can judge whether their regimen is moving them toward the goal range. For",
+    "  example: 'tirzepatide can be expected to bring HbA1c toward ~5%';",
+    "  'ezetimibe typically lowers ApoB by ~20-25% from baseline'; 'glycine 3-15g",
+    "  can lower HbA1c by ~0.2-0.5 points and improve sleep-driven glucose control'.",
+    "  Be specific about anticipated direction and magnitude when relevant.",
+    "",
+    `Patient: ${describeFactors(client)}.`,
+  ].join("\n");
+}
+
+/** The unit a marker is measured in: the LATEST reading's, by date. `""` for a dimensionless ratio.
+ *  Whether a `""` here means "dimensionless" or "never ingested" is the host's call, not this
+ *  module's — see the caller's NoMeasuredUnitError. */
+export function unitForMarker(client: Client, marker: string): { unit: string; rows: MarkerResult[] } {
+  const rows = client.results
+    .filter((r) => r.marker === marker)
+    .sort((a, b) => a.date.localeCompare(b.date));
+  return { unit: rows.length > 0 ? rows[rows.length - 1].unit : "", rows };
+}
+
+/** The prompt's unit line — spelled out for a dimensionless ratio marker (unit "") so the model
+ *  can't read it as missing data. Named and exported so the benchmark's "after" arm scores this
+ *  exact shipped text rather than a hand-copied snapshot that could drift from it. */
+export function unitLineFor(unit: string): string {
+  return unit
+    ? `Unit: ${unit}`
+    : `Unit: (dimensionless ratio — this marker has no physical unit; return "" for the unit field)`;
+}
+
+/** The Ranges user message, the other half of the prompt `systemPromptFor` starts. Lives here for
+ *  the same reason the system prompt does: the CLI and the Function must never word it two
+ *  different ways, and a golden fixture can only cover text this package owns. */
+export function rangesUserMessage(client: Client, marker: string): string {
+  const { unit, rows } = unitForMarker(client, marker);
+  const recent = rows.slice(-5);
+  const measuredLine =
+    recent.length > 0
+      ? `Recent measured values for this patient (use these to disambiguate assay/unit scale when the same unit appears across assays with different reference ranges): ${recent.map((r) => `${r.date}: ${r.value}`).join(", ")}`
+      : `Recent measured values for this patient: (none on file)`;
+  const imperialUnit = IMPERIAL_CONVERTS[unit];
+  const imperialReminder = imperialUnit
+    ? `\nThis unit (${unit}) has an imperial equivalent (${imperialUnit}); explanationImperial is REQUIRED, not null — at least 20 chars converting every number to ${imperialUnit}.`
+    : "";
+  return `Marker: ${marker}\n${unitLineFor(unit)}${imperialReminder}\n${measuredLine}\n\nReturn the personalized reference range as JSON.`;
+}
+
+export function validate(marker: string, expectedUnit: string, r: RangeAIResponse): void {
+  if (r.low == null && r.high == null) {
+    throw new Error(`range for "${marker}" has neither low nor high`);
+  }
+  if (r.low != null && r.high != null && r.low >= r.high) {
+    throw new Error(`range for "${marker}" has low (${r.low}) >= high (${r.high})`);
+  }
+  if (expectedUnit !== "" && (!r.unit || r.unit.trim() === "")) {
+    throw new Error(`range for "${marker}" missing unit`);
+  }
+  if (normalizeUnit(r.unit) !== normalizeUnit(expectedUnit)) {
+    throw new Error(
+      `range for "${marker}" returned unit "${r.unit}" but lab data is in "${expectedUnit}"`,
+    );
+  }
+  if (!r.meaning || r.meaning.trim().length === 0) {
+    throw new Error(`range for "${marker}" missing meaning`);
+  }
+  if (!r.explanation || r.explanation.trim().length === 0) {
+    throw new Error(`range for "${marker}" missing explanation`);
+  }
+  if (IMPERIAL_CONVERTS[expectedUnit] && (!r.explanationImperial || r.explanationImperial.trim().length === 0)) {
+    throw new Error(`range for "${marker}" (unit ${expectedUnit}) missing imperial explanation`);
+  }
+  if (r.generalLow == null && r.generalHigh == null) {
+    throw new Error(`range for "${marker}" has neither generalLow nor generalHigh`);
+  }
+  if (r.generalLow != null && r.generalHigh != null && r.generalLow >= r.generalHigh) {
+    throw new Error(`range for "${marker}" has generalLow (${r.generalLow}) >= generalHigh (${r.generalHigh})`);
+  }
+  if (!r.generalExplanation || r.generalExplanation.trim().length === 0) {
+    throw new Error(`range for "${marker}" missing generalExplanation`);
+  }
+}
+
+function normalizeUnit(u: string): string {
+  return u.toLowerCase().replace(/\s+/g, "").replace(/μ/g, "u");
+}