@peopl-health/nexus 5.45.0-dev.7142 → 5.45.0-dev.7159

package/lib/clinical/config/divergenceConfig.js

@@ -2,6 +2,8 @@ const { Config_ID } = require('../../config/airtableConfig');
 
 const { getRecordByFilter } = require('../../services/airtableService');
 
+const { ESCALATION_ROUTES } = require('../../shared/dtos/RecommendationSafetyGate');
+
 const { MapCache } = require('../../utils/MapCache');
 const { safeParse, safeParseArray, isPlainObject } = require('../../utils/jsonUtils');
 
@@ -14,6 +16,70 @@ const STOCHASTIC_DEFAULTS = { enabled: false, presetId: '' };
 
 const cache = new MapCache({ maxSize: 1, ttl: CACHE_TTL });
 
+function parseSafetyFlagPatterns(value) {
+  if (!value) return [];
+  const parsedPatterns = safeParseArray(value);
+  if (!parsedPatterns) throw new Error('divergence config SAFETY_FLAG_PATTERNS is not a JSON array');
+  return parsedPatterns.map((row) => {
+    if (!isPlainObject(row)) throw new Error('divergence config SAFETY_FLAG_PATTERNS row is not an object');
+    const { flag, pattern } = row;
+    if (!flag || !pattern) throw new Error('divergence config SAFETY_FLAG_PATTERNS row missing flag or pattern');
+    try {
+      return { flag, re: new RegExp(pattern, 'i') };
+    } catch (err) {
+      throw new Error(`divergence config SAFETY_FLAG_PATTERNS pattern for ${flag} is not a valid regex: ${err.message}`);
+    }
+  });
+}
+
+function parseRedFlagMinRoute(row) {
+  if (!isPlainObject(row)) throw new Error('divergence config RED_FLAG_MIN_ROUTES row is not an object');
+  const {
+    flag,
+    ctcae_terms: ctcaeTerms,
+    min_route: minRoute,
+    max_action_time_hours: maxActionTimeHours,
+    requires_risk: requiresRisk = true,
+  } = row;
+  if (typeof flag !== 'string' || !flag.trim()) throw new Error('divergence config RED_FLAG_MIN_ROUTES row missing flag');
+  if (!Array.isArray(ctcaeTerms) || !ctcaeTerms.length || !ctcaeTerms.every((term) => typeof term === 'string' && term.trim())) {
+    throw new Error(`divergence config RED_FLAG_MIN_ROUTES ctcae_terms for ${flag} is not a non-empty list of terms`);
+  }
+  if (!ESCALATION_ROUTES.includes(minRoute)) {
+    throw new Error(`divergence config RED_FLAG_MIN_ROUTES min_route for ${flag} is not one of ${ESCALATION_ROUTES.join(', ')}`);
+  }
+  if (!Number.isInteger(maxActionTimeHours) || maxActionTimeHours < 1 || maxActionTimeHours > 24) {
+    throw new Error(`divergence config RED_FLAG_MIN_ROUTES max_action_time_hours for ${flag} is not an integer from 1 to 24`);
+  }
+  if (typeof requiresRisk !== 'boolean') throw new Error(`divergence config RED_FLAG_MIN_ROUTES requires_risk for ${flag} is not a boolean`);
+  return {
+    flag, ctcaeTerms, minRoute, maxActionTimeHours, requiresRisk,
+  };
+}
+
+function parseRedFlagMinRoutes(value) {
+  const routes = { rows: [], invalidRows: [] };
+  if (!value) return routes;
+  const parsedRoutes = safeParseArray(value);
+  if (!parsedRoutes) throw new Error('divergence config RED_FLAG_MIN_ROUTES is not a JSON array');
+  for (const row of parsedRoutes) {
+    try {
+      routes.rows.push(parseRedFlagMinRoute(row));
+    } catch (err) {
+      routes.invalidRows.push(err.message);
+    }
+  }
+  return routes;
+}
+
+function parseIsolated(parse) {
+  try {
+    return { value: parse(), error: null };
+  } catch (error) {
+    return { value: null, error };
+  }
+}
+
 async function load() {
   const cached = cache.get(CACHE_KEY);
   if (cached) return cached;
@@ -46,23 +112,13 @@ async function load() {
   const stochastic = { ...STOCHASTIC_DEFAULTS, ...(parsedStochastic || {}) };
   if (stochastic.enabled && !stochastic.presetId) throw new Error('divergence config STOCHASTIC.presetId is required when enabled');
 
-  let safetyFlagPatterns = [];
-  if (byKey.SAFETY_FLAG_PATTERNS) {
-    const parsedPatterns = safeParseArray(byKey.SAFETY_FLAG_PATTERNS);
-    if (!parsedPatterns) throw new Error('divergence config SAFETY_FLAG_PATTERNS is not a JSON array');
-    safetyFlagPatterns = parsedPatterns.map((row) => {
-      if (!isPlainObject(row)) throw new Error('divergence config SAFETY_FLAG_PATTERNS row is not an object');
-      const { flag, pattern } = row;
-      if (!flag || !pattern) throw new Error('divergence config SAFETY_FLAG_PATTERNS row missing flag or pattern');
-      try {
-        return { flag, re: new RegExp(pattern, 'i') };
-      } catch (err) {
-        throw new Error(`divergence config SAFETY_FLAG_PATTERNS pattern for ${flag} is not a valid regex: ${err.message}`);
-      }
-    });
-  }
-
-  const config = { FIELDS: fields, ORACLE_CONNECTION: oracleConnection, STOCHASTIC: stochastic, SAFETY_FLAG_PATTERNS: safetyFlagPatterns };
+  const config = {
+    FIELDS: fields,
+    ORACLE_CONNECTION: oracleConnection,
+    STOCHASTIC: stochastic,
+    SAFETY_FLAG_PATTERNS: parseIsolated(() => parseSafetyFlagPatterns(byKey.SAFETY_FLAG_PATTERNS)),
+    RED_FLAG_MIN_ROUTES: parseIsolated(() => parseRedFlagMinRoutes(byKey.RED_FLAG_MIN_ROUTES)),
+  };
   cache.set(CACHE_KEY, config);
   return config;
 }
@@ -72,9 +128,16 @@ async function get(key) {
   return config[key];
 }
 
+async function getIsolated(key) {
+  const { value, error } = await get(key);
+  if (error) throw error;
+  return value;
+}
+
 module.exports = {
   getFields: () => get('FIELDS'),
   getOracleConnection: () => get('ORACLE_CONNECTION'),
   getStochastic: () => get('STOCHASTIC'),
-  getSafetyFlagPatterns: () => get('SAFETY_FLAG_PATTERNS'),
+  getSafetyFlagPatterns: () => getIsolated('SAFETY_FLAG_PATTERNS'),
+  getRedFlagMinRoutes: () => getIsolated('RED_FLAG_MIN_ROUTES'),
 };

package/lib/clinical/helpers/recommendationGateHelper.js

@@ -1,8 +1,10 @@
 const { ESCALATION_ROUTES, RED_FLAG_STATUSES } = require('../../shared/dtos/RecommendationSafetyGate');
+const { aliasClosure } = require('../../fhir/helpers/symptomAliasHelper');
 const { str, arr, strList } = require('../../utils/coercionUtils');
 const { foldAccents } = require('../../utils/formatUtils');
 
 const ECHO_SHARE = 0.5;
+const ROUTE_FLOOR_UNVERIFIABLE_CODE = 'route_floor_unverifiable';
 
 const tokensOf = (text) => foldAccents(str(text)).toLowerCase().match(/[a-z0-9]{4,}/g) || [];
 
@@ -107,6 +109,93 @@ function normalizeGateEscalation(raw, repairs) {
   return { urgent, maxActionTimeHours, escalationRoute, reasonForEscalation };
 }
 
+const routeUrgency = (route) => ESCALATION_ROUTES.indexOf(route);
+
+const aliasKeySet = (catalog, terms) => new Set(terms.flatMap((term) => aliasClosure(catalog, term)));
+
+function riskSymptomKeys(catalog, riskAssessment) {
+  return aliasKeySet(catalog, [
+    ...arr(riskAssessment?.predictedAes)
+      .filter((ae) => ae?.severityIfConfirmed === 'emergency')
+      .flatMap((ae) => arr(ae.relatedSymptomTerms)),
+    ...arr(riskAssessment?.diseaseRisks).flatMap((risk) => arr(risk?.relatedSymptomTerms)),
+  ]);
+}
+
+const unverifiableFloor = (subject, reason) => ({
+  path: 'escalation_route',
+  code: ROUTE_FLOOR_UNVERIFIABLE_CODE,
+  warning: true,
+  problem: `${subject}: ${reason}; el gate no se elevó`,
+});
+
+function applyRouteFloor(escalation, {
+  catalog,
+  rows = [],
+  invalidRows = [],
+  affirmedKeys = new Set(),
+  riskAssessment = null,
+  riskReadFailed = false,
+  freeTextPending = false,
+  configError = null,
+} = {}, repairs = [], warnings = []) {
+  if (configError) {
+    warnings.push(unverifiableFloor('rutas mínimas no verificables', `no se pudo leer RED_FLAG_MIN_ROUTES (${configError})`));
+    return escalation;
+  }
+  if (invalidRows.length) {
+    warnings.push({
+      path: 'escalation_route',
+      code: ROUTE_FLOOR_UNVERIFIABLE_CODE,
+      warning: true,
+      problem: `rutas mínimas incompletas: se ignoraron filas inválidas de RED_FLAG_MIN_ROUTES (${invalidRows.join('; ')}); esas filas no pueden elevar el gate`,
+    });
+  }
+  const riskKeys = riskSymptomKeys(catalog, riskAssessment);
+  const fired = [];
+  for (const row of rows) {
+    const termKeys = [...aliasKeySet(catalog, row.ctcaeTerms)];
+    const eligibleKeys = termKeys.filter((key) => !row.requiresRisk || riskKeys.has(key));
+    if (eligibleKeys.some((key) => affirmedKeys.has(key))) {
+      fired.push(row);
+    } else if (row.requiresRisk && !riskAssessment && termKeys.some((key) => affirmedKeys.has(key))) {
+      const reason = riskReadFailed ? 'no se pudo leer el perfil de riesgo' : 'no hay perfil de riesgo';
+      warnings.push(unverifiableFloor(`ruta mínima ${row.minRoute} de ${row.flag} no verificable`, reason));
+    } else if (freeTextPending && eligibleKeys.length) {
+      warnings.push(unverifiableFloor(`ruta mínima ${row.minRoute} de ${row.flag} no verificable`, 'el clasificador del texto libre no ha terminado'));
+    }
+  }
+  if (!fired.length) return escalation;
+  const currentRoute = escalation.urgent ? escalation.escalationRoute : null;
+  const currentHours = escalation.urgent ? escalation.maxActionTimeHours : null;
+  const floorRoute = fired.map((row) => row.minRoute).sort((left, right) => routeUrgency(left) - routeUrgency(right))[0];
+  const floorHours = Math.min(...fired.map((row) => row.maxActionTimeHours));
+  const route = currentRoute && routeUrgency(currentRoute) <= routeUrgency(floorRoute) ? currentRoute : floorRoute;
+  const hours = Number.isInteger(currentHours) ? Math.min(currentHours, floorHours) : floorHours;
+  const routeRaised = route !== currentRoute;
+  const windowTightened = hours !== currentHours;
+  if (!routeRaised && !windowTightened) return escalation;
+  const flags = [...new Set(fired
+    .filter((row) => (routeRaised && row.minRoute === route) || (windowTightened && row.maxActionTimeHours === hours))
+    .map((row) => row.flag))].join(', ');
+  const changes = [
+    routeRaised ? `escalation_route ${currentRoute ? `'${currentRoute}'` : 'null'} → '${route}'` : null,
+    windowTightened ? `max_action_time_hours ${currentHours ?? 'null'} → ${hours}` : null,
+    escalation.urgent ? null : 'urgent_under_24h false → true',
+  ].filter(Boolean);
+  repairs.push(`ruta mínima por término reportado (${flags}): ${changes.join(', ')}`);
+  return {
+    ...escalation,
+    urgent: true,
+    maxActionTimeHours: hours,
+    escalationRoute: route,
+    reasonForEscalation: escalation.reasonForEscalation || `Término reportado en este triaje (${flags}): ruta mínima ${route}, máximo ${hours} h.`,
+    summary: [str(escalation.summary).trim(), `Ruta mínima aplicada por un término reportado en este triaje (${flags}): ${route}, máximo ${hours} h.`]
+      .filter(Boolean)
+      .join(' '),
+  };
+}
+
 module.exports = {
   str,
   arr,
@@ -115,4 +204,5 @@ module.exports = {
   normalizeStatus,
   buildRedFlag,
   normalizeGateEscalation,
+  applyRouteFloor,
 };

package/lib/clinical/services/triageRecommendationService.js

@@ -1,10 +1,12 @@
 const { getTriageGate, getTriagePlan } = require('../config/subAgentsConfig');
-const { getSafetyFlagPatterns } = require('../config/divergenceConfig');
+const { getSafetyFlagPatterns, getRedFlagMinRoutes } = require('../config/divergenceConfig');
 const { requireGatewayProvider } = require('../config/llmConfig');
 const { getTriageRecommendationEventModel } = require('../models/triageRecommendationEventModel');
 const { isShadowRun } = require('../helpers/shadowHelper');
 const { readOutputText } = require('../helpers/clinicalMentionHelper');
-const { str, arr, buildRedFlag, normalizeGateEscalation } = require('../helpers/recommendationGateHelper');
+const {
+  str, arr, buildRedFlag, normalizeGateEscalation, applyRouteFloor,
+} = require('../helpers/recommendationGateHelper');
 const { buildElement, nullableStr } = require('../helpers/recommendationPlanHelper');
 const { readClinicalProfile } = require('../helpers/clinicalProfileHelper');
 const {
@@ -265,7 +267,13 @@ async function generateTriageRecommendations({ payload, provider, runId = null }
   if (profile === undefined) return { ...settle, status: 'failed', stage: 'assemble', reason: 'profile_read_failed' };
   if (!profile) return { ...settle, status: 'failed', stage: 'assemble', reason: 'no_clinical_profile' };
 
-  const [riskAssessment] = await readPatientRiskAssessments({ patientId: code, limit: 1 }).catch(() => []);
+  const riskRead = await readPatientRiskAssessments({ patientId: code, limit: 1 })
+    .then((assessments) => ({ assessments, failed: false }))
+    .catch((err) => {
+      logger.warn('[triageRecommendation] risk assessment unavailable; section degraded', { code, error: err?.message });
+      return { assessments: [], failed: true };
+    });
+  const [riskAssessment] = riskRead.assessments;
   // A failed read degrades the section; it must never fail the run.
   const [openCases, escalations] = await Promise.all([
     readSymptomCases({ patientId: code })
@@ -315,16 +323,40 @@ async function generateTriageRecommendations({ payload, provider, runId = null }
     ...freeTextDerivedSymptoms,
   ];
   const reportedKeys = symptomKeySet(catalog, reportedTerms);
+  const floorConfig = await getRedFlagMinRoutes()
+    .then(({ rows, invalidRows }) => ({ rows, invalidRows, configError: null }))
+    .catch((err) => {
+      logger.warn('[triageRecommendation] red-flag minimum routes unavailable; no route floor', { code, error: err?.message });
+      return { rows: [], invalidRows: [], configError: err?.message || 'desconocido' };
+    });
+  const routeFloor = {
+    catalog,
+    ...floorConfig,
+    affirmedKeys: reportedKeys,
+    riskAssessment,
+    riskReadFailed: riskRead.failed,
+    freeTextPending: settle.classifierPending === true && freeTextBits.length > 0,
+  };
 
   const gateStart = Date.now();
-  const gateOutcome = await runGate({ provider, presetId: gatePresetId, casoBase: casoBaseFor('gate'), rid, code, payload });
+  const gateOutcome = await runGate({
+    provider, presetId: gatePresetId, casoBase: casoBaseFor('gate'), routeFloor, rid, code, payload,
+  });
   settle.gateLatencyMs = Date.now() - gateStart;
   settle.gateAttempts = gateOutcome.attempts;
-  if (gateOutcome.failure) return { ...settle, ...gateOutcome.failure, autoRepairs: gateOutcome.gateRepairs || [] };
-  const { gate, gateRepairs } = gateOutcome;
+  if (gateOutcome.failure) {
+    return {
+      ...settle,
+      ...gateOutcome.failure,
+      autoRepairs: gateOutcome.gateRepairs || [],
+      qualityWarnings: gateOutcome.gateWarnings || settle.qualityWarnings,
+    };
+  }
+  const { gate, gateRepairs, gateWarnings } = gateOutcome;
   settle.gateVerdict = gate.urgentUnder24h ? 'urgent' : 'clear';
   settle.urgentUnder24h = gate.urgentUnder24h;
   settle.escalationRoute = gate.escalationRoute;
+  settle.qualityWarnings = gateWarnings;
 
   const planStart = Date.now();
   const boundary = {
@@ -344,7 +376,7 @@ async function generateTriageRecommendations({ payload, provider, runId = null }
   const { plan, planRepairs, qualityWarnings } = planOutcome;
   settle.elementCount = plan.elements.length;
   settle.autoRepairs = [...gateRepairs, ...planRepairs];
-  settle.qualityWarnings = qualityWarnings;
+  settle.qualityWarnings = [...gateWarnings, ...qualityWarnings];
   settle.rankReordered = planOutcome.rankReordered;
   settle.deniedCardsDropped = planOutcome.deniedCardsDropped;
   settle.deniedTargetsStripped = planOutcome.deniedTargetsStripped;
@@ -404,7 +436,9 @@ function rejectedGateShape(rawGate, redFlags) {
   };
 }
 
-async function runGate({ provider, presetId, casoBase, rid, code, payload }) {
+async function runGate({
+  provider, presetId, casoBase, routeFloor, rid, code, payload,
+}) {
   let attempts = 0;
   let gateRepairs = [];
   let accepted = null;
@@ -468,7 +502,10 @@ async function runGate({ provider, presetId, casoBase, rid, code, payload }) {
     break;
   }
   if (!accepted) return { attempts, gateRepairs, failure: { status: 'failed', stage: 'safety_gate', reason: 'gate_malformed' } };
-  const { summary, redFlags, urgent, maxActionTimeHours, escalationRoute, reasonForEscalation } = accepted;
+  const gateWarnings = [];
+  const {
+    summary, redFlags, urgent, maxActionTimeHours, escalationRoute, reasonForEscalation,
+  } = applyRouteFloor(accepted, routeFloor, gateRepairs, gateWarnings);
 
   let gate;
   try {
@@ -487,15 +524,21 @@ async function runGate({ provider, presetId, casoBase, rid, code, payload }) {
     });
   } catch (err) {
     logger.warn('[triageRecommendation] gate failed DTO validation', { code, runId: rid, error: err?.message });
-    return { attempts, gateRepairs, failure: { status: 'failed', stage: 'safety_gate', reason: 'gate_malformed' } };
+    return {
+      attempts, gateRepairs, gateWarnings, failure: { status: 'failed', stage: 'safety_gate', reason: 'gate_malformed' },
+    };
   }
   try {
     await storeSafetyGate({ patientId: code, safetyGate: gate });
   } catch (err) {
     logger.error('[triageRecommendation] gate store failed', { code, runId: rid, error: err?.message });
-    return { attempts, gateRepairs, failure: { status: 'failed', stage: 'fhir', reason: 'gate_store_failed' } };
+    return {
+      attempts, gateRepairs, gateWarnings, failure: { status: 'failed', stage: 'fhir', reason: 'gate_store_failed' },
+    };
   }
-  return { attempts, gate, gateRepairs };
+  return {
+    attempts, gate, gateRepairs, gateWarnings,
+  };
 }
 
 async function runPlan({ provider, presetId, casoBase, gate, boundary = null, rid, code, payload }) {

package/package.json

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