@pablotech/akesi 0.1.22

package/treatment-normalize.ts

@@ -0,0 +1,91 @@
+import type {
+  Client,
+  ClientFactors,
+  LegacyFactors,
+  LegacyTreatmentItem,
+  TreatmentItem,
+  TreatmentKind,
+} from "./types";
+
+// Normalize free-text treatment dates to ISO `YYYY-MM` and fold pre-unification vaults
+// (medications / supplements / plan) into the single `treatments` array. Pure, and shared by a
+// one-time migration and the read-shim (treatmentsOf) alike, so both fold identically.
+
+const MONTHS: Record<string, string> = {
+  jan: "01", january: "01", feb: "02", february: "02", mar: "03", march: "03",
+  apr: "04", april: "04", may: "05", jun: "06", june: "06", jul: "07", july: "07",
+  aug: "08", august: "08", sep: "09", sept: "09", september: "09", oct: "10", october: "10",
+  nov: "11", november: "11", dec: "12", december: "12",
+};
+
+// A single date-ish token → YYYY-MM (or YYYY, or "" when there's no year to anchor it).
+function parseOne(raw: string, fallbackYear?: string): string {
+  const cleaned = raw.trim().toLowerCase().replace(/^since\s+/, "");
+  if (!cleaned) return "";
+  const iso = cleaned.match(/(\d{4})-(\d{1,2})(?:-\d{1,2})?/);
+  if (iso) return `${iso[1]}-${iso[2].padStart(2, "0")}`;
+  let month: string | undefined;
+  let year: string | undefined;
+  for (const tok of cleaned.split(/[\s,]+/).filter(Boolean)) {
+    if (MONTHS[tok]) month = MONTHS[tok];
+    else if (/^\d{4}$/.test(tok)) year = tok;
+  }
+  year ??= fallbackYear;
+  if (!year) return "";
+  return month ? `${year}-${month}` : year;
+}
+
+// Free-text date → { start, end? }. A closed window like "April–May 2026" (en/em dash — a hyphen
+// is left to ISO) becomes start+end; a bare month/year becomes start only; prose ("TBD", "when HRV
+// rises") yields an empty start.
+export function parseSince(raw: string): { start: string; end?: string } {
+  const s = (raw ?? "").trim();
+  if (!s) return { start: "" };
+  if (/^\d{4}(-\d{1,2}){0,2}$/.test(s)) return { start: parseOne(s) };
+  const range = s.match(/^(.+?)\s*[–—]\s*(.+)$/);
+  if (range) {
+    const end = parseOne(range[2]);
+    const start = parseOne(range[1], end.slice(0, 4) || undefined);
+    return end ? { start, end } : { start };
+  }
+  return { start: parseOne(s) };
+}
+
+export function normalizeDate(raw: string): string {
+  return parseSince(raw).start;
+}
+
+// Fold a (possibly legacy) factors object into the unified treatments array. Idempotent: if
+// `treatments` already exists it is returned untouched, so a migrated vault is a no-op.
+export function normalizeTreatments(factors: (ClientFactors & LegacyFactors) | undefined): TreatmentItem[] {
+  if (!factors) return [];
+  if (factors.treatments) return factors.treatments;
+  const out: TreatmentItem[] = [];
+  const fold = (items: LegacyTreatmentItem[] | undefined, kind: TreatmentKind) => {
+    for (const it of items ?? []) {
+      const name = (it.drug ?? "").trim();
+      if (!name) continue;
+      const { start, end } = parseSince(it.since ?? "");
+      const t: TreatmentItem = { id: crypto.randomUUID(), name, kind, start };
+      const dose = (it.dose ?? "").trim();
+      if (dose) t.dose = dose;
+      if (end) t.end = end;
+      out.push(t);
+    }
+  };
+  fold(factors.medications, "drug");
+  fold(factors.supplements, "supplement");
+  for (const p of factors.plan ?? []) {
+    const name = (p.action ?? "").trim();
+    if (!name) continue;
+    // Plan actions are free prose — keep the whole string as a behavior name (no lossy name/dose
+    // split); their prose date often won't parse, leaving start "". The migration CLI re-stamps
+    // such rows to a future month so they read as PLANNED.
+    out.push({ id: crypto.randomUUID(), name, kind: "behavior", start: normalizeDate(p.date ?? "") });
+  }
+  return out;
+}
+
+export function treatmentsOf(client: Client): TreatmentItem[] {
+  return normalizeTreatments(client.factors as (ClientFactors & LegacyFactors) | undefined);
+}

