@pablotech/akesi 0.1.22

package/finding-regroup.ts

@@ -0,0 +1,167 @@
+// The treatmentGroups finding node, extracted so a host web endpoint and a host
+// CLI leaf-regen can regenerate just this leaf without the ~$5 monolithic call. This is the
+// single source of truth for the prompt, the tool schema, the validator, and the id→text resolver.
+//
+// Two structural robustness fixes land here, where the node is small enough for both to
+// be practical (the monolith's combined schema outgrew the grammar ceiling):
+//   #1 id-refs — every input carries a short stable id (S#/P#/A#/AI#); the model references the id,
+//      never the free text, so the "ref must match a presented string exactly" failure class is gone.
+//   #3 tool-schema — the output is emitted through a JSON-schema tool call, not hand-rolled JSON in a
+//      text block, so escaping/format failures largely disappear.
+// Isomorphic: no node:/SDK imports, so both a Pages Function and the browser can build inputs, validate,
+// and resolve. The Anthropic call itself lives in each caller (Function / CLI), which supply prompt+tool.
+
+import type { Client, TreatmentGroup } from "./types";
+import { treatmentsOf } from "./treatment-normalize";
+import { bucketOf, treatmentLabel, todayISODate } from "./treatment-bucket";
+
+export interface RegroupItem {
+  id: string;
+  text: string;
+  purpose?: string;
+}
+export interface RegroupInputs {
+  systems: { id: string; name: string }[]; // S# — disease[].group, in order
+  patientHypotheses: RegroupItem[]; // P# — factors.decisions
+  planActions: RegroupItem[]; // A# — planned (future-dated) treatments
+  aiInterventions: RegroupItem[]; // AI# — finding.decisions.ai
+}
+
+// id-ref'd group as the model emits it (before resolving ids back to text).
+export interface GroupRef {
+  system: string; // an S# id
+  topic: string;
+  patient: string[]; // P#/A# ids
+  ai: string[]; // AI# ids
+}
+export interface RegroupResponse {
+  groups: GroupRef[];
+}
+
+export function buildRegroupInputs(client: Client): RegroupInputs {
+  const today = todayISODate();
+  return {
+    systems: (client.finding?.disease ?? []).map((d, i) => ({ id: `S${i + 1}`, name: d.group.trim() })),
+    patientHypotheses: (client.factors?.decisions ?? []).map((d, i) => ({ id: `P${i + 1}`, text: d.intervention.trim(), purpose: d.purpose })),
+    planActions: treatmentsOf(client)
+      .filter((t) => bucketOf(t, today) === "planned")
+      .map((t, i) => ({ id: `A${i + 1}`, text: treatmentLabel(t) })),
+    aiInterventions: (client.finding?.decisions?.ai ?? []).map((d, i) => ({ id: `AI${i + 1}`, text: d.intervention.trim(), purpose: d.purpose })),
+  };
+}
+
+export const REGROUP_SYSTEM_PROMPT =
+  "You partition a patient's proposed treatments into clinically-coherent clusters — the patient's " +
+  "view beside the AI's — so a doctor can see where they agree, differ, or have no counterpart. You " +
+  "reference every item by its short id (S#/P#/A#/AI#), never by copying its text. Emit the result " +
+  "ONLY through the emit_treatment_groups tool.";
+
+export function regroupUserPrompt(inputs: RegroupInputs): string {
+  const sec: string[] = [];
+  sec.push("Body systems (reference by id; a group's `system` is exactly one of these ids), in order:");
+  for (const s of inputs.systems) sec.push(`  ${s.id}: ${s.name}`);
+  sec.push("Patient hypotheses — interventions the patient is weighing (reference in `patient` by id):");
+  for (const p of inputs.patientHypotheses) sec.push(`  ${p.id}: ${p.text}${p.purpose ? ` — ${p.purpose}` : ""}`);
+  sec.push("Patient Plan actions — committed steps (reference in `patient` by id; ignore any timing):");
+  for (const a of inputs.planActions) sec.push(`  ${a.id}: ${a.text}`);
+  sec.push("AI interventions — the AI's proposed set (reference in `ai` by id):");
+  for (const ai of inputs.aiInterventions) sec.push(`  ${ai.id}: ${ai.text}${ai.purpose ? ` — ${ai.purpose}` : ""}`);
+  sec.push(
+    [
+      "Rules:",
+      "- Each group is { system, topic, patient, ai }: an S# id, a drug-class label, patient ids on the",
+      "  left, ai ids on the right.",
+      "- topic is the DRUG CLASS (≤6 words: \"Lipid-lowering\", \"ARB\", \"GLP-1 / incretin\", \"Androgen",
+      "  support\", \"Methyl donors\"), NOT a hoped-for benefit. Cluster items sharing a class together;",
+      "  never split a class across groups by benefit.",
+      "- HARD COVERAGE: every P#, every A#, and every AI# appears in EXACTLY ONE group. Never invent an id.",
+      "  Many-to-many is fine — a patient item may sit with several ai items and vice versa. Fold a",
+      "  \"Continue X\" plan action into the group of the therapy it continues.",
+      "- system is the body system the therapy primarily acts on.",
+      "- ORDER groups by their system id in the order listed above; all groups sharing a system MUST be",
+      "  contiguous. A group may be patient-only (empty ai) or ai-only (empty patient), but not both empty.",
+    ].join("\n"),
+  );
+  return sec.join("\n\n");
+}
+
+export const TREATMENT_GROUPS_TOOL = {
+  name: "emit_treatment_groups",
+  description: "Emit the partition of proposed treatments into system/drug-class clusters, referencing every item by its id.",
+  input_schema: {
+    type: "object" as const,
+    properties: {
+      groups: {
+        type: "array",
+        description: "The clusters, ordered by system id, systems contiguous.",
+        items: {
+          type: "object",
+          properties: {
+            system: { type: "string", description: "a body-system id (S1, S2, …)" },
+            topic: { type: "string", description: "the drug-class label (≤6 words)" },
+            patient: { type: "array", items: { type: "string" }, description: "patient item ids (P#/A#); may be empty" },
+            ai: { type: "array", items: { type: "string" }, description: "AI intervention ids (AI#); may be empty" },
+          },
+          required: ["system", "topic", "patient", "ai"],
+        },
+      },
+    },
+    required: ["groups"],
+  },
+};
+
+// Id-based coverage / order / contiguity checks — the verbatim-match logic from the monolith
+// (claude-finding.ts) ported to ids, so nothing depends on the model echoing free text exactly.
+export function validateRegroup(resp: unknown, inputs: RegroupInputs): void {
+  const r = resp as RegroupResponse;
+  if (!r || !Array.isArray(r.groups)) throw new Error("groups missing or not an array");
+
+  const systemOrder = inputs.systems.map((s) => s.id);
+  const patientIds = new Set([...inputs.patientHypotheses, ...inputs.planActions].map((x) => x.id));
+  const aiIds = new Set(inputs.aiInterventions.map((x) => x.id));
+  const seenPatient = new Set<string>();
+  const seenAi = new Set<string>();
+  let prevSysIdx = -1;
+  const systemsSeen = new Set<string>();
+
+  for (const [i, g] of r.groups.entries()) {
+    if (!g || typeof g.topic !== "string" || g.topic.trim().length === 0) throw new Error(`groups[${i}].topic missing`);
+    if (typeof g.system !== "string") throw new Error(`groups[${i}] (${g.topic}) system missing`);
+    const sysIdx = systemOrder.indexOf(g.system);
+    if (sysIdx < 0) throw new Error(`groups[${i}] (${g.topic}) system "${g.system}" is not one of the system ids`);
+    if (sysIdx < prevSysIdx) throw new Error(`groups[${i}] (${g.topic}) system "${g.system}" is out of order`);
+    if (sysIdx !== prevSysIdx && systemsSeen.has(g.system)) {
+      throw new Error(`groups system "${g.system}" is not contiguous — all groups of a system must be adjacent`);
+    }
+    prevSysIdx = sysIdx;
+    systemsSeen.add(g.system);
+    if (!Array.isArray(g.patient) || !Array.isArray(g.ai)) throw new Error(`groups[${i}] (${g.topic}) patient and ai must be arrays`);
+    if (g.patient.length === 0 && g.ai.length === 0) throw new Error(`groups[${i}] (${g.topic}) has neither patient nor ai items`);
+    for (const ref of g.ai) {
+      if (!aiIds.has(ref)) throw new Error(`groups[${i}] (${g.topic}) ai ref "${ref}" is not an AI# id`);
+      if (seenAi.has(ref)) throw new Error(`ai ref "${ref}" appears in more than one group`);
+      seenAi.add(ref);
+    }
+    for (const ref of g.patient) {
+      if (!patientIds.has(ref)) throw new Error(`groups[${i}] (${g.topic}) patient ref "${ref}" is not a P#/A# id`);
+      if (seenPatient.has(ref)) throw new Error(`patient ref "${ref}" appears in more than one group`);
+      seenPatient.add(ref);
+    }
+  }
+  for (const id of aiIds) if (!seenAi.has(id)) throw new Error(`AI intervention ${id} is not placed in any group`);
+  for (const id of patientIds) if (!seenPatient.has(id)) throw new Error(`patient item ${id} is not placed in any group`);
+}
+
+// Resolve id-refs back to the stored TreatmentGroup[] shape (verbatim text), which the render-side
+// resolver (treatment-groups.ts) and FutureTreatment already consume. Assumes validateRegroup passed.
+export function resolveRegroup(resp: RegroupResponse, inputs: RegroupInputs): TreatmentGroup[] {
+  const sysName = new Map(inputs.systems.map((s) => [s.id, s.name]));
+  const patientText = new Map([...inputs.patientHypotheses, ...inputs.planActions].map((x) => [x.id, x.text]));
+  const aiText = new Map(inputs.aiInterventions.map((x) => [x.id, x.text]));
+  return resp.groups.map((g) => ({
+    system: sysName.get(g.system) ?? g.system,
+    topic: g.topic.trim(),
+    patient: g.patient.map((id) => patientText.get(id) ?? id),
+    ai: g.ai.map((id) => aiText.get(id) ?? id),
+  }));
+}

