@peopl-health/nexus 5.44.0-dev.5374 → 5.44.0-dev.5376

package/lib/clinical/helpers/gradeEstimateHelper.js

@@ -4,7 +4,7 @@ const { MEDICATION_NAMING_RULE } = require('./medicationNamingRule');
 const CARRIED_FORWARD = 'carried_forward';
 
 function parseGradeEstimate(raw) {
-  const grade = { bestEstimate: null, confidence: null, possibleRange: null, functionalAnchor: null, source: null, matchedGrade: null, reasoning: '' };
+  const grade = { bestEstimate: null, confidence: null, possibleRange: null, functionalAnchor: null, source: null, matchedGrade: null, improvementBasis: null, reasoning: '' };
   if (!raw || typeof raw !== 'object') return grade;
   if (raw.best_estimate !== null && raw.best_estimate !== undefined) {
     if (!inGradeRange(raw.best_estimate)) return { error: 'grade_out_of_range' };
@@ -37,6 +37,7 @@ function parseGradeEstimate(raw) {
     && (grade.bestEstimate < grade.possibleRange[0] || grade.bestEstimate > grade.possibleRange[1])) {
     return { error: 'grade_out_of_range' };
   }
+  if (typeof raw.improvement_basis === 'string' && raw.improvement_basis.trim()) grade.improvementBasis = raw.improvement_basis.trim();
   if (typeof raw.reasoning === 'string') grade.reasoning = raw.reasoning;
   return grade;
 }
@@ -69,6 +70,10 @@ function gradeEstimateSchema(description) {
         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 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.',
       },
+      improvement_basis: {
+        type: ['string', 'null'],
+        description: 'REQUIRED when best_estimate is lower than the grade this case already holds. Name the finding that no longer holds, in the patient\'s own terms — what they can do again, or the symptom that stopped. A grade only comes down when something specific resolved; "mejoró un poco" is not that, and neither is the absence of new complaints.',
+      },
       source: {
         type: 'string',
         enum: GRADE_SOURCES,
@@ -88,6 +93,10 @@ function gradeEstimateSchema(description) {
   };
 }
 
+// improvement_basis explains a downgrade in prose. It renders and it persists, but it is not part
+// of the clinical read, so it never decides whether a repeated mention moved anything.
+const GRADE_READ_FIELDS = ['best_estimate', 'confidence', 'possible_range', 'functional_anchor', 'source', 'matched_grade'];
+
 function projectGradeEstimate(grade) {
   return {
     best_estimate: grade?.bestEstimate ?? null,
@@ -96,9 +105,15 @@ function projectGradeEstimate(grade) {
     functional_anchor: grade?.functionalAnchor ?? null,
     source: grade?.source ?? null,
     matched_grade: grade?.matchedGrade ?? null,
+    improvement_basis: grade?.improvementBasis ?? null,
   };
 }
 
+function projectGradeRead(grade) {
+  const projected = projectGradeEstimate(grade);
+  return GRADE_READ_FIELDS.reduce((out, key) => Object.assign(out, { [key]: projected[key] }), {});
+}
+
 function hasGradeSignal(raw) {
   return !!raw && typeof raw === 'object'
     && ['best_estimate', 'possible_range', 'confidence', 'functional_anchor', 'source', 'matched_grade']
@@ -112,6 +127,7 @@ function isCarriedForward(raw) {
 module.exports = {
   gradeEstimateSchema,
   projectGradeEstimate,
+  projectGradeRead,
   hasGradeSignal,
   isCarriedForward,
   CARRIED_FORWARD,

package/lib/clinical/monitoring/contingencyMonitorSpec.js

@@ -224,11 +224,14 @@ function timelineStep(step, callIndex) {
   };
 }
 
+const MONITOR_GRADE_FIELDS = ['best_estimate', 'confidence', 'possible_range', 'functional_anchor', 'source', 'matched_grade'];
+
 function gradedNumbers(raw) {
   if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
   const parsed = parseGradeEstimate(raw);
   if (parsed.error) return null;
-  return projectGradeEstimate(parsed);
+  const projected = projectGradeEstimate(parsed);
+  return MONITOR_GRADE_FIELDS.reduce((out, key) => Object.assign(out, { [key]: projected[key] ?? null }), {});
 }
 
 function gradingStep(step) {

package/lib/clinical/services/gradeClaimService.js

@@ -1,8 +1,34 @@
 const { CARRIED_FORWARD, parseGradeEstimate } = require('../helpers/gradeEstimateHelper');
-const { gradeAnchorError, hasCuratedLadder } = require('./gradeAnchorService');
+const { gradeAnchorError, hasCuratedLadder, anchorLeanedOnBy } = require('./gradeAnchorService');
 const { gradeSourceError, carriedForwardError } = require('./gradeSourceService');
 
+// A resolution names a finding. Length is not the test: 'ya come' names one and 'mejoró un poco'
+// does not, however long it runs. Reject the placeholders and the bare comparatives instead.
+const EMPTY_BASIS = new Set(['n/a', 'na', 'none', 'ninguno', 'ninguna', 'nada', '-', '--', '?', 'null', 'n/d', 'ok']);
+const VAGUE_BASIS = /^(algo |un poco |bastante |ya )?(mejor|mejoría|mejoria|mejorando|mejor[oó])( un poco| algo| bastante)?$|^(sin cambios|va mejor|menos|menos molestias?|todo bien|estable)$/i;
+const namesAResolution = (basis) => {
+  const text = String(basis || '').trim().replace(/[.!]+$/, '');
+  if (text.length < 4) return false;
+  if (EMPTY_BASIS.has(text.toLowerCase())) return false;
+  return !VAGUE_BASIS.test(text);
+};
+
 const GUARDS = [
+  ({ ctcaeTerm, grade, previous, recordsOngoingRead }) => {
+    if (!recordsOngoingRead) return null;
+    const now = grade.bestEstimate;
+    const before = previous && previous.bestEstimate;
+    if (!Number.isInteger(now) || !Number.isInteger(before) || now >= before) return null;
+    // Only 'not_established' is exempt. It means the question was not asked, so the drop is the
+    // anchor guard's own remediation rather than a claim that anything got better. 'not_limited'
+    // is the opposite: the question WAS asked and the limitation is gone — a finding, and the
+    // thing this field exists to record.
+    if (grade.functionalAnchor === 'not_established' && now === before - 1 && anchorLeanedOnBy(ctcaeTerm, before)) return null;
+    if (namesAResolution(grade.improvementBasis)) return null;
+    return `best_estimate ${now} is below the grade ${before} this case already holds, so this call records an improvement. `
+      + 'Name what resolved in `improvement_basis`: the finding that no longer holds, in the patient\'s own terms — a placeholder is not one. '
+      + `If nothing specific resolved, the case still carries grade ${before} — keep it, and put ${now} in possible_range as where it may be heading.`;
+  },
   ({ stated, previous, restatesPriorEvidence }) => {
     if (stated.source !== CARRIED_FORWARD) return null;
     if (!previous) {
@@ -34,9 +60,9 @@ const GUARDS = [
   }),
 ];
 
-function gradeClaimError({ ctcaeTerm, grade, stated = null, previous = null, restatesPriorEvidence = true, continuesEpisode = false, trace = null }) {
+function gradeClaimError({ ctcaeTerm, grade, stated = null, previous = null, restatesPriorEvidence = true, continuesEpisode = false, recordsOngoingRead = false, trace = null }) {
   const resolved = grade || {};
-  const claim = { ctcaeTerm, grade: resolved, stated: stated || resolved, previous, restatesPriorEvidence, continuesEpisode, trace };
+  const claim = { ctcaeTerm, grade: resolved, stated: stated || resolved, previous, restatesPriorEvidence, continuesEpisode, recordsOngoingRead, trace };
   for (const guard of GUARDS) {
     const error = guard(claim);
     if (error) return error;

package/lib/clinical/tools/recordClinicalImpressionTool.js

@@ -1,6 +1,6 @@
 const crypto = require('node:crypto');
 
-const { CARRIED_FORWARD, GRADE_CONFIDENCE_LEVELS, GRADE_MIN, GRADE_MAX, gradeEstimateSchema, parseGradeEstimate, projectGradeEstimate, hasGradeSignal, isCarriedForward } = require('../helpers/gradeEstimateHelper');
+const { CARRIED_FORWARD, GRADE_CONFIDENCE_LEVELS, GRADE_MIN, GRADE_MAX, gradeEstimateSchema, parseGradeEstimate, projectGradeEstimate, projectGradeRead, hasGradeSignal, isCarriedForward } = require('../helpers/gradeEstimateHelper');
 const { ceilingGapError } = require('../helpers/ceilingGapHelper');
 const { mentionProvenanceError } = require('../helpers/evidenceAnchorHelper');
 const { MEDICATION_NAMING_RULE } = require('../helpers/medicationNamingRule');
@@ -106,6 +106,8 @@ function coerceGrade(raw, base, continuesEpisode = false) {
 
 const statesTrajectory = (args) => args?.trajectory_direction !== null && args?.trajectory_direction !== undefined;
 
+const ONGOING_READ_EVENTS = ['add_evidence', 'new_episode'];
+
 function buildAssessment(condition, previous, args, runtime, restatesPriorEvidence = false) {
   const continuesEpisode = normalisedEvent(args) !== 'new_episode';
   const grade = coerceGrade(args?.grade_estimate, previous.grade, continuesEpisode);
@@ -118,6 +120,7 @@ function buildAssessment(condition, previous, args, runtime, restatesPriorEviden
       previous: previous.grade,
       restatesPriorEvidence,
       continuesEpisode,
+      recordsOngoingRead: ONGOING_READ_EVENTS.includes(normalisedEvent(args)),
       trace: runtime?.trace || null,
     });
     if (claimGap) return { error: claimGap };
@@ -171,7 +174,7 @@ function requireCeilingGap(args, event) {
 }
 
 function sameGrade(a, b) {
-  return JSON.stringify(projectGradeEstimate(a)) === JSON.stringify(projectGradeEstimate(b));
+  return JSON.stringify(projectGradeRead(a)) === JSON.stringify(projectGradeRead(b));
 }
 
 function movesTheRead(previous, next) {

package/lib/fhir/constants/extensionSlugs.js

@@ -40,6 +40,7 @@ const GRADE_EXT = {
   THRESHOLD_CLAUSE: 'grade-threshold-clause',
   FUNCTIONAL_ANCHOR: 'grade-functional-anchor',
   MATCHED_GRADE: 'grade-matched-clause',
+  IMPROVEMENT_BASIS: 'grade-improvement-basis',
 };
 
 const MENTION_EXT = {

package/lib/fhir/projections/symptomCaseProjection.js

@@ -48,7 +48,7 @@ function caseProvenance(anchorId, recordedAt, targetRefs) {
 function assessmentResources(assessment, placeholderIds) {
   const grade = assessment.grade;
   const hasGradeSignal = grade.bestEstimate !== null || grade.possibleRange !== null
-    || grade.matchedGrade !== null || grade.functionalAnchor !== null
+    || grade.matchedGrade !== null || grade.functionalAnchor !== null || Boolean(grade.improvementBasis)
     || Boolean(grade.confidence) || Boolean(grade.reasoning) || Boolean(assessment.gradeThresholdClause);
   const out = [impressionResource(assessment, placeholderIds, hasGradeSignal)];
   if (hasGradeSignal) out.push(gradeResource(assessment));
@@ -170,6 +170,7 @@ function gradeExtensions(assessment) {
   if (grade.reasoning) out.push(extension(GRADE_EXT.REASONING, { valueString: grade.reasoning }));
   if (grade.functionalAnchor !== null) out.push(extension(GRADE_EXT.FUNCTIONAL_ANCHOR, { valueString: grade.functionalAnchor }));
   if (grade.matchedGrade !== null) out.push(extension(GRADE_EXT.MATCHED_GRADE, { valueString: String(grade.matchedGrade) }));
+  if (grade.improvementBasis) out.push(extension(GRADE_EXT.IMPROVEMENT_BASIS, { valueString: grade.improvementBasis }));
   if (assessment.gradeVerification) out.push(extension(GRADE_EXT.VERIFICATION, { valueString: assessment.gradeVerification }));
   if (assessment.gradeThresholdClause) out.push(extension(GRADE_EXT.THRESHOLD_CLAUSE, { valueString: assessment.gradeThresholdClause }));
   return out;
@@ -251,7 +252,7 @@ function reconstructAssessment(impression, { patientId, conditionId, previousId
 }
 
 function reconstructGrade(obs) {
-  const grade = { bestEstimate: null, confidence: null, possibleRange: null, functionalAnchor: null, source: null, matchedGrade: null, reasoning: '' };
+  const grade = { bestEstimate: null, confidence: null, possibleRange: null, functionalAnchor: null, source: null, matchedGrade: null, improvementBasis: null, reasoning: '' };
   if (!obs) return grade;
   const ext = extMap(obs);
   if (typeof obs.valueInteger === 'number') grade.bestEstimate = obs.valueInteger;
@@ -261,6 +262,7 @@ function reconstructGrade(obs) {
     if (Number.isInteger(lo) && Number.isInteger(hi)) grade.possibleRange = [lo, hi];
   }
   if (ext[GRADE_EXT.FUNCTIONAL_ANCHOR]) grade.functionalAnchor = ext[GRADE_EXT.FUNCTIONAL_ANCHOR];
+  if (typeof ext[GRADE_EXT.IMPROVEMENT_BASIS] === 'string') grade.improvementBasis = ext[GRADE_EXT.IMPROVEMENT_BASIS];
   if (ext[GRADE_EXT.MATCHED_GRADE]) {
     const matched = Number(ext[GRADE_EXT.MATCHED_GRADE]);
     if (inGradeRange(matched)) grade.matchedGrade = matched;

package/lib/shared/dtos/ManagedSymptom.js

@@ -25,6 +25,7 @@ const gradeEstimateSchema = z.strictObject({
   functionalAnchor: z.enum(FUNCTIONAL_ANCHORS).nullable().default(null),
   source: z.enum(GRADE_SOURCES).nullable().default(null),
   matchedGrade: gradeNumber.nullable().default(null),
+  improvementBasis: z.string().nullable().default(null),
   reasoning: z.string().default(''),
 })
   .refine((g) => g.possibleRange === null || g.possibleRange[0] <= g.possibleRange[1], {

package/package.json

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