feat: clinical fidelity hardening — population roles, real exclusions, value-set safety flags

.env.example

@@ -68,3 +68,6 @@ NGINX_PORT=3081
 # Solr and Redis ports exposed to host (for debugging/admin)
 SOLR_PORT=8984
 REDIS_PORT=6379
+
+# Measure evaluation engine: sql (star-schema aggregation) | cql (future cqf-ruler bridge)
+MEASURE_EVALUATOR=sql

.gitignore

@@ -16,6 +16,9 @@ coverage/
 /backend/public/build
 /backend/storage/*.key
 
+# TypeScript incremental build state — never commit; causes tsc to skip emission on fresh checkouts
+*.tsbuildinfo
+
 # Turbo
 .turbo
 

apps/api/.eslintrc.json

@@ -0,0 +1,21 @@
+{
+  "root": true,
+  "parser": "@typescript-eslint/parser",
+  "parserOptions": {
+    "ecmaVersion": 2022,
+    "sourceType": "module"
+  },
+  "plugins": ["@typescript-eslint"],
+  "extends": [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/recommended"
+  ],
+  "env": {
+    "node": true,
+    "es2022": true
+  },
+  "rules": {
+    "@typescript-eslint/no-explicit-any": "warn",
+    "@typescript-eslint/no-unused-vars": ["warn", { "argsIgnorePattern": "^_" }]
+  }
+}

apps/api/package.json

@@ -43,6 +43,9 @@
     "@types/node": "^22.10.1",
     "@types/supertest": "^6.0.2",
     "@types/ws": "^8.18.1",
+    "@typescript-eslint/eslint-plugin": "^8.0.0",
+    "@typescript-eslint/parser": "^8.0.0",
+    "eslint": "^8.57.0",
     "supertest": "^7.0.0",
     "tsx": "^4.19.2",
     "typescript": "^5.7.2",

apps/api/src/routes/admin/index.ts

@@ -16,7 +16,7 @@ import {
   generateDeidentifiedCohort,
 } from '../../services/omopExport.js';
 import { sql } from '@medgnosis/db';
-import { refreshMeasureResults } from '../../services/measureCalculatorV2.js';
+import { getMeasureEvaluator } from '../../services/measureEvaluator.js';
 import { getSolrClient, isSolrAvailable } from '../../plugins/solr.js';
 import { config } from '../../config.js';
 
@@ -380,7 +380,7 @@ export default async function adminRoutes(app: FastifyInstance) {
 
     // Also refresh measure results after mat views
     try {
-      await refreshMeasureResults();
+      await getMeasureEvaluator().refresh();
       results.push({ view: 'fact_measure_result', status: 'ok' });
     } catch (err) {
       results.push({ view: 'fact_measure_result', status: 'error', error: String(err) });
@@ -396,7 +396,7 @@ export default async function adminRoutes(app: FastifyInstance) {
 
   app.post('/refresh-measures', async (req, reply) => {
     try {
-      const result = await refreshMeasureResults();
+      const result = await getMeasureEvaluator().refresh();
 
       await sql`
         INSERT INTO public.audit_log (user_id, action, resource_type, details)

apps/api/src/routes/index.ts

@@ -20,6 +20,7 @@ import clinicalNoteRoutes from './clinical-notes/index.js';
 import orderRoutes from './orders/index.js';
 import cdsHooksRoutes from './cds-hooks/index.js';
 import rulesRoutes from './rules/index.js';
+import valueSetRoutes from './value-sets/index.js';
 import problemListRoutes from './problem-list/index.js';
 import populationFinderRoutes from './population-finder/index.js';
 import closeTheLoopRoutes from './close-the-loop/index.js';
@@ -58,6 +59,7 @@ export async function registerRoutes(fastify: FastifyInstance): Promise<void> {
       await api.register(clinicalNoteRoutes, { prefix: '/clinical-notes' });
       await api.register(orderRoutes, { prefix: '/orders' });
       await api.register(rulesRoutes, { prefix: '/rules' });
+      await api.register(valueSetRoutes, { prefix: '/value-sets' });
       await api.register(problemListRoutes, { prefix: '/problem-list' });
       await api.register(populationFinderRoutes, { prefix: '/population-finder' });
       await api.register(closeTheLoopRoutes, { prefix: '/close-the-loop' });

apps/api/src/routes/measures/index.ts

@@ -5,6 +5,7 @@
 import type { FastifyInstance } from 'fastify';
 import { sql } from '@medgnosis/db';
 import { measureFilterSchema } from '@medgnosis/shared';
+import { wilsonCI } from '../../services/wilsonCI.js';
 
 export default async function measureRoutes(fastify: FastifyInstance): Promise<void> {
   fastify.addHook('preHandler', fastify.authenticate);
@@ -77,4 +78,48 @@ export default async function measureRoutes(fastify: FastifyInstance): Promise<v
       },
     });
   });
+
+  // GET /measures/:id/strata — age/sex strata with Wilson 95% CIs.
+  // measure_id != measure_key: resolve through dim_measure (see GET /:id).
+  fastify.get<{ Params: { id: string } }>('/:id/strata', async (request, reply) => {
+    const { id } = request.params;
+
+    const rows = await sql<
+      { dimension: string; stratum: string; denominator: number; numerator: number; excluded: number }[]
+    >`
+      SELECT fms.dimension, fms.stratum,
+             fms.denominator::int, fms.numerator::int, fms.excluded::int
+      FROM phm_star.fact_measure_strata fms
+      JOIN phm_star.dim_measure dm ON dm.measure_key = fms.measure_key
+      WHERE dm.measure_id = ${id}::int
+      ORDER BY fms.dimension, fms.stratum
+    `;
+
+    if (rows.length === 0) {
+      return reply.status(404).send({
+        success: false,
+        error: { code: 'NOT_FOUND', message: 'No strata for this measure (run a measure refresh first)' },
+      });
+    }
+
+    const data = rows.map((row) => {
+      // small_cell: display guidance for wide-CI / small-n strata (denominator
+      // 1–10). NOT suppression — this is an internal clinical tool; raw n stays
+      // visible. Consumers may render a warning indicator alongside the rate.
+      const small_cell = row.denominator > 0 && row.denominator < 11;
+      if (row.denominator <= 0) {
+        return { ...row, rate: null, ci_lower: null, ci_upper: null, small_cell };
+      }
+      const ci = wilsonCI(row.numerator, row.denominator);
+      return {
+        ...row,
+        rate: Math.round((row.numerator / row.denominator) * 1000) / 10,
+        ci_lower: Math.round(ci.lower * 1000) / 10,
+        ci_upper: Math.round(ci.upper * 1000) / 10,
+        small_cell,
+      };
+    });
+
+    return reply.send({ success: true, data });
+  });
 }

apps/api/src/routes/value-sets/index.ts

@@ -0,0 +1,67 @@
+// =============================================================================
+// Medgnosis API — VSAC value set transparency routes
+// Show the authoritative CMS code lists behind any measure. Read-only.
+// =============================================================================
+
+import type { FastifyInstance } from 'fastify';
+import {
+  listValueSets,
+  getValueSetCodes,
+  getMeasureValueSets,
+  getMeasureBridgeStatus,
+} from '../../services/vsacService.js';
+
+export default async function valueSetRoutes(fastify: FastifyInstance): Promise<void> {
+  fastify.addHook('preHandler', fastify.authenticate);
+
+  // GET /value-sets?search= — catalog with code counts
+  fastify.get<{ Querystring: { search?: string } }>('/', async (request, reply) => {
+    const valueSets = await listValueSets(request.query.search);
+    return reply.send({ success: true, data: valueSets });
+  });
+
+  // GET /value-sets/measure/:measureCode — value sets bridged to a measure
+  // (registered before /:oid so "measure" is not swallowed as an OID)
+  // Response includes bridge status (version_drift, unclassified_count, role
+  // distribution) alongside the value set list. 404 when the measure has no
+  // bridge rows (status === null).
+  fastify.get<{ Params: { measureCode: string } }>(
+    '/measure/:measureCode',
+    async (request, reply) => {
+      const [status, value_sets] = await Promise.all([
+        getMeasureBridgeStatus(request.params.measureCode),
+        getMeasureValueSets(request.params.measureCode),
+      ]);
+      if (status === null) {
+        return reply.status(404).send({
+          success: false,
+          error: {
+            code: 'NOT_FOUND',
+            message: `No value sets bridged to measure ${request.params.measureCode}`,
+          },
+        });
+      }
+      return reply.send({ success: true, data: { status, value_sets } });
+    },
+  );
+
+  // GET /value-sets/:oid/codes?code_system= — the flattened expansion
+  fastify.get<{
+    Params: { oid: string };
+    Querystring: { code_system?: string };
+  }>('/:oid/codes', async (request, reply) => {
+    const codes = await getValueSetCodes(request.params.oid, request.query.code_system);
+    if (codes.length === 0) {
+      return reply.status(404).send({
+        success: false,
+        error: {
+          code: 'NOT_FOUND',
+          message: `No codes for value set ${request.params.oid}${
+            request.query.code_system ? ` in ${request.query.code_system}` : ''
+          }`,
+        },
+      });
+    }
+    return reply.send({ success: true, data: codes });
+  });
+}

apps/api/src/services/__tests__/cohortFlags.test.ts

@@ -2,7 +2,7 @@
 // Unit tests — Cohort high-risk flags + cohort matching (pure)
 // =============================================================================
 
-import { describe, it, expect, vi } from 'vitest';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
 
 const { mockSql } = vi.hoisted(() => {
   const fn = vi.fn();
@@ -13,7 +13,7 @@ vi.mock('@medgnosis/db', () => ({
   sql: Object.assign(mockSql, { unsafe: vi.fn(), json: (v: unknown) => v }),
 }));
 
-import { flagHyperkalemia, flagGfrLow, flagNewAceArbNoBmp, matchesCohort } from '../cohortFlags.js';
+import { flagHyperkalemia, flagGfrLow, flagNewAceArbNoBmp, matchesCohort, runCohortFlags } from '../cohortFlags.js';
 
 describe('flagHyperkalemia', () => {
   it('flags K >= 5.5', () => {
@@ -54,3 +54,67 @@ describe('matchesCohort', () => {
     expect(matchesCohort({ conditions: ['N18.4'], flags: [] }, { conditions: ['N18.4'] })).toBe(true);
   });
 });
+
+describe('runCohortFlags (VSAC-driven ACE/ARB)', () => {
+  const ACE_OID = '2.16.840.1.113883.3.526.2.39';
+  const SUPPRESS_OID_1 = '2.16.840.1.113883.3.526.2.1256';
+  const SUPPRESS_OID_2 = '2.16.840.1.113883.3.526.2.1257';
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockSql.mockResolvedValue([]);
+  });
+
+  it('throws when ACEARB_RXNORM_VALUE_SET_OID rule row is missing', async () => {
+    // acearbOid lookup returns empty → no rule row → must throw
+    mockSql.mockResolvedValueOnce([]);
+    await expect(runCohortFlags()).rejects.toThrow('ACEARB_RXNORM_VALUE_SET_OID missing');
+  });
+
+  it('queries the cohort with the OID from clinical_rule and returns flag counts', async () => {
+    // Call[0]: acearbOid lookup
+    mockSql.mockResolvedValueOnce([{ value_text: ACE_OID }]);
+    // Call[1]: suppressOids lookup (two suppress sets)
+    mockSql.mockResolvedValueOnce([{ value_text: SUPPRESS_OID_1 }, { value_text: SUPPRESS_OID_2 }]);
+    // Call[2]: suppress fragment sql`` interpolation (always fires — empty or populated)
+    // Call[3]: cohort query — one patient on ACE/ARB, no recent BMP
+    mockSql.mockResolvedValueOnce([]); // fragment
+    mockSql.mockResolvedValueOnce([
+      { patient_id: 1, latest_k: null, latest_gfr: null, on_acearb: true, has_recent_bmp: false },
+    ]);
+    // remaining setFlag calls → default []
+    mockSql.mockResolvedValue([]);
+
+    const result = await runCohortFlags();
+    expect(result.cohort).toBe(1);
+    expect(result.byFlag['NEW_ACEARB_NO_BMP']).toBe(1);
+    expect(result.byFlag['HYPERKALEMIA']).toBe(0);
+    expect(result.byFlag['GFR_LOW']).toBe(0);
+    // Verify acearbOid reached the cohort query (call[3], values start at slice(1))
+    const cohortCallValues = (mockSql.mock.calls[3] ?? []).slice(1) as unknown[];
+    expect(cohortCallValues).toContain(ACE_OID);
+  });
+
+  it('passes suppress OIDs to the suppression fragment when present', async () => {
+    mockSql.mockResolvedValueOnce([{ value_text: ACE_OID }]);
+    mockSql.mockResolvedValueOnce([{ value_text: SUPPRESS_OID_1 }]);
+    mockSql.mockResolvedValue([]);
+
+    await runCohortFlags();
+    // Call[2] is the suppress fragment; its values include the suppress array
+    const fragmentValues = (mockSql.mock.calls[2] ?? []).slice(1) as unknown[];
+    expect(fragmentValues).toContainEqual([SUPPRESS_OID_1]);
+  });
+
+  it('still runs when suppress OID list is empty (no allergy/intolerance rules)', async () => {
+    mockSql.mockResolvedValueOnce([{ value_text: ACE_OID }]);
+    mockSql.mockResolvedValueOnce([]); // empty suppress list
+    mockSql.mockResolvedValue([]);
+
+    // Must not throw — empty suppress list = no suppression fragment, no error
+    await expect(runCohortFlags()).resolves.toMatchObject({ cohort: 0 });
+    // Verify acearbOid still reached call[3]
+    const cohortCallValues = (mockSql.mock.calls[3] ?? []).slice(1) as unknown[];
+    expect(cohortCallValues).toContain(ACE_OID);
+  });
+});