@fhiron/sdk 0.1.0

package/src/_linter/catalog.js

@@ -0,0 +1,638 @@
+// Fhiron linter — catálogo pedagógico de códigos.
+//
+// Para cada código (cl-* y hapi-*) responde las cuatro preguntas del feedback:
+//
+//   • what       → resumen corto (en español; el linter ya lo emite como `message`)
+//   • why        → POR QUÉ está mal — frase pedagógica con contexto CL Core / FHIR
+//   • profileUrl → DÓNDE SE INDICA — URL canónica del StructureDefinition / CodeSystem
+//   • docsUrl    → link humano a la doc explicativa (fhiron.cl/errores/{code})
+//   • suggestion → SOLUCIÓN explicada cuando no hay quickFix mecánico
+//   • example    → recorte JSON correcto cercano al error (5–10 líneas)
+//
+// Diseño:
+//   - Tabla pura (objeto) — sin lógica. La función enrichIssue() vive en rules.js.
+//   - Si un código no está en el catálogo, enrichIssue lo deja intacto (compat).
+//   - Para issues hapi-error / hapi-warning de `route.ts`, el código viene
+//     enriquecido con un sub-tipo categorizado por la traducción (ej.
+//     hapi-error.cardinality, hapi-error.terminology). Si no, fallback genérico.
+
+"use strict";
+
+// ── URLs canónicas CL Core v1.9.4 ───────────────────────────────────────────
+
+const IG_BASE = "https://hl7chile.cl/fhir/ig/clcore";
+const SD = (id) => `${IG_BASE}/StructureDefinition/${id}`;
+const CS = (id) => `${IG_BASE}/CodeSystem/${id}`;
+const VS = (id) => `${IG_BASE}/ValueSet/${id}`;
+const DOCS = (code) => `https://docs.fhiron.cl/errores/${code}`;
+
+// ── URLs canónicas MINSAL EIS v0.1.0 ────────────────────────────────────────
+// IG paralelo a CL Core publicado por Unidad de Interoperabilidad del MINSAL.
+// Sólo terminología (49 CodeSystems + 49 ValueSets), 0 perfiles.
+const EIS_BASE = "https://interoperabilidad.minsal.cl/fhir/ig/eis";
+const EIS_CS = (id) => `${EIS_BASE}/CodeSystem/${id}`;
+const EIS_VS = (id) => `${EIS_BASE}/ValueSet/${id}`;
+
+// ── Ejemplos válidos breves (para campo `example` por código) ────────────────
+
+const EX_PATIENT_RUN = {
+  resourceType: "Patient",
+  meta: { profile: [SD("CorePacienteCl")] },
+  identifier: [{
+    use: "official",
+    type: { coding: [{ system: CS("CSTipoIdentificador"), code: "01" }] },
+    system: "http://www.registrocivil.cl/run",
+    value: "12345678-5",
+  }],
+  name: [{ family: "Pérez", given: ["María"] }],
+  gender: "female",
+};
+
+const EX_PATIENT_NAME = {
+  resourceType: "Patient",
+  name: [{ family: "Pérez", given: ["María"] }],
+};
+
+const EX_OBSERVATION = {
+  resourceType: "Observation",
+  status: "final",
+  code: { coding: [{ system: "http://loinc.org", code: "29463-7", display: "Peso corporal" }] },
+  subject: { reference: "Patient/123" },
+};
+
+const EX_MEDICATION = {
+  resourceType: "Medication",
+  code: {
+    coding: [{
+      system: "http://www.whocc.no/atc",
+      code: "C09AA02",
+      display: "Enalapril 10 mg",
+    }],
+  },
+};
+
+const EX_MEDREQ = {
+  resourceType: "MedicationRequest",
+  status: "active",
+  intent: "order",
+  subject: { reference: "Patient/123" },
+  medicationCodeableConcept: { coding: [{ system: "http://www.whocc.no/atc", code: "C09AA02" }] },
+};
+
+const EX_ENCOUNTER = {
+  resourceType: "Encounter",
+  status: "finished",
+  class: { system: "http://terminology.hl7.org/CodeSystem/v3-ActCode", code: "AMB", display: "ambulatorio" },
+  subject: { reference: "Patient/123" },
+};
+
+const EX_CONDITION = {
+  resourceType: "Condition",
+  subject: { reference: "Patient/123" },
+  code: { coding: [{ system: "http://hl7.org/fhir/sid/icd-10", code: "I10", display: "Hipertensión esencial" }] },
+};
+
+const EX_ALLERGY = {
+  resourceType: "AllergyIntolerance",
+  patient: { reference: "Patient/123" },
+  code: { coding: [{ system: "http://snomed.info/sct", code: "256349002", display: "Maní" }] },
+};
+
+const EX_PROCEDURE = {
+  resourceType: "Procedure",
+  status: "completed",
+  subject: { reference: "Patient/123" },
+  code: { coding: [{ system: "http://snomed.info/sct", code: "80146002", display: "Apendicectomía" }] },
+};
+
+const EX_COVERAGE = {
+  resourceType: "Coverage",
+  status: "active",
+  beneficiary: { reference: "Patient/123" },
+  payor: [{ reference: "Organization/fonasa" }],
+};
+
+const EX_ORG = {
+  resourceType: "Organization",
+  name: "Hospital Clínico Universidad de Chile",
+};
+
+const EX_IMM = {
+  resourceType: "Immunization",
+  status: "completed",
+  vaccineCode: { coding: [{ system: "http://hl7.org/fhir/sid/cvx", code: "208", display: "COVID-19 mRNA" }] },
+  patient: { reference: "Patient/123" },
+  occurrenceDateTime: "2026-04-29",
+};
+
+const EX_DR = {
+  resourceType: "DiagnosticReport",
+  status: "final",
+  code: { coding: [{ system: "http://loinc.org", code: "11502-2", display: "Laboratory report" }] },
+  subject: { reference: "Patient/123" },
+};
+
+const EX_BUNDLE = {
+  resourceType: "Bundle",
+  type: "collection",
+  entry: [{ resource: EX_PATIENT_RUN }],
+};
+
+// ── Catálogo principal ──────────────────────────────────────────────────────
+
+const CATALOG = {
+  // ── Formato y estructura ──────────────────────────────────────────────────
+  "cl-json-01": {
+    why: "El cuerpo de la petición no es JSON válido — un coma faltante, una comilla suelta o una llave sin cerrar bastan para que el parser falle. FHIR exige JSON estricto (no JSON5).",
+    suggestion: "Pega el recurso en jsonlint.com o en un IDE que resalte errores de JSON. Revisa el carácter en la posición indicada por el mensaje.",
+    docsUrl: DOCS("cl-json-01"),
+  },
+  "cl-json-02": {
+    why: "FHIR R4 modela cada recurso como un objeto JSON con la propiedad `resourceType`. Arrays, números o strings sueltos no son recursos válidos.",
+    suggestion: "Envuelve el contenido en `{ \"resourceType\": \"<Tipo>\", ... }`.",
+    docsUrl: DOCS("cl-json-02"),
+  },
+  "cl-json-03": {
+    why: "`resourceType` es el discriminador que le dice al servidor qué perfil aplicar. Sin él, HAPI no puede invocar la validación correcta.",
+    suggestion: "Agrega `\"resourceType\": \"Patient\"` (o el tipo que corresponda) como primera propiedad.",
+    example: { resourceType: "Patient", identifier: [], name: [{ family: "..." }] },
+    docsUrl: DOCS("cl-json-03"),
+  },
+  "cl-json-04": {
+    why: "FHIR R4 define ~145 resourceTypes oficiales. Si usas un nombre que no existe, HAPI rechazará el recurso con HTTP 404.",
+    suggestion: "Revisa la lista oficial en https://hl7.org/fhir/R4/resourcelist.html. Los recursos más usados en CL Core son Patient, Practitioner, Encounter, Condition, MedicationRequest.",
+    docsUrl: DOCS("cl-json-04"),
+  },
+
+  // ── RUN chileno (perfil CorePacienteCl + CSTipoIdentificador) ────────────
+  "cl-run-01": {
+    why: "CL Core v1.9.4 normaliza el RUN al cuerpo numérico sin puntos: `12345678-5`. Los puntos son una convención visual chilena, pero no se almacenan en sistemas FHIR. CL Core indica el tipo de identificador con `code: \"01\"` del CodeSystem CSTipoIdentificador.",
+    profileUrl: SD("CorePacienteCl"),
+    suggestion: "Aplica el quickFix incluido o quita los puntos manualmente. El dígito verificador conserva su posición tras el guión.",
+    example: { identifier: [{ system: CS("CSTipoIdentificador"), value: "12345678-5" }] },
+    docsUrl: DOCS("cl-run-01"),
+  },
+  "cl-run-02": {
+    why: "Un identifier con `system` que apunta al RUN sin `value` es un campo a medio llenar — FHIR rechaza identifiers parciales porque comprometen la integridad referencial.",
+    profileUrl: SD("CorePacienteCl"),
+    suggestion: "Agrega el RUN como string en `identifier[i].value` con formato `12345678-5`.",
+    example: { identifier: [{ system: CS("CSTipoIdentificador"), value: "12345678-5" }] },
+    docsUrl: DOCS("cl-run-02"),
+  },
+  "cl-run-03": {
+    why: "El dígito verificador se calcula con módulo 11 sobre el cuerpo del RUN (Decreto Ley 1.094 / Servicio de Registro Civil). Si no coincide, el RUN no existe o fue tipeado mal — CL Core lo rechaza para evitar pacientes fantasma.",
+    profileUrl: SD("CorePacienteCl"),
+    suggestion: "Verifica el RUN contra el registro civil o usa una calculadora de DV. El mensaje indica qué DV se esperaba.",
+    example: { identifier: [{ system: CS("CSTipoIdentificador"), value: "12345678-5" }] },
+    docsUrl: DOCS("cl-run-03"),
+  },
+  "cl-run-04": {
+    why: "El system `https://hl7chile.cl/identificador/run` quedó obsoleto en CL Core v1.7+. La nueva versión unifica todos los identificadores chilenos bajo CSTipoIdentificador con `code: \"01\"` (RUN).",
+    profileUrl: CS("CSTipoIdentificador"),
+    suggestion: "Reemplaza el system por `https://hl7chile.cl/fhir/ig/clcore/CodeSystem/CSTipoIdentificador` y agrega `type.coding[0].code = \"01\"`.",
+    docsUrl: DOCS("cl-run-04"),
+  },
+
+  // ── Patient (CorePacienteCl) ──────────────────────────────────────────────
+  "cl-patient-01": {
+    why: "Un Patient sin identifier es un paciente anónimo — incumple la traza de auditoría exigida por la Ley 21.719 y el perfil CorePacienteCl. Sin identifier, no puedes vincular Encounters, Observations ni Coverage.",
+    profileUrl: SD("CorePacienteCl"),
+    suggestion: "Incluye al menos un identifier — usualmente el RUN con system CSTipoIdentificador. Para extranjeros usa pasaporte (code 02) o DNI (code 03).",
+    example: EX_PATIENT_RUN,
+    docsUrl: DOCS("cl-patient-01"),
+  },
+  "cl-patient-02": {
+    why: "CorePacienteCl marca `name` como [1..*] obligatorio porque sin nombre el recurso no es legible para clínicos ni cumple el deber de identificar al titular del dato (principio de calidad de la Ley 21.719).",
+    profileUrl: SD("CorePacienteCl"),
+    suggestion: "Agrega `name: [{ family: \"<Apellido Paterno>\", given: [\"<Nombres>\"] }]`. CL Core acepta múltiples apellidos como entradas separadas en `family` o como extensión `SegundoApellido`.",
+    example: EX_PATIENT_NAME,
+    docsUrl: DOCS("cl-patient-02"),
+  },
+  "cl-patient-03": {
+    why: "Cada elemento de `name` debe tener al menos `family` o `given` — un objeto vacío es ruido que rompe el binding del HumanName.",
+    profileUrl: SD("CorePacienteCl"),
+    suggestion: "Llena al menos uno de los dos campos por cada nombre del paciente.",
+    docsUrl: DOCS("cl-patient-03"),
+  },
+  "cl-patient-04": {
+    why: "`gender` administrativo (no biológico) es recomendado para vincular trayectorias clínicas y reportar al MINSAL. Su ausencia no rompe la validación pero reduce calidad de los reportes.",
+    profileUrl: SD("CorePacienteCl"),
+    suggestion: "Agrega `gender` con uno de: `male`, `female`, `other`, `unknown`. Para sexo biológico distinto del administrativo, usa la extensión `SexoBiologico` de CL Core.",
+    docsUrl: DOCS("cl-patient-04"),
+  },
+
+  // ── Practitioner (CorePrestadorCl) ────────────────────────────────────────
+  "cl-practitioner-01": {
+    why: "CorePrestadorCl exige un identificador único — usualmente el RUN del prestador o su código DEIS. Sin él no puedes vincular el profesional a Encounters ni acreditar la atención ante FONASA/Isapre.",
+    profileUrl: SD("CorePrestadorCl"),
+    suggestion: "Agrega `identifier` con system CSTipoIdentificador (RUN) o el system del registro de prestadores SIS.",
+    docsUrl: DOCS("cl-practitioner-01"),
+  },
+  "cl-practitioner-02": {
+    why: "Sin nombre el prestador no es identificable en la historia clínica ni en facturación.",
+    profileUrl: SD("CorePrestadorCl"),
+    suggestion: "Agrega `name: [{ family, given }]`.",
+    docsUrl: DOCS("cl-practitioner-02"),
+  },
+
+  // ── Observation ───────────────────────────────────────────────────────────
+  "cl-obs-01": {
+    why: "`status` indica si la observación es preliminar, final o corregida — sin ese contexto un valor clínico no se puede interpretar legalmente.",
+    suggestion: "Usa `final` para resultados confirmados, `preliminary` para borradores, `amended` para correcciones.",
+    example: EX_OBSERVATION,
+    docsUrl: DOCS("cl-obs-01"),
+  },
+  "cl-obs-02": {
+    why: "`code` define qué se midió — sin él, un valor numérico no significa nada. CL Core recomienda LOINC para signos vitales y laboratorio.",
+    suggestion: "Usa `code: { coding: [{ system: \"http://loinc.org\", code: \"<LOINC>\" }] }`.",
+    example: EX_OBSERVATION,
+    docsUrl: DOCS("cl-obs-02"),
+  },
+  "cl-obs-03": {
+    why: "Toda observación se hace sobre alguien — sin `subject` el valor flota desconectado del paciente y rompe la cadena clínica.",
+    suggestion: "Agrega `subject: { reference: \"Patient/<id>\" }`.",
+    docsUrl: DOCS("cl-obs-03"),
+  },
+
+  // ── Medication (CoreMedicamentoCl) ────────────────────────────────────────
+  "cl-med-01": {
+    why: "Sin código no se puede dispensar ni facturar. CL Core CoreMedicamentoCl recomienda ATC (http://www.whocc.no/atc), SNOMED CT o RxNorm como systems canónicos.",
+    profileUrl: SD("CoreMedicamentoCl"),
+    suggestion: "Usa el código ATC del medicamento. Para fármacos sin ATC asignado, usa SNOMED CT o RxNorm.",
+    example: EX_MEDICATION,
+    docsUrl: DOCS("cl-med-01"),
+  },
+  "cl-med-02": {
+    why: "Los códigos propietarios (custom.example.com) no se pueden mapear a otros sistemas — CL Core privilegia ATC, SNOMED CT y RxNorm para garantizar interoperabilidad.",
+    profileUrl: SD("CoreMedicamentoCl"),
+    suggestion: "Migra al sistema ATC (http://www.whocc.no/atc). Para fármacos sin ATC, usa SNOMED CT o RxNorm.",
+    docsUrl: DOCS("cl-med-02"),
+  },
+
+  // ── MedicationRequest ─────────────────────────────────────────────────────
+  "cl-medreq-01": {
+    why: "El status (`active`, `completed`, `cancelled`...) es lo que un sistema de despacho consulta para decidir si entregar el medicamento.",
+    suggestion: "`active` para órdenes vigentes, `completed` cuando se despachó, `cancelled` si fue revocada.",
+    example: EX_MEDREQ,
+    docsUrl: DOCS("cl-medreq-01"),
+  },
+  "cl-medreq-02": {
+    why: "`intent` distingue si es propuesta (`proposal`), plan (`plan`) o orden ejecutable (`order`). Sin él, la cascada de autorizaciones no funciona.",
+    suggestion: "`order` para una receta médica formal, `plan` para una indicación pendiente de aprobación.",
+    example: EX_MEDREQ,
+    docsUrl: DOCS("cl-medreq-02"),
+  },
+  "cl-medreq-03": {
+    why: "Toda receta es para alguien — el `subject` enlaza al Patient destinatario.",
+    suggestion: "`subject: { reference: \"Patient/<id>\" }`.",
+    docsUrl: DOCS("cl-medreq-03"),
+  },
+  "cl-medreq-04": {
+    why: "El medicamento puede ir como CodeableConcept (in-line) o Reference a un Medication separado. Sin uno de los dos, la receta no tiene contenido.",
+    suggestion: "Para casos simples usa `medicationCodeableConcept`; para reutilizar un Medication catalogado usa `medicationReference`.",
+    example: EX_MEDREQ,
+    docsUrl: DOCS("cl-medreq-04"),
+  },
+
+  // ── Encounter (EncounterCL) ───────────────────────────────────────────────
+  "cl-enc-01": {
+    why: "El status indica el estado del encuentro. Sin él no puedes facturar ni cerrar la atención.",
+    profileUrl: SD("EncounterCL"),
+    suggestion: "`finished` para encuentros cerrados, `in-progress` para activos, `arrived` para esperando.",
+    example: EX_ENCOUNTER,
+    docsUrl: DOCS("cl-enc-01"),
+  },
+  "cl-enc-02": {
+    why: "`class` clasifica el tipo de atención (ambulatoria, hospitalizada, urgencia). Es input crítico para reportería FONASA y GES.",
+    profileUrl: SD("EncounterCL"),
+    suggestion: "Usa el ValueSet v3-ActCode: `AMB` ambulatorio, `IMP` hospitalizado, `EMER` urgencia.",
+    example: EX_ENCOUNTER,
+    docsUrl: DOCS("cl-enc-02"),
+  },
+  "cl-enc-03": {
+    why: "Un encuentro sin paciente no es atendible — el subject ancla todo el resto del registro clínico.",
+    profileUrl: SD("EncounterCL"),
+    suggestion: "`subject: { reference: \"Patient/<id>\" }`.",
+    docsUrl: DOCS("cl-enc-03"),
+  },
+
+  // ── Condition (CoreDiagnosticoCl) ───────────────────────────────────────────
+  "cl-cond-01": {
+    why: "Un diagnóstico siempre pertenece a alguien.",
+    profileUrl: SD("CoreDiagnosticoCl"),
+    suggestion: "`subject: { reference: \"Patient/<id>\" }`.",
+    docsUrl: DOCS("cl-cond-01"),
+  },
+  "cl-cond-02": {
+    why: "Sin código, el diagnóstico es solo texto y no se puede agregar a estadísticas DEIS ni cubrir bajo GES.",
+    profileUrl: SD("CoreDiagnosticoCl"),
+    suggestion: "Usa CIE-10 (`http://hl7.org/fhir/sid/icd-10`) o SNOMED CT (`http://snomed.info/sct`).",
+    example: EX_CONDITION,
+    docsUrl: DOCS("cl-cond-02"),
+  },
+
+  // ── AllergyIntolerance (CoreAlergiaIntCl) ───────────────────────────────────
+  "cl-allergy-01": {
+    why: "La alergia siempre es de un paciente — sin el campo `patient` el aviso no llega a HCE.",
+    profileUrl: SD("CoreAlergiaIntCl"),
+    suggestion: "`patient: { reference: \"Patient/<id>\" }`.",
+    docsUrl: DOCS("cl-allergy-01"),
+  },
+  "cl-allergy-02": {
+    why: "Sin código no se puede generar alerta automática en farmacia ni cruzar con interacciones.",
+    profileUrl: SD("CoreAlergiaIntCl"),
+    suggestion: "Usa SNOMED CT (sustancia) o el catálogo de alergias DEIS.",
+    example: EX_ALLERGY,
+    docsUrl: DOCS("cl-allergy-02"),
+  },
+
+  // ── Procedure ─────────────────────────────────────────────────────────────
+  "cl-proc-01": {
+    why: "Status indica si el procedimiento se completó, se interrumpió o quedó preparado.",
+    suggestion: "`completed` para terminados, `in-progress` durante ejecución.",
+    example: EX_PROCEDURE,
+    docsUrl: DOCS("cl-proc-01"),
+  },
+  "cl-proc-02": {
+    why: "El procedimiento se realiza sobre un paciente.",
+    suggestion: "`subject: { reference: \"Patient/<id>\" }`.",
+    docsUrl: DOCS("cl-proc-02"),
+  },
+  "cl-proc-03": {
+    why: "Sin código no se puede facturar a FONASA ni cruzar con la canasta GES.",
+    suggestion: "Usa SNOMED CT o la codificación de prestaciones FONASA/MAI.",
+    example: EX_PROCEDURE,
+    docsUrl: DOCS("cl-proc-03"),
+  },
+
+  // ── Coverage ──────────────────────────────────────────────────────────────
+  // CL Core 1.9.4 no incluye un perfil dedicado para Coverage. Se valida
+  // contra la base R4 de FHIR; las recomendaciones siguen aplicando para
+  // que el flujo FONASA / Isapre quede bien tipado.
+  "cl-cov-01": {
+    why: "Status define si la cobertura está vigente — input crítico para autorizaciones.",
+    suggestion: "`active` para vigente, `cancelled` para terminada.",
+    example: EX_COVERAGE,
+    docsUrl: DOCS("cl-cov-01"),
+  },
+  "cl-cov-02": {
+    why: "El asegurado es el paciente cubierto por el plan.",
+    suggestion: "`beneficiary: { reference: \"Patient/<id>\" }`.",
+    docsUrl: DOCS("cl-cov-02"),
+  },
+  "cl-cov-03": {
+    why: "El payor es FONASA, una Isapre, una mutual o seguro privado.",
+    suggestion: "`payor: [{ reference: \"Organization/<id>\" }]`.",
+    example: EX_COVERAGE,
+    docsUrl: DOCS("cl-cov-03"),
+  },
+
+  // ── Organization (CoreOrganizacionCl) ─────────────────────────────────────
+  "cl-org-01": {
+    why: "Una organización debe ser identificable — por código DEIS (establecimientos) o al menos un nombre legible.",
+    profileUrl: SD("CoreOrganizacionCl"),
+    suggestion: "Mejor: agrega `identifier` con el código DEIS del establecimiento (catálogo MINSAL). Mínimo: agrega `name`. CL Core 1.9.4 no incluye un CodeSystem dedicado al catálogo DEIS — usa `system` propio del establecimiento.",
+    example: EX_ORG,
+    docsUrl: DOCS("cl-org-01"),
+  },
+  "cl-org-02": {
+    why: "Si declaras un system de identificación de establecimiento pero no el código, el identifier no apunta a nada.",
+    suggestion: "Busca el código DEIS en el SIS-MINSAL. Si no lo conoces, llama `fhiron_search_terminology` con `system: \"deis\"`.",
+    docsUrl: DOCS("cl-org-02"),
+  },
+
+  // ── Immunization (ImmunizationCL) ─────────────────────────────────────
+  "cl-imm-01": {
+    why: "Status define si la dosis se administró, no se aplicó o quedó registrada con error.",
+    profileUrl: SD("ImmunizationCL"),
+    suggestion: "`completed` para vacunas administradas, `not-done` cuando se omitió.",
+    example: EX_IMM,
+    docsUrl: DOCS("cl-imm-01"),
+  },
+  "cl-imm-02": {
+    why: "vaccineCode identifica la vacuna — clave para reportería al RNI (Registro Nacional de Inmunizaciones).",
+    profileUrl: SD("ImmunizationCL"),
+    suggestion: "Usa el catálogo CVX (`http://hl7.org/fhir/sid/cvx`). El catálogo PNI chileno (`CSNombreCampana`) está pendiente de publicación oficial por MINSAL.",
+    example: EX_IMM,
+    docsUrl: DOCS("cl-imm-02"),
+  },
+  "cl-imm-03": {
+    why: "La vacuna se aplica a un paciente concreto.",
+    profileUrl: SD("ImmunizationCL"),
+    suggestion: "`patient: { reference: \"Patient/<id>\" }`.",
+    docsUrl: DOCS("cl-imm-03"),
+  },
+  "cl-imm-04": {
+    why: "Sin fecha no se puede calcular cobertura ni intervalo entre dosis.",
+    profileUrl: SD("ImmunizationCL"),
+    suggestion: "`occurrenceDateTime: \"YYYY-MM-DD\"` (o ISO 8601 con hora).",
+    docsUrl: DOCS("cl-imm-04"),
+  },
+
+  // ── DiagnosticReport ──────────────────────────────────────────────────────
+  "cl-dr-01": {
+    why: "Status diferencia un informe preliminar de uno final firmado por el patólogo/radiólogo.",
+    suggestion: "`final` para informes firmados, `preliminary` para borradores.",
+    example: EX_DR,
+    docsUrl: DOCS("cl-dr-01"),
+  },
+  "cl-dr-02": {
+    why: "El code define el tipo de informe (laboratorio, imagenología, anatomía patológica). LOINC es el estándar.",
+    suggestion: "Usa LOINC: `11502-2` informe de laboratorio, `18748-4` informe de imagenología.",
+    example: EX_DR,
+    docsUrl: DOCS("cl-dr-02"),
+  },
+  "cl-dr-03": {
+    why: "Todo informe es sobre un paciente.",
+    suggestion: "`subject: { reference: \"Patient/<id>\" }`.",
+    docsUrl: DOCS("cl-dr-03"),
+  },
+
+  // ── Bundle ────────────────────────────────────────────────────────────────
+  "cl-bundle-01": {
+    why: "El `type` define cómo HAPI procesa el Bundle: `transaction` ejecuta atómico, `document` valida como documento clínico, `collection` solo agrupa.",
+    suggestion: "`transaction` para enviar varios recursos atómicamente, `collection` para agrupar sin transaccionalidad, `document` para historia clínica electrónica.",
+    example: EX_BUNDLE,
+    docsUrl: DOCS("cl-bundle-01"),
+  },
+
+  // ── MINSAL EIS — terminología paralela a CL Core ──────────────────────────
+  "cl-eis-comuna-01": {
+    why: "Estás usando el CodeSystem oficial MINSAL de comunas. Es la lista de 347 comunas autorizada por DEIS — equivalente a la lista CL Core pero bajo el namespace minsal.cl.",
+    suggestion: "Tanto el system EIS (`https://interoperabilidad.minsal.cl/fhir/ig/eis/CodeSystem/CSComunas`) como el CL Core (`https://hl7chile.cl/fhir/ig/clcore/CodeSystem/CSCodComunasCL`) son válidos. Elige según con qué sistema te integras.",
+    docsUrl: DOCS("cl-eis-comuna-01"),
+  },
+  "cl-eis-prevision-01": {
+    why: "Estás usando el CodeSystem oficial MINSAL de previsión (Fonasa A/B/C/D, ISAPRE, PRAIS, Ley 21.418). No existe equivalente en CL Core — EIS es la única fuente oficial.",
+    suggestion: "Acepta el código y valida que `code` esté en la lista oficial (ej. `1` Fonasa A, `2` Fonasa B, `3` Fonasa C, `4` Fonasa D, `5` ISAPRE).",
+    docsUrl: DOCS("cl-eis-prevision-01"),
+  },
+  "cl-eis-system-01": {
+    why: "El system declarado parece de MINSAL EIS pero no aparece en el catálogo de los 49 CodeSystems oficiales del paquete `hl7.fhir.cl.minsal.eis@0.1.0`. Puede ser un typo o un namespace inventado.",
+    suggestion: "Verifica el system exacto. Los CodeSystems EIS publicados oficialmente listados en `/conceptos/cl-core#minsal-eis-terminología-paralela`.",
+    docsUrl: DOCS("cl-eis-system-01"),
+  },
+
+  // ── Reglas adicionales de calidad — recursos previamente parciales ───────
+  "cl-proc-04": {
+    why: "Procedure debe declarar cuándo ocurrió el procedimiento (`performedDateTime` o `performedPeriod`) para que sea analizable epidemiológicamente y trazable bajo Ley 21.719.",
+    suggestion: "`performedDateTime: \"2026-05-12T14:30:00-04:00\"` para procedimientos puntuales, `performedPeriod` para intervenciones extendidas.",
+    docsUrl: DOCS("cl-proc-04"),
+  },
+  "cl-allergy-04": {
+    why: "AllergyIntolerance sin `clinicalStatus` deja ambiguo si la alergia está activa, resuelta o inactiva. CL Core exige el binding required al ValueSet `allergyintolerance-clinical`.",
+    suggestion: "`clinicalStatus: { coding: [{ system: \"http://terminology.hl7.org/CodeSystem/allergyintolerance-clinical\", code: \"active\" }] }`.",
+    docsUrl: DOCS("cl-allergy-04"),
+  },
+  "cl-cov-04": {
+    why: "Coverage en Chile debe identificar al titular de la cobertura. Para Fonasa es el RUN del cotizante, para ISAPRE el número de contrato. Sin `subscriberId` el dispensador no puede liquidar.",
+    suggestion: "`subscriberId: \"15420097-3\"` (RUN del cotizante en Fonasa) o número de contrato ISAPRE.",
+    docsUrl: DOCS("cl-cov-04"),
+  },
+  "cl-imm-05": {
+    why: "Immunization en el PNI chileno requiere trazabilidad del lote de la vacuna para investigación epidemiológica ante eventos adversos. Sin `lotNumber` no es auditable.",
+    suggestion: "`lotNumber: \"AB1234\"` — el número impreso en el frasco/cápsula de la dosis aplicada.",
+    docsUrl: DOCS("cl-imm-05"),
+  },
+  "cl-dr-04": {
+    why: "DiagnosticReport sin fecha del informe deja ambiguo cuándo se generó. Para trazabilidad clínica conviene declarar `effectiveDateTime`.",
+    suggestion: "`effectiveDateTime: \"2026-05-12T09:00:00-04:00\"` — fecha/hora de toma de muestra o realización del estudio.",
+    docsUrl: DOCS("cl-dr-04"),
+  },
+
+  // ── Narrativa text.div ────────────────────────────────────────────────────
+  "cl-narrative-01": {
+    why: "FHIR R4 define solo cuatro valores válidos para `text.status`: `generated` (la narrativa se generó automáticamente del JSON), `extensions` (incluye texto de extensiones), `additional` (texto adicional aportado por el humano) y `empty` (no hay narrativa). Cualquier otro string rompe el binding.",
+    suggestion: "Usa `generated` por defecto cuando el div es derivado del recurso.",
+    docsUrl: DOCS("cl-narrative-01"),
+  },
+  "cl-narrative-02": {
+    why: "FHIR R4 dom-6 recomienda que cada DomainResource incluya `text.div` con narrativa HTML legible. No es obligatorio, pero ayuda a sistemas que no parsean el JSON estructurado y mejora la auditoría humana del recurso.",
+    suggestion: "Agrega `text: { status: 'generated', div: '<div xmlns=\"http://www.w3.org/1999/xhtml\">...</div>' }`. El quickFix inserta una narrativa mínima — reemplázala por una descripción humana real antes de producción.",
+    docsUrl: DOCS("cl-narrative-02"),
+  },
+
+  // ── HAPI fallback (categorías genéricas) ──────────────────────────────────
+  "hapi-error": {
+    why: "El validador HAPI detectó una violación al StructureDefinition del perfil — slicing, cardinalidad, binding terminológico o invariante FHIRPath. El detalle exacto está en `message`.",
+    suggestion: "Lee el `message` (en español): te indica el campo y la causa. Si menciona un código, búscalo en el ValueSet referido. Si menciona un perfil, revisa su definición canónica.",
+    docsUrl: DOCS("hapi-error"),
+  },
+  "hapi-warning": {
+    why: "HAPI emitió una advertencia — el recurso es válido pero hay una recomendación incumplida (best practice, narrative ausente, código deprecado).",
+    suggestion: "Las warnings no rompen el flujo pero degradan la calidad del dato. Atiéndelas antes de un release.",
+    docsUrl: DOCS("hapi-warning"),
+  },
+
+  // ── HAPI por categoría (route.ts categoriza el mensaje y emite estos códigos) ─
+  "hapi-error-cardinality": {
+    why: "Cada perfil CL Core declara un rango [min..max] obligatorio para cada campo. Un campo con cardinalidad [1..1] que falta o un [0..1] que aparece dos veces detiene la validación.",
+    suggestion: "Revisa el StructureDefinition del perfil para el campo afectado y ajusta la cantidad de ocurrencias enviadas.",
+    docsUrl: DOCS("hapi-error-cardinality"),
+  },
+  "hapi-error-terminology": {
+    why: "El binding del perfil exige que el campo use un código de un ValueSet específico (LOINC, SNOMED CT, TFC, CIE-10, CodeSystem chileno). El código enviado no pertenece al CodeSystem referenciado o el `system` está mal escrito.",
+    suggestion: "Verifica que `coding[].system` apunte al CodeSystem correcto y que `coding[].code` exista en él. Llama `fhiron_search_terminology` para buscar el código que necesitas.",
+    docsUrl: DOCS("hapi-error-terminology"),
+  },
+  "hapi-error-slicing": {
+    why: "El campo tiene múltiples variantes (slices) declaradas por el perfil. La instancia enviada no coincide con ninguna porque le falta una extensión, un `system` discriminador, o una combinación de campos esperada.",
+    suggestion: "Revisa el slicing del StructureDefinition. Cada slice define un discriminador (usualmente `system` + `code` o una extensión) que debe coincidir exactamente.",
+    docsUrl: DOCS("hapi-error-slicing"),
+  },
+  "hapi-error-run": {
+    why: "El RUN chileno debe seguir el formato 12345678-5: cuerpo numérico hasta 8 dígitos, guión, y dígito verificador (0-9 o K) calculado por módulo 11. CL Core lo valida en el slot identifier del perfil CorePacienteCl, con `type.coding[0].code = \"01\"` (CSTipoIdentificador).",
+    profileUrl: SD("CorePacienteCl"),
+    suggestion: "Si tienes puntos, usa el quickFix de `cl-run-01` para quitarlos. Verifica el DV con `fhiron_fhir_lint_run` antes de enviar al servidor.",
+    example: { identifier: [{ system: CS("CSTipoIdentificador"), value: "12345678-5" }] },
+    docsUrl: DOCS("hapi-error-run"),
+  },
+  "hapi-error-profile": {
+    why: "El recurso no satisface el StructureDefinition completo del perfil declarado en `meta.profile` o detectado automáticamente por HAPI. Pueden ser múltiples violaciones acumuladas (cardinalidad + terminología + slicing).",
+    suggestion: "Revisa los issues anteriores en este mismo OperationOutcome — usualmente el error de perfil es la suma de los issues más específicos.",
+    docsUrl: DOCS("hapi-error-profile"),
+  },
+  "hapi-error-reference": {
+    why: "Una referencia (`Patient/123`, `Practitioner/X`, etc.) no se pudo resolver — el recurso target no existe en el Bundle, no se proporcionó como contained, ni la URL absoluta es accesible.",
+    suggestion: "Para Bundles transactionales, asegúrate de que el recurso referenciado esté en otra entry del mismo Bundle. Para servidores con recursos pre-cargados, verifica que la referencia apunte al ID correcto.",
+    docsUrl: DOCS("hapi-error-reference"),
+  },
+  "hapi-error-format": {
+    why: "El validador detectó un valor que no calza con el tipo de dato esperado por el perfil — un string donde se esperaba un número, una fecha mal formada, un MIME type incorrecto, o un valor que no cumple el regex declarado.",
+    suggestion: "Revisa el tipo declarado en el StructureDefinition para el campo y ajusta el formato del valor enviado.",
+    docsUrl: DOCS("hapi-error-format"),
+  },
+  "hapi-warning-best-practice": {
+    why: "Recomendación opcional del IG: el recurso es técnicamente válido pero le falta algo que mejora la interoperabilidad (narrativa text.div, performer en Observation, identifier business, etc.).",
+    suggestion: "No bloquea el envío. Atiende estas warnings antes de producción para mejorar la calidad del dato compartido.",
+    docsUrl: DOCS("hapi-warning-best-practice"),
+  },
+
+  // ── MCP infraestructura ───────────────────────────────────────────────────
+  "mcp-auth-01": {
+    why: "El conector necesita una API key para llamar al validador HAPI remoto. Sin ella solo puede correr reglas locales.",
+    suggestion: "Pasa `--key TU_API_KEY` al invocar el MCP, o define la variable de entorno FHIRON_API_KEY. Obtén una gratis en https://fhiron.cl/registro.",
+    docsUrl: DOCS("mcp-auth-01"),
+  },
+  "mcp-auth-02": {
+    why: "La API key existe pero el servidor la rechazó (401/403). Pudo haber sido revocada, rotada o nunca existió.",
+    suggestion: "Verifica el valor en https://fhiron.cl/dashboard/connect-ai. Si la rotaste, actualiza tu config MCP.",
+    docsUrl: DOCS("mcp-auth-02"),
+  },
+  "mcp-quota-01": {
+    why: "Se agotó la cuota mensual de validaciones del plan actual. Las reglas locales (cl-*) siguen funcionando offline.",
+    suggestion: "Mejora el plan en https://fhiron.cl/precios o espera al primer día del próximo mes. Las tools `fhiron_fhir_lint_local` y `fhiron_fhir_lint_run` son gratis.",
+    docsUrl: DOCS("mcp-quota-01"),
+  },
+  "mcp-net-01": {
+    why: "No se pudo establecer conexión con Fhiron Bridge — red caída, firewall, DNS o el servicio está reiniciando.",
+    suggestion: "Revisa tu conexión, el firewall corporativo y el estado del servicio en https://status.fhiron.cl.",
+    docsUrl: DOCS("mcp-net-01"),
+  },
+  "mcp-server-01": {
+    why: "El servidor respondió 500 — bug en Fhiron Bridge, no en tu recurso.",
+    suggestion: "Reintenta en unos segundos. Si persiste, reporta el caso en https://github.com/Fhironstack/skills/issues incluyendo el recurso (sin datos sensibles).",
+    docsUrl: DOCS("mcp-server-01"),
+  },
+  "mcp-server-02": {
+    why: "El servidor respondió 502/503/504 — gateway o servicio temporalmente no disponible (deploy, restart, rolling update).",
+    suggestion: "Reintenta en 1–2 minutos. Si persiste, revisa https://status.fhiron.cl.",
+    docsUrl: DOCS("mcp-server-02"),
+  },
+  "mcp-server-03": {
+    why: "Respuesta HTTP inesperada del servidor (no 200, 401, 403, 422, 429, 500, 502-504). Probablemente un error de proxy intermedio.",
+    suggestion: "Reintenta. Si persiste, captura el `message` y reporta el caso.",
+    docsUrl: DOCS("mcp-server-03"),
+  },
+};
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+/**
+ * Devuelve la entrada del catálogo para un código, o null si no existe.
+ * @param {string} code
+ * @returns {{ why?:string, profileUrl?:string, docsUrl?:string, suggestion?:string, example?:any }|null}
+ */
+function lookupCode(code) {
+  if (!code) return null;
+  return CATALOG[code] || null;
+}
+
+/**
+ * Lista todos los códigos del catálogo (útil para fhiron_explain_code y tests).
+ * @returns {string[]}
+ */
+function listCodes() {
+  return Object.keys(CATALOG);
+}
+
+module.exports = {
+  CATALOG,
+  lookupCode,
+  listCodes,
+  IG_BASE,
+  SD,
+  CS,
+  VS,
+  DOCS,
+};