package/imaging-catalog.ts

@@ -0,0 +1,108 @@
+// Canonical names for imaging-derived markers. LLM extraction (claude-report.ts)
+// names the same metric inconsistently across runs/reports ("LVEF" vs "LV
+// Ejection Fraction (Biplane Simpson)"), and because marker name is the de-facto
+// primary key (ranges, dedup, trends), that drift fragments a metric into
+// separate series. This is the imaging analogue of the STABLE names the
+// deterministic blood/DEXA parsers emit by construction.
+//
+// canonicalImagingMarker() maps a raw extracted name to its canonical form:
+// pure case/whitespace/punctuation variants of a canonical name collapse
+// automatically; genuinely different phrasings are listed in ALIASES. Unknown
+// names pass through unchanged (the alias map is the knob — extend it as new
+// metrics appear).
+
+export const CANONICAL_IMAGING_MARKERS: string[] = [
+  // Cardiac CT
+  "Coronary artery calcium (CAC) score",
+  "CAC score — left main",
+  "CAC score — left anterior descending",
+  "CAC score — circumflex",
+  "CAC score — right coronary artery",
+  // Echocardiogram
+  "Left ventricular ejection fraction (LVEF)",
+  "Left ventricular end-diastolic volume",
+  "Left ventricular end-systolic volume",
+  "TAPSE",
+  "Aortic root diameter",
+  "Ascending aorta diameter",
+  "Left atrial volume (A4C)",
+  "Right atrial volume (A4C)",
+  "E/A ratio",
+  "E/e′ average",
+  "e′ average",
+  "Left ventricular mass",
+  "LVOT stroke-volume index",
+  "Left atrial volume index",
+  "Right atrial volume index",
+  "IVC diameter",
+  "Aortic valve area",
+  "Aortic valve area index",
+  "Aortic valve max velocity",
+  "Aortic valve peak gradient",
+  "Aortic valve mean gradient",
+  // Renal / abdominal ultrasound
+  "Right kidney length",
+  "Left kidney length",
+  "Right renal cortical thickness",
+  "Left renal cortical thickness",
+  "Pre-void bladder volume",
+  "Post-void residual volume",
+  "Prostate volume",
+  "Common bile duct diameter",
+];
+
+// Variant phrasing → canonical. Keys are matched after normalization, so only
+// genuinely different wording needs an entry (not mere case/spacing/dash diffs).
+const ALIASES: Record<string, string> = {
+  "lv ejection fraction biplane simpson": "Left ventricular ejection fraction (LVEF)",
+  "lv ejection fraction biplane simpson s": "Left ventricular ejection fraction (LVEF)",
+  "left ventricular ejection fraction biplane simpson": "Left ventricular ejection fraction (LVEF)",
+  "lvef": "Left ventricular ejection fraction (LVEF)",
+  "lv end diastolic volume biplane": "Left ventricular end-diastolic volume",
+  "lv end systolic volume biplane": "Left ventricular end-systolic volume",
+  "lad cac score": "CAC score — left anterior descending",
+  "mid ascending aorta diameter": "Ascending aorta diameter",
+  "right kidney size": "Right kidney length",
+  "left kidney size": "Left kidney length",
+  "post void residual": "Post-void residual volume",
+  "post void residual bladder volume": "Post-void residual volume",
+  "ava": "Aortic valve area",
+  "avai": "Aortic valve area index",
+  "ava index": "Aortic valve area index",
+  "aortic valve area indexed": "Aortic valve area index",
+  "peak gradient": "Aortic valve peak gradient",
+  "aortic valve peak instantaneous gradient": "Aortic valve peak gradient",
+  "e e prime average": "E/e′ average",
+  "e e prime": "E/e′ average",
+  "e e ratio": "E/e′ average",
+  "e prime average": "e′ average",
+  "lv mass": "Left ventricular mass",
+  "lvot svi": "LVOT stroke-volume index",
+  "lvot stroke volume index si": "LVOT stroke-volume index",
+  "stroke volume index": "LVOT stroke-volume index",
+  "la volume index": "Left atrial volume index",
+  "lavi": "Left atrial volume index",
+  "left atrial volume index biplane": "Left atrial volume index",
+  "ra volume index": "Right atrial volume index",
+  "ravi": "Right atrial volume index",
+};
+
+function normalize(s: string): string {
+  return s.toLowerCase().replace(/[^a-z0-9]+/g, " ").trim();
+}
+
+// normalized canonical form → canonical display name (auto-handles case/space/dash variants)
+const CANON_BY_NORM = new Map<string, string>(CANONICAL_IMAGING_MARKERS.map((c) => [normalize(c), c]));
+
+export function canonicalImagingMarker(name: string): string {
+  const key = normalize(name);
+  return ALIASES[key] ?? CANON_BY_NORM.get(key) ?? name.trim();
+}
+
+// Whether `name` is in the catalog (an alias or a canonical form) vs passed
+// through verbatim. Drives the ingest-time "uncataloged marker" report so
+// divergent names surface for cataloging instead of silently splitting a series.
+export function isKnownImagingMarker(name: string): boolean {
+  const key = normalize(name);
+  return key in ALIASES || CANON_BY_NORM.has(key);
+}

