@peopl-health/nexus 5.10.0-dev.1021 → 5.10.0-dev.1024

package/lib/clinical/tools/submitSafetyGateTool.js

@@ -0,0 +1,207 @@
+const { ZodError } = require('zod');
+
+const { storeSafetyGate, safetyGateExists } = require('../../fhir');
+const {
+  RecommendationSafetyGate,
+  ESCALATION_ROUTES,
+  RED_FLAG_STATUSES,
+} = require('../../shared/dtos/RecommendationSafetyGate');
+const { logger } = require('../../utils/logger');
+
+const definition = {
+  name: 'submitSafetyGate',
+  description: '**Does:** Commits the safety-gate evaluation (red flags mapped to high-risk adverse events, urgency, escalation route) for THIS turn\'s recommendation run. Call ONCE when generating a plan. Verification arithmetic and escalation-field consistency are repaired server-side (disclosed in `auto_repairs`); only a contradictory URGENT gate is rejected — an urgent gate demands `max_action_time_hours` (1-24), an `escalation_route`, and ≥1 confirmed/partially_confirmed red flag. An urgent gate does not notify anyone by itself: escalate via reportMedicalEscalation.\n\n**Required inputs:** `urgent_under_24h`, `summary`. Per red flag in `red_flags`: `name` + `verification_status`. `max_action_time_hours` / `escalation_route` / `reason_for_escalation` apply only when urgent.\n\n**Returns:** `accepted`, `run_id`, `urgent_under_24h`, `escalation_route`, `red_flags_count`, `must_escalate_now`, `auto_repairs`.\n\n**Side effects:** persists the gate as a run-scoped FHIR RiskAssessment.',
+  strict: false,
+  parameters: {
+    type: 'object',
+    properties: {
+      urgent_under_24h: {
+        type: 'boolean',
+        description: 'True when the situation demands action within 24h. Requires max_action_time_hours + escalation_route + a confirmed/partially_confirmed red flag.',
+      },
+      max_action_time_hours: {
+        type: 'integer',
+        description: '1-24 when urgent_under_24h=true; null otherwise. Nulled server-side on a non-urgent gate.',
+      },
+      escalation_route: {
+        type: 'string',
+        enum: ESCALATION_ROUTES,
+        description: 'Global escalation route: emergencia | urgencias | equipo_tratante_hoy. Required when urgent; nulled otherwise.',
+      },
+      reason_for_escalation: {
+        type: 'string',
+        description: 'Why this gate escalates. Nulled server-side on a non-urgent gate.',
+      },
+      summary: {
+        type: 'string',
+        description: 'Plain-language gate summary.',
+      },
+      red_flags: {
+        type: 'array',
+        description: 'Red flags evaluated this turn. Each: `{name, verification_status, escalation_route, events_confirmed[], events_denied[], related_aes[], definition[{clinical_event, ctcae_grades_reference[]}], grounded_in[]}`. verification_status is repaired from the events (denied ⇒ denied; no confirmed events ⇒ inconclusive; confirmed but a definition clinical_event is unconfirmed ⇒ partially_confirmed).',
+        items: { type: 'object' },
+      },
+    },
+    required: ['urgent_under_24h', 'summary'],
+  },
+};
+
+const str = (value) => (typeof value === 'string' ? value : '');
+const arr = (value) => (Array.isArray(value) ? value : []);
+const strList = (value) => arr(value).map(str).filter(Boolean);
+
+function derivedStatus(redFlag) {
+  if (redFlag.eventsDenied.length) return 'denied';
+  if (!redFlag.eventsConfirmed.length) return 'inconclusive';
+  if (!['confirmed', 'partially_confirmed'].includes(redFlag.verificationStatus)) return 'partially_confirmed';
+  if (redFlag.verificationStatus === 'confirmed' && redFlag.definition.length) {
+    const confirmed = new Set(redFlag.eventsConfirmed.map((event) => event.trim()));
+    if (redFlag.definition.some((event) => !confirmed.has(event.clinicalEvent.trim()))) return 'partially_confirmed';
+  }
+  return redFlag.verificationStatus;
+}
+
+function normalizeStatus(raw) {
+  const status = str(raw).trim();
+  if (status === 'suspected') return null;
+  return RED_FLAG_STATUSES.includes(status) ? status : null;
+}
+
+function normalizeRelatedAe(raw) {
+  const probability = str(raw?.probability_given_patient).trim();
+  return {
+    ctcaeTerm: str(raw?.ctcae_term).trim(),
+    probabilityGivenPatient: ['high', 'medium', 'low'].includes(probability) ? probability : 'low',
+    whyIsRelevant: str(raw?.why_is_relevant).trim(),
+    groundedIn: strList(raw?.grounded_in),
+  };
+}
+
+function normalizeRedFlagEvent(raw) {
+  return {
+    clinicalEvent: str(raw?.clinical_event).trim(),
+    ctcaeGradesReference: arr(raw?.ctcae_grades_reference)
+      .map((grade) => Number(grade))
+      .filter(Number.isInteger),
+  };
+}
+
+function buildRedFlag(raw, repairs, index) {
+  const requested = str(raw?.verification_status).trim();
+  const base = {
+    name: str(raw?.name).trim(),
+    verificationStatus: normalizeStatus(raw?.verification_status) || 'inconclusive',
+    escalationRoute: ESCALATION_ROUTES.includes(str(raw?.escalation_route).trim()) ? str(raw.escalation_route).trim() : null,
+    eventsConfirmed: strList(raw?.events_confirmed),
+    eventsDenied: strList(raw?.events_denied),
+    relatedAes: arr(raw?.related_aes).map(normalizeRelatedAe),
+    definition: arr(raw?.definition).map(normalizeRedFlagEvent).filter((event) => event.clinicalEvent),
+    groundedIn: strList(raw?.grounded_in),
+  };
+  const want = derivedStatus(base);
+  if (want !== base.verificationStatus) {
+    repairs.push(`red_flags[${index}].verification_status: '${requested || base.verificationStatus}' → '${want}' (aritmética de eventos)`);
+    base.verificationStatus = want;
+  }
+  return base;
+}
+
+async function handler(args = {}, context = {}) {
+  try {
+    const runtime = context?.toolRuntimeContext || null;
+    if (!runtime?.turnId || !runtime?.patientCode) {
+      return JSON.stringify({ success: false, error: 'submitSafetyGate requires an active turn context (turnId, patientCode).', data: {} });
+    }
+    if (typeof args?.urgent_under_24h !== 'boolean') {
+      return JSON.stringify({ success: false, error: 'urgent_under_24h is required and must be a boolean.', data: {} });
+    }
+    const summary = str(args?.summary).trim();
+    if (!summary) {
+      return JSON.stringify({ success: false, error: 'summary is required.', data: {} });
+    }
+
+    const repairs = [];
+    const runId = `recrun-chat-${runtime.turnId}`;
+    const redFlags = arr(args?.red_flags).map((raw, index) => buildRedFlag(raw, repairs, index));
+
+    const urgent = args.urgent_under_24h;
+    let maxActionTimeHours = Number.isInteger(args?.max_action_time_hours) ? args.max_action_time_hours : null;
+    let escalationRoute = ESCALATION_ROUTES.includes(str(args?.escalation_route).trim()) ? str(args.escalation_route).trim() : null;
+    let reasonForEscalation = str(args?.reason_for_escalation).trim() || null;
+    if (!urgent) {
+      const stray = [];
+      if (maxActionTimeHours !== null) { stray.push('max_action_time_hours'); maxActionTimeHours = null; }
+      if (escalationRoute !== null) { stray.push('escalation_route'); escalationRoute = null; }
+      if (reasonForEscalation !== null) { stray.push('reason_for_escalation'); reasonForEscalation = null; }
+      if (stray.length) repairs.push(`no urgente ⇒ anulados campos de escalamiento: ${stray.join(', ')}`);
+    }
+
+    if (urgent) {
+      const basis = redFlags.some((redFlag) => ['confirmed', 'partially_confirmed'].includes(redFlag.verificationStatus));
+      const issues = [];
+      if (maxActionTimeHours === null) issues.push('max_action_time_hours (1-24)');
+      if (!escalationRoute) issues.push(`escalation_route (${ESCALATION_ROUTES.join(' | ')})`);
+      if (!basis) issues.push('≥1 red flag confirmed/partially_confirmed');
+      if (issues.length) {
+        return JSON.stringify({ success: false, error: 'gate_inconsistent', data: { urgent_gate_requires: issues } });
+      }
+    }
+
+    if (await safetyGateExists({ runId })) {
+      return JSON.stringify({ success: false, error: 'gate_already_committed_for_turn', data: { run_id: runId } });
+    }
+
+    const safetyGate = new RecommendationSafetyGate({
+      runId,
+      patientId: runtime.patientCode,
+      origin: 'chat',
+      turnId: runtime.turnId,
+      urgentUnder24h: urgent,
+      maxActionTimeHours,
+      escalationRoute,
+      reasonForEscalation,
+      summary,
+      redFlags,
+      createdAt: new Date().toISOString(),
+    });
+
+    await storeSafetyGate({ patientId: runtime.patientCode, safetyGate });
+
+    const trace = runtime.trace || null;
+    if (trace) {
+      trace.setSignals({
+        safetyGate: {
+          runId,
+          urgentUnder24h: urgent,
+          escalationRoute,
+          redFlagsCount: redFlags.length,
+        },
+      });
+    } else {
+      logger.warn('[submitSafetyGate] no trace on runtime context; safety-gate signal not recorded', { turnId: runtime.turnId });
+    }
+
+    return JSON.stringify({
+      success: true,
+      data: {
+        accepted: true,
+        run_id: runId,
+        urgent_under_24h: urgent,
+        escalation_route: escalationRoute,
+        red_flags_count: redFlags.length,
+        must_escalate_now: urgent,
+        auto_repairs: repairs,
+      },
+    });
+  } catch (err) {
+    if (err instanceof ZodError) {
+      return JSON.stringify({ success: false, error: 'gate_schema_invalid', data: { issues: err.issues.map((issue) => ({ path: issue.path.join('.'), problem: issue.message })) } });
+    }
+    return JSON.stringify({ success: false, error: err?.message || 'submitSafetyGate failed', data: {} });
+  }
+}
+
+module.exports = {
+  definition,
+  handler,
+};

