@peopl-health/nexus 5.10.0-dev.1026 → 5.10.0-dev.1035

package/lib/clinical/helpers/palliativeAssessmentHelper.js

@@ -0,0 +1,62 @@
+const crypto = require('node:crypto');
+
+const { PalliativeAssessment } = require('../../shared/dtos/PalliativeAssessment');
+
+const uid = (prefix) => `${prefix}_${crypto.randomUUID().replace(/-/g, '').slice(0, 12)}`;
+
+function assessmentUid() {
+  return uid('pa');
+}
+
+function mapEscalation(raw, patientId) {
+  if (!raw || typeof raw !== 'object') return null;
+  return {
+    patientId,
+    maxActionTimeHours: raw.max_action_time_hours,
+    escalationRoutes: raw.escalation_routes || [],
+    escalationReason: raw.escalation_reason || '',
+  };
+}
+
+function mapFinding(raw, patientId) {
+  if (!raw || typeof raw !== 'object') return {};
+  return {
+    rank: raw.rank,
+    elementType: raw.element_type,
+    nameShort: raw.name_short,
+    timeWindow: raw.time_window || '',
+    symptomTerms: raw.symptom_terms || [],
+    clinicalDescription: raw.clinical_description || '',
+    whyRelevant: raw.why_relevant || '',
+    qolImpact: raw.qol_impact ?? null,
+    qolCriteria: raw.qol_criteria || '',
+    improvementCapacity: raw.improvement_capacity ?? null,
+    improvementCriteria: raw.improvement_criteria || '',
+    areMedsNeeded: raw.are_meds_needed ?? null,
+    needsCharacterization: raw.needs_characterization ?? null,
+    characterizationCriteria: raw.characterization_criteria || '',
+    probeQuestions: raw.probe_questions || [],
+    auditNotes: raw.audit_notes || '',
+    clusterNote: raw.cluster_note ?? null,
+    escalation: mapEscalation(raw.escalation, patientId),
+  };
+}
+
+function buildAssessment({ raw, assessmentId, patientId, turnId, committedAt }) {
+  const findings = Array.isArray(raw.findings) ? raw.findings : [];
+  return new PalliativeAssessment({
+    assessmentId,
+    patientId,
+    turnId,
+    committedAt,
+    evaluationSummary: raw.evaluation_summary || '',
+    rankingRationale: raw.ranking_rationale || '',
+    escalationReason: raw.escalation_reason ?? null,
+    findings: findings.map((finding) => mapFinding(finding, patientId)),
+  });
+}
+
+module.exports = {
+  assessmentUid,
+  buildAssessment,
+};

package/lib/clinical/tools/{getPatientRiskProfileTool.js → getPatientRiskAssessmentTool.js}

