fhirsmith 0.18.1 → 1.0.0

package/ips/ips.js

@@ -43,6 +43,7 @@ const express = require('express');
 const path = require('path');
 const fs = require('fs');
 const crypto = require('crypto');
+const scripts = require('./scripts');
 const rateLimit = require('express-rate-limit');
 const escape = require('escape-html');
 const session = require('express-session');
@@ -60,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');
@@ -79,7 +83,35 @@ const TX_STARTUP_GRACE_MS = 5 * 60 * 1000;
 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 RESERVED = new Set(['login', 'logout', 'admin', 'metadata', 'openapi', 'static', 'assets', 'lookup']);
+const { jurisdiction: jurisdictionOf } = require('./jurisdictions');
+const { SNOMED_LINKABLE_EDITIONS } = require('../tx/sct/editions');
+const RESERVED = new Set(['login', 'logout', 'admin', 'metadata', 'openapi', 'static', 'assets', 'lookup', 'national-profiles']);
+
+/**
+ * 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), 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, 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)';
+  }
+  if (packageId.length > 128 || !/^[a-z0-9][a-z0-9_-]*(\.[a-z0-9][a-z0-9_-]*)+$/.test(packageId)) {
+    return 'The package id must be a FHIR package id: lower case letters, digits, - and _, in two or more parts separated by dots (e.g. hl7.fhir.au.ips)';
+  }
+  if (!/^[0-9A-Za-z][0-9A-Za-z.+-]{0,63}$/.test(version)) {
+    return 'The version must be a package version (e.g. 1.0.0, or 1.1.0-ballot)';
+  }
+  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;
+}
 
 /**
  * What's wrong with a submitted document, if anything.
@@ -165,25 +197,6 @@ function preferValue(req, name) {
   return null;
 }
 
-// the browser scripts: the module's own files, read once and served from memory (so no
-// request reaches the file system), with an ETag so a browser can keep its copy
-const SCRIPTS = new Map();
-function script(name) {
-  if (!SCRIPTS.has(name)) {
-    const body = fs.readFileSync(path.join(__dirname, name), 'utf8');
-    SCRIPTS.set(name, { body, etag: `"${crypto.createHash('sha256').update(body).digest('base64url').substring(0, 27)}"` });
-  }
-  const s = SCRIPTS.get(name);
-  return (req, res) => {
-    res.setHeader('Cache-Control', 'public, max-age=3600');
-    res.setHeader('ETag', s.etag);
-    if (req.get('If-None-Match') === s.etag) {
-      return res.status(304).end();
-    }
-    res.type('application/javascript').send(s.body);
-  };
-}
-
 function wantsHtml(req) {
   const f = req.query._format;
   if (typeof f === 'string' && f !== '') {
@@ -308,6 +321,7 @@ class IpsModule {
     this.setupSession();
     this.setupRootRoutes();
     this.setupProfileRoutes();
+    this.setupNationalProfileRoutes();
     this.setupProjectRoutes();
     this.setupValidator();
     this.setupValueSets();
@@ -451,7 +465,7 @@ class IpsModule {
       next();
     };
 
-    r.get('/profile-editor.js', script('profile-editor.js'));
+    r.get('/profile-editor.js', scripts.handler('profile-editor.js'));
     r.get('/lookup', this.session, adminJson, ...this.lookups, h('lookup', (req, res) => this.systemLookup(req, res)));
     r.get('/lookup-vs', this.session, adminJson, ...this.lookups, h('lookup', (req, res) => this.valueSetLookup(req, res)));
     r.get('/StructureDefinition', ...this.web, h('profiles', (req, res) => this.profileList(req, res)));
@@ -460,12 +474,37 @@ class IpsModule {
     r.get('/StructureDefinition/:id', profile, ...this.web, h('profile', (req, res) => this.profileRead(req, res)));
     r.get('/StructureDefinition/:id/edit', profile, this.session, this.csrf, admin, h('profile', (req, res) => this.profileEditor(req, res, req.profile)));
     r.post('/StructureDefinition/:id', profile, this.sameOrigin, this.session, json, this.csrf, adminJson, h('profile', (req, res) => this.profileSave(req, res, req.profile)));
+    // one constraint at a time, from the profile's page: add, edit (keeping its key), delete
+    r.post('/StructureDefinition/:id/constraint', profile, this.sameOrigin, this.session, json, this.csrf, adminJson, h('profile', (req, res) => this.constraintSave(req, res, null)));
+    r.post('/StructureDefinition/:id/constraint/:key', profile, this.sameOrigin, this.session, json, this.csrf, adminJson, h('profile', (req, res) => this.constraintSave(req, res, req.params.key)));
+    r.post('/StructureDefinition/:id/constraint/:key/delete', profile, this.sameOrigin, this.session, this.form, this.csrf, admin, h('profile', (req, res) => this.constraintDelete(req, res)));
     r.post('/StructureDefinition/:id/delete', profile, this.sameOrigin, this.session, this.form, this.csrf, admin, h('profile', (req, res) => {
       this.store.deleteProfile(req.profileId);
       res.redirect(req.baseUrl + '/StructureDefinition');
     }));
   }
 
+  /**
+   * The national profiles, across all projects: everyone can see them, only the administrator
+   * adds, edits and deletes them. Before the project routes, so /national-profiles isn't taken
+   * for a project code.
+   */
+  setupNationalProfileRoutes() {
+    const r = this.router;
+    const h = (name, fn) => (req, res) => this.handle(req, res, name, () => fn(req, res));
+    const admin = this.adminOnly;
+    r.get('/national-profiles', ...this.web, h('national-profiles', (req, res) => this.sendNationalProfiles(req, res)));
+    r.post('/national-profiles', this.sameOrigin, this.session, this.form, this.csrf, admin, h('national-profiles', (req, res) => this.saveNationalProfile(req, res, null)));
+    r.post('/national-profiles/:id', this.sameOrigin, this.session, this.form, this.csrf, admin, h('national-profiles', (req, res) => this.saveNationalProfile(req, res, req.params.id)));
+    r.post('/national-profiles/:id/delete', this.sameOrigin, this.session, this.form, this.csrf, admin, h('national-profiles', (req, res) => {
+      const np = /^\d{1,15}$/.test(req.params.id) ? this.store.nationalProfile(parseInt(req.params.id, 10)) : null;
+      if (np && this.store.deleteNationalProfile(np.id)) {
+        this.log.info(`IPS module: national profile ${np.packageId}#${np.version} deleted`);
+      }
+      res.redirect(req.baseUrl + '/national-profiles');
+    }));
+  }
+
   setupProjectRoutes() {
     const r = this.router;
     const h = (name, fn) => (req, res) => this.handle(req, res, name, () => fn(req, res));
@@ -509,7 +548,7 @@ class IpsModule {
       next();
     };
 
-    r.get('/editor.js', script('editor.js'));
+    r.get('/editor.js', scripts.handler('editor.js'));
     r.get('/:code', project, ...this.web, h('list', (req, res) => this.htmlList(req, res)));
     r.get('/:code/metadata', project, h('metadata', (req, res) => this.metadata(req, res)));
     // The submission form has no CSRF token and starts no session: submitting is open to
@@ -595,25 +634,39 @@ class IpsModule {
    * wait in the queue.
    */
   setupValidator() {
+    // the national profiles' packages, as they are loaded into the validator: id#version -> Promise
+    this.nationalPackages = new Map();
     const cfg = this.config.validator;
     if (!cfg || cfg.enabled === false) {
       this.log.warn('IPS module: no validator configured (modules.ips.validator) - documents will not be validated');
       return;
     }
     const FhirValidator = require('fhir-validator-wrapper');
-    const jar = folders.filePath('bin', 'validator_cli.jar');
+    // a jar of its own (a validator built locally, say): used as it is, never downloaded or
+    // updated; otherwise the released one in the data folder's bin directory, kept up to date
+    const localJar = typeof cfg.jar === 'string' && cfg.jar.trim() ? (path.isAbsolute(cfg.jar) ? cfg.jar : folders.filePath(cfg.jar)) : null;
+    const jar = localJar || folders.filePath('bin', 'validator_cli.jar');
     this.validator = new FhirValidator(jar, this.log);
     const settings = {
+      autoDownload: !localJar,
+      skipUpdateCheck: !!localJar,
       version: cfg.version || '4.0.1',
       txServer: cfg.txServer || 'http://tx.fhir.org/r4',
       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 on port ${settings.port} (tx ${settings.txServer}; ${settings.igs.join(', ')})`);
+    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;
@@ -622,6 +675,60 @@ 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
+   * document doesn't ask again. The validator's packages (modules.ips.validator.packages) are
+   * loaded when it starts; these are added to them.
+   * @returns {Promise<void>} rejects with the reason the package could not be loaded
+   */
+  loadNationalPackage(packageId, version) {
+    const key = `${packageId}#${version}`;
+    let p = this.nationalPackages.get(key);
+    if (!p) {
+      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);
+    }
+    return p;
+  }
+
   /** Read the value sets the terminology check holds documents to: the module's own, in ips/valuesets/. */
   setupValueSets() {
     try {
@@ -654,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
@@ -829,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.');
     }
@@ -1295,6 +1463,59 @@ class IpsModule {
       render.renderSubmit(req.project, this.ctx(req, res), { needsToken: tokenConfigured(req.project.token), aiEnabled: this.store.projectAi(req.project).enabled === true, ...options }), Date.now(), req);
   }
 
+  // ---- national profiles ----
+
+  /** The national profiles: a page (with the administrator's forms), or JSON. */
+  sendNationalProfiles(req, res, message, status = 200) {
+    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,
+        ...(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: 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');
+    const version = field('version');
+    const url = field('url');
+    // a country code is upper case; a region's is digits
+    const jurisdiction = field('jurisdiction').toUpperCase();
+    // 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);
+    }
+    const existing = this.store.nationalProfileByPackage(packageId, version);
+    if (id === null) {
+      if (existing) {
+        return this.sendNationalProfiles(req, res, `There is already a national profile for ${packageId}#${version}`, 409);
+      }
+      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, snomedEdition)) {
+        return this.sendNationalProfiles(req, res, 'That national profile no longer exists', 404);
+      }
+      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; 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');
+  }
+
   // ---- clinical profiles ----
 
   /** The clinical profiles: a page, or a FHIR searchset of the StructureDefinitions. */
@@ -1321,7 +1542,31 @@ class IpsModule {
       res.type('application/fhir+json');
       return res.send(JSON.stringify(sd));
     }
-    this.sendHtml(res, `Clinical Profile: ${sd.title}`, render.renderProfile(sd, { ...this.ctx(req, res), valueSetTitle: (url) => this.valueSetTitle(url) }), Date.now(), req);
+    const ctx = { ...this.ctx(req, res), valueSetTitle: (url) => this.valueSetTitle(url), profileTitle: (url) => this.profileTitle(url) };
+    // the administrator edits the rows in place, a row at a time
+    const editor = ctx.user?.isAdmin ? {
+      constraints: this.editorConstraints(sd),
+      sections: profiles.IPS_SECTIONS, systems: profiles.SYSTEMS, resourceTypes: profiles.RESOURCE_TYPES, sectionSystem: editorSchema.LOINC, canLookup: !!this.tx
+    } : null;
+    this.sendHtml(res, `Clinical Profile: ${sd.title}`, render.renderProfile(sd, ctx, editor), Date.now(), req);
+  }
+
+  /**
+   * What to call a profile a rule says resources conform to: one of the clinical profiles (by
+   * its title), or one of the national profiles (by its jurisdiction and package), or null.
+   */
+  profileTitle(url) {
+    if (typeof url !== 'string') {
+      return null;
+    }
+    const plain = url.split('|')[0];
+    const m = /\/StructureDefinition\/profile-([a-f0-9]{12})$/.exec(plain);
+    const sd = m ? this.store.profile(m[1]) : null;
+    if (sd && sd.url === plain) {
+      return sd.title;
+    }
+    const np = this.store.nationalProfiles().find(p => p.url === plain);
+    return np ? `${np.jurisdiction ? `${np.jurisdiction} ` : ''}national profile (${np.packageId}#${np.version})` : null;
   }
 
   /** The title of one of this module's own value sets, or null. */
