@peopl-health/nexus 5.10.0-dev.1051 → 5.10.0-dev.1054

package/lib/clinical/helpers/carePlanInterventionDerivation.js

@@ -0,0 +1,76 @@
+const crypto = require('node:crypto');
+
+const { readSymptomCases, storeIntervention } = require('../../fhir');
+const { Intervention } = require('../../shared/dtos/Intervention');
+
+const OPEN_CASE_STATUSES = ['characterizing', 'monitoring'];
+
+const interventionUid = () => `intv_${crypto.randomUUID().replace(/-/g, '').slice(0, 12)}`;
+
+async function findOpenCase(patientId, ctcaeTerms) {
+  for (const term of ctcaeTerms) {
+    const cases = await readSymptomCases({ patientId, ctcaeTerm: String(term).trim().toLowerCase() });
+    const open = cases.find((managed) => OPEN_CASE_STATUSES.includes(managed.condition.clinicalStatus));
+    if (open) return open.condition.conditionId;
+  }
+  return null;
+}
+
+function recordsForRecommendation(recommendation, { patientId, caseId, careplanId, deliveredAt }) {
+  const rationale = `auto-derived from palliative careplan ${careplanId} (rank ${recommendation.rank})`;
+  const records = [];
+  const otc = recommendation.otcOffer;
+  if (otc && typeof otc === 'object' && otc.label) {
+    const label = ['OTC:', otc.label, otc.dose, otc.frequency ? `cada ${otc.frequency}` : null].filter(Boolean).join(' ');
+    records.push({ kind: 'otc', interventionLabel: label, rationale });
+  }
+  if (typeof recommendation.mainRecommendation === 'string' && recommendation.mainRecommendation.trim()) {
+    records.push({
+      kind: 'self_care',
+      interventionLabel: `self-care: ${recommendation.elementNameShort}`,
+      rationale: `${rationale}: ${recommendation.mainRecommendation.trim().slice(0, 200)}`,
+    });
+  }
+  const followupType = recommendation.followup && recommendation.followup.type
+    ? String(recommendation.followup.type).trim().toLowerCase() : '';
+  if (followupType === 'checkin_48h') {
+    records.push({ kind: 'follow_up_check', interventionLabel: `check-in 48h — ${recommendation.elementNameShort}`, rationale });
+  } else if (followupType === 'team_referral') {
+    records.push({ kind: 'team_escalation', interventionLabel: `team referral — ${recommendation.elementNameShort}`, rationale });
+  }
+  return records.map((record) => new Intervention({
+    ...record,
+    interventionId: interventionUid(),
+    patientId,
+    caseId,
+    deliveredAt,
+  }));
+}
+
+async function deriveInterventionsFromCarePlan({ carePlan }) {
+  const created = [];
+  let skippedNoCase = 0;
+  const deliveredAt = new Date().toISOString();
+  for (const recommendation of carePlan.recommendations) {
+    const caseId = await findOpenCase(carePlan.patientId, recommendation.ctcaeTerms);
+    if (!caseId) {
+      skippedNoCase += 1;
+      continue;
+    }
+    const interventions = recordsForRecommendation(recommendation, {
+      patientId: carePlan.patientId,
+      caseId,
+      careplanId: carePlan.careplanId,
+      deliveredAt,
+    });
+    for (const intervention of interventions) {
+      await storeIntervention({ patientId: carePlan.patientId, intervention });
+      created.push(intervention.interventionId);
+    }
+  }
+  return { created, skippedNoCase };
+}
+
+module.exports = {
+  deriveInterventionsFromCarePlan,
+};

package/lib/clinical/helpers/carePlanValidationHelper.js