@@ -1,8 +1,8 @@
 const { readPatientRisk } = require('../../fhir');
 
 const definition = {
-  name: 'getPatientRiskProfile',
-  description: '**Does:** Returns the patient\'s persistent risk profile — predicted adverse events, disease risks, and comorbidity amplifiers derived from their regimen. Read-only.\n\n**Required inputs:** none.\n\n**When to call:** before routing, to anticipate which adverse events or complications the current regimen makes plausible.\n\n**Returns:** `status` (`final` when a profile exists, `not_generated` otherwise) and `profile` (`assessment_id`, `source_regimen`, `source_diagnosis`, `source_phase`, `predicted_aes[]`, `disease_risks[]`, `comorbidity_amplifiers[]`, `assessed_at`, `assessed_by_model`) — `null` when not yet generated.',
+  name: 'getPatientRiskAssessment',
+  description: '**Does:** Returns the patient\'s persistent risk assessment — predicted adverse events, disease risks, and comorbidity amplifiers derived from their regimen. Read-only.\n\n**Required inputs:** none.\n\n**When to call:** before routing, to anticipate which adverse events or complications the current regimen makes plausible.\n\n**Returns:** `status` (`final` when an assessment exists, `not_generated` otherwise) and `profile` (`assessment_id`, `source_regimen`, `source_diagnosis`, `source_phase`, `predicted_aes[]`, `disease_risks[]`, `comorbidity_amplifiers[]`, `assessed_at`, `assessed_by_model`) — `null` when not yet generated.',
   strict: false,
   parameters: {
     type: 'object',
@@ -55,12 +55,12 @@ async function handler(_args = {}, context = {}) {
   try {
     const runtime = context?.toolRuntimeContext || null;
     if (!runtime?.turnId || !runtime?.patientCode) {
-      return JSON.stringify({ success: false, error: 'getPatientRiskProfile requires an active turn context (turnId, patientCode).', data: {} });
+      return JSON.stringify({ success: false, error: 'getPatientRiskAssessment requires an active turn context (turnId, patientCode).', data: {} });
     }
     const data = await assembleRiskProfile(runtime.patientCode);
     return JSON.stringify({ success: true, data });
   } catch (err) {
-    return JSON.stringify({ success: false, error: err?.message || 'getPatientRiskProfile failed', data: {} });
+    return JSON.stringify({ success: false, error: err?.message || 'getPatientRiskAssessment failed', data: {} });
   }
 }
 

package/lib/clinical/tools/getRouterContextBundleTool.js

@@ -1,6 +1,6 @@
 const { assembleLandscape } = require('./getActiveSymptomLandscapeTool');
 const { assembleHistory, SUPPORTED_SCOPES, TIMEFRAME_DAYS } = require('./getPatientHistoryTool');
-const { assembleRiskProfile } = require('./getPatientRiskProfileTool');
+const { assembleRiskProfile } = require('./getPatientRiskAssessmentTool');
 
 const ALLOWED_SECTIONS = ['landscape', 'history', 'risk'];
 

package/lib/clinical/tools/registerClinicalTools.js

@@ -17,7 +17,7 @@ const TOOLS = [
   require('./getActiveSymptomLandscapeTool'),
   require('./recordInterventionTool'),
   require('./setContingencyPlanTool'),
-  require('./getPatientRiskProfileTool'),
+  require('./getPatientRiskAssessmentTool'),
   require('./getPatientHistoryTool'),
   require('./getRouterContextBundleTool'),
   require('./deliverPatientMessageTool'),

package/lib/clinical/tools/submitPalliativeAssessmentTool.js

@@ -0,0 +1,75 @@
+const { assessmentUid, buildAssessment } = require('../helpers/palliativeAssessmentHelper');
+const { storePalliativeAssessment, readPalliativeByTurn } = require('../../fhir');
+const { fhirId } = require('../../fhir/helpers/fhirHelper');
+
+const definition = {
+  name: 'submitPalliativeAssessment',
+  description: '**Does:** Terminal Phase-1 commit of the `accompaniment` skill — persists a structured palliative assessment with ranked `findings[]` covering symptoms, QoL impact, improvement capacity, need characterization, and urgent-under-24h escalation.\n\n**Required inputs:** `assessment` (one object) with `findings[]` — each `{rank, element_type (cluster|individual), name_short, time_window, symptom_terms[], clinical_description, why_relevant, qol_impact (Low|Medium|High), qol_criteria, improvement_capacity (Low|Medium|High), improvement_criteria, are_meds_needed, needs_characterization, characterization_criteria, probe_questions[], audit_notes, cluster_note, escalation}` — plus `evaluation_summary`, `ranking_rationale`, `escalation_reason`. An `escalation` (`{max_action_time_hours 1-24, escalation_routes[], escalation_reason}`) is present only for a finding urgent under 24h.\n\n**When NOT to call:**\n- Twice in the same turn — fail-hard dedup, returns `assessment_already_committed_for_turn`.\n- To CORRECT a committed assessment — use `updatePalliativeAssessment` (full-replacement) instead.\n\n**Returns:** `accepted`, `assessment_id`, `turn_id`, `committed_at`, `element_count`.\n\n**Side effects:** persists the assessment as a FHIR `ClinicalImpression` (+ a `Task` per urgent finding) + `Provenance`.',
+  strict: false,
+  parameters: {
+    type: 'object',
+    properties: {
+      assessment: {
+        type: 'object',
+        description: 'The full palliative assessment. `findings[]` (ranked, contiguous): each finding carries its clinical shape and an optional `escalation` for urgent-under-24h items. Plus `evaluation_summary`, `ranking_rationale`, `escalation_reason`.',
+      },
+    },
+    required: ['assessment'],
+  },
+};
+
+function fail(error, data = {}) {
+  return JSON.stringify({ success: false, error, data });
+}
+
+async function handler(args = {}, context = {}) {
+  try {
+    const runtime = context?.toolRuntimeContext || null;
+    if (!runtime?.turnId || !runtime?.patientCode) {
+      return fail('submitPalliativeAssessment requires an active turn context (turnId, patientCode).');
+    }
+    const raw = args?.assessment;
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+      return fail('assessment is required (non-empty object)');
+    }
+
+    const patientId = runtime.patientCode;
+    const turnId = runtime.turnId;
+
+    const existing = await readPalliativeByTurn({ patientId, turnId });
+    if (existing) {
+      return fail('assessment_already_committed_for_turn', { existing_assessment_id: fhirId(existing.assessmentId), turn_id: turnId });
+    }
+
+    const assessment = buildAssessment({
+      raw,
+      assessmentId: assessmentUid(),
+      patientId,
+      turnId,
+      committedAt: new Date().toISOString(),
+    });
+    await storePalliativeAssessment({ patientId, assessment });
+
+    const assessmentId = fhirId(assessment.assessmentId);
+    runtime.setPalliativeAssessment({ assessmentId, turnId });
+    runtime.trace.setSignals({ palliativeAssessmentId: assessmentId });
+
+    return JSON.stringify({
+      success: true,
+      data: {
+        accepted: true,
+        assessment_id: assessmentId,
+        turn_id: turnId,
+        committed_at: assessment.committedAt,
+        element_count: assessment.findings.length,
+      },
+    });
+  } catch (err) {
+    return JSON.stringify({ success: false, error: err?.message || 'submitPalliativeAssessment failed', data: {} });
+  }
+}
+
+module.exports = {
+  definition,
+  handler,
+};

package/lib/clinical/tools/updatePalliativeAssessmentTool.js

@@ -0,0 +1,74 @@
+const { assessmentUid, buildAssessment } = require('../helpers/palliativeAssessmentHelper');
+const { storePalliativeAssessment, readPalliativeByTurn } = require('../../fhir');
+const { fhirId } = require('../../fhir/helpers/fhirHelper');
+
+const definition = {
+  name: 'updatePalliativeAssessment',
+  description: '**Does:** Full-replacement correction path for the Phase-1 palliative assessment — issues a NEW assessment (new `assessment_id`); it is NOT a field-level patch. The prior assessment_id is returned as `replaced_prior_assessment_id` for audit lineage.\n\n**Required inputs:** `assessment` (one object, identical shape to `submitPalliativeAssessment`).\n\n**When NOT to call:**\n- Before a Phase-1 assessment exists for the turn — returns `no_assessment_to_update`; call `submitPalliativeAssessment` first.\n\n**Returns:** `accepted`, `assessment_id` (new), `replaced_prior_assessment_id`, `turn_id`.\n\n**Side effects:** persists a replacement FHIR `ClinicalImpression` (+ a `Task` per urgent finding) + `Provenance`.',
+  strict: false,
+  parameters: {
+    type: 'object',
+    properties: {
+      assessment: {
+        type: 'object',
+        description: 'The corrected palliative assessment — full replacement, same shape as submitPalliativeAssessment.',
+      },
+    },
+    required: ['assessment'],
+  },
+};
+
+function fail(error, data = {}) {
+  return JSON.stringify({ success: false, error, data });
+}
+
+async function handler(args = {}, context = {}) {
+  try {
+    const runtime = context?.toolRuntimeContext || null;
+    if (!runtime?.turnId || !runtime?.patientCode) {
+      return fail('updatePalliativeAssessment requires an active turn context (turnId, patientCode).');
+    }
+    const raw = args?.assessment;
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+      return fail('assessment is required (non-empty object)');
+    }
+
+    const patientId = runtime.patientCode;
+    const turnId = runtime.turnId;
+
+    const prior = await readPalliativeByTurn({ patientId, turnId });
+    if (!prior) {
+      return fail('no_assessment_to_update — call submitPalliativeAssessment first', { turn_id: turnId });
+    }
+
+    const assessment = buildAssessment({
+      raw,
+      assessmentId: assessmentUid(),
+      patientId,
+      turnId,
+      committedAt: new Date().toISOString(),
+    });
+    await storePalliativeAssessment({ patientId, assessment });
+
+    const assessmentId = fhirId(assessment.assessmentId);
+    runtime.setPalliativeAssessment({ assessmentId, turnId });
+    runtime.trace.setSignals({ palliativeAssessmentId: assessmentId });
+
+    return JSON.stringify({
+      success: true,
+      data: {
+        accepted: true,
+        assessment_id: assessmentId,
+        replaced_prior_assessment_id: fhirId(prior.assessmentId),
+        turn_id: turnId,
+      },
+    });
+  } catch (err) {
+    return JSON.stringify({ success: false, error: err?.message || 'updatePalliativeAssessment failed', data: {} });
+  }
+}
+
+module.exports = {
+  definition,
+  handler,
+};

package/lib/fhir/constants/projectionSlugs.js

@@ -19,6 +19,8 @@ const CLUSTER_IMPRESSION_SLUG = 'cluster-impression';
 const CLUSTER_LABEL_SLUG = 'cluster-label';
 const ROUTING_ASSESSMENT_SLUG = 'routing-assessment';
 const ROUTING_DISPOSITION_SLUG = 'routing-disposition';
+const PALLIATIVE_ASSESSMENT_SLUG = 'palliative-assessment';
+const PALLIATIVE_ESCALATION_SLUG = 'palliative-escalation';
 
 module.exports = {
   MENTION_SLUG,
@@ -42,4 +44,6 @@ module.exports = {
   CLUSTER_LABEL_SLUG,
   ROUTING_ASSESSMENT_SLUG,
   ROUTING_DISPOSITION_SLUG,
+  PALLIATIVE_ASSESSMENT_SLUG,
+  PALLIATIVE_ESCALATION_SLUG,
 };

package/lib/fhir/index.js

@@ -7,6 +7,7 @@ const { storeContingency, readContingencies } = require('./services/contingencyS
 const { storeIntervention, readInterventions } = require('./services/interventionService');
 const { storeCluster, readClusters } = require('./services/clusterService');
 const { storeRoutingDecision, readRoutingByTurn } = require('./services/routingService');
+const { storePalliativeAssessment, readPalliativeByTurn } = require('./services/palliativeService');
 const { storeTriage } = require('./services/triageService');
 const { patientSnapshot } = require('./services/snapshotService');
 const { registerAllProjectors } = require('./projections/registerProjectors');
@@ -40,6 +41,8 @@ module.exports = {
   readClusters,
   storeRoutingDecision,
   readRoutingByTurn,
+  storePalliativeAssessment,
+  readPalliativeByTurn,
   storeTriage,
   patientSnapshot,
   getFhirStore,

package/lib/fhir/projections/palliativeProjection.js

@@ -0,0 +1,37 @@
+const { getDeviceId } = require('../config/fhirConfig');
+const { fhirId } = require('../helpers/fhirHelper');
+const { ClinicalImpression } = require('../resources/ClinicalImpression');
+const { Task } = require('../resources/Task');
+const { Provenance } = require('../resources/Provenance');
+
+const PROJECTOR_NAME = 'palliativeAssessment';
+const ACTIVITY_TEXT = 'palliative-assessment';
+
+function projectPalliativeAssessment(assessment) {
+  const deviceId = getDeviceId();
+  const impression = ClinicalImpression.fromPalliativeAssessment({ assessment });
+  const tasks = assessment.findings
+    .filter((finding) => finding.escalation !== null)
+    .map((finding) => Task.fromPalliativeEscalation({
+      assessmentId: assessment.assessmentId,
+      committedAt: assessment.committedAt,
+      finding,
+      deviceId,
+    }));
+  const targetRefs = [
+    { reference: `ClinicalImpression/${fhirId(assessment.assessmentId)}` },
+    ...tasks.map((task) => ({ reference: `Task/${task.id}` })),
+  ];
+  const provenance = Provenance.fromSymptomCase({
+    provenanceId: `${assessment.assessmentId}-prov`,
+    targetRefs,
+    recordedAt: assessment.committedAt,
+    activityText: ACTIVITY_TEXT,
+  });
+  return [impression, ...tasks, provenance];
+}
+
+module.exports = {
+  projectPalliativeAssessment,
+  PROJECTOR_NAME,
+};

package/lib/fhir/projections/registerProjectors.js

@@ -9,6 +9,7 @@ const { projectContingency, PROJECTOR_NAME: CONTINGENCY_PROJECTOR_NAME } = requi
 const { projectIntervention, PROJECTOR_NAME: INTERVENTION_PROJECTOR_NAME } = require('./interventionProjection');
 const { projectCluster, PROJECTOR_NAME: CLUSTER_PROJECTOR_NAME } = require('./clusterProjection');
 const { projectRoutingDecision, PROJECTOR_NAME: ROUTING_PROJECTOR_NAME } = require('./routingProjection');
+const { projectPalliativeAssessment, PROJECTOR_NAME: PALLIATIVE_PROJECTOR_NAME } = require('./palliativeProjection');
 
 const PROJECTORS = [
   { name: MENTION_PROJECTOR_NAME, project: projectClinicalMention },
@@ -21,6 +22,7 @@ const PROJECTORS = [
   { name: INTERVENTION_PROJECTOR_NAME, project: projectIntervention },
   { name: CLUSTER_PROJECTOR_NAME, project: projectCluster },
   { name: ROUTING_PROJECTOR_NAME, project: projectRoutingDecision },
+  { name: PALLIATIVE_PROJECTOR_NAME, project: projectPalliativeAssessment },
 ];
 
 function registerAllProjectors() {

package/lib/fhir/resources/ClinicalImpression.js

@@ -1,6 +1,6 @@
 const { fhirId } = require('../helpers/fhirHelper');
 const { identifier, reference, patientReference, codeableConcept, extension, toIso } = require('../helpers/elementHelper');
-const { SYMPTOM_ASSESSMENT_SLUG, CLUSTER_IMPRESSION_SLUG, CLUSTER_LABEL_SLUG, ROUTING_ASSESSMENT_SLUG } = require('../constants/projectionSlugs');
+const { SYMPTOM_ASSESSMENT_SLUG, CLUSTER_IMPRESSION_SLUG, CLUSTER_LABEL_SLUG, ROUTING_ASSESSMENT_SLUG, PALLIATIVE_ASSESSMENT_SLUG } = require('../constants/projectionSlugs');
 
 const CLUSTER_STATUS_TO_FHIR = { active: 'in-progress', dissolved: 'completed' };
 const CLUSTER_LIST_SEPARATOR = '; ';
@@ -109,6 +109,45 @@ class ClinicalImpression {
     if (assessment.notes.length) payload.note = assessment.notes.map((text) => ({ text }));
     return new ClinicalImpression(payload);
   }
+
+  static fromPalliativeAssessment({ assessment }) {
+    const payload = {
+      resourceType: 'ClinicalImpression',
+      id: fhirId(assessment.assessmentId),
+      identifier: [identifier(PALLIATIVE_ASSESSMENT_SLUG, assessment.assessmentId)],
+      status: 'completed',
+      subject: patientReference(assessment.patientId),
+      effectiveDateTime: toIso(assessment.committedAt),
+      finding: assessment.findings.map(palliativeFinding),
+      extension: [extension('palliative-turn-id', { valueString: assessment.turnId })],
+    };
+    if (assessment.evaluationSummary) payload.summary = assessment.evaluationSummary;
+    if (assessment.rankingRationale) payload.description = assessment.rankingRationale;
+    if (assessment.escalationReason) payload.note = [{ text: assessment.escalationReason }];
+    return new ClinicalImpression(payload);
+  }
+}
+
+function palliativeFinding(finding) {
+  const extensions = [
+    extension('palliative-finding-rank', { valueInteger: finding.rank }),
+    extension('palliative-finding-element-type', { valueString: finding.elementType }),
+    extension('palliative-finding-time-window', { valueString: finding.timeWindow }),
+    extension('palliative-finding-clinical-description', { valueString: finding.clinicalDescription }),
+    extension('palliative-finding-why-relevant', { valueString: finding.whyRelevant }),
+    extension('palliative-finding-qol-criteria', { valueString: finding.qolCriteria }),
+    extension('palliative-finding-improvement-criteria', { valueString: finding.improvementCriteria }),
+    extension('palliative-finding-characterization-criteria', { valueString: finding.characterizationCriteria }),
+    extension('palliative-finding-audit-notes', { valueString: finding.auditNotes }),
+  ];
+  for (const term of finding.symptomTerms) extensions.push(extension('palliative-finding-symptom-term', { valueString: term }));
+  for (const question of finding.probeQuestions) extensions.push(extension('palliative-finding-probe-question', { valueString: question }));
+  if (finding.qolImpact !== null) extensions.push(extension('palliative-finding-qol-impact', { valueString: finding.qolImpact }));
+  if (finding.improvementCapacity !== null) extensions.push(extension('palliative-finding-improvement-capacity', { valueString: finding.improvementCapacity }));
+  if (finding.areMedsNeeded !== null) extensions.push(extension('palliative-finding-are-meds-needed', { valueBoolean: finding.areMedsNeeded }));
+  if (finding.needsCharacterization !== null) extensions.push(extension('palliative-finding-needs-characterization', { valueBoolean: finding.needsCharacterization }));
+  if (finding.clusterNote !== null) extensions.push(extension('palliative-finding-cluster-note', { valueString: finding.clusterNote }));
+  return { item: { concept: codeableConcept(finding.nameShort) }, extension: extensions };
 }
 
 module.exports = {

package/lib/fhir/resources/Task.js

@@ -16,6 +16,7 @@ const {
   INTERVENTION_KIND_SLUG,
   INTERVENTION_OUTCOME_SLUG,
   ROUTING_DISPOSITION_SLUG,
+  PALLIATIVE_ESCALATION_SLUG,
 } = require('../constants/projectionSlugs');
 const { SEVERITY_TO_PRIORITY } = require('../constants/severityPriority');
 const { interventionExtensions } = require('./interventionExtensions');
@@ -83,6 +84,31 @@ class Task {
     return new Task(payload);
   }
 
+  static fromPalliativeEscalation({ assessmentId, committedAt, finding, deviceId }) {
+    const { escalation } = finding;
+    const start = new Date(committedAt);
+    const end = new Date(start.getTime() + escalation.maxActionTimeHours * 3600000);
+    const payload = {
+      resourceType: 'Task',
+      id: fhirId(`${assessmentId}-${finding.rank}`),
+      identifier: [identifier(PALLIATIVE_ESCALATION_SLUG, `${assessmentId}-${finding.rank}`)],
+      status: 'requested',
+      intent: 'order',
+      priority: 'urgent',
+      code: codeableConcept(finding.nameShort),
+      description: escalation.escalationReason,
+      for: patientReference(escalation.patientId),
+      authoredOn: toIso(committedAt),
+      requester: reference('Device', deviceId),
+      restriction: { period: { end: toIso(end) } },
+      extension: [extension('palliative-escalation-rank', { valueInteger: finding.rank })],
+    };
+    if (escalation.escalationRoutes.length) {
+      payload.requestedPerformer = escalation.escalationRoutes.map((route) => ({ concept: codeableConcept(route) }));
+    }
+    return new Task(payload);
+  }
+
   static fromRoutingDisposition({ disposition }) {
     const payload = {
       resourceType: 'Task',

package/lib/fhir/services/palliativeService.js

@@ -0,0 +1,121 @@
+const { ZodError } = require('zod');
+
+const { fhirId } = require('../helpers/fhirHelper');
+const { extMap, extValues, identifierValue } = require('../helpers/fhirReadHelper');
+const { PALLIATIVE_ASSESSMENT_SLUG } = require('../constants/projectionSlugs');
+const { PROJECTOR_NAME } = require('../projections/palliativeProjection');
+const { getFhirStore } = require('../stores/fhirStore');
+const { PalliativeAssessment } = require('../../shared/dtos/PalliativeAssessment');
+const { logger } = require('../../utils/logger');
+const { project, storeResources } = require('./fhirService');
+
+async function storePalliativeAssessment({ patientId, assessment }) {
+  if (assessment.patientId !== patientId) {
+    throw new Error(`storePalliativeAssessment patientId mismatch: expected ${patientId}`);
+  }
+  const bundle = project([{ name: PROJECTOR_NAME, aggregate: assessment }]);
+  const resources = bundle.entry.map((entry) => entry.resource);
+  const { stored } = await storeResources(resources);
+  return { count: stored.length, ids: stored };
+}
+
+async function readPalliativeByTurn({ patientId, turnId }) {
+  const store = getFhirStore();
+  const impression = await findImpression(store, patientId, turnId);
+  if (!impression) return null;
+  const assessmentId = identifierValue(impression, PALLIATIVE_ASSESSMENT_SLUG);
+  const provenance = await store.getByReference(`Provenance/${fhirId(`${assessmentId}-prov`)}`);
+  if (!provenance) return null;
+  return reconstruct(store, impression, provenance, patientId, turnId);
+}
+
+async function findImpression(store, patientId, turnId) {
+  const patient = `Patient/${fhirId(patientId)}`;
+  const impressions = (await store.find({ patient, resourceType: 'ClinicalImpression' }))
+    .filter((resource) => identifierValue(resource, PALLIATIVE_ASSESSMENT_SLUG));
+  return impressions.find((impression) => extMap(impression)['palliative-turn-id'] === turnId) || null;
+}
+
+async function reconstruct(store, impression, provenance, patientId, turnId) {
+  const assessmentId = identifierValue(impression, PALLIATIVE_ASSESSMENT_SLUG);
+  const escalations = await readEscalations(store, provenance, patientId);
+  try {
+    return new PalliativeAssessment({
+      assessmentId,
+      patientId,
+      turnId,
+      committedAt: impression.effectiveDateTime,
+      evaluationSummary: impression.summary || '',
+      rankingRationale: impression.description || '',
+      escalationReason: (impression.note && impression.note[0] && impression.note[0].text) || null,
+      findings: (impression.finding || []).map((finding) => reconstructFinding(finding, escalations)),
+    });
+  } catch (error) {
+    if (error instanceof ZodError) {
+      logger.warn({ assessmentId: impression.id }, 'skipping malformed palliative ClinicalImpression');
+      return null;
+    }
+    throw error;
+  }
+}
+
+async function readEscalations(store, provenance, patientId) {
+  const taskRefs = ((provenance && provenance.target) || [])
+    .map((target) => target.reference)
+    .filter((ref) => ref && ref.startsWith('Task/'));
+  const byRank = {};
+  for (const ref of taskRefs) {
+    const task = await store.getByReference(ref);
+    if (!task) continue;
+    const rank = extMap(task)['palliative-escalation-rank'];
+    if (rank === undefined || rank === null) continue;
+    byRank[rank] = reconstructEscalation(task, patientId);
+  }
+  return byRank;
+}
+
+function reconstructFinding(finding, escalations) {
+  const ext = extMap(finding);
+  const nameShort = ccText(finding.item && finding.item.concept);
+  const rank = ext['palliative-finding-rank'];
+  return {
+    rank,
+    elementType: ext['palliative-finding-element-type'],
+    nameShort,
+    timeWindow: ext['palliative-finding-time-window'] || '',
+    symptomTerms: extValues(finding, 'palliative-finding-symptom-term'),
+    clinicalDescription: ext['palliative-finding-clinical-description'] || '',
+    whyRelevant: ext['palliative-finding-why-relevant'] || '',
+    qolImpact: ext['palliative-finding-qol-impact'] || null,
+    qolCriteria: ext['palliative-finding-qol-criteria'] || '',
+    improvementCapacity: ext['palliative-finding-improvement-capacity'] || null,
+    improvementCriteria: ext['palliative-finding-improvement-criteria'] || '',
+    areMedsNeeded: ext['palliative-finding-are-meds-needed'] ?? null,
+    needsCharacterization: ext['palliative-finding-needs-characterization'] ?? null,
+    characterizationCriteria: ext['palliative-finding-characterization-criteria'] || '',
+    probeQuestions: extValues(finding, 'palliative-finding-probe-question'),
+    auditNotes: ext['palliative-finding-audit-notes'] || '',
+    clusterNote: ext['palliative-finding-cluster-note'] ?? null,
+    escalation: escalations[rank] || null,
+  };
+}
+
+function reconstructEscalation(task, patientId) {
+  const end = task.restriction && task.restriction.period && task.restriction.period.end;
+  const hours = end
+    ? Math.round((new Date(end).getTime() - new Date(task.authoredOn).getTime()) / 3600000)
+    : 24;
+  return {
+    patientId,
+    maxActionTimeHours: hours,
+    escalationRoutes: (task.requestedPerformer || []).map((performer) => ccText(performer.concept)),
+    escalationReason: task.description || '',
+  };
+}
+
+const ccText = (concept) => (concept && concept.text) || null;
+
+module.exports = {
+  storePalliativeAssessment,
+  readPalliativeByTurn,
+};

package/lib/shared/dtos/PalliativeAssessment.js

@@ -0,0 +1,62 @@
+const { z } = require('zod');
+
+const { BaseDto } = require('./BaseDto');
+
+const dateTime = z.iso.datetime({ offset: true });
+
+const escalationSchema = z.strictObject({
+  patientId: z.string(),
+  maxActionTimeHours: z.number().int().min(1).max(24),
+  escalationRoutes: z.array(z.string()).default([]),
+  escalationReason: z.string(),
+});
+
+const findingSchema = z.strictObject({
+  rank: z.number().int().min(1),
+  elementType: z.enum(['cluster', 'individual']),
+  nameShort: z.string().min(1),
+  timeWindow: z.string().default(''),
+  symptomTerms: z.array(z.string()).default([]),
+  clinicalDescription: z.string().default(''),
+  whyRelevant: z.string().default(''),
+  qolImpact: z.enum(['Low', 'Medium', 'High']).nullable().default(null),
+  qolCriteria: z.string().default(''),
+  improvementCapacity: z.enum(['Low', 'Medium', 'High']).nullable().default(null),
+  improvementCriteria: z.string().default(''),
+  areMedsNeeded: z.boolean().nullable().default(null),
+  needsCharacterization: z.boolean().nullable().default(null),
+  characterizationCriteria: z.string().default(''),
+  probeQuestions: z.array(z.string()).default([]),
+  auditNotes: z.string().default(''),
+  clusterNote: z.string().nullable().default(null),
+  escalation: escalationSchema.nullable().default(null),
+});
+
+const schema = z.strictObject({
+  schemaVersion: z.string().default('1'),
+  assessmentId: z.string(),
+  patientId: z.string(),
+  turnId: z.string(),
+  committedAt: dateTime,
+  evaluationSummary: z.string().default(''),
+  rankingRationale: z.string().default(''),
+  escalationReason: z.string().nullable().default(null),
+  findings: z.array(findingSchema).default([]).refine(hasContiguousRanks, {
+    message: 'findings ranks must be unique and contiguous 1..N',
+  }),
+});
+
+function hasContiguousRanks(findings) {
+  const ranks = new Set(findings.map((finding) => finding.rank));
+  if (ranks.size !== findings.length) return false;
+  for (let expected = 1; expected <= findings.length; expected += 1) {
+    if (!ranks.has(expected)) return false;
+  }
+  return true;
+}
+
+class PalliativeAssessment extends BaseDto {}
+
+PalliativeAssessment.schema = schema;
+
+module.exports = { PalliativeAssessment };

package/package.json

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