@@ -1331,8 +1576,12 @@ class IpsModule {
   }
 
   /** The editor, for a new profile or an existing one. */
+  editorConstraints(sd) {
+    return profiles.constraintsOf(sd).map(c => ({ ...c, shape: profiles.parseShape(c.expression), rshape: profiles.parseResourceShape(c.expression) }));
+  }
+
   profileEditor(req, res, sd) {
-    const constraints = profiles.constraintsOf(sd).map(c => ({ ...c, shape: profiles.parseShape(c.expression), rshape: profiles.parseResourceShape(c.expression) }));
+    const constraints = this.editorConstraints(sd);
     this.sendHtml(res, sd ? `Edit Clinical Profile: ${sd.title}` : 'New Clinical Profile',
       render.renderProfileEditor(sd, this.ctx(req, res), {
         profile: { id: sd ? sd.id : null, title: sd ? sd.title : '', constraints },
@@ -1369,6 +1618,53 @@ class IpsModule {
     res.status(previous ? 200 : 201).json({ id: sd.id, url: `${req.baseUrl}/StructureDefinition/${sd.id}` });
   }
 
+  /**
+   * Add a constraint to a profile ({human, expression}), or replace one (by its key, which it
+   * keeps). 201/200 with {key}, 404 when there is no constraint with that key, 422 with {problems}.
+   */
+  constraintSave(req, res, key) {
+    const previous = req.profile;
+    const body = req.body && typeof req.body === 'object' && !Array.isArray(req.body) ? req.body : {};
+    const row = { key, human: body.human, expression: body.expression };
+    const constraints = profiles.constraintsOf(previous);
+    const at = key === null ? constraints.length : constraints.findIndex(c => c.key === key);
+    if (at < 0) {
+      return res.status(404).json({ problems: [`The profile has no constraint '${key}'`] });
+    }
+    // the row by itself first, so what is wrong is said of it, not of a number in the list
+    const alone = profiles.checkInput({ title: previous.title, constraints: [{ human: row.human, expression: row.expression }] }, null);
+    if (alone.problems.length) {
+      return res.status(422).json({ problems: alone.problems.map(p => p.replace(/^Constraint 1/, 'The rule')) });
+    }
+    constraints.splice(at, key === null ? 0 : 1, row);
+    const checked = profiles.checkInput({ title: previous.title, constraints }, previous);
+    if (checked.problems.length) {
+      return res.status(422).json({ problems: checked.problems });
+    }
+    this.saveConstraints(previous, checked.constraints);
+    this.log.info(`IPS module: clinical profile ${previous.id}: constraint ${checked.constraints[at].key} ${key === null ? 'added' : 'saved'}`);
+    res.status(key === null ? 201 : 200).json({ key: checked.constraints[at].key });
+  }
+
+  /** Delete one of a profile's constraints, back to the profile's page. */
+  constraintDelete(req, res) {
+    const previous = req.profile;
+    const constraints = profiles.constraintsOf(previous);
+    const at = constraints.findIndex(c => c.key === req.params.key);
+    if (at < 0) {
+      return htmlServer.sendErrorResponse(res, TEMPLATE, new Error(`The profile has no constraint '${req.params.key}'`), 404);
+    }
+    constraints.splice(at, 1);
+    this.saveConstraints(previous, constraints);
+    this.log.info(`IPS module: clinical profile ${previous.id}: constraint ${req.params.key} deleted`);
+    res.redirect(`${req.baseUrl}/StructureDefinition/${previous.id}`);
+  }
+
+  saveConstraints(previous, constraints) {
+    const id = previous.id.substring('profile-'.length);
+    this.store.saveProfile(id, profiles.build({ id, url: previous.url, title: previous.title, constraints }));
+  }
+
   // ---- the editor ----
 
   sendCompose(req, res) {
@@ -1588,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);
@@ -1597,7 +1893,9 @@ class IpsModule {
         ...this.ctx(req, res),
         steps: this.steps.map(st => st.name),
         level: typeof req.query.level === 'string' ? req.query.level : undefined,
-        problemsOnly: req.query.problems === '1'
+        np: typeof req.query.np === 'string' ? req.query.np : undefined,
+        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/jurisdictions.js

@@ -0,0 +1,65 @@
+//
+// Copyright 2026, Health Intersections Pty Ltd (http://www.healthintersections.com.au)
+//
+// Licensed under BSD-3: https://opensource.org/license/bsd-3-clause
+//
+
+/**
+ * Jurisdictions, as http://hl7.org/fhir/ValueSet/jurisdiction has them: a country, by its
+ * ISO 3166-1 two-letter code (urn:iso:std:iso:3166), or a region, by its UN M49 three-digit
+ * code (http://unstats.un.org/unsd/methods/m49/m49.htm). The codes and names are the ones
+ * the terminology module's providers hold (tx/cs/cs-country.js, tx/cs/cs-areacode.js).
+ *
+ * @module ips/jurisdictions
+ */
+
+const { CountryCodeFactoryProvider } = require('../tx/cs/cs-country');
+const { AreaCodeFactoryProvider } = require('../tx/cs/cs-areacode');
+
+const ISO_3166 = 'urn:iso:std:iso:3166';
+const M49 = 'http://unstats.un.org/unsd/methods/m49/m49.htm';
+// in the country list, but not countries
+const UNKNOWN = new Set(['XX', 'ZZ']);
+
+let tables = null;
+
+/**
+ * The providers' code lists, read once. Only their data is wanted, not code system
+ * providers, so their load() runs on an object with no i18n (it only fills codes/codeMap).
+ */
+function load() {
+  if (!tables) {
+    const countries = Object.create(CountryCodeFactoryProvider.prototype);
+    const areas = Object.create(AreaCodeFactoryProvider.prototype);
+    // load() is async in form, but does its work synchronously
+    countries.load();
+    areas.load();
+    tables = { countries: countries.codeMap, areas: areas.codeMap };
+  }
+  return tables;
+}
+
+/**
+ * A jurisdiction by its code: two upper case letters (a country), or three digits (a
+ * region - an M49 region, not a country's numeric code).
+ * @param {string} code
+ * @returns {{system: string, code: string, display: string}|null} null if it is neither
+ */
+function jurisdiction(code) {
+  if (typeof code !== 'string') {
+    return null;
+  }
+  const t = load();
+  if (/^[A-Z]{2}$/.test(code)) {
+    const c = t.countries.get(code);
+    // not the user-assigned codes (XK, QM-QZ...), nor the 'unknown' ones (XX, ZZ): they aren't countries ISO 3166 names
+    return c && !c.userDefined && !UNKNOWN.has(code) ? { system: ISO_3166, code, display: c.display } : null;
+  }
+  if (/^\d{3}$/.test(code)) {
+    const a = t.areas.get(code);
+    return a && a.class_ === 'region' ? { system: M49, code, display: a.display } : null;
+  }
+  return null;
+}
+
+module.exports = { jurisdiction, ISO_3166, M49 };