@@ -0,0 +1,62 @@
+const MISMATCH = 'ASSESSMENT_CAREPLAN_MISMATCH';
+const NO_PATIENT_ACTION = 'CAREPLAN_NO_PATIENT_ACTION';
+const MALFORMED_RECOMMENDATION = 'MALFORMED_RECOMMENDATION';
+
+function checkCarePlanAgainstAssessment(recommendations, findings) {
+  const malformedIndex = recommendations.findIndex((rec) => !rec || typeof rec !== 'object');
+  if (malformedIndex !== -1) {
+    return { errorCode: MALFORMED_RECOMMENDATION, path: `recommendations[${malformedIndex}]`, message: `recommendation at index ${malformedIndex} is null or not an object` };
+  }
+  if (recommendations.length !== findings.length) {
+    return { errorCode: MISMATCH, path: 'recommendations', message: `recommendations length ${recommendations.length} != assessment findings length ${findings.length}` };
+  }
+  const byRank = new Map(findings.map((finding) => [finding.rank, finding]));
+  const seen = new Set();
+  for (const rec of recommendations) {
+    if (typeof rec.rank !== 'number' || !Number.isInteger(rec.rank)) {
+      return { errorCode: MISMATCH, path: 'recommendations[rank]', message: `recommendation rank must be an integer, got ${JSON.stringify(rec.rank)}` };
+    }
+    if (seen.has(rec.rank)) {
+      return { errorCode: MISMATCH, path: `recommendations[rank=${rec.rank}]`, message: 'duplicate rank in recommendations' };
+    }
+    seen.add(rec.rank);
+  }
+  for (const rec of recommendations) {
+    const finding = byRank.get(rec.rank);
+    if (!finding) {
+      return { errorCode: MISMATCH, path: `recommendations[rank=${rec.rank}]`, message: `rank=${rec.rank} has no matching assessment finding` };
+    }
+    if (typeof rec.elementNameShort === 'string' && rec.elementNameShort && rec.elementNameShort !== finding.nameShort) {
+      return { errorCode: MISMATCH, path: `recommendations[rank=${rec.rank}].element_name_short`, message: 'element_name_short must match the assessment finding name_short' };
+    }
+    if (typeof rec.isPharmacologicalMedNeeded === 'boolean' && finding.areMedsNeeded !== null) {
+      if (finding.areMedsNeeded && !rec.isPharmacologicalMedNeeded) {
+        return { errorCode: MISMATCH, path: `recommendations[rank=${rec.rank}].is_pharmacological_med_needed`, message: 'assessment has are_meds_needed=true but careplan set is_pharmacological_med_needed=false' };
+      }
+      if (!finding.areMedsNeeded && rec.isPharmacologicalMedNeeded) {
+        return { errorCode: MISMATCH, path: `recommendations[rank=${rec.rank}].is_pharmacological_med_needed`, message: 'assessment has are_meds_needed=false but careplan set is_pharmacological_med_needed=true' };
+      }
+    }
+  }
+  return null;
+}
+
+function checkCarePlanHasPatientAction(recommendations) {
+  for (const rec of recommendations) {
+    const hasMain = typeof rec.mainRecommendation === 'string' && rec.mainRecommendation.trim();
+    const hasOtc = rec.otcOffer && typeof rec.otcOffer === 'object' && Object.keys(rec.otcOffer).length > 0;
+    const isReferral = rec.followup && typeof rec.followup.type === 'string' && rec.followup.type.trim().toLowerCase() === 'team_referral';
+    if (!hasMain && !hasOtc && !isReferral) {
+      return { errorCode: NO_PATIENT_ACTION, path: `recommendations[rank=${rec.rank}]`, message: 'careplan recommendation delivers nothing to the patient: main_recommendation and otc_offer are both empty and followup is not team_referral' };
+    }
+  }
+  return null;
+}
+
+module.exports = {
+  checkCarePlanAgainstAssessment,
+  checkCarePlanHasPatientAction,
+  MISMATCH,
+  NO_PATIENT_ACTION,
+  MALFORMED_RECOMMENDATION,
+};

package/lib/clinical/helpers/palliativeCarePlanHelper.js