package/index.ts

@@ -0,0 +1,4 @@
+// The isomorphic core: safe to import from a browser bundle, a Cloudflare Pages Function, or a
+// node:crypto-based CLI alike. Runtime-specific pieces (pdfjs-dist) live in ./pdf-node instead —
+// import that directly rather than adding a node-specific dependency here.
+export {};

package/ingest-core.ts

@@ -0,0 +1,115 @@
+// The PURE ingest core: fold + parse + provenance, with no Node/fs/process
+// dependency, so both a CLI and a browser/serverless ingest path reuse the exact same logic. The
+// non-pure edges stay outside, in host-side modules:
+//   - reading bytes / copying files / writing artifacts  → a host CLI (node:fs)
+//   - content hashing (hashSource)                        → a host module (node:crypto;
+//                                                            a browser supplies SubtleCrypto)
+//   - the report LLM extraction (proposeFromReport)       → a host module (injected)
+// This module takes BYTES + already-extracted data and mutates an in-memory Client.
+
+import type { Client, SourceRecord } from "./types";
+
+// The lab/dexa/scale byte parser (parseRawFile) lives in ./parse-raw so this module
+// stays parser-free — parseDexa pulls in pdfjs-dist, which a browser fold path must not bundle.
+
+// ── Content hash, WebCrypto twin of the Node hash a server-side caller uses. Same sha256 hex +
+// 12-char id, so a Node import and a browser upload dedup identically. ──
+export async function hashSourceWeb(bytes: Uint8Array): Promise<{ sha256: string; id: string }> {
+  const buf =
+    bytes.byteOffset === 0 && bytes.byteLength === bytes.buffer.byteLength
+      ? (bytes.buffer as ArrayBuffer)
+      : (bytes.slice().buffer as ArrayBuffer);
+  const digest = new Uint8Array(await (globalThis.crypto as Crypto).subtle.digest("SHA-256", buf));
+  let sha256 = "";
+  for (const b of digest) sha256 += b.toString(16).padStart(2, "0");
+  return { sha256, id: sha256.slice(0, 12) };
+}
+
+// ── Fold: merge parsed rows / a report extraction into an in-memory Client. Pure. ──
+export { applySourceReadings, applyReportContribution, pruneOrphanImagingMarkers } from "./report-merge";
+
+// ── Removal: cascade-delete one source + its derived data, with corroboration + a tombstone.
+// The provenance check (provenanceIssues) backs vault:verify. Pure. ──
+export { removeSource, provenanceIssues, processedSha8 } from "./report-merge";
+export type { RemoveResult, ProvenanceIssue } from "./report-merge";
+
+// ── Provenance: stored-name formatting + the SourceRecord registry. Pure. ──
+
+const MONTHS = [
+  "January", "February", "March", "April", "May", "June",
+  "July", "August", "September", "October", "November", "December",
+];
+
+// "2026-05-19" → "2026May19"
+export function formatDate(d: string): string {
+  const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(d.trim());
+  if (!m) return d.trim().replace(/[^a-zA-Z0-9]+/g, "") || "undated";
+  return `${m[1]}${MONTHS[+m[2] - 1]}${m[3]}`;
+}
+
+// One date → "2026May19"; a span → "2025Sep02-2026May19".
+export function dateSegment(dates: string[]): string {
+  const valid = dates.filter((d) => /^\d{4}-\d{2}-\d{2}$/.test(d)).sort();
+  if (valid.length === 0) return "undated";
+  const lo = formatDate(valid[0]);
+  const hi = formatDate(valid[valid.length - 1]);
+  return lo === hi ? lo : `${lo}-${hi}`;
+}
+
+const TYPE_BY_KIND: Record<SourceRecord["kind"], string> = {
+  lab: "blood", dexa: "dexa", scale: "scale", imaging: "imaging",
+};
+export function typeForKind(kind: SourceRecord["kind"]): string {
+  return TYPE_BY_KIND[kind];
+}
+
+// Words that describe the modality, not the region — dropped so the subtype is
+// the body region (the user's example: "Renal Ultrasound" → "renal").
+const MODALITY_WORDS = new Set([
+  "ultrasound", "us", "ct", "cta", "mri", "mr", "scan", "xray", "x", "ray",
+  "angiogram", "angiography", "limited", "with", "without", "wo", "w", "contrast", "and", "the", "of",
+]);
+const STUDY_SLUG_OVERRIDES: Record<string, string> = {
+  "transthoracic echocardiogram": "echo",
+  "echocardiogram": "echo",
+};
+export function slugStudyType(studyType: string): string {
+  const norm = studyType.toLowerCase().trim();
+  if (STUDY_SLUG_OVERRIDES[norm]) return STUDY_SLUG_OVERRIDES[norm];
+  const words = norm.replace(/[^a-z0-9 ]+/g, " ").split(/\s+/).filter(Boolean);
+  return words.find((w) => !MODALITY_WORDS.has(w)) ?? words[0] ?? "study";
+}
+
+export function subtypeFor(kind: SourceRecord["kind"], studyType?: string): string {
+  if (kind === "imaging") return studyType ? slugStudyType(studyType) : "study";
+  return kind === "lab" ? "panel" : kind === "dexa" ? "bodycomp" : "inbody";
+}
+
+// <dateSeg>-<type>-<subtype>-<sha8>.<ext>, e.g. 2021October15-imaging-coronary-13da11c4.pdf
+export function storedName(opts: {
+  sha256: string;
+  kind: SourceRecord["kind"];
+  subtype: string;
+  dates: string[];
+  ext: string;
+}): string {
+  const subtype = opts.subtype.replace(/[^a-zA-Z0-9]+/g, "-").replace(/^-|-$/g, "").toLowerCase() || "x";
+  return `${dateSegment(opts.dates)}-${typeForKind(opts.kind)}-${subtype}-${opts.sha256.slice(0, 8)}${opts.ext}`;
+}
+
+export function findSourceBySha(client: Client, sha256: string): SourceRecord | undefined {
+  return client.sources?.find((s) => s.sha256 === sha256);
+}
+
+export function upsertSourceRecord(client: Client, rec: SourceRecord): void {
+  client.sources ??= [];
+  const i = client.sources.findIndex((s) => s.id === rec.id);
+  if (i >= 0) client.sources[i] = rec;
+  else client.sources.push(rec);
+  // Re-ingesting a previously-removed sha clears its tombstone: the source is
+  // live again, so leaving the tombstone would be a tombstone/live provenance collision.
+  if (client.removedSources?.length) {
+    client.removedSources = client.removedSources.filter((t) => t.sourceId !== rec.id);
+    if (client.removedSources.length === 0) delete client.removedSources;
+  }
+}

