@peopl-health/nexus 5.44.0-dev.5327 → 5.44.0-dev.5345

package/lib/clinical/helpers/gradeEstimateHelper.js

@@ -67,7 +67,7 @@ function gradeEstimateSchema(description) {
       functional_anchor: {
         type: 'string',
         enum: FUNCTIONAL_ANCHORS,
-        description: 'What you ESTABLISHED about function, not what the clause says. Required whenever the rubric clause for your grade turns on ADL — grade 2 on instrumental ADL, grade 3 on self-care. `instrumental_adl_limited`: they told you the symptom stops them cooking, working, shopping, driving. `self_care_adl_limited`: it stops them bathing, dressing, feeding themselves. `not_limited`: you asked and it does NOT limit them — then that grade is ruled out, so assign the grade below rather than widening the range. `not_established`: you have not asked — then the grade below stays inside possible_range.',
+        description: 'What you ESTABLISHED about function, not what the clause says. Required whenever the rubric clause for your grade turns on ADL — grade 2 on instrumental ADL, grade 3 on self-care. `instrumental_adl_limited`: they told you the symptom stops them cooking, working, shopping, driving. `self_care_adl_limited`: it stops them bathing, dressing, feeding themselves. `not_limited`: you asked and it does NOT limit them — then that grade is ruled out, so assign the grade below rather than widening the range. `not_established`: you have not asked — then that grade is not yours to assert yet: put the grade below in best_estimate and leave the higher one live in possible_range. The exception is a grade the case already holds on a limitation established earlier in this same episode: there `not_established` just means you did not re-ask, and the grade stands.',
       },
       source: {
         type: 'string',

package/lib/clinical/services/gradeAnchorService.js

@@ -32,7 +32,7 @@ function anchorLeanedOnBy(ctcaeTerm, grade) {
   return null;
 }
 
-function gradeAnchorError({ ctcaeTerm, grade, anchor, possibleRange }) {
+function gradeAnchorError({ ctcaeTerm, grade, anchor, possibleRange, previous = null, continuesEpisode = false }) {
   const leaned = anchorLeanedOnBy(ctcaeTerm, grade);
   if (!leaned) return null;
   const named = leaned === 'self_care' ? 'self-care' : 'instrumental';
@@ -41,14 +41,19 @@ function gradeAnchorError({ ctcaeTerm, grade, anchor, possibleRange }) {
       + `Say what you established — ${FUNCTIONAL_ANCHORS.join(', ')} — rather than restating the clause.`;
   }
   if (SATISFIED_BY[leaned].has(anchor)) return null;
+  // The case already holds this grade on an anchor established earlier. 'not_established' here
+  // says "I did not re-ask this turn", not "nobody ever established it" — holding is honest.
+  if (anchor === 'not_established' && continuesEpisode && previous
+    && previous.bestEstimate === grade && SATISFIED_BY[leaned].has(previous.functionalAnchor)) return null;
   const below = grade - 1;
   if (anchor === 'not_limited') {
     return `functional_anchor is 'not_limited', so the ${named} ADL limitation that grade ${grade} of ${ctcaeTerm} turns on is ruled OUT, not merely unknown. `
       + `Assign grade ${below} — the highest grade whose clause the evidence actually satisfies.`;
   }
-  if (Array.isArray(possibleRange) && possibleRange[0] <= below) return null;
-  return `functional_anchor is '${anchor}', but grade ${grade} of ${ctcaeTerm} turns on ${named} ADL, `
-    + `so grade ${below} is still live: set possible_range to [${below}, ${Array.isArray(possibleRange) ? possibleRange[1] : grade}], or establish the ${named} ADL limitation before asserting ${grade}.`;
+  const top = Array.isArray(possibleRange) ? possibleRange[1] : grade;
+  return `functional_anchor is '${anchor}', so the ${named} ADL limitation that grade ${grade} of ${ctcaeTerm} turns on is not established. `
+    + `best_estimate is the grade the evidence already carries, not the one it might reach: assign ${below} and keep ${grade} live as possible_range [${below}, ${top}]. `
+    + `Establish the ${named} ADL limitation and ${grade} becomes assertable.`;
 }
 
 module.exports = {

package/lib/clinical/services/gradeClaimService.js

@@ -24,17 +24,19 @@ const GUARDS = [
     hasLadder: hasCuratedLadder(ctcaeTerm),
     trace,
   }),
-  ({ ctcaeTerm, grade }) => gradeAnchorError({
+  ({ ctcaeTerm, grade, previous, continuesEpisode }) => gradeAnchorError({
     ctcaeTerm,
     grade: grade.bestEstimate ?? null,
     anchor: grade.functionalAnchor ?? null,
     possibleRange: grade.possibleRange ?? null,
+    previous,
+    continuesEpisode,
   }),
 ];
 
-function gradeClaimError({ ctcaeTerm, grade, stated = null, previous = null, restatesPriorEvidence = true, trace = null }) {
+function gradeClaimError({ ctcaeTerm, grade, stated = null, previous = null, restatesPriorEvidence = true, continuesEpisode = false, trace = null }) {
   const resolved = grade || {};
-  const claim = { ctcaeTerm, grade: resolved, stated: stated || resolved, previous, restatesPriorEvidence, trace };
+  const claim = { ctcaeTerm, grade: resolved, stated: stated || resolved, previous, restatesPriorEvidence, continuesEpisode, trace };
   for (const guard of GUARDS) {
     const error = guard(claim);
     if (error) return error;

package/lib/clinical/tools/recordClinicalImpressionTool.js

@@ -78,9 +78,12 @@ const EVENTS = definition.parameters.properties.event.enum;
 const TRAJECTORIES = definition.parameters.properties.trajectory_direction.enum;
 const POSTURES = definition.parameters.properties.decision_posture.enum;
 
+// Only new_episode starts a fresh episode; every other event acts on the one the case holds.
+const normalisedEvent = (args) => (typeof args?.event === 'string' ? args.event : '').trim().toLowerCase();
+
 const uid = (prefix) => `${prefix}_${crypto.randomUUID().replace(/-/g, '').slice(0, 12)}`;
 
-function coerceGrade(raw, base) {
+function coerceGrade(raw, base, continuesEpisode = false) {
   if (isCarriedForward(raw)) {
     const parsed = parseGradeEstimate(raw);
     if (parsed?.error) return parsed;
@@ -89,7 +92,13 @@ function coerceGrade(raw, base) {
   if (!hasGradeSignal(raw)) return base;
   const parsed = parseGradeEstimate(raw);
   if (parsed?.error) return parsed;
-  if (parsed.functionalAnchor === null && parsed.bestEstimate === base?.bestEstimate) {
+  // The anchor records the case's functional state, not whether this turn re-asked. An unchanged
+  // grade keeps the anchor already established, so the finding survives more than one quiet turn.
+  const holdsGrade = parsed.bestEstimate === base?.bestEstimate;
+  const notReasked = parsed.functionalAnchor === null || parsed.functionalAnchor === 'not_established';
+  if (continuesEpisode && holdsGrade && notReasked && base?.functionalAnchor) {
+    parsed.functionalAnchor = base.functionalAnchor;
+  } else if (parsed.functionalAnchor === null && holdsGrade) {
     parsed.functionalAnchor = base?.functionalAnchor ?? null;
   }
   return parsed;
@@ -98,7 +107,8 @@ function coerceGrade(raw, base) {
 const statesTrajectory = (args) => args?.trajectory_direction !== null && args?.trajectory_direction !== undefined;
 
 function buildAssessment(condition, previous, args, runtime, restatesPriorEvidence = false) {
-  const grade = coerceGrade(args?.grade_estimate, previous.grade);
+  const continuesEpisode = normalisedEvent(args) !== 'new_episode';
+  const grade = coerceGrade(args?.grade_estimate, previous.grade, continuesEpisode);
   if (grade?.error) return grade;
   if (hasGradeSignal(args?.grade_estimate)) {
     const claimGap = gradeClaimError({
@@ -107,6 +117,7 @@ function buildAssessment(condition, previous, args, runtime, restatesPriorEviden
       stated: parseGradeEstimate(args.grade_estimate),
       previous: previous.grade,
       restatesPriorEvidence,
+      continuesEpisode,
       trace: runtime?.trace || null,
     });
     if (claimGap) return { error: claimGap };
@@ -280,7 +291,7 @@ async function handler(args = {}, context = {}) {
       return JSON.stringify({ success: false, error: 'recordClinicalImpression requires an active turn context (turnId, patientCode).', data: {} });
     }
     const caseId = (typeof args?.case_id === 'string' ? args.case_id : '').trim();
-    const event = (typeof args?.event === 'string' ? args.event : '').trim().toLowerCase();
+    const event = normalisedEvent(args);
     if (!caseId) return fail('case_id is required');
     if (!EVENTS.includes(event)) {
       return fail(`unknown event: '${event}'. Must be one of ${EVENTS.join(' | ')}.`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peopl-health/nexus",
-  "version": "5.44.0-dev.5327",
+  "version": "5.44.0-dev.5345",
   "description": "Core messaging and assistant library for WhatsApp communication platforms",
   "keywords": [
     "whatsapp",