@@ -0,0 +1,68 @@
+const crypto = require('node:crypto');
+
+const { PalliativeCarePlan } = require('../../shared/dtos/PalliativeCarePlan');
+
+const uid = (prefix) => `${prefix}_${crypto.randomUUID().replace(/-/g, '').slice(0, 12)}`;
+
+function carePlanUid() {
+  return uid('cp');
+}
+
+function mapOtcOffer(raw) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw) || typeof raw.label !== 'string') return null;
+  return {
+    label: raw.label,
+    dose: typeof raw.dose === 'string' ? raw.dose : null,
+    frequency: typeof raw.frequency === 'string' ? raw.frequency : null,
+    duration: typeof raw.duration === 'string' ? raw.duration : null,
+    warnings: (Array.isArray(raw.warnings) ? raw.warnings : []).filter((warning) => typeof warning === 'string'),
+  };
+}
+
+function mapRecommendation(raw) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
+  const patient = (raw.recommendations_patient && typeof raw.recommendations_patient === 'object')
+    ? raw.recommendations_patient : {};
+  const followupRaw = patient.followup;
+  const followup = (followupRaw && typeof followupRaw === 'object')
+    ? { type: followupRaw.type ?? null, urgency: followupRaw.urgency ?? null }
+    : (typeof followupRaw === 'string' ? { type: followupRaw, urgency: null } : null);
+  const target = (raw.target && typeof raw.target === 'object') ? raw.target : {};
+  return {
+    rank: raw.rank,
+    elementNameShort: raw.element_name_short,
+    isPharmacologicalMedNeeded: typeof raw.is_pharmacological_med_needed === 'boolean'
+      ? raw.is_pharmacological_med_needed : null,
+    ctcaeTerms: (Array.isArray(target.CTCAE_term) ? target.CTCAE_term : []).filter((term) => term),
+    mainRecommendation: typeof patient.main_recommendation === 'string' ? patient.main_recommendation : null,
+    otcOffer: mapOtcOffer(patient.otc_offer),
+    followup,
+    whenToEscalate: typeof patient.when_to_escalate === 'string' ? patient.when_to_escalate : null,
+    expectedEffectiveness: typeof patient.expected_effectiveness === 'string' ? patient.expected_effectiveness : null,
+  };
+}
+
+function normalizeRecommendations(raw) {
+  const recs = Array.isArray(raw.recommendations) ? raw.recommendations : [];
+  return recs.map(mapRecommendation);
+}
+
+function buildCarePlan({ raw, carePlanId, patientId, turnId, assessmentId, committedAt, recommendations }) {
+  const takeaways = (raw.careplan_takeaways && typeof raw.careplan_takeaways === 'object') ? raw.careplan_takeaways : {};
+  return new PalliativeCarePlan({
+    careplanId: carePlanId,
+    patientId,
+    turnId,
+    assessmentId,
+    committedAt,
+    summary: typeof takeaways.careplan_summary_internal === 'string' ? takeaways.careplan_summary_internal : null,
+    recommendations,
+  });
+}
+
+module.exports = {
+  carePlanUid,
+  mapRecommendation,
+  normalizeRecommendations,
+  buildCarePlan,
+};

package/lib/clinical/tools/submitPalliativeCarePlanTool.js