package/item-registry.ts

@@ -0,0 +1,69 @@
+// Pins for the items a finding GENERATES — questions, glossary terms, exploration items, analysis
+// passages — none of which has a source record to hang a pin on.
+//
+// Every other pinnable thing in a host app is a row the user typed: a note, a study entry, a
+// treatment, an allergy. Those have ids, and a pin is just a boolean on the row. These four do not.
+// The next finding rewrites their lists wholesale, so an index is meaningless and an id would be
+// re-minted on every regeneration — a pin keyed either way would silently move to a different item
+// or vanish. The item's own TEXT is the only thing that survives, so that is the key.
+//
+// Matching is deliberately loose (case- and whitespace-insensitive): a regeneration that reflows
+// "Ferritin" to "ferritin " must keep the pin. A regeneration that says something genuinely
+// different SHOULD lose it — the pin was about that text.
+//
+// Records are minted lazily and deleted on unpin, so an unpinned item costs nothing and the
+// registry never accumulates rows for content that no longer exists.
+import type { Client, ItemRecord, ItemRecordKind } from "./types";
+
+const SEP = "::";
+
+/** The opaque id the sidebar carries on a row (SidebarLeafRow.itemId) for a generated item. */
+export function itemRecordId(kind: ItemRecordKind, label: string): string {
+  return `${kind}${SEP}${label.trim()}`;
+}
+
+export function itemKindOf(id: string): ItemRecordKind {
+  return id.slice(0, id.indexOf(SEP)) as ItemRecordKind;
+}
+
+export function itemLabelOf(id: string): string {
+  return id.slice(id.indexOf(SEP) + SEP.length);
+}
+
+
+function norm(s: string): string {
+  return s.trim().toLowerCase().replace(/\s+/g, " ");
+}
+
+function matches(r: ItemRecord, kind: ItemRecordKind, label: string): boolean {
+  return r.kind === kind && norm(r.label) === norm(label);
+}
+
+export function isItemPinned(client: Client, id: string): boolean {
+  const kind = itemKindOf(id);
+  const label = itemLabelOf(id);
+  return (client.itemRegistry ?? []).some((r) => r.pinned && matches(r, kind, label));
+}
+
+/** Appends a pinned record on the first pin, drops it again on unpin. */
+export function toggleItemPin(client: Client, id: string): Client {
+  const kind = itemKindOf(id);
+  const label = itemLabelOf(id);
+  const prior = client.itemRegistry ?? [];
+  const next = prior.some((r) => matches(r, kind, label))
+    ? prior.filter((r) => !matches(r, kind, label))
+    : [...prior, { kind, label, pinned: true } as ItemRecord];
+  // Absent rather than [] when nothing is pinned — an untouched client's vault stays byte-identical
+  // to what it was before this feature existed, and findingInputsCanonicalString omits the key.
+  return next.length ? { ...client, itemRegistry: next } : (({ itemRegistry: _drop, ...rest }) => rest as Client)(client);
+}
+
+/** Convenience read for the sidebar builders, which have the text rather than the id. */
+export function isPinnedItem(client: Client, kind: ItemRecordKind, label: string): boolean {
+  return isItemPinned(client, itemRecordId(kind, label));
+}
+
+/** Every pinned generated item, in registry order. */
+export function pinnedItems(client: Client): ItemRecord[] {
+  return (client.itemRegistry ?? []).filter((r) => r.pinned);
+}