package/treatment-product.ts

@@ -0,0 +1,111 @@
+// The product side of a treatment — description, ingredients, links — as pure functions shared by
+// the browser form, the inference endpoint's validator, the staleness hash and the search index.
+//
+// Kept out of treatment-bucket.ts on purpose: that module owns dose and TIMING, and the one rule
+// this feature must never break is that a product's label amounts stay away from formatDose() /
+// treatmentLabel(). Different file, different concern, no import back the other way.
+
+import type { Administration, Ingredient, ProductLink, TreatmentItem } from "./types";
+
+/**
+ * A URL safe to store and render. http/https only — a `javascript:` or `data:` href reaching an
+ * anchor is a script-injection vector, and these URLs arrive from model output over pasted text,
+ * which is exactly the untrusted boundary worth validating at.
+ */
+export function safeProductUrl(raw: unknown): string | null {
+  if (typeof raw !== "string" || !raw.trim()) return null;
+  let parsed: URL;
+  try {
+    parsed = new URL(raw.trim());
+  } catch {
+    return null;
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return null;
+  return parsed.toString();
+}
+
+/** Drops anything unnamed or malformed rather than storing a half-record. */
+export function cleanIngredients(raw: unknown): Ingredient[] {
+  if (!Array.isArray(raw)) return [];
+  const out: Ingredient[] = [];
+  for (const item of raw) {
+    const i = item as Partial<Ingredient>;
+    const name = typeof i?.name === "string" ? i.name.trim() : "";
+    if (!name) continue;
+    const amount = typeof i.amount === "number" && Number.isFinite(i.amount) ? i.amount : undefined;
+    const unit = typeof i.unit === "string" && i.unit.trim() ? i.unit.trim() : undefined;
+    const form = typeof i.form === "string" && i.form.trim() ? i.form.trim() : undefined;
+    out.push({ name, ...(amount != null ? { amount } : {}), ...(unit ? { unit } : {}), ...(form ? { form } : {}) });
+  }
+  return out;
+}
+
+/** A link with no usable URL is dropped; a link with no label falls back to its own host. */
+export function cleanLinks(raw: unknown): ProductLink[] {
+  if (!Array.isArray(raw)) return [];
+  const out: ProductLink[] = [];
+  for (const item of raw) {
+    const l = item as Partial<ProductLink>;
+    const url = safeProductUrl(l?.url);
+    if (!url) continue;
+    const label = typeof l.label === "string" && l.label.trim() ? l.label.trim() : new URL(url).hostname;
+    out.push({ label, url });
+  }
+  return out;
+}
+
+/** "100mcg Selenium (L-Selenomethionine)" — display and prompt use the same rendering. */
+export function formatIngredient(i: Ingredient): string {
+  const amount = i.amount != null ? `${i.amount}${i.unit ?? ""} ` : "";
+  return `${amount}${i.name}${i.form ? ` (${i.form})` : ""}`;
+}
+
+export function hasProductData(
+  t: Pick<TreatmentItem, "description" | "maker" | "ingredients" | "links" | "administration">,
+): boolean {
+  return !!t.description?.trim() || !!t.maker?.trim() || !!t.ingredients?.length || !!t.links?.length || !!t.administration;
+}
+
+/**
+ * Whether a medicine-scope save is newly attaching `administration` for the first time, or
+ * changing its `unit` vs. what the medicine's rows already carry — the trigger for relabeling
+ * every sibling dose row's `doseUnit` to match. Same trimmed/lowercased comparison
+ * computeConclusion uses for its own unit-mismatch check, so "unchanged" here means it already
+ * agreed the units matched.
+ */
+export function administrationUnitChanged(
+  prevAdministration: Administration | undefined,
+  nextAdministration: Administration | undefined,
+): boolean {
+  if (!nextAdministration) return false;
+  if (!prevAdministration) return true;
+  return prevAdministration.unit.trim().toLowerCase() !== nextAdministration.unit.trim().toLowerCase();
+}
+
+/**
+ * The product half of a treatment's staleness signature, or "" when there is none.
+ *
+ * Returning "" — rather than a run of empty pipes — is what keeps this rollout free. treatmentCanonical
+ * builds one pipe-joined string per treatment, so appending unconditionally would change EVERY
+ * existing treatment's signature, mark all of them stale, and fire a full regeneration for every user
+ * on next load. Same reasoning as the allergy/family summaries in factors-hash.ts, which omit their
+ * key outright when empty instead of emitting [].
+ */
+export function productCanonical(
+  t: Pick<TreatmentItem, "description" | "maker" | "ingredients" | "links" | "administration">,
+): string {
+  if (!hasProductData(t)) return "";
+  const ingredients = (t.ingredients ?? []).map(formatIngredient).join(";");
+  const links = (t.links ?? []).map((l) => `${l.label}=${l.url}`).join(";");
+  // `maker` and `administration` are both appended ONLY when present — not into the middle of the
+  // original {description, ingredients, links} slots — so a record that predates either field
+  // (every treatment that already had product data before this milestone) produces the EXACT same
+  // string as before. Inserting a new fixed slot there, even an empty one, would still reshape
+  // every existing record's signature and fire the same unwanted mass regen this file exists to
+  // avoid — see the doc comment above.
+  const maker = t.maker?.trim() ? `|${t.maker.trim()}` : "";
+  const admin = t.administration
+    ? `|${t.administration.unit}|${t.administration.unitsPerServing}|${t.administration.suggestedUnits}|${t.administration.suggestedFrequency}|${t.administration.containerQuantity ?? ""}`
+    : "";
+  return `|${t.description?.trim() ?? ""}|${ingredients}|${links}${maker}${admin}`;
+}

package/treatment-timing-rules.ts

@@ -0,0 +1,90 @@
+// The two timing rules every treatment assessment must obey, in ONE place.
+//
+// They were previously written out twice — once in leaf-regen-registry.ts's per-node prompts (the
+// Translate path) and once in finding-generate.ts's monolith prompt (the whole-Finding "↻ Translate"
+// path) — in different formats, so a correction to one silently left the other wrong. Both had shipped
+// the same two defects:
+//
+//   1. "the current dose is the most-recently-dated row" — which names a SCHEDULED FUTURE titration
+//      step as current the moment one exists, reporting a drug at 6mg while 9mg is actually active.
+//   2. Nothing required a named co-treatment to be real or concurrent, so an assessment could call a
+//      stack "concurrent" by reading its constituents out of ANOTHER entry's name, months after it
+//      had ended.
+//
+// Both prompt systems now interpolate these constants, so there is one wording to correct.
+
+// Which row of a titration is the dose in force right now.
+export const CURRENT_DOSE_RULE =
+  "The CURRENT dose is the row whose window CONTAINS Today: its start is on or before Today AND it " +
+  "either has no end or its end is on or after Today. This is NOT simply the latest-dated row. A row " +
+  "that starts AFTER Today is a scheduled future step and is NOT the current dose, even though it is " +
+  "the newest and even though it has no end date; a CLOSED range that contains Today IS the current " +
+  "dose. If several rows contain Today, take the one with the latest start.";
+
+// What must be true before another treatment may be named in an assessment.
+export const CO_MENTION_RULE =
+  "CO-MENTION DISCIPLINE — before naming any OTHER treatment, verify BOTH of the following against " +
+  "the treatment list and drop the mention if either fails. (1) IT EXISTS AS ITS OWN ROW. Never infer " +
+  "a treatment from words inside another entry's name: an entry called \"Glutathione stack (Glycine " +
+  "20g/day and NAC 2g/day)\" is ONE row, and is NOT evidence that Glycine or NAC is separately on " +
+  "record. Only a row that appears in its own right counts. (2) ITS WINDOW OVERLAPS the window you " +
+  "are discussing. Read that row's own dates: a [Since X] row is active from X onward; a closed range " +
+  "[X–Y] is active only between X and Y. Two treatments are concurrent ONLY if both are active at the " +
+  "same time. If the other one ended before the item you are assessing started, or starts after it " +
+  "ended, they never overlapped — say what you actually mean in the right tense (\"ran until May 2026, " +
+  "so it no longer overlaps this dose\") or leave it out. NEVER write \"concurrent\", \"alongside\", " +
+  "\"together with\", \"on top of\", or \"while also taking\" about a treatment whose window does not " +
+  "overlap the one under discussion. An interaction you cannot date is an interaction you do not assert.";
+
+// finding-generate.ts builds its prompt as an array of pre-wrapped lines rather than one long string,
+// so the shared text is wrapped to a column and optionally indented to sit inside its section.
+export function asPromptLines(rule: string, indent = "", width = 68): string[] {
+  const out: string[] = [];
+  let line = "";
+  for (const word of rule.split(" ")) {
+    const candidate = line ? `${line} ${word}` : word;
+    if (candidate.length > width && line) {
+      out.push(indent + line);
+      line = word;
+    } else {
+      line = candidate;
+    }
+  }
+  if (line) out.push(indent + line);
+  return out;
+}
+
+// How to speak about dose in each temporal bucket, and against what yardstick.
+//
+// Two failures this exists to stop, both seen live on the same drug. A PAST card was described as
+// "ongoing since August 2025" with "the current 6 mg/week dose" — present tense and a "current" dose
+// for a regimen that has ended, which is simply false. And a bucket is not one dose: Tirzepatide's
+// past alone holds nine closed windows, so naming any single row "the dose" throws away the
+// trajectory that is the actual clinical content.
+export const BUCKET_DOSE_RULE =
+  "DOSE IN CONTEXT — a treatment's rows are grouped by whether they are PAST, ONGOING or PLANNED, " +
+  "and each group can hold SEVERAL rows, because a titration is one drug across many dose periods. " +
+  "Never pick one row and call it \"the dose\"; read the group as a trajectory and say where it " +
+  "started, where it ended, and how it moved. Then match your tense and your language to the group " +
+  "you are discussing. PAST: every row has ended. Write entirely in the past tense and NEVER use " +
+  "\"current\", \"currently\", \"is taking\", \"remains on\", or \"ongoing\" about it. The facts worth " +
+  "stating are the range the dose covered, the highest dose reached, the final dose before it " +
+  "stopped, how long it ran in total, and what the markers did across that span — not what the " +
+  "patient is on now, which this group cannot tell you. ONGOING: the current dose is the row whose " +
+  "window contains Today (see the rule above); earlier rows in the group are the path taken to reach " +
+  "it, and a row starting after Today is a scheduled step, not the present. PLANNED: nothing is " +
+  "being taken yet. Write in the future tense — \"is scheduled to start at\", \"will escalate to\" — " +
+  "and never describe a planned dose as one the patient is on.";
+
+// The yardstick the patient's own numbers should be read against.
+export const STANDARD_DOSING_RULE =
+  "STANDARD DOSING — when you discuss a dose, say where it sits against that drug's usual range, " +
+  "when you know that range with confidence: its usual starting dose, its usual titration steps, and " +
+  "its maximum or usual maintenance dose. Tirzepatide, for example, conventionally starts at 2.5 " +
+  "mg/week and is titrated in 2.5 mg steps to a maximum of 15 mg/week; a patient at 7.5 mg/week is " +
+  "mid-titration with room above, and one at 15 mg/week is at ceiling with no escalation left. That " +
+  "placement is what makes a dose mean something: say plainly when a dose is sub-therapeutic, " +
+  "mid-range, at the usual maximum, or above label, and when an escalation is available say what the " +
+  "next conventional step is rather than inventing a target. If you do not know a drug's standard " +
+  "range with confidence, say nothing about it rather than guessing — a wrong ceiling is worse than " +
+  "no ceiling.";