@@ -0,0 +1,101 @@
+const { carePlanUid, normalizeRecommendations, buildCarePlan } = require('../helpers/palliativeCarePlanHelper');
+const { checkCarePlanAgainstAssessment, checkCarePlanHasPatientAction } = require('../helpers/carePlanValidationHelper');
+const { deriveInterventionsFromCarePlan } = require('../helpers/carePlanInterventionDerivation');
+const { readPalliativeByTurn, readPalliativeCarePlanByTurn, storePalliativeCarePlan } = require('../../fhir');
+const { fhirId } = require('../../fhir/helpers/fhirHelper');
+const { logger } = require('../../utils/logger');
+
+const definition = {
+  name: 'submitPalliativeCarePlan',
+  description: '**Does:** Terminal Phase-2 commit of the `accompaniment` skill — persists a structured palliative CARE PLAN for the turn\'s committed assessment as a FHIR `CarePlan` (+ one `Task` per recommendation). One recommendation per assessment finding, aligned by `rank`.\n\n**Required inputs:** `careplan` (one object) with `recommendations[]` — each `{rank, element_name_short, is_pharmacological_med_needed, target:{CTCAE_term[]}, recommendations_patient:{main_recommendation, otc_offer, followup, when_to_escalate, expected_effectiveness}}` — plus `careplan_takeaways`.\n\n**When NOT to call:**\n- Before a Phase-1 assessment exists for the turn — returns `assessment_required`; call `submitPalliativeAssessment` first.\n- Twice in the same turn — returns `careplan_already_committed_for_turn`.\n\n**Validation (fail-hard before persisting):**\n- `ASSESSMENT_CAREPLAN_MISMATCH` — recommendations must be one-per-finding with unique ranks matching the assessment, `element_name_short` matching the finding, and `is_pharmacological_med_needed` coherent with the finding\'s `are_meds_needed`.\n- `CAREPLAN_NO_PATIENT_ACTION` — each recommendation must hand the patient something (`main_recommendation` | `otc_offer` | `followup=team_referral`).\n\n**Returns:** `accepted`, `careplan_id`, `assessment_id`, `turn_id`, `committed_at`, plus best-effort `derived_intervention_ids` / `derived_interventions_skipped_no_case`.\n\n**Side effects:** persists the FHIR `CarePlan` + `Task[]` + `Provenance`; auto-derives case-layer Interventions (never blocks the commit).',
+  strict: false,
+  parameters: {
+    type: 'object',
+    properties: {
+      careplan: {
+        type: 'object',
+        description: 'The full palliative care plan. `recommendations[]` (one per assessment finding, aligned by `rank`) each carry patient-facing advice; plus `careplan_takeaways`.',
+      },
+    },
+    required: ['careplan'],
+  },
+};
+
+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('submitPalliativeCarePlan requires an active turn context (turnId, patientCode).');
+    }
+    const raw = args?.careplan;
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+      return fail('careplan is required (non-empty object)');
+    }
+
+    const patientId = runtime.patientCode;
+    const turnId = runtime.turnId;
+
+    const assessment = await readPalliativeByTurn({ patientId, turnId });
+    if (!assessment) {
+      return fail('assessment_required — call submitPalliativeAssessment first', { turn_id: turnId });
+    }
+    const existing = await readPalliativeCarePlanByTurn({ patientId, turnId });
+    if (existing) {
+      return fail('careplan_already_committed_for_turn', { existing_careplan_id: existing.careplanId, turn_id: turnId });
+    }
+
+    const recommendations = normalizeRecommendations(raw);
+    const mismatch = checkCarePlanAgainstAssessment(recommendations, assessment.findings);
+    if (mismatch) return fail(mismatch.errorCode, { turn_id: turnId, ...mismatch });
+    const hollow = checkCarePlanHasPatientAction(recommendations);
+    if (hollow) return fail(hollow.errorCode, { turn_id: turnId, ...hollow });
+
+    const carePlan = buildCarePlan({
+      raw,
+      carePlanId: carePlanUid(),
+      patientId,
+      turnId,
+      assessmentId: assessment.assessmentId,
+      committedAt: new Date().toISOString(),
+      recommendations,
+    });
+    await storePalliativeCarePlan({ patientId, carePlan });
+
+    runtime.setCareplan({ careplanId: carePlan.careplanId, assessmentId: carePlan.assessmentId, turnId });
+    runtime.trace.setSignals({ palliativeCareplanId: carePlan.careplanId });
+
+    const data = {
+      accepted: true,
+      careplan_id: fhirId(carePlan.careplanId),
+      assessment_id: carePlan.assessmentId,
+      turn_id: turnId,
+      committed_at: carePlan.committedAt,
+    };
+    const derived = await deriveInterventions(carePlan);
+    if (derived.created.length) data.derived_intervention_ids = derived.created;
+    if (derived.skippedNoCase) data.derived_interventions_skipped_no_case = derived.skippedNoCase;
+    if (derived.error) data.derived_interventions_error = true;
+
+    return JSON.stringify({ success: true, data });
+  } catch (err) {
+    return fail(err?.message || 'submitPalliativeCarePlan failed');
+  }
+}
+
+async function deriveInterventions(carePlan) {
+  try {
+    return await deriveInterventionsFromCarePlan({ carePlan });
+  } catch (err) {
+    logger.warn({ careplanId: carePlan.careplanId, err: err?.message }, 'palliative careplan intervention derivation failed');
+    return { created: [], skippedNoCase: 0, error: true };
+  }
+}
+
+module.exports = {
+  definition,
+  handler,
+};

package/lib/clinical/tools/updatePalliativeAssessmentTool.js

@@ -1,10 +1,10 @@
 const { assessmentUid, buildAssessment } = require('../helpers/palliativeAssessmentHelper');
-const { storePalliativeAssessment, readPalliativeByTurn } = require('../../fhir');
+const { storePalliativeAssessment, readPalliativeByTurn, readPalliativeCarePlanByTurn } = 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`.',
+  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- After a care plan has been committed for the turn — returns `careplan_already_committed`; the assessment is locked.\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',
@@ -40,6 +40,10 @@ async function handler(args = {}, context = {}) {
     if (!prior) {
       return fail('no_assessment_to_update — call submitPalliativeAssessment first', { turn_id: turnId });
     }
+    const careplan = await readPalliativeCarePlanByTurn({ patientId, turnId });
+    if (careplan) {
+      return fail('careplan_already_committed — the assessment is locked once a careplan exists for the turn', { turn_id: turnId, careplan_id: careplan.careplanId });
+    }
 
     const assessment = buildAssessment({
       raw,

package/lib/fhir/constants/projectionSlugs.js

@@ -24,6 +24,8 @@ const ROUTING_ASSESSMENT_SLUG = 'routing-assessment';
 const ROUTING_DISPOSITION_SLUG = 'routing-disposition';
 const PALLIATIVE_ASSESSMENT_SLUG = 'palliative-assessment';
 const PALLIATIVE_ESCALATION_SLUG = 'palliative-escalation';
+const PALLIATIVE_CAREPLAN_SLUG = 'palliative-careplan';
+const PALLIATIVE_CAREPLAN_REC_SLUG = 'palliative-careplan-rec';
 
 module.exports = {
   MENTION_SLUG,
@@ -52,4 +54,6 @@ module.exports = {
   ROUTING_DISPOSITION_SLUG,
   PALLIATIVE_ASSESSMENT_SLUG,
   PALLIATIVE_ESCALATION_SLUG,
+  PALLIATIVE_CAREPLAN_SLUG,
+  PALLIATIVE_CAREPLAN_REC_SLUG,
 };

package/lib/fhir/index.js

@@ -8,7 +8,12 @@ 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 {
+  storePalliativeAssessment,
+  readPalliativeByTurn,
+  storePalliativeCarePlan,
+  readPalliativeCarePlanByTurn,
+} = require('./services/palliativeService');
 const { storeTriage } = require('./services/triageService');
 const { patientSnapshot } = require('./services/snapshotService');
 const { registerAllProjectors } = require('./projections/registerProjectors');
@@ -46,6 +51,8 @@ module.exports = {
   readRoutingByTurn,
   storePalliativeAssessment,
   readPalliativeByTurn,
+  storePalliativeCarePlan,
+  readPalliativeCarePlanByTurn,
   storeTriage,
   patientSnapshot,
   getFhirStore,

package/lib/fhir/projections/palliativeCarePlanProjection.js

@@ -0,0 +1,38 @@
+const { getDeviceId } = require('../config/fhirConfig');
+const { CarePlan } = require('../resources/CarePlan');
+const { Task } = require('../resources/Task');
+const { Provenance } = require('../resources/Provenance');
+
+const PROJECTOR_NAME = 'palliativeCarePlan';
+const ACTIVITY_TEXT = 'palliative-careplan';
+
+function projectPalliativeCarePlan(carePlan) {
+  const deviceId = getDeviceId();
+  const tasks = carePlan.recommendations.map((recommendation) => Task.fromPalliativeRecommendation({
+    carePlanId: carePlan.careplanId,
+    recommendation,
+    patientId: carePlan.patientId,
+    committedAt: carePlan.committedAt,
+    deviceId,
+  }));
+  const plan = CarePlan.fromPalliativeCarePlan({
+    carePlan,
+    taskIds: tasks.map((task) => task.identifier[0].value),
+  });
+  const targetRefs = [
+    { reference: `CarePlan/${plan.id}` },
+    ...tasks.map((task) => ({ reference: `Task/${task.id}` })),
+  ];
+  const provenance = Provenance.fromSymptomCase({
+    provenanceId: `${carePlan.careplanId}-prov`,
+    targetRefs,
+    recordedAt: carePlan.committedAt,
+    activityText: ACTIVITY_TEXT,
+  });
+  return [plan, ...tasks, provenance];
+}
+
+module.exports = {
+  projectPalliativeCarePlan,
+  PROJECTOR_NAME,
+};

package/lib/fhir/projections/registerProjectors.js

@@ -11,6 +11,7 @@ const { projectIntervention, PROJECTOR_NAME: INTERVENTION_PROJECTOR_NAME } = req
 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 { projectPalliativeCarePlan, PROJECTOR_NAME: PALLIATIVE_CAREPLAN_PROJECTOR_NAME } = require('./palliativeCarePlanProjection');
 
 const PROJECTORS = [
   { name: MENTION_PROJECTOR_NAME, project: projectClinicalMention },
@@ -25,6 +26,7 @@ const PROJECTORS = [
   { name: CLUSTER_PROJECTOR_NAME, project: projectCluster },
   { name: ROUTING_PROJECTOR_NAME, project: projectRoutingDecision },
   { name: PALLIATIVE_PROJECTOR_NAME, project: projectPalliativeAssessment },
+  { name: PALLIATIVE_CAREPLAN_PROJECTOR_NAME, project: projectPalliativeCarePlan },
 ];
 
 function registerAllProjectors() {

package/lib/fhir/resources/CarePlan.js

@@ -7,7 +7,7 @@ const {
   extension,
   toIso,
 } = require('../helpers/elementHelper');
-const { CONTINGENCY_PLAN_SLUG, ROUTING_DISPOSITION_SLUG, RECOMMENDATION_PLAN_SLUG } = require('../constants/projectionSlugs');
+const { CONTINGENCY_PLAN_SLUG, ROUTING_DISPOSITION_SLUG, RECOMMENDATION_PLAN_SLUG, PALLIATIVE_CAREPLAN_SLUG } = require('../constants/projectionSlugs');
 
 const CONTINGENCY_STATUS_TO_FHIR = {
   armed: 'active',
@@ -67,6 +67,29 @@ class CarePlan {
     return new CarePlan(payload);
   }
 
+  static fromPalliativeCarePlan({ carePlan, taskIds }) {
+    const payload = {
+      resourceType: 'CarePlan',
+      id: fhirId(carePlan.careplanId),
+      identifier: [identifier(PALLIATIVE_CAREPLAN_SLUG, carePlan.careplanId)],
+      status: 'active',
+      intent: 'plan',
+      category: [codeableConcept(PALLIATIVE_CAREPLAN_SLUG)],
+      subject: patientReference(carePlan.patientId),
+      created: toIso(carePlan.committedAt),
+      extension: [extension('palliative-turn-id', { valueString: carePlan.turnId })],
+    };
+    if (carePlan.summary) payload.description = carePlan.summary;
+    if (carePlan.assessmentId) {
+      payload.extension.push(extension('palliative-assessment-id', { valueString: carePlan.assessmentId }));
+      payload.supportingInfo = [reference('ClinicalImpression', carePlan.assessmentId)];
+    }
+    if (taskIds.length) {
+      payload.activity = taskIds.map((taskId) => ({ plannedActivityReference: reference('Task', taskId) }));
+    }
+    return new CarePlan(payload);
+  }
+
   static fromRoutingDisposition({ disposition }) {
     const payload = {
       resourceType: 'CarePlan',

package/lib/fhir/resources/Task.js

@@ -18,6 +18,7 @@ const {
   ROUTING_DISPOSITION_SLUG,
   RECOMMENDATION_REC_SLUG,
   PALLIATIVE_ESCALATION_SLUG,
+  PALLIATIVE_CAREPLAN_REC_SLUG,
 } = require('../constants/projectionSlugs');
 const { SEVERITY_TO_PRIORITY } = require('../constants/severityPriority');
 const { interventionExtensions } = require('./interventionExtensions');
@@ -140,6 +141,43 @@ class Task {
     return new Task(payload);
   }
 
+  static fromPalliativeRecommendation({ carePlanId, recommendation, patientId, committedAt, deviceId }) {
+    const recId = `${carePlanId}-rank${recommendation.rank}`;
+    const code = codeableConcept(recommendation.elementNameShort);
+    const ctcaeTerms = (recommendation.ctcaeTerms || []).filter(Boolean);
+    if (ctcaeTerms.length) {
+      code.coding = ctcaeTerms.map((term) => ({ system: codeSystemUrl('pro-ctcae'), code: term, display: term }));
+    }
+    const payload = {
+      resourceType: 'Task',
+      id: fhirId(recId),
+      identifier: [identifier(PALLIATIVE_CAREPLAN_REC_SLUG, recId)],
+      status: 'requested',
+      intent: 'plan',
+      code,
+      for: patientReference(patientId),
+      authoredOn: toIso(committedAt),
+      requester: reference('Device', deviceId),
+      extension: [extension('palliative-careplan-rec-rank', { valueInteger: recommendation.rank })],
+    };
+    if (recommendation.otcOffer && recommendation.otcOffer.label) {
+      payload.extension.push(extension('palliative-careplan-otc-offer', { valueString: JSON.stringify(recommendation.otcOffer) }));
+    }
+    if (recommendation.mainRecommendation) payload.description = recommendation.mainRecommendation;
+    const noteTexts = [];
+    if (recommendation.whenToEscalate) noteTexts.push(`when_to_escalate: ${recommendation.whenToEscalate}`);
+    if (recommendation.expectedEffectiveness) noteTexts.push(`expected_effectiveness: ${recommendation.expectedEffectiveness}`);
+    if (recommendation.followup && recommendation.followup.type) {
+      noteTexts.push(`followup: ${recommendation.followup.type} / ${recommendation.followup.urgency || ''}`);
+    }
+    if (recommendation.isPharmacologicalMedNeeded !== null) {
+      noteTexts.push(`is_pharmacological_med_needed: ${recommendation.isPharmacologicalMedNeeded}`);
+    }
+    const note = notes(...noteTexts);
+    if (note) payload.note = note;
+    return new Task(payload);
+  }
+
   static fromRoutingDisposition({ disposition }) {
     const payload = {
       resourceType: 'Task',

package/lib/fhir/services/palliativeService.js

@@ -2,10 +2,12 @@ const { ZodError } = require('zod');
 
 const { fhirId } = require('../helpers/fhirHelper');
 const { extMap, extValues, identifierValue } = require('../helpers/fhirReadHelper');
-const { PALLIATIVE_ASSESSMENT_SLUG } = require('../constants/projectionSlugs');
+const { PALLIATIVE_ASSESSMENT_SLUG, PALLIATIVE_ESCALATION_SLUG, PALLIATIVE_CAREPLAN_SLUG } = require('../constants/projectionSlugs');
 const { PROJECTOR_NAME } = require('../projections/palliativeProjection');
+const { PROJECTOR_NAME: CAREPLAN_PROJECTOR_NAME } = require('../projections/palliativeCarePlanProjection');
 const { getFhirStore } = require('../stores/fhirStore');
 const { PalliativeAssessment } = require('../../shared/dtos/PalliativeAssessment');
+const { PalliativeCarePlan } = require('../../shared/dtos/PalliativeCarePlan');
 const { logger } = require('../../utils/logger');
 const { project, storeResources } = require('./fhirService');
 
@@ -29,6 +31,95 @@ async function readPalliativeByTurn({ patientId, turnId }) {
   return reconstruct(store, impression, provenance, patientId, turnId);
 }
 
+async function storePalliativeCarePlan({ patientId, carePlan }) {
+  if (carePlan.patientId !== patientId) {
+    throw new Error(`storePalliativeCarePlan patientId mismatch: expected ${patientId}`);
+  }
+  const bundle = project([{ name: CAREPLAN_PROJECTOR_NAME, aggregate: carePlan }]);
+  const resources = bundle.entry.map((entry) => entry.resource);
+  const { stored } = await storeResources(resources);
+  return { count: stored.length, ids: stored };
+}
+
+async function readPalliativeCarePlanByTurn({ patientId, turnId }) {
+  const store = getFhirStore();
+  const patient = `Patient/${fhirId(patientId)}`;
+  const plans = (await store.find({ patient, resourceType: 'CarePlan' }))
+    .filter((resource) => identifierValue(resource, PALLIATIVE_CAREPLAN_SLUG));
+  const plan = plans.find((resource) => extMap(resource)['palliative-turn-id'] === turnId) || null;
+  if (!plan) return null;
+  const careplanId = identifierValue(plan, PALLIATIVE_CAREPLAN_SLUG);
+  const provenance = await store.getByReference(`Provenance/${fhirId(`${careplanId}-prov`)}`);
+  if (!provenance) return null;
+  return reconstructCarePlan(store, plan, patientId, turnId);
+}
+
+async function reconstructCarePlan(store, plan, patientId, turnId) {
+  const careplanId = identifierValue(plan, PALLIATIVE_CAREPLAN_SLUG);
+  const assessmentId = extMap(plan)['palliative-assessment-id'];
+  const taskRefs = (plan.activity || [])
+    .map((activity) => activity.plannedActivityReference && activity.plannedActivityReference.reference)
+    .filter(Boolean);
+  const recommendations = [];
+  for (const ref of taskRefs) {
+    const task = await store.getByReference(ref);
+    if (task) recommendations.push(reconstructRecommendation(task));
+  }
+  try {
+    return new PalliativeCarePlan({
+      careplanId,
+      patientId,
+      turnId,
+      assessmentId: assessmentId || '',
+      committedAt: plan.created,
+      summary: plan.description || null,
+      recommendations,
+    });
+  } catch (error) {
+    if (error instanceof ZodError) {
+      logger.warn({ careplanId }, 'skipping malformed palliative CarePlan');
+      return null;
+    }
+    throw error;
+  }
+}
+
+function reconstructRecommendation(task) {
+  const noteMap = {};
+  for (const note of task.note || []) {
+    const [key, ...rest] = String(note.text || '').split(': ');
+    noteMap[key] = rest.join(': ');
+  }
+  const followupText = noteMap.followup;
+  const followup = followupText
+    ? { type: (followupText.split(' / ')[0] || '').trim() || null, urgency: (followupText.split(' / ')[1] || '').trim() || null }
+    : null;
+  const medsText = noteMap.is_pharmacological_med_needed;
+  const ext = extMap(task);
+  const ctcaeTerms = ((task.code && task.code.coding) || []).map((coding) => coding.code).filter(Boolean);
+  return {
+    rank: ext['palliative-careplan-rec-rank'],
+    elementNameShort: (task.code && task.code.text) || 'recommendation',
+    isPharmacologicalMedNeeded: medsText === undefined ? null : medsText === 'true',
+    ctcaeTerms,
+    mainRecommendation: task.description || null,
+    otcOffer: parseOtcOffer(ext['palliative-careplan-otc-offer']),
+    whenToEscalate: noteMap.when_to_escalate || null,
+    expectedEffectiveness: noteMap.expected_effectiveness || null,
+    followup,
+  };
+}
+
+function parseOtcOffer(raw) {
+  if (typeof raw !== 'string' || !raw) return null;
+  try {
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
 async function findImpression(store, patientId, turnId) {
   const patient = `Patient/${fhirId(patientId)}`;
   const impressions = (await store.find({ patient, resourceType: 'ClinicalImpression' }))
@@ -118,4 +209,6 @@ const ccText = (concept) => (concept && concept.text) || null;
 module.exports = {
   storePalliativeAssessment,
   readPalliativeByTurn,
+  storePalliativeCarePlan,
+  readPalliativeCarePlanByTurn,
 };

package/lib/shared/dtos/PalliativeCarePlan.js

@@ -0,0 +1,47 @@
+const { z } = require('zod');
+
+const { BaseDto } = require('./BaseDto');
+
+const dateTime = z.iso.datetime({ offset: true });
+
+const followupSchema = z.strictObject({
+  type: z.string().nullable().default(null),
+  urgency: z.string().nullable().default(null),
+}).nullable().default(null);
+
+const otcOfferSchema = z.strictObject({
+  label: z.string(),
+  dose: z.string().nullable().default(null),
+  frequency: z.string().nullable().default(null),
+  duration: z.string().nullable().default(null),
+  warnings: z.array(z.string()).default([]),
+}).nullable().default(null);
+
+const recommendationSchema = z.strictObject({
+  rank: z.number().int().min(1),
+  elementNameShort: z.string().min(1),
+  isPharmacologicalMedNeeded: z.boolean().nullable().default(null),
+  ctcaeTerms: z.array(z.string()).default([]),
+  mainRecommendation: z.string().nullable().default(null),
+  otcOffer: otcOfferSchema,
+  followup: followupSchema,
+  whenToEscalate: z.string().nullable().default(null),
+  expectedEffectiveness: z.string().nullable().default(null),
+});
+
+const schema = z.strictObject({
+  schemaVersion: z.string().default('1'),
+  careplanId: z.string(),
+  patientId: z.string(),
+  turnId: z.string(),
+  assessmentId: z.string(),
+  committedAt: dateTime,
+  summary: z.string().nullable().default(null),
+  recommendations: z.array(recommendationSchema).default([]),
+});
+
+class PalliativeCarePlan extends BaseDto {}
+
+PalliativeCarePlan.schema = schema;
+
+module.exports = { PalliativeCarePlan };

package/package.json

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