fhirsmith 0.18.2 → 1.0.0

package/ips/ips.js

@@ -39,7 +39,6 @@
  * @module ips/ips
  */
 
-const http = require('http');
 const express = require('express');
 const path = require('path');
 const fs = require('fs');
@@ -62,6 +61,9 @@ const { parseSearch, listQueryToSearch, capabilitySearchParams, compositionOf, p
 const render = require('./render');
 const { TxClient } = require('./tx-client');
 const { STEPS, stripChecks } = require('./pipeline');
+
+// the extension definitions remembered from the validator (the analysis step)
+const MAX_CACHED_EXTENSIONS = 5000;
 const { IpsValueSets } = require('./ips-valuesets');
 const aiClient = require('./ai-client');
 const { ShlClient } = require('./share');
@@ -82,54 +84,17 @@ const FHIR_JSON = 'application/fhir+json; charset=utf-8';
 const CODE_RE = /^[a-z0-9][a-z0-9-]{1,31}$/;
 // paths at the root that can't be project codes
 const { jurisdiction: jurisdictionOf } = require('./jurisdictions');
-const LOAD_IG_TIMEOUT_MS = 300000;
+const { SNOMED_LINKABLE_EDITIONS } = require('../tx/sct/editions');
 const RESERVED = new Set(['login', 'logout', 'admin', 'metadata', 'openapi', 'static', 'assets', 'lookup', 'national-profiles']);
 
-/**
- * Ask the validator service to load a package (id#version) - POST /loadIG with {"ig": ...} as
- * the validator's LoadIGHTTPHandler takes it. fhir-validator-wrapper's own loadIG() (to 1.6.0
- * at least) sends the package id and version as query parameters with no body, which the
- * service refuses ("Error parsing JSON source: ... Eof at Line 1"), so it is only used for a
- * validator with no address of its own (as the tests' are).
- * @returns {Promise<Object>} the OperationOutcome the service answers with
- */
-function loadIG(validator, packageId, version) {
-  if (!validator.baseUrl) {
-    return validator.loadIG(packageId, version);
-  }
-  const body = JSON.stringify({ ig: `${packageId}#${version}` });
-  const url = new URL(`${validator.baseUrl}/loadIG`);
-  return new Promise((resolve, reject) => {
-    const req = http.request({
-      hostname: url.hostname, port: url.port, path: url.pathname, method: 'POST',
-      headers: { 'Content-Type': 'application/json', 'Accept': 'application/fhir+json', 'Content-Length': Buffer.byteLength(body) }
-    }, (res) => {
-      const chunks = [];
-      res.on('data', (c) => chunks.push(c));
-      res.on('end', () => {
-        const text = Buffer.concat(chunks).toString('utf8');
-        try {
-          resolve(JSON.parse(text));
-        } catch (e) {
-          reject(new Error(`The validator answered HTTP ${res.statusCode} with a response that is not JSON (${text.length} bytes)`));
-        }
-      });
-      res.on('error', reject);
-    });
-    req.on('error', reject);
-    // loading a package can mean downloading it, and its dependencies
-    req.setTimeout(LOAD_IG_TIMEOUT_MS, () => req.destroy(new Error('The validator took too long to load the package')));
-    req.end(body);
-  });
-}
-
 /**
  * What's wrong with a national profile's details, or null: a jurisdiction (a country's ISO 3166
  * two-letter code, or a region's UN M49 three-digit code - see jurisdictions.js), a FHIR package id (lower case, at
- * least two parts separated by dots), a version (as package versions are written), and the
- * canonical URL (http or https) of the IG's profile on Bundle.
+ * least two parts separated by dots), a version (as package versions are written), the
+ * canonical URL (http or https) of the IG's profile on Bundle, and - optionally - the SNOMED CT
+ * edition the IG takes for granted, by its module id (one of SNOMED_LINKABLE_EDITIONS).
  */
-function nationalProfileProblem(jurisdiction, packageId, version, url) {
+function nationalProfileProblem(jurisdiction, packageId, version, url, snomedEdition) {
   if (!jurisdictionOf(jurisdiction)) {
     return 'The jurisdiction must be a country, by its ISO 3166 two-letter code (e.g. AU), or a region, by its UN M49 three-digit code (e.g. 150 for Europe)';
   }
@@ -142,6 +107,9 @@ function nationalProfileProblem(jurisdiction, packageId, version, url) {
   if (url.length > 1024 || !/^https?:\/\/[^\s/?#]+(?:[/?#]\S*)?$/.test(url)) {
     return 'The profile must be the canonical URL (http or https) of the IG\'s profile on Bundle';
   }
+  if (snomedEdition && !SNOMED_LINKABLE_EDITIONS.has(snomedEdition)) {
+    return 'The SNOMED CT edition must be one of the editions offered (or none)';
+  }
   return null;
 }
 
@@ -687,11 +655,18 @@ class IpsModule {
       txLog: cfg.txLog || folders.filePath('logs', 'ips-validator-tx.log'),
       port: cfg.port || 8082,
       igs: Array.isArray(cfg.packages) ? cfg.packages : ['hl7.fhir.uv.ips#1.1.0'],
-      timeout: cfg.timeout || 120000
+      timeout: cfg.timeout || 120000,
+      // lookupExtension(): an extension the validator doesn't have is looked for the way the
+      // validator does while validating - the package that defines it is found from the url,
+      // downloaded and loaded (validator 7.0.5 and later; fhir-validator-wrapper 1.7.0 and later)
+      autoLoadPackages: cfg.autoLoadPackages !== false
     };
     this.log.info(`IPS module: starting the FHIR validator${localJar ? ` (${localJar})` : ''} on port ${settings.port} (tx ${settings.txServer}; ${settings.igs.join(', ')})`);
     this.validatorStarting = this.validator.start(settings).then(() => {
       this.log.info('IPS module: the FHIR validator is running');
+      // documents wait for this too, so the analysis step - which looks up extensions before
+      // the national step would load the packages - finds what the national IGs define
+      return this.loadNationalPackages();
     }).catch(e => {
       this.log.error('IPS module: the FHIR validator failed to start: ' + e.message);
       this.validatorError = e.message;
@@ -700,6 +675,33 @@ class IpsModule {
     });
   }
 
+  /**
+   * Load every national profile's package into the validator (as the national step would), so
+   * that what they define is there from the start. A package that won't load is logged (and
+   * remembered) by loadNationalPackage(), and doesn't stop the others.
+   * @returns {Promise<void>}
+   */
+  async loadNationalPackages() {
+    if (!this.validator || !this.store) {
+      return;
+    }
+    const list = this.store.nationalProfiles();
+    if (list.length === 0) {
+      return;
+    }
+    const started = Date.now();
+    this.log.info(`IPS module: loading the packages of ${list.length} national profiles into the validator`);
+    // one at a time: the validator loads one package per request anyway
+    for (const np of list) {
+      try {
+        await this.loadNationalPackage(np.packageId, np.version);
+      } catch (e) {
+        // already logged
+      }
+    }
+    this.log.info(`IPS module: national profile packages loaded in ${Math.round((Date.now() - started) / 1000)}s`);
+  }
+
   /**
    * Load a national profile's package into the validator - once: a package that loaded, or
    * failed to (with why), is remembered until the national profiles are changed, so each
@@ -711,13 +713,15 @@ class IpsModule {
     const key = `${packageId}#${version}`;
     let p = this.nationalPackages.get(key);
     if (!p) {
-      p = loadIG(this.validator, packageId, version).then(outcome => {
+      p = this.validator.loadIG(packageId, version).then(outcome => {
         const bad = (Array.isArray(outcome?.issue) ? outcome.issue : []).filter(i => i && (i.severity === 'error' || i.severity === 'fatal'));
         if (bad.length > 0 || outcome?.resourceType !== 'OperationOutcome') {
           const why = bad.map(i => i.details?.text || i.diagnostics || i.code).filter(Boolean).join('; ') || 'the validator did not return an OperationOutcome';
           throw new Error(`The validator could not load ${key}: ${why}`);
         }
         this.log.info(`IPS module: national profile package ${key} loaded into the validator`);
+        // the validator knows more now: extensions it couldn't find before may be there
+        this.forgetMissingExtensions();
       });
       p.catch(e => this.log.warn(`IPS module: ${e.message}`));
       this.nationalPackages.set(key, p);
@@ -757,6 +761,58 @@ class IpsModule {
     return null;
   }
 
+  /**
+   * Forget the extensions the validator couldn't find: it has loaded a package since, and may
+   * know them now. The ones it found are kept.
+   */
+  forgetMissingExtensions() {
+    if (this.extensionCache) {
+      for (const [url, answer] of this.extensionCache) {
+        if (answer === null) {
+          this.extensionCache.delete(url);
+        }
+      }
+    }
+  }
+
+  /**
+   * The definition of an extension, for the analysis step: {url, title, name, description},
+   * or null when it can't be found. It is asked of the validator (the wrapper's
+   * lookupCanonical(), the service's /canonical, which looks in the validator's context - and,
+   * with modules.ips.validator.autoLoadPackages (on by default), finds and loads the package that
+   * defines one it doesn't have).
+   * Answers are remembered (a bounded cache); a validator that isn't there, or that fails, or
+   * that predates /canonical, isn't an answer, and is asked again next time.
+   * @param {string} url
+   * @returns {Promise<Object|null>}
+   */
+  async lookupExtension(url) {
+    const v = this.validator;
+    if (!v || typeof v.lookupCanonical !== 'function' || typeof v.isRunning !== 'function' || !v.isRunning()) {
+      return null;
+    }
+    const cache = this.extensionCache || (this.extensionCache = new Map());
+    if (cache.has(url)) {
+      return cache.get(url);
+    }
+    let answer = null;
+    try {
+      const r = await v.lookupCanonical(url);
+      if (r) {
+        const str = (x) => (typeof x === 'string' ? x : '');
+        answer = { url: str(r.url), title: str(r.title), name: str(r.name), description: str(r.description).substring(0, 1000) };
+      }
+    } catch (e) {
+      this.log.warn(`IPS module: looking up extension ${url} failed: ${e.message}`);
+      return null;
+    }
+    if (cache.size >= MAX_CACHED_EXTENSIONS) {
+      cache.delete(cache.keys().next().value);
+    }
+    cache.set(url, answer);
+    return answer;
+  }
+
   /**
    * Whether the pipeline can run now: not while the validator is still starting, nor -
    * for a while after start-up - while a terminology server on this server isn't there
@@ -932,20 +988,29 @@ class IpsModule {
   }
 
   /**
-   * The paragraph for the server's daily report: pages served, documents
-   * received in the period, and how many are stored.
+   * The paragraph for the server's daily report: pages served (and how many were about documents - a
+   * document's page, in any of its views), new documents and how many are stored, and the
+   * processing pipeline - how many times it was started, and how many of those didn't finish
+   * (it failed, or the server stopped while it ran).
    */
   dailyReport({since, now}) {
     const {plural} = require('../library/daily-report');
+    const was = (n) => n === 1 ? 'was' : 'were';
     const sentences = [];
     if (this.stats) {
       const counts = this.stats.countsSince(since, now);
-      sentences.push(`${plural(counts.total, 'page')} ${counts.total === 1 ? 'was' : 'were'} served.`);
+      const docs = counts.operations.read || 0;
+      sentences.push(`${plural(counts.total, 'page')} ${was(counts.total)} served${counts.total ? `, ${docs} of them about documents` : ''}.`);
     }
     if (this.store) {
       const received = this.store.countReceived(since, now);
       const stored = this.store.count();
-      sentences.push(`${plural(received, 'IPS document')} ${received === 1 ? 'was' : 'were'} received; ${plural(stored, 'document')} ${stored === 1 ? 'is' : 'are'} stored.`);
+      sentences.push(`${plural(received, 'new document')} ${was(received)} received; ${plural(stored, 'document')} ${stored === 1 ? 'is' : 'are'} stored.`);
+      const runs = this.store.countRuns(since, now);
+      const unfinished = runs.failed + runs.interrupted;
+      const why = [runs.failed ? `${runs.failed} failed` : '', runs.interrupted ? `${runs.interrupted} interrupted by a shutdown` : ''].filter(Boolean).join(', ');
+      sentences.push(`The processing pipeline was started ${plural(runs.started, 'time')}; ${unfinished} didn't finish${why ? ` (${why})` : ''}` +
+        `${runs.running ? `, and ${runs.running} ${runs.running === 1 ? 'is' : 'are'} still running` : ''}.`);
     } else {
       sentences.push('The document store is not open.');
     }
@@ -1405,12 +1470,13 @@ class IpsModule {
     const list = this.store.nationalProfiles();
     res.status(status);
     if (!wantsHtml(req) && !message) {
-      return res.json(list.map(np => ({ jurisdiction: np.jurisdiction, packageId: np.packageId, version: np.version, url: np.url })));
+      return res.json(list.map(np => ({ jurisdiction: np.jurisdiction, packageId: np.packageId, version: np.version, url: np.url,
+        ...(np.snomedEdition ? { snomedEdition: np.snomedEdition } : {}) })));
     }
     this.sendHtml(res, 'National Profiles', render.renderNationalProfiles(list, this.ctx(req, res), message), Date.now(), req);
   }
 
-  /** Add (id null) or change a national profile, from the form: packageId, version, url. */
+  /** Add (id null) or change a national profile, from the form: jurisdiction, packageId, version, url, snomedEdition (optional). */
   saveNationalProfile(req, res, id) {
     const field = (name) => (typeof req.body[name] === 'string' ? req.body[name].trim() : '');
     const packageId = field('packageId');
@@ -1418,7 +1484,9 @@ class IpsModule {
     const url = field('url');
     // a country code is upper case; a region's is digits
     const jurisdiction = field('jurisdiction').toUpperCase();
-    const problem = nationalProfileProblem(jurisdiction, packageId, version, url);
+    // the edition's module id; empty for none
+    const snomedEdition = field('snomedEdition') || null;
+    const problem = nationalProfileProblem(jurisdiction, packageId, version, url, snomedEdition);
     if (problem) {
       return this.sendNationalProfiles(req, res, problem, 400);
     }
@@ -1427,20 +1495,24 @@ class IpsModule {
       if (existing) {
         return this.sendNationalProfiles(req, res, `There is already a national profile for ${packageId}#${version}`, 409);
       }
-      this.store.createNationalProfile(packageId, version, url, jurisdiction);
-      this.log.info(`IPS module: national profile ${packageId}#${version} (${jurisdiction}) added (${url})`);
+      this.store.createNationalProfile(packageId, version, url, jurisdiction, snomedEdition);
+      this.log.info(`IPS module: national profile ${packageId}#${version} (${jurisdiction}${snomedEdition ? `, SNOMED CT ${snomedEdition}` : ''}) added (${url})`);
     } else {
       const n = /^\d{1,15}$/.test(id) ? parseInt(id, 10) : -1;
       if (existing && existing.id !== n) {
         return this.sendNationalProfiles(req, res, `There is already a national profile for ${packageId}#${version}`, 409);
       }
-      if (!this.store.updateNationalProfile(n, packageId, version, url, jurisdiction)) {
+      if (!this.store.updateNationalProfile(n, packageId, version, url, jurisdiction, snomedEdition)) {
         return this.sendNationalProfiles(req, res, 'That national profile no longer exists', 404);
       }
-      this.log.info(`IPS module: national profile ${packageId}#${version} (${jurisdiction}) saved (${url})`);
+      this.log.info(`IPS module: national profile ${packageId}#${version} (${jurisdiction}${snomedEdition ? `, SNOMED CT ${snomedEdition}` : ''}) saved (${url})`);
     }
-    // a package that failed to load is tried again
+    // a package that failed to load is tried again; the packages are loaded now (in the
+    // background), so the analysis step finds what they define
     this.nationalPackages = new Map();
+    if (this.validator && this.validator.isRunning()) {
+      this.loadNationalPackages().catch(e => this.log.warn(`IPS module: loading the national profile packages failed: ${e.message}`));
+    }
     res.redirect(req.baseUrl + '/national-profiles');
   }
 
@@ -1812,7 +1884,7 @@ class IpsModule {
       if (!row) {
         return htmlServer.sendErrorResponse(res, TEMPLATE, new Error(`No document with id '${req.params.id}'`), 404);
       }
-      const view = render.VIEWS.some(([v]) => v === req.query.view) ? req.query.view : render.VIEWS[0][0];
+      const { view, narrative } = render.viewOf(req.query);
       row.results = {};
       for (const step of this.steps) {
         row.results[step.name] = this.store.readResult(row.id, step.name);
@@ -1822,7 +1894,8 @@ class IpsModule {
         steps: this.steps.map(st => st.name),
         level: typeof req.query.level === 'string' ? req.query.level : undefined,
         np: typeof req.query.np === 'string' ? req.query.np : undefined,
-        problemsOnly: req.query.problems === '1'
+        problemsOnly: req.query.problems === '1',
+        narrative
       };
       return this.sendHtml(res, `${req.project.name}: Document ${row.id}`, render.renderDocument(req.project, row, view, ctx), start, req);
     }

package/ips/nationality.js

@@ -0,0 +1,120 @@
+//
+// Copyright 2026, Health Intersections Pty Ltd (http://www.healthintersections.com.au)
+//
+// Licensed under BSD-3: https://opensource.org/license/bsd-3-clause
+//
+
+/**
+ * The nationality step - the first processing step: which nation an IPS document is from,
+ * as far as the document itself says. Few national IGs give a way to tell, so this is a
+ * short list of signs, to grow as more are found:
+ *
+ *   US  the Bundle claims the US Patient Summary profile (Bundle-us-pcs), or a US Core
+ *       extension is used anywhere in the document
+ *   AU  the Bundle claims the AU Patient Summary profile (au-ps-bundle)
+ *
+ * The result is { jurisdiction, reasons: [{ jurisdiction, text }] }: jurisdiction is the
+ * nation's ISO 3166 two-letter code, or null when it is unknown - nothing points to a nation,
+ * or the signs point to more than one (then the reasons say which).
+ *
+ * @module ips/nationality
+ */
+
+const US_CORE_EXTENSIONS = 'http://hl7.org/fhir/us/core/StructureDefinition/';
+// how many extension urls a reason names
+const MAX_NAMED = 3;
+
+/** The profiles a resource claims (meta.profile), without their versions. */
+function profilesOf(resource) {
+  const p = resource?.meta?.profile;
+  return Array.isArray(p) ? p.filter(x => typeof x === 'string').map(x => x.split('|')[0]) : [];
+}
+
+/** Every extension url in the document, at any depth, each once. */
+function extensionUrls(node, found = new Set()) {
+  if (Array.isArray(node)) {
+    for (const n of node) {
+      extensionUrls(n, found);
+    }
+  } else if (node && typeof node === 'object') {
+    for (const [k, v] of Object.entries(node)) {
+      if ((k === 'extension' || k === 'modifierExtension') && Array.isArray(v)) {
+        for (const e of v) {
+          if (e && typeof e.url === 'string') {
+            found.add(e.url);
+          }
+        }
+      }
+      extensionUrls(v, found);
+    }
+  }
+  return found;
+}
+
+/** A Bundle profile that says which nation a document is from. */
+function profileRule(jurisdiction, url, name) {
+  return (bundle) => (profilesOf(bundle).includes(url) ? `the Bundle claims the ${name} profile (${url})` : null);
+}
+
+const RULES = [
+  { jurisdiction: 'US', test: profileRule('US', 'http://hl7.org/fhir/us/pcs/StructureDefinition/Bundle-us-pcs', 'US Patient Summary') },
+  {
+    jurisdiction: 'US',
+    test: (bundle, urls) => {
+      const core = [...urls].filter(u => u.startsWith(US_CORE_EXTENSIONS)).sort();
+      if (core.length === 0) {
+        return null;
+      }
+      const named = core.slice(0, MAX_NAMED).map(u => u.substring(US_CORE_EXTENSIONS.length)).join(', ');
+      return `US Core extension${core.length === 1 ? ' is' : 's are'} used (${named}${core.length > MAX_NAMED ? ` and ${core.length - MAX_NAMED} more` : ''})`;
+    }
+  },
+  { jurisdiction: 'AU', test: profileRule('AU', 'http://hl7.org.au/fhir/ps/StructureDefinition/au-ps-bundle', 'AU Patient Summary') }
+];
+
+/**
+ * Which nation a document is from.
+ * @param {Object} bundle
+ * @returns {{jurisdiction: string|null, reasons: Array<{jurisdiction: string, text: string}>}}
+ */
+function determineNationality(bundle) {
+  const urls = extensionUrls(bundle);
+  const reasons = [];
+  for (const rule of RULES) {
+    const text = rule.test(bundle, urls);
+    if (text) {
+      reasons.push({ jurisdiction: rule.jurisdiction, text });
+    }
+  }
+  const nations = [...new Set(reasons.map(r => r.jurisdiction))];
+  return { jurisdiction: nations.length === 1 ? nations[0] : null, reasons };
+}
+
+/** What the result says, in a sentence. */
+function nationalityText(result) {
+  if (!result) {
+    return null;
+  }
+  const reasons = Array.isArray(result.reasons) ? result.reasons : [];
+  if (result.jurisdiction) {
+    return `From ${result.jurisdiction}: ${reasons.map(r => r.text).join('; ')}`;
+  }
+  if (reasons.length > 0) {
+    const nations = [...new Set(reasons.map(r => r.jurisdiction))];
+    return `Nationality unknown: the document has signs of more than one nation (${nations.map(n => `${n}: ${reasons.filter(r => r.jurisdiction === n).map(r => r.text).join('; ')}`).join(' - ')})`;
+  }
+  return 'Nationality unknown: nothing in the document says which nation it is from (only US and Australian documents can be recognised so far)';
+}
+
+const nationalityStep = {
+  name: 'nationality',
+  async run(row, project, module) {
+    const started = Date.now();
+    const result = determineNationality(row.bundle);
+    module.store.saveResult(row.id, 'nationality', { ms: Date.now() - started, ...result });
+    module.store.setNationality(row.id, result.jurisdiction);
+    return `nationality: ${result.jurisdiction || 'unknown'}`;
+  }
+};
+
+module.exports = { determineNationality, nationalityText, nationalityStep, RULES };

package/ips/pipeline.js

@@ -9,14 +9,16 @@
  * One process works through the queue (ips.js: processQueue), and runs these steps over
  * each document, in this order:
  *
- *   1. translate     translate CodeableConcepts that fail the terminology check to codes that pass it
- *   2. narrative     generate the narrative with the IPS presenter (presenter.js), into the analysed copy
- *   3. validation    validate the (translated) document with the FHIR validator (fhir-validator-wrapper)
- *   4. national      validate it against each national profile (the national IGs' profiles on Bundle)
- *   5. terminology   check each CodeableConcept against the value sets for international exchange
- *   6. piqi          measure the quality of the document with PIQI                        (not yet)
- *   7. profiles      check the document against each clinical profile (profiles.js)
- *   8. ai            assess the document for consistency and its terminology with an AI service (ai-client.js)
+ *   0. nationality   which nation the document is from, as far as it says (nationality.js)
+ *   1. analysis      look at each resource and section for what a reader should know (analysis.js)
+ *   2. translate     translate CodeableConcepts that fail the terminology check to codes that pass it
+ *   3. narrative     generate the narrative with the IPS presenter (presenter.js), into the analysed copy
+ *   4. validation    validate the (translated) document with the FHIR validator (fhir-validator-wrapper)
+ *   5. national      validate it against each national profile (the national IGs' profiles on Bundle)
+ *   6. terminology   check each CodeableConcept against the value sets for international exchange
+ *   7. piqi          measure the quality of the document with PIQI                        (not yet)
+ *   8. profiles      check the document against each clinical profile (profiles.js)
+ *   9. ai            assess the document for consistency and its terminology with an AI service (ai-client.js)
  *
  * Each step is { name, run(row, project, module) -> result }. A step keeps what it finds in
  * one of two places: as a result stored against the document (store.saveResult - the
@@ -35,6 +37,8 @@ const { Presenter } = require('./presenter');
 const ai = require('./ai-client');
 const { evaluateAsync } = require('./fhirpath-ips');
 const { checkNarrative } = require('../library/narrative-check');
+const { analysisStep } = require('./analysis');
+const { nationalityStep } = require('./nationality');
 
 const IPS_BUNDLE_PROFILE = 'http://hl7.org/fhir/uv/ips/StructureDefinition/Bundle-uv-ips';
 const VALIDATE_TIMEOUT_MS = 120000;
@@ -100,14 +104,13 @@ const validation = {
     }
     const cfg = module.config.validator || {};
     const profiles = Array.isArray(cfg.profiles) ? cfg.profiles : [IPS_BUNDLE_PROFILE];
-    // the validator's own IPS checks (code systems and value sets the IPS expects), unless
-    // the configuration turns them off
-    const checkIpsCodes = cfg.checkIpsCodes !== false;
+    // no checkIpsCodes: validator 7.0.4 dropped its IPS code checks, and refuses the parameter
+    // ("Unable to process param checkIpsCodes"), failing every validation
     const started = Date.now();
     // fhir-validator-wrapper 1.5.0 or later: earlier versions sent the profiles in a form the
     // validator service refuses
     // the analysed copy: the translations are in it, and the validator should see them
-    const outcome = await v.validate(JSON.stringify(row.analysed || row.bundle), { profiles, checkIpsCodes, timeout: VALIDATE_TIMEOUT_MS });
+    const outcome = await v.validate(JSON.stringify(row.analysed || row.bundle), { profiles, timeout: VALIDATE_TIMEOUT_MS });
     if (!outcome || outcome.resourceType !== 'OperationOutcome') {
       throw new Error('The validator did not return an OperationOutcome');
     }
@@ -148,8 +151,6 @@ const national = {
     if (!v.isRunning()) {
       throw new Error('The validator is not running');
     }
-    const cfg = module.config.validator || {};
-    const checkIpsCodes = cfg.checkIpsCodes !== false;
     const doc = JSON.stringify(row.analysed || row.bundle);
     const profiles = [];
     for (const np of list) {
@@ -157,7 +158,7 @@ const national = {
       const t0 = Date.now();
       try {
         await module.loadNationalPackage(np.packageId, np.version);
-        const outcome = await v.validate(doc, { profiles: [np.url], checkIpsCodes, timeout: VALIDATE_TIMEOUT_MS });
+        const outcome = await v.validate(doc, { profiles: [np.url], timeout: VALIDATE_TIMEOUT_MS });
         if (!outcome || outcome.resourceType !== 'OperationOutcome') {
           throw new Error('The validator did not return an OperationOutcome');
         }
@@ -546,6 +547,56 @@ function translationOf(coding) {
   };
 }
 
+const SNOMED_CT = 'http://snomed.info/sct';
+
+/**
+ * The SNOMED CT edition a document's codes are taken to be from when they don't say: the
+ * edition of a national profile for the nation the document is from (the nationality step).
+ * Only the translate step uses it - the terminology check takes the codes as they are, so a
+ * code that is fine as it is passes whatever its edition, and one whose edition says otherwise
+ * doesn't.
+ * @returns {{edition: string, packageId: string, version: string, jurisdiction: string}|null}
+ */
+function defaultSnomedEdition(module, row) {
+  const jurisdiction = module.store.readResult(row.id, 'nationality')?.result?.jurisdiction;
+  if (!jurisdiction) {
+    return null;
+  }
+  const np = module.store.nationalProfiles().find(p => p.jurisdiction === jurisdiction && p.snomedEdition);
+  return np ? { edition: np.snomedEdition, packageId: np.packageId, version: np.version, jurisdiction } : null;
+}
+
+/** A concept with its SNOMED CT codings that have no version given the edition (a copy; the concept is unchanged). */
+function withSnomedEdition(concept, edition) {
+  if (!edition || !Array.isArray(concept.coding)) {
+    return concept;
+  }
+  return { ...concept, coding: concept.coding.map(c => (c && c.system === SNOMED_CT && !c.version ? { ...c, version: `${SNOMED_CT}/${edition}` } : c)) };
+}
+
+/** The SNOMED CT edition a version names (its module id, without the release date), or the version itself. */
+function editionOf(system, version) {
+  if (system === SNOMED_CT && typeof version === 'string') {
+    const m = version.match(/^http:\/\/snomed\.info\/x?sct\/(\d+)(?:\/version\/\d+)?$/);
+    if (m) {
+      return m[1];
+    }
+  }
+  return version;
+}
+
+/**
+ * Whether a concept already has a coding: the same system and code, and - when both say - the
+ * same version. A version that differs makes it a different coding: the same SNOMED CT code in
+ * the International Edition is what a translation from a national edition is for, even though
+ * the code is the same (SNOMED CT versions are compared by edition, not release). A coding with
+ * no version already stands for the code, whatever the translation's version.
+ */
+function hasCoding(codings, coding) {
+  return codings.some(x => x && x.system === coding.system && x.code === coding.code &&
+    (!x.version || !coding.version || editionOf(x.system, x.version) === editionOf(coding.system, coding.version)));
+}
+
 /** A CodeableConcept as the server should see it: without our extensions. */
 function withoutOurExtensions(concept) {
   const c = structuredClone(concept);
@@ -586,6 +637,8 @@ const translate = {
     const budget = { left: MAX_CHECKS_PER_DOCUMENT };
     const cache = module.txCache || (module.txCache = new Map());
     const started = Date.now();
+    // SNOMED CT codes with no version are taken to be from the edition of the document's nation
+    const defaultEdition = defaultSnomedEdition(module, row);
     // what happened to each concept, for the translation view
     const entries = [];
     // the same resource in two sections, and the same concept in two places: once
@@ -619,11 +672,11 @@ const translate = {
         } else if (budget.left <= 0) {
           translation = { matches: [], failed: true, check, message: `not translated - the document has more codes than are checked (${MAX_CHECKS_PER_DOCUMENT})` };
         } else {
-          const cacheKey = `translate|${key}`;
+          const cacheKey = `translate|${defaultEdition ? defaultEdition.edition : ''}|${key}`;
           translation = cache.get(cacheKey);
           if (!translation) {
             budget.left--;
-            translation = await translateConcept(module.tx, valueSets, withoutOurExtensions(c.concept), target);
+            translation = await translateConcept(module.tx, valueSets, withSnomedEdition(withoutOurExtensions(c.concept), defaultEdition?.edition), target);
             if (!translation.failed) {
               if (cache.size >= MAX_CACHED_ANSWERS) {
                 cache.delete(cache.keys().next().value);
@@ -653,7 +706,7 @@ const translate = {
       }
       let added = 0;
       for (const m of translation.matches) {
-        if (codings.some(x => x && x.system === m.coding.system && x.code === m.coding.code)) {
+        if (hasCoding(codings, m.coding)) {
           entry.added.push({ ...m, present: true });
           continue; // already there
         }
@@ -678,7 +731,7 @@ const translate = {
         entry.message = translation.matches.length > 0 ? 'The translation gave only codings the concept already has' : (translation.message || 'The terminology server has no translation');
       }
     }
-    module.store.saveResult(row.id, 'translate', { ms: Date.now() - started, server: module.tx.url, counts, entries });
+    module.store.saveResult(row.id, 'translate', { ms: Date.now() - started, server: module.tx.url, counts, entries, ...(defaultEdition ? { defaultEdition } : {}) });
     return `translate: ${counts.translated} of ${counts.tried} concepts translated (${counts.codings} codings added)` +
       (counts.failed ? `, ${counts.failed} not translated (see the log)` : '');
   }
@@ -1064,10 +1117,10 @@ const aiStep = {
 };
 
 /** The steps, in order. Only the ones that exist yet. */
-const STEPS = [translate, narrative, validation, national, terminology, profilesStep, aiStep];
+const STEPS = [nationalityStep, analysisStep, translate, narrative, validation, national, terminology, profilesStep, aiStep];
 
 module.exports = {
-  STEPS, translate, narrative, validation, national, terminology, profiles: profilesStep, ai: aiStep, checkConstraint, valueSetsIn, lookupDisplay, checkConcept, documentForAi, assessmentOf, aiSystemPrompt, AI_SYSTEM_PROMPT, checkOf, addCheck, stripChecks, translateConcept, translationOf,
+  STEPS, analysis: analysisStep, translate, narrative, validation, national, terminology, profiles: profilesStep, ai: aiStep, checkConstraint, valueSetsIn, lookupDisplay, checkConcept, documentForAi, assessmentOf, aiSystemPrompt, AI_SYSTEM_PROMPT, checkOf, addCheck, stripChecks, translateConcept, translationOf, defaultSnomedEdition, withSnomedEdition, hasCoding,
   validateCodeInValueSet, validateCodeInSystem, issueCounts, issueSummary,
   IPS_BUNDLE_PROFILE, CHECK_EXTENSION, TRANSLATION_EXTENSION, MAX_CHECKS_PER_DOCUMENT, MAX_CACHED_ANSWERS
 };

package/ips/presenter.js

@@ -969,6 +969,6 @@ const GENERIC = {
 };
 
 module.exports = {
-  Presenter, COLUMNS, GENERIC, describeResource, NONE,
+  Presenter, COLUMNS, GENERIC, describeResource, codeText, NONE,
   dateText, periodText, quantityText, rangeText, humanNameText, addressText, identifierText, contactPointText, annotationText
 };