package/marker-deltas.ts

@@ -0,0 +1,84 @@
+// Cross-study deltas (W2). The single source of truth for "what changed" — shared
+// by a host's chart/print surfaces and by the Finding prompt builder here, so the change
+// shown on screen and the change the model reasons over can never disagree.
+//
+// Grouping is by stored marker name, which is canonical post-W1c (imaging-catalog),
+// so a metric is one series. `fromComparison` rows (W1b) are real datapoints here; a
+// directly-measured reading at the same marker|date already won at ingest.
+
+import type { Client, MarkerResult } from "./types";
+import { normalizeSeries } from "./unit-systems";
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+export type Direction = "up" | "down" | "flat";
+
+export interface DeltaChange {
+  abs: number; // latest.value - reference.value, in the marker's stored unit
+  pct: number | null; // percent change vs the reference; null when reference value is 0
+  direction: Direction;
+  spanDays: number; // days from the reference reading to the latest
+}
+
+export interface MarkerDelta {
+  marker: string;
+  unit: string;
+  latest: MarkerResult;
+  prior: MarkerResult; // the reading immediately before latest
+  vsPrior: DeltaChange;
+  // The first reading and the change against it — present only when the baseline is a
+  // distinct datapoint from `prior` (≥3 readings or ≥2 distinct dates), so a two-point
+  // series doesn't report the same change twice.
+  baseline?: MarkerResult;
+  vsBaseline?: DeltaChange;
+}
+
+function change(latest: MarkerResult, ref: MarkerResult): DeltaChange {
+  const abs = latest.value - ref.value;
+  const pct = ref.value !== 0 ? (abs / Math.abs(ref.value)) * 100 : null;
+  const direction: Direction = abs > 0 ? "up" : abs < 0 ? "down" : "flat";
+  const spanDays = Math.round(
+    (new Date(latest.date).getTime() - new Date(ref.date).getTime()) / DAY_MS,
+  );
+  return { abs, pct, direction, spanDays };
+}
+
+// Delta for one marker's readings. `rows` need not be pre-sorted. Returns null when
+// fewer than two readings exist (no change to report).
+export function deltaForSeries(rows: MarkerResult[]): MarkerDelta | null {
+  if (rows.length < 2) return null;
+  // A mixed-unit series (e.g. an xls with both mg/dL and mmol/L) is reconciled to one
+  // canonical unit so the subtraction is like-for-like; a single-unit series is untouched.
+  const sorted = [...normalizeSeries(rows)].sort((a, b) => a.date.localeCompare(b.date));
+  const latest = sorted[sorted.length - 1];
+  const prior = sorted[sorted.length - 2];
+  const baseline = sorted[0];
+  const out: MarkerDelta = {
+    marker: latest.marker,
+    unit: latest.unit,
+    latest,
+    prior,
+    vsPrior: change(latest, prior),
+  };
+  if (baseline.date !== prior.date) {
+    out.baseline = baseline;
+    out.vsBaseline = change(latest, baseline);
+  }
+  return out;
+}
+
+// Per-marker deltas across the whole vault. One entry per marker with ≥2 readings,
+// sorted by marker name.
+export function markerDeltas(client: Client): MarkerDelta[] {
+  const byMarker = new Map<string, MarkerResult[]>();
+  for (const r of client.results) {
+    if (!byMarker.has(r.marker)) byMarker.set(r.marker, []);
+    byMarker.get(r.marker)!.push(r);
+  }
+  const out: MarkerDelta[] = [];
+  for (const rows of byMarker.values()) {
+    const d = deltaForSeries(rows);
+    if (d) out.push(d);
+  }
+  return out.sort((a, b) => a.marker.localeCompare(b.marker));
+}