package/lib/fhir/constants/projectionSlugs.js

@@ -9,6 +9,7 @@ const SYMPTOM_CASE_SLUG = 'symptom-condition';
 const SYMPTOM_ASSESSMENT_SLUG = 'symptom-assessment';
 const SYMPTOM_GRADE_SLUG = 'symptom-grade';
 const PATIENT_RISK_SLUG = 'patient-risk-assessment';
+const SAFETY_GATE_SLUG = 'recommendation-safety';
 const CONTINGENCY_PLAN_SLUG = 'contingency-plan';
 const CONTINGENCY_STEP_SLUG = 'contingency-step';
 const INTERVENTION_SLUG = 'intervention';
@@ -31,6 +32,7 @@ module.exports = {
   SYMPTOM_ASSESSMENT_SLUG,
   SYMPTOM_GRADE_SLUG,
   PATIENT_RISK_SLUG,
+  SAFETY_GATE_SLUG,
   CONTINGENCY_PLAN_SLUG,
   CONTINGENCY_STEP_SLUG,
   INTERVENTION_SLUG,

package/lib/fhir/index.js

@@ -2,7 +2,7 @@ const { registerProjector, project, storeResources } = require('./services/fhirS
 const { storeClinicalMentions } = require('./services/clinicalMentionService');
 const { storeResultObservations } = require('./services/resultObservationService');
 const { storeSymptomCase, readSymptomCases } = require('./services/symptomCaseService');
-const { storePatientRisk, readPatientRisk } = require('./services/riskService');
+const { storePatientRisk, readPatientRisk, storeSafetyGate, safetyGateExists } = require('./services/riskService');
 const { storeContingency, readContingencies } = require('./services/contingencyService');
 const { storeIntervention, readInterventions } = require('./services/interventionService');
 const { storeCluster, readClusters } = require('./services/clusterService');
@@ -30,6 +30,8 @@ module.exports = {
   readSymptomCases,
   storePatientRisk,
   readPatientRisk,
+  storeSafetyGate,
+  safetyGateExists,
   storeContingency,
   readContingencies,
   storeIntervention,

package/lib/fhir/projections/registerProjectors.js

@@ -4,6 +4,7 @@ const { projectDispatchedEscalation, PROJECTOR_NAME: ESCALATION_PROJECTOR_NAME }
 const { projectReminder, PROJECTOR_NAME: REMINDER_PROJECTOR_NAME } = require('./reminderProjection');
 const { projectSymptomCase, PROJECTOR_NAME: SYMPTOM_CASE_PROJECTOR_NAME } = require('./symptomCaseProjection');
 const { projectPatientRisk, PROJECTOR_NAME: RISK_PROJECTOR_NAME } = require('./riskProjection');
+const { projectSafetyGate, PROJECTOR_NAME: SAFETY_GATE_PROJECTOR_NAME } = require('./safetyGateProjection');
 const { projectContingency, PROJECTOR_NAME: CONTINGENCY_PROJECTOR_NAME } = require('./contingencyProjection');
 const { projectIntervention, PROJECTOR_NAME: INTERVENTION_PROJECTOR_NAME } = require('./interventionProjection');
 const { projectCluster, PROJECTOR_NAME: CLUSTER_PROJECTOR_NAME } = require('./clusterProjection');
@@ -15,6 +16,7 @@ const PROJECTORS = [
   { name: REMINDER_PROJECTOR_NAME, project: projectReminder },
   { name: SYMPTOM_CASE_PROJECTOR_NAME, project: projectSymptomCase },
   { name: RISK_PROJECTOR_NAME, project: projectPatientRisk },
+  { name: SAFETY_GATE_PROJECTOR_NAME, project: projectSafetyGate },
   { name: CONTINGENCY_PROJECTOR_NAME, project: projectContingency },
   { name: INTERVENTION_PROJECTOR_NAME, project: projectIntervention },
   { name: CLUSTER_PROJECTOR_NAME, project: projectCluster },

package/lib/fhir/projections/safetyGateProjection.js

@@ -0,0 +1,16 @@
+const { RiskAssessment } = require('../resources/RiskAssessment');
+const { Provenance } = require('../resources/Provenance');
+
+const PROJECTOR_NAME = 'safetyGate';
+
+function projectSafetyGate(gate) {
+  return [
+    RiskAssessment.fromSafetyGate({ gate }),
+    Provenance.fromSafetyGate({ gate }),
+  ];
+}
+
+module.exports = {
+  projectSafetyGate,
+  PROJECTOR_NAME,
+};

package/lib/fhir/resources/Provenance.js

@@ -89,6 +89,15 @@ class Provenance {
     });
   }
 
+  static fromSafetyGate({ gate }) {
+    return Provenance.fromSymptomCase({
+      provenanceId: `${gate.runId}-safety-prov`,
+      targetRefs: [{ reference: `RiskAssessment/${fhirId(`${gate.runId}-safety`)}` }],
+      recordedAt: gate.createdAt,
+      activityText: 'recommendation-safety-gate',
+    });
+  }
+
   static fromContingency({ planId, recipients, recordedAt, activityText }) {
     const targets = [{ reference: `CarePlan/${fhirId(planId)}` }];
     for (const recipient of recipients) {

package/lib/fhir/resources/RiskAssessment.js

@@ -8,13 +8,30 @@ const {
   extension,
   toIso,
 } = require('../helpers/elementHelper');
-const { PATIENT_RISK_SLUG } = require('../constants/projectionSlugs');
+const { PATIENT_RISK_SLUG, SAFETY_GATE_SLUG } = require('../constants/projectionSlugs');
 
 const RISK_SEVERITY_CODESYSTEM = 'risk-severity';
 const PREDICTION_KIND_AE = 'ae';
 const PREDICTION_KIND_DISEASE = 'disease';
 const PREDICTION_KIND_COMORBIDITY = 'comorbidity';
 
+const PROBABILITY_TO_RISK = { high: 'high', medium: 'moderate', low: 'low' };
+const PREDICTION_BASIS_STATUSES = ['confirmed', 'partially_confirmed'];
+
+function safetyGatePrediction(ae) {
+  const risk = PROBABILITY_TO_RISK[ae.probabilityGivenPatient] || ae.probabilityGivenPatient;
+  const prediction = {
+    outcome: codeableConcept(ae.ctcaeTerm),
+    qualitativeRisk: codeableConcept(risk, { code: risk, system: codeSystemUrl(RISK_SEVERITY_CODESYSTEM) }),
+  };
+  const rationaleBits = [];
+  if (ae.whyIsRelevant) rationaleBits.push(ae.whyIsRelevant);
+  const grounding = ae.groundedIn.filter(Boolean).join('; ');
+  if (grounding) rationaleBits.push(`sustento: ${grounding}`);
+  if (rationaleBits.length) prediction.rationale = rationaleBits.join(' | ');
+  return prediction;
+}
+
 function aePrediction(ae) {
   const prediction = {
     outcome: codeableConcept(ae.aeName),
@@ -89,6 +106,28 @@ class RiskAssessment {
     if (extensions.length) payload.extension = extensions;
     return new RiskAssessment(payload);
   }
+
+  static fromSafetyGate({ gate }) {
+    const payload = {
+      resourceType: 'RiskAssessment',
+      id: fhirId(`${gate.runId}-safety`),
+      identifier: [identifier(SAFETY_GATE_SLUG, `${gate.runId}-safety`)],
+      status: 'final',
+      subject: patientReference(gate.patientId),
+      performer: reference('Device', getDeviceId()),
+      occurrenceDateTime: toIso(gate.createdAt),
+    };
+    const prediction = gate.redFlags
+      .filter((redFlag) => PREDICTION_BASIS_STATUSES.includes(redFlag.verificationStatus))
+      .flatMap((redFlag) => redFlag.relatedAes.map(safetyGatePrediction));
+    if (prediction.length) payload.prediction = prediction;
+    if (gate.summary) payload.note = [{ text: gate.summary }];
+    if (gate.urgentUnder24h && gate.escalationRoute) {
+      payload.mitigation = `ruta de escalamiento: ${gate.escalationRoute}`
+        + (gate.maxActionTimeHours ? `; actuar en ≤${gate.maxActionTimeHours}h` : '');
+    }
+    return new RiskAssessment(payload);
+  }
 }
 
 module.exports = {

package/lib/fhir/services/riskService.js

@@ -4,6 +4,7 @@ const { fhirId } = require('../helpers/fhirHelper');
 const { identifierValue, extValues } = require('../helpers/fhirReadHelper');
 const { PATIENT_RISK_SLUG } = require('../constants/projectionSlugs');
 const { PROJECTOR_NAME } = require('../projections/riskProjection');
+const { PROJECTOR_NAME: SAFETY_GATE_PROJECTOR_NAME } = require('../projections/safetyGateProjection');
 const {
   PREDICTION_KIND_AE,
   PREDICTION_KIND_DISEASE,
@@ -43,6 +44,22 @@ async function readPatientRisk({ patientId }) {
   return null;
 }
 
+async function storeSafetyGate({ patientId, safetyGate }) {
+  if (safetyGate.patientId !== patientId) {
+    throw new Error(`storeSafetyGate patientId mismatch: expected ${patientId}`);
+  }
+  const bundle = project([{ name: SAFETY_GATE_PROJECTOR_NAME, aggregate: safetyGate }]);
+  const resources = bundle.entry.map((entry) => entry.resource);
+  const { stored } = await storeResources(resources);
+  return { count: stored.length, ids: stored };
+}
+
+async function safetyGateExists({ runId }) {
+  const store = getFhirStore();
+  const resource = await store.getByKey(`Provenance|${fhirId(`${runId}-safety-prov`)}`);
+  return Boolean(resource);
+}
+
 function reconstructRisk(resource, patientId) {
   const predictions = resource.prediction || [];
   return {
@@ -98,4 +115,6 @@ const outcomeText = (prediction) => (prediction.outcome && prediction.outcome.te
 module.exports = {
   storePatientRisk,
   readPatientRisk,
+  storeSafetyGate,
+  safetyGateExists,
 };

package/lib/shared/dtos/RecommendationSafetyGate.js

@@ -0,0 +1,64 @@
+const { z } = require('zod');
+
+const { BaseDto } = require('./BaseDto');
+
+const dateTime = z.iso.datetime({ offset: true });
+
+const ESCALATION_ROUTES = ['emergencia', 'urgencias', 'equipo_tratante_hoy'];
+const RED_FLAG_STATUSES = ['confirmed', 'partially_confirmed', 'inconclusive', 'denied'];
+const RISK_PROBABILITIES = ['high', 'medium', 'low'];
+
+const relatedAeSchema = z.strictObject({
+  ctcaeTerm: z.string(),
+  probabilityGivenPatient: z.enum(RISK_PROBABILITIES),
+  whyIsRelevant: z.string(),
+  groundedIn: z.array(z.string()).default([]),
+});
+
+const redFlagEventSchema = z.strictObject({
+  clinicalEvent: z.string(),
+  ctcaeGradesReference: z.array(z.number().int()).default([]),
+});
+
+const redFlagSchema = z.strictObject({
+  name: z.string(),
+  verificationStatus: z.enum(RED_FLAG_STATUSES),
+  escalationRoute: z.enum(ESCALATION_ROUTES).nullable().default(null),
+  eventsConfirmed: z.array(z.string()).default([]),
+  eventsDenied: z.array(z.string()).default([]),
+  relatedAes: z.array(relatedAeSchema).default([]),
+  definition: z.array(redFlagEventSchema).default([]),
+  groundedIn: z.array(z.string()).default([]),
+});
+
+const schema = z.strictObject({
+  schemaVersion: z.string().default('1'),
+  runId: z.string(),
+  patientId: z.string(),
+  origin: z.enum(['chat', 'triage']).default('chat'),
+  turnId: z.string(),
+  urgentUnder24h: z.boolean(),
+  maxActionTimeHours: z.number().int().min(1).max(24).nullable().default(null),
+  escalationRoute: z.enum(ESCALATION_ROUTES).nullable().default(null),
+  reasonForEscalation: z.string().nullable().default(null),
+  summary: z.string(),
+  redFlags: z.array(redFlagSchema).default([]),
+  createdAt: dateTime,
+})
+  .refine((g) => !g.urgentUnder24h || g.maxActionTimeHours !== null, {
+    message: 'urgent gate requires maxActionTimeHours',
+  })
+  .refine((g) => !g.urgentUnder24h || g.escalationRoute !== null, {
+    message: 'urgent gate requires escalationRoute',
+  });
+
+class RecommendationSafetyGate extends BaseDto {}
+
+RecommendationSafetyGate.schema = schema;
+
+module.exports = {
+  RecommendationSafetyGate,
+  ESCALATION_ROUTES,
+  RED_FLAG_STATUSES,
+  RISK_PROBABILITIES,
+};

package/package.json

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