@pablotech/akesi 0.1.22

package/finding-assemble.ts

@@ -0,0 +1,803 @@
+// The pure, browser-safe half of finding generation: the response schema
+// (FindingAIResponse), the structural + coverage validator, and the assembly of a validated
+// response into a ClientFinding (hashes injected by the caller). No prompt, no Anthropic SDK, no
+// Node — a browser imports this to validate + assemble a streamed finding; a host CLI and a
+// serverless refresh endpoint reuse the exact same validate/assemble.
+import type { ClientFinding } from "./types";
+
+interface FindingDecisionAIResponse {
+  intervention: string;
+  purpose: string;
+  pros: string[];
+  cons: string[];
+  alternatives: string[];
+  recommendation: string;
+}
+
+export interface FindingAIResponse {
+  progression: {
+    latest: string;
+    recent: string;
+    overall: string;
+  };
+  /** Leaf-owned: absent from a core response, present on an older stored finding. */
+  studyResults?: { study: string; result: string; group: string }[];
+  // M92 — no `noteId`/label field here: a note has no short verbatim-echoable label like Study's
+  // `focus`, so entries are paired back to `factors.noteEntries` by array position, not content.
+  // See assembleFinding's `meta.noteIds` (the caller supplies the parallel id array).
+  /** Leaf-owned: absent from a core response, present on an older stored finding. */
+  noteResults?: { result: string; group: string }[];
+  disease: { group: string; finding: string }[];
+  /** Leaf-owned: absent from a core response, present on an older stored finding. */
+  treatment?: { item: string; assessment: string; group: string }[];
+  patternAntipattern: { pattern: string; antipattern: string };
+  clinicalSynthesis: { adverse: string; favorable: string; conditioning?: string };
+  criticalRatios: {
+    name: string;
+    numerator: string;
+    denominator: string;
+    unit: string;
+    meaning: string;
+    generalLow?: number;
+    generalHigh?: number;
+    generalExplanation: string;
+    personalizedLow?: number;
+    personalizedHigh?: number;
+    explanation: string;
+  }[];
+  decisions: {
+    patient: FindingDecisionAIResponse[];
+    ai: FindingDecisionAIResponse[];
+  };
+  doctorConversation: { group: string; questions: string[] }[];
+  definitions: { term: string; definition: string; group: string }[];
+  healthMarkers: {
+    recommended: { group: string; markers: { name: string; rationale: string }[] }[];
+  };
+  dataRequisition: { type: string; group: string; items: string[] }[];
+  /** Leaf-owned: absent from a core response, present on an older stored finding. */
+  treatmentGroups?: { system: string; topic: string; patient: string[]; ai: string[] }[];
+  planAssessment: string;
+  /** Leaf-owned (aiOnPlan): absent from a core response, present on an older stored one. */
+  planAssessmentRows?: { action: string; assessment: string }[];
+  finalThoughts: string;
+  // The union the validator has always accepted (see validate()'s "accept either shape"), and
+  // the object form is the one production actually stores; the array form is what a model may emit,
+  // which the parser then collapses. This was declared as the array alone, so every test fixture
+  // built the real (object) shape and was silently wrong against its own type — invisible until
+  // tests/ came under the type checker.
+  basis: { key: string; text: string }[] | Record<string, string>;
+}
+
+// The streamed finding's top-level portions, in emission order. Typed as
+// `keyof FindingAIResponse` so a renamed schema key breaks the build here; a host refresh client scans the
+// stream buffer for these to drive portion-based progress (N of M sections), so progress and the
+// validated shape can't drift apart.
+export const FINDING_PORTION_KEYS: readonly (keyof FindingAIResponse)[] = [
+  "progression",
+  // studyResults, noteResults, treatment, treatmentGroups and planAssessmentRows are gone
+  // from this list because
+  // they are gone from the core prompt: each is now written by its own leaf. Leaving them here would
+  // peg the progress bar four portions short of full on every successful run.
+  "disease",
+  "patternAntipattern",
+  "clinicalSynthesis",
+  "criticalRatios",
+  "decisions",
+  "doctorConversation",
+  "definitions",
+  "healthMarkers",
+  "dataRequisition",
+  "planAssessment",
+  "finalThoughts",
+  "basis",
+];
+
+// The six keys the monolith no longer narrates: each is a leaf whose turn is generated by its own
+// LEAF_REGEN_SPECS entry, and whose basis sentence is stamped from that node's own DagNode.basis at
+// merge time (stampLeafBasis in leaf-regen-registry.ts). Keeping them in the required set would make
+// the core response fail validation for narrating sections it does not write.
+export const LEAF_OWNED_BASIS_KEYS = [
+  "studyResults",
+  "noteResults",
+  "treatmentAssessment",
+  "hypothesisEvaluation",
+  "treatmentGroups",
+  "aiOnPlan",
+] as const;
+
+export const BASIS_KEYS = [
+  "patientAssessment",
+  "patientProfile",
+  "statedObjective",
+  "pursuedStudy",
+  "pursuedNotes",
+  "diagnosedDisease",
+  "treatmentHistory",
+  "correlationHistory",
+  "patientHypothesis",
+  "markerLevels",
+  "aiFindings",
+  "healthProgression",
+  "studyResults",
+  "noteResults",
+  "possibleFindings",
+  "treatmentAssessment",
+  "dataRequisition",
+  "aiHypothesis",
+  "hypothesisEvaluation",
+  "doctorConversation",
+  "healthMarkers",
+  "patientPlan",
+  "treatmentGroups",
+  "patternAntipattern",
+  "clinicalSynthesis",
+  "criticalRatios",
+  "aiOnPlan",
+  "finalThoughts",
+  "abbreviations",
+] as const;
+
+type BasisKey = typeof BASIS_KEYS[number];
+
+/**
+ * Collapse a response's `basis` into the object form the vault stores.
+ *
+ * Accepts BOTH shapes, matching what validate() has always accepted. It took the array alone,
+ * so a model emitting the object form (which validate explicitly permits — see its "accept either
+ * shape" branch) passed validation and then threw here, iterating a non-iterable. Latent until the
+ * declared type was widened to the union the validator actually allows.
+ */
+function basisFromResponse(basis: FindingAIResponse["basis"]) {
+  const out = {} as Record<BasisKey, string>;
+  const entries = Array.isArray(basis)
+    ? basis.map((e) => [e.key, e.text] as const)
+    : Object.entries(basis ?? {});
+  for (const [key, text] of entries) {
+    out[key.trim() as BasisKey] = String(text).trim();
+  }
+  return out as ClientFinding["basis"];
+}
+
+function parseFindingDecision(d: FindingDecisionAIResponse) {
+  return {
+    intervention: d.intervention.trim(),
+    purpose: d.purpose.trim(),
+    pros: d.pros.map((s) => s.trim()).filter((s) => s.length > 0),
+    cons: d.cons.map((s) => s.trim()).filter((s) => s.length > 0),
+    alternatives: d.alternatives.map((s) => s.trim()).filter((s) => s.length > 0),
+    recommendation: d.recommendation.trim(),
+  };
+}
+
+export function validateFindingResponse(r: FindingAIResponse): void {
+  return validate(r);
+}
+
+// Full validation including patient-side coverage/verbatim matching — the exact path the pipeline
+// runs (generateFinding passes the same `expected`). Exposed so a contract test can assert the
+// prompt presentation and the verbatim-match logic agree (e.g. a date-prefixed plan-action ref is
+// rejected, so the retry-feedback can fix it).
+export function validateFindingWithInputs(
+  r: FindingAIResponse,
+  expected: { patient: string[]; planActions?: string[]; noteIds?: string[] },
+): void {
+  return validate(r, expected);
+}
+
+// `expected.patient` is the set of patient-item refs (factors.decisions interventions + factors.plan
+// actions) that treatmentGroups must cover. `expected.noteIds` is the ordered id list noteResults
+// must be pairable against (one result per populated Note entry, in order — see populatedNoteEntries).
+// Omitted by the structural-only wrapper above (existing unit fixtures), in which case patient-side
+// coverage/membership and the noteResults count are skipped; AI-side coverage (from r.decisions.ai)
+// is always checked.
+export function validate(r: FindingAIResponse, expected?: { patient: string[]; planActions?: string[]; noteIds?: string[] }): void {
+  const sections: [string, string][] = [
+    ["progression.latest", r.progression?.latest],
+    ["progression.recent", r.progression?.recent],
+    ["progression.overall", r.progression?.overall],
+  ];
+  for (const [key, value] of sections) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+      throw new Error(`finding section "${key}" missing`);
+    }
+  }
+  // Body-system tags on studyResults / treatment (used by the UI to group them under System Analysis
+  // headings) must each match one of the disease[].group names — same discipline as treatmentGroups.
+  const diseaseGroupSet = new Set((r.disease ?? []).map((d) => d?.group?.trim()).filter((g): g is string => !!g));
+  if (r.studyResults !== undefined && !Array.isArray(r.studyResults)) {
+    throw new Error(`studyResults present but not an array`);
+  }
+  for (const [i, s] of (r.studyResults ?? []).entries()) {
+    if (!s || typeof s.study !== "string" || s.study.trim().length === 0) {
+      throw new Error(`studyResults[${i}].study missing`);
+    }
+    if (typeof s.result !== "string" || s.result.trim().length === 0) {
+      throw new Error(`studyResults[${i}] (${s.study}) result missing`);
+    }
+    if (typeof s.group !== "string" || s.group.trim().length === 0) {
+      throw new Error(`studyResults[${i}] (${s.study}) group missing`);
+    }
+    if (!diseaseGroupSet.has(s.group.trim())) {
+      throw new Error(`studyResults[${i}] (${s.study}) group "${s.group}" is not one of the disease groups`);
+    }
+  }
+  // noteResults — same shape/group discipline as studyResults, minus a label field (a note has no
+  // short verbatim label; entries pair back to factors.noteEntries by position — see expected.noteIds).
+  if (r.noteResults !== undefined && !Array.isArray(r.noteResults)) {
+    throw new Error(`noteResults missing or not an array`);
+  }
+  if (expected?.noteIds && r.noteResults !== undefined && r.noteResults.length !== expected.noteIds.length) {
+    throw new Error(
+      `noteResults must have exactly one entry per populated Note, in order (expected ${expected.noteIds.length}, got ${r.noteResults!.length})`,
+    );
+  }
+  for (const [i, n] of (r.noteResults ?? []).entries()) {
+    if (!n || typeof n.result !== "string" || n.result.trim().length === 0) {
+      throw new Error(`noteResults[${i}].result missing`);
+    }
+    if (typeof n.group !== "string" || n.group.trim().length === 0) {
+      throw new Error(`noteResults[${i}].group missing`);
+    }
+    if (!diseaseGroupSet.has(n.group.trim())) {
+      throw new Error(`noteResults[${i}] group "${n.group}" is not one of the disease groups`);
+    }
+  }
+  if (!Array.isArray(r.disease) || r.disease.length < 4) {
+    throw new Error(`disease missing or has fewer than 4 area entries`);
+  }
+  if (r.disease.length > 10) {
+    throw new Error(`disease has more than 10 area entries (${r.disease.length})`);
+  }
+  for (const [i, d] of r.disease.entries()) {
+    if (!d || typeof d.group !== "string" || d.group.trim().length === 0) {
+      throw new Error(`disease[${i}].group missing`);
+    }
+    if (typeof d.finding !== "string" || d.finding.trim().length === 0) {
+      throw new Error(`disease[${i}] (${d.group}) finding missing`);
+    }
+  }
+  if (r.treatment !== undefined && (!Array.isArray(r.treatment) || r.treatment.length < 1)) {
+    throw new Error(`treatment missing or empty`);
+  }
+  if ((r.treatment?.length ?? 0) > 30) {
+    throw new Error(`treatment has more than 30 entries (${r.treatment!.length})`);
+  }
+  const seenItems = new Set<string>();
+  for (const [i, t] of (r.treatment ?? []).entries()) {
+    if (!t || typeof t.item !== "string" || t.item.trim().length === 0) {
+      throw new Error(`treatment[${i}].item missing`);
+    }
+    if (typeof t.assessment !== "string" || t.assessment.trim().length === 0) {
+      throw new Error(`treatment[${i}] (${t.item}) assessment missing`);
+    }
+    if (typeof t.group !== "string" || t.group.trim().length === 0) {
+      throw new Error(`treatment[${i}] (${t.item}) group missing`);
+    }
+    if (!diseaseGroupSet.has(t.group.trim())) {
+      throw new Error(`treatment[${i}] (${t.item}) group "${t.group}" is not one of the disease groups`);
+    }
+    const baseName = t.item.trim().toLowerCase().replace(/\s+\d.*$/, "");
+    if (seenItems.has(baseName)) {
+      throw new Error(`treatment[${i}] (${t.item}) duplicates a prior entry by drug name — titration must collapse into one entry`);
+    }
+    seenItems.add(baseName);
+  }
+  if (!r.decisions || typeof r.decisions !== "object" || Array.isArray(r.decisions)) {
+    throw new Error(`decisions missing or not an object with { patient, ai }`);
+  }
+  if (!Array.isArray(r.decisions.patient)) {
+    throw new Error(`decisions.patient missing or not an array`);
+  }
+  if (!Array.isArray(r.decisions.ai)) {
+    throw new Error(`decisions.ai missing or not an array`);
+  }
+  if (r.decisions.ai.length > 12) {
+    throw new Error(`decisions.ai has more than 12 entries (${r.decisions.ai.length})`);
+  }
+  const validateOneDecision = (label: string, i: number, d: FindingDecisionAIResponse) => {
+    if (!d || typeof d.intervention !== "string" || d.intervention.trim().length === 0) {
+      throw new Error(`${label}[${i}].intervention missing`);
+    }
+    if (typeof d.purpose !== "string" || d.purpose.trim().length === 0) {
+      throw new Error(`${label}[${i}] (${d.intervention}) purpose missing`);
+    }
+    for (const field of ["pros", "cons", "alternatives"] as const) {
+      if (!Array.isArray(d[field]) || d[field].length < 2) {
+        throw new Error(`${label}[${i}] (${d.intervention}) ${field} must be an array of 2+ bullets`);
+      }
+      if (d[field].length > 8) {
+        throw new Error(`${label}[${i}] (${d.intervention}) ${field} has more than 8 bullets`);
+      }
+      for (const [j, s] of d[field].entries()) {
+        if (typeof s !== "string" || s.trim().length === 0) {
+          throw new Error(`${label}[${i}].${field}[${j}] missing`);
+        }
+      }
+    }
+    if (typeof d.recommendation !== "string" || d.recommendation.trim().length === 0) {
+      throw new Error(`${label}[${i}] (${d.intervention}) recommendation missing`);
+    }
+  };
+  for (const [i, d] of r.decisions.patient.entries()) validateOneDecision("decisions.patient", i, d);
+  for (const [i, d] of r.decisions.ai.entries()) validateOneDecision("decisions.ai", i, d);
+  // AI Hypothesis is now the collective intervention set, so it MAY restate
+  // items the patient already lists — no dedup against decisions.patient.
+
+  const expectedDc = r.disease.length + r.decisions.patient.length + r.decisions.ai.length;
+  if (!Array.isArray(r.doctorConversation) || r.doctorConversation.length !== expectedDc) {
+    throw new Error(
+      `doctorConversation must have one entry per disease group + one per patient decision + one per AI consideration (expected ${expectedDc}, got ${
+        Array.isArray(r.doctorConversation) ? r.doctorConversation.length : "non-array"
+      })`,
+    );
+  }
+  for (const [i, g] of r.doctorConversation.entries()) {
+    if (!g || typeof g.group !== "string" || g.group.trim().length === 0) {
+      throw new Error(`doctorConversation[${i}].group missing`);
+    }
+    let expectedGroup: string | undefined;
+    if (i < r.disease.length) {
+      expectedGroup = r.disease[i]?.group?.trim();
+    } else if (i < r.disease.length + r.decisions.patient.length) {
+      expectedGroup = r.decisions.patient[i - r.disease.length]?.intervention?.trim();
+    } else {
+      expectedGroup = r.decisions.ai[i - r.disease.length - r.decisions.patient.length]?.intervention?.trim();
+    }
+    if (expectedGroup && g.group.trim() !== expectedGroup) {
+      // A real run died here on attempt 6 with "Methylation stack (Methyl-B12 + L-methylfolate)"
+      // against its OWN earlier "…(Methyl-B12 + L-methylfolate ± cofactors)": the model truncated a
+      // long label it was asked to reproduce verbatim. That is a transcription slip, not a different
+      // intervention, and a $5 regeneration is an absurd price for it.
+      //
+      // A prefix relationship is the signature of a truncation and is strong evidence of the same
+      // subject; anything else still throws, so naming an unrelated intervention (the real
+      // misattribution risk — wrong questions filed under the wrong decision) is untouched. On a
+      // tolerated near-match the canonical label is STAMPED, so downstream readers still get one
+      // spelling.
+      const got = g.group.trim();
+      const near = got.startsWith(expectedGroup) || expectedGroup.startsWith(got);
+      if (!near) {
+        throw new Error(
+          `doctorConversation[${i}] group "${g.group}" does not match expected "${expectedGroup}" — order is disease groups, then patient decisions, then AI considerations`,
+        );
+      }
+      g.group = expectedGroup;
+    }
+    if (!Array.isArray(g.questions) || g.questions.length < 1) {
+      throw new Error(`doctorConversation[${i}] (${g.group}) has no questions`);
+    }
+    if (g.questions.length > 6) {
+      throw new Error(
+        `doctorConversation[${i}] (${g.group}) has more than 6 questions (${g.questions.length})`,
+      );
+    }
+    for (const [j, q] of g.questions.entries()) {
+      if (typeof q !== "string" || q.trim().length === 0) {
+        throw new Error(`doctorConversation[${i}].questions[${j}] missing`);
+      }
+    }
+  }
+  // treatmentGroups — partition of every proposed treatment. AI-side coverage is always
+  // enforced (refs live in r.decisions.ai); patient-side only when `expected` is supplied.
+  if (r.treatmentGroups !== undefined && !Array.isArray(r.treatmentGroups)) {
+    throw new Error(`treatmentGroups missing or not an array`);
+  }
+  const aiInterventions = r.decisions.ai.map((d) => d.intervention.trim());
+  // Every group is pinned to a disease[].group (its System Analysis heading); groups are
+  // ordered by that system in disease order, and all groups of one system are contiguous.
+  const diseaseGroups = r.disease.map((d) => d.group.trim());
+  const seenAi = new Set<string>();
+  const seenPatient = new Set<string>();
+  let prevSystemIdx = -1;
+  const systemsSeen = new Set<string>();
+  for (const [i, g] of (r.treatmentGroups ?? []).entries()) {
+    if (!g || typeof g.topic !== "string" || g.topic.trim().length === 0) {
+      throw new Error(`treatmentGroups[${i}].topic missing`);
+    }
+    if (typeof g.system !== "string" || g.system.trim().length === 0) {
+      throw new Error(`treatmentGroups[${i}] (${g.topic}) system missing`);
+    }
+    const sysIdx = diseaseGroups.indexOf(g.system.trim());
+    if (sysIdx < 0) {
+      throw new Error(`treatmentGroups[${i}] (${g.topic}) system "${g.system}" is not one of the disease groups`);
+    }
+    if (sysIdx < prevSystemIdx) {
+      throw new Error(`treatmentGroups[${i}] (${g.topic}) system "${g.system}" is out of disease order`);
+    }
+    if (sysIdx !== prevSystemIdx && systemsSeen.has(g.system.trim())) {
+      throw new Error(`treatmentGroups system "${g.system}" is not contiguous — all groups of a system must be adjacent`);
+    }
+    prevSystemIdx = sysIdx;
+    systemsSeen.add(g.system.trim());
+    if (!Array.isArray(g.patient) || !Array.isArray(g.ai)) {
+      throw new Error(`treatmentGroups[${i}] (${g.topic}) patient and ai must be arrays`);
+    }
+    if (g.patient.length === 0 && g.ai.length === 0) {
+      throw new Error(`treatmentGroups[${i}] (${g.topic}) has neither patient nor ai items`);
+    }
+    for (const ref of g.ai) {
+      const t = (ref ?? "").trim();
+      if (!aiInterventions.includes(t)) {
+        throw new Error(`treatmentGroups[${i}] (${g.topic}) ai ref "${ref}" matches no decisions.ai intervention`);
+      }
+      if (seenAi.has(t)) throw new Error(`treatmentGroups ai ref "${t}" appears in more than one group`);
+      seenAi.add(t);
+    }
+    for (const ref of g.patient) {
+      const t = (ref ?? "").trim();
+      if (t.length === 0) throw new Error(`treatmentGroups[${i}] (${g.topic}) has an empty patient ref`);
+      if (expected && !expected.patient.includes(t)) {
+        throw new Error(`treatmentGroups[${i}] (${g.topic}) patient ref "${ref}" matches no patient hypothesis or plan action`);
+      }
+      if (seenPatient.has(t)) throw new Error(`treatmentGroups patient ref "${t}" appears in more than one group`);
+      seenPatient.add(t);
+    }
+  }
+  // Only when the response actually CARRIES treatmentGroups. The core writes decisions.ai but
+  // no longer writes treatmentGroups (the leaf does), which made this unsatisfiable: it demanded
+  // placement into a section that is legitimately absent. Placement is still enforced for the leaf's
+  // own output by validateRegroup (finding-regroup.ts), which checks the same thing against the ids
+  // it was given — so the guarantee moved rather than disappeared.
+  if (r.treatmentGroups !== undefined) {
+    for (const a of aiInterventions) {
+      if (!seenAi.has(a)) throw new Error(`decisions.ai "${a}" is not placed in any treatmentGroups group`);
+    }
+  }
+  // Same guard, patient side. This one fires only when `expected` is supplied — which the live
+  // refresh always does and the structural-only wrapper never does, which is exactly why the
+  // core-only unit test below had to start passing `expected` too.
+  if (expected && r.treatmentGroups !== undefined) {
+    for (const p of expected.patient) {
+      if (!seenPatient.has(p)) throw new Error(`patient item "${p}" is not placed in any treatmentGroups group`);
+    }
+  }
+
+  if (!Array.isArray(r.definitions) || r.definitions.length < 3) {
+    throw new Error(`definitions missing or has fewer than 3 entries`);
+  }
+  if (r.definitions.length > 80) {
+    throw new Error(`definitions has more than 80 entries (${r.definitions.length})`);
+  }
+  for (const [i, d] of r.definitions.entries()) {
+    if (!d || typeof d.term !== "string" || d.term.trim().length === 0) {
+      throw new Error(`definitions[${i}].term missing`);
+    }
+    if (typeof d.definition !== "string" || d.definition.trim().length === 0) {
+      throw new Error(`definitions[${i}] (${d.term}) definition missing`);
+    }
+    if (typeof d.group !== "string" || d.group.trim().length === 0) {
+      throw new Error(`definitions[${i}] (${d.term}) group missing`);
+    }
+    if (!diseaseGroupSet.has(d.group.trim())) {
+      throw new Error(`definitions[${i}] (${d.term}) group "${d.group}" is not one of the disease groups`);
+    }
+  }
+  if (!r.healthMarkers || !Array.isArray(r.healthMarkers.recommended) || r.healthMarkers.recommended.length < 1) {
+    throw new Error(`healthMarkers.recommended missing or empty`);
+  }
+  // A duplicated group used to reject the whole response, costing a full regeneration to fix
+  // something with exactly one correct reading: the group's markers are the union of its entries. The
+  // group name is the key, nothing is ambiguous, and nothing is lost, so merge in place instead. This
+  // is the only rule in this validator that repairs rather than rejects, and it earns it by being
+  // information-preserving — contrast the group-not-in-disease-groups rule two blocks down, where
+  // picking a replacement would be a clinical guess.
+  const byGroup = new Map<string, { group: string; markers: unknown[] }>();
+  for (const g of r.healthMarkers.recommended) {
+    const groupKey = g?.group?.trim();
+    if (!groupKey) continue;
+    const prior = byGroup.get(groupKey);
+    if (prior) prior.markers.push(...(Array.isArray(g.markers) ? g.markers : []));
+    else byGroup.set(groupKey, g as { group: string; markers: unknown[] });
+  }
+  if (byGroup.size !== r.healthMarkers.recommended.filter((g) => g?.group?.trim()).length) {
+    r.healthMarkers.recommended = [...byGroup.values()] as typeof r.healthMarkers.recommended;
+  }
+  for (const [i, g] of r.healthMarkers.recommended.entries()) {
+    if (!g || typeof g.group !== "string" || g.group.trim().length === 0) {
+      throw new Error(`healthMarkers.recommended[${i}].group missing`);
+    }
+    if (!Array.isArray(g.markers)) {
+      throw new Error(`healthMarkers.recommended[${i}] (${g.group}) markers not an array`);
+    }
+    for (const [j, m] of g.markers.entries()) {
+      if (!m || typeof m.name !== "string" || m.name.trim().length === 0) {
+        throw new Error(`healthMarkers.recommended[${i}][${j}].name missing`);
+      }
+      if (typeof m.rationale !== "string" || m.rationale.trim().length === 0) {
+        throw new Error(`healthMarkers.recommended[${i}][${j}] (${m.name}) rationale missing`);
+      }
+    }
+  }
+  if (!Array.isArray(r.dataRequisition)) {
+    throw new Error(`dataRequisition missing or not an array`);
+  }
+  for (const [i, g] of r.dataRequisition.entries()) {
+    if (!g || typeof g.type !== "string" || g.type.trim().length === 0) {
+      throw new Error(`dataRequisition[${i}].type missing`);
+    }
+    if (typeof g.group !== "string" || g.group.trim().length === 0) {
+      throw new Error(`dataRequisition[${i}] (${g.type}) group missing`);
+    }
+    if (!diseaseGroupSet.has(g.group.trim())) {
+      throw new Error(`dataRequisition[${i}] (${g.type}) group "${g.group}" is not one of the disease groups`);
+    }
+    if (!Array.isArray(g.items)) {
+      throw new Error(`dataRequisition[${i}] (${g.type}) items not an array`);
+    }
+    // assembleFinding silently .filter()s an items-empty group out (see the dataRequisition
+    // build below), so the model's mistake vanished instead of being corrected. Checked HERE, inside
+    // validate(), so the core's correction loop can actually fix it.
+    if (g.items.length === 0) {
+      throw new Error(`dataRequisition[${i}] (${g.type}) has no items — omit the group entirely instead`);
+    }
+    for (const [j, s] of g.items.entries()) {
+      if (typeof s !== "string" || s.trim().length === 0) {
+        throw new Error(`dataRequisition[${i}][${j}] missing`);
+      }
+    }
+  }
+  // planAssessment (AI on Plan) is empty when the patient gave no Patient
+  // Plan to reason about; otherwise it's a substantive paragraph.
+  if (typeof r.planAssessment !== "string") {
+    throw new Error(`planAssessment missing or not a string`);
+  }
+  // planAssessmentRows — one AI assessment per Patient Plan Action. Coverage/membership are
+  // enforced only when the plan actions are supplied (skipped by the structural-only wrapper).
+  if (r.planAssessmentRows !== undefined && !Array.isArray(r.planAssessmentRows)) {
+    throw new Error(`planAssessmentRows missing or not an array`);
+  }
+  for (const [i, row] of (r.planAssessmentRows ?? []).entries()) {
+    if (!row || typeof row.action !== "string" || row.action.trim().length === 0) {
+      throw new Error(`planAssessmentRows[${i}].action missing`);
+    }
+    if (typeof row.assessment !== "string" || row.assessment.trim().length === 0) {
+      throw new Error(`planAssessmentRows[${i}] (${row.action}) assessment missing`);
+    }
+  }
+  if (expected?.planActions) {
+    const seen = new Set<string>();
+    for (const [i, row] of (r.planAssessmentRows ?? []).entries()) {
+      const a = row.action.trim();
+      if (!expected.planActions.includes(a)) {
+        throw new Error(`planAssessmentRows[${i}] action "${row.action}" matches no Patient Plan action`);
+      }
+      if (seen.has(a)) throw new Error(`planAssessmentRows action "${a}" appears more than once`);
+      seen.add(a);
+    }
+    // Coverage only when the core actually wrote the rows. aiOnPlan owns them now, so an absent
+    // planAssessmentRows means "the leaf will fill it", not "every plan action went unassessed".
+    if (r.planAssessmentRows !== undefined) {
+      for (const a of expected.planActions) {
+        if (!seen.has(a)) throw new Error(`Patient Plan action "${a}" is not assessed in planAssessmentRows`);
+      }
+    }
+  }
+  // finalThoughts (the whole-report reflection) is always expected — it does
+  // not depend on a Patient Plan existing.
+  if (typeof r.finalThoughts !== "string" || r.finalThoughts.trim().length === 0) {
+    throw new Error(`finalThoughts missing`);
+  }
+  // patternAntipattern (the patient-specific Pattern and Antipattern section)
+  // is always expected — both prose halves required.
+  if (!r.patternAntipattern || typeof r.patternAntipattern !== "object" || Array.isArray(r.patternAntipattern)) {
+    throw new Error(`patternAntipattern missing or not an object with { pattern, antipattern }`);
+  }
+  if (typeof r.patternAntipattern.pattern !== "string" || r.patternAntipattern.pattern.trim().length === 0) {
+    throw new Error(`patternAntipattern.pattern missing`);
+  }
+  if (typeof r.patternAntipattern.antipattern !== "string" || r.patternAntipattern.antipattern.trim().length === 0) {
+    throw new Error(`patternAntipattern.antipattern missing`);
+  }
+  // clinicalSynthesis (the two-track trajectory section): adverse + favorable
+  // always required; conditioning is optional (may be "" when the data does
+  // not support a biological-age read).
+  if (!r.clinicalSynthesis || typeof r.clinicalSynthesis !== "object" || Array.isArray(r.clinicalSynthesis)) {
+    throw new Error(`clinicalSynthesis missing or not an object with { adverse, favorable }`);
+  }
+  if (typeof r.clinicalSynthesis.adverse !== "string" || r.clinicalSynthesis.adverse.trim().length === 0) {
+    throw new Error(`clinicalSynthesis.adverse missing`);
+  }
+  if (typeof r.clinicalSynthesis.favorable !== "string" || r.clinicalSynthesis.favorable.trim().length === 0) {
+    throw new Error(`clinicalSynthesis.favorable missing`);
+  }
+  if (r.clinicalSynthesis.conditioning != null && typeof r.clinicalSynthesis.conditioning !== "string") {
+    throw new Error(`clinicalSynthesis.conditioning must be a string when present`);
+  }
+  // criticalRatios: 2–8 marker ratios, each with non-empty name / components /
+  // meaning / explanations; range bounds are optional numbers.
+  if (!Array.isArray(r.criticalRatios) || r.criticalRatios.length < 2) {
+    throw new Error(`criticalRatios must be an array of at least 2 entries`);
+  }
+  if (r.criticalRatios.length > 8) {
+    throw new Error(`criticalRatios has more than 8 entries`);
+  }
+  for (const [i, cr] of r.criticalRatios.entries()) {
+    for (const k of ["name", "numerator", "denominator", "meaning", "generalExplanation", "explanation"] as const) {
+      if (typeof cr[k] !== "string" || cr[k].trim().length === 0) {
+        throw new Error(`criticalRatios[${i}].${k} missing`);
+      }
+    }
+    if (typeof cr.unit !== "string") {
+      throw new Error(`criticalRatios[${i}].unit must be a string ("" for dimensionless)`);
+    }
+    for (const k of ["generalLow", "generalHigh", "personalizedLow", "personalizedHigh"] as const) {
+      if (cr[k] != null && typeof cr[k] !== "number") {
+        throw new Error(`criticalRatios[${i}].${k} must be a number when present`);
+      }
+    }
+  }
+  // The LLM emits basis as an array of {key, text} (the strict json-schema
+  // grammar limit on the object form was rejecting the 14-key shape). We
+  // accept either shape — the typed parser collapses the array form into
+  // an object before persisting, but validate runs against the raw response.
+  if (!r.basis) {
+    throw new Error("basis missing");
+  }
+  const basisMap = new Map<string, string>();
+  if (Array.isArray(r.basis)) {
+    for (const entry of r.basis as { key: string; text: string }[]) {
+      if (!entry || typeof entry.key !== "string" || typeof entry.text !== "string") {
+        throw new Error(`basis entries must be { key, text } pairs`);
+      }
+      basisMap.set(entry.key.trim(), entry.text);
+    }
+  } else if (typeof r.basis === "object") {
+    for (const [key, value] of Object.entries(r.basis as Record<string, unknown>)) {
+      if (typeof value !== "string") {
+        throw new Error(`basis.${key} must be a string`);
+      }
+      basisMap.set(key, value);
+    }
+  } else {
+    throw new Error("basis must be an array of {key, text} or an object");
+  }
+  const leafOwned = new Set<string>(LEAF_OWNED_BASIS_KEYS);
+  for (const key of BASIS_KEYS) {
+    if (leafOwned.has(key)) continue; // stamped by the leaf that writes the section, not by the core
+    const value = basisMap.get(key);
+    if (typeof value !== "string" || value.trim().length === 0) {
+      throw new Error(`basis.${key} missing`);
+    }
+  }
+}
+
+// Assemble a validated FindingAIResponse into a ClientFinding. The mapping is the exact
+// tail of the old generateFinding (trim/filter/sort); the hashes + timestamp + generatedBy are
+// INJECTED so a host CLI (node:crypto findingInputsHashOf/nodeHashesOf) and a browser (SubtleCrypto
+// twins in staleness.ts) produce an identical finding.
+export function assembleFinding(
+  parsed: FindingAIResponse,
+  meta: {
+    generatedAt: string;
+    inputsHash: string;
+    nodeHashes: Record<string, string>;
+    generatedBy: ClientFinding["generatedBy"];
+    // M92 — the ordered ids of the Note entries the prompt presented (populatedNoteEntries), zipped
+    // positionally against parsed.noteResults since a note has no label the LLM could echo back.
+    noteIds: string[];
+    // 06/Gap A — injected rather than looked up here, so this module carries no dependency on
+    // finding-config/brain-versions (both span brains outside the reasoning core's own scope).
+    promptVersions: ClientFinding["promptVersions"];
+  },
+): ClientFinding {
+  const definitions = parsed.definitions
+    .map((d) => ({ term: d.term.trim(), definition: d.definition.trim(), group: d.group?.trim() ?? "" }))
+    .filter((d) => d.term.length > 0 && d.definition.length > 0)
+    .sort((a, b) => a.term.localeCompare(b.term));
+  const healthMarkers = {
+    recommended: parsed.healthMarkers.recommended.map((g) => ({
+      group: g.group.trim(),
+      markers: g.markers
+        .map((m) => ({ name: m.name.trim(), rationale: m.rationale.trim() }))
+        .filter((m) => m.name.length > 0 && m.rationale.length > 0),
+    })),
+  };
+  const dataRequisition = parsed.dataRequisition
+    .map((g) => ({
+      type: g.type.trim(),
+      group: g.group?.trim() ?? "",
+      items: g.items.map((s) => s.trim()).filter((s) => s.length > 0),
+    }))
+    .filter((g) => g.type.length > 0 && g.items.length > 0);
+  return {
+    progression: {
+      latest: parsed.progression.latest.trim(),
+      recent: parsed.progression.recent.trim(),
+      overall: parsed.progression.overall.trim(),
+    },
+    // `?? []` on all four: the core no longer narrates them, and the leaf that owns each one
+    // merges its own entries in afterwards. An older stored response still carries them.
+    studyResults: (parsed.studyResults ?? [])
+      .map((s) => ({ study: s.study.trim(), result: s.result.trim(), group: s.group?.trim() ?? "" }))
+      .filter((s) => s.study.length > 0 && s.result.length > 0),
+    noteResults: (parsed.noteResults ?? [])
+      .map((n, i) => ({ noteId: meta.noteIds[i] ?? "", result: n.result.trim(), group: n.group?.trim() ?? "" }))
+      .filter((n) => n.noteId.length > 0 && n.result.length > 0),
+    disease: parsed.disease.map((d) => ({ group: d.group.trim(), finding: d.finding.trim() })),
+    treatment: (parsed.treatment ?? []).map((t) => ({ item: t.item.trim(), assessment: t.assessment.trim(), group: t.group?.trim() ?? "" })),
+    patternAntipattern: {
+      pattern: parsed.patternAntipattern.pattern.trim(),
+      antipattern: parsed.patternAntipattern.antipattern.trim(),
+    },
+    clinicalSynthesis: {
+      adverse: parsed.clinicalSynthesis.adverse.trim(),
+      favorable: parsed.clinicalSynthesis.favorable.trim(),
+      conditioning: parsed.clinicalSynthesis.conditioning?.trim() || undefined,
+    },
+    criticalRatios: parsed.criticalRatios.map((r) => ({
+      name: r.name.trim(),
+      numerator: r.numerator.trim(),
+      denominator: r.denominator.trim(),
+      unit: r.unit.trim(),
+      meaning: r.meaning.trim(),
+      generalLow: r.generalLow,
+      generalHigh: r.generalHigh,
+      generalExplanation: r.generalExplanation.trim(),
+      personalizedLow: r.personalizedLow,
+      personalizedHigh: r.personalizedHigh,
+      explanation: r.explanation.trim(),
+    })),
+    decisions: {
+      patient: parsed.decisions.patient.map(parseFindingDecision),
+      ai: parsed.decisions.ai.map(parseFindingDecision),
+    },
+    doctorConversation: parsed.doctorConversation.map((g) => ({
+      group: g.group.trim(),
+      questions: g.questions.map((q) => q.trim()).filter((q) => q.length > 0),
+    })),
+    definitions,
+    healthMarkers,
+    dataRequisition,
+    treatmentGroups: (parsed.treatmentGroups ?? []).map((g) => ({
+      system: g.system.trim(),
+      topic: g.topic.trim(),
+      patient: g.patient.map((s) => s.trim()).filter((s) => s.length > 0),
+      ai: g.ai.map((s) => s.trim()).filter((s) => s.length > 0),
+    })),
+    planAssessment: parsed.planAssessment.trim(),
+    planAssessmentRows: (parsed.planAssessmentRows ?? [])
+      .map((r) => ({ action: r.action.trim(), assessment: r.assessment.trim() }))
+      .filter((r) => r.action.length > 0 && r.assessment.length > 0),
+    finalThoughts: parsed.finalThoughts.trim(),
+    basis: basisFromResponse(parsed.basis),
+    generatedAt: meta.generatedAt,
+    inputsHash: meta.inputsHash,
+    nodeHashes: meta.nodeHashes,
+    // Only `core`, and only the core. The leaf-owned sections this object leaves empty are
+    // written later by mergeLeafResult, which stamps its own key; claiming them here would attribute
+    // nine sections to a brain that never saw them.
+    promptVersions: meta.promptVersions,
+    generatedBy: meta.generatedBy,
+  };
+}
+
+// The finding is no longer grammar-constrained, so tolerate a stray code
+// fence or surrounding prose. Extract the FIRST complete (brace-balanced) JSON
+// object — slicing to the last "}" over-grabs when the model appends extra
+// content after the object (observed: "Unexpected non-whitespace after JSON"),
+// which then fails to parse. Braces inside string literals are ignored.
+export function extractJson(text: string): string {
+  let t = text.trim();
+  const fence = t.match(/^```(?:json)?\s*([\s\S]*?)\s*```$/);
+  if (fence) t = fence[1].trim();
+  const first = t.indexOf("{");
+  if (first < 0) return t;
+  let depth = 0;
+  let inStr = false;
+  let esc = false;
+  for (let i = first; i < t.length; i++) {
+    const ch = t[i];
+    if (inStr) {
+      if (esc) esc = false;
+      else if (ch === "\\") esc = true;
+      else if (ch === '"') inStr = false;
+    } else if (ch === '"') inStr = true;
+    else if (ch === "{") depth++;
+    else if (ch === "}") {
+      depth--;
+      if (depth === 0) return t.slice(first, i + 1);
+    }
+  }
+  return t.slice(first); // unbalanced — let JSON.parse